hanzoai/cloud@113cf7d6 declares components.securitySchemes.bearer and applies it
document-wide, so regenerating writes a populated Configuration.auth_settings()
and auth_settings=['bearer'] into 2498 call sites; ApiClient._apply_auth_params
sets Authorization: Bearer <token> from access_token, which was read by nothing
before. Four call sites carry an empty list — exactly the operations the document
marks security: [] (get_models, get_models_providers, get_commands,
get_openapi_json) — so the public routes still go out with no credential.
examples/client.py drops the header_name/header_value compensation and passes
access_token. examples/models is a new flow on the public catalog: it runs before
a reader has a key, which makes the install checkable in one command.
Proven on api.hanzo.ai, not by reading: examples.models prints 112 models with no
credential; examples.hello returns the caller's keys with a real sk- and 403
"sign in to manage API keys" with a bogus one.
"Nothing in the client reads the environment" is true of the generated tree —
zero os.environ under hanzoai.cloud — and false of the package a reader
installs: hanzoai.zap reads HANZO_ZAP_ENDPOINT and hanzoai.config reads
HANZO_CONFIG_HOME. Neither carries a credential, which is the property the
sentence was reaching for, so it now says that instead of overreaching.
The README offered the two key shapes as a permission split — pk- to read,
sk- to write. cloud's own identity boundary says otherwise: middleware_identity
returns nil for any pk- before it consults the key store, because a key meant
for a browser bundle must not read. A pk- resolves to an org so a beacon can be
attributed to a tenant, and that is all it does.
Following the old sentence, a reader exports a pk- and every one of the five
flows answers 403 — /v1/tools spells out why, "a validated principal is
required" — and that refusal reads like a revoked key rather than the wrong
shape of key. examples/client.py now refuses a pk- before the request goes out,
the same argument that already rejects an unsendable access_token.
Also: three status codes in example docstrings had drifted from what the API
answers now (/v1/kv/keys/* 404s on every verb, /v1/automations/mcp 404s), and
two dead files went with them — examples/.keep, whose directory has held real
flows for a while, and scripts/mock, which reads a .stats.yml this repo does
not have and which scripts/test already says is unnecessary.
README: PyPI serves 3.2.1 and this tree is 3.2.11, so the install line is the
git one. Between the two the default version left the operation ids — 3.2.1
carries get_v1_keys/get_v1_tools (182 api modules, 2172 models) and this carries
get_keys/get_tools — so `pip install hanzoai` above a `get_keys()` quickstart
hands the reader a client that cannot run it. Counts are measured off the pinned
document: 1814 paths, 2479 operations, 191 tags + default_api = 192 API classes
over 2460 models, 2659 importable modules.
Auth was wrong everywhere and it was the same root cause: the document declares
no securityScheme, so every operation got an empty auth_settings and
Configuration(access_token=…) is read by nothing. Serializing get_keys from such
a Configuration produces a request with no Authorization header at all — the
five flows have been calling anonymously and reading the refusal as a bad key.
examples/client.py now passes the bearer through ApiClient's header_name/value
pair, verified against a local server that echoes what it received, and a smoke
test pins both halves so the day cloud emits the scheme, the test fails and the
header moves back into Configuration.
The examples gate resolved class names and stopped there, which is how `money`
and `tools` once passed it while every call in them named a method that no
longer existed. It now walks the syntax tree for attribute accesses on anything
bound to a *Api and asks the class: ten names resolve, and a stale get_v1_tools
fails in the same second the import passes.
Deleted five example scripts that imported hanzoai.Hanzo, hanzoai.cluster,
hanzoai.agents and hanzoai.completion — none of which exist — or were dict
literals captioned "in practice this would be called through the MCP interface";
compileall passed all five, because syntax is not a claim. Deleted three docs
that were fabrication rather than drift and that nothing rendered: FEATURES.md,
QUICKSTART.md, GPT5_ORCHESTRATION.md.
pkg/hanzo-agent said `pip install hanzoai` and `from hanzoai import Agent,
Runner`; the client has no Agent. Its own `full` extra resolved to
hanzoai[web3,tee,marketplace,cli], extras the client does not declare, so it
installed the client and none of the extensions. pyproject said BSD-3-Clause
while LICENSE is the Apache 2.0 text. test_smoke imported tracker_api and no
/v1/tracker path is emitted any more, so the suite carried a failing test naming
a module the client does not have; it reads analytics_api now, off the client.
Cloud's APIKeyPrefixes admits pk- and sk- only (auth_identity.go, 4b030b77).
The lsp tool still told the user to set an hk- key, which cloud resolves to no
principal — following the message produced a key that could never authenticate.
The message is now a single NO_KEY beside the resolver that mints it, exported
from hanzo_tools.core, so a second tool reporting it cannot spell it differently.
Resolution order is untouched: HANZO_API_KEY, then ~/.hanzo/config.json .apiKey,
then the CLI's IAM session.
vector_index names the split cloud actually draws: pk- publishable for read,
sk- secret for write.
Co-authored-by: Hanzo Dev <[email protected]>
This distribution shipped two complete generated clients under one import root.
`hanzoai.cloud` is the current one, generated from hanzoai/cloud's openapi.yaml at
the ref .spec-lock names. `hanzoai.api` / `hanzoai.models` was another, and the
package root re-exported its 2,202 names flat — so the obvious spelling,
`from hanzoai import ApiClient`, reached the second client, while
`hanzoai.cloud.ApiClient` reached the first. Nine core names existed twice as
distinct classes bound to distinct documents, and which one a caller got depended
on which import line they happened to write.
The second lineage was not an older copy of the first. It was a projection of a
document that no longer exists: of the 1,695 routes it binds, 243 are still in the
document at v1.801.495 and 1,452 are not. Eighty-six percent of it builds a
request the server answers with a 404. It had been broken for as long as it had
been shipping, and nothing said so, because a client only fails at the call.
So it goes, along with its runtime — api_client, api_response, configuration,
exceptions, rest — which `hanzoai.cloud` carries its own copies of. The package
root now exports `cloud` and nothing else. Nothing is re-exported flat on purpose:
a name that appears in two places is a name that can disagree with itself, and the
namespace already says which document a symbol came from.
The smoke tests pinned the deleted surface — they asserted more than 300 api
modules and imported `hanzoai.api.tracker_projects_api` by name, which is how a
suite can stay green over a client that 404s. They now assert the surviving one,
plus the invariant that made this possible in the first place: exactly one
generated package under `hanzoai`, and none of the nine core names re-exported
flat beside it.
Three published packages declared a console script named `hanzo`, competing with
the native CLI and with each other. Measured on a clean venv at hanzo==0.4.3:
`hanzo --help` printed hanzo-cli's program, not the one pkg/hanzo/README.md
documents. Renamed to `hanzo-py` and `hanzo-cli` — script named after its
distribution. Nothing is yanked; both packages still install and run.
- pkg/hanzo 0.4.4 — summary and README now say the CLI is a native binary
(curl -fsSL https://hanzo.sh | sh). Dropped the invented command tour
(`hanzo chat --model gpt-4`, `hanzo node start`, `hanzo router start` on
localhost:4000): none of those verbs exist in the program this package
installs. Kept the three library entry points, each import-checked.
- pkg/hanzo-cli 0.2.4 — `hanzo login` replaced with the native `hanzo auth login`
plus its own `hanzo-cli login`. Verified `hanzo iam users list` and
`hanzo kms secrets list` against the shipped v1.9.18 binary.
- pkg/hanzo-node 0.1.1 — states the two meanings of the name: the `hanzo-node`
COMMAND is a symlink to the Hanzo CLI; this package fetches a different binary
from hanzoai/node, which is private, so the download 404s for the public.
Documentation URL moved off docs.hanzo.ai/node (404) to hanzo.sh.
- root README (published as `hanzoai`) — `pip install hanzo` no longer advertised
as the CLI; model ids zen-coder -> zen5-coder (zen-coder is not in the catalog);
"2452 operations, 1798 schemas" dropped for the spec URL, since the live
surface is 1058 paths / 1465 operations / 1139 schemas.
Co-authored-by: Hanzo Dev <[email protected]>
The document grew: cloud's woven spec was merged and won, taking hanzo.yaml from
1132 paths / 1519 operations / 779 schemas to 1737 / 2452 / 1798.
pkg/hanzoai/cloud/ is now 263 api + 2031 model modules, all importing.
`generate.py python --check` reports [python] clean.
The resync also RENAMED nearly every operationId to cloud_<method>_<path>, which
renames every generated method: billing_billingBalance became
cloud_get_v1_billing_balance, cloud_AgentsController.Create became
cloud_post_v1_agents. Examples written against the old names stop resolving —
exactly what the examples gate exists to catch. It went red; this is the fix.
Every flow was re-probed against api.hanzo.ai unauthenticated and with a bogus
key, because a spec says what SHOULD be served and only a request says what IS.
All eleven operations answer 401/403 — routed and identity-gated. Two moved:
store to the PROVISIONING plane (POST /v1/kv, GET|DELETE /v1/kv/{name}). The
per-key data plane the spec also describes is mounted nowhere: GET
/v1/kv/keys/{key} 404s, PUT and DELETE 405, kv.hanzo.ai 404s the whole
prefix. A round-trip on keys could not run.
tools to GET /v1/tools, the catalog. A live JSON-RPC door at POST /v1/mcp
answers tools/list with 730 tools but is absent from hanzo.yaml, so the
generator emits no method and an example would have to bypass the SDK
to reach it. Of the declared MCP routes /v1/automations/mcp returns 405.
hello stays on bot_authMe: /v1/ai/account answers 200 with
type="anonymous-user" to a request with NO Authorization header, so a hello
built on it certifies a key that would 401 everywhere else.
All six run and report the server's own refusal for a bogus key:
hello 403 no validated principal store 403 X-Org-Id required
chat 401 API key validation failed agent 403 X-Org-Id required
money 401 sign in to view billing tools 403 a validated principal required
money goes through the generated *_without_preload_content variant, because its
two operations are declared with a `default` response and no content so the
typed methods return None though the server sends JSON — a spec gap, and not a
small one: 696 of 2425 operations model no response body. That raw variant does
NOT raise on 4xx (the check lives in the typed deserialization these lack), so
the example checks status itself; without it a 401 body printed as the balance.
3.1.5 -> 3.1.6. 3.1.5 is live on PyPI, so this is a real patch above it.
Co-authored-by: Hanzo Dev <[email protected]>
REGENERATED pkg/hanzoai/cloud/ from hanzo.yaml @ 07783f5 via the canonical
driver (hanzoai/openapi generate.py python) — 1132 paths, 1519 operations, 779
schemas, landing as 239 api + 1116 model modules. `generate.py python --check`
reports `[python] clean`: the committed tree is byte-identical to a fresh
generation, with no local strip of any kind.
The path count fell from 1885 because the spec deleted 18 products it authored
and served nowhere. Nothing here was lost to a collapse — LLM.md carried an open
defect saying 127 of 411 operations went missing to 23 case-variant tag groups
(AI/ai, Users/users). That is now fixed upstream, and this regeneration proves
it: 239 distinct tags produce 239 api modules, exactly 1:1.
Generating at all required two spec fixes. Both landed in hanzoai/openapi first,
neither is patched here:
- fc0c17a 35 /v1/platform operations carried no `responses`. OAS 3.x requires
it and openapi-generator aborts the whole document, so hanzo.yaml
was producing no client in ANY language.
- 07783f5 ChatCompletionResponse.choices was `items: {type: object}` — so
choices[0].message.content came out List[object], unusable without
a cast, on the most-called route in the API.
SIX EXAMPLES under examples/{hello,chat,money,store,agent,tools}, plus
examples/client.py as the single place a base URL or an env var is resolved.
Same six, same names, same order as the TypeScript set, so a reader who knows
one can navigate the other. They import from hanzoai.cloud — the generated
surface new work targets — not the frozen pkg/hanzoai/{api,models}.
Each flow's call sits behind `if __name__ == "__main__":` deliberately: that is
what lets the gate IMPORT all six to prove every `from hanzoai.cloud import X`
still resolves, with no API key and no socket. A spec change that renames or
drops an operation goes red in CI instead of in a user's app.
CI is the fleet convention and this repo had none: root hanzo.yml + a 7-line
cicd.yml importing hanzoai/ci. The gate is two blocks — import every generated
module (for generated code that IS the build step; there is no compiler to catch
a bad $ref or a model referencing a class the generator declined to emit), then
import the six flows. Both provision an interpreter with uv, because the arc
runner image promises none and a gate that silently no-ops is worse than none.
Scope is deliberate: the cloud client and its flows, not all 65 packages, so a
red gate means "the client the spec just produced is broken" rather than
"something, somewhere". Publishing is untouched — .hanzo/workflows/publish-pypi.yml
stays canonical because it reads the PyPI token from KMS. Two publish paths is
one too many.
3.1.4 -> 3.1.5. PyPI still serves 3.1.1; the tree has been ahead since the KMS
secret at hanzo/prod/python-sdk-publish went unseeded.
Co-authored-by: Hanzo Dev <[email protected]>
- Create detailed README for main repository with architecture overview
- Add package-specific READMEs with usage examples and API documentation
- Create CONTRIBUTING.md with development guidelines and workflow
- Update LLM.md with architectural decisions and patterns
- Document all CLI commands, configuration options, and best practices
- Include installation, testing, and deployment instructions
- Add code examples for all major features
- Document port allocation strategy and integration points
- Ensure 100% test pass rate (197 tests passing)
- Renamed 'cluster' terminology to 'node' throughout codebase for clarity
- Added new 'hanzo router' command for managing LLM proxy server
- Added zsh shell tool with automatic shell detection (prefers zsh over bash)
- Fixed REPL to use cloud mode by default to avoid local server dependency
- Updated chat command to try router (port 4000) before local node (port 8000)
- Added comprehensive Grok documentation to README
- Created NODE_COMPATIBILITY.md documenting integration with desktop app and network
BREAKING CHANGE: 'hanzo cluster' commands now use 'hanzo node' - old commands still work via aliases
Key changes:
- hanzo node start/stop/status - manage local AI nodes
- hanzo router start/stop/status - manage LLM proxy router
- hanzo node worker - manage node workers (formerly cluster nodes)
- Zsh is now default shell when available
- Router runs on port 4000, nodes on port 8000
- Full compatibility with Hanzo desktop app and network layer
- Implement unified CLI tools module for all AI providers
- Add support for claude/cc, codex, gemini, grok, openhands/oh, hanzo-dev, cline, aider
- Enable parallel batch execution of CLI tools
- Add comprehensive test suite with 16 passing tests
- Fix typing issues with mypy strict mode
- Add GitHub Actions CI/CD workflow with optional integration tests
- Support authentication flow for all providers
- Follow DRY principle with single source of truth
- Implement hanzo dev command with System 2 thinking orchestration
- Add support for local models (Llama, Qwen, Mistral) as orchestrators
- Create cost-optimized routing that uses local models for simple tasks
- Add MCP bridge for inter-agent communication
- Enable agent networks where all agents can call each other
- Add comprehensive E2E tests for local AI orchestration
- Fix logger initialization in dev.py
- Add fallback classes for when hanzo-network is not available
- Bump versions: hanzo 0.3.12, hanzo-mcp 0.8.2
- Added Test Status and Hanzo Packages CI badges
- Updated project status to reflect mock-based testing
- Highlighted CI/CD pipeline and no external dependencies
- Add CI status, test coverage, and version badges
- Update with current features and capabilities
- Add comprehensive usage examples
- Include development and testing instructions
- Clean, professional documentation structure
- Reorganized main README to focus on complete AI SDK ecosystem
- Created dedicated hanzoai package README for AI client library
- Clear distinction between ecosystem (hanzo) and client library (hanzoai)
- Updated package descriptions and usage examples
- Bump versions: hanzoai 2.0.2→2.1.0, hanzo 0.2.14→0.3.0, hanzo-mcp 0.7.7→0.8.0
- Highlighted hanzo net command for local AI orchestration
- Added comprehensive installation variants and architecture details
zeekay
