Resources
=========

.. This page is generated by smarter-nodejs's scripts/generate-reference.ts. Do not edit it.

The client's resource families, e.g. ``client.guardrails``. Every method returns a promise. See :doc:`../resources`.

.. js:class:: AccountContacts(client)

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

   Extends ``ReadOnlyResource``, and has its methods.

   :param client: The client.
   :type client: ResourceClient

.. js:class:: Accounts(client)

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

   Extends ``SmarterKindResource``, and has its methods.

   :param client: The client.
   :type client: unknown

   .. js:attribute:: contacts

      The account's contacts.

      :type: AccountContacts

   .. js:attribute:: kind

      The manifest kind, e.g. ``Guardrail``.

      :type: "Account"

   .. js:attribute:: model

      The schema of one resource.

      :type: object

   .. js:attribute:: path

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

      :type: "accounts/"

   .. js:attribute:: userProfiles

      The users' memberships of accounts.

      :type: UserProfiles

   .. js:attribute:: users

      The account's users.

      :type: Users

.. js: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``.

   :param llmclients: The LLMClients resource.
   :type llmclients: LLMClients
   :param llmclientId: The LLMClient's id or hashed id.
   :type llmclientId: SmarterId
   :param config: The chat session's configuration.
   :type config: object

   .. js:attribute:: config

      The chat session's configuration.

      :type: object

   .. js:attribute:: llmclientId

      The LLMClient's id or hashed id.

      :type: SmarterId

   .. js:attribute:: messages

      The chat thread.

      :type: object[]

   .. js:attribute:: sessionKey

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

      :type: string

   .. js:method:: send(content, options?)

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

      :param content: A user message's text, or a message.
      :type content: string | object
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The prompt's response. ``text`` is the LLM's reply.
      :rtype: Promise<PromptResponse>

   .. js:method:: 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.

      :param content: A user message's text, or a message.
      :type content: string | object
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The stream.
      :rtype: ChatStream

.. js: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.

   :param events: Starts the request, and iterates its Server-Sent Events.
   :type events: object
   :param onMessages: Called with a successful prompt's messages.
   :type onMessages: object

.. js:class:: Guardrails(client)

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

   Extends ``SmarterKindResource``, and has its methods.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:attribute:: kind

      The manifest kind, e.g. ``Guardrail``.

      :type: "Guardrail"

   .. js:attribute:: model

      The schema of one resource.

      :type: object

   .. js:attribute:: path

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

      :type: "guardrails/"

   .. js:method:: evaluate(id, text, options?)

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

      :param id: The Guardrail's id or hashed id.
      :type id: SmarterId
      :param text: The text, e.g. a prompt (``input``) or an LLM's reply (``output``).
      :type text: string
      :param options: ``stage``: the stage to evaluate the text as, ``input`` by default. The Guardrail must run on it.
      :type options: unknown | undefined
      :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.
      :rtype: Promise<object>

   .. js:method:: events(id, options?)

      The latest events of a Guardrail that the user owns.

      :param id: The Guardrail's id or hashed id.
      :type id: SmarterId
      :param options: ``reviewed``: only reviewed (true) or unreviewed (false) events. ``disposition``: only events of this disposition, e.g. ``blocked``.
      :type options: unknown | undefined
      :returns: The events, newest first.
      :rtype: Promise<object>

.. js: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.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:attribute:: path

      The journal's endpoint.

      :type: "journal/"

   .. js:method:: list(options?)

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

      :param options: ``page``, ``pageSize``, ``search`` and ``ordering``.
      :type options: JournalListOptions | undefined
      :returns: The page, and its pagination.
      :rtype: Promise<object>

   .. js:method:: retrieve(key, options?)

      A journal entry, with its request and response documents.

      :param key: The entry's key: the ``metadata.key`` of a journaled response.
      :type key: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The entry.
      :rtype: Promise<object>

