Metadata-Version: 2.4
Name: silvanexum
Version: 0.1.2
Summary: Official Python SDK for Silvanexum — the spend-control plane for AI agents. Meter, attribute, cap, and audit agent spend across a multi-agent mesh, on any model or rail. Typed pydantic models generated from the API's Zod contracts.
Project-URL: Homepage, https://docs.silvanexum.com
Project-URL: Documentation, https://docs.silvanexum.com
Project-URL: Repository, https://github.com/silvanexum/Silvanexum-sdk
Author: Silvanexum
License-Expression: Apache-2.0
Keywords: agents,ai,budget,cost,finops,llm,observability,sdk,silvanexum,spend
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.7
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# silvanexum

Official Python SDK for [Silvanexum](https://silvanexum.com) — **the spend-control
plane for AI agents**. Meter, attribute, cap, and audit what every agent spends
across your whole agent-to-agent mesh, on any model or rail. Models are generated
from the API's Zod contracts (pydantic v2), so they never drift from the live API.

📚 Full docs: **https://docs.silvanexum.com**

## Install

```bash
pip install silvanexum
# uv add silvanexum · poetry add silvanexum
```

Requires Python ≥ 3.9.

## Quickstart — cap spend, then see who spent it

```python
import os
from silvanexum import Silvanexum

sx = Silvanexum(api_key=os.environ["SILVANEXUM_API_KEY"])

# Cap runaway spend — a run or mesh hop that would breach the budget is
# rejected server-side (HTTP 402). "Spent" is computed from real run telemetry.
sx.budgets.create(
    name="support-team",
    scope_type="agent",
    scope_id="agt_123",
    period_type="monthly",
    limit_credits=50_000,
    enforcement="block",
)

# Attribute cost across the mesh — which agent / project / model actually spent.
for row in sx.spending.summary(group_by="agent"):
    print(row.label, row.costCredits)
```

The client is a context manager, so connections are cleaned up for you:

```python
with Silvanexum() as sx:          # reads SILVANEXUM_API_KEY from the env
    trend = sx.spending.trends(bucket="1d")  # daily spend, last 30 days
```

## What's in the SDK

| Resource | What it does |
| --- | --- |
| `sx.spending` | Cost attribution — `summary` / `trends` / `mesh_trace` (by agent, project, model, provider) |
| `sx.budgets` | Spend caps with `off` / `alert` / `block` enforcement + live status |
| `sx.gateway` | Zero-code OpenAI-compatible capture + usage |
| `sx.fleet` | Cost, latency, drift, and alert observability |
| `sx.runs` · `sx.agents` | Run agents; read signed, replayable traces |
| `sx.security` | Hash-chained audit log + compliance export |

…plus `marketplace`, `wallet`, `routing`, `connectors`, `team`, and more. Full
reference: **https://docs.silvanexum.com/docs/sdk-reference/python**.

## Zero-code capture (gateway)

Point your OpenAI client's `base_url` at the gateway and use your Silvanexum key.
Every call is metered on your own provider key and counts toward budgets:

```python
from openai import OpenAI

openai = OpenAI(
    base_url=sx.gateway.openai_base_url(),
    api_key=os.environ["SILVANEXUM_API_KEY"],
    default_headers={"x-silvanexum-trace": trace_id},  # optional mesh stitching
)
```

## Errors

```python
from silvanexum import InsufficientCreditsError, RateLimitError

try:
    sx.runs.create(agent_id="agt_123", prompt="…")
except InsufficientCreditsError:
    ...  # budget/credits exhausted (HTTP 402) — top up or raise the cap
except RateLimitError:
    ...  # client already retried with backoff
```

Licensed Apache-2.0.
