> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokz.si/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> tokz for Python — typed decisions about text, sync and async, and your fine tunes on your own machine.

```bash theme={null}
pip install tokz
```

Requires Python 3.9+. The only dependency is `httpx`, which gives sync and async
from one API — so `AsyncTokz` is not a second HTTP stack with its own timeout
semantics to keep in step. Only `decide_local` needs more, through
`pip install "tokz[local]"`.

## Decide

```python theme={null}
import os
from tokz import Tokz

tokz = Tokz(api_key=os.environ["TOKZ_API_KEY"])

out = tokz.decide(
    ["I was charged twice.", "How do I export my data?"],
    {
        "queue": {"type": "choice", "options": ["billing", "technical", "account"]},
        "urgent": {"type": "bool"},
    },
)
for r in out["results"]:
    print(r["queue"]["best"], r["urgent"]["best"])
print(out["usage"]["billed_tokens"])
```

`tokz.decide(inputs, decisions, *, model=None, timeout=60.0)` and
`tokz.list_decision_models()`. See the [Decisions API](https://docs.tokz.si/decisions.md). `decide` is never
retried, because a retry could bill twice.

`Tokz(api_key, base_url="https://api.tokz.si", client=None)` accepts your own
`httpx.Client` for proxies or tests; a client you pass in is not closed for you. Use
`with Tokz(...) as tokz:` or call `close()`.

## Fine tunes

Call a [fine tune](https://docs.tokz.si/fine-tune.md) by name. Needs 0.6+. Up to 16 texts on our servers, and the
answer is always under `decision`. For a multi-label model read `selected`, because `best`
names a label even when `selected` is empty.

```python theme={null}
out = tokz.decide("support-triage", "I was charged twice.")
print(out["results"][0]["decision"]["best"])
```

`decide_local` runs the same model on this machine for free, with the same result shape.

```bash theme={null}
pip install "tokz[local]"
```

```python theme={null}
out = tokz.decide_local("support-triage", "I was charged twice.")
print(out["results"][0]["decision"]["best"])
```

The first call downloads the model into `~/.cache/tokz` on every OS and verifies its hashes.
`TOKZ_CACHE_DIR` moves the cache. After that it works offline, and asks the server about once
an hour whether the model still exists. The extra keeps `onnxruntime` at 1.26.0 or older,
because newer versions change the scores. See [Fine Tune](https://docs.tokz.si/fine-tune.md#run-it-on-your-machine).

## Async

```python theme={null}
from tokz import AsyncTokz

async with AsyncTokz(api_key=os.environ["TOKZ_API_KEY"]) as tokz:
    out = await tokz.decide("charged twice", {"urgent": {"type": "bool"}})
```

Same methods, same errors. `decide_local` runs on a worker thread.

## Errors

| Exception | When |
| - | - |
| `TokzError` | Any failure; `.status` carries the HTTP status when there was one, `.retry_after` the seconds from `Retry-After` |
| `TokzInsufficientCreditsError` | HTTP 402; `.balance_cents` carries the reported balance |

Both are importable from `tokz`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.