SAM Kinds

The kinds of Smarter Application Manifest (SAM).

SAMKinds is the single definition of which kinds exist. The Smarter platform, its Python SDK and every other enumeration of kinds, such as SmarterJournalThings, take their kinds from it.

class smarter_types.kinds.SAMKinds(*values)[source]

Bases: SmarterEnumAbstract

Every Smarter Application Manifest (SAM) kind, as it appears in a manifest’s kind.

Each value is the name of a kind of resource that a manifest declares, and that the platform validates, applies and routes to the kind’s broker. The members’ names are the kinds’ names in upper snake case, except that a static plugin’s kind is Plugin, and an api key’s is SmarterAuthToken.

from smarter_types import SAMKinds

SAMKinds.LLM_CLIENT.value  # "LLMClient"
SAMKinds("Secret") is SAMKinds.SECRET  # True
SAMKinds.str_to_kind("sqlplugin")  # "SqlPlugin"

A new kind is added here first, with a deliberate place in apply_order(), and the tests fail until it has one.

STATIC_PLUGIN = 'Plugin'

A static plugin: a tool whose results are fixed in its manifest.

API_PLUGIN = 'ApiPlugin'

A plugin that calls a web api through an ApiConnection.

SKILL_PLUGIN = 'SkillPlugin'

A plugin that gives the LLM a skill: instructions and files that it loads when it needs them.

SQL_PLUGIN = 'SqlPlugin'

A plugin that queries a database through a SqlConnection.

WEBSEARCH_PLUGIN = 'WebsearchPlugin'

A plugin that searches the web.

Experimental.

IMAGE_SEARCH_PLUGIN = 'ImageSearchPlugin'

A plugin that searches for images.

Experimental.

API_CONNECTION = 'ApiConnection'

The url and credentials of a web api, which ApiPlugins call.

SQL_CONNECTION = 'SqlConnection'

The address and credentials of a database, which SqlPlugins query.

ACCOUNT = 'Account'

An account: the owner of every other resource.

AUTH_TOKEN = 'SmarterAuthToken'

A Smarter api key.

BUDGET = 'Budget'

Spending limits, enforced on the resources that it lists.

USER = 'User'

A user, a member of an account.

SECRET = 'Secret'

An encrypted value, such as a password or an api key, that other resources name.

GUARDRAIL = 'Guardrail'

Rules that an LLMClient’s prompts and responses are checked against.

PROMPT = 'Prompt'

A chat session with an LLMClient.

LLM_CLIENT = 'LLMClient'

An LLM application: its provider, model, system prompt, tools and guardrails.

CUSTOM_DOMAIN = 'CustomDomain'

A domain that serves LLMClients.

LLM_HOST = 'LLMHost'

A self-hosted model.

LLM_HOST_COMPUTE = 'LLMHostCompute'

A kind of node, and its node group, that LLMHosts run on.

MCP_CLIENT = 'MCPClient'

A connection to an MCP server, whose tools LLMClients may call.

ORCHESTRATOR = 'Orchestrator'

A workflow of LLMClients.

PROVIDER = 'Provider'

An LLM provider, and the Secret that holds its api key.

PROXY = 'Proxy'

A proxy to an LLM provider’s own api.

VECTORSEARCH = 'Vectorsearch'

A search of a Vectorstore.

VECTORSTORE = 'Vectorstore'

A vector database, and the provider of its embeddings.

classmethod str_to_kind(kind_str: str | bytes) → str | None[source]

Return the kind that a string names, in any case.

SAMKinds.str_to_kind("sqlplugin")  # "SqlPlugin"
Parameters:

kind_str (str | bytes) – The kind’s name, in any case.

Returns:

The kind’s value, or None if kind_str is not a string.

Return type:

str | None

Raises:

SmarterTypesValueError – If the string is not a kind.

classmethod plural(kind: str | SAMKinds) → str[source]

Return the plural of a kind, pluralizing only its final CamelCase word.

SAMKinds.plural(SAMKinds.API_CONNECTION)  # "ApiConnections"
SAMKinds.plural("vectorsearch")  # "Vectorsearches"
Parameters:

kind (str | SAMKinds) – The kind, as a member or its value, in any case.

Returns:

The plural.

Return type:

str

Raises:

SmarterTypesValueError – If it is not a kind.

classmethod all_plugins() → list[SAMKinds][source]

Return the kinds of plugin.

Returns:

The members.

Return type:

list[SAMKinds]

classmethod all_connections() → list[SAMKinds][source]

Return the kinds of connection.

Returns:

The members.