.. js:class:: LLMClients(client)

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

   Extends ``SmarterKindResource``, and has its methods.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:attribute:: kind

      The manifest kind, e.g. ``Guardrail``.

      :type: "LLMClient"

   .. js:attribute:: model

      The schema of one resource.

      :type: object

   .. js:attribute:: path

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

      :type: "llm-clients/"

   .. js:method:: apiKeys(id, options?)

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

      :param id: The LLMClient's integer id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The api keys.
      :rtype: Promise<object[]>

   .. js:method:: chat(id, options?)

      Start or resume a conversation with an LLMClient.

      :param id: The LLMClient's id or hashed id.
      :type id: SmarterId
      :param options: ``sessionKey``: an existing session's key, to resume it, or none for a new session.
      :type options: PromptOptions | undefined
      :returns: The chat session.
      :rtype: Promise<ChatSession>

   .. js:method:: config(id, options?)

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

      :param id: The LLMClient's id or hashed id.
      :type id: SmarterId
      :param options: ``sessionKey``: an existing session's key, to resume it with its history, or none for a new session.
      :type options: PromptOptions | undefined
      :returns: The configuration, whose ``session_key`` identifies the session.
      :rtype: Promise<object>

   .. js:method:: customDomains(id, options?)

      The custom domains of an LLMClient.

      :param id: The LLMClient's integer id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The custom domains.
      :rtype: Promise<object[]>

   .. js:method:: 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.

      :param name: The LLMClient's name.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The platform's response.
      :rtype: Promise<object>

   .. js:method:: events(id, prompt, options?)

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

      :param id: The LLMClient's id or hashed id.
      :type id: SmarterId
      :param prompt: The prompt.
      :type prompt: PromptInput
      :param options: ``sessionKey``, and per-request options.
      :type options: PromptOptions | undefined
      :returns: A function that starts the request.
      :rtype: object

   .. js:method:: functions(id, options?)

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

      :param id: The LLMClient's integer id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The functions.
      :rtype: Promise<object[]>

   .. js:method:: plugins(id, options?)

      An LLMClient's plugins.

      :param id: The LLMClient's integer id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The plugins.
      :rtype: Promise<object[]>

   .. js:method:: 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.

      :param id: The LLMClient's id or hashed id.
      :type id: SmarterId
      :param prompt: The text of one user message, or the chat thread as a list of messages.
      :type prompt: PromptInput
      :param options: ``sessionKey``, the chat session's key, and per-request options.
      :type options: PromptOptions | undefined
      :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.
      :rtype: Promise<PromptResponse>

   .. js:method:: stream(id, prompt, options?)

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

      :param id: The LLMClient's id or hashed id.
      :type id: SmarterId
      :param prompt: The text of one user message, or the chat thread as a list of messages.
      :type prompt: PromptInput
      :param options: ``sessionKey``, and per-request options. The timeout applies to each event.
      :type options: PromptOptions | undefined
      :returns: The stream. Iterate it with ``for await`` for the progress events.
      :rtype: PromptStream

   .. js:method:: undeploy(name, options?)

      Undo an LLMClient's deployment.

      :param name: The LLMClient's name.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The platform's response.
      :rtype: Promise<object>

.. js:class:: LLMHosts(client)

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

   Extends ``SmarterKindResource``, and has its methods.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:attribute:: kind

      The manifest kind, e.g. ``Guardrail``.

      :type: "LLMHost"

   .. js:attribute:: model

      The schema of one resource.

      :type: object

   .. js:attribute:: path

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

      :type: "llmhosts/"

   .. js:method:: deploy(id, options?)

      Deploy an LLMHost on the platform's cluster.

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

      :param id: The LLMHost's id or hashed id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: Its state.
      :rtype: Promise<object>

   .. js:method:: discover(options?)

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

      :param options: ``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.
      :type options: unknown | undefined
      :returns: The models, each with the LLMHost manifest that would serve it.
      :rtype: Promise<object[]>

   .. js:method:: discoverManifest(repository, options?)

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

      :param repository: The model's repository, e.g. ``Qwen/Qwen2.5-7B-Instruct``.
      :type repository: string
      :param options: ``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.
      :type options: unknown | undefined
      :returns: The manifest, which ``LLMHosts.apply`` accepts.
      :rtype: Promise<Manifest>

   .. js:method:: logs(id, options?)

      The latest log lines of an LLMHost's pods.

      :param id: The LLMHost's id or hashed id.
      :type id: SmarterId
      :param options: ``tail``: how many lines, 200 by default.
      :type options: unknown | undefined
      :returns: The logs.
      :rtype: Promise<object>

   .. js:method:: plan(id, options?)

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

      :param id: The LLMHost's id or hashed id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The resources.
      :rtype: Promise<object>

   .. js:method:: report(options?)

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

      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The report.
      :rtype: Promise<object>

   .. js:method:: status(id, options?)

      An LLMHost's state, read from Kubernetes now.

      :param id: The LLMHost's id or hashed id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: Its status, replicas and pods.
      :rtype: Promise<object>

   .. js:method:: undeploy(id, options?)

      Undeploy an LLMHost.

      :param id: The LLMHost's id or hashed id.
      :type id: SmarterId
      :param options: ``purge``: true to delete its model storage too.
      :type options: unknown | undefined
      :returns: Its state.
      :rtype: Promise<object>

