load_from_github

Apply every Smarter manifest in a GitHub repository, in the order of their dependencies.

manage.py initialize_platform and manage.py initialize_account load two repositories with this command:

  • smarter-sh/example-manifests, the community-supported collection of example manifests, one folder per kind: the platform’s example Guardrails, MCPClients, LLMHosts, Proxies, Vectorstores, plugins, LLMClients, Budgets and more.

  • smarter-sh/stackademy, the Secrets, Connections, plugins, LLMClients and Budget of a fictional code academy.

A repository may also hold scripts, in its scripts/ folder, which run before or after its manifests are applied: see smarter.apps.account.repository_scripts.

class smarter.apps.account.management.commands.load_from_github.Command(*args, **kwargs)[source]

Bases: SmarterCommand

Django manage.py load_from_github command.

Clones a public GitHub repository and applies each Smarter manifest in it, as a user, through the same brokers as the apply api. The repository’s folders are only for people: the manifests are applied in the order of their kinds’ dependencies, SAMKinds.apply_order(), so that a Connection exists before the plugin that uses it, a plugin before the LLMClient that lists it, and so on. Within a kind, they are applied in the order of their paths.

  • A manifest is a *.yaml, *.yml or *.yaml.tpl file whose apiVersion is a Smarter api version. Other files, and hidden files and folders, e.g. .github/ and .pre-commit-config.yaml, are ignored.

  • A manifest template, *.yaml.tpl, is filled in with this platform’s scheme and domain, e.g. the Stackademy ApiConnection, whose baseUrl is the platform that applies it.

  • An LLMClient that exists keeps its deployed value, and an LLMClient that needs an extension that is not installed is skipped.

  • A Budget whose manifest lists no spec.resources is created detached, once. If it exists, it is left as it is: applying the manifest again would detach it from the resources that a superuser has since attached it to, and undo their changes.

  • --deploy deploys each LLMClient that is not deployed, and deploys again one whose domain was never verified, or failed to verify.

  • The repository’s top-level scripts/ folder holds no manifests. --run_scripts runs the scripts that its scripts/scripts.yaml lists: the pre ones before any manifest is applied, and the post ones after every manifest is applied and the LLMClients deployed. Only manage.py initialize_platform passes it. See smarter.apps.account.repository_scripts.

  • --include_kind applies only the manifests of the kinds that it names, e.g. the plugins and LLMClients of which each account gets its own copy. --exclude_kind skips the manifests of a kind, e.g. a Budget, which only a superuser may apply, and which applies to the platform rather than to one account.

  • --skip_missing_references skips, with a warning, a manifest that names a resource that this platform doesn’t have, e.g. an MCPClient whose credentials Secret no operator has created: the broker raises SAMBrokerErrorNotFound. It is applied by a later load, once the resource exists. manage.py initialize_platform and manage.py initialize_account pass it for the example manifests, some of which need a Secret of a third-party service, and not for Stackademy, which brings its own Secrets.

  • One manifest or script that fails doesn’t stop the rest. The command fails at the end, with the list of what failed, and also when the repository holds no manifest at all, or its scripts/scripts.yaml is not valid.

The owner is --username, or the admin of the account --account_number. Applying is idempotent: a resource that exists is updated.

UNVERIFIED_DNS_STATUSES = (LLMClient.DnsVerificationStatusChoices.NOT_VERIFIED, LLMClient.DnsVerificationStatusChoices.FAILED)

The domain statuses of a deployed LLMClient that no deploy task is going to change.

__init__(*args, **kwargs)[source]
add_arguments(parser)[source]

Add the arguments.

apply(filespec, user_profile, manifest=None)[source]

Apply one manifest, and report, rather than raise, a failure.

The manifest is applied in a transaction, so that one that fails leaves nothing behind.

Parameters:

  • filespec (str) – The manifest’s path.

  • user_profile (UserProfile) – The owner of the resource.

  • manifest (str | None) – The manifest to apply instead of the file’s, e.g. a template’s, filled in.

A manifest that names a resource that doesn’t exist is skipped, rather than failed, with --skip_missing_references: its file is added to skipped.

Returns:

The error, or None if the manifest was applied or skipped.

Return type:

str | None

apply_manifests(manifests, user_profile, deploy=False)[source]

Apply the manifests, in order, and deploy the LLMClients if deploy.

Parameters:
Returns:

A description of each manifest that failed to apply or deploy.

Return type:

list[str]

clone_repo(local_path)[source]

Clone the repository’s default branch, without its history.

Parameters:

local_path (str) – The folder to clone into.

Raises:

subprocess.CalledProcessError – If git fails.

Return type:

None

deploy_llmclient(name, user_profile)[source]

