Files
zeekayandGitHub fcac09e8b2 enso: five models, an effort ladder, and billing by the rung that served (#126)
enso-auto, enso-flash, enso-pro, enso-max and enso-ultra are sold; nothing is
named free. The effort ladder reads router.depth: instant, low, medium, high,
max. With no effort, or auto, the router decides: it starts at Flash and goes
deeper only on its prefer table for the request's task or on Kai's effort
decision (one choice over the ladder's words, counted at 0.9 within 600 ms).

Every Enso tier is served to every caller. The gate orders its rungs by who
pays and tells the engine (X-Hanzo-Classes): ours, premium, free for a paying
caller, premium only while the wallet holds cash; free, ours at no charge for
one nothing pays for, in limited mode, never another model. Fast mode puts
premium first where cash pays it.

The engine's X-Hanzo-Class bills the answer: ours as the grant says, premium
and any fast answer from the wallet's cash at list on every plan, free
nothing. Fast bills 2x enso-auto and Flash, 3x Pro and Max, 4x Ultra.
UsageEvent.Lane and LimitAsk.Lane name the kind for the host.

Prices are the catalog's quotes: pro 3.30 / 16.50 / 0.165 / 4.125, max 4.30
/ 21.50 / 0.215 / 5.375, ultra 5.236 / 26.18 / 0.2618 / 6.545. An answer to
a router id is named for it; the pool's id and its no-cost models are never
listed, and a caller naming one is refused.

Claude-Session: https://claude.ai/code/session_015XYKLnBbrbajqj1GpRydF8
2026-11-07 20:49:12 -08:00

549 lines
21 KiB
Go

// Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package routers
import (
"reflect"
"slices"
"strings"
"github.com/zap-proto/zip"
"github.com/hanzoai/ai/controllers"
)
// The published API description of this service is DERIVED from the router that
// serves it — never written a second time.
//
// A hand-maintained spec beside a route table is two sources for one fact, and
// they drift in the direction that hurts: the spec is what customers and every
// generated SDK believe, so it goes stale silently while the routes move. The
// checked-in swagger.json in this repo is the standing proof — it still describes
// `/api/<verb>-<noun>`, a base path this service has never served.
//
// So [Document] is the ONE accessor, and it is a whole document rather than a
// fragment somebody else completes. hanzoai/cloud reaches this surface through a
// single `/v1/*` entry point and publishes what comes back as the fleet's contract,
// so what it asks for is everything an operation owes a reader: the address, the
// verb, the sentence, and — where this service declares one — the body.
//
// Membership comes from [App.Patterns], the live route table, because that is
// the only thing that knows what answers. Detail comes from wherever it is
// already written: the resource table for the half it generates, the doc comment
// on the handler for the rest. Nothing is copied.
// Document is everything this service serves, as one OpenAPI 3.1 document.
//
// The result is deterministic: it reads the route table and two package-level
// tables, and nothing here reads the clock, the environment, or a random source.
func Document(app *zip.App) map[string]any {
described := items()
said := map[string]Doc{}
// Every named type the document ends up referring to, gathered as the paths are
// built rather than from a list beside them, so a shape cannot be published
// without its components.
named := map[string]reflect.Type{}
answered := map[string]map[string]any{}
taken := map[string]map[string]any{}
routes := map[string]bool{}
for _, w := range wired {
path := openAPIPath(w.Path)
said[w.Method+" "+path] = Doc{Summary: w.Summary, Description: w.Description}
if a, ok := controllers.Answers()[w.Handler]; ok {
answered[w.Method+" "+path] = answer(a, named)
}
if b, ok := controllers.Takes()[w.Handler]; ok {
taken[w.Method+" "+path] = take(b, named)
}
if controllers.Routed()[w.Handler] {
routes[w.Method+" "+path] = true
}
}
paths := map[string]any{}
for pattern, methods := range Patterns(app) {
path := openAPIPath(pattern)
for _, registered := range methods {
for _, verb := range expand(registered) {
item, ok := paths[path].(map[string]any)
if !ok {
item = map[string]any{}
paths[path] = item
}
generated, _ := described[path].(map[string]any)
o, _ := generated[strings.ToLower(verb)].(map[string]any)
if o == nil {
// A hand-written route. Its body is the OpenAI wire format or a
// stream, not this service's envelope, so the only honest thing
// to say about it is what its handler says.
o = map[string]any{}
}
d, ok := said[verb+" "+path]
if !ok {
// One handler answering every verb says one thing about all of
// them, and the table keeps the star it was registered under.
d = said["* "+path]
}
if d.Summary != "" {
o["summary"] = d.Summary
}
if d.Description != "" {
o["description"] = d.Description
}
// A hand-written route's own body. Only where the generated half said
// nothing: an operation the resource table describes is described by
// the table, and this cannot overrule it.
if _, told := o["responses"]; !told {
r, ok := answered[verb+" "+path]
if !ok {
r = answered["* "+path]
}
if r != nil {
o["responses"] = r
}
}
// And the body it reads, on the same terms: the generated half
// speaks for itself, a hand-written route through the takes table.
if _, told := o["requestBody"]; !told {
b, ok := taken[verb+" "+path]
if !ok {
b = taken["* "+path]
}
if b != nil {
o["requestBody"] = b
}
}
// A routed call's bounds and the model that served it, on the
// operations whose handler reads and writes them.
if routes[verb+" "+path] || routes["* "+path] {
budget(o)
}
// Named HERE because this is the one place that knows both the verb
// and the address. items() builds operations before it knows which
// verbs the router actually registered for them.
o["operationId"] = zip.ID(verb, path)
// The PRODUCT this operation belongs to. hanzoai/cloud counts a
// product by the tags its operations carry, so an untagged operation
// belongs to nothing: it reaches the composed document and then
// disappears from every per-product total, which is how a surface
// loses whole products with the path count unchanged.
if t := product(path); t != "" {
o["tags"] = []any{t}
}
// A templated segment NAMES a parameter, and an operation that
// leaves it undeclared reaches a client with the value in its
// address and not in its signature — `get_videos_by_id(self)`
// took no id and requested the literal "{id}". Merged rather
// than assigned, so a hand-written list survives.
if names := pathParams(path); len(names) > 0 {
params, _ := o["parameters"].([]any)
have := map[string]bool{}
for _, p := range params {
m, ok := p.(map[string]any)
if !ok || m["in"] != "path" {
continue
}
if n, _ := m["name"].(string); n != "" {
have[n] = true
}
}
for _, n := range names {
if have[n] {
continue
}
params = append(params, map[string]any{
"name": n, "in": "path", "required": true,
"schema": map[string]any{"type": "string"},
})
}
o["parameters"] = params
}
item[strings.ToLower(verb)] = o
}
}
}
// Every type the resource table names, closed over what those types refer to.
// The roots come from the table rather than a list beside it, so a resource
// cannot publish a shape the document does not carry.
var roots []reflect.Type
for _, r := range resources {
if r.shape != nil {
roots = append(roots, reflect.TypeOf(r.shape))
}
}
schemas := components(roots, named)
schemas["Envelope"] = envelope()
return map[string]any{
"openapi": "3.1.0",
"info": map[string]any{"title": "Hanzo AI", "version": "v1"},
"paths": paths,
"components": map[string]any{"schemas": schemas},
}
}
// expand is the verbs one registration publishes.
//
// A route registered "*" is ONE handler answering every method, so the document
// has to choose which of them to name. It names the five a client calls. TRACE
// echoes the request back and is the Cross-Site Tracing vector; OPTIONS is CORS
// preflight, which a browser sends and a person never does — advertising either
// puts a method in every generated SDK, CLI and tool list that nobody should
// reach for.
func expand(registered string) []string {
all := []string{"DELETE", "GET", "PATCH", "POST", "PUT"}
if registered == "*" {
return all
}
registered = strings.ToUpper(registered)
if slices.Contains(all, registered) {
return []string{registered}
}
return nil
}
// budget publishes what a routed call reads and answers beside its body: the two
// bounds as optional header parameters, and the model that served as a header of
// its success. A client generated from the document then takes the bounds as
// arguments of the call rather than as headers a caller has to know to set.
func budget(o map[string]any) {
// The effort and fast-mode prose, on the operation, so every client generated from
// the document can send both.
desc, _ := o["description"].(string)
o["description"] = strings.TrimSpace(desc + "\n\n" + effortProse)
params, _ := o["parameters"].([]any)
o["parameters"] = append(params,
map[string]any{
"name": "X-Fast", "in": "header", "required": false,
"description": "Fast mode, as the body's `fast`: \"1\" or \"true\".",
"schema": map[string]any{"type": "string"},
},
map[string]any{
"name": controllers.MaxCostHeader, "in": "header", "required": false,
"description": "The most this request may cost, in USD per 1,000 tokens. Routing picks only " +
"models under it; an org's own ceiling fills it when it is absent, and the lower of the two holds.",
"schema": map[string]any{"type": "number", "minimum": 0},
},
map[string]any{
"name": controllers.MaxLatencyHeader, "in": "header", "required": false,
"description": "The slowest model this request accepts, in milliseconds.",
"schema": map[string]any{"type": "integer", "minimum": 0},
},
)
responses, _ := o["responses"].(map[string]any)
ok, _ := responses["200"].(map[string]any)
if ok == nil {
return
}
headers, _ := ok["headers"].(map[string]any)
if headers == nil {
headers = map[string]any{}
ok["headers"] = headers
}
headers[controllers.RoutedModelHeader] = map[string]any{
"description": "The model that served a routed request, one that named auto or an id the router " +
"resolves. The body's model field names the same id.",
"schema": map[string]any{"type": "string"},
}
// The body says why: a routed answer carries the router's decision beside it, on
// the whole body or the first chunk of a stream.
content, _ := ok["content"].(map[string]any)
for _, media := range content {
m, _ := media.(map[string]any)
if m == nil || m["schema"] == nil {
continue
}
m["schema"] = map[string]any{"allOf": []any{m["schema"], map[string]any{
"type": "object",
"properties": map[string]any{"routing": routingSchema},
}}}
}
}
// effortProse is how a routed call states the reasoning it asks for, and fast mode.
const effortProse = "Reasoning effort is `reasoning_effort` (Responses: `reasoning.effort`). Send `auto`, or nothing, " +
"and enso-auto's router decides: it starts at Enso Flash and moves to a deeper tier only when the router or Kai " +
"judges the request needs it. The ladder: `instant` (no reasoning; `none` and `minimal` read instant) serves " +
"enso-flash with thinking off, `low` enso-flash, `medium` enso-pro, `high` enso-max, `max` enso-ultra (`xhigh` " +
"reads max). On a tier named outright the effort sets only how hard it thinks, and `instant` turns thinking off. " +
"Fast mode is `fast: true` (or `X-Fast: 1`): billed from prepaid balance on every plan at 2x the price on " +
"enso-auto and enso-flash, 3x on enso-pro and enso-max, 4x on enso-ultra, it asks prepaid rungs first, and a " +
"payer with no money of its own is refused prepaid_required."
// routingSchema is controllers.Routing: what a router decided for one request, and why.
var routingSchema = map[string]any{
"type": "object",
"description": "What the router decided for this request and why, present when one routed it (a model " +
"Enso routes by reasoning depth). Every field is one the router read or wrote; it reports no score, " +
"expected cost or latency because it weighs none.",
"required": []any{"router", "chosen", "candidates", "inputs", "reason"},
"properties": map[string]any{
"router": map[string]any{"type": "string", "description": "The router that decided: enso."},
"by": map[string]any{"type": "string", "enum": []any{"effort", "default", "router", "kai"},
"description": "What chose the tier: the request's effort, the router's start, its table for the task, or Kai's effort decision."},
"chosen": map[string]any{"type": "string", "description": "The model the request is served at."},
"candidates": map[string]any{
"type": "array",
"description": "Each model the router's table names, with the reasoning depths that read it, shallow to deep.",
"items": map[string]any{
"type": "object",
"required": []any{"model", "depths"},
"properties": map[string]any{
"model": map[string]any{"type": "string"},
"depths": map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
},
},
},
"inputs": map[string]any{
"type": "object",
"required": []any{"depth", "key", "policy"},
"properties": map[string]any{
"depth": map[string]any{"type": "string", "description": "The reasoning depth the request states; default when it states none."},
"key": map[string]any{"type": "string", "description": "The table row that depth was read at."},
"task": map[string]any{"type": "string", "description": "The task the router read a request that left its effort to it as."},
"policy": map[string]any{"type": "string", "enum": []any{"funded", "unfunded", "n/a"}, "description": "Whether the caller's plan or balance pays for the tier; unfunded is served on its no-cost rungs at no charge."},
},
},
"reason": map[string]any{"type": "string", "description": "How the inputs led to chosen, in a sentence."},
},
}
// envelope is the one body this service returns from its resource surface.
//
// `data` is left open HERE because the envelope belongs to the surface and the
// result belongs to the operation: what comes back from listing stores is not
// what comes back from reading one. Each operation narrows it — see [result] —
// so the two facts compose instead of one of them having to be vague.
func envelope() map[string]any {
return map[string]any{
"type": "object",
"required": []any{"status", "msg"},
"description": "The resource surface's response. `status` is the verdict, not the HTTP code: " +
"a handled failure is still 200.",
"properties": map[string]any{
"status": map[string]any{"type": "string", "enum": []any{"ok", "error"}},
"msg": map[string]any{"type": "string", "description": "Empty on success, the reason on failure."},
"data": map[string]any{"description": "The operation's own result."},
"data2": map[string]any{"description": "A second result the operation defines, when it has one."},
},
}
}
// items are the Path Item Objects the resource table generates, keyed by path.
func items() map[string]any {
out := map[string]any{}
add := func(path, method string, op map[string]any) {
path = openAPIPath(path)
item, ok := out[path].(map[string]any)
if !ok {
item = map[string]any{}
out[path] = item
}
item[strings.ToLower(method)] = op
}
for _, r := range resources {
coll, member := r.collection(), r.member()
// What this resource IS, read off its own row. A row with no shape has not
// said, and its operations publish the bare envelope as before.
var list, one map[string]any
if r.shape != nil {
t := reflect.TypeOf(r.shape)
list, one = listOf(t), oneOf(t)
}
if !r.noList {
add(coll, "GET", op("List "+r.path,
"List the caller's "+r.path+".", nil, false, list))
}
if !r.noCreate {
add(coll, "POST", op("Create a "+singularNoun(r),
"Create one "+singularNoun(r)+".", nil, true, one))
}
if r.global {
add(coll+"/global", "GET", op("List "+r.path+" across tenants",
"Cross-tenant listing. Admin-only; a tenant caller is refused.", nil, false, list))
}
mp := memberParams()
if !r.noRead {
add(member, "GET", op("Retrieve a "+singularNoun(r),
"Read one "+singularNoun(r)+" by its (owner, name) key.", mp, false, one))
}
if !r.noUpdate {
add(member, "PATCH", op("Update a "+singularNoun(r),
"Update one "+singularNoun(r)+". PATCH and PUT reach the same handler, "+
"which has always taken a whole object.", mp, true, one))
add(member, "PUT", op("Replace a "+singularNoun(r),
"Identical to PATCH — the handler takes a whole object either way.", mp, true, one))
}
if !r.noDelete {
add(member, "DELETE", op("Delete a "+singularNoun(r),
"Delete one "+singularNoun(r)+".", mp, false, one))
}
for _, a := range r.actions {
verb := a.verb
if verb == "" {
verb = "POST"
}
p, params := coll+"/"+a.name, []any(nil)
if !a.collection {
p, params = member+"/"+a.name, mp
}
body := verb == "POST" || verb == "PUT" || verb == "PATCH"
add(p, verb, op(actionSummary(a.name, singularNoun(r)), "", params, body, nil))
}
}
for _, s := range singletons {
// Iterate a FIXED verb order, not the map: Go randomizes map order, and an
// accessor whose output reorders between runs cannot be diffed for drift.
for _, verb := range []string{"GET", "POST", "PUT", "PATCH", "DELETE"} {
if _, ok := s.verbs[verb]; !ok {
continue
}
body := verb == "POST" || verb == "PUT" || verb == "PATCH"
add(s.url(), verb, op(actionSummary(s.path, ""), "", nil, body, nil))
}
}
return out
}
// op builds one Operation Object.
//
// Every response is the SAME envelope: this surface answers {status,msg,data,data2}
// on success AND on a handled failure, so a 200 does not imply success — `status`
// does. That is a property of the backend, not a description choice, and saying so
// here is the difference between a spec a client can trust and one that quietly
// misleads.
//
// The refusals are written out rather than pointed at a shared Response Object,
// because a $ref binds this document to component definitions it does not carry,
// and an operation pointing at a definition that is not here resolves to nothing.
// The `data` argument is what THIS operation puts in the envelope's data field.
// Nil means the operation has not said — the envelope alone, which is what every
// operation used to publish.
func op(summary, description string, params []any, body bool, data map[string]any) map[string]any {
schema := map[string]any{"$ref": "#/components/schemas/Envelope"}
if data != nil {
schema = result(data)
}
o := map[string]any{
"summary": summary,
"responses": map[string]any{
"200": map[string]any{
"description": "Envelope. `status` is \"ok\" or \"error\" — check it; a handled " +
"failure is still HTTP 200.",
"content": map[string]any{
"application/json": map[string]any{"schema": schema},
},
},
"401": map[string]any{"description": "No credential, or one this service does not accept."},
"403": map[string]any{"description": "A valid credential that may not do this."},
},
}
if description != "" {
o["description"] = description
}
if len(params) > 0 {
o["parameters"] = params
}
if body {
o["requestBody"] = map[string]any{
"required": true,
"content": map[string]any{
"application/json": map[string]any{
"schema": map[string]any{"type": "object"},
},
},
}
}
return o
}
// memberParams are the two segments that identify a member.
//
// They are two parameters, not one, because the identity of every object here is
// the PAIR (owner, name) and a single segment cannot carry it — a composite id
// URL-encoded into one segment is decoded back to a separator before routing and
// matches nothing. The spec has to say that or every generated SDK gets it wrong.
func memberParams() []any {
return []any{
map[string]any{
"name": "owner", "in": "path", "required": true,
"schema": map[string]any{"type": "string"},
"description": "Owning organization.",
},
map[string]any{
"name": "name", "in": "path", "required": true,
"schema": map[string]any{"type": "string"},
"description": "Resource name, unique within the owner.",
},
}
}
// actionSummary renders a URL segment as a human summary: "query-second" ->
// "Query second", "mcp-tools" -> "Mcp tools".
func actionSummary(name, subject string) string {
s := titleCase(strings.ReplaceAll(name, "-", " "))
if subject != "" {
return s + " (" + subject + ")"
}
return s
}
// openAPIPath rewrites the router's ":name" parameter syntax into OpenAPI's
// "{name}". The two describe the same route; only the spelling differs, and a
// spec left in the router's spelling silently produces SDKs that request a
// literal ":owner".
func openAPIPath(p string) string {
segs := strings.Split(p, "/")
for i, s := range segs {
if strings.HasPrefix(s, ":") {
segs[i] = "{" + s[1:] + "}"
}
}
return strings.Join(segs, "/")
}
// pathParams names the templated segments of an OpenAPI path. Rewriting the
// spelling is only half of what that comment above promises: a client also
// needs the parameter DECLARED, or the generator emits a method that cannot be
// given the value its own name asks for.
func pathParams(p string) []string {
var names []string
for s := range strings.SplitSeq(p, "/") {
if len(s) > 2 && s[0] == '{' && s[len(s)-1] == '}' {
names = append(names, s[1:len(s)-1])
}
}
return names
}
func titleCase(s string) string {
parts := strings.FieldsFunc(s, func(r rune) bool { return r == '-' || r == ' ' || r == '/' })
for i, p := range parts {
if p == "" {
continue
}
parts[i] = strings.ToUpper(p[:1]) + p[1:]
}
return strings.Join(parts, " ")
}