Resources

`smarter.resources.base`

The base classes of the SDK’s api resources.

Each resource family (LLMClients, Guardrails, …) is a class whose methods send requests through the client’s SmarterHttpClient. Writes go through the manifest api, exactly as the smarter cli sends them, so that the platform validates them and applies its business rules. The REST endpoints are used to read resources, and for actions that the manifest api has no verb for, such as evaluating a Guardrail or calling an MCP tool.

smarter.resources.base.ManifestInput: A manifest: a Manifest, a typed SAM model, a dict, YAML or JSON text, or the path of a YAML or JSON file.

smarter.resources.base.resource_id(value: 'SmarterIdType') → 'str'

A resource id as a url path segment.

Parameters:: value – The resource’s integer id, or its hashed id.
Returns:: The id, as text.
Raises:: SmarterValueError – If the id is empty, or contains a slash.

class smarter.resources.base.SmarterAPIResource(client: 'Smarter') → 'None'

A group of api operations.

Parameters:: client – The client whose requests the operations send.

class smarter.resources.base.SmarterKindResource

Bases: smarter.resources.base.SmarterAPIResource, typing.Generic

The operations of one resource kind, e.g. Guardrail.

Subclasses set kind, the manifest kind, and path, the REST list endpoint, and model, the model of a resource. They get:

list(), retrieve() and find(), from the REST api, and
apply(), describe(), delete(), example_manifest() and json_schema(), from the manifest api.

list() → 'list[ModelT]'

Every resource of this kind that the api key’s user may read.

Returns:: The resources.

retrieve(id: 'SmarterIdType') → 'ModelT'

One resource, by its id or hashed id.

Parameters:: id – The resource’s integer id, or its hashed id.
Returns:: The resource.
Raises:: NotFoundError – If it does not exist, or the user may not read it.

find(name: 'str') → 'ModelT'

One resource, by its name.

Parameters:: name – The resource’s name.
Returns:: The first resource of that name that the user may read.
Raises:: ResourceNotFoundError – If there is none.

apply(manifest: 'ManifestInput') → 'SmarterJournalMessage'

Create or update a resource of this kind from its manifest.

Parameters:: manifest – The manifest.
Returns:: The platform’s response, whose message says what was applied.
Raises:: SmarterValueError – If the manifest is of another kind.

describe(name: 'str') → 'Manifest'

A resource’s manifest, with its read-only status.

Parameters:: name – The resource’s name.
Returns:: The manifest.

delete(name: 'str') → 'SmarterJournalMessage'

Permanently delete a resource.

Parameters:: name – The resource’s name.
Returns:: The platform’s response.

example_manifest() → 'Manifest'

A valid example manifest of this kind, to start from.

Returns:: The manifest.

json_schema() → 'SmarterJsonObjectType'

The JSON Schema of this kind’s manifest.

Returns:: The schema.

smarter.resources.base.to_manifest(manifest: 'ManifestInput') → 'Manifest'

A manifest from any of the forms that the SDK accepts.

A string that names an existing file is read as a file. Any other string is parsed as YAML.

Parameters:: manifest – The manifest.
Returns:: The parsed manifest.
Raises:: SmarterValueError – If it cannot be parsed.

`smarter.resources.manifests`

The manifest api: the brokered, journaled /api/v1/cli/ endpoints that the smarter cli uses.

Every resource kind is managed through the same verbs: apply, validate, get, describe, delete, deploy, undeploy and logs. The kind’s broker on the platform validates the manifest with its Pydantic models and applies its business rules, so this is the only way that the SDK writes resources.

from smarter import Smarter

client = Smarter()
client.manifests.apply("guardrail.yaml")
manifest = client.manifests.describe("Guardrail", "pii_redactor")
client.manifests.delete("Guardrail", "pii_redactor")

class smarter.resources.manifests.ManifestValidation

Bases: smarter.models.base.SmarterModel

The result of validating a manifest, without applying it.

valid: bool

errors: list

smarter.resources.manifests.kind_segment(kind: 'str') → 'str'

A kind as a url path segment.

Parameters:: kind – The manifest kind, e.g. LLMClient.
Returns:: The kind.
Raises:: SmarterValueError – If it is empty or not a single path segment.

class smarter.resources.manifests.Manifests