Deploy the LLMClient of a user, if it is not deployed.

An LLMClient that is deployed is left as it is, unless its domain was never verified, or failed to verify, e.g. because the DNS service wasn’t ready. It is then deployed again, with deploy_default_api: otherwise nothing ever retries it, and it stays unreachable until someone undeploys and redeploys it by hand.

Parameters:

  • name (str) – The LLMClient’s name.

  • user_profile (UserProfile) – Its owner.

Returns:

False if the LLMClient does not exist, or failed to deploy.

Return type:

bool

find_manifests(local_path)[source]

Return the repository’s manifests, in the order in which to apply them.

Parameters:

local_path (str) – The repository’s clone.

Returns:

The manifests, sorted by SAMKinds.apply_order(), then by path.

Return type:

list[RepositoryManifest]

get_user_profile(account_number, username)[source]

Return the owner of the resources: username, or else the admin of the account account_number.

It is the user profile that manage.py apply_manifest applies the manifests as.

Parameters:

  • account_number (str | None) – The account whose admin owns the resources, if no username.

  • username (str | None) – The user who owns the resources.

Returns:

The owner.

Return type:

UserProfile

Raises:

SmarterValueError – If neither is given, or the account or user does not exist.

handle(*args, **options)[source]

Clone the repository, apply its manifests, and delete the clone.

help = 'Apply every Smarter manifest in a public GitHub repository, in the order of their dependencies, e.g. https://github.com/smarter-sh/example-manifests.'
is_existing_detached_budget(item)[source]

Whether a manifest is of a Budget that exists, and lists no resources.

Such a Budget is left as it is: applying its manifest would detach it from the resources that a superuser has attached it to since it was created.

Parameters:

item (RepositoryManifest) – The manifest.

Returns:

True if it is to be skipped.

Return type:

bool

static keep_deployed(manifest, user_profile)[source]

Return a copy of an LLMClient manifest whose deployed is that of the LLMClient that exists, if any.

A manifest is not deployed, so applying it as it is would undeploy an LLMClient that is deployed, whose undeploy task destroys its A record, only for the next deploy to create it again. Resolvers that query the domain in between cache the NXDOMAIN for minutes.

Parameters:

  • manifest (dict[str, Any]) – The LLMClient manifest.

  • user_profile (UserProfile) – The owner of the LLMClient.

Returns:

The manifest, with spec.config.prompt.deployed set.

Return type:

dict[str, Any]

static missing_extensions(slugs)[source]

Return the slugs, of those that an LLMClient manifest lists, of the extensions that are not installed.

manage.py install_official_extensions installs them, from a registry that may not be reachable.

Parameters:

slugs (list[str]) – The extensions that the manifest lists.

Returns:

Those that are not installed.

Return type:

list[str]

run_scripts(local_path, config, stage, user_profile)[source]

Run the repository’s scripts of one stage, in the order of its scripts/scripts.yaml.

Parameters:

  • local_path (str) – The repository’s clone.

  • config (RepositoryScriptsConfig | None) – The repository’s scripts configuration, or None if it has none.

  • stage (Literal['pre', 'post']) – pre or post.

  • user_profile (UserProfile) – The owner of the resources, whose account and username the scripts receive.

Returns:

A description of each script that failed.

Return type:

list[str]

select_manifests(manifests, included, excluded)[source]

Return the manifests of the kinds to apply, and say which were skipped.

Parameters:
Returns:

The manifests to apply, in the same order.

Return type:

list[RepositoryManifest]

skip_missing_references: bool = False
skipped: set[str]

The manifests, by file, that apply() skipped, because they name a resource that doesn’t exist.

property url: str

The repository’s url.

user_profile: UserProfile | None = None
verbose: bool = False
smarter.apps.account.management.commands.load_from_github.MANIFEST_EXTENSIONS = ('.yaml', '.yml', '.yaml.tpl')

The extensions of the files that may hold a manifest.

Other files, e.g. a README, are ignored.

('.yaml', '.yml', '.yaml.tpl')
class smarter.apps.account.management.commands.load_from_github.RepositoryManifest(path, filespec, kind, name, manifest)[source]

Bases: object

A manifest of the repository: its file, relative to the repository’s root, and its content.

__init__(path, filespec, kind, name, manifest)
filespec: str

The file’s absolute path in the clone.

kind: str

The manifest’s kind, e.g. SqlPlugin.

manifest: dict[str, Any]

The manifest, with a template’s placeholders filled in.

name: str

The manifest’s metadata.name.

path: str

The file, relative to the repository’s root, e.g. plugins/sql/stackademy-sql.yaml.

property rank: int

The position of the manifest’s kind in SAMKinds.apply_order().