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)Documentation: https://docs.smarter-python.smarter.sh/
smarter-python is part of The Smarter Project.
Both manage the same resources through the same api. The difference is how you use them:
| smarter-python (this package) | smarter-cli |
|---|---|
| A Python library that you import into your own software. | A program that you install on your computer. |
client.manifests.apply("guardrail.yaml") |
smarter apply -f guardrail.yaml |
| Returns typed Pydantic models, and raises typed exceptions. | Prints JSON or YAML in a terminal window. |
| For applications, services, notebooks, tests and automation. | For people at a keyboard, and shell scripts. |
The SDK reads the cli's configuration file, so if you have run
smarter configure, the SDK needs no other setup.
- Every resource kind, through the same manifest api as the cli:
apply,validate,get,describe,delete,deploy,undeployandlogs, 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.typedpackage for your type checker.
pip install smarter-apiPoint 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:9357from 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 = 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)client.llm_clients.config(llmclient.id) returns the chat configuration that a
session starts with. It has what a chat needs, and only the counts of the
LLMClient's plugins and extensions. Pass verbose=True for the complete
configuration, with their lists and the session's tool calls.
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)The SDK's documentation is at https://docs.smarter-python.smarter.sh/: the user guide, the api reference generated from its docstrings, and its architecture decision records. The platform's own documentation is at docs.smarter.sh.
Python 3.10 or later, and a Smarter platform to connect to. See the Quick Start Guide to run one on your laptop.
make # list every command
make init # create venv/ from requirements/local.txt, install the package and the git hooks
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
make lint # run the pre-commit hooks on every file
make sphinx-build # build the Sphinx docs into docs/build/html
make sphinx-publish # publish them to docs.smarter-python.smarter.sh (releases do it themselves)
make build # build the sdist and wheel, and check them
make python-requirements # recompile the pinned requirements/*.txtCI runs the hooks, the unit tests on every supported Python version, the docs
build and a package build, on every pull request, and on every push to main,
alpha and beta as the first step of the Release workflow. Coverage is
reported to Codecov. When CI
passes, the Release workflow releases with semantic-release, from the
conventional commit messages, and publishes to PyPI from main (or to TestPyPI
from alpha and beta). Once PyPI has a release from main, the same
workflow publishes its documentation to docs.smarter-python.smarter.sh.
make release-dry-run shows the next version.
The agent skills in skills/ describe how this repository is developed, tested and documented, for people and for AI coding agents.
Please report bugs to the GitHub Issues Page for this project.
Please see the CONTRIBUTING.