Files

28 KiB

LLM.md — hanzo-go/sdk

Go module github.com/hanzoai/go-sdk/v8, published by git tag → proxy.golang.org.

go build ./... && go vet ./... && go test -count=1 ./... && go build ./examples/...

Those four are the whole gate, and hanzo.yml runs exactly them.

Repo identity

Canonical repo is hanzo-go/sdk. hanzoai/go-sdk is a rename redirect that GitHub honours and the forge does not: git.hanzo.ai/hanzoai/go-sdk answers Repository not found, so a checkout with that remote fetches nothing and quietly stays on whatever it last saw. Point origin at https://git.hanzo.ai/hanzo-go/sdk.git.

The module path stays github.com/hanzoai/go-sdk/v8 and is not renamed. A go.mod path must match what consumers require; github.com/hanzo-go/sdk has never been on the proxy and resolving it fails with a path mismatch.

The document, and the lock that names it

The client is a projection of hanzoai/cloud's openapi.yaml — the file cloud emits from its own routers and regenerates-and-diffs on every release, so it cannot describe a route the binary does not serve. .spec-lock names the ref and sha256 this committed client came from, in the four lines every Hanzo SDK uses:

ref=<commit sha, never a branch>
sha256=<of openapi.yaml at that ref>
repo=hanzoai/cloud
path=openapi.yaml

A branch there would read as a moving target in CI, which clones without your remotes and cannot resolve forge/main. The driver re-fetches at that ref and refuses to run if the bytes hash to anything else.

It is not hanzoai/openapi's hanzo.yaml. That file is itself a projection of this document with codegen rules applied, so reading it made this client a projection of a projection — one release behind whenever the middle step had not run. Every Hanzo SDK reads this same document, at the ref its own .spec-lock names; five of the seven — python, typescript, java, kotlin and this one — are pinned at this ref and share one digest. Generating from the projection instead, measured at the locked ref, costs this client 46 methods — 2456 against 2502 — and stamps every file's header API version: 8.0.0, the projection's own release counter, which names no cloud release. It buys one thing: the projection tags the 50 operations cloud leaves on DefaultAPI. That is cloud's emitter to fix, not a reason to read a second document.

The one difference that does not apply here: the projection's root security requires a bearerAuth its own components.securitySchemes does not define, which costs the languages that emit a credential per operation. Go's generator reads the defined bearer scheme instead, so Go's single Authorization site in client.go survives either document.

Go is a row in sdks.yaml like every other language. It was not, for one reason: take: used to promise the generator owned a directory, and this client's directory is the module root beside go.mod and .git. take: now names the files the generator wrote — see .generated below — so the row can say {.: .} and the second driver this repo carried is gone.

One client, at the module root

The repo root *.go is the client, package hanzoai — 3054 generated files beside the hand-written ones below. There is no second surface: the hand-shipped client that predated it and the parallel cloud/ subpackage are both gone.

The shape, measured against the locked document (8.5.623). 1771 paths carry 2450 operations, every one under exactly one tag, so 124 services and 2450 methods. 2449 distinct names: GetProvider is on two services from two operationIds. Every operation is reachable.

Hand-written, and safe from regeneration:

file why
hanzo.go New / Options / Client / As — the constructor and the six accessors
identity.go the IAM mints: client credentials, and the act grant As rides on
usage.go UsageLimitError, the six Code* constants and Err* sentinels, ReadUsage
call/ Answer, Denied, Held, Fault, Money, Page, and the one request path
budget/ policy/ audit/ search/ kb/ graph/ the six capabilities
secret/ Boot — a service reads its own credentials out of KMS at startup
hanzo_test.go, identity_test.go, capabilities_test.go, usage_test.go the round trip against an httptest estate
examples/ the six flows, plus models, errors, limits and six
go.mod, README.md, LLM.md, hanzo.yml, .hanzo/, scripts/ repo-owned

The six live in their own packages, and that is forced. The generated client already defines Answer, Page, Hit, Backend, Wrote, Allowance, Charge, Policy, Audit, Graph and Link as projections of unrelated operations, and a regeneration may add more. A hand-written type cannot share a package with a generated one of the same name, so call.Answer[T], audit.Filter and graph.Fact are where they are — which also means a regeneration can never collide with them.

