Files
zeekay a3cd3b4309 fee: a call bills what its arms cost and the platform's fee; Enso is quoted from, typical and up to
A call through the gateway bills the price of the arm that answered and the
platform's fee on top, and nothing else: 5.5% on Hanzo's accounts, 1% on the
org's own key, both the host's settings (object.Fee: hanzo, hanzo_byok). A
vendor's fee is part of the cost: a call OpenRouter's credit bought cost its
stated price plus 5.5%, and the platform's fee goes on that.

- Enso answers bill their cost of record (X-Hanzo-Cogs and the buying
  vendor's fee) times the platform's fee; a maker's answer the same; a resold
  OpenRouter SKU its vendor price times both fees. An answer that states no
  cost bills the SKU's listed ceiling. A call billed below its cost writes
  loss_nano and a warning.
- hanzo.cloud_usage gains reasoning, reasoning_tokens, served, vendor, arms
  and loss_nano: each Enso row names the arm that answered, its rate at the
  time and the tokens it was paid for, and each arm that failed first.
- rates.go prices every Enso SKU at each depth: from (its cheapest arm), up to
  (its dearest, a long prompt included), and typical (its measured cost a
  token over the last day, or its last 50 calls), the arms read from the
  engine's admin catalog. /v1/models lists the typical rate with from, up_to,
  fee and window beside it; Prices, Price and Blend serve the rest. The
  board's ledger counts answers, failovers, OpenRouter-bought answers, fee
  and losses by model and vendor.
2026-10-15 12:33:32 -07:00

322 lines
15 KiB
Go
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// Copyright 2023-2025 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 controllers
import (
"fmt"
"math"
"strconv"
"strings"
)
// EXACT usage cost in nano-USD (1e-9), the anti-cents-flooring path. LLM prices are
// $/1M tokens, so the natural unit is integer nano-USD: a token's cost is
// tokens × (price/1e6 $) = tokens × (price × 1000 nano) with NO division and NO float
// rounding, so a 200-token $6.60/1M completion bills exactly 1,320,000 nano ($0.00132)
// instead of flooring to 0¢. The host parses the emitted decimal-USD string into
// atto-USD (1e-18) for the ledger — nano→atto is exact (×1e9), so nothing is skipped
// end to end. This is the money-of-record path; the cents helpers remain only for the
// analytics warehouse and the standalone HTTP billing queue.
// nanoPerToken converts a $/1M-token price to EXACT integer nano-USD per token:
// perMillion/1e6 dollars/token × 1e9 nano/dollar = perMillion × 1000. Model prices carry
// ≤3 decimals, so the product is integer and math.Round only clears float64's binary
// representation of the decimal literal — it is not an economic rounding.
func nanoPerToken(perMillion float64) int64 {
if perMillion <= 0 {
return 0
}
return int64(math.Round(perMillion * 1000))
}
// tokenNanoAt is the exact nano-USD token cost for the four per-million base rates,
// applying the shared cache-rate defaulting (cache-read = 10% of input when the model
// declares none, cache-write = cacheWriteRate). It is the ONE place the token→nano arithmetic
// lives: both the billed-price path (tokenCostNano) and the provider-COGS path
// (tokenProviderCostNano) call it, so their cache math can never drift.
//
// promptTokens is EVERY input token, the cache reads and writes among them (one
// convention on every path: usageRecord.PromptTokens). The input rate bills the part
// read fresh, prompt less reads and writes; each cache part bills at its own rate.
func tokenNanoAt(inPerM, outPerM, cacheReadPerM, cacheWritePerM float64, promptTokens, completionTokens, cacheReadTokens, cacheWriteTokens int) int64 {
cacheReadPerM = cacheReadRate(inPerM, cacheReadPerM)
cacheWritePerM = cacheWriteRate(inPerM, cacheWritePerM)
return int64(fresh(promptTokens, cacheReadTokens, cacheWriteTokens))*nanoPerToken(inPerM) +
int64(completionTokens)*nanoPerToken(outPerM) +
int64(cacheReadTokens)*nanoPerToken(cacheReadPerM) +
int64(cacheWriteTokens)*nanoPerToken(cacheWritePerM)
}
// cacheReadRate is the per-million price of a cache read: the model's own rate when
// it states one, else a tenth of its input rate (Anthropic parity). The one rule for
// the nano ledger (tokenNanoAt) and what the cache saved (cacheSavedNano).
func cacheReadRate(inPerM, readPerM float64) float64 {
if readPerM == 0 && inPerM > 0 {
return inPerM * 0.10
}
return readPerM
}
// cacheSavedNano is what the prompt cache took off a call's bill, in nano-USD: its
// cache-read tokens at the input price less the same tokens at the cache-read price,
// both from the model's billed price, the table usageCostNano reads. Only a call
// billed per token at that table saves anything it can state: a free route, a BYO
// call (its bill is a fee, not the table's price), a call billed at an amount its
// answer stated, and a decision, image, video or audio call have no such saving, so
// they are 0. Never negative.
func cacheSavedNano(record *usageRecord) int64 {
if record.CacheReadTokens <= 0 || record.Free || record.BYO || record.BilledNanoExact != nil ||
record.VideoCount > 0 || record.ImageCount > 0 || record.DecisionCount > 0 || recordIsAudio(record) {
return 0
}
price := getModelPrice(record.Model)
per := nanoPerToken(price.InputPerMillion) - nanoPerToken(cacheReadRate(price.InputPerMillion, price.CacheReadPerMillion))
return int64(record.CacheReadTokens) * max(per, 0)
}
// fresh is the part of a prompt read neither from the cache nor written to it.
func fresh(promptTokens, cacheReadTokens, cacheWriteTokens int) int {
return max(promptTokens-max(cacheReadTokens, 0)-max(cacheWriteTokens, 0), 0)
}
// tokenCostNano is the exact BILLED (customer-price) token cost in nano-USD, mirroring
// modelCostBreakdown's rate selection but in integer arithmetic so no sub-cent is lost.
func tokenCostNano(model string, promptTokens, completionTokens, cacheReadTokens, cacheWriteTokens int) int64 {
price := getModelPrice(model)
return tokenNanoAt(price.InputPerMillion, price.OutputPerMillion, price.CacheReadPerMillion, price.CacheWritePerMillion,
promptTokens, completionTokens, cacheReadTokens, cacheWriteTokens)
}
// tokenProviderCostNano is the exact PROVIDER-COGS token cost in nano-USD: the same
// arithmetic as tokenCostNano at the model's COGS rates. Cache COGS is not separately
// configured, so pass 0 and let tokenNanoAt default cache-read to 10% of the COGS input
// rate and cache-write to cacheWriteRate of it — mirroring the price path exactly.
//
// Nil when the model states no COGS. Reading the customer price there and calling it a
// cost makes every such call report margin exactly zero, which is not a small error in
// the last digit: it is the difference between a business whose costs are visible and
// one whose ledger says it earns nothing on everything it sells.
func tokenProviderCostNano(model string, promptTokens, completionTokens, cacheReadTokens, cacheWriteTokens int) *int64 {
price := getModelPrice(model)
if !price.costed() {
return nil
}
cost := tokenNanoAt(price.costInputPerMillion(), price.costOutputPerMillion(), 0, 0,
promptTokens, completionTokens, cacheReadTokens, cacheWriteTokens)
return &cost
}
// usageCostNano is the authoritative billable cost of a call in nano-USD — the exact twin
// of usageCostCents. Image/video bill per unit (their per-unit cents scaled to nano);
// everything else bills exactly per token.
func usageCostNano(record *usageRecord) int64 {
switch {
// A route the vendor charges nothing for costs nothing, whatever a price table
// would guess for a model id it has never seen. It is stated HERE because every
// reader of the money — the ledger debit, the warehouse row and the gen_ai span —
// asks this one function, which is what keeps them agreeing.
case record.Free:
return 0
// A Hanzo-served call whose biller knows its exact charge costs exactly that: a
// variable SKU bills what its answer stated, which no rate table can recompute. A
// BYO call's exact figure is the platform fee, not the cost, so it is not read here.
case record.BilledNanoExact != nil && !record.BYO:
return *record.BilledNanoExact
case record.VideoCount > 0:
return videoCostCents(record.Model, record.VideoCount) * 10_000_000 // 1¢ = 1e7 nano
case record.ImageCount > 0:
return imageCostCents(record.Model, record.ImageCount) * 10_000_000
case record.DecisionCount > 0:
return decisionCostNano(record.Model, record.PromptTokens, record.CompletionTokens)
case recordIsAudio(record):
return audioCostNano(record)
default:
return tokenCostNano(record.Model, record.PromptTokens, record.CompletionTokens,
record.CacheReadTokens, record.CacheWriteTokens)
}
}
// usageBilledNano is what Hanzo DEBITS in nano-USD: the full cost for a Hanzo-served
// call, or the platform's BYOK fee for a BYO call (fee.go, 1%; ceil to the nano, so a
// fee is never rounded down to zero).
func usageBilledNano(record *usageRecord, costNano int64) int64 {
if record.BYO {
if costNano <= 0 {
return 0
}
return plus(costNano, true) - costNano
}
return costNano
}
// costMargin is the money-of-record margin view of one call, all in integer nano-USD:
// BilledNano (what Hanzo debits the org), CostNano (Hanzo's provider COGS to serve it),
// and MarginNano = BilledNano − CostNano. Computed once (usageMargin) so the ledger, the
// cloud_usage row, and the o11y span read identical figures and can never drift.
type costMargin struct {
// CostNano is the provider COGS to Hanzo, and NIL where no cost is known — see
// providerCostNano. It is a pointer for the same reason MarginNano is: the row has
// to be able to say it does not know, and an int64 can only say zero.
CostNano *int64
BilledNano int64 // what Hanzo debits the org (full for served, 1% platform fee for BYO)
// MarginNano is BilledNano − CostNano, and it is NIL when that subtraction has
// no meaning. An unpriced model has no configured rate, so the COGS leg is the
// conservative default rather than a cost anyone paid; subtracting an invented
// number from a real billed amount yields a figure that reads as a heavy loss
// and is not one. Better to report no margin than a fabricated one.
MarginNano *int64
}
// providerCostNano is Hanzo's cost of goods sold for a call, in nano-USD, and NIL where
// that cost is not known.
//
// Zero and unknown are different answers and the caller must be able to tell them apart.
// Zero is a fact: a BYO call was paid upstream with the customer's own key, a free route
// is charged nothing, speech runs on hardware already bought. Nil is the absence of one:
// image and video have a per-unit PRICE table and no vendor invoice behind it, and a
// token model that states no COGS has told us nothing about what it costs.
//
// The tempting substitution is the customer price, which is always to hand. It reads as
// a complete answer, arrives at margin zero for every such call, and is wrong in the
// direction that hides the entire cost of the business.
func providerCostNano(record *usageRecord) *int64 {
if record.BYO || record.Free {
return new(int64)
}
switch {
case record.VideoCount > 0:
return nil // the per-unit table is a price; no vendor invoice is known
case record.ImageCount > 0:
return nil
case record.DecisionCount > 0:
return nil // a decision that states its cost carries it as CostNanoExact
case recordIsAudio(record):
// Speech runs on hardware we already own, so there is no upstream invoice
// to pass through: COGS is 0 and the margin on an audio call is the whole
// price. Stated explicitly rather than reached by falling through to token
// math that happens to yield 0 on a record with no tokens — the two agree
// today by accident, and only one of them is the reason.
return new(int64)
default:
return tokenProviderCostNano(record.Model, record.PromptTokens, record.CompletionTokens,
record.CacheReadTokens, record.CacheWriteTokens)
}
}
// usageMargin computes the billed/cost/margin trio for a call in nano-USD from the ONE
// billed path (usageBilledNano ∘ usageCostNano) and the provider COGS (providerCostNano).
// MarginNano is Hanzo's gross margin on the call: for a Hanzo-served call it is
// price − COGS; for a BYO call CostNano is 0 so the margin is exactly the platform fee
// (the billed amount itself is unchanged — still the 1% fee).
func usageMargin(record *usageRecord) costMargin {
billed := usageBilledNano(record, usageCostNano(record))
cost := providerCostNano(record)
// A self-billing subsystem (zen's commerce Meter) knows its EXACT billed
// amount + upstream COGS per served tier; those ARE the numbers, so the table
// recompute is not consulted. Presence, not positivity: a turn that billed
// exactly nothing said so, and must not be handed a price it never charged.
if record.BilledNanoExact != nil {
billed = *record.BilledNanoExact
}
if record.CostNanoExact != nil {
cost = record.CostNanoExact
}
m := costMargin{CostNano: cost, BilledNano: billed}
// Margin is the subtraction of two known numbers. A stated COGS is one whatever the
// price table knows; a derived one requires both a real cost and a real price.
if cost != nil && (record.CostNanoExact != nil || !recordUnpriced(record)) {
margin := billed - *cost
m.MarginNano = &margin
}
return m
}
// nanoToCents rounds a nano-USD amount to the nearest cent (1¢ = 1e7 nano). It is how
// the cent-precision surfaces — the analytics ledger, the span's total, the standalone
// billing queue — read the exact money, so none of them computes a cost of its own.
// Half a cent rounds up; a negative amount has no meaning as a cost and reads as zero.
func nanoToCents(nano int64) int64 {
if nano <= 0 {
return 0
}
return (nano + 5_000_000) / 10_000_000
}
// usdToNano converts a decimal-USD amount to integer nano-USD — the inverse of
// nanoToUSD, for a caller that already knows the exact dollars it billed and needs
// to report them on the nano money ledger.
func usdToNano(usd float64) int64 {
return int64(math.Round(usd * 1_000_000_000))
}
// nanoToUSD renders a signed nano-USD amount as an EXACT decimal USD string ("0.00132"),
// the value carried across the billing seam.
func nanoToUSD(nano int64) string {
if nano == 0 {
return "0"
}
neg := nano < 0
if neg {
nano = -nano
}
s := strconv.FormatInt(nano/1_000_000_000, 10)
if frac := nano % 1_000_000_000; frac > 0 {
s += "." + strings.TrimRight(fmt.Sprintf("%09d", frac), "0")
}
if neg {
s = "-" + s
}
return s
}
// usageBilledUSD is the exact decimal-USD amount for the native finance debit. It
// reads usageMargin — the ONE billed path — rather than recomputing the table leg of
// it, so a caller that knows its exact billed amount is debited THAT and not a
// rate-table guess, and the invoice, the warehouse row and the span all carry one
// number.
func usageBilledUSD(record *usageRecord) string {
return nanoToUSD(usageMargin(record).BilledNano)
}
// usageFree reports whether a call was served at a price of ZERO — the class a wallet
// has nothing to refuse, and therefore the class the plan allowance counts.
//
// "THE NUMBER CAME OUT ZERO" IS A DIFFERENT QUESTION AND GETS A DIFFERENT ANSWER, so
// three things have to be true:
//
// - It billed nothing. The wallet's question, read from the same margin
// usageBilledUSD renders, so free and $0 are one answer and not two that drift.
//
// - The zero is a PRICE and not a missing one. A model whose rate is not set —
// an audio id absent from sttNanoPerSecond, say — computes zero and is
// UNPRICED, not free. Counting it would spend a customer's free calls on
// traffic we have simply not billed, and empty their day on the work they are
// paying for.
//
// - The route is free by DECLARATION or by the TABLE. costsNothing is the same
// question the balance gate asks before the call, so the gate and the counter
// bound the same set of calls; record.Free is a route the vendor charges nothing
// for — the free pool and the spare routes — which states its own zero and
// appears in no table under the id that served it.
//
// The third is what keeps a vendor's failure from being read as a gift: an upstream
// that answers an error carries no tokens, so a PRICED model can compute zero, and
// only asking what the route costs tells the two apart.
func usageFree(record *usageRecord) bool {
return usageMargin(record).BilledNano == 0 &&
!recordUnpriced(record) &&
(record.Free || costsNothing(record.Model, record.Owner))
}