Bases: smarter.resources.base.SmarterAPIResource

The manifest api: apply, validate, get, describe, delete, deploy, undeploy and logs, for any kind.

apply(manifest: 'ManifestInput') → 'SmarterJournalMessage'

Create or update a resource from its manifest.

The platform compares the manifest with the resource’s current state and makes the changes that the difference requires.

Parameters:: manifest – The manifest: a Manifest, a dict, YAML text, or the path of a YAML file.
Returns:: The platform’s response, whose message says what was applied.
Raises:: BadRequestError – If the platform rejects the manifest.

validate(manifest: 'ManifestInput') → 'ManifestValidation'

Validate a manifest without applying it.

Parameters:: manifest – The manifest, in any form that apply() accepts.
Returns:: Whether it is valid, and its errors.

get(kind: 'str', name: 'str | None' = None) → 'ManifestList'

The resources of one kind, as a table.

Parameters:

kind – The manifest kind, e.g. LLMClient.
name – Only the resource of this name.

Returns:

The table: .items are its rows, and .names the resources’ names.

describe(kind: 'str', name: 'str') → 'Manifest'

A resource’s manifest, with its read-only status.

Parameters:

kind – The manifest kind.
name – The resource’s name.

Returns:

The manifest, which apply() accepts as is.

Raises:

NotFoundError – If the resource does not exist.

delete(kind: 'str', name: 'str') → 'SmarterJournalMessage'

Permanently delete a resource.

Parameters:

kind – The manifest kind.
name – The resource’s name.

Returns:

The platform’s response.

Raises:

NotFoundError – If the resource does not exist.

deploy(kind: 'str', name: 'str') → 'SmarterJournalMessage'

Deploy a resource, e.g. an LLMClient on its own host name.

This creates real infrastructure on the platform’s cloud, e.g. DNS records, TLS certificates and Kubernetes ingresses, which may be billable.

Parameters:

kind – The manifest kind of a deployable resource. See smarter.Smarter.kinds().
name – The resource’s name.

Returns:

The platform’s response.

undeploy(kind: 'str', name: 'str') → 'SmarterJournalMessage'

Undo a resource’s deployment.

Parameters:

kind – The manifest kind.
name – The resource’s name.

Returns:

The platform’s response.

logs(kind: 'str', name: 'str') → 'SmarterJournaledResponse[SmarterJsonObjectType]'

A resource’s logs.

Parameters:

kind – The manifest kind.
name – The resource’s name.

Returns:

The platform’s response: its message, and its data for the kinds that have logs.

example_manifest(kind: 'str') → 'Manifest'

A valid example manifest of a kind, to start from.

Parameters:: kind – The manifest kind.
Returns:: The manifest.

json_schema(kind: 'str') → 'SmarterJsonObjectType'

The JSON Schema of a kind’s manifest, e.g. to validate manifests locally or to generate a form.

Parameters:: kind – The manifest kind.
Returns:: The schema (draft 2020-12).

`smarter.resources.llmclients`

LLMClients: read them, prompt them, stream a prompt’s progress, and hold a multi-turn chat.

from smarter import Smarter

client = Smarter()
llmclient = client.llm_clients.find("calculator")

# one prompt
response = client.llm_clients.prompt(llmclient.id, "What is 17 times 23?")
print(response.text)

# a conversation, which keeps its session and thread
chat = client.llm_clients.chat(llmclient.id)
print(chat.send("What is 2 to the 10th power?").text)
print(chat.send("And divided by 4?").text)

# the prompt's progress, e.g. its tool calls, while it runs
with client.llm_clients.stream(llmclient.id, "What is sin(pi / 2)?") as stream:
    for event in stream:
        print(event.message)
    print(stream.response.text)

smarter.resources.llmclients.MessageInput: A message: a PromptChatApiMessage, or a dict such as {"role": "user", "content": "Hi"}.

smarter.resources.llmclients.PromptInput: A prompt: the text of one user message, or a list of messages.

class smarter.resources.llmclients.SmarterPromptError(message: 'str', response: 'PromptChatApiPromptResponse | PromptChatApiErrorResponse')

Bases: smarter.core.exceptions.SmarterError

A streamed prompt failed.

Its result event carried an error response.

Parameters:

message – The error’s description.
response – The error response.

