Three numbers this repo publishes were true only under conditions it did not state, so a reader who followed the instructions measured something else: - `libhanzo.a` is 349 MB at Release. `cmake -B build && cmake --build build` leaves CMAKE_BUILD_TYPE empty, which inlines nothing and keeps every template instantiation: the same 2664 objects archive to 1281 MB. The size paragraph now carries the flag it was measured with, and both figures. - The templates' cost was documented as defect classes with no measurement. Regenerating with no `-t` and syntax-checking all 2663 sources lands 24 errors in two files, not one: 8 in ModelBase.h from ConsoleSettings's std::vector<Object>, and 16 in Post_event_request.cpp from the oneOf shape. Whoever re-derives the templates has to check both. - README's FetchContent snippet names GIT_TAG v8.0.0 and this repo has zero tags, so its first install instruction fails. The lane cuts that tag on resync; until it does, a commit is what a consumer can pin. Generated sources are untouched — `generate.py cpp --check` still reports clean.
16 KiB
LLM.md — hanzo-cpp/sdk
Guidance for AI agents working in this repo.
What this is
The full Hanzo cloud SDK for C++ — a typed client over the entire /v1
surface (AI, agents, inference, compute, data, network, security/IAM/KMS,
platform, observe, web3). Generated from the openapi.yaml that hanzoai/cloud
emits, at the commit .spec-lock names — the same document, at the same kind of
pin, as every other Hanzo client.
Canonical role
- This is the real code for the C++ full cloud SDK line:
hanzo-cpp/sdk.hanzoai/cpp-sdkis a rename redirect to it (gh api repos/hanzoai/cpp-sdk --jq .full_name→hanzo-cpp/sdk), so the two are one repo, not two. - Separate line: the AI/agents lib lives at
hanzo-cpp/ai. Don't merge the two. - One impl, one place. DRY. Discovery repos link OUT.
Generation — one place, one way
hanzoai/openapi owns the invocation (generate.py) and the matrix of language
projections (sdks.yaml). C++ is a row there like every other language, and
scripts/generate.sh is a call site that says "cpp, into this checkout" and
nothing else. Nothing about HOW this SDK is generated lives in this repo.
OPENAPI=~/work/hanzo/openapi ./scripts/generate.sh # regenerate include/ and src/
OPENAPI=~/work/hanzo/openapi ./scripts/generate.sh --check # non-zero on drift
This repo used to own its whole invocation, and both reasons it gave are
gone. The first was templates: four cpp-restsdk mustache overrides are
required before the output compiles at all — measured, without them the library
fails with 8 errors in ModelBase.h — and the argument was that a template is a
FILE that must sit beside the call. Right about the risk, wrong about which
call: the call is generate.py's emit(), so the overrides now live at
templates/cpp-restsdk/ in the driver repo, one directory from the flags they
go with. The second was the generator version, and it expired (below).
What the departure cost is the reason not to repeat it: that script named
hanzoai/openapi's hanzo.yaml at branch main while this repo's hanzo.yml
already declared cloud's openapi.yaml, and it re-derived the jar fetch, the
YAML-to-JSON conversion, --skip-validate-spec and the drift check — four
copies of logic the driver owns once. generate.py cpp --check reports clean
against the tree that script produced: byte for byte, 5327 files.
Both inputs arrive as VALUES. $SPEC is the document, already fetched at the
pinned ref and digest-checked; $OPENAPI is the checkout holding the driver.
hanzoai/ci's client lane sets both, because it holds the one credential that
reads the forge. Without $SPEC the driver reads .spec-lock and fetches the
commit it names from git.hanzo.ai, refusing if the bytes hash to anything
else. The forge serves its API at /v1/, not /api/v1/, and the wrong path
404s in a way that reads like a rejected credential.
THE DOCUMENT MOVED — cloud's emission, not a projection of it
This client used to read hanzoai/openapi's hanzo.yaml at branch main, with
no lock at all. It now reads what hanzoai/cloud emits, at a commit. Both halves
of that mattered: a branch name is not a version, and hanzo.yaml is a
projection of the same bytes rather than a second authority.
Measured across the two documents at this ref, so the trade is on the record rather than argued:
| hanzo.yaml | cloud openapi.yaml | |
|---|---|---|
| routes | 2456 | 2479 |
| routes the other lacks | 0 | 23 |
| operations with a requestBody | 673 | 694 |
| operations with a typed 2xx | 1622 | 1645 |
| generated methods | 2456 | 2502 |
…returning void |
834 | 834 |
Nothing is lost: cloud's routes are a strict superset. And the one thing
publish.py adds for C++ — a default response injected into every operation
that declares none — buys exactly nothing here: a default with no content
produces the same void return that no responses does, so both documents
yield the identical 834 void-returning methods. The projection's cost is real
(23 routes and 46 methods), its benefit for this language is zero.
The generator version — 7.14.0, the fleet's one pin
This repo used to state a 7.24.0 floor of its own, and it was true when
written: two defects in the generator's type resolution left 10 translation units
uncompilable, neither reachable by a template. Both defects lived in schemas the
document no longer carries — vector_NamedVectors/vector_DenseVector under
additionalProperties, and framework_Document.docstatus — so the floor was a
fact about a document, not about cpp-restsdk.
Re-measured at the locked ref, 7.14.0 and 7.24.0 emit the same library: apart
from the generator string in each file's header comment and blank lines, exactly
one file differs, and the difference is a doc comment on
ConsoleSettings::getOidcConfig. 7.14.0 builds clean — 2663 sources, 0 errors.
So there is no cpp-specific version any more: sdks.yaml pins one generator for
everyone and this row needs no exception. The fleet moves as one when it moves.
The document reaches the generator as JSON, and that is the whole of the
snakeyaml story. swagger-parser hands YAML to snakeyaml, which refuses anything
over 3 * 1024 * 1024 = 3145728 code points and reports the refusal as
Issues with the OpenAPI input — which reads like a malformed spec and is not.
-DmaxYamlCodePoints lifts the cap and is NOT what the driver uses: it is
honoured by 7.24.0's parser and ignored by 7.14.0's. JSON avoids snakeyaml on
every version, so one mechanism serves every language and none of them carries a
ceiling the document will keep growing into.
One flag, and it is the fleet's flag
name-mappings: removed_at=removed_at_legacy,integration_config=integration_config_legacy,
in the cpp row.
o11y.GettableAgentCheckIn declares integration_config AND integrationConfig,
removed_at AND removedAt — the snake spellings are live wire, published so
older agents keep working. C++ camel-cases a property into its accessor, so each
pair lands on one method declared twice and the library does not compile (5
errors). Renaming the ACCESSOR keeps both wire keys — measured, all four are
present in the emitted model, each under its own name. The python, go, java,
kotlin, ruby and php rows correct the same two schemas the same way.
templates/cpp-restsdk/ — four overrides, in hanzoai/openapi
Forked from 7.24.0 stock, so a generator bump re-derives them rather than merging them. Each hunk is commented in place; none of them says anything about the Hanzo API. Deforming the document to suit one C++ generator would degrade the other language projections that read the same file — do not do it.
They are load-bearing, and the cost of dropping them is measured, not asserted:
regenerate this document with the same flags and no -t, then syntax-check all
2663 sources, and 24 errors land in two files — 8 in
include/hanzo/ModelBase.h (defect 4, reached from ConsoleSettings.cpp's
std::vector<Object>) and 16 in src/model/Post_event_request.cpp (defects 1–3,
the oneOf shape). Both root causes are below; check both if you ever re-derive.
- A oneOf class cannot be a field of another model. It is generated outside
the
ModelBasehierarchy and declares only explicit-Targettemplates, so nothing resolves it as a member. The override derives it fromModelBaseand adds the non-templatefromJson/fromMultiPartpair, trying each alternative in declaration order. - oneOf visitors call members the alternatives do not have —
arg.toJson()whereargis astd::shared_ptr<Model>or a primitive.ModelBasealready overloads every alternative kind; the template just did not use it. - oneOf explicit instantiations are HTML-escaped —
{{.}}where the header uses the triple form, emittingfromJson<std::shared_ptr<Object>>. - A free-form
objectis held BY VALUE.Objectis aModelBasesubclass, but the overload set covers primitives andstd::shared_ptr<T>only, sotoJson/fromJson/toHttpContent/fromHttpContenton a container ofObject— or on a oneOf whose alternatives are by-value models — find no overload. The override addsis_base_ofoverloads for all four, plus theObject.hinclude that oneOf headers omit. - An API response container and its element type are resolved separately,
so an array of free-form objects declares
std::vector<Object>and is filled withpush_back(std::shared_ptr<Object>). The override reads the element type off the container itself (::value_type/::mapped_type).
Plus two in the enum path, both template-shaped and both fixed here:
isPrimitiveType and isEnum are not exclusive, so an integer-backed enum
declared its setter twice and defined it once; and the conversion helpers were
declared over utility::string_t in the header while defined over the property's
own dataType in the source, with string literals in bodies that must return a
number. The literal form now switches on the property's isNumeric — note that
enumVars' own isString is false for utility::string_t and is the wrong
discriminator; using it silently emits bare identifiers (if (value == user)).
Mustache comments must not contain {{ or }}. Such a comment closes at the
inner tag and dumps its remainder into the generated C++. That cost two full
regeneration cycles here; the templates are clean now, keep them so.
Layout
include/hanzo/…,src/…— generated. Never hand-edit;--checkenforces it.CMakeLists.txt,cmake/— the repo's own. The generator'sCMakeLists.txtandConfig.cmake.inare dropped before the tree lands: thehanzo::hanzotarget, the export set andHANZO_BUILD_EXAMPLESare this repo's contract with a consumer, not a generator artifact.examples/— the six canonical flows.templates/— GONE from this repo; the overrides live inhanzoai/openapiattemplates/cpp-restsdk/, beside the row whose flags they go with.
Namespaces are hanzo::api and hanzo::model; the include root is hanzo/.
Every call returns pplx::task<T>.
Examples — the six canonical flows
hello, chat, money, store, agent, tools, named and ordered by
hanzoai/openapi's flows.yaml. Read that file; do not re-derive them — a
sibling lane shipped divergent flows by deriving its own and had to reconcile.
It names the exact operationIds per flow, and a gate upstream asserts every one
of them exists in the merged document.
HANZO_API_KEY, HANZO_BASE_URL (default https://api.hanzo.ai) and
HANZO_ORG_ID resolve in ONE place — examples/hanzo.cpp — not once per flow.
store deletes in a scope guard; agent polls the run list to a terminal state.
Four flows changed route when the document did, and the rule they follow is "demonstrate a call the document TYPES". A generated client can only be as typed as its document, and several of the obvious addresses are declared with no body and no response — the generated method then takes nothing and returns nothing, which cannot demonstrate anything. Where that was true, the flow moved to the typed route for the same job and says so in its header comment:
| flow | was | is | why |
|---|---|---|---|
hello |
bot_authMe |
get_ai_account → Envelope |
the old route is in neither document |
chat |
/v1/chat/completions |
research_web → Report |
completions declares no body and no response |
money |
/v1/billing/{balance,usage} |
get_finance_{credits,usage} |
billing declares no parameters and no response |
tools |
POST /v1/mcp (JSON-RPC) |
aiMCPTools → AiMCPSurface |
/v1/mcp is in neither document |
agent kept its route and lost its input: postAgentsByRefRun is declared with
no request body and no response, so it starts the run and reports nothing — the
id, the status and the output are read from the typed run LIST instead.
None of this came from the document move. Every one of those routes is untyped
or absent in hanzo.yaml too, measured by regenerating from it: the committed
tree simply predated the change. Do not "restore" these to the old operations —
they do not exist, and a client cannot invent a shape the document does not
declare.
Build
cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build -j"$(nproc)"
cmake -B build -DHANZO_BUILD_EXAMPLES=ON && cmake --build build -j"$(nproc)"
Needs C++17, CMake 3.20+, cpprestsdk + Boost + OpenSSL (libcpprest-dev 2.10.19
from Ubuntu universe resolves cleanly, and so do find_package(cpprestsdk) and
find_package(Boost)).
KNOWN FUTURE MIGRATION — cpprestsdk is ARCHIVED upstream by Microsoft. This
is a decision with an expiry, recorded so it is not a surprise later. It ships
because cpp-restsdk is the only openapi-generator C++ target that produces a
compiling library from this document — cpp-qt-client fails on defects no
template reaches, and the rest are embedded or engine targets (see below). An
archived dependency gets no security fixes, so the trigger to revisit is
whichever comes first: a CVE in cpprestsdk, its removal from Ubuntu universe, or
a C++ generator target that compiles from this document without an archived HTTP
stack. When that happens the move is a generator change plus new
templates/<target>/ overrides — the document, the seam and the six flows do
not move.
Scale is not a problem, and these are measured rather than estimated. At document
49389cf9, aarch64 Ubuntu 24.04, g++ 13.3, generator 7.14.0, -j20,
-DCMAKE_BUILD_TYPE=Release, from a clean tree: 2663 sources / 2664 headers,
192 API classes, 2462 models, 2502 operations; the library builds with 0
errors and libhanzo.a is 349 MB; the six examples then build with 0
errors. Generation is well under a minute now that the document reaches the
generator as JSON. The file count moves with every resync — re-measure, do not
quote.
Quote the build type with the archive size or the number means nothing. 349
MB is Release. cmake -B build && cmake --build build leaves CMAKE_BUILD_TYPE
EMPTY, which is not a smaller build — it is an unoptimized one that inlines
nothing and keeps every template instantiation, and the same 2664 objects then
archive to 1281 MB, 3.7x. Both figures are this tree at this document; they
differ only in that one flag.
The generators that were measured and rejected, so nobody re-runs the
experiment: cpp-qt-client (drags in Qt6 Core + Network + Gui, and 31 of its
failures are models it references but never emits — not template-reachable);
cpp-tiny (not a library at all — emits platformio.ini, root.cert,
src/main.cpp; an Arduino/PlatformIO target); cpp-ue4 (Unreal); cpp-tizen
(Samsung Tizen).
CI
hanzo.yml declares the gates, .github/workflows/cicd.yml is the seven-line
call into hanzoai/ci. Wired, and UNEXERCISED — do not claim it is green.
Two distinct failure modes, both observed, neither fixed by anything in this
repo:
- On
hanzo-cpp/sdk, both runs to date arecompleted / startup_failurewith zero jobs created — GitHub never got as far as scheduling one. It is not a missing reusable:hanzoai/ciis public,@v1resolves to 18bd16c, and itsbuild.ymlis present (57 KB). - On the
hanzoai/*repos the same workflow instead satqueuedforever, for capacity rather than permissions:hanzoai/cidefaults toruns-on: [hanzo-build-linux-amd64]and nothing was registered under that label. That label is now served by thegit-runnerfleet on git.hanzo.ai (StatefulSetgit-runner, nshanzo) — the arc pool this note used to name was retired. Re-measure before claiming either state; do not quote this.
Actions itself is enabled and unrestricted (enabled_repositories: all,
allowed_actions: all), so neither is a permissions problem. Verification here
is a clean-clone local build, and that is where every number above comes
from.
C++ has no registry, so the release artifact is a tagged GitHub release carrying
headers + library, built by binaries: on every push and published on a tag.
Brand rules (hard — enforce in all docs/code)
- Never call Hanzo an "LLM gateway" or position it against LiteLLM. It is a full AI SDK / AI cloud, not a proxy.
- Paths are
/v1/…only — never an/api/prefix. - Zen models are Hanzo's own family — never reference upstream model names.
- Voice: "Hanzo — the Open AI Cloud." Modern, crisp, developer-first.
Pointer
Full SDK model + one-way rules: ~/work/hanzo/SDK-ARCHITECTURE.md.