Resources

The client’s resource families, e.g. client.guardrails. Every method returns a promise. See Resources.

class AccountContacts(client)

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

Extends ReadOnlyResource, and has its methods.

Arguments:

client (ResourceClient) – The client.

class Accounts(client)

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

Extends SmarterKindResource, and has its methods.

Arguments:

client (unknown) – The client.

Accounts.contacts

The account’s contacts.

Type:: AccountContacts

Accounts.kind

The manifest kind, e.g. Guardrail.

Type:: “Account”

Accounts.model

The schema of one resource.

Type:: object

Accounts.path

The REST list endpoint, relative to the api’s base url, e.g. guardrails/.

Type:: “accounts/”

Accounts.userProfiles

The users’ memberships of accounts.

Type:: UserProfiles

Accounts.users

The account’s users.

Type:: Users

class ChatSession(llmclients, llmclientId, config)

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.

Arguments:

llmclients (LLMClients) – The LLMClients resource.
llmclientId (SmarterId) – The LLMClient’s id or hashed id.
config (object) – The chat session’s configuration.

ChatSession.config

The chat session’s configuration.

Type:: object

ChatSession.llmclientId

The LLMClient’s id or hashed id.

Type:: SmarterId

ChatSession.messages

The chat thread.

Type:: object[]

ChatSession.sessionKey

The chat session’s key, with which the session can be resumed: see LLMClients.chat.

Type:: string

ChatSession.send(content, options?)

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

Arguments:

content (string | object) – A user message’s text, or a message.
options (RequestOptions | undefined) – Per-request options.

Returns:

The prompt’s response. text is the LLM’s reply.

Return type:

Promise<PromptResponse>

ChatSession.stream(content, options?)

Send a message, and stream the prompt’s progress. The thread is updated when the stream has been read to its end.

Arguments:

content (string | object) – A user message’s text, or a message.
options (RequestOptions | undefined) – Per-request options.

Returns:

The stream.

Return type:

ChatStream

class ChatStream(events, onMessages)

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

Extends PromptStream, and has its methods.

Arguments:

events (object) – Starts the request, and iterates its Server-Sent Events.
onMessages (object) – Called with a successful prompt’s messages.

class Guardrails(client)

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

Extends SmarterKindResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

Guardrails.kind

The manifest kind, e.g. Guardrail.

Type:: “Guardrail”

Guardrails.model

The schema of one resource.

Type:: object

Guardrails.path

The REST list endpoint, relative to the api’s base url, e.g. guardrails/.

Type:: “guardrails/”

Guardrails.evaluate(id, text, options?)

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

Arguments:

id (SmarterId) – The Guardrail’s id or hashed id.
text (string) – The text, e.g. a prompt (input) or an LLM’s reply (output).
options (unknown | undefined) – stage: the stage to evaluate the text as, input by default. The Guardrail must run on it.

Returns:

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

Throws:

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

Return type:

Promise<object>

Guardrails.events(id, options?)

The latest events of a Guardrail that the user owns.

Arguments:

id (SmarterId) – The Guardrail’s id or hashed id.
options (unknown | undefined) – reviewed: only reviewed (true) or unreviewed (false) events. disposition: only events of this disposition, e.g. blocked.

Returns:

The events, newest first.

Return type:

Promise<object>

class Journal(client)

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.

Extends SmarterAPIResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

Journal.path

The journal’s endpoint.

Type:: “journal/”

Journal.list(options?)

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

Arguments:

options (JournalListOptions | undefined) – page, pageSize, search and ordering.

Returns:

The page, and its pagination.

Return type:

Promise<object>

Journal.retrieve(key, options?)

A journal entry, with its request and response documents.

Arguments:

key (string) – The entry’s key: the metadata.key of a journaled response.
options (RequestOptions | undefined) – Per-request options.

Returns:

The entry.

Return type:

Promise<object>

class LLMClients(client)

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