smarter.resources.llmclients.to_messages(prompt: 'PromptInput') → 'list[PromptChatApiMessage]'

A prompt as a list of messages.

Parameters:: prompt – A user message’s text, or a list of messages.
Returns:: The messages.

smarter.resources.llmclients.request_messages(messages: 'Sequence[PromptChatApiMessage]') → 'list[SmarterJsonType]'

Messages as the prompt api’s request sends them: only those that the LLM accepts.

Smarter’s own smarter and smarter_error messages are left out, as Smarter Chat leaves them out. Every message keeps its content, even when it is null, e.g. an assistant’s tool calls: the platform requires the key.

Parameters:: messages – A chat thread.
Returns:: The messages, as JSON.

class smarter.resources.llmclients.PromptStream(events: 'AbstractContextManager[Iterator[ServerSentEvent]]') → 'None'

A prompt whose progress is streamed as Server-Sent Events.

Iterate it for the PromptChatApiProgressEvent events, e.g. “Calling tool calculator”. When the iteration ends, response is the prompt’s response, exactly as a non-streaming prompt returns it. Use it as a context manager, so that the connection is closed.

Parameters:: events – The context manager of the stream’s Server-Sent Events.

until_done() → 'PromptChatApiPromptResponse'

Read the stream to its end, discarding the progress events.

Returns:: The prompt’s response.

property result: The final result event, once the stream has been read: the prompt’s status and response.

property response

The prompt’s response, once the stream has been read.

Raises:

SmarterPromptError – If the prompt failed.
SmarterError – If the stream has not been read, or ended without a result.

class smarter.resources.llmclients.ChatSession(llmclients: 'LLMClients', llmclient_id: 'SmarterIdType', config: 'PromptChatApiConfig') → 'None'

A multi-turn conversation with an LLMClient.

It keeps the chat session’s key, so that the platform keeps the session’s history, and the thread, which it sends with each prompt as Smarter Chat does. Create one with LLMClients.chat().

Parameters:

llmclients – The LLMClients resource.
llmclient_id – The LLMClient’s id or hashed id.
config – The chat session’s configuration.

property session_key: The chat session’s key, with which the session can be resumed: see LLMClients.chat().

send(content: 'str | MessageInput') → 'PromptChatApiPromptResponse'

Send a message, and add it and the prompt’s messages to the thread.

Parameters:: content – A user message’s text, or a message.
Returns:: The prompt’s response. .text is the LLM’s reply.

stream(content: 'str | MessageInput') → 'ChatStream'

Send a message, and stream the prompt’s progress.

The thread is updated when the stream has been read to its end.

Parameters:: content – A user message’s text, or a message.
Returns:: The stream. Use it as a context manager.

class smarter.resources.llmclients.ChatStream(events: 'AbstractContextManager[Iterator[ServerSentEvent]]', session: 'ChatSession', thread: 'list[PromptChatApiMessage]') → 'None'

Bases: smarter.resources.llmclients.PromptStream

A PromptStream of a ChatSession, which adds the prompt’s messages to the session’s thread.

class smarter.resources.llmclients.LLMClients

Bases: smarter.resources.base.SmarterKindResource

LLMClients: /api/v1/llm-clients/, and the manifest api’s LLMClient kind.

config(id: 'SmarterIdType', *, session_key: 'str | None' = None) → 'PromptChatApiConfig'

An LLMClient’s chat configuration, and a chat session.

Parameters:

id – The LLMClient’s id or hashed id.
session_key – An existing session’s key, to resume it with its history, or None for a new session.

Returns:

The configuration, whose session_key identifies the session.

prompt(id: 'SmarterIdType', prompt: 'PromptInput', *, session_key: 'str | None' = None, timeout: 'float | None' = None) → 'PromptChatApiPromptResponse'

Prompt an LLMClient.

The platform runs the LLMClient’s whole prompt: it selects plugins, calls the LLM, runs the tools that the LLM calls, and applies the Guardrails. Prompts are billed by the LLM provider.

Parameters:

id – The LLMClient’s id or hashed id.
prompt – The text of one user message, or the chat thread as a list of messages.
session_key – The chat session’s key, from config(), to keep the prompt’s history in that session.
timeout – Seconds, instead of the client’s timeout.

Returns:

The response. .text is the LLM’s final reply, and .data.messages every message that the prompt added, including Smarter’s own.

Raises:

APIStatusError – If the prompt failed, e.g. the LLM provider returned an error. The exception’s body is the error response.

stream(id: 'SmarterIdType', prompt: 'PromptInput', *, session_key: 'str | None' = None, timeout: 'float | None' = None) → 'PromptStream'

Prompt an LLMClient, and stream its progress: the LLM requests, tool calls and plugin calls.

Parameters:

id – The LLMClient’s id or hashed id.
prompt – The text of one user message, or the chat thread as a list of messages.
session_key – The chat session’s key.
timeout – Seconds to wait for each event, instead of the client’s timeout.

Returns:

The stream. Use it as a context manager, and iterate it for the progress events.

chat(id: 'SmarterIdType', *, session_key: 'str | None' = None) → 'ChatSession'

Start or resume a conversation with an LLMClient.

Parameters:

id – The LLMClient’s id or hashed id.
session_key – An existing session’s key, to resume it, or None for a new session.

Returns:

The chat session.

plugins(id: 'SmarterIdType') → 'list[LLMClientPlugin]'

An LLMClient’s plugins.

Parameters:: id – The LLMClient’s integer id.
Returns:: The plugins.

functions(id: 'SmarterIdType') → 'list[LLMClientFunction]'

An LLMClient’s built-in functions, e.g. calculator.

Parameters:: id – The LLMClient’s integer id.
Returns:: The functions.

api_keys(id: 'SmarterIdType') → 'list[LLMClientApiKey]'

The api keys that may call an LLMClient that requires authentication.

Parameters:: id – The LLMClient’s integer id.
Returns:: The api keys.

custom_domains(id: 'SmarterIdType') → 'list[LLMClientCustomDomain]'

The custom domains of an LLMClient.

Parameters:: id – The LLMClient’s integer id.
Returns:: The custom domains.

deploy(name: 'str') → 'SmarterJournalMessage'

Deploy an LLMClient on its own host name.

This creates real, possibly billable infrastructure: DNS records, a TLS certificate and a Kubernetes ingress.

Parameters:: name – The LLMClient’s name.
Returns:: The platform’s response.

undeploy(name: 'str') → 'SmarterJournalMessage'

Undo an LLMClient’s deployment.

Parameters:: name – The LLMClient’s name.
Returns:: The platform’s response.

`smarter.resources.guardrails`

Guardrails: checks that the platform runs on prompts and on the LLM’s replies.

result = client.guardrails.evaluate(17, "My card is 4111 1111 1111 1111")
if result.triggered:
    print(result.disposition, result.text)

class smarter.resources.guardrails.Guardrails

Bases: smarter.resources.base.SmarterKindResource

Guardrails: /api/v1/guardrails/, and the manifest api’s Guardrail kind.

evaluate(id: 'SmarterIdType', text: 'str', *, stage: "Literal['input', 'output']" = 'input') → 'GuardrailEvaluation'

Dry-run a Guardrail on a text, without saving an event.

Parameters:

id – The Guardrail’s id or hashed id.
text – The text, e.g. a prompt (input) or an LLM’s reply (output).
stage – The stage to evaluate the text as. The Guardrail must run on it.

Returns:

Whether it triggered, its disposition, and the text after its action.

Raises:

BadRequestError – If the text is empty or too long, or the Guardrail does not run on the stage.

events(id: 'SmarterIdType', *, reviewed: 'bool | None' = None, disposition: 'str | None' = None) → 'GuardrailEvents'

The latest events of a Guardrail that the user owns.

Parameters:

id – The Guardrail’s id or hashed id.
reviewed – Only reviewed (True) or unreviewed (False) events.
disposition – Only events of this disposition, e.g. blocked.

Returns:

The events, newest first.

`smarter.resources.mcpclients`

MCPClients: the platform’s connections to Model Context Protocol servers.

tools = client.mcp_clients.tools(1)
result = client.mcp_clients.call_tool(1, "aws___search_documentation", {"search_phrase": "S3"})
print(result.content)

class smarter.resources.mcpclients.MCPClients

Bases: smarter.resources.base.SmarterKindResource

MCPClients: /api/v1/mcpclients/, and the manifest api’s MCPClient kind.

