zeekay
42139d1849
The unified tool derived its surface from /v1/openapi.json, which describes the API rather than what a model may be handed. cloud keeps an operation off the agent surface when its name discloses a bearer secret or when a mutating verb acts on identity — post_iam_users is in the contract and refused at /v1/mcp, so this tool offered an identity mutation the fleet declines. The document still supplies each operation's method and path, which a caller needs to make the request; the generated catalog supplies which are offered. Two facts, one source each, and the rule is asked of cloud rather than restated. An unreadable catalog offers nothing, because failing open widens the surface silently. Two aliases pointed at names the fleet had left behind, mapping callers off the live surface. A synonym may only point at a name it serves. A fixture naming no operations is not exercising the offer rule and now says so, rather than the default being weakened to keep it green.
Hanzo Python SDK
hanzoai is the Python client for the Hanzo API, generated from the API's own
OpenAPI document. Every /v1 route is in it, and the names it exposes are the
document's operation ids. .spec-lock names the commit and sha256
of the document this tree was cut from.
Install
pip install hanzoai
Check the install without a key — GET /v1/models is public:
python -m examples.models
https://api.hanzo.ai serves 112 models, no credential required
all-mini-lm-l6-v2 · do-ai · $0.02/Mtok in
anthropic-claude-opus-5 · do-ai · $1/Mtok in
…
Quickstart
import os
from hanzoai.cloud import ApiClient, Configuration, KeysApi
client = ApiClient(Configuration(
host="https://api.hanzo.ai",
access_token=os.environ["HANZO_API_KEY"],
))
with client as api:
for key in KeysApi(api).get_keys().keys or []:
print(key.prefix, key.type, key.created_at)
Every route follows that shape: one *Api class per tag, one method per
operation, typed models in and out.
Auth
access_token is the whole configuration — it becomes
Authorization: Bearer <token> on every operation that asks for a credential.
Four operations do not: GET /v1/models, GET /v1/models/providers,
GET /v1/commands, GET /v1/openapi.json. They send no credential, which is why
examples/models runs before you have a key.
Keys come from cloud.hanzo.ai or hanzo login in two
shapes, and only one of them works here. Use an sk-: it carries a principal,
which every credentialled call needs. A pk- is publishable — safe in a browser
bundle because it names an org and authenticates nobody — so cloud refuses it at
the identity boundary.
No generated code reads the environment, so no variable you export reaches a
request on its own. (The hand-written hanzoai.zap and hanzoai.config read
HANZO_ZAP_ENDPOINT and HANZO_CONFIG_HOME; neither is a credential.)
examples/client.py is where HANZO_API_KEY and
HANZO_BASE_URL get resolved, for all six flows.
Examples
examples/ carries one directory per flow. Each is a whole path through one part
of the API. CI imports all six and resolves every method name they call against
the client.
| flow | what it does | routes | key |
|---|---|---|---|
models |
the model catalog | GET /v1/models |
none |
hello |
prove the key works | GET /v1/keys |
sk- |
money |
balance + usage | GET /v1/billing/balance, GET /v1/billing/usage |
sk- |
store |
KV round-trip | POST /v1/kv, GET/DELETE /v1/kv/{name} |
sk- |
agent |
create, run, read the runs | POST /v1/agents, POST /v1/agents/{ref}/run, GET /v1/agents/{ref}/runs |
sk- |
tools |
the tool catalog | GET /v1/tools |
sk- |
One command each, from the repo root:
python -m examples.models # no credential
export HANZO_API_KEY=sk-...
python -m examples.hello
A real key prints your keys; a bogus one prints
HTTP 403: {"code":"forbidden","error":"sign in to manage API keys"}.
There is no chat flow: POST /v1/chat/completions is declared with no
requestBody and no responses, so the method takes no arguments and returns
None. It comes back the day the document describes the body.
money reads its two payloads through the generated
*_without_preload_content variant, for the same reason — an operation that
declares no responses, or a 2xx carrying no content, models no body to
deserialize.
Reference for the routes themselves: api.hanzo.ai/docs, served from the same document — api.hanzo.ai/v1/openapi.json.
The rest of the repo
This is a uv workspace. pkg/hanzoai is the client above; the other packages
are hand-written, ship separately, and mostly carry their own README:
| Package | Install | Purpose |
|---|---|---|
pkg/hanzoai |
hanzoai |
the client above |
pkg/hanzo-mcp |
hanzo-mcp |
Model Context Protocol server |
pkg/hanzo-agent |
hanzo-agent |
agent framework (import path agents) |
pkg/hanzo-agents |
hanzo-agents |
agent networks and swarms |
pkg/hanzo-memory |
hanzo-memory |
persistent memory + RAG over SQLite |
pkg/hanzo-network |
hanzo-network |
distributed compute nodes |
pkg/hanzo-tools-* |
one each | single-concern tool packages, each registering a TOOLS list under the hanzo.tools entry point, which is how hanzo-mcp finds them |
The hanzo command is a native binary, not a Python package:
curl -fsSL https://hanzo.sh | sh. pip install hanzo ships the older Python CLI
under the name hanzo-py, so the two never fight over one name on a PATH.
Development
git clone https://github.com/hanzoai/python-sdk && cd python-sdk
uv sync --all-packages
uv run pytest tests/ -v
pkg/hanzoai/cloud/ is generated and is never edited by hand — a regeneration
does rmtree then copytree, so an edit there is gone on the next run. It comes
from hanzoai/openapi:
cd ../openapi && uv run --with pyyaml python3 generate.py python \
--repo ../python-sdk --spec ../cloud/openapi.yaml
A defect in generated code is fixed in the document.
License
Apache 2.0 — see LICENSE. Report vulnerabilities to [email protected] (SECURITY.md).
Hanzo — the Open AI Cloud
hanzo.ai · docs.hanzo.ai · same client in other languages: TypeScript · Go · Java · Kotlin · umbrella