.. js:class:: Manifests(client)

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

   Extends ``SmarterAPIResource``, and has its methods.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:method:: 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.

      :param manifest: The manifest: a ``Manifest``, an object, YAML text, or the path of a YAML file.
      :type manifest: ManifestInput
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The platform's response, whose ``message`` says what was applied.
      :throws BadRequestError: If the platform rejects the manifest.
      :rtype: Promise<object>

   .. js:method:: delete(kind, name, options?)

      Permanently delete a resource.

      :param kind: The manifest kind.
      :type kind: string
      :param name: The resource's name.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The platform's response.
      :throws NotFoundError: If the resource does not exist.
      :rtype: Promise<object>

   .. js:method:: 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.

      :param kind: The manifest kind of a deployable resource. See ``client.kinds()``.
      :type kind: string
      :param name: The resource's name.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The platform's response.
      :rtype: Promise<object>

   .. js:method:: describe(kind, name, options?)

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

      :param kind: The manifest kind.
      :type kind: string
      :param name: The resource's name.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The manifest, which ``Manifests.apply`` accepts as is.
      :throws NotFoundError: If the resource does not exist.
      :rtype: Promise<Manifest>

   .. js:method:: exampleManifest(kind, options?)

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

      :param kind: The manifest kind.
      :type kind: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The manifest.
      :rtype: Promise<Manifest>

   .. js:method:: get(kind, name?, options?)

      The resources of one kind, as a table.

      :param kind: The manifest kind, e.g. ``LLMClient``.
      :type kind: string
      :param name: Only the resource of this name.
      :type name: string | null | undefined
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The table: ``data.items`` are its rows, and ``names`` the resources' names.
      :rtype: Promise<ManifestTable>

   .. js:method:: jsonSchema(kind, options?)

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

      :param kind: The manifest kind.
      :type kind: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The schema (draft 2020-12).
      :rtype: Promise<JsonObject>

   .. js:method:: logs(kind, name, options?)

      A resource's logs.

      :param kind: The manifest kind.
      :type kind: string
      :param name: The resource's name.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The platform's response: its ``message``, and its ``data`` for the kinds that have logs.
      :rtype: Promise<SmarterJournaledResponse<JsonObject>>

   .. js:method:: undeploy(kind, name, options?)

      Undo a resource's deployment.

      :param kind: The manifest kind.
      :type kind: string
      :param name: The resource's name.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The platform's response.
      :rtype: Promise<object>

   .. js:method:: validate(manifest, options?)

      Validate a manifest without applying it.

      :param manifest: The manifest, in any form that ``Manifests.apply`` accepts.
      :type manifest: ManifestInput
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: Whether it is valid, and its errors.
      :rtype: Promise<object>

.. js:class:: MCPClients(client)

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

   Extends ``SmarterKindResource``, and has its methods.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:attribute:: kind

      The manifest kind, e.g. ``Guardrail``.

      :type: "MCPClient"

   .. js:attribute:: model

      The schema of one resource.

      :type: object

   .. js:attribute:: path

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

      :type: "mcpclients/"

   .. js:method:: callTool(id, tool, args, options?)

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

      :param id: The MCPClient's id or hashed id.
      :type id: SmarterId
      :param tool: The tool's name.
      :type tool: string
      :param args: The tool's arguments, as its input schema describes them.
      :type args: Record<string, JsonValue>
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The tool's result. Check ``isError``: a tool reports its own failures in its result.
      :rtype: Promise<object>

   .. js:method:: refresh(id, options?)

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

      :param id: The MCPClient's id or hashed id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The connection's state.
      :rtype: Promise<object>

   .. js:method:: tools(id, options?)

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

      :param id: The MCPClient's id or hashed id.
      :type id: SmarterId
      :param options: ``refresh``: true to read the catalog from the server now.
      :type options: unknown | undefined
      :returns: The connection's state, the server's instructions, and the tools.
      :rtype: Promise<object>

.. js:class:: Orchestrators(client)

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

   Extends ``SmarterKindResource``, and has its methods.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:attribute:: kind

      The manifest kind, e.g. ``Guardrail``.

      :type: "Orchestrator"

   .. js:attribute:: model

      The schema of one resource.

      :type: object

   .. js:attribute:: path

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

      :type: "orchestrators/"