tools(id: 'SmarterIdType', *, refresh: 'bool' = False) → 'MCPClientTools'

The tools that an MCPClient allows the LLM to call, from the server’s cached catalog.

Parameters:

id – The MCPClient’s id or hashed id.
refresh – True to read the catalog from the server now.

Returns:

The connection’s state, the server’s instructions, and the tools.

refresh(id: 'SmarterIdType') → 'MCPClientStatus'

Reconnect to an MCPClient’s server, and reload its catalog.

Only the owner may refresh.

Parameters:: id – The MCPClient’s id or hashed id.
Returns:: The connection’s state.

call_tool(id: 'SmarterIdType', tool: 'str', arguments: 'Mapping[str, SmarterJsonType] | None' = None) → 'MCPToolResult'

Call one of an MCPClient’s tools.

Only the owner may call tools.

Parameters:

id – The MCPClient’s id or hashed id.
tool – The tool’s name.
arguments – The tool’s arguments, as its input schema describes them.

Returns:

The tool’s result. Check is_error: a tool reports its own failures in its result.

`smarter.resources.vectorstores`

Vectorstores: vector databases for retrieval-augmented generation.

client.vectorstores.add_text(2, "Our refund window is 30 days.", name="refunds")
client.vectorstores.add_files(2, ["handbook.pdf"])
for result in client.vectorstores.search(2, "How long is the refund window?").results:
    print(result.score, result.text)

class smarter.resources.vectorstores.Vectorstores

Bases: smarter.resources.base.SmarterKindResource

Vectorstores: /api/v1/vectorstores/, and the manifest api’s Vectorstore kind.

The platform serves these endpoints only when SMARTER_ENABLE_VECTORSTORE is true.

status(id: 'SmarterIdType') → 'VectorstoreStatus'

A vectorstore’s state, checked now.

Parameters:: id – The vectorstore’s id or hashed id.
Returns:: Its status and vector count.

deploy(id: 'SmarterIdType') → 'Vectorstore'

Deploy a vectorstore: create its database, or connect to the provider’s.

A self-hosted vectorstore creates real, possibly billable, Kubernetes resources.

Parameters:: id – The vectorstore’s id or hashed id.
Returns:: The vectorstore.

undeploy(id: 'SmarterIdType') → 'Vectorstore'

Stop serving a vectorstore.

A self-hosted server’s data is kept.

Parameters:: id – The vectorstore’s id or hashed id.
Returns:: The vectorstore.

documents(id: 'SmarterIdType') → 'VectorstoreDocuments'

A vectorstore’s documents, newest first.

Parameters:: id – The vectorstore’s id or hashed id.
Returns:: The documents.

add_text(id: 'SmarterIdType', text: 'str', *, name: 'str | None' = None, metadata: 'Mapping[str, SmarterJsonType] | None' = None) → 'VectorstoreDocumentsAdded'

Add a text as a document.

Parameters:

id – The vectorstore’s id or hashed id.
text – The text.
name – The document’s name.
metadata – A JSON object, stored with each of the document’s chunks.

Returns:

The added document. It is loaded asynchronously, once the vectorstore is deployed.

add_url(id: 'SmarterIdType', url: 'str', *, metadata: 'Mapping[str, SmarterJsonType] | None' = None) → 'VectorstoreDocumentsAdded'

Add a public web page or file, by its url, as a document.

The platform fetches it.

Parameters:

id – The vectorstore’s id or hashed id.
url – The url.
metadata – A JSON object, stored with each of the document’s chunks.

Returns:

The added document.

add_files(id: 'SmarterIdType', files: 'Sequence[str | Path]') → 'VectorstoreDocumentsAdded'

Upload files as documents, e.g. PDF, Word, HTML or text files.

The platform extracts their text.

Parameters:

id – The vectorstore’s id or hashed id.
files – The files’ paths.

Returns:

The added documents.

delete_document(id: 'SmarterIdType', document_id: 'int') → 'VectorstoreDocumentDeleted'

Remove a document and its chunks.

The removal is asynchronous.

Parameters:

id – The vectorstore’s id or hashed id.
document_id – The document’s id.

Returns:

The document, being deleted.

