The Smarter Python SDK

smarter-api is the official Python SDK of the Smarter platform. It is to Smarter what the openai package is to the OpenAI api: one pip install gives your Python software typed, complete access to your own Smarter installation, whether it runs on your laptop or on Kubernetes.

Use it to build custom software that is tightly integrated with your Smarter resources and functionality, without customizing or forking the Smarter backend: a web application that chats with your LLMClients, a CI job that applies your manifests, a data pipeline that loads documents into a vectorstore, or a service that calls your MCP servers' tools.

from smarter import Smarter

client = Smarter()  # SMARTER_API_KEY, or the smarter cli's ~/.smarter/config.yaml

llmclient = client.llm_clients.find("customer_support")
response = client.llm_clients.prompt(llmclient.id, "Where is my order #1234?")
print(response.text)

Smarter Python SDK or Smarter CLI?

Both manage the same resources through the same api. The difference is how you use them:

The SDK reads the cli's configuration file, so if you have run smarter configure, the SDK needs no other setup.

At a Glance

• Every resource kind, through the same manifest api as the cli: apply, validate, get, describe, delete, deploy, undeploy and logs, for LLMClients, Plugins, Guardrails, MCPClients, Vectorstores, LLMHosts, Secrets, Custom Domains, Accounts, Users, and every other kind.
• Prompts and conversations: prompt an LLMClient, hold a multi-turn chat that keeps its session, and stream a prompt's progress (its LLM requests, tool calls and MCP calls) as it runs.
• Resource actions: evaluate a Guardrail, call an MCP server's tools, add documents to and search a vectorstore, plan and deploy an LLMHost, discover open-weight models, and call an LLM provider through a Proxy.
• The platform's own Pydantic models: a typed model of every SAM manifest kind (e.g. SAMLLMClient), the Smarter Chat api contract (e.g. PromptChatApiConfig), the Smarter Journal contract, and the Django-React integration contract, kept in step with the platform by tests.
• Production behavior: retries with backoff, timeouts, typed exceptions, logging that never prints your api key, and a py.typed package for your type checker.

Quickstart

pip install smarter-api

Point the SDK at your platform with environment variables, or pass them as arguments to Smarter(...):

export SMARTER_API_KEY="your 64-character Smarter api key"
export SMARTER_BASE_URL="https://platform.example.com"   # or http://localhost:9357

Manifests

from smarter import Smarter

client = Smarter()

client.manifests.apply("pii-redactor.yaml")                    # create or update
manifest = client.guardrails.describe("pii_redactor")          # read it back
guardrail = manifest.to_sam()                                  # as a typed SAMGuardrail
print(guardrail.spec.config.action)
client.guardrails.delete("pii_redactor")

Chat

chat = client.llm_clients.chat(llmclient.id)
print(chat.send("What is 2 to the 10th power?").text)
print(chat.send("And divided by 4?").text)

with chat.stream("Now take its square root.") as stream:
    for event in stream:
        print("...", event.message)     # e.g. "Calling tool calculator"
    print(stream.response.text)

Errors

from smarter import NotFoundError, SmarterError

try:
    client.manifests.describe("LLMClient", "no_such_client")
except NotFoundError as e:
    print(e.status_code, e.message, e.error_class)
except SmarterError as e:
    print("something else went wrong:", e)

Documentation

Read the Docs: The Smarter Python SDK on docs.smarter.sh.

Requirements

Python 3.10 or later, and a Smarter platform to connect to. See the Quick Start Guide to run one on your laptop.

Development

make init        # a virtual environment, with the development requirements and pre-commit
make test        # the unit tests, which never reach a platform
make coverage    # the unit tests, with a coverage report
SMARTER_BASE_URL=http://localhost:9357 SMARTER_API_KEY=... make test-live

The agent skills in skills/ describe how this repository is developed, tested and documented, for people and for AI coding agents.

Support

Please report bugs to the GitHub Issues Page for this project.

Contributing

Please see the CONTRIBUTING.