.. js: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.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:attribute:: kind

      The manifest kind, e.g. ``Guardrail``.

      :type: "Plugin"

   .. js:attribute:: model

      The schema of one resource.

      :type: object

   .. js:attribute:: path

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

      :type: "plugins/"

   .. js:method:: apply(manifest, options?)

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

      :param manifest: The manifest.
      :type manifest: ManifestInput
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The platform's response.
      :throws SmarterValueError: If the manifest is not a plugin's.
      :rtype: Promise<object>

   .. js:method:: delete(name, options?)

      Permanently delete a plugin.

      :param name: The plugin's name.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The platform's response.
      :rtype: Promise<object>

   .. js:method:: describe(name, options?)

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

      :param name: The plugin's name.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The manifest.
      :rtype: Promise<Manifest>

   .. js:method:: kindOf(name, options?)

      A plugin's manifest kind.

      :param name: The plugin's name.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: e.g. ``SqlPlugin``.
      :rtype: Promise<string>

   .. js:method:: 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.

      :param id: The plugin's integer id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The plugin.
      :throws ResourceNotFoundError: If the user may read no plugin of that id.
      :rtype: Promise<object>

   .. js:method:: 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.

      :param id: The plugin's id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The plugin's manifest, whose ``kind`` is the plugin's, e.g. ``SqlPlugin``.
      :rtype: Promise<Manifest>

.. js: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.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:attribute:: path

      The history's endpoint.

      :type: "prompts/history/"

   .. js:method:: pluginUsage(options?)

      The plugin uses of the chat sessions.

      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The plugin uses.
      :rtype: Promise<object[]>

   .. js:method:: pluginUse(id, options?)

      A plugin use, by id.

      :param id: The plugin use's id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The plugin use.
      :rtype: Promise<object>

   .. js:method:: session(id, options?)

      A chat session, by id.

      :param id: The session's id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The session.
      :rtype: Promise<object>

   .. js:method:: sessions(options?)

      The chat sessions.

      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The sessions.
      :rtype: Promise<object[]>

   .. js:method:: toolCall(id, options?)

      A tool call, by id.

      :param id: The tool call's id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The tool call.
      :rtype: Promise<object>

   .. js:method:: toolCalls(options?)

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

      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The tool calls.
      :rtype: Promise<object[]>

.. js: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.

   :param events: Starts the request, and iterates its Server-Sent Events.
   :type events: object
   :param onResult: Called with the final ``result`` event, before the iteration ends.
   :type onResult: object | undefined

   .. js:attribute:: response

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

      :type: PromptResponse

   .. js:attribute:: result

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

      :type: object | undefined

   .. js:method:: [asyncIterator]()

      :rtype: AsyncGenerator<object>

   .. js:method:: untilDone()

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

      :returns: The prompt's response.
      :rtype: Promise<PromptResponse>

.. js:class:: Providers(client)

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

   Extends ``SmarterAPIResource``, and has its methods.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:attribute:: path

      The providers' endpoint.

      :type: "providers/"

   .. js:method:: list(options?)

      The providers.

      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The providers.
      :rtype: Promise<object[]>

   .. js:method:: models(name, options?)

      A provider's models.

      :param name: The provider's name.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The models.
      :rtype: Promise<object[]>

   .. js:method:: retrieve(name, options?)

      A provider, by name.

      :param name: The provider's name, e.g. ``openai``.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The provider.
      :rtype: Promise<object>

.. js: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.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:attribute:: path

      The proxies' endpoint.

      :type: "proxy/"

   .. js:method:: baseUrl(name)

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

      :param name: The proxy's name, e.g. ``openai``.
      :type name: string
      :returns: e.g. ``https://platform.smarter.sh/api/v1/proxy/openai/``.
      :rtype: string

   .. js:method:: list(options?)

      The proxies that the user may call.

      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The proxies.
      :rtype: Promise<object[]>

   .. js:method:: request(name, path, options?)

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

      :param name: The proxy's name, e.g. ``openai``.
      :type name: string
      :param path: The provider api's path, e.g. ``v1/chat/completions``. It must be one of the proxy's ``allowedPaths``.
      :type path: string
      :param options: ``method``, ``json`` and ``params``.
      :type options: ProxyRequestOptions | undefined
      :returns: The provider's JSON response, or undefined for an empty response.
      :rtype: Promise<JsonValue | undefined>

.. js: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.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:attribute:: kind

      The manifest kind, e.g. ``Guardrail``.

      :type: "Secret"

   .. js:attribute:: model

      The schema of one resource.

      :type: object

   .. js:attribute:: path

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

      :type: "secrets/"

.. js:class:: SmarterAPIResource(client)

   A group of api operations.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

.. js: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.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:attribute:: kind

      The manifest kind, e.g. ``Guardrail``.

      :type: string

   .. js:attribute:: model

      The schema of one resource.

      :type: M

   .. js:attribute:: path

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

      :type: string

   .. js:method:: apply(manifest, options?)

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

      :param manifest: The manifest.
      :type manifest: ManifestInput
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The platform's response, whose ``message`` says what was applied.
      :throws SmarterValueError: If the manifest is of another kind.
      :rtype: Promise<object>

   .. js:method:: delete(name, options?)

      Permanently delete a resource.

      :param name: The resource's name.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The platform's response.
      :rtype: Promise<object>

   .. js:method:: describe(name, options?)

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

      :param name: The resource's name.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The manifest.
      :rtype: Promise<Manifest>

   .. js:method:: exampleManifest(options?)

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

      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The manifest.
      :rtype: Promise<Manifest>

   .. js:method:: find(name, options?)

      One resource, by its name.

      :param name: The resource's name.
      :type name: string
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The first resource of that name that the user may read.
      :throws ResourceNotFoundError: If there is none.
      :rtype: Promise<output<M>>

   .. js:method:: jsonSchema(options?)

      The JSON Schema of this kind's manifest.

      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The schema.
      :rtype: Promise<JsonObject>

   .. js:method:: list(options?)

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

      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The resources.
      :rtype: Promise<output<M>[]>

   .. js:method:: retrieve(id, options?)

      One resource, by its id or hashed id.

      :param id: The resource's integer id, or its hashed id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The resource.
      :throws NotFoundError: If it does not exist, or the user may not read it.
      :rtype: Promise<output<M>>

.. js:class:: UserProfiles(client)

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

   Extends ``ReadOnlyResource``, and has its methods.

   :param client: The client.
   :type client: ResourceClient

.. js:class:: Users(client)

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

   Extends ``ReadOnlyResource``, and has its methods.

   :param client: The client.
   :type client: ResourceClient

.. js:class:: Vectorsearches(client)

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

   Extends ``SmarterKindResource``, and has its methods.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:attribute:: kind

      The manifest kind, e.g. ``Guardrail``.

      :type: "Vectorsearch"

   .. js:attribute:: model

      The schema of one resource.

      :type: object

   .. js:attribute:: path

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

      :type: "vectorsearches/"

.. js: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.

   :param client: The client whose requests the operations send.
   :type client: ResourceClient

   .. js:attribute:: kind

      The manifest kind, e.g. ``Guardrail``.

      :type: "Vectorstore"

   .. js:attribute:: model

      The schema of one resource.

      :type: object

   .. js:attribute:: path

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

      :type: "vectorstores/"

   .. js:method:: addFiles(id, files, options?)

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

      :param id: The vectorstore's id or hashed id.
      :type id: SmarterId
      :param files: The files: paths, ``file:`` urls, or ``File`` objects.
      :type files: unknown
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The added documents.
      :rtype: Promise<object>

   .. js:method:: addText(id, text, options?)

      Add a text as a document.

      :param id: The vectorstore's id or hashed id.
      :type id: SmarterId
      :param text: The text.
      :type text: string
      :param options: ``name``: the document's name. ``metadata``: a JSON object, stored with each of the document's chunks.
      :type options: unknown | undefined
      :returns: The added document. It is loaded asynchronously, once the vectorstore is deployed.
      :rtype: Promise<object>

   .. js:method:: addUrl(id, url, options?)

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

      :param id: The vectorstore's id or hashed id.
      :type id: SmarterId
      :param url: The url.
      :type url: string
      :param options: ``metadata``: a JSON object, stored with each of the document's chunks.
      :type options: unknown | undefined
      :returns: The added document.
      :rtype: Promise<object>

   .. js:method:: createSnapshot(id, options?)

      Take a snapshot of a vectorstore's data now.

      :param id: The vectorstore's id or hashed id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The snapshot.
      :rtype: Promise<object>

   .. js:method:: deleteDocument(id, documentId, options?)

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

      :param id: The vectorstore's id or hashed id.
      :type id: SmarterId
      :param documentId: The document's id.
      :type documentId: number
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The document, being deleted.
      :rtype: Promise<object>

   .. js:method:: 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.

      :param id: The vectorstore's id or hashed id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The vectorstore.
      :rtype: Promise<object>

   .. js:method:: documents(id, options?)

      A vectorstore's documents, newest first.

      :param id: The vectorstore's id or hashed id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The documents.
      :rtype: Promise<object>

   .. js:method:: restore(id, snapshotId, options?)

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

      :param id: The vectorstore's id or hashed id.
      :type id: SmarterId
      :param snapshotId: The snapshot's id.
      :type snapshotId: number
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The restored vector count.
      :rtype: Promise<object>

   .. js:method:: search(id, query, options?)

      Search a vectorstore.

      :param id: The vectorstore's id or hashed id.
      :type id: SmarterId
      :param query: The search text.
      :type query: string
      :param options: ``k``, ``searchType``, ``scoreThreshold``, ``fetchK``, ``lambdaMult`` and ``filter``.
      :type options: VectorstoreSearchOptions | undefined
      :returns: The matching chunks, best first.
      :rtype: Promise<object>

   .. js:method:: snapshots(id, options?)

      A vectorstore's snapshots.

      :param id: The vectorstore's id or hashed id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The snapshots.
      :rtype: Promise<object>

   .. js:method:: status(id, options?)

      A vectorstore's state, checked now.

      :param id: The vectorstore's id or hashed id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: Its status and vector count.
      :rtype: Promise<object>

   .. js:method:: undeploy(id, options?)

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

      :param id: The vectorstore's id or hashed id.
      :type id: SmarterId
      :param options: Per-request options.
      :type options: RequestOptions | undefined
      :returns: The vectorstore.
      :rtype: Promise<object>

.. js:function:: kindSegment(kind)

   A kind as a url path segment.

   :param kind: The manifest kind, e.g. ``LLMClient``.
   :type kind: string
   :returns: The kind.
   :throws SmarterValueError: If it is empty or not a single identifier.
   :rtype: string

.. js:function:: 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.

   :param messages: A chat thread.
   :type messages: unknown
   :returns: The messages, as JSON.
   :rtype: JsonValue[]

.. js:function:: resourceId(value)

   A resource id as a url path segment.

   :param value: The resource's integer id, or its hashed id.
   :type value: SmarterId
   :returns: The id, as text.
   :throws SmarterValueError: If the id is empty, or contains a slash.
   :rtype: string

.. js:function:: toMessages(prompt)

   A prompt as a list of messages.

   :param prompt: A user message's text, or a list of messages.
   :type prompt: PromptInput
   :returns: The messages.
   :rtype: object[]

.. js:data:: CLI_PATH

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

   :type: "cli/"

.. js:data:: PLUGIN_KINDS

   The manifest kinds of plugins.

   :type: unknown

.. js:class:: JournalListOptions

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

   Extends ``RequestOptions``, and has its methods.

   .. js:attribute:: ordering

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

      :type: string | null

   .. js:attribute:: page

      The page number, from 1.

      :type: number

   .. js:attribute:: pageSize

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

      :type: number | null

   .. js:attribute:: search

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

      :type: string | null

.. js:class:: PromptOptions

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

   Extends ``RequestOptions``, and has its methods.

   .. js:attribute:: sessionKey

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

      :type: string | null

.. js:class:: ProxyRequestOptions

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

   Extends ``RequestOptions``, and has its methods.

   .. js:attribute:: json

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

      :type: JsonValue

   .. js:attribute:: method

      The http method, ``POST`` by default.

      :type: string

   .. js:attribute:: params

      Query parameters.

      :type: Record<string, QueryParamValue>

.. js:class:: VectorstoreSearchOptions

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

   Extends ``RequestOptions``, and has its methods.

   .. js:attribute:: fetchK

      How many chunks ``mmr`` considers.

      :type: number | null

   .. js:attribute:: filter

      Only chunks whose metadata match.

      :type: Record<string, JsonValue> | null

   .. js:attribute:: k

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

      :type: number

   .. js:attribute:: lambdaMult

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

      :type: number | null

   .. js:attribute:: scoreThreshold

      The minimum score, for ``similarity_score_threshold``.

      :type: number | null

   .. js:attribute:: searchType

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

      :type: VectorstoreSearchType

.. js:data:: GuardrailStage

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

   :type: "input" | "output"

.. js:data:: MessageInput

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

   :type: PromptChatApiMessage

.. js:data:: PromptInput

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

   :type: string | unknown

.. js:data:: UploadInput

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

   :type: string | URL | File

.. js:data:: VectorstoreSearchType

   How a vectorstore search ranks chunks.

   :type: "similarity" | "mmr" | "similarity_score_threshold"