mirror of
https://github.com/hanzoai/ai.git
synced 2026-11-20 14:13:23 +00:00
This surface reaches api.hanzo.ai through ONE `app.All("/v1/*")` in the host, so
reading the host's router alone published `/v1/{wildcard1}` and seven operations
for the whole model API. No generated SDK carried chat completions, no MCP tool
list carried one, and hanzoai/cli grew a `{wildcard1}` command because that is what
the document named. The host can ask what is behind its own door — App.Patterns
already answers the address and the verb — but a published operation owes a reader
a third thing, and there was nowhere to get it: 190 patterns, 295 registrations,
0 sentences reachable from outside this package.
Go drops comments at compile time, so a running program cannot read the sentence
its own handler was documented with. cmd/routerdoc lifts it before the build, from
the one place it already lives: `App.Router(path, &controllers.X{}, "GET:Fn")` names
the handler machine-readably in the same call that names the address, and 67 of 68
handlers already carried a doc comment. Nothing new is declared and there is no
table to keep in step — same law, and the same identifier strip, as zip's
cmd/zipdoc for typed handlers.
routers.Prose() 295 of 295 registrations: 87 rows lifted from handler doc
comments, plus the resource half routers/openapi.go already
derives from the same table that registers it
82 of those are the bare /v1 inference surface — chat/completions, models,
embeddings, messages, rerank, audio/speech, images/generations and the rest
Two tests, one bijection: every route App registers has a sentence, and every
sentence is about a route App registers. A missing one is an operation no SDK, MCP
tool or CLI command can describe; an extra one is a phantom. cmd/routerdoc's own
test re-derives wired_gen.go and compares, because an artifact checked against
itself passes while the comment it was lifted from moves on.
Six doc comments are rewritten so the sentence leads rather than the address:
ReloadModelConfig documented `/api/reload-model-config`, a prefix this service has
never served, and four in model_access.go opened mid-clause ("(GET /v1/models/…)
returns …"). The strip drops a leading subject WITH its copula, so godoc's idiomatic
"AudioSpeech is the OpenAI-compatible TTS endpoint" reads as "The OpenAI-compatible
TTS endpoint" once it is out of Go's namespace.
Co-authored-by: Hanzo Dev <[email protected]>