Extends SmarterKindResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

LLMClients.kind

The manifest kind, e.g. Guardrail.

Type:: “LLMClient”

LLMClients.model

The schema of one resource.

Type:: object

LLMClients.path

The REST list endpoint, relative to the api’s base url, e.g. guardrails/.

Type:: “llm-clients/”

LLMClients.apiKeys(id, options?)

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

Arguments:

id (SmarterId) – The LLMClient’s integer id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The api keys.

Return type:

Promise<object[]>

LLMClients.chat(id, options?)

Start or resume a conversation with an LLMClient.

Arguments:

id (SmarterId) – The LLMClient’s id or hashed id.
options (PromptOptions | undefined) – sessionKey: an existing session’s key, to resume it, or none for a new session.

Returns:

The chat session.

Return type:

Promise<ChatSession>

LLMClients.config(id, options?)

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

Arguments:

id (SmarterId) – The LLMClient’s id or hashed id.
options (PromptOptions | undefined) – sessionKey: 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.

Return type:

Promise<object>

LLMClients.customDomains(id, options?)

The custom domains of an LLMClient.

Arguments:

id (SmarterId) – The LLMClient’s integer id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The custom domains.

Return type:

Promise<object[]>

LLMClients.deploy(name, options?)

Deploy an LLMClient on its own host name.

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

Arguments:

name (string) – The LLMClient’s name.
options (RequestOptions | undefined) – Per-request options.

Returns:

The platform’s response.

Return type:

Promise<object>

LLMClients.events(id, prompt, options?)

The Server-Sent Events of a prompt, which are requested when the iteration starts.

Arguments:

id (SmarterId) – The LLMClient’s id or hashed id.
prompt (PromptInput) – The prompt.
options (PromptOptions | undefined) – sessionKey, and per-request options.

Returns:

A function that starts the request.

Return type:

object

LLMClients.functions(id, options?)

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

Arguments:

id (SmarterId) – The LLMClient’s integer id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The functions.

Return type:

Promise<object[]>

LLMClients.plugins(id, options?)

An LLMClient’s plugins.

Arguments:

id (SmarterId) – The LLMClient’s integer id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The plugins.

Return type:

Promise<object[]>

LLMClients.prompt(id, prompt, options?)

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.

Arguments:

id (SmarterId) – The LLMClient’s id or hashed id.
prompt (PromptInput) – The text of one user message, or the chat thread as a list of messages.
options (PromptOptions | undefined) – sessionKey, the chat session’s key, and per-request options.

Returns:

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

Throws:

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

Return type:

Promise<PromptResponse>

LLMClients.stream(id, prompt, options?)

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

Arguments:

id (SmarterId) – The LLMClient’s id or hashed id.
prompt (PromptInput) – The text of one user message, or the chat thread as a list of messages.
options (PromptOptions | undefined) – sessionKey, and per-request options. The timeout applies to each event.

Returns:

The stream. Iterate it with for await for the progress events.

Return type:

PromptStream

LLMClients.undeploy(name, options?)

Undo an LLMClient’s deployment.

Arguments:

name (string) – The LLMClient’s name.
options (RequestOptions | undefined) – Per-request options.

Returns:

The platform’s response.

Return type:

Promise<object>

class LLMHosts(client)

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

Extends SmarterKindResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

LLMHosts.kind

The manifest kind, e.g. Guardrail.

Type:: “LLMHost”

LLMHosts.model

The schema of one resource.

Type:: object

LLMHosts.path

The REST list endpoint, relative to the api’s base url, e.g. guardrails/.

Type:: “llmhosts/”

LLMHosts.deploy(id, options?)

Deploy an LLMHost on the platform’s cluster.

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

Arguments:

id (SmarterId) – The LLMHost’s id or hashed id.
options (RequestOptions | undefined) – Per-request options.

Returns:

Its state.

Return type:

Promise<object>

LLMHosts.discover(options?)

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