search(id: 'SmarterIdType', query: 'str', *, k: 'int' = 4, search_type: "Literal['similarity', 'mmr', 'similarity_score_threshold']" = 'similarity', score_threshold: 'float | None' = None, fetch_k: 'int | None' = None, lambda_mult: 'float | None' = None, filter: 'Mapping[str, SmarterJsonType] | None' = None) → 'VectorstoreSearchResults'

Search a vectorstore.

Parameters:

id – The vectorstore’s id or hashed id.
query – The search text.
k – How many chunks to return. The platform caps it.
search_type – similarity, mmr (maximal marginal relevance), or similarity_score_threshold.
score_threshold – The minimum score, for similarity_score_threshold.
fetch_k – How many chunks mmr considers.
lambda_mult – mmr’s balance of relevance (1) and diversity (0).
filter – Only chunks whose metadata match.

Returns:

The matching chunks, best first.

snapshots(id: 'SmarterIdType') → 'VectorstoreSnapshots'

A vectorstore’s snapshots.

Parameters:: id – The vectorstore’s id or hashed id.
Returns:: The snapshots.

create_snapshot(id: 'SmarterIdType') → 'VectorstoreSnapshot'

Take a snapshot of a vectorstore’s data now.

Parameters:: id – The vectorstore’s id or hashed id.
Returns:: The snapshot.

restore(id: 'SmarterIdType', snapshot_id: 'int') → 'VectorstoreRestored'

Replace a vectorstore’s data with one of its snapshots.

Parameters:

id – The vectorstore’s id or hashed id.
snapshot_id – The snapshot’s id.

Returns:

The restored vector count.

`smarter.resources.llmhosts`

LLMHosts: open-weight models that the platform serves on its own Kubernetes cluster.

models = client.llm_hosts.discover(query="qwen", task="chat")
plan = client.llm_hosts.plan(3)          # what deploying would create, without creating it
status = client.llm_hosts.status(3)

class smarter.resources.llmhosts.LLMHosts

Bases: smarter.resources.base.SmarterKindResource

LLMHosts: /api/v1/llmhosts/, and the manifest api’s LLMHost kind.

status(id: 'SmarterIdType') → 'LLMHostStatus'

An LLMHost’s state, read from Kubernetes now.

Parameters:: id – The LLMHost’s id or hashed id.
Returns:: Its status, replicas and pods.

logs(id: 'SmarterIdType', *, tail: 'int' = 200) → 'LLMHostLogs'

The latest log lines of an LLMHost’s pods.

Parameters:

id – The LLMHost’s id or hashed id.
tail – How many lines.

Returns:

The logs.

plan(id: 'SmarterIdType') → 'LLMHostPlan'

The Kubernetes resources that deploying an LLMHost would create, without creating them.

Parameters:: id – The LLMHost’s id or hashed id.
Returns:: The resources.

deploy(id: 'SmarterIdType') → 'LLMHostStatus'

Deploy an LLMHost on the platform’s cluster.

This creates real, billable infrastructure, e.g. GPU nodes. Check plan() first.

Parameters:: id – The LLMHost’s id or hashed id.
Returns:: Its state.

undeploy(id: 'SmarterIdType', *, purge: 'bool' = False) → 'LLMHostStatus'

Undeploy an LLMHost.

Parameters:

id – The LLMHost’s id or hashed id.
purge – True to delete its model storage too.

Returns:

Its state.

report() → 'LLMHostReport'

A report of every LLMHost that the user may read: counts by status and engine, and estimated costs.

Returns:: The report.

discover(*, query: 'str | None' = None, task: 'str | None' = None, catalog: 'str' = 'huggingface', limit: 'int' = 20) → 'list[DiscoveredModel]'

Search a public model catalog for models that an LLMHost can serve.

Parameters:

query – The search text, e.g. qwen.
task – Only models of this task, e.g. chat or embedding.
catalog – The catalog.
limit – The maximum number of models.

Returns:

The models, each with the LLMHost manifest that would serve it.

discover_manifest(repository: 'str', *, catalog: 'str' = 'huggingface', engine: 'str | None' = None, name: 'str | None' = None, token_secret: 'str | None' = None) → 'Manifest'

An LLMHost manifest for a model in a public catalog, ready to apply.

Parameters:

repository – The model’s repository, e.g. Qwen/Qwen2.5-7B-Instruct.
catalog – The catalog.
engine – The inference engine, or None for the platform’s choice.
name – The LLMHost’s name, or None for one derived from the repository.
token_secret – The name of a Secret that holds the catalog’s access token, for gated models.

Returns:

The manifest, which apply() accepts.

`smarter.resources.catalog`

Secrets, plugins, orchestrators and vectorsearches: the kinds whose REST api only lists and reads them.

smarter.resources.catalog.PLUGIN_KINDS: The manifest kinds of plugins.

class smarter.resources.catalog.Secrets

Bases: smarter.resources.base.SmarterKindResource

Secrets: /api/v1/secrets/, and the manifest api’s Secret kind.

The api never returns a secret’s value. Create and rotate secrets with apply().

class smarter.resources.catalog.Plugins

Bases: smarter.resources.base.SmarterKindResource

Plugins: /api/v1/plugins/, and the manifest api’s plugin kinds.

A plugin’s manifest kind is its class, e.g. ApiPlugin or SqlPlugin. apply() accepts any of them, and describe() and delete() look the kind up by name.

apply(manifest: 'ManifestInput') → 'SmarterJournalMessage'

Create or update a plugin from its manifest, of any plugin kind.

Parameters:: manifest – The manifest.
Returns:: The platform’s response.
Raises:: SmarterValueError – If the manifest is not a plugin’s.

kind_of(name: 'str') → 'str'

A plugin’s manifest kind.

Parameters:: name – The plugin’s name.
Returns:: e.g. SqlPlugin.

describe(name: 'str') → 'Manifest'

A plugin’s manifest, with its read-only status.

Parameters:: name – The plugin’s name.
Returns:: The manifest.

delete(name: 'str') → 'SmarterJournalMessage'

Permanently delete a plugin.

Parameters:: name – The plugin’s name.
Returns:: The platform’s response.

retrieve(id: 'SmarterIdType') → 'Plugin'

One plugin, by its id.

The platform serves this only when its ALLOW_API_GET waffle switch is on. Otherwise it answers 405: use find() or describe() instead.

Parameters:: id – The plugin’s id.
Returns:: The plugin.

class smarter.resources.catalog.Orchestrators

Bases: smarter.resources.base.SmarterKindResource

Orchestrators: /api/v1/orchestrators/, and the manifest api’s Orchestrator kind.

class smarter.resources.catalog.Vectorsearches

Bases: smarter.resources.base.SmarterKindResource

Vectorsearches: /api/v1/vectorsearches/, and the manifest api’s Vectorsearch kind.

`smarter.resources.accounts`

Accounts, their users, and their contacts: /api/v1/accounts/.

Users and accounts are created and changed with manifests (the User and Account kinds): see smarter.resources.manifests.Manifests.

class smarter.resources.accounts.Users

Bases: smarter.resources.base.SmarterAPIResource

The users of the api key’s account: /api/v1/accounts/users/.

list() → 'list[User]'

The users that the api key’s user may read.

Returns:: The users.

retrieve(id: 'SmarterIdType') → 'User'

A user, by id.

Parameters:: id – The user’s id.
Returns:: The user.

class smarter.resources.accounts.AccountContacts

Bases: smarter.resources.base.SmarterAPIResource

The contacts of the api key’s account: /api/v1/accounts/contacts/.

list() → 'list[AccountContact]'

The account’s contacts.

Returns:: The contacts.

retrieve(id: 'SmarterIdType') → 'AccountContact'

A contact, by id.

Parameters:: id – The contact’s id.
Returns:: The contact.

class smarter.resources.accounts.Accounts(client: 'Smarter') → 'None'

Bases: smarter.resources.base.SmarterKindResource

Accounts: /api/v1/accounts/, and the manifest api’s Account kind.

`smarter.resources.history`

The history of chat sessions, tool calls and plugin uses: /api/v1/prompts/history/, and the Smarter Journal.

class smarter.resources.history.PromptHistory

Bases: smarter.resources.base.SmarterAPIResource

The chat sessions of the api key’s user, and their tool calls and plugin uses.

sessions() → 'list[PromptSession]'

The chat sessions.

Returns:: The sessions.

session(id: 'SmarterIdType') → 'PromptSession'

A chat session, by id.

