Metadata-Version: 2.4
Name: smarter-api
Version: 0.4.0
Summary: The official Python SDK of the Smarter platform's api.
Home-page: https://github.com/smarter-sh/smarter-python/
Author: Lawrence McDaniel
Author-email: lpm0073@gmail.com
Maintainer: Lawrence McDaniel
Maintainer-email: lpm0073@gmail.com
License: AGPL-3.0-or-later
Project-URL: Source, https://github.com/smarter-sh/smarter-python
Project-URL: Documentation, https://docs.smarter.sh/en/latest/smarter-framework/smarter-python.html
Project-URL: Changelog, https://github.com/smarter-sh/smarter-python/blob/main/CHANGELOG.md
Project-URL: Security, https://github.com/smarter-sh/smarter-python/blob/main/SECURITY.md
Project-URL: Code of Conduct, https://github.com/smarter-sh/smarter-python/blob/main/CODE_OF_CONDUCT.md
Project-URL: Tracker, https://github.com/smarter-sh/smarter-python/issues
Keywords: smarter,sdk,api,llm,ai,agents,manifests
Platform: any
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: pydantic-settings<3,>=2.3
Requires-Dist: PyYAML<7,>=6.0
Requires-Dist: email-validator<3,>=2.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: platform
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# The Smarter Python SDK

![Build Status](https://github.com/smarter-sh/smarter-python/actions/workflows/build.yml/badge.svg?branch=main)
![Test Status](https://github.com/smarter-sh/smarter-python/actions/workflows/test.yml/badge.svg?branch=main)
[![Python coverage](https://img.shields.io/codecov/c/github/smarter-sh/smarter-python/main?flag=python&label=Python%20coverage&logo=codecov)](https://codecov.io/gh/smarter-sh/smarter-python?flags%5B0%5D=python)
[![Latest Release](https://img.shields.io/github/v/release/smarter-sh/smarter-python?label=release)](https://github.com/smarter-sh/smarter-python/releases)
[![PyPI](https://img.shields.io/pypi/v/smarter-api?logo=pypi&label=PyPI)](https://pypi.org/project/smarter-api/)
[![Python versions](https://img.shields.io/pypi/pyversions/smarter-api?logo=python)](https://pypi.org/project/smarter-api/)
[![Docs](https://img.shields.io/badge/Read%20the%20Docs-smarter.sh-blue?logo=readthedocs)](https://docs.smarter.sh/en/latest/smarter-framework/smarter-python.html)
[![Website](https://img.shields.io/badge/official%20web%20site-smarter.sh-blue?logo=google-chrome)](https://smarter.sh)
[![License: GNU AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)<br>

`smarter-api` is the official Python SDK of the
[Smarter platform](https://github.com/smarter-sh/smarter). 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.

```python
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:

| [smarter-python](https://github.com/smarter-sh/smarter-python) (this package) | [smarter-cli](https://github.com/smarter-sh/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.

## 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](https://docs.smarter.sh/en/latest/smarter-framework/smarter-manifests.html)
  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

```console
pip install smarter-api
```

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

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

### Manifests

```python
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

```python
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

```python
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](https://docs.smarter.sh/en/latest/smarter-framework/smarter-python.html)
on [docs.smarter.sh](https://docs.smarter.sh/).

## Requirements

Python 3.10 or later, and a Smarter platform to connect to. See the
[Quick Start Guide](https://docs.smarter.sh/en/latest/smarter-platform/installation/quick-start.html)
to run one on your laptop.

## Development

```console
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/](./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](https://github.com/smarter-sh/smarter-python/issues)
for this project.

## Contributing

Please see the [CONTRIBUTING](https://docs.smarter.sh/en/latest/smarter-framework/guides/contributing.html).
