Models

smarter.models.base

The base classes of the SDK’s response models.

Every model allows extra fields. The Smarter platform adds fields to its responses in minor releases, and an SDK that rejected them would break whenever the platform is upgraded. Extra fields are kept, and are available as attributes and in SmarterModel.to_dict().

class smarter.models.base.SmarterModel

Bases: pydantic.main.BaseModel

The base class of the SDK’s models: a Pydantic model that keeps unknown fields.

to_dict() → dict[str, Any]

The model as a JSON-compatible dict, with the api’s own field names.

Returns:

The fields that the api returned, or that were set.

to_json(indent: int | None = 2) → str

The model as JSON text, with the api’s own field names.

Parameters:

indent – The indentation, or None for compact JSON.

Returns:

The JSON text.

class smarter.models.base.SmarterCamelModel

Bases: smarter.models.base.SmarterModel

A model of a response whose field names are camelCase, e.g. hashedId.

Its attributes are snake_case (hashed_id), and it accepts either spelling.

class smarter.models.base.SmarterUserRef

Bases: smarter.models.base.SmarterCamelModel

The user of a resource’s owner.

username: str
email: Optional
class smarter.models.base.SmarterAccountRef

Bases: smarter.models.base.SmarterCamelModel

The account of a resource’s owner.

account_number: str = alias ``accountNumber``
class smarter.models.base.SmarterOwner

Bases: smarter.models.base.SmarterCamelModel

The owner of a resource: its user profile, as the user and the account.

user: Optional
account: Optional
class smarter.models.base.SmarterResource

Bases: smarter.models.base.SmarterCamelModel

The fields that every Smarter resource shares, as the REST api returns them.

The api’s resources are Django rows with the same metadata as a manifest’s metadata: a name, description, version, tags and annotations. Each resource’s model adds its own fields.

id: int
hashed_id: Optional = alias ``hashedId``
name: str
description: Optional
version: Optional
tags: list
annotations: list
created_at: Optional = alias ``createdAt``
updated_at: Optional = alias ``updatedAt``
user_profile: Optional = alias ``userProfile``
can_delete: Optional = alias ``canDelete``
manifest_url: Optional = alias ``manifestUrl``
ready: Optional

smarter.models.manifest

Models of Smarter Application Manifests (SAM): the YAML documents that declare every Smarter resource.

A manifest has the same four sections as a Kubernetes manifest: apiVersion, kind, metadata and spec. describe adds a read-only status. The shape of spec depends on the kind and the platform’s version, so it is a JSON object here. The platform publishes the complete JSON Schema of each kind: see smarter.resources.manifests.Manifests.json_schema().

smarter.models.manifest.SMARTER_API_VERSION

The apiVersion of every Smarter manifest.

class smarter.models.manifest.ManifestMetadata

Bases: smarter.models.base.SmarterModel

A manifest’s metadata: the resource’s name, and descriptive information about it.

name: str

The resource’s name, unique per account and kind, in snake_case.

description: Optional
version: Optional

The resource’s semantic version, e.g. 1.0.0.

tags: list
annotations: list

Key-value pairs, as a list of single-key objects.

class smarter.models.manifest.Manifest

Bases: smarter.models.base.SmarterModel

A Smarter Application Manifest.

manifest = Manifest.from_yaml(open("llmclient.yaml").read())
manifest.metadata.name
manifest.spec["config"]["provider"]
apiVersion: str
kind: str

The resource kind, e.g. LLMClient. See Smarter.kinds().

metadata: ManifestMetadata
spec: dict

The resource’s specification.

status: Optional

Read-only state, returned by describe.

classmethod from_yaml(text: str) → 'Manifest'

Parse a manifest from YAML (or JSON) text.

Parameters:

text – The manifest’s text.

Returns:

The manifest.

Raises:

SmarterValueError – If the text is not a YAML object.

classmethod from_file(path: str | pathlib.Path) → 'Manifest'

Read a manifest from a YAML or JSON file.

Parameters:

path – The file’s path.

Returns:

The manifest.

to_sam() → 'SAMModel'

The manifest as its kind’s typed SAM model, e.g. a SAMGuardrail.

guardrail = client.guardrails.describe("pii_redactor").to_sam()
print(guardrail.spec.config.action)
Returns:

The typed manifest.

Raises:
  • SmarterValueError – If the SDK has no model of the manifest’s kind.

  • pydantic.ValidationError – If the manifest does not match its kind’s model.

to_yaml() → str

The manifest as YAML text, without its read-only status, ready to apply.

Returns:

The YAML text.

class smarter.models.manifest.ManifestListTitle

Bases: smarter.models.base.SmarterModel

A column of a get result: the field’s name, and its Django field type.

name: str
type: str
class smarter.models.manifest.ManifestListData

Bases: smarter.models.base.SmarterModel

The table of a get result.

titles: list
items: list
class smarter.models.manifest.ManifestListMetadata

Bases: smarter.models.base.SmarterModel

The metadata of a get result.

count: int
class smarter.models.manifest.ManifestList

Bases: smarter.models.base.SmarterModel

The result of get: the resources of one kind, as a table.

data.items are the rows, and data.titles their columns. The columns depend on the kind.

apiVersion: str
kind: str
name: Optional
metadata: ManifestListMetadata
data: ManifestListData
property items

The rows.

property names

The names of the resources: each row’s name, or its username for the User kind.

class smarter.models.manifest.KindInfo

Bases: smarter.models.base.SmarterCamelModel

A resource kind that the platform supports, as /api/v1/cli/resources/ describes it.

singular: str = alias ``Singular``
plural: str = alias ``Plural``
api_kind: str = alias ``APIKind``

The kind, as it appears in a manifest.

display: Optional = alias ``Display``
display_plural: Optional = alias ``DisplayPlural``
deployable: bool = alias ``Deployable``

True if the kind can be deployed.

smarter.models.platform

Models of the platform’s own endpoints: whoami, version and status.

class smarter.models.platform.WhoAmI

Bases: smarter.models.base.SmarterModel

The owner of the api key: the user, their account, and the platform’s environment.

user: User
account: Account
environment: Optional

The platform’s environment, e.g. local or prod.

class smarter.models.platform.ApiVersion

Bases: smarter.models.base.SmarterModel

The platform’s version, and the versions of its main Python packages.

version: str

The Smarter platform’s semantic version.

python: dict

Python package versions, by package.

class smarter.models.platform.CliVersion

Bases: smarter.models.base.SmarterModel

The version of the smarter cli that the platform recommends.

version: Optional
class smarter.models.platform.PlatformVersion

Bases: smarter.models.base.SmarterModel

The response of version.

api: ApiVersion
cli: Optional
class smarter.models.platform.PlatformStatus

Bases: smarter.models.base.SmarterCamelModel

The response of status: the state of the platform’s infrastructure and compute.

The sections’ contents depend on how the platform is hosted, so they are JSON objects.

infrastructures: dict
compute: dict

smarter.models.account

Models of accounts, users and account contacts, as /api/v1/accounts/ returns them.

class smarter.models.account.Account

Bases: smarter.models.base.SmarterResource

A Smarter account: the tenant that owns users and resources.

account_number: str = alias ``accountNumber``
is_default_account: Optional = alias ``isDefaultAccount``
company_name: Optional = alias ``companyName``
phone_number: Optional = alias ``phoneNumber``
address1: Optional
address2: Optional
city: Optional
state: Optional
postal_code: Optional = alias ``postalCode``
country: Optional
language: Optional
timezone: Optional
currency: Optional
is_active: Optional = alias ``isActive``
class smarter.models.account.User

Bases: smarter.models.base.SmarterCamelModel

A user of the platform.

id: int
username: str
first_name: Optional = alias ``firstName``
last_name: Optional = alias ``lastName``
email: Optional
is_staff: Optional = alias ``isStaff``
is_superuser: Optional = alias ``isSuperuser``
class smarter.models.account.AccountContact

Bases: smarter.models.base.SmarterCamelModel

A contact of an account, who receives its notices.

id: int
account: Optional
created_at: Optional = alias ``createdAt``
updated_at: Optional = alias ``updatedAt``
first_name: Optional = alias ``firstName``
last_name: Optional = alias ``lastName``
email: Optional
phone: Optional
is_primary: Optional = alias ``isPrimary``
is_test: Optional = alias ``isTest``
welcomed: Optional

smarter.models.llmclient

Models of LLMClients and their plugins, built-in functions, api keys and custom domains.

class smarter.models.llmclient.LLMClientPluginRef

Bases: smarter.models.base.SmarterCamelModel

A plugin of an LLMClient, by its id and name.

id: int
name: Optional
class smarter.models.llmclient.LLMClientFunction

Bases: smarter.models.base.SmarterCamelModel

A built-in function of an LLMClient, e.g. calculator.

id: int
name: Optional
llmclient: Optional
created_at: Optional = alias ``createdAt``
updated_at: Optional = alias ``updatedAt``
class smarter.models.llmclient.LLMClientPlugin

Bases: smarter.models.base.SmarterCamelModel

The association of a plugin with an LLMClient.

id: int
plugin_meta: Plugin = alias ``pluginMeta``
llmclient: Optional
class smarter.models.llmclient.LLMClientApiKey

Bases: smarter.models.base.SmarterCamelModel

An api key that may call an LLMClient that requires authentication.

id: int
llmclient: Optional
api_key: Optional = alias ``apiKey``
class smarter.models.llmclient.LLMClientCustomDomain

Bases: smarter.models.base.SmarterCamelModel

A custom domain on which an LLMClient is deployed.

id: int
llmclient: Optional
custom_domain: Optional = alias ``customDomain``
class smarter.models.llmclient.LLMClient

Bases: smarter.models.base.SmarterResource

An LLMClient: a deployable AI agent, built from an LLM provider and model, a system prompt, plugins and functions.

Prompt it with smarter.resources.llmclients.LLMClients.prompt(), or start a chat with smarter.resources.llmclients.LLMClients.chat().

rfc1034_compliant_name: Optional = alias ``rfc1034CompliantName``
provider: Optional
default_model: Optional = alias ``defaultModel``
default_system_role: Optional = alias ``defaultSystemRole``

The system prompt of a new chat session.

deployed: Optional
default_host: Optional = alias ``defaultHost``
default_url: Optional = alias ``defaultUrl``
custom_host: Optional = alias ``customHost``
custom_url: Optional = alias ``customUrl``
sandbox_host: Optional = alias ``sandboxHost``
sandbox_url: Optional = alias ``sandboxUrl``
functions: list
plugins: list

smarter.models.plugin

Models of plugins: the tools that an LLMClient’s LLM can call.

class smarter.models.plugin.Plugin

Bases: smarter.models.base.SmarterResource

A plugin’s metadata.

Its kind is the manifest kind, e.g. ApiPlugin or SqlPlugin, and its plugin_class the implementation: api, skill, sql, static, websearch or imagesearch.

plugin_class: Optional = alias ``pluginClass``

api, skill, sql, static, websearch or imagesearch.

kind: Optional

The manifest kind, e.g. ApiPlugin.

smarter.models.guardrail

Models of guardrails, their evaluations, and their events.

class smarter.models.guardrail.Guardrail

Bases: smarter.models.base.SmarterResource

A guardrail: a check that the platform runs on prompts (input) or on the LLM’s replies (output).

stage: Optional

input or output.

category: Optional
strategy: Optional

e.g. regex, detector, classifier or llm.

pattern: Optional
config: Optional
threshold: Optional
action: Optional

e.g. block, redact or flag.

replacement: Optional
message: Optional
severity: Optional
mode: Optional

enforce or monitor.

fail_closed: Optional = alias ``failClosed``
priority: Optional
is_active: Optional = alias ``isActive``
class smarter.models.guardrail.GuardrailMatch

Bases: smarter.models.base.SmarterModel

A span of the text that a guardrail matched.

start: int
end: int
text: str
label: Optional
class smarter.models.guardrail.GuardrailFinding

Bases: smarter.models.base.SmarterModel

One finding of a guardrail evaluation.

confidence: Optional
rationale: Optional
matches: list
class smarter.models.guardrail.GuardrailEvaluation

Bases: smarter.models.base.SmarterCamelModel

The result of a guardrail’s dry run on a text.

Nothing is saved: an evaluation does not create an event.

guardrail: str
stage: str
triggered: bool
disposition: Optional

e.g. passed, blocked, redacted or flagged.

text: Optional

The text after the guardrail’s action, e.g. redacted.

message: Optional
error: Optional
duration_ms: Optional = alias ``durationMs``
findings: list
class smarter.models.guardrail.GuardrailEvent

Bases: smarter.models.base.SmarterCamelModel

A guardrail’s finding in a real prompt, saved for review.

id: int
created_at: Optional = alias ``createdAt``
llmclient: Optional

The name of the LLMClient whose prompt triggered it.

stage: Optional
disposition: Optional
reviewed: Optional
class smarter.models.guardrail.GuardrailEvents

Bases: smarter.models.base.SmarterModel

The latest events of a guardrail.

guardrail: str
events: list

smarter.models.mcpclient

Models of MCPClients: connections to Model Context Protocol servers, whose tools an LLMClient’s LLM can call.

class smarter.models.mcpclient.MCPClient

Bases: smarter.models.base.SmarterResource

An MCPClient: an MCP server, how to reach it, and which of its tools the LLM may call.

transport: Optional

http, sse or stdio.

endpoint_url: Optional = alias ``endpointUrl``
command: Optional
timeout: Optional
auth_type: Optional = alias ``authType``
allowed_tools: list = alias ``allowedTools``
allowed_resources: list = alias ``allowedResources``
include_instructions: Optional = alias ``includeInstructions``
cache_ttl: Optional = alias ``cacheTtl``
is_active: Optional = alias ``isActive``
status: Optional

e.g. connected or error.

priority: Optional
protocol_version: Optional = alias ``protocolVersion``
server_name: Optional = alias ``serverName``
server_version: Optional = alias ``serverVersion``
tools: list

The names of every tool that the server offers.

last_connected_at: Optional = alias ``lastConnectedAt``
last_error: Optional = alias ``lastError``
class smarter.models.mcpclient.MCPClientStatus

Bases: smarter.models.base.SmarterCamelModel

The connection state of an MCPClient.

name: str
status: Optional
protocol_version: Optional = alias ``protocolVersion``
server_name: Optional = alias ``serverName``
server_version: Optional = alias ``serverVersion``
last_connected: Optional = alias ``lastConnected``
last_error: Optional = alias ``lastError``
error: Optional

The error of a failed refresh.

class smarter.models.mcpclient.MCPTool

Bases: smarter.models.base.SmarterCamelModel

A tool of an MCP server, which the MCPClient allows the LLM to call.

name: str
title: Optional
description: Optional
input_schema: Optional = alias ``inputSchema``

The tool’s arguments, as a JSON Schema.

read_only: Optional = alias ``readOnly``
destructive: Optional
class smarter.models.mcpclient.MCPClientTools

Bases: smarter.models.mcpclient.MCPClientStatus

An MCPClient’s allowed tools, and the server’s instructions.

instructions: Optional
tools: list
class smarter.models.mcpclient.MCPToolResult

Bases: smarter.models.base.SmarterCamelModel

The result of a tool call.

name: str

The MCPClient’s name.

tool: str
is_error: bool = alias ``isError``
content: Optional

The tool’s result, as text.

smarter.models.vectorstore

Models of vectorstores, their documents and snapshots, and search results.

class smarter.models.vectorstore.Vectorstore

Bases: smarter.models.base.SmarterResource

A vectorstore: a vector database, hosted by Smarter or by a provider, for retrieval-augmented generation.

backend: Optional

e.g. qdrant or pinecone.

hosting: Optional

self_hosted or managed.

is_active: Optional = alias ``isActive``
dimension: Optional
metric: Optional
embeddings_provider: Optional = alias ``embeddingsProvider``
embeddings_model: Optional = alias ``embeddingsModel``
status: Optional

e.g. pending, ready or error.

status_message: Optional = alias ``statusMessage``
index_name: Optional = alias ``indexName``
endpoint_url: Optional = alias ``endpointUrl``
vector_count: Optional = alias ``vectorCount``
document_count: Optional = alias ``documentCount``
snapshot_count: Optional = alias ``snapshotCount``
spec: Optional
deployed_at: Optional = alias ``deployedAt``
class smarter.models.vectorstore.VectorstoreStatus

Bases: smarter.models.base.SmarterCamelModel

A vectorstore’s state, checked now.

vectorstore: str
status: str
message: Optional
vector_count: Optional = alias ``vectorCount``
stats: dict
class smarter.models.vectorstore.VectorstoreDocument

Bases: smarter.models.base.SmarterCamelModel

A document of a vectorstore: a file, a text or a url, split into chunks and embedded.

id: int
name: str
created_at: Optional = alias ``createdAt``
updated_at: Optional = alias ``updatedAt``
source: Optional

upload, text or url.

content_type: Optional = alias ``contentType``
status: Optional

e.g. pending, loaded, error or deleting.

chunk_count: Optional = alias ``chunkCount``
metadata: Optional
class smarter.models.vectorstore.VectorstoreDocuments

Bases: smarter.models.base.SmarterCamelModel

A vectorstore’s documents.

documents: list
class smarter.models.vectorstore.VectorstoreDocumentsAdded

Bases: smarter.models.base.SmarterCamelModel

The result of adding documents.

Documents are loaded asynchronously, and only once the vectorstore is deployed: see queued.

documents: list
duplicates: list

Documents that already existed.

queued: bool
message: Optional
class smarter.models.vectorstore.VectorstoreDocumentDeleted

Bases: smarter.models.base.SmarterCamelModel

A document that is being deleted, with its chunks.

document: str
status: str
class smarter.models.vectorstore.VectorstoreSearchResult

Bases: smarter.models.base.SmarterCamelModel

A chunk that matched a search.

id: Optional
text: str
metadata: Optional
score: Optional
class smarter.models.vectorstore.VectorstoreSearchResults

Bases: smarter.models.base.SmarterCamelModel

The chunks that matched a search, best first.

vectorstore: str
results: list
class smarter.models.vectorstore.VectorstoreSnapshot

Bases: smarter.models.base.SmarterCamelModel

A snapshot of a vectorstore’s data.

id: int
name: Optional
created_at: Optional = alias ``createdAt``
status: Optional
scheduled: Optional
size_bytes: Optional = alias ``sizeBytes``
class smarter.models.vectorstore.VectorstoreSnapshots

Bases: smarter.models.base.SmarterCamelModel

A vectorstore’s snapshots.

snapshots: list
class smarter.models.vectorstore.VectorstoreRestored

Bases: smarter.models.base.SmarterCamelModel

The result of restoring a snapshot.

vectorstore: str
restored: str
vector_count: Optional = alias ``vectorCount``

smarter.models.llmhost

Models of LLMHosts: open-weight models that Smarter serves on its own Kubernetes cluster.

class smarter.models.llmhost.LLMHost

Bases: smarter.models.base.SmarterResource

An LLMHost: a model, the inference engine that serves it, and the compute it runs on.

spec: Optional
model_source: Optional = alias ``modelSource``
model_repository: Optional = alias ``modelRepository``
model_revision: Optional = alias ``modelRevision``
model_task: Optional = alias ``modelTask``

e.g. chat, completion or embedding.

inference_engine: Optional = alias ``inferenceEngine``

e.g. vllm, tgi, tei, ollama or llama_cpp.

api_format: Optional = alias ``apiFormat``
compute: Optional

The id of the LLMHostCompute that the LLMHost runs on.

gpu_count: Optional = alias ``gpuCount``
gpu_type: Optional = alias ``gpuType``
replicas: Optional
ready_replicas: Optional = alias ``readyReplicas``
status: Optional
status_message: Optional = alias ``statusMessage``
endpoint_url: Optional = alias ``endpointUrl``
public_url: Optional = alias ``publicUrl``
served_model_name: Optional = alias ``servedModelName``
is_active: Optional = alias ``isActive``
deployed_at: Optional = alias ``deployedAt``
cost_per_hour: Optional = alias ``costPerHour``
class smarter.models.llmhost.LLMHostStatus

Bases: smarter.models.base.SmarterCamelModel

An LLMHost’s state, read from Kubernetes now.

llmhost: str
status: str
message: Optional
replicas: Optional
ready_replicas: Optional = alias ``readyReplicas``
healthy: Optional
endpoint: Optional
public_url: Optional = alias ``publicUrl``
pods: list
checked_at: Optional = alias ``checkedAt``
class smarter.models.llmhost.LLMHostLogs

Bases: smarter.models.base.SmarterCamelModel

The latest log lines of an LLMHost’s pods.

llmhost: str
logs: JsonValue
class smarter.models.llmhost.LLMHostPlan

Bases: smarter.models.base.SmarterCamelModel

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

llmhost: str
resources: list
class smarter.models.llmhost.LLMHostReport

Bases: smarter.models.base.SmarterCamelModel

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

totals: dict
by_status: dict = alias ``byStatus``
by_engine: dict = alias ``byEngine``
llmhosts: list
class smarter.models.llmhost.DiscoveredModel

Bases: smarter.models.base.SmarterModel

A model found in a public catalog, e.g. Hugging Face, with the LLMHost manifest that would serve it.

catalog: Optional
source: Optional
repository: str
task: Optional
description: Optional
license: Optional
gated: Optional
downloads: Optional
likes: Optional
tags: list
manifest: Optional
class smarter.models.llmhost.DiscoveredManifest

Bases: smarter.models.base.SmarterModel

The response of discover/manifest/: a drafted LLMHost manifest.

manifest: dict
class smarter.models.llmhost.DiscoveredModels

Bases: smarter.models.base.SmarterModel

The models that a catalog search found.

models: list

smarter.models.misc

Models of secrets, prompt history, proxies, orchestrators and vectorsearches.

class smarter.models.misc.Secret

Bases: smarter.models.base.SmarterResource

A secret’s metadata.

The api never returns a secret’s value.

expires_at: Optional = alias ``expiresAt``
last_accessed: Optional = alias ``lastAccessed``
class smarter.models.misc.Orchestrator

Bases: smarter.models.base.SmarterResource

An orchestrator: a multi-agent workflow that composes LLMClients.

class smarter.models.misc.Vectorsearch

Bases: smarter.models.base.SmarterResource

A vectorsearch: a retrieval pipeline over one or more vectorstores.

class smarter.models.misc.PromptSession

Bases: smarter.models.base.SmarterModel

A chat session: one conversation with an LLMClient, by its session key.

id: int
created_at: Optional
updated_at: Optional
name: Optional
description: Optional
session_key: Optional
ip_address: Optional
user_agent: Optional
url: Optional
user_profile: Optional
llmclient: Optional
class smarter.models.misc.PromptToolCall

Bases: smarter.models.base.SmarterModel

A tool call that the LLM made in a chat session.

id: int
prompt: Union
created_at: Optional
updated_at: Optional
plugin: Optional
function_name: Optional
function_args: Optional
request: JsonValue
response: JsonValue
class smarter.models.misc.PromptPluginUsage

Bases: smarter.models.base.SmarterModel

A use of a plugin in a chat session.

id: int
prompt: Union
created_at: Optional
updated_at: Optional
plugin: Optional
input_text: Optional
class smarter.models.misc.Proxy

Bases: smarter.models.base.SmarterCamelModel

A proxy: authenticated passthrough access to an LLM provider’s own api.

The platform holds the provider’s api key. Callers use their Smarter api key instead, and may reach only the proxy’s allowed_paths.

name: str
description: Optional
provider: Optional
url: Optional

The proxy’s base url on the Smarter platform.

upstream_url: Optional = alias ``upstreamUrl``
allowed_paths: list = alias ``allowedPaths``
is_active: Optional = alias ``isActive``
class smarter.models.misc.Proxies

Bases: smarter.models.base.SmarterModel

The proxies that the user may call.

proxies: list
class smarter.models.misc.Provider

Bases: smarter.models.base.SmarterCamelModel

An LLM provider that the platform is configured for, e.g. openai.

name: str
description: Optional
base_url: Optional = alias ``baseUrl``
is_active: Optional = alias ``isActive``
class smarter.models.misc.ProviderModel

Bases: smarter.models.base.SmarterCamelModel

A model of an LLM provider.

name: str
description: Optional
max_tokens: Optional = alias ``maxTokens``
supports_streaming: Optional = alias ``supportsStreaming``
supports_tools: Optional = alias ``supportsTools``
metadata: Optional