Parameters:: id – The session’s id.
Returns:: The session.

tool_calls() → 'list[PromptToolCall]'

The tool calls of the chat sessions, with the LLM requests that made them.

Returns:: The tool calls.

tool_call(id: 'SmarterIdType') → 'PromptToolCall'

A tool call, by id.

Parameters:: id – The tool call’s id.
Returns:: The tool call.

plugin_usage() → 'list[PromptPluginUsage]'

The plugin uses of the chat sessions.

Returns:: The plugin uses.

class smarter.resources.history.Journal

Bases: smarter.resources.base.SmarterAPIResource

The Smarter Journal: a record of every journaled api request and response.

Superusers only.

Each entry’s request document holds the caller’s headers, including their api key, so only superusers may read the journal.

list(*, page: 'int' = 1, page_size: 'int | None' = None, search: 'str | None' = None, ordering: 'str | None' = None) → 'JournalPage'

One page of the journal’s entries, newest first, without their request and response documents.

Parameters:

page – The page number, from 1.
page_size – Entries per page, or None for the platform’s default.
search – Only entries whose key, thing or command contains this text.
ordering – A sort field, e.g. createdAt or -statusCode.

Returns:

The page, and its pagination.

retrieve(key: 'str') → 'JournalEntry'

A journal entry, with its request and response documents.

Parameters:: key – The entry’s key: the metadata.key of a journaled response.
Returns:: The entry.

`smarter.resources.providers`

LLM providers and their models: /api/v1/providers/.

class smarter.resources.providers.Providers

Bases: smarter.resources.base.SmarterAPIResource

The LLM providers that the platform is configured for, e.g. openai or anthropic.

list() → 'list[Provider]'

The providers.

Returns:: The providers.

retrieve(name: 'str') → 'Provider'

A provider, by name.

Parameters:: name – The provider’s name, e.g. openai.
Returns:: The provider.

models(name: 'str') → 'list[ProviderModel]'

A provider’s models.

Parameters:: name – The provider’s name.
Returns:: The models.

`smarter.resources.proxies`

Proxies: authenticated passthrough access to LLM providers’ own apis.

The platform holds the provider’s api key, and callers use their Smarter api key instead. The easiest way to call a proxy is with the provider’s own SDK:

from openai import OpenAI
from smarter import Smarter

smarter = Smarter()
openai = OpenAI(base_url=smarter.proxies.base_url("openai"), api_key=smarter.api_key)

class smarter.resources.proxies.Proxies

Bases: smarter.resources.base.SmarterAPIResource

Proxies: /api/v1/proxy/.

The platform serves these endpoints only when SMARTER_ENABLE_PROXY is true.

list() → 'list[Proxy]'

The proxies that the user may call.

Returns:: The proxies.

base_url(name: 'str') → 'str'

A proxy’s base url, for the provider’s own SDK.

Parameters:: name – The proxy’s name, e.g. openai.
Returns:: e.g. https://platform.smarter.sh/api/v1/proxy/openai/.

request(name: 'str', path: 'str', *, method: 'str' = 'POST', json: 'SmarterJsonType' = None, params: 'Mapping[str, QueryParamValue] | None' = None) → 'SmarterJsonType'

Send a request to a provider’s api, through its proxy.

Parameters:

name – The proxy’s name, e.g. openai.
path – The provider api’s path, e.g. v1/chat/completions. It must be one of the proxy’s allowed_paths.
method – The http method.
json – The JSON body, as the provider’s api expects it.
params – Query parameters.

Returns:

The provider’s JSON response.

Resources

smarter.resources.base

smarter.resources.manifests

smarter.resources.llmclients

smarter.resources.guardrails

smarter.resources.mcpclients

smarter.resources.vectorstores

smarter.resources.llmhosts

smarter.resources.catalog

smarter.resources.accounts

smarter.resources.history

smarter.resources.providers

smarter.resources.proxies

`smarter.resources.base`

`smarter.resources.manifests`

`smarter.resources.llmclients`

`smarter.resources.guardrails`

`smarter.resources.mcpclients`

`smarter.resources.vectorstores`

`smarter.resources.llmhosts`

`smarter.resources.catalog`

`smarter.resources.accounts`

`smarter.resources.history`

`smarter.resources.providers`

`smarter.resources.proxies`