Files
zeekay 89f7199f7f client: regenerate from hanzo-inc/cloud@834987f231 (8.5.1026)
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.
2026-11-06 13:07:55 -08:00

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, not generichost. generichost names a response type per operation from its responses; 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, so Temperature = 0 never reaches the wire and every unset bool is sent as false. The normalizer makes them T?; conditional serialization sends a property only once assigned. WireTests.SendsTheCompletionAndItsBounds pins the request body to exactly the keys that were set.
  • Templates modelAnyOf/modelOneOf: one line each, the getter of a union member is Get{{pascalcase baseType}}; with int? members the stock template wrote GetInt?().
  • Model name mappings: Exception, Index, Number collide 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.