Arguments:

options (unknown | undefined) – query: the search text, e.g. qwen. task: only models of this task, e.g. chat or embedding. catalog: huggingface by default. limit: at most this many, 20 by default.

Returns:

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

Return type:

Promise<object[]>

LLMHosts.discoverManifest(repository, options?)

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

Arguments:

repository (string) – The model’s repository, e.g. Qwen/Qwen2.5-7B-Instruct.
options (unknown | undefined) – catalog, huggingface by default. engine: the inference engine, or none for the platform’s choice. name: the LLMHost’s name, or none for one derived from the repository. tokenSecret: the name of a Secret that holds the catalog’s access token, for gated models.

Returns:

The manifest, which LLMHosts.apply accepts.

Return type:

Promise<Manifest>

LLMHosts.logs(id, options?)

The latest log lines of an LLMHost’s pods.

Arguments:

id (SmarterId) – The LLMHost’s id or hashed id.
options (unknown | undefined) – tail: how many lines, 200 by default.

Returns:

The logs.

Return type:

Promise<object>

LLMHosts.plan(id, options?)

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

Arguments:

id (SmarterId) – The LLMHost’s id or hashed id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The resources.

Return type:

Promise<object>

LLMHosts.report(options?)

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

Arguments:

options (RequestOptions | undefined) – Per-request options.

Returns:

The report.

Return type:

Promise<object>

LLMHosts.status(id, options?)

An LLMHost’s state, read from Kubernetes now.

Arguments:

id (SmarterId) – The LLMHost’s id or hashed id.
options (RequestOptions | undefined) – Per-request options.

Returns:

Its status, replicas and pods.

Return type:

Promise<object>

LLMHosts.undeploy(id, options?)

Undeploy an LLMHost.

Arguments:

id (SmarterId) – The LLMHost’s id or hashed id.
options (unknown | undefined) – purge: true to delete its model storage too.

Returns:

Its state.

Return type:

Promise<object>

class Manifests(client)

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

Extends SmarterAPIResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

Manifests.apply(manifest, options?)

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.

Arguments:

manifest (ManifestInput) – The manifest: a Manifest, an object, YAML text, or the path of a YAML file.
options (RequestOptions | undefined) – Per-request options.

Returns:

The platform’s response, whose message says what was applied.

Throws:

BadRequestError – If the platform rejects the manifest.

Return type:

Promise<object>

Manifests.delete(kind, name, options?)

Permanently delete a resource.

Arguments:

kind (string) – The manifest kind.
name (string) – The resource’s name.
options (RequestOptions | undefined) – Per-request options.

Returns:

The platform’s response.

Throws:

NotFoundError – If the resource does not exist.

Return type:

Promise<object>

Manifests.deploy(kind, name, options?)

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.

Arguments:

kind (string) – The manifest kind of a deployable resource. See client.kinds().
name (string) – The resource’s name.
options (RequestOptions | undefined) – Per-request options.

Returns:

The platform’s response.

Return type:

Promise<object>

Manifests.describe(kind, name, options?)

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

Arguments:

kind (string) – The manifest kind.
name (string) – The resource’s name.
options (RequestOptions | undefined) – Per-request options.

Returns:

The manifest, which Manifests.apply accepts as is.

Throws:

NotFoundError – If the resource does not exist.

Return type:

Promise<Manifest>

Manifests.exampleManifest(kind, options?)

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

Arguments:

kind (string) – The manifest kind.
options (RequestOptions | undefined) – Per-request options.

Returns:

The manifest.

Return type:

Promise<Manifest>

Manifests.get(kind, name?, options?)

The resources of one kind, as a table.

Arguments:

kind (string) – The manifest kind, e.g. LLMClient.
name (string | null | undefined) – Only the resource of this name.
options (RequestOptions | undefined) – Per-request options.

Returns:

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

Return type:

Promise<ManifestTable>

