Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

feat(model-hub): bill the calls that ran fast at fast-tier rates in usage (#3094)

Call White4abe99868965
diff --git a/core/handlers/model_hub/pricing.py b/core/handlers/model_hub/pricing.py
index 207f7533c..cdb090a10 100644
--- a/core/handlers/model_hub/pricing.py
+++ b/core/handlers/model_hub/pricing.py
@@ -124,6 +124,10 @@ class ModelPrice:
# Higher rates past a context size, as (size, rates) by ascending size. A call
# whose context input exceeds a size is billed whole at that tier's rates.
context_tiers: tuple[tuple[int, "ModelPrice"], ...] = ()
+ # The vendor's fast tier (docs/plans/fast-mode.md), from models.dev
+ # `experimental.modes.fast.cost`: a call its response says ran fast is billed
+ # at these rates, read by the same rules. None when the table lists none.
+ fast: Optional["ModelPrice"] = None
def _bounded(value: object, ceiling: float) -> Optional[float]:
@@ -144,9 +148,12 @@ def _price(value: object) -> Optional[float]:
return _bounded(value, _MAX_PRICE_PER_MTOK)
-def model_price(cost: object) -> Optional[ModelPrice]:
+def model_price(cost: object, *, fast_cost: object = None) -> Optional[ModelPrice]:
"""Read one models.dev-shaped `cost` object, or None when it has no usable price.
+ ``fast_cost`` is the same model's fast-tier `cost`, read by the same rules into
+ ``ModelPrice.fast``; it never prices a model whose standard price is missing.
+
Input and output are required. A missing cache member falls back to what the
tokens are otherwise: a cache read or write is input.
@@ -173,7 +180,10 @@ def model_price(cost: object) -> Optional[ModelPrice]:
legacy = _flat_price(cost.get("context_over_200k"))
if legacy is not None:
tiers[_LEGACY_CONTEXT_TIER_SIZE] = legacy
- return replace(price, context_tiers=tuple(sorted(tiers.items()))) if tiers else price
+ if tiers:
+ price = replace(price, context_tiers=tuple(sorted(tiers.items())))
+ fast = model_price(fast_cost) if fast_cost is not None else None
+ return replace(price, fast=fast) if fast is not None else price
def context_tier_size(price: Optional[ModelPrice], context_input_tokens: int) -> int:
@@ -271,8 +281,14 @@ def _first_party(model_id: str, vendor_map: Mapping[str, Any]) -> Optional[str]:
return max(matches, key=lambda item: len(item["prefix"]))["vendor_id"]
-def _first_party_costs(catalog: Mapping[str, Any], vendor_map: Mapping[str, Any]) -> dict[str, dict[str, object]]:
- """Each first-party provider's `cost` objects by model key: the part of the catalog a price is read from."""
+def _first_party_costs(
+ catalog: Mapping[str, Any], vendor_map: Mapping[str, Any],
+) -> dict[str, dict[str, tuple[object, object]]]:
+ """Each first-party provider's standard and fast-tier `cost` objects by model key.
+
+ The part of the catalog a price is read from. The fast one is the entry's
+ `experimental.modes.fast.cost`, None when it lists none.
+ """
families = vendor_map.get("families")
vendors = {
@@ -285,10 +301,19 @@ def _first_party_costs(catalog: Mapping[str, Any], vendor_map: Mapping[str, Any]
provider = catalog.get(vendor)
models = provider.get("models") if isinstance(provider, Mapping) else None
if isinstance(models, Mapping):
- costs[vendor] = {key: entry.get("cost") for key, entry in models.items() if isinstance(entry, Mapping)}
+ costs[vendor] = {
+ key: (entry.get("cost"), _fast_cost(entry)) for key, entry in models.items() if isinstance(entry, Mapping)
+ }
return costs
+def _fast_cost(entry: Mapping[str, Any]) -> object:
+ modes = entry.get("experimental")
+ modes = modes.get("modes") if isinstance(modes, Mapping) else None
+ fast = modes.get("fast") if isinstance(modes, Mapping) else None
+ return fast.get("cost") if isinstance(fast, Mapping) else None
+
+
def plan_key(vendor: str, plan: Optional[str]) -> Optional[str]:
"""Resolve a reported plan to a fee-table key, or None when it is not a known plan."""
@@ -337,7 +362,7 @@ class PriceTable:
# controller loop (at startup, then on the usage writer's thread), so a
# lookup on the loop is a dictionary read however large the catalog is.
self._prices: dict[str, dict[str, Optional[ModelPrice]]] = {
- vendor: {key: model_price(cost) for key, cost in costs.items()}
+ vendor: {key: model_price(cost, fast_cost=fast_cost) for key, (cost, fast_cost) in costs.items()}
for vendor, costs in _first_party_costs(catalog, vendor_map).items()
}
self._vendor_map = vendor_map
@@ -457,7 +482,11 @@ class Cost:
def row_cost(row: Mapping[str, Any], price: Optional[ModelPrice]) -> Cost:
- """Price one ledger row's counters at one model's price, in the row's context tier."""
+ """Price one ledger row's counters at one model's price, in the row's context tier and speed.
+
+ A fast row (`speed: "fast"`) is valued at the model's fast-tier rates; where
+ the table lists none, at its standard rates, as a floor.
+ """
input_tokens = int(row.get("input_tokens") or 0)
output_tokens = int(row.get("output_tokens") or 0)
@@ -466,6 +495,12 @@ def row_cost(row: Mapping[str, Any], price: Optional[ModelPrice]) -> Cost:
unreported = int(row.get("requests") or 0) > int(row.get("token_reports") or 0)
if price is None:
return Cost(excluded_tokens=input_tokens + output_tokens, api_cost_lower_bound=unreported)
+ fast_unpriced = False
+ if row.get("speed") == "fast":
+ if price.fast is not None:
+ price = price.fast
+ else:
+ fast_unpriced = True
price = context_tier_price(price, int(row.get("context_tier") or 0))
cache_read = min(int(row.get("cached_input_tokens") or 0), input_tokens)
cache_write = min(int(row.get("cache_write_input_tokens") or 0), input_tokens - cache_read)
@@ -488,7 +523,9 @@ def row_cost(row: Mapping[str, Any], price: Optional[ModelPrice]) -> Cost:
ttl_uncaptured = int(row.get("cache_write_ttl_uncaptured_reports") or 0) > 0
return Cost(
api_cost_usd=usd,
- api_cost_lower_bound=unreported or ttl_uncaptured or (uncaptured and price.charges_cache_writes),
+ api_cost_lower_bound=(
+ unreported or fast_unpriced or ttl_uncaptured or (uncaptured and price.charges_cache_writes)
+ ),
)
diff --git a/core/handlers/model_hub/service.py b/core/handlers/model_hub/service.py
index 5d6490f7b..e6202b525 100644
--- a/core/handlers/model_hub/service.py
+++ b/core/handlers/model_hub/service.py
@@ -11322,6 +11322,10 @@ class ModelHubService:
"""
usage = _call_usage(outcome, observed)
+ # The tier the response named prices its tokens; Avibe never assumes one.
+ tier = outcome.served_tier if outcome is not None else None
+ if tier is None and observed is not None:
+ tier = observed.served_tier
reached_model = (
outcome is not None
and (outcome.kind is RawOutcomeKind.SUCCESS or outcome.stream_started)
@@ -11334,6 +11338,7 @@ class ModelHubService:
model_id=model_id,
usage=usage,
at=at or self.now(),
+ speed=tier,
)
)
diff --git a/core/handlers/model_hub/turn_gateway.py b/core/handlers/model_hub/turn_gateway.py
index 0ab45e99e..1190897fd 100644
--- a/core/handlers/model_hub/turn_gateway.py
+++ b/core/handlers/model_hub/turn_gateway.py
@@ -357,6 +357,19 @@ class _TurnExecution:
)
return self.handle is not None
+ @property
+ def reported_tier(self) -> ServedTier | None:
+ """The processing tier the response named, whichever shape it answered in and however it ended.
+
+ The same owners in the same order as the usage report, because it is the
+ rate those tokens are billed at.
+ """
+
+ for state in (self.upstream_observation, self.wire_state):
+ if state is not None and state.served_tier is not None:
+ return state.served_tier
+ return self.handle_outcome.served_tier if self.handle_outcome is not None else None
+
@property
def served_tier(self) -> tuple[bool, ServedTier | None]:
"""Whether upstream served this call in full, and the processing tier its response named.
@@ -1743,6 +1756,7 @@ class ModelHubTurnGateway:
model_id=resolved.model_id,
usage=usage,
at=execution.completed_at or self._now(),
+ speed=execution.reported_tier,
)
await self._usage_writer.wait_recorded(execution.usage_write)
diff --git a/core/handlers/model_hub/usage.py b/core/handlers/model_hub/usage.py
index 125d52517..3da15a783 100644
--- a/core/handlers/model_hub/usage.py
+++ b/core/handlers/model_hub/usage.py
@@ -47,6 +47,7 @@ from pathlib import Path
from time import monotonic
from typing import Callable, Final, Mapping, Optional, Sequence
+from .fast_mode import FAST_SPEED
from .identifiers import persisted_ledger_key, usage_ledger_key
from .pricing import Cost, ModelPrice, PriceTable, ServiceCost, context_tier_size, row_cost, service_row_cost
from .state_file import write_state_document
@@ -797,6 +798,13 @@ def _normalize_row(row: object) -> Optional[dict]:
context_tier = row.get("context_tier", 0)
if not isinstance(context_tier, int) or isinstance(context_tier, bool) or context_tier < 0:
return None
+ # The same for the processing tier: a call its response said ran at the
+ # vendor's fast tier is billed at fast rates (docs/plans/fast-mode.md).
+ # Absent on every standard-tier row and on every row a released version wrote,
+ # which reads a fast row as a standard one and keeps every count.
+ speed = row.get("speed")
+ if speed is not None and speed != FAST_SPEED:
+ return None
legacy_cache_write_shape = any(key not in row for key in _NEW_CACHE_WRITE_KEYS)
if legacy_cache_write_shape:
row = {**_released_cache_write_counters(row), **row}
@@ -812,6 +820,7 @@ def _normalize_row(row: object) -> Optional[dict]:
"model_id": model_id,
# Written only past the base tier, so a base row keeps the released shape.
**({"context_tier": context_tier} if context_tier else {}),
+ **({"speed": speed} if speed else {}),
**counters,
}
if legacy_cache_write_shape:
@@ -1095,6 +1104,7 @@ def _bucket_rows(
key, {"source_id": row["source_id"], "model_id": row["model_id"], **_empty_totals()}
)
_accumulate(target, row)
+ _count_fast(target, row)
if prices is not None:
costs.setdefault(key, Cost()).add(row_cost(row, _row_price(row, prices, keyed_model_labels)))
service_rows = [
@@ -1197,17 +1207,19 @@ def _cache_write_increment(usage: Optional[ProtocolUsageReport]) -> dict[str, in
}
-def _row_key(row: dict) -> tuple[str, str, str, int, bool, str]:
- """A row is one day of one model on one Source, in one context tier.
+def _row_key(row: dict) -> tuple[str, str, str, int, bool, str, str]:
+ """A row is one day of one model on one Source, in one context tier and processing tier.
Or of one hosted service/tool on one Source. The boolean keeps model and
- service identities apart; the final tool keeps shared Exa search/fetch
- attribution separate without changing its service/cooldown identity.
+ service identities apart; the tool keeps shared Exa search/fetch attribution
+ separate without changing its service/cooldown identity. The last member is a
+ model row's speed (`"fast"`, else empty), so calls billed at fast rates never
+ share a row with standard ones.
"""
if _is_service(row):
- return (row["day"], row["source_id"], row["service_id"], 0, True, row.get("tool", "web_search"))
- return (row["day"], row["source_id"], row["model_id"], row.get("context_tier", 0), False, "")
+ return (row["day"], row["source_id"], row["service_id"], 0, True, row.get("tool", "web_search"), "")
+ return (row["day"], row["source_id"], row["model_id"], row.get("context_tier", 0), False, "", row.get("speed", ""))
def _empty_totals(*, service: bool = False) -> dict:
@@ -1216,6 +1228,17 @@ def _empty_totals(*, service: bool = False) -> dict:
return {key: 0 for key in _COUNTER_KEYS}
+def _count_fast(target: dict, row: dict) -> None:
+ """Publish how many of an aggregate's requests ran at the vendor's fast tier.
+
+ Present only once a fast row joins, so an aggregate without one keeps the
+ released shape. Read-side only: no persisted row carries it.
+ """
+
+ if row.get("speed") == FAST_SPEED:
+ target["fast_requests"] = target.get("fast_requests", 0) + row["requests"]
+
+
def _accumulate(target: dict, row: dict) -> None:
"""Add one row's counters into an aggregate, exactly.
@@ -1403,6 +1426,7 @@ def _model_increment(
"source_id": source_key,
"model_id": model_key,
"context_tier": call.context_tier,
+ **({"speed": call.speed} if call.speed else {}),
"requests": call.requests,
"token_reports": call.requests if usage is not None else 0,
"input_tokens": usage.input_tokens if usage else 0,
@@ -1617,6 +1641,7 @@ class BoundedUsageLedger:
model_id: str,
usage: Optional[ProtocolUsageReport],
at: datetime,
+ speed: Optional[str] = None,
) -> None:
"""Fold one metered upstream call into its day's row.
@@ -1635,7 +1660,7 @@ class BoundedUsageLedger:
metered later than the write that records it.
"""
- self.record_many((UsageCall(source_id=source_id, model_id=model_id, usage=usage, at=at),))
+ self.record_many((UsageCall(source_id=source_id, model_id=model_id, usage=usage, at=at, speed=speed),))
def record_many(self, calls: Sequence["UsageCall | ServiceUsageCall"]) -> None:
"""Fold a batch of metered calls into their days' rows in one transaction.
@@ -2027,6 +2052,7 @@ class BoundedUsageLedger:
)
continue
_accumulate(totals, row)
+ _count_fast(totals, row)
cost = (
None
if prices is None
@@ -2045,6 +2071,7 @@ class BoundedUsageLedger:
},
)
_accumulate(source, row)
+ _count_fast(source, row)
priced(source, cost)
source["last_metered_at"] = _newer_timestamp(
source["last_metered_at"],
@@ -2059,12 +2086,14 @@ class BoundedUsageLedger:
},
)
_accumulate(model, row)
+ _count_fast(model, row)
priced(model, cost)
if prices is not None:
model["priced"] = _row_price(row, prices, keyed_model_labels) is not None
day = by_day.setdefault(row["day"], {"day": row["day"], **_empty_totals()})
_accumulate(day, row)
+ _count_fast(day, row)
priced(day, cost)
published_services = []
@@ -2274,6 +2303,7 @@ class BoundedUsageLedger:
**({"service_id": row["service_id"], **({"tool": row["tool"]} if "tool" in row else {})}
if service else {"model_id": row["model_id"]}),
**({"context_tier": row["context_tier"]} if "context_tier" in row else {}),
+ **({"speed": row["speed"]} if "speed" in row else {}),
**_empty_totals(service=service),
"last_metered_at": None,
}
@@ -2436,6 +2466,9 @@ class UsageCall:
# The context tier the call was billed in (`pricing.context_tier_size`), 0 for
# the base rates. Decided per call, since a folded row can no longer tell.
context_tier: int = 0
+ # `"fast"` when the call's response said it ran at the vendor's fast tier, so it
+ # is billed at fast rates; None for the standard tier.
+ speed: Optional[str] = None
def __post_init__(self) -> None:
# An init field intentionally survives dataclasses.replace during a fold.
@@ -2444,13 +2477,14 @@ class UsageCall:
object.__setattr__(self, "owner_day", local_usage_day(self.at).isoformat())
@property
- def fold_key(self) -> tuple[str, str, str, str, int, bool]:
+ def fold_key(self) -> tuple[str, str, str, str, int, str, bool]:
"""What makes two calls one daily row and one hourly slice.
The ledger's own row key plus whether tokens were reported, which is the
part that keeps a fold arithmetically identical to the calls it replaces.
- The row key includes the context tier, so calls billed at different rates
- never fold: one call's tier would otherwise price the other's tokens.
+ The row key includes the context tier and the speed, so calls billed at
+ different rates never fold: one call's tier would otherwise price the
+ other's tokens.
The hour is part of the queue key so a flush cannot merge calls from
different hours before the ledger sees their temporal identity. The local
date must also remain: a UTC hour can cross local midnight, and folding
@@ -2463,6 +2497,7 @@ class UsageCall:
self.source_id,
self.model_id,
self.context_tier,
+ self.speed or "",
self.usage is not None,
)
@@ -2680,6 +2715,7 @@ class UsageWriter:
model_id: str,
usage: Optional[ProtocolUsageReport],
at: datetime,
+ speed: Optional[str] = None,
) -> "asyncio.Future[None]":
"""Own one call and queue it, handing back what will finish it.
@@ -2698,16 +2734,19 @@ class UsageWriter:
The call's context tier is decided here from the price table the writer
holds, a lookup in memory. A writer built without a table, or holding one
- without tiers (no models.dev copy yet), records the base tier.
+ without tiers (no models.dev copy yet), records the base tier. `speed` is
+ `"fast"` only when the call's response said it ran at the fast tier.
"""
+ speed = FAST_SPEED if speed == FAST_SPEED else None
return self._queue(
UsageCall(
source_id=source_id,
model_id=model_id,
usage=usage,
at=at,
- context_tier=self._context_tier(model_id, usage),
+ context_tier=self._context_tier(model_id, usage, speed),
+ speed=speed,
)
)
@@ -2839,13 +2878,20 @@ class UsageWriter:
if not queued.done.done():
queued.done.set_result(None)
- def _context_tier(self, model_id: str, usage: Optional[ProtocolUsageReport]) -> int:
- """The tier the held price table puts one call in; the base tier without usage or a table."""
+ def _context_tier(self, model_id: str, usage: Optional[ProtocolUsageReport], speed: Optional[str] = None) -> int:
+ """The tier the held price table puts one call in; the base tier without usage or a table.
+
+ A fast call is placed by the fast rates' own context sizes, the rates its
+ row is valued at; where the table lists no fast rates, by the standard ones.
+ """
held = self._prices
if usage is None or held is None:
return 0
- return context_tier_size(held[0].price(model_id), usage.input_tokens)
+ price = held[0].price(model_id)
+ if speed == FAST_SPEED and price is not None and price.fast is not None:
+ price = price.fast
+ return context_tier_size(price, usage.input_tokens)
def _prices_due(self) -> bool:
"""Whether the next flush re-reads the price table: none held, too old, or still being fetched."""
diff --git a/docs/plans/fast-mode.md b/docs/plans/fast-mode.md
index 49e993ca6..215adee91 100644
--- a/docs/plans/fast-mode.md
+++ b/docs/plans/fast-mode.md
@@ -102,6 +102,19 @@ the Hub believes that report rather than the request:
its next fast response. The record is process memory, bounded; after a
restart, a hop is unknown until its next fast response.
+### Usage
+
+The usage ledger bills what the response said, like the confirmation does. A
+call whose response named the fast tier is recorded in its own row
+(`speed: "fast"`, beside the context tier in the row's identity; standard rows
+keep the released shape). Valuation prices a fast row at the model's models.dev
+`experimental.modes.fast.cost` rates, in the row's context tier, or at its
+standard rates as a lower bound where the table lists none. Every published
+aggregate (totals, Sources, models, days and buckets) counts `fast_requests`
+beside `requests`, present only once a fast request joins it. A released reader
+treats a fast row as a standard one, merging it into that day's standard row
+without losing a count. Pricing details: `docs/plans/model-hub-capability-model.md` §6.2.
+
### Picker
- The Hub Agent read states, on each catalog model, whether a fast turn on it
@@ -126,8 +139,6 @@ the Hub believes that report rather than the request:
- Per-turn cost estimates. The tooltip says the price is higher; the
multiplier differs by vendor and plan.
- Fast mode for Direct-mode Agents, OpenCode, and the IM settings surfaces.
-- Recording the served tier in usage records, and pricing fast requests there.
- The tier is read on every call; the usage ledger does not keep it yet.
## Validation
@@ -139,6 +150,9 @@ the Hub believes that report rather than the request:
says the tier ran).
- Units: the served tier each protocol reports, streamed and buffered
(`tests/test_model_hub_served_tier.py`), and the observation record.
+- Fast-tier usage (`tests/test_model_hub_fast_usage.py`): fast rates, rows,
+ `fast_requests` in every aggregate, the schema, and both metering owners.
+ `MH-FAST-004` also checks that only the call that ran fast is billed as fast.
- Units: the hop rule (`tests/test_model_hub_fast_mode.py`), the Session field
and its dispatch read, the preference, the picker, and the new-session flow.
- Browser: the mark stays visible on a crowded 320px phone row.
diff --git a/docs/plans/model-hub-capability-model.md b/docs/plans/model-hub-capability-model.md
index 4b6a8a251..e14fd258d 100644
--- a/docs/plans/model-hub-capability-model.md
+++ b/docs/plans/model-hub-capability-model.md
@@ -268,6 +268,7 @@ and the existing tone vocabulary (`TimeHint` for dates):
| Token prices: input, output, cache read, cache write | models.dev base `cost.*`; the user's override file | used |
| One-hour cache write | override file, or 2× input by default (`pricing.py`) | used; models.dev has no field |
| **Context-tier prices** (a higher rate past a context size) | models.dev `cost.tiers[]` with `{"tier": {"type": "context", "size": N}}`, plus the legacy `cost.context_over_200k` (size 200K, read only when no context tier is usable); an override entry in the same shape. On 2026-10-13: 630 and 517 models (e.g. `gpt-6-astra` above 272K: $20/$75; `grok-4.6` above 200K: $4/$12) | used. `model_price` reads each tier by the flat-price rules and ignores an unusable one. A call whose total context input (input plus cache-read and cache-write tokens, which the ledger's `input_tokens` already counts) exceeds a size is billed whole at that tier's rates; the highest tier exceeded wins. The ledger keeps no per-call rows, so the usage writer decides the tier when it records a call, from a price table it reads off the event loop and holds for five minutes, and the tier is part of the row's identity (`context_tier`, persisted only above the base tier, so released rows read as base). Valuation prices each row at its own tier and sums tiers per Source and model; a tier the table no longer lists is valued at the largest listed tier below it. |
+| **Fast-tier prices** (the vendor's faster processing tier, docs/plans/fast-mode.md) | models.dev `experimental.modes.fast.cost`, read by the flat-price and context-tier rules into `ModelPrice.fast`. On 2026-10-31: e.g. `claude-opus-5-5` $8/$40 against $4/$20, `gpt-5.4` $5/$30 against $2.50/$15. Override entries carry none | used. The tier a call ran at is what its response says (Anthropic `usage.speed`, OpenAI `service_tier`), never what was asked; the usage writer records it as part of the row's identity (`speed: "fast"`, persisted only for the fast tier, so released rows read as standard, and a released reader folds a fast row into the standard one without losing a count). Valuation prices a fast row at the fast rates in the row's context tier, or at the standard rates as a lower bound where the table lists none. Summaries publish `fast_requests` beside `requests` |
| **Hosted-tool call prices** | overlay `providers.<vendor>.models[].hosted_tools.<protocol>.<tool>.price` (§4): unit, USD per 1,000 units, date and source URL | new. models.dev has none; the open proposal anomalyco/models.dev#8707 adds `cost.web_search = {search, prompt}` (no maintainer response yet) |
| Search-result tokens | the provider's usage (input tokens), priced by the token rows | already counted as input |
| Provider-reported cost | per-call usage, when present: xAI `cost_in_usd_ticks` (USD × 10¹⁰), `server_side_tool_usage_details`; Anthropic `server_tool_use.web_search_requests` | not read today; hosted tools read it (§6.4) |
diff --git a/docs/plans/model-hub-contracts/usage-summary.schema.json b/docs/plans/model-hub-contracts/usage-summary.schema.json
index 3ae2f70b2..5750fcadd 100644
--- a/docs/plans/model-hub-contracts/usage-summary.schema.json
+++ b/docs/plans/model-hub-contracts/usage-summary.schema.json
@@ -219,6 +219,10 @@
"excluded_service_requests": {
"$ref": "#/definitions/Count",
"description": "Billable search requests whose service has no current catalog price, so they are excluded from api_cost_usd. Present exactly when `pricing` is."
+ },
+ "fast_requests": {
+ "$ref": "#/definitions/Count",
+ "description": "Requests among `requests` whose response said they ran at the vendor's fast tier (Anthropic `usage.speed: \"fast\"`, OpenAI `service_tier: \"priority\"`; docs/plans/fast-mode.md). Their tokens are valued at the model's fast-tier rates, or at its standard rates as a lower bound where the price table lists none. Present only when at least one such request is in the aggregate."
}
}
},
@@ -294,6 +298,9 @@
},
"api_cost_lower_bound": {
"$ref": "#/definitions/Counters/properties/api_cost_lower_bound"
+ },
+ "fast_requests": {
+ "$ref": "#/definitions/Counters/properties/fast_requests"
}
}
},
@@ -464,6 +471,9 @@
},
"api_cost_lower_bound": {
"$ref": "#/definitions/Counters/properties/api_cost_lower_bound"
+ },
+ "fast_requests": {
+ "$ref": "#/definitions/Counters/properties/fast_requests"
}
}
},
@@ -537,6 +547,9 @@
"priced": {
"description": "Whether a price was found for this model. Present exactly when `pricing` is; false means the UI shows no price for it and its tokens are in excluded_tokens.",
"type": "boolean"
+ },
+ "fast_requests": {
+ "$ref": "#/definitions/Counters/properties/fast_requests"
}
}
},
@@ -673,6 +686,9 @@
},
"excluded_service_requests": {
"$ref": "#/definitions/Count"
+ },
+ "fast_requests": {
+ "$ref": "#/definitions/Counters/properties/fast_requests"
}
}
},
diff --git a/tests/scenarios/model_hub/test_model_hub_live_resolution_scenarios.py b/tests/scenarios/model_hub/test_model_hub_live_resolution_scenarios.py
index d75ff875e..98cdb1213 100644
--- a/tests/scenarios/model_hub/test_model_hub_live_resolution_scenarios.py
+++ b/tests/scenarios/model_hub/test_model_hub_live_resolution_scenarios.py
@@ -1679,7 +1679,7 @@ def test_mh_fast_004_the_response_confirms_whether_the_fast_tier_ran(
monkeypatch: pytest.MonkeyPatch,
stream: bool,
) -> None:
- """MH-FAST-004: a relay is asked for the fast tier too, and its responses decide whether the menu says it ran."""
+ """MH-FAST-004: a relay is asked for the fast tier too, and its responses decide whether the menu says it ran and what usage bills as fast."""
from vibe import models_dev_catalog
@@ -1740,6 +1740,9 @@ def test_mh_fast_004_the_response_confirms_whether_the_fast_tier_ran(
await turn("turn_standard", None)
assert menu() == (True, True)
assert [request.get("service_tier") for request in adapter.requests] == ["priority", "priority", None]
+ # Usage follows the same report: only the call that ran fast is billed as fast.
+ model = service.usage_summary(days=1)["sources"][0]["models"][0]
+ assert (model["requests"], model.get("fast_requests")) == (3, 1)
finally:
await gateway.close()
diff --git a/tests/test_model_hub_fast_usage.py b/tests/test_model_hub_fast_usage.py
new file mode 100644
index 000000000..74ffafee4
--- /dev/null
+++ b/tests/test_model_hub_fast_usage.py
@@ -0,0 +1,207 @@
+"""Fast-tier usage: recorded by what the response said, valued at fast rates (docs/plans/fast-mode.md).
+
+A call whose response named the vendor's fast tier is its own ledger row
+(`speed: "fast"`), valued at the models.dev `experimental.modes.fast.cost`
+rates, and counted as `fast_requests` in every published aggregate.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+import jsonschema
+import pytest
+
+from core.handlers.model_hub.pricing import PriceTable, model_price, row_cost
+from core.handlers.model_hub.stream_wire import ProtocolUsageReport
+from core.handlers.model_hub.usage import BoundedUsageLedger, SourceIdentity, UsageCall
+
+NOW = datetime(2026, 10, 31, 12, 0, tzinfo=timezone.utc)
+VENDOR_MAP = {"families": [{"prefix": "claude-", "vendor_id": "anthropic"}, {"prefix": "gpt-", "vendor_id": "openai"}]}
+CATALOG = {
+ "anthropic": {"models": {
+ "claude-opus-5-5": {
+ "cost": {"input": 4, "output": 20, "cache_read": 0.2, "cache_write": 5},
+ "experimental": {"modes": {"fast": {
+ "cost": {"input": 8, "output": 40, "cache_read": 0.4, "cache_write": 10},
+ "provider": {"body": {"speed": "fast"}},
+ }}},
+ },
+ # Listed without a fast tier.
+ "claude-sonnet-5-5": {"cost": {"input": 2, "output": 10, "cache_read": 0.2, "cache_write": 2.5}},
+ }},
+ "openai": {"models": {
+ "gpt-6-astra": {
+ "cost": {
+ "input": 10, "output": 50, "cache_read": 1,
+ "tiers": [{"input": 20, "output": 75, "cache_read": 2, "tier": {"type": "context", "size": 272000}}],
+ },
+ # The fast tier lists no context tier: it applies across the whole context.
+ "experimental": {"modes": {"fast": {"cost": {"input": 20, "output": 100, "cache_read": 2}}}},
+ },
+ }},
+}
+MILLION = ProtocolUsageReport.of(input_tokens=1_000_000, cached_input_tokens=0, output_tokens=1_000_000)
+
+
+def _table() -> PriceTable:
+ return PriceTable(catalog=CATALOG, vendor_map=VENDOR_MAP, overrides={}, price_table_date="2026-10-31")
+
+
+def _row(model_id: str, *, speed: str | None = None, context_tier: int = 0) -> dict:
+ return {
+ "model_id": model_id, "requests": 1, "token_reports": 1,
+ "input_tokens": 1_000_000, "cached_input_tokens": 0, "output_tokens": 1_000_000,
+ **({"speed": speed} if speed else {}), **({"context_tier": context_tier} if context_tier else {}),
+ }
+
+
+def test_the_price_table_reads_each_models_fast_tier_rates():
+ table = _table()
+ opus = table.price("claude-opus-5-5")
+ assert (opus.input, opus.output) == (4, 20)
+ assert (opus.fast.input, opus.fast.output, opus.fast.cache_read) == (8, 40, 0.4)
+ assert table.price("claude-sonnet-5-5").fast is None
+ # Read by the same rules: no usable standard price, no fast one either.
+ assert model_price({"output": 1}, fast_cost={"input": 1, "output": 1}) is None
+
+
+ ("model_id", "speed", "context_tier", "usd", "lower_bound"),
+ [
+ ("claude-opus-5-5", None, 0, 24.0, False),
+ ("claude-opus-5-5", "fast", 0, 48.0, False),
+ # Past a standard context tier, a fast call stays at the fast tier's flat rates.
+ ("gpt-6-astra", None, 272000, 95.0, False),
+ ("gpt-6-astra", "fast", 272000, 120.0, False),
+ # A fast row for a model the table lists no fast tier for: standard rates, as a floor.
+ ("claude-sonnet-5-5", "fast", 0, 12.0, True),
+ ],
+)
+def test_a_fast_row_is_valued_at_the_fast_tier_rates(model_id, speed, context_tier, usd, lower_bound):
+ cost = row_cost(_row(model_id, speed=speed, context_tier=context_tier), _table().price(model_id))
+ assert cost.api_cost_usd == pytest.approx(usd)
+ assert cost.api_cost_lower_bound is lower_bound
+
+
+def test_fast_and_standard_calls_keep_their_own_rows_and_every_aggregate_counts_the_fast_ones(tmp_path):
+ path = tmp_path / "usage.json"
+ ledger = BoundedUsageLedger(path, now=lambda: NOW)
+ ledger.record_many([
+ UsageCall("src_relay", "claude-opus-5-5", MILLION, NOW),
+ UsageCall("src_relay", "claude-opus-5-5", MILLION, NOW, speed="fast"),
+ UsageCall("src_relay", "claude-opus-5-5", MILLION, NOW, speed="fast"),
+ ])
+ persisted = json.loads(path.read_text(encoding="utf-8"))
+ assert sorted((row.get("speed", ""), row["requests"]) for row in persisted) == [("", 1), ("fast", 2)]
+
+ identities = [SourceIdentity("src_relay", "Relay", ["claude-opus-5-5"])]
+ summary = ledger.summary(days=1, now=NOW, identities=identities, prices=_table())
+ model = summary["sources"][0]["models"][0]
+ for aggregate in (summary["totals"], summary["sources"][0], model, summary["days"][0]):
+ assert (aggregate["requests"], aggregate["fast_requests"]) == (3, 2)
+ # One standard million-and-million, two fast ones.
+ assert model["api_cost_usd"] == pytest.approx(24 + 2 * 48)
+ for window in ("24h", "7d"):
+ rows = [row for bucket in ledger.report(window=window, now=NOW, identities=identities)["buckets"]
+ for row in bucket["rows"]]
+ assert [(row["requests"], row["fast_requests"]) for row in rows] == [(3, 2)]
+
+
+def test_an_aggregate_without_a_fast_request_keeps_the_released_shape(tmp_path):
+ ledger = BoundedUsageLedger(tmp_path / "usage.json", now=lambda: NOW)
+ ledger.record_many([UsageCall("src_a", "claude-opus-5-5", MILLION, NOW)])
+ summary = ledger.summary(days=1, now=NOW)
+ assert "fast_requests" not in summary["totals"]
+ assert "fast_requests" not in summary["sources"][0]["models"][0]
+
+
+def test_the_summary_still_matches_its_published_schema(tmp_path):
+ with open("docs/plans/model-hub-contracts/usage-summary.schema.json", encoding="utf-8") as handle:
+ schema = json.load(handle)
+ ledger = BoundedUsageLedger(tmp_path / "usage.json", now=lambda: NOW)
+ ledger.record_many([UsageCall("src_a", "claude-opus-5-5", MILLION, NOW, speed="fast")])
+ summary = ledger.summary(
+ days=1, now=NOW, identities=[SourceIdentity("src_a", "A", ["claude-opus-5-5"])], prices=_table(),
+ )
+ jsonschema.validate({**summary, "pricing": {"currency": "USD", "price_table_date": "2026-10-31"}}, schema)
+
+
+def test_a_persisted_speed_is_read_back_and_an_unknown_one_drops_only_its_row(tmp_path):
+ path = tmp_path / "usage.json"
+ ledger = BoundedUsageLedger(path, now=lambda: NOW)
+ ledger.record_many([UsageCall("src_a", "claude-opus-5-5", MILLION, NOW, speed="fast")])
+ rows = json.loads(path.read_text(encoding="utf-8"))
+ unknown = {**rows[0], "model_id": "claude-sonnet-5-5", "speed": "turbo"}
+ path.write_text(json.dumps([*rows, unknown]), encoding="utf-8")
+
+ summary = BoundedUsageLedger(path, now=lambda: NOW).summary(days=1, now=NOW)
+ assert summary["totals"]["requests"] == 1
+ assert summary["totals"]["fast_requests"] == 1
+
+
+def test_a_call_the_resolver_meters_is_billed_at_the_tier_its_outcome_reported(tmp_path):
+ """The resolver's half of metering reads the tier the same way the gateway does."""
+
+ import asyncio
+ from types import SimpleNamespace
+
+ from core.handlers.model_hub.adapter import RawCallOutcome, RawOutcomeKind
+ from core.handlers.model_hub.service import ModelHubService
+ from core.handlers.model_hub.stream_wire import ProtocolSSEState
+ from core.handlers.model_hub.usage import UsageWriter
+
+ ledger = BoundedUsageLedger(tmp_path / "usage.json", now=lambda: NOW)
+
+ async def meter() -> None:
+ owner = SimpleNamespace(usage_writer=UsageWriter(ledger), now=lambda: NOW)
+ served = RawCallOutcome(
+ kind=RawOutcomeKind.SUCCESS, http_status=200, error_code=None, redacted_message=None,
+ stream_started=False, model_id="claude-opus-5-5", source_id="src_a", usage=MILLION, served_tier="fast",
+ )
+ await ModelHubService._meter_call(owner, source_id="src_a", model_id="claude-opus-5-5", outcome=served, observed=None)
+ # A stream the resolver closed itself: its tracker's tier.
+ observed = ProtocolSSEState("anthropic")
+ observed.usage, observed.served_tier, observed.model_output_started = MILLION, "standard", True
+ await ModelHubService._meter_call(owner, source_id="src_a", model_id="claude-opus-5-5", outcome=None, observed=observed)
+
+ asyncio.run(meter())
+ totals = ledger.summary(days=1, now=NOW)["totals"]
+ assert (totals["requests"], totals["fast_requests"]) == (2, 1)
+
+
+def test_a_fast_call_is_placed_by_the_fast_rates_own_context_sizes(tmp_path):
+ """Flat standard rates, fast rates that rise past 100K: a 150K fast call is billed in that fast tier."""
+
+ import asyncio
+
+ from core.handlers.model_hub.usage import UsageWriter
+
+ catalog = {"anthropic": {"models": {"claude-opus-9": {
+ "cost": {"input": 5, "output": 25},
+ "experimental": {"modes": {"fast": {"cost": {
+ "input": 10, "output": 50,
+ "tiers": [{"input": 20, "output": 100, "tier": {"type": "context", "size": 100_000}}],
+ }}}},
+ }}}}
+
+ def table() -> PriceTable:
+ return PriceTable(catalog=catalog, vendor_map=VENDOR_MAP, overrides={}, price_table_date="2026-10-31")
+
+ ledger = BoundedUsageLedger(tmp_path / "usage.json", now=lambda: NOW)
+ usage = ProtocolUsageReport.of(input_tokens=150_000, cached_input_tokens=0, output_tokens=0)
+
+ async def record() -> None:
+ writer = UsageWriter(ledger, price_table=table)
+ writer.record(source_id="src_a", model_id="claude-opus-9", usage=usage, at=NOW, speed="fast")
+ writer.record(source_id="src_a", model_id="claude-opus-9", usage=usage, at=NOW)
+ assert await writer.drain(timeout=5) == 0
+
+ asyncio.run(record())
+ rows = {row.get("speed", ""): row for row in json.loads(ledger.path.read_text(encoding="utf-8"))}
+ assert rows["fast"].get("context_tier") == 100_000
+ assert "context_tier" not in rows[""]
+ summary = ledger.summary(days=1, now=NOW, prices=table())
+ # 150K at the fast tier's $20, plus 150K at the flat standard $5.
+ assert summary["totals"]["api_cost_usd"] == pytest.approx(150_000 * 20 / 1e6 + 150_000 * 5 / 1e6)
diff --git a/tests/test_model_hub_pricing.py b/tests/test_model_hub_pricing.py
index b03aa99c4..776227ba8 100644
--- a/tests/test_model_hub_pricing.py
+++ b/tests/test_model_hub_pricing.py
@@ -1132,9 +1132,9 @@ def test_a_price_table_parses_every_price_when_built_and_none_on_lookup(monkeypa
parsed = []
original = pricing.model_price
- def counting(cost):
+ def counting(cost, **kwargs):
parsed.append(cost)
- return original(cost)
+ return original(cost, **kwargs)
monkeypatch.setattr(pricing, "model_price", counting)
table = _table(overrides={"models": {"house-model": {"input": 1, "output": 2}, "relay-opus": {"alias": "claude-opus-5"}}})