Return type:

list[SAMKinds]

classmethod apply_order() → tuple[str, ...][source]

Return the order in which to apply manifests: each kind after the kinds that its manifests may name.

SAM resources refer to one another by name. A SqlPlugin’s spec.connection is the name of a SqlConnection, and a SqlConnection’s password is the name of a Secret. A broker resolves each name when it applies the manifest, so the resource that is named must already exist. A set of manifests, e.g. a project such as Stackademy, can only be applied in an order where every resource comes after the resources that it names. This is that order, for every kind. It is part of the definition of SAM: a new kind needs a deliberate place in it, and the tests fail until it has one.

The order, kind by kind, and why:

  1. Account. Every other resource belongs to an account, so the account comes first. It names nothing.

  2. User. A user is a member of an account, and owns the resources that it applies.

  3. SmarterAuthToken. An api key’s spec.username names its User. It comes before the LLMClients, whose spec.apiKey may name one.

  4. Secret. A Secret holds a password or an api key, and names nothing, but nearly everything after it may name a Secret: Providers, Proxies, LLMHosts, Connections, MCPClients, Vectorsearches and the search plugins. So it comes before all of them.

  5. Provider. An LLM provider names the Secret that holds its api key. LLMClients, Guardrails, Proxies and Vectorstores name a Provider, so it comes before them.

  6. Proxy. spec.provider names a Provider, and spec.apiKey a Secret.

  7. LLMHostCompute. A kind of node, and its node group. It names nothing, but an LLMHost’s spec.compute names one.

  8. LLMHost. A self-hosted model. spec.compute names an LLMHostCompute, and its tokenSecret and apiKeySecret name Secrets.

  9. SqlConnection. password and proxyPassword name Secrets. SqlPlugins name it.

  10. ApiConnection. apiKey and proxyPassword name Secrets. ApiPlugins name it.

  11. Guardrail. spec.config.provider names the Provider that its semantic, moderation and llm_judge strategies call. LLMClients name it in spec.guardrails.

  12. Vectorstore. spec.provider names the Provider of its embeddings, and its database may name a Secret.

  13. Vectorsearch. vectorstore_name names a Vectorstore, so it comes after them, and auth_secret_name names a Secret.

  14. MCPClient. credentials names a Secret. LLMClients name it in spec.mcpClients.

  15. The plugins: Plugin, SqlPlugin, ApiPlugin, SkillPlugin, WebsearchPlugin and ImageSearchPlugin. A SqlPlugin’s spec.connection names a SqlConnection, an ApiPlugin’s an ApiConnection, and a WebsearchPlugin’s and an ImageSearchPlugin’s apiKey a Secret. A static Plugin and a SkillPlugin name nothing. All of them come after the Connections and before the LLMClients, whose spec.plugins names them.

  16. CustomDomain. A domain that serves LLMClients. It names nothing, but an LLMClient’s customDomain names its domain, so it comes before them.

  17. LLMClient. It names the most kinds: a Provider, and its Plugins, Guardrails, MCPClients, CustomDomain and SmarterAuthToken. It comes after all of them.

  18. Prompt. A chat session, whose spec.llmclient names the LLMClient that it talks to.

  19. Orchestrator. Each of spec.config.harnesses names an LLMClient, by llmClientName.

  20. Budget. Last, because spec.resources can name nearly any kind of resource: Accounts, Users, Connections, LLMClients, LLMHosts, LLMHostComputes, MCPClients, Orchestrators, Providers, Proxies, Vectorsearches and every kind of plugin. Applied any earlier, a Budget could name a resource that doesn’t exist yet.

Kinds that name nothing in common (e.g. the plugins among themselves) may be applied in any order. apply_rank() gives each kind’s position, and a kind that is not listed, i.e. not a SAM kind, is applied last:

sorted(manifests, key=lambda m: SAMKinds.apply_rank(m["kind"]))
Returns:

The kinds’ values, in the order in which to apply them.

Return type:

tuple[str, …]

classmethod apply_rank(kind: str | SAMKinds) → int[source]

Return the position of a kind in apply_order(), to sort manifests by.

SAMKinds.apply_rank(SAMKinds.SECRET) < SAMKinds.apply_rank("SqlConnection")  # True
SAMKinds.apply_rank("NoSuchKind") == len(SAMKinds.apply_order())  # True: applied last
Parameters:

kind (str | SAMKinds) – The kind, as a member or its value, in any case.

Returns:

The kind’s position, or the length of apply_order() for a kind that isn’t a SAM kind, so that it is applied last.

Return type:

int