The document api.hanzo.ai serves now (x-api-version v8.5.1026). The build is quiet: the four warnings the generated code raises (a cref to `int?`, null checks on value types) are named in the csproj.
3.4 KiB
hanzo-csharp/sdk — notes for the next person in here
Home: github.com/hanzo-csharp/sdk. hanzoai/csharp-sdk is an archived pointer
to it. Checkout: ~/work/hanzo-csharp/sdk. NuGet id Hanzo; namespaces
Hanzo.AI, Hanzo.AI.Api, Hanzo.AI.Client, Hanzo.AI.Model.
What is generated and what is not
src/Hanzo.AI/{Api,Client,Model}/** is generated by hanzoai/openapi
generate.py from the csharp row of its sdks.yaml. The driver owns exactly
the files listed in .generated; a hand edit there is caught by
./scripts/generate.sh --check. Everything else is the repo's: the csproj
(package id, version, TFM), Gateway.cs, tests/, examples/, scripts/.
The shape, and how to measure it
find src/Hanzo.AI/Api src/Hanzo.AI/Client src/Hanzo.AI/Model -name '*.cs' | wc -l # 3435
ls src/Hanzo.AI/Api/*.cs | wc -l # 130
Measured at hanzo-inc/cloud v8.5.1026 (834987f2): 1,908 paths, 2,649
operations, 3,197 schemas. 419 operations carry no responses and become
void methods.
Why the row is shaped the way it is
httpclient, notgenerichost. generichost names a response type per operation from itsresponses; with 419 operations publishing none it references one type per such operation it never emits (4,956 CS0246). httpclient builds clean.- Nullable primitives +
conditionalSerialization. The default types an optional int/decimal/bool as a plain value type with EmitDefaultValue=false, soTemperature = 0never reaches the wire and every unset bool is sent asfalse. The normalizer makes themT?; conditional serialization sends a property only once assigned.WireTests.SendsTheCompletionAndItsBoundspins the request body to exactly the keys that were set. - Templates
modelAnyOf/modelOneOf: one line each, the getter of a union member isGet{{pascalcase baseType}}; withint?members the stock template wroteGetInt?(). - Model name mappings:
Exception,Index,Numbercollide with BCL types every generated file imports (CS0104).
Building
./scripts/dotnet build src/Hanzo.AI -c Release # ~15s
./scripts/dotnet test tests/Hanzo.AI.Tests -c Release
./scripts/dotnet build examples -c Release
HANZO_API_KEY=$(hanzo auth token) ./scripts/dotnet run --project examples -c Release -- hello
scripts/dotnet uses a .NET 10 SDK on PATH or installs one into ~/.dotnet
(no root) — the CI runner image carries no .NET. Tests and examples target
net8.0 with RollForward=Major, so the one SDK runs them.
Publishing, and what it waits on
release.yml publishes on a push to main whose csproj <Version> nuget.org
does not serve. It reads NUGET_API_KEY from KMS org hanzo, env prod —
absent today: an API key from the nuget.org account that owns Hanzo,
scoped to push that package, is owed there. The Hanzo id is unclaimed on
nuget.org; the first push claims it.
The org needs, like every projection org: the hanzo-platform GitHub App
installed and bound to the Hanzo org (it mints the per-job runners), and org
secrets KMS_CLIENT_ID, KMS_CLIENT_SECRET, GH_PAT.
The lane
hanzo-inc/cloud's release dispatches cicd.yml with spec-ref and
spec-version (its fanout PROJECTIONS list names this repo). hanzoai/ci
regenerates at that ref, runs hanzo.yml's test:, rewrites <Version> via
client.version, commits, tags v<version>, and pushes; the push runs
release.yml.