Metadata-Version: 2.5
Name: hanzo-kai
Version: 0.1.0
Summary: Python client for Kai decisions on the Hanzo API: typed answers to choice, yes/no and score questions.
Project-URL: Homepage, https://hanzo.ai
Project-URL: Documentation, https://docs.hanzo.ai/docs/kai
Project-URL: Repository, https://github.com/hanzoai/python-sdk
Author-email: Hanzo AI <dev@hanzo.ai>
License-Expression: Apache-2.0
Keywords: classification,decisions,hanzo,kai,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.10
Description-Content-Type: text/markdown

# hanzo-kai

Python client for Kai decisions on the Hanzo API. Send a state and named questions; get typed,
calibrated answers back: a label for a choice, a probability for a yes/no noul, an expected level
for a score.

## Install

```bash
pip install hanzo-kai    # or: uv add hanzo-kai
```

Python 3.12 or later. Set `HANZO_API_KEY` to a Hanzo `sk-` key.

## Quickstart

```python
from hanzo_kai import Choice, Kai, Noul, Score

teams = {"billing": "charges, invoices, refunds", "tech": "bugs and outages"}
billing = {"true": "it concerns charges, invoices or refunds", "false": "it concerns something else"}
questions = {
    "team": Choice(instructions="Which team should handle this?", criteria=teams),
    "billing": Noul(instructions="Is this about billing?", criteria=billing),
    "urgency": Score(instructions="How urgent is this?", criteria=["can wait", "this week", "today"]),
}
with Kai() as kai:  # reads HANZO_API_KEY
    d = kai.decide({"ticket": "I was charged twice for my March invoice. Please refund the duplicate."}, questions)

print(d.choices["team"].choice, d.choices["team"].probabilities)
print(d.nouls["billing"].noul)
print(d.scores["urgency"].score, d.scores["urgency"].probabilities)
```

`AsyncKai` takes the same arguments, with `await` and `async with`. `kai.models.list()` lists the
models that answer decisions.

Settings come from arguments, then `HANZO_API_KEY`, `HANZO_BASE_URL` (default
`https://api.hanzo.ai`), `KAI_MODEL` (default `kai`) and `KAI_LOG_LEVEL` (default `warn`).

## Moving from Jev

`hanzo_kai.jev` keeps TypeSafe's call shapes on Kai's Jev-compatible path, `POST /v1/systemone`, answering in Jev's shape:
`from hanzo_kai.jev import Choice, Noul, Score, Client as TypeSafeClient` ports a TypeSafe program in one line.

## Docs

- Kai: https://docs.hanzo.ai/docs/kai
- Moving from TypeSafe's Jev: https://docs.hanzo.ai/docs/guides/migrate/jev
