Metadata-Version: 2.5
Name: tokenspend
Version: 0.1.2
Summary: Official Python client for the TokenSpend API
Project-URL: Documentation, https://tokenspend.dev/docs/router
Project-URL: Homepage, https://tokenspend.dev
Project-URL: Repository, https://github.com/haseebc2000/token-spend
Author: TokenSpend
License-Expression: MIT
License-File: LICENSE
Keywords: ai,api,llm,tokenspend
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# TokenSpend Python

Official Python client for the TokenSpend API. It has no runtime dependencies.
Requires Python 3.9+. Use a virtual environment.

Follow the [canonical quickstart](https://tokenspend.dev/docs/agents#quickstart)
to set `TOKENSPEND_API_KEY` with hidden input. Use a TokenSpend rail key, never
a provider or admin credential. Do not commit keys.

```bash
python3 -m pip install tokenspend
```

```python
from tokenspend import TokenSpend

client = TokenSpend()
response = client.chat.completions.create(
    model="xai/grok-4.5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)
print(response.request_id)
```

Pass one stable key across retries of the same request:

```python
response = client.chat.completions.create(
    model="xai/grok-4.5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    idempotency_key="job-42-generation",
)
```

Changing the request requires a new idempotency key. The safe TokenSpend request
id is available as `response.request_id`, on a streaming iterator, and as
`error.request_id` when a duplicate returns 409.
Keys are scoped to workspace and route for 24 hours. Duplicates do not replay
the response. Use a new key after a failed request if you want another attempt.

Discover canonical ids and protocol capabilities from the live registry:

```python
models = client.models.list()
model = client.models.retrieve("zai/glm-5.2")
```

Set `stream=True` to iterate over server-sent chunks. `client.messages.create(...)`
uses the Anthropic-compatible Messages API. See https://tokenspend.dev/docs/router.

Other canonical IDs include `meta/muse-spark-1.2`, `thinking-machines/inkling`,
and `moonshot/kimi-k3`. Capabilities differ by model and format. Muse needs
`max_tokens=2048` or greater for its visible-output contract.

Requests are billable. Match `response.request_id` to the cost receipt in Router
activity. Check stream errors and completion state before accepting output.

Request logging is off by default. Opt-in history is encrypted and expires after
30 days. Disabling logging stops new storage; existing history keeps its expiry.
Capture is metadata-only. TokenSpend does not currently offer provider ZDR.
See [Trust](https://tokenspend.dev/trust) and the
[agent compatibility review](https://tokenspend.dev/docs/agents#compatibility).
SDK smoke tests do not verify agent sessions. Responses tools are unsupported.

The SDK never accepts a serving-host selector.