.generated is what makes that table a fact rather than a promise. It names every path the driver wrote — the root *.go and docs/*.md, nothing else — so a regeneration removes a file the document stopped projecting and cannot touch a file it never wrote, whatever directory that file sits in. It is the same record in every Hanzo SDK, and it is why the client can live at the module root at all: ownership is a set of files, not a directory. Everything it names is generated — do not edit it, change the handler in hanzoai/cloud.

Usage limits

usage.go adds an Unwrap method to the generated GenericOpenAPIError, so every generated method's error reaches a *UsageLimitError through errors.As, and its code's sentinel through errors.Is, when the body is the gateway's {"error":{code,...}} with one of the six codes (hanzoai/ai routers/filter_balance.go writes them). Anything else unwraps to nil. Status comes from the error's status line; an operation whose error schema is the problem envelope fails to decode a gateway body and drops that line, so the code's documented status (402 or 429) stands in. A generator release that adds its own Unwrap breaks the build, which is the gate catching it.

ReadUsage reads X-Hanzo-Usage, -Usage-Class, -Paid-By, -Fallback, -Served and -Usage-Reason; absent reads "". Chat from a client credential is refused rather than answered by a fallback unless the client sends X-Hanzo-Fallback: allow (client.GetConfig().AddDefaultHeader).

TestLive is the live smoke, gated on its own flag: go test . -run TestLive -token="$(hanzo auth token)".

Auth: IAM mints, the SDK never accepts a bearer

The document declares it: one securityScheme, bearer (type: http, scheme: bearer), and a root security: [{bearer: []}] every operation inherits. Four opt out with security: [] — GET /v1/models, GET /v1/models/providers, GET /v1/commands, GET /v1/openapi.json — and /v1/models says why in its own description: the catalogue takes no principal, so the route reads Authorization to annotate gated SKUs and never to admit.

The client mints its own token and never takes one. New(Options{}) reads HANZO_CLIENT_ID and HANZO_CLIENT_SECRET and exchanges them at POST {issuer}/v1/iam/oauth/token — client_credentials under client_secret_basic, scoped by the RFC 8707 resource, which defaults to the base URL (HIP-0111). The reference is hanzoai/visor/egress_identity.go. There is no HANZO_API_KEY and no way to hand the SDK a bearer: a credential an SDK is given is a credential nobody rotates and one that says nothing about who is calling, which is the question every refusal in the estate exists to answer.

The token is held until a minute before expiry and minted again on a 401, once — a second 401 is the server saying no. Both the mint and the 401 replay live on an http.RoundTripper, which is the one place a credential is presented: the generated surface and the six capabilities share the same *http.Client, so there is one header on a request and never two. TestFlows asserts len(Header.Values("Authorization")) == 1 rather than just its value.

A client holding no credentials presents nothing rather than failing. The four operations that take none still answer.

secret.Boot: where a service's own credentials come from

A service needs values before it can serve: a signing key, a database URL, the client secret it mints with. secret.Boot reads them from KMS at startup, over the identity the pod already carries, and holds them in memory.

import "github.com/hanzoai/go-sdk/v8/secret"

values, err := secret.Boot(ctx, "hanzo/cloud", "HANZO_CLIENT_SECRET", "DB_URL")
client := hanzoai.New(hanzoai.Options{Secret: values["HANZO_CLIENT_SECRET"]})

The projected ServiceAccount token is the assertion: IAM exchanges it at POST /v1/iam/oauth/token for a bearer (RFC 7523, grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, which IAM serves from v1.34.99), and KMS answers GET /v1/kms/secrets/<path>/<key>?env=<env> under it. One mint per Boot and exactly one more on a 401 — a second 401 is a refusal, and retrying it is how a boot loop becomes a mint flood. Every key must resolve or the whole Boot fails naming the key, because a map one entry short is a service that starts, serves, and fails at the first request that needed the value. A key is a bare name — no separator, no . or .. — so it can address a secret and nothing else.

environment is default
HANZO_SA_TOKEN the projected ServiceAccount token /var/run/secrets/hanzo/iam/token
HANZO_IAM_URL where the assertion is exchanged https://hanzo.id
KMS_URL where the values live http://cloud.hanzo.svc:8000
HANZO_ENV which environment a name resolves in prod
HANZO_DEV 1 with no token file: read the keys from the environment —

These are the platform's own variable names, so a pod already carrying them needs nothing added; HANZO_IAM_URL is the same host HANZO_ISSUER_URL names for the client, under the name a pod is given it by. HANZO_DEV=1 with no token file is the only path by which a secret reaches the process from the environment, and it says so in the log; it looks each key up under its own name, so DB_URL is DB_URL either way. In production an absent token is an error, never a fallback.

The alternative this replaces is a Kubernetes Secret, which is a base64 field anyone holding get on the namespace reads, mounted where anything in the pod reads it again.

Acting as a subject

client.As(subject) returns the same client — the same 2450 methods — scoped to one tenant subject. It mints a subject-bound token from IAM's act grant, caches it to expiry and re-mints once on a 401, so no method takes a user id: the credential is the scope, and a caller cannot pass the wrong one.

One extension point, an http.RoundTripper on the Configuration's HTTPClient. Signing and the 401 replay are the same object, because they are one question — is this request carrying a live token — asked at the one moment the answer is known.

The act grant is not a call to the platform. It is POST https://hanzo.id/v1/iam/tokens/issue?id=<subject>, on IAM's own host, carrying the operator's own minted access token; HANZO_ISSUER_URL moves it for a private estate, the way HANZO_BASE_URL moves the gateway. The generated PostIamTokensIssue cannot serve: the document states that operation as an address and not as a shape, so the method carries neither the id query nor the camelCase {accessToken, expiresIn} it answers with — the same reason identity.go exists.

A scoped client shares the operator's held token, so scoping costs one act grant and not a second exchange. The operator credential does not travel with the minted one: the subject-bound token is the whole identity of a scoped call.

The two mints spell their answers differently — {access_token, expires_in} from the OAuth endpoint, {accessToken, expiresIn} from the act grant — and identity.go is where that ends.

The six capabilities, and the answer they share

Budget, Policy, Audit, Search, KB and Graph hang off the same client as the generated surface. One word each, the same word in the Go, Python and TypeScript SDKs; Go exports it capitalized because that is Go's rule, and KB is all-caps because that is Go's rule for an initialism. Method names carry no capability prefix: client.Graph.Read, never client.Graph.ReadGraph.

A refusal is a value, not an exception. Every method a gate can refuse answers call.Answer[T], whose value is reachable only through Value() — Go has no sum type, and an ignored error return is loud where an exported field read is silent. Value() hands back a *call.Denied where a budget or a policy said no (with Code, Reason, Product and the Cures that clear it), a *call.Held where a person was asked, and a *call.Fault where nothing decided anything. Answer.Request is the x-request-id on every arm, and it is the join to audit.Event.Request.

Pure reads answer their value directly. Budget.Left, Budget.Balance, Budget.Plan, Budget.Spent, Policy.Check, Audit.List, Audit.All, Graph.Read, Graph.Find, Graph.Resolve, Graph.Walk, Graph.Extract, Graph.Vocabulary, KB.Get, KB.List, KB.Connectors, KB.Connect and KB.Links are not refused, so wrapping them in an Answer would be a branch with one arm.

One rule maps an HTTP answer to an arm, in call.Ask, and no capability varies it. 2xx is the value; a 202 whose body says held is a hold; 402 is a denial whatever the code; a 403 carrying policy_denied, entitlement_required, spend_cap_exceeded or insufficient_balance is a denial; everything else is a fault. That last allow-list is a workaround for one cloud defect: cloud spells "no validated principal" as 403 forbidden, and reading a bare forbidden as a denial would tell an unauthenticated caller their budget said no. The day cloud answers 401 for that, the list goes and the rule collapses to "402 or 403 means denied".

The body says whether a call was held, not the status code. A dozen operations answer 202 for "accepted, working on it" and carry a real schema — a deployment, a preview, a build — so discriminating on the code turns each of them into an approval nobody is waiting on, and the caller waits forever for an answer from someone who was never asked. Only "status":"held" is a hold. That is the discriminator the other Hanzo clients use, so there is one contract rather than one per language.

call.Ask decides the hold before it decodes, because the hold is a property of the answer: a held body need not fit the operation's own schema, and the caller still has to learn a person was asked.

Generation knobs

Every knob is the go: row of hanzoai/openapi's sdks.yaml and nowhere else. scripts/generate.sh is a call site: it names the language and this checkout.

generator: go            take: {.: .}          format: [gofmt, -w]
properties: packageName=hanzoai, withGoMod=false, structPrefix=true, enumClassPrefix=true
flags:      name-mappings <eleven fields>, model-name-mappings Config=StreamConfig
global:     apiDocs=true, modelDocs=true       (--skip-validate-spec is the driver's, for every language)

format is there because the generator's Go output is not gofmt'd — 2655 of 2656 files — and an unformatted Go file reformats itself in every contributor's editor. apiDocs/modelDocs are on where the fleet default has them off: Go is the one client that publishes docs/ as its reference.

--skip-validate-spec is load-bearing. The document is OpenAPI 3.1, which made responses optional on an operation; the validator in 7.14.0 still enforces the 3.0 rule that it is required, and 716 of 2479 operations state their address and not their shape on purpose. The gate is go build, not the validator.

structPrefix=true is what lets an operation carry two tags: the request struct is named <Service>API<Op>Request, so 25 operations reachable from two service groups produce two distinct structs instead of a redeclaration. This used to be recorded here as a hard blocker.

The mappings rename what Go sees and never the wire — the document's key stays as the field's json tag. Each mapped name occurs in exactly one schema, measured against the locked document, so a global mapping reaches nothing else. Three schemas need them, all because Go emits Get<F>/Has<F>/Set<F> beside every field:

schema what collides
o11y.O11yPodOnboarding eight has<Label>Name flags beside the labels; the FIELD HasClusterName and the METHOD HasClusterName are one name. All eight take <label>NamePresent — one family, one spelling, so the next sibling label cannot break the build
o11y.PostableProfile has_existing_observability_tool beside existing_observability_tool
o11y.GettableAgentCheckIn two spellings of two fields (integration_config with integrationConfig, removed_at with removedAt), published together so older AWS agents keep working. The snake one is the legacy wire and takes the suffix — the same correction python and kotlin make

Spell every mapped value EXPORTED. The Go generator takes a mapped name verbatim where python and kotlin re-case theirs, so a camelCase value lands a lowercase field: unexported, invisible to a caller, and skipped by encoding/json in both directions. It compiles, and it drops the value the mapping was written to preserve.

Config=StreamConfig is a model rename, and the collision is with this repo: the document's Config is the MQ stream configuration (POST /v1/mq/streams, Stream.config), whose constructor NewConfig is already hanzo.go's. It is also the one bare Config in a document where every other is qualified — TLSConfig, iam.config, o11y.DiscordConfig.

The drift check

OPENAPI=../openapi ./scripts/generate.sh --check   # non-zero if the client drifted

It regenerates into a temp dir and compares against the files .generated names. Restricting the comparison to those is the load-bearing part: hanzo.go and hanzo_test.go are root *.go files the generator never wrote, so a check that compared the two directories outright would report the hand-written seam as drift on every run and could never pass.

The flows come from flows.yaml

hanzoai/openapi carries a root-level flows.yaml naming six example flows and, per flow, the operationIds to call in order. It is the manifest that makes "the same examples in every SDK" a fact. examples/ and the TestFlows table both follow it — do not pick a different operation here without changing it there first.

All six ship. chat is POST /v1/chat/completions, which the document now types both ways: OpenaiChatCompletionRequest in, OpenaiChatCompletionResponse out. AiAPI also projects the typed Hyperframe compositor endpoints AiFrameGenerate (POST /v1/frame/generations) and AiFrameEdit (POST /v1/frame/edits) with AiFrameGenerateRequest, AiFrameEditRequest, AiFrameResponse, and AiFrameLayer.

hello is get_keys (GET /v1/keys), chosen by probing rather than by reading: it answers 403 with no key and with a bogus one while /v1/keys-zzq9 answers 404, so the refusal is this route's. It replaced bot_authMe, which stopped resolving when cloud began relaying all of /v1/bot through one wildcard.

Names moved, twice, and both are in the past

Every method used to read CloudGetV1Tools: a cloud_ service prefix and the default version, both inside the operationId. The document dropped both, and the method is GetTools. Measured on the two clients: v1.0.1 has 2478 methods over 263 services, of which 1351 carry V1 and 1502 carry Cloud; the current tree has 2502 over 192, of which one carries V1 and none carry the prefix.

Every apparent survivor is correct and must not be "fixed":

  • GetTeamTransactorApiV1Statistics drops only the FIRST v1, because the second is a path segment.
  • 11 methods spell Cloud because cloud is a path segment of the product — GetCloudAccounts, GetPricingCloudPlans. Another 33 are Cloudflare, and a grep for Cloud counts all 44 as leftovers.
  • CloudIntegrationId is a query-parameter setter named after the parameter cloudIntegrationId.

Never derive a name — read it off the generated client or the document.

What cloud has to change, measured

Each of these was probed against api.hanzo.ai or read out of hanzoai/cloud. Each one removes a workaround the three SDKs otherwise write identically.

route what it does what it costs the SDK
every gated route answers 403 forbidden where there is no validated principal call.refusals exists only to tell a refusal from an absent caller
every 402 two bodies: errmap's RFC 9457 envelope with code, and cloud.Refuse's {error, product, reason, message, cure[]} call.denial reads both
POST /v1/authz/check binds {subject, verb, path, grants} and answers {allow, subject, verb, path}, where the document's own description says {sub, obj, act} the SDK sends what the handler binds; the description is what the contract was written from
POST /v1/authz/check decides against grants carried IN THE REQUEST — authz.Can fails closed, so an empty grant set authorizes nothing a three-argument check answers false for every question until cloud reads the caller's grants from IAM, as its description says it does
GET /v1/billing/balance, /usage declare an address and no shape budget models {balance, holds, available, account} and the usage envelope by hand
GET /v1/audit no requestId filter, though every row carries one; pageSize and p are strings audit.Filter.Request narrows client-side
/v1/framework/kb.* the elective middleware answers 404 with the problem envelope to a caller whose org has not enabled the module a 404 there is a refusal wearing an absence; only the plain-text 404 means unrouted
POST /v1/graph/ingest validates before it authenticates — an unauthenticated POST {} answers 400 timestamp "" is not RFC 3339, measured an unauthenticated caller learns the validation rules
/v1/approvals/{id} is not served the held arm is terminal: a caller learns a person was asked and cannot poll
every metered route emits no per-call cost spend is unattributable without a second read

Release state

v1.0.0 is the reverted experiment, is published, and outranks every v0.1.0-alpha.*. The proxy is immutable (cached 2026-07-05), so retagging or deleting it does nothing; the fix was to publish higher.

v1.0.1 is the last tag that predates the rename, and that is a documented fact rather than trivia: go get github.com/hanzoai/go-sdk/v8 resolved to a client whose KeysAPI has CloudGetV1Keys and no GetKeys, so every method name in the README was one a consumer following the install line could not call. The fix was the tag, not a footnote: v1.0.2 is out at 3ad23f3e and is the first tag carrying the renamed operationIds. Do not write a method name into the README that the newest TAG does not carry — cut the tag instead.

The README pins the current tag rather than printing a bare go get, because the proxy's @latest and @v/list are cached for a while after a push while @v/<version>.info is immediate. A pinned line works the second the tag lands; a bare one silently resolves to the previous tag until the index catches up, which is the whole failure this repo once had. Move that pin with every tag — v1.0.2 stays named in the prose as the floor, which is a different fact.

Publishing a Go module is pushing the tag. .github/workflows/release.yml proves the tag compiles and warms the proxy; there is no registry and no token. The proxy reads github.com/hanzoai/go-sdk/v8, which GitHub redirects to hanzo-go/sdk, the canonical repo (the forge has no copy) — so a tag pushed to GitHub is resolvable publicly without anything else being done.

The version is cloud's: cloud's fanout dispatches cicd.yml with spec-ref (the release commit) and spec-version, and the client lane regenerates from https://api.hanzo.ai/v1/openapi.json and cuts that version, the same number npm and PyPI hanzoai get. Run by hand, the lane is: write .spec-lock (ref = the release commit, sha256 = of the served JSON), then SPEC=<served json> OPENAPI=<hanzoai/openapi at GitHub main> ./scripts/generate.sh.

Every job here runs on linux-amd64, and a GitHub runner exists only for a bound App installation. cloud's apps/provider/github_runner.go mints a JIT runner per queued job in the job's org, and ignores a delivery whose installation no Hanzo org has connected ("unknown installation"). The hanzo-platform installation on hanzo-go must be connected to org hanzo (it shows in GET /v1/provider/github/installations for that org); unbound, every run queues, the next dispatch cancels it, and the fanout still counts it started because the run has a job.

Confirming that from a Hanzo machine takes care, because two settings route around the thing under test: GOPRIVATE=github.com/hanzoai/* makes the fetch skip the proxy, and url.https://git.hanzo.ai/hanzoai/.insteadOf https://github.com/hanzoai/ aims the direct fetch at the forge. A green go get under both proves the forge has the tag and says nothing about the registry. Exporting GOPRIVATE= does not undo it — Go falls back to its go env file when the variable is empty, so the override has to be a pattern that matches nothing. GOVCS=off is what makes the check honest: it forbids version control outright, leaving the proxy as the only source. From an empty module:

GOMODCACHE=$(mktemp -d) GOFLAGS= GOVCS=off GOPROXY=https://proxy.golang.org \
GOSUMDB=sum.golang.org GOPRIVATE=example.invalid GONOPROXY=example.invalid \
GIT_CONFIG_GLOBAL=/dev/null go get github.com/hanzoai/go-sdk/[email protected]

A go.sum line for the version means sum.golang.org vouched for it as well. Two files are in the tag but not in the artifact: AGENTS.md and CLAUDE.md are symlinks to LLM.md, and a module zip carries no symlinks. Everything else is byte-identical, so a diff of the two is a real integrity check.

There is no CHANGELOG.md, and one should not come back. The generator that wrote the old one left with the client it described, so it stopped at 0.1.0-alpha.7 while three releases shipped past it — a file that says nothing happened since July reads as fact. The tag list is the record.

Testing

hanzo_test.go stands up an httptest server answering both IAM's mint and the platform API, and asserts for each flow that the client sends the documented method and path plus exactly one Authorization: Bearer. If a regeneration moves an operation, that test fails instead of the examples silently calling a wrong endpoint.

capabilities_test.go does the same for the six, a row per method, asserting the exact request — method, path, query and body — beside the decode. That half of a client contract is the half a decode cannot check: a method that posts the right shape to the wrong address passes every test that only reads the reply. It also walks each arm end to end: a 402 in both bodies cloud writes, a policy_denied 403, a held 202, and a bare forbidden that must NOT read as a denial.

identity_test.go is the credential: the client_credentials exchange with its resource, the held token, the single 401 replay with the body it carried, the act grant As rides on, and the assertion that concurrent first calls mint once between them.

Two examples run to completion with no credential, and they are the pair that proves the auth contract from both ends against the live API: models is a public operation answering everyone, and errors is a gated route answering 403 to a client that cannot say who it is. errors is also the way to check a base URL end to end.

$ go run ./examples/models              # no credentials set
200 OK  112 model(s)
$ go run ./examples/errors
status    403 Forbidden
$ HANZO_CLIENT_ID=... HANZO_CLIENT_SECRET=... go run ./examples/six

examples/six is the five-step composition: what the wallet holds decides whether to ask, the wallet's own account names the org a policy question is scoped to, a search states its degradation, a graph write answers a request id, and that id finds the row the server wrote about it.

This replaces the suite that shipped with that client, whose ok was 187 SKIP / 25 PASS against a disabled mock server and asserted nothing about the API surface.