Python SDK

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

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

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. decide is never retried, because a retry could bill twice.

Tokz(api_key, base_url="https://api.tokz.dev", 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 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.

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.

pip install "tokz[local]"

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.

​

Async

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.