mirror of
https://github.com/hanzoai/ai.git
synced 2026-11-20 14:13:23 +00:00
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.
322 lines
15 KiB
Go
322 lines
15 KiB
Go
// 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))
|
||
}
|