Developing the SDK

The SDK’s source is github.com/smarter-sh/smarter-python. It follows the platform’s practices and architecture decisions: the same pre-commit hooks, reStructuredText docstrings, semantic versioning and conventional commits. Its own decisions are recorded in its doc/adr/ folder, and its Agent Skills in skills/ describe how it is developed, for people and for AI coding agents.

git clone https://github.com/smarter-sh/smarter-python.git
cd smarter-python
make init                     # a virtual environment, development requirements and pre-commit
make test                     # the unit tests
make coverage                 # with a coverage report

Tests

The unit tests never reach a platform: an httpx mock transport answers every request, with sanitized copies of real platform responses. They run in CI on every supported Python version, which also checks that coverage stays at 90% or more.

The live tests check the SDK against a running platform. They validate every model against real responses, including a describe of a real resource of every kind, parsed as its SAM model. They prompt an LLMClient, which makes billable LLM requests, and they never deploy anything.

SMARTER_BASE_URL=http://localhost:9357 SMARTER_API_KEY=<api key> make test-live

Keeping in step with the platform

Three things are copied from the platform, and each has a command that refreshes it:

Command	What it refreshes
`make sam-models`	The SAM models, generated from a running platform’s JSON Schemas, and the schemas and example manifests that their tests use.
`make contracts`	The chat and journal contracts’ JSON Schemas and examples, from a checkout of the platform beside the SDK (`../smarter`).
`python scripts/generate_reference.py`	The SDK’s API reference pages in the platform’s documentation.

When the platform changes a contract or a manifest kind, refresh, run the tests, and fix what they find.

The SDK’s API reference

The platform’s documentation autodocs the platform’s own smarter package, and the SDK’s import name is smarter too, so the documentation build can’t import the SDK. Its reference pages are generated instead, from the SDK’s docstrings, as Sphinx directives that need no import. Don’t edit them: change the docstring, and regenerate.