mirror of https://github.com/hanzoai/python-sdk.git synced 2026-10-23 20:23:00 +00:00

Files

T

zeekayandHanzo Dev 22b00e135a sdk: regen — the KMS org left the URL, so 3.1.2's secrets routes were dead

Regenerated pkg/hanzoai/cloud from hanzo.yaml. Consumed: cloud 8143fc0e,
openapi 2861089 (was f581a0e when 3.1.2 was cut).

openapi 3300cda took {org} out of the KMS secrets contract — the org is read from
the token now — and 3.1.2 shipped from before it, so its KMS methods addressed a
path the server no longer serves:

    /v1/kms/orgs/{org}/secrets         -> /v1/kms/secrets
    /v1/kms/orgs/{org}/secrets/{rest}  -> /v1/kms/secrets/{rest}
    kms_get_v1_kms_orgs_org_secrets    -> kms_get_v1_kms_secrets
    kms_post_v1_kms_orgs_org_secrets   -> kms_post_v1_kms_secrets

Five request/response models renamed with them. Nothing else in the 1885-path
surface moved: 5 models added, 5 removed, 6 files changed.

3.1.2 never reached PyPI (the tag cannot get to git.hanzo.ai — sync-from-github
fast-forwards main only, never tags), so this is fix-forward, not a replacement.
PyPI still serves 3.1.1; 3.1.2 stays a tag.

The upstream tag-casing collision came back exactly as LLM.md said it would: the
regen rmtree'd the tree and `import hanzoai.cloud` raised ImportError again on
AiApi/ApiKeysApi/McpApi. Stripped the same 9 dead lines. It will return on every
regen until one tag spelling per service lands in the per-service specs — that
also recovers the 127 of 411 operations those 23 colliding groups still drop.

No test pins the KMS route: asserting spec content here would make this repo a
second source of truth for routes and fight the pull-only contract. test_smoke
pins structure instead — import, version, surface breadth. 6 passed.

Version 3.1.2 -> 3.1.3, patch only.

Co-authored-by: Hanzo Dev <[email protected]>

2026-07-28 10:34:39 -07:00

4.3 KiB

Raw Blame History

LLM.md — hanzoai/python-sdk

What this is: the flagship, most-complete Hanzo SDK — a uv workspace of 60+ packages: the typed cloud client (hanzoai), agents, MCP server + tools, memory, distributed compute, and the hanzo CLI. pip install hanzo.

Canonical role (one-way SDK model): Hanzo ships two SDK lines per language — (1) the full cloud SDK generated from OpenAPI, (2) the AI/agents library. This repo is the Python flagship of line 2, the reference for every other language. Completeness: Python → Rust → C++ → Go. One impl, one place; discovery repos link OUT, never duplicate. Full spec: ~/work/hanzo/SDK-ARCHITECTURE.md.

Install / run

pip install hanzo            # CLI + agents + MCP + client
uv sync --all-packages       # dev: whole workspace
uv run pytest tests/ -v      # tests

Brand rules (hard — enforce in all docs)

Never "LLM gateway"; never position against LiteLLM. Hanzo is a full AI SDK / AI cloud, not a proxy.
Zen models are our own family — never name upstream models.
Paths are /v1/…, never /api/…. Base host: https://api.hanzo.ai.
Voice: "Hanzo — the Open AI Cloud." Crisp, developer-first, no emoji-spam.

Codegen — this repo PULLS, it never pushes

hanzoai/cloud    emits its own router spec    -> cloud/openapi.yaml (984 paths)
hanzoai/openapi  merges 69 per-service specs  -> hanzo.yaml (1885 paths)  [the ONE SDK input]
hanzoai/openapi  generate.py + sdks.yaml      -> projects hanzo.yaml into each SDK repo
this repo        owns its test + PATCH bump + release

pkg/hanzoai/cloud/ is generated — never hand-edit it. generate.py does rmtree(dst) + copytree(src), so anything written there dies on the next run. Regenerate only from hanzoai/openapi (python3 generate.py python) — never from here. The old scripts/generate.sh was a second, destructive driver (rm -rf pkg/hanzoai, which would have eaten the hand-written config/mcp/protocols/session/zap modules); it is deleted. Consumed at 3.1.3: cloud 8143fc0e, openapi 2861089. Regenerate whenever either moves — openapi 3300cda dropped {org} from the KMS secrets routes (/v1/kms/orgs/{org}/secrets -> /v1/kms/secrets; the org is read from the token), which silently stranded 3.1.2 on a path the server no longer serves.

Upstream spec defect — open, fix in the per-service specs. hanzo.yaml carries 23 tag groups that differ only by case (AI/ai, Users/users, flows/Flows, …). openapi-generator maps both spellings onto one module, so the second overwrites the first: 127 of the 411 operations in those groups are missing from the generated client. Three groups (AI/ai, API Keys/api-keys, MCP/mcp) also yield divergent class names (AiApi vs AIApi), which made import hanzoai.cloud raise ImportError; those 9 dead lines are stripped and tests/test_smoke.py locks the import. One spelling per tag upstream fixes both symptoms and the fix survives regeneration — the local strip does not.

Key entry points

pkg/hanzoai/ — typed OpenAPI client (ApiClient, Configuration, Ai*Api). Two surfaces live here: pkg/hanzoai/{api,models} (older, frozen — nothing regenerates it now) and pkg/hanzoai/cloud/ (current, spec-driven). New work targets cloud/.
pkg/hanzo/src/hanzo/cli.py — the hanzo CLI command tree.
pkg/hanzo-mcp/ — MCP server; tools via [project.entry-points."hanzo.tools"].
pkg/hanzo-tools-*/ — one concern each, exports a TOOLS list.
pkg/hanzo-{agents,agent,network,memory}/ — agent/compute/memory libraries.
pkg/hanzo-kms/ — KMS client. The server is luxfi/kms (kms.hanzo.ai, kms.lux.network) and its whole surface is /v1/kms/auth/login plus /v1/kms/orgs/{org}/secrets[/{path}/{name}]. /api/* is Infisical's and was never served — it looked like a decode error rather than a 404 only because old builds answered every unmatched path with the console SPA (200 text/html). A secret is (org, path, name, env), one value each — no versions. The server splits the trailing URL at its LAST slash into (path, name), so escape each segment individually. pkg/hanzo-kms/tests/ pins all of it.

Rules for agents: update THIS file with significant discoveries; never write random summary files; keep the README cross-link block intact.