Manifests.jsonSchema(kind, options?)

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

Arguments:

kind (string) – The manifest kind.
options (RequestOptions | undefined) – Per-request options.

Returns:

The schema (draft 2020-12).

Return type:

Promise<JsonObject>

Manifests.logs(kind, name, options?)

A resource’s logs.

Arguments:

kind (string) – The manifest kind.
name (string) – The resource’s name.
options (RequestOptions | undefined) – Per-request options.

Returns:

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

Return type:

Promise<SmarterJournaledResponse<JsonObject>>

Manifests.undeploy(kind, name, options?)

Undo a resource’s deployment.

Arguments:

kind (string) – The manifest kind.
name (string) – The resource’s name.
options (RequestOptions | undefined) – Per-request options.

Returns:

The platform’s response.

Return type:

Promise<object>

Manifests.validate(manifest, options?)

Validate a manifest without applying it.

Arguments:

manifest (ManifestInput) – The manifest, in any form that Manifests.apply accepts.
options (RequestOptions | undefined) – Per-request options.

Returns:

Whether it is valid, and its errors.

Return type:

Promise<object>

class MCPClients(client)

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

Extends SmarterKindResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

MCPClients.kind

The manifest kind, e.g. Guardrail.

Type:: “MCPClient”

MCPClients.model

The schema of one resource.

Type:: object

MCPClients.path

The REST list endpoint, relative to the api’s base url, e.g. guardrails/.

Type:: “mcpclients/”

MCPClients.callTool(id, tool, args, options?)

Call one of an MCPClient’s tools. Only the owner may call tools.

Arguments:

id (SmarterId) – The MCPClient’s id or hashed id.
tool (string) – The tool’s name.
args (Record) – The tool’s arguments, as its input schema describes them.
options (RequestOptions | undefined) – Per-request options.

Returns:

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

Return type:

Promise<object>

MCPClients.refresh(id, options?)

Reconnect to an MCPClient’s server, and reload its catalog. Only the owner may refresh.

Arguments:

id (SmarterId) – The MCPClient’s id or hashed id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The connection’s state.

Return type:

Promise<object>

MCPClients.tools(id, options?)

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

Arguments:

id (SmarterId) – The MCPClient’s id or hashed id.
options (unknown | undefined) – refresh: true to read the catalog from the server now.

Returns:

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

Return type:

Promise<object>

class Orchestrators(client)

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

Extends SmarterKindResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

Orchestrators.kind

The manifest kind, e.g. Guardrail.

Type:: “Orchestrator”

Orchestrators.model

The schema of one resource.

Type:: object

Orchestrators.path

The REST list endpoint, relative to the api’s base url, e.g. guardrails/.

Type:: “orchestrators/”

class Plugins(client)

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

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

Extends SmarterKindResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

Plugins.kind

The manifest kind, e.g. Guardrail.

Type:: “Plugin”

Plugins.model

The schema of one resource.

Type:: object

Plugins.path

The REST list endpoint, relative to the api’s base url, e.g. guardrails/.

Type:: “plugins/”

Plugins.apply(manifest, options?)

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

Arguments:

manifest (ManifestInput) – The manifest.
options (RequestOptions | undefined) – Per-request options.

Returns:

The platform’s response.

Throws:

SmarterValueError – If the manifest is not a plugin’s.

Return type:

Promise<object>

Plugins.delete(name, options?)

Permanently delete a plugin.

Arguments:

name (string) – The plugin’s name.
options (RequestOptions | undefined) – Per-request options.

Returns:

The platform’s response.

Return type:

Promise<object>

Plugins.describe(name, options?)

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

Arguments:

name (string) – The plugin’s name.
options (RequestOptions | undefined) – Per-request options.

Returns:

The manifest.

Return type:

Promise<Manifest>

Plugins.kindOf(name, options?)

A plugin’s manifest kind.

Arguments:

name (string) – The plugin’s name.
options (RequestOptions | undefined) – Per-request options.

Returns:

e.g. SqlPlugin.

Return type:

Promise<string>

Plugins.retrieve(id, options?)

One plugin, by its id, from the list.

The platform’s plugins/<id>/ returns a plugin’s manifest, not the plugin, so this reads the list. See Plugins.retrieveManifest for the manifest.

Arguments:

id (SmarterId) – The plugin’s integer id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The plugin.

Throws:

ResourceNotFoundError – If the user may read no plugin of that id.

Return type:

Promise<object>

Plugins.retrieveManifest(id, options?)

One plugin’s manifest, by the plugin’s id: what the Python SDK’s plugins.retrieve() returns.

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

Arguments:

id (SmarterId) – The plugin’s id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The plugin’s manifest, whose kind is the plugin’s, e.g. SqlPlugin.

Return type:

Promise<Manifest>

class PromptHistory(client)

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

An account admin also reads the sessions of their account’s users, and a superuser every session.

Extends SmarterAPIResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

PromptHistory.path

The history’s endpoint.

Type:: “prompts/history/”

PromptHistory.pluginUsage(options?)

The plugin uses of the chat sessions.

Arguments:

options (RequestOptions | undefined) – Per-request options.

Returns:

The plugin uses.

Return type:

Promise<object[]>

PromptHistory.pluginUse(id, options?)

A plugin use, by id.

Arguments:

id (SmarterId) – The plugin use’s id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The plugin use.

Return type:

Promise<object>

PromptHistory.session(id, options?)

A chat session, by id.

Arguments:

id (SmarterId) – The session’s id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The session.

Return type:

Promise<object>

PromptHistory.sessions(options?)

The chat sessions.

Arguments:

options (RequestOptions | undefined) – Per-request options.

Returns:

The sessions.

Return type:

Promise<object[]>

PromptHistory.toolCall(id, options?)

A tool call, by id.

Arguments:

id (SmarterId) – The tool call’s id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The tool call.

Return type:

Promise<object>

PromptHistory.toolCalls(options?)

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

Arguments:

options (RequestOptions | undefined) – Per-request options.

Returns:

The tool calls.

Return type:

Promise<object[]>

class PromptStream(events, onResult?)

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

Iterate it with for await for the PromptChatApiProgressEvent events, e.g. “Calling tool calculator”. The request is sent when the iteration starts, and its connection is closed when the iteration ends, also when the loop exits early. When the stream has been read to its end, PromptStream.response is the prompt’s response, exactly as a non-streaming prompt returns it.

Arguments:

events (object) – Starts the request, and iterates its Server-Sent Events.
onResult (object | undefined) – Called with the final result event, before the iteration ends.

PromptStream.response

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

Type:: PromptResponse

PromptStream.result

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

Type:: object | undefined

PromptStream.[asyncIterator]()

Return type:: AsyncGenerator<object>

PromptStream.untilDone()

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

Returns:: The prompt’s response.
Return type:: Promise<PromptResponse>

class Providers(client)

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

Extends SmarterAPIResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

Providers.path

The providers’ endpoint.

Type:: “providers/”

Providers.list(options?)

The providers.

Arguments:

options (RequestOptions | undefined) – Per-request options.

Returns:

The providers.

Return type:

Promise<object[]>

Providers.models(name, options?)

A provider’s models.

Arguments:

name (string) – The provider’s name.
options (RequestOptions | undefined) – Per-request options.

Returns:

The models.

Return type:

Promise<object[]>

Providers.retrieve(name, options?)

A provider, by name.

Arguments:

name (string) – The provider’s name, e.g. openai.
options (RequestOptions | undefined) – Per-request options.

Returns:

The provider.

Return type:

Promise<object>

class Proxies(client)

Proxies: /api/v1/proxy/.

The platform serves these endpoints only when SMARTER_ENABLE_PROXY is true.

Extends SmarterAPIResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

Proxies.path

The proxies’ endpoint.

Type:: “proxy/”

Proxies.baseUrl(name)

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

Arguments:

name (string) – The proxy’s name, e.g. openai.

Returns:

e.g. https://platform.smarter.sh/api/v1/proxy/openai/.

Return type:

string

Proxies.list(options?)

The proxies that the user may call.

Arguments:

options (RequestOptions | undefined) – Per-request options.

Returns:

The proxies.

Return type:

Promise<object[]>

Proxies.request(name, path, options?)

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

Arguments:

name (string) – The proxy’s name, e.g. openai.
path (string) – The provider api’s path, e.g. v1/chat/completions. It must be one of the proxy’s allowedPaths.
options (ProxyRequestOptions | undefined) – method, json and params.

Returns:

The provider’s JSON response, or undefined for an empty response.

Return type:

Promise<JsonValue | undefined>

class Secrets(client)

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

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

Extends SmarterKindResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

Secrets.kind

The manifest kind, e.g. Guardrail.

Type:: “Secret”

Secrets.model

The schema of one resource.

Type:: object

Secrets.path

The REST list endpoint, relative to the api’s base url, e.g. guardrails/.

Type:: “secrets/”

class SmarterAPIResource(client)

A group of api operations.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

class SmarterKindResource(client)

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

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

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

Extends SmarterAPIResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

SmarterKindResource.kind

The manifest kind, e.g. Guardrail.

Type:: string

SmarterKindResource.model

The schema of one resource.

Type:: M

SmarterKindResource.path

The REST list endpoint, relative to the api’s base url, e.g. guardrails/.

Type:: string

SmarterKindResource.apply(manifest, options?)

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

Arguments:

manifest (ManifestInput) – The manifest.
options (RequestOptions | undefined) – Per-request options.

Returns:

The platform’s response, whose message says what was applied.

Throws:

SmarterValueError – If the manifest is of another kind.

Return type:

Promise<object>

SmarterKindResource.delete(name, options?)

Permanently delete a resource.

Arguments:

name (string) – The resource’s name.
options (RequestOptions | undefined) – Per-request options.

Returns:

The platform’s response.

Return type:

Promise<object>

SmarterKindResource.describe(name, options?)

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

Arguments:

name (string) – The resource’s name.
options (RequestOptions | undefined) – Per-request options.

Returns:

The manifest.

Return type:

Promise<Manifest>

SmarterKindResource.exampleManifest(options?)

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

Arguments:

options (RequestOptions | undefined) – Per-request options.

Returns:

The manifest.

Return type:

Promise<Manifest>

SmarterKindResource.find(name, options?)

One resource, by its name.

Arguments:

name (string) – The resource’s name.
options (RequestOptions | undefined) – Per-request options.

Returns:

The first resource of that name that the user may read.

Throws:

ResourceNotFoundError – If there is none.

Return type:

Promise<output<M>>

SmarterKindResource.jsonSchema(options?)

The JSON Schema of this kind’s manifest.

Arguments:

options (RequestOptions | undefined) – Per-request options.

Returns:

The schema.

Return type:

Promise<JsonObject>

SmarterKindResource.list(options?)

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

Arguments:

options (RequestOptions | undefined) – Per-request options.

Returns:

The resources.

Return type:

Promise<output<M>[]>

SmarterKindResource.retrieve(id, options?)

One resource, by its id or hashed id.

Arguments:

id (SmarterId) – The resource’s integer id, or its hashed id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The resource.

Throws:

NotFoundError – If it does not exist, or the user may not read it.

Return type:

Promise<output<M>>

class UserProfiles(client)

Each user’s membership of an account: /api/v1/accounts/user-profiles/.

Extends ReadOnlyResource, and has its methods.

Arguments:

client (ResourceClient) – The client.

class Users(client)

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

Extends ReadOnlyResource, and has its methods.

Arguments:

client (ResourceClient) – The client.

class Vectorsearches(client)

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

Extends SmarterKindResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

Vectorsearches.kind

The manifest kind, e.g. Guardrail.

Type:: “Vectorsearch”

Vectorsearches.model

The schema of one resource.

Type:: object

Vectorsearches.path

The REST list endpoint, relative to the api’s base url, e.g. guardrails/.

Type:: “vectorsearches/”

class Vectorstores(client)

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

The platform serves these endpoints only when SMARTER_ENABLE_VECTORSTORE is true.

Extends SmarterKindResource, and has its methods.

Arguments:

client (ResourceClient) – The client whose requests the operations send.

Vectorstores.kind

The manifest kind, e.g. Guardrail.

Type:: “Vectorstore”

Vectorstores.model

The schema of one resource.

Type:: object

Vectorstores.path

The REST list endpoint, relative to the api’s base url, e.g. guardrails/.

Type:: “vectorstores/”

Vectorstores.addFiles(id, files, options?)

Upload files as documents, e.g. PDF, Word, HTML or text files. The platform extracts their text.

Arguments:

id (SmarterId) – The vectorstore’s id or hashed id.
files (unknown) – The files: paths, file: urls, or File objects.
options (RequestOptions | undefined) – Per-request options.

Returns:

The added documents.

Return type:

Promise<object>

Vectorstores.addText(id, text, options?)

Add a text as a document.

Arguments:

id (SmarterId) – The vectorstore’s id or hashed id.
text (string) – The text.
options (unknown | undefined) – 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.

Return type:

Promise<object>

Vectorstores.addUrl(id, url, options?)

Add a public web page or file, by its url, as a document. The platform fetches it.

Arguments:

id (SmarterId) – The vectorstore’s id or hashed id.
url (string) – The url.
options (unknown | undefined) – metadata: a JSON object, stored with each of the document’s chunks.

Returns:

The added document.

Return type:

Promise<object>

Vectorstores.createSnapshot(id, options?)

Take a snapshot of a vectorstore’s data now.

Arguments:

id (SmarterId) – The vectorstore’s id or hashed id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The snapshot.

Return type:

Promise<object>

Vectorstores.deleteDocument(id, documentId, options?)

Remove a document and its chunks. The removal is asynchronous.

Arguments:

id (SmarterId) – The vectorstore’s id or hashed id.
documentId (number) – The document’s id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The document, being deleted.

Return type:

Promise<object>

Vectorstores.deploy(id, options?)

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

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

Arguments:

id (SmarterId) – The vectorstore’s id or hashed id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The vectorstore.

Return type:

Promise<object>

Vectorstores.documents(id, options?)

A vectorstore’s documents, newest first.

Arguments:

id (SmarterId) – The vectorstore’s id or hashed id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The documents.

Return type:

Promise<object>

Vectorstores.restore(id, snapshotId, options?)

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

Arguments:

id (SmarterId) – The vectorstore’s id or hashed id.
snapshotId (number) – The snapshot’s id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The restored vector count.

Return type:

Promise<object>

Vectorstores.search(id, query, options?)

Search a vectorstore.

Arguments:

id (SmarterId) – The vectorstore’s id or hashed id.
query (string) – The search text.
options (VectorstoreSearchOptions | undefined) – k, searchType, scoreThreshold, fetchK, lambdaMult and filter.

Returns:

The matching chunks, best first.

Return type:

Promise<object>

Vectorstores.snapshots(id, options?)

A vectorstore’s snapshots.

Arguments:

id (SmarterId) – The vectorstore’s id or hashed id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The snapshots.

Return type:

Promise<object>

Vectorstores.status(id, options?)

A vectorstore’s state, checked now.

Arguments:

id (SmarterId) – The vectorstore’s id or hashed id.
options (RequestOptions | undefined) – Per-request options.

Returns:

Its status and vector count.

Return type:

Promise<object>

Vectorstores.undeploy(id, options?)

Stop serving a vectorstore. A self-hosted server’s data is kept.

Arguments:

id (SmarterId) – The vectorstore’s id or hashed id.
options (RequestOptions | undefined) – Per-request options.

Returns:

The vectorstore.

Return type:

Promise<object>

kindSegment(kind)

A kind as a url path segment.

Arguments:

kind (string) – The manifest kind, e.g. LLMClient.

Returns:

The kind.

Throws:

SmarterValueError – If it is empty or not a single identifier.

Return type:

string

requestMessages(messages)

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.

Arguments:

messages (unknown) – A chat thread.

Returns:

The messages, as JSON.

Return type:

JsonValue[]

resourceId(value)

A resource id as a url path segment.

Arguments:

value (SmarterId) – The resource’s integer id, or its hashed id.

Returns:

The id, as text.

Throws:

SmarterValueError – If the id is empty, or contains a slash.

Return type:

string

toMessages(prompt)

A prompt as a list of messages.

Arguments:

prompt (PromptInput) – A user message’s text, or a list of messages.

Returns:

The messages.

Return type:

object[]

CLI_PATH

The path of the manifest api, relative to the api’s base url.

Type:: “cli/”

PLUGIN_KINDS

The manifest kinds of plugins.

Type:: unknown

class JournalListOptions()

The options of a page of the journal, beside the per-request options.

Extends RequestOptions, and has its methods.

JournalListOptions.ordering

A sort field, e.g. createdAt or -statusCode.

Type:: string | null

JournalListOptions.page

The page number, from 1.

Type:: number

JournalListOptions.pageSize

Entries per page, or none for the platform’s default.

Type:: number | null

JournalListOptions.search

Only entries whose key, thing or command contains this text.

Type:: string | null

class PromptOptions()

The options of a prompt, beside the per-request options.

Extends RequestOptions, and has its methods.

PromptOptions.sessionKey

The chat session’s key, from LLMClients.config, to keep the prompt’s history in that session.

Type:: string | null

class ProxyRequestOptions()

The options of a proxied request, beside the per-request options.

Extends RequestOptions, and has its methods.

ProxyRequestOptions.json

The JSON body, as the provider’s api expects it.

Type:: JsonValue

ProxyRequestOptions.method

The http method, POST by default.

Type:: string

ProxyRequestOptions.params

Query parameters.

Type:: Record<string, QueryParamValue>

class VectorstoreSearchOptions()

The options of a vectorstore search, beside the per-request options.

Extends RequestOptions, and has its methods.

VectorstoreSearchOptions.fetchK

How many chunks mmr considers.

Type:: number | null

VectorstoreSearchOptions.filter

Only chunks whose metadata match.

Type:: Record<string, JsonValue> | null

VectorstoreSearchOptions.k

How many chunks to return, 4 by default. The platform caps it.

Type:: number

VectorstoreSearchOptions.lambdaMult

mmr’s balance of relevance (1) and diversity (0).

Type:: number | null

VectorstoreSearchOptions.scoreThreshold

The minimum score, for similarity_score_threshold.

Type:: number | null

VectorstoreSearchOptions.searchType

similarity (the default), mmr (maximal marginal relevance), or similarity_score_threshold.

Type:: VectorstoreSearchType

GuardrailStage

The stage of a prompt that a Guardrail runs on: the prompt (input) or the LLM’s reply (output).

Type:: “input” | “output”

MessageInput

A message: a PromptChatApiMessage, e.g. { role: "user", content: "Hi" }.

Type:: PromptChatApiMessage

PromptInput

A prompt: the text of one user message, or a list of messages.

Type:: string | unknown

UploadInput

A file to upload: its path, its file: url, or a File.

Type:: string | URL | File

VectorstoreSearchType

How a vectorstore search ranks chunks.

Type:: “similarity” | “mmr” | “similarity_score_threshold”