From 7aa9f86427f5eb0260f4dcb386538d9cf4de7e05 Mon Sep 17 00:00:00 2001 From: 1bcMax Date: Thu, 19 Nov 2026 11:41:38 -0600 Subject: [PATCH] fix(router): cost_estimate reads the per-row platform fee (PF-8) Per-token paid chat is charged list rates x (1 + platform_fee_percent/100). build_model_pricing now carries the fee from pricing.platform_fee_percent, falling back to the row's top-level field, 0 when absent or unusable, and 0 for free, flat, media and Decisions rows. route_with_catalog uses it for the per-token estimate instead of Router Core's hardcoded server margin; flat and unpriced entries keep Router Core's estimate. --- CHANGELOG.md | 11 + blockrun_llm/router_adapter.py | 83 +++++++- tests/unit/test_platform_fee_estimate.py | 244 +++++++++++++++++++++++ tests/unit/test_routing_parity.py | 1 + 4 files changed, 337 insertions(+), 2 deletions(-) create mode 100644 tests/unit/test_platform_fee_estimate.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 672658a..5c5bf9f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,17 @@ All notable changes to blockrun-llm will be documented in this file. ## Unreleased +### Fixed +- **Routing `cost_estimate` includes the platform fee.** blockrun.ai and + sol.blockrun.ai charge per-token paid chat its list rates times + `1 + platform_fee_percent / 100`, published on each `/v1/models` chat row + (inside `pricing`, and at the row's top level on blockrun.ai). The estimate + now reads that field (`pricing` first, then the top level) instead of a + hardcoded server margin, so it is 0 on gateways that do not send it (older + gateways, enterprise). Free, flat, media and Decisions rows never pay it. + The real charge is still the gateway's 402 quote, and the spend limits still + check that quote. + ## 1.23.1 — 2026-11-18 ### Fixed diff --git a/blockrun_llm/router_adapter.py b/blockrun_llm/router_adapter.py index d233111..a518528 100644 --- a/blockrun_llm/router_adapter.py +++ b/blockrun_llm/router_adapter.py @@ -26,6 +26,7 @@ get_fallback_chain, route, ) +from .router_core.selector import usable_pricing from .router_core.types import ( Capacity, ModelPricing, @@ -36,6 +37,18 @@ ) +class CatalogPricing(ModelPricing, total=False): + """A Router Core price entry plus the gateway's per-token platform fee. + + ``platform_fee_percent`` is what an x402 call to a per-token paid chat row + pays on top of its list ``input`` / ``output`` rates (spec PF-8). Router + Core ignores it; :func:`route_with_catalog` reads it for ``cost_estimate``. + Absent means 0. + """ + + platform_fee_percent: float + + class ResolvedRoutingDecision(RoutingDecision, total=False): """A Router Core decision resolved against the live BlockRun catalog. @@ -218,7 +231,61 @@ def _version_key(model_id: str) -> list[Any]: ] -def build_model_pricing(models: list[dict[str, Any]]) -> dict[str, ModelPricing]: +def _fee_percent(value: object) -> float | None: + if isinstance(value, bool) or not isinstance(value, (int, float)): + return None + if not math.isfinite(value) or value < 0: + return None + return float(value) + + +def platform_fee_percent(model: Mapping[str, Any]) -> float: + """The platform fee percent a ``/v1/models`` row's per-token price pays on top. + + The gateways charge per-token paid chat its list rates multiplied by + ``1 + platform_fee_percent / 100`` (spec PF-8). The field is read from + ``pricing.platform_fee_percent`` (both gateways), then from the row's top + level (blockrun.ai also publishes it there). It is 0 when neither is a + finite, non-negative number — older gateways and the enterprise gateway do + not send it — and 0 for any row that is not a per-token paid chat row: + free rows, flat rows, media and Decisions never pay it. + """ + billing_mode = model.get("billing_mode") + if billing_mode is not None and billing_mode != "paid": + return 0.0 + block = model.get("pricing") + if isinstance(block, Mapping): + if block.get("flat"): + return 0.0 + nested = _fee_percent(block.get("platform_fee_percent")) + if nested is not None: + return nested + if model.get("flatPrice") or model.get("flat_price"): + return 0.0 + top_level = _fee_percent(model.get("platform_fee_percent")) + return top_level if top_level is not None else 0.0 + + +def token_cost_usd( + pricing: ModelPricing | None, estimated_input_tokens: int, max_output_tokens: int +) -> float | None: + """Estimated USD for a per-token entry, platform fee included. + + ``None`` for a flat entry, a missing one, or one with an unusable price — + those keep Router Core's own estimate. + """ + entry = usable_pricing(pricing) + if entry is None or entry.get("flat_price"): + return None + list_cost = ( + estimated_input_tokens * entry.get("input_price", 0) + + max_output_tokens * entry.get("output_price", 0) + ) / 1_000_000 + fee = _fee_percent(dict(entry).get("platform_fee_percent")) or 0.0 + return list_cost * (1 + fee / 100) + + +def build_model_pricing(models: list[dict[str, Any]]) -> dict[str, CatalogPricing]: """Build the router's pricing map from a ``/v1/models`` payload. Shared by every client (Base and Solana, sync and async) so the four copies @@ -228,7 +295,10 @@ def build_model_pricing(models: list[dict[str, Any]]) -> dict[str, ModelPricing] The catalog uses the nested ``pricing.input`` / ``pricing.output`` shape; older snapshots used top-level ``inputPrice`` / ``outputPrice``. Both are - accepted so the SDK keeps working through backend transitions. + accepted so the SDK keeps working through backend transitions. Each entry + also carries the row's ``platform_fee_percent`` (see + :func:`platform_fee_percent`), so ``cost_estimate`` matches what the + gateway quotes for per-token paid chat. """ pricing = ModelPricingMap() for model in models: @@ -245,6 +315,7 @@ def build_model_pricing(models: list[dict[str, Any]]) -> dict[str, ModelPricing] "input_price": float(input_price or 0), "output_price": float(output_price or 0), "flat_price": float(flat_price or 0), + "platform_fee_percent": platform_fee_percent(model), } xai_chat = [ model @@ -486,6 +557,14 @@ def route_with_catalog( costs = calculate_model_cost( model, model_pricing, estimated_input_tokens, max_output_tokens, routing_profile ) + # A per-token row's estimate is its list cost times (1 + platform_fee_percent + # / 100), the fee the catalog publishes per row (0 when absent). Router + # Core's calculate_model_cost instead multiplies by a hardcoded server + # margin, which is not the per-row fee (enterprise and older gateways charge + # none). Flat and unpriced entries keep Router Core's estimate. + token_cost = token_cost_usd(model_pricing.get(model), estimated_input_tokens, max_output_tokens) + if token_cost is not None: + costs["cost_estimate"] = token_cost # Free models settle at $0 (no payment is signed) — never floor them up to # the paid minimum. Detected from the catalog pricing, because Router Core's # calculate_model_cost applies its own internal floor even to $0 models. diff --git a/tests/unit/test_platform_fee_estimate.py b/tests/unit/test_platform_fee_estimate.py new file mode 100644 index 0000000..9abbd62 --- /dev/null +++ b/tests/unit/test_platform_fee_estimate.py @@ -0,0 +1,244 @@ +""" +The routing cost estimate includes the gateway's per-token platform fee (spec PF-8). + +blockrun.ai and sol.blockrun.ai charge per-token paid chat its list +``pricing.input`` / ``pricing.output`` rates times ``1 + platform_fee_percent / +100``. The fee rides on each ``/v1/models`` chat row: inside ``pricing`` on both +gateways, and at the row's top level on blockrun.ai. Older gateways and the +enterprise gateway do not send it, so absent means 0. Free, flat, media and +Decisions rows never pay it. +""" + +from __future__ import annotations + +import math + +import pytest + +from blockrun_llm.router_adapter import ( + BASE_MINIMUM_PAYMENT_USD, + build_model_pricing, + platform_fee_percent, + route_with_catalog, + token_cost_usd, +) +from blockrun_llm.router_core import DEFAULT_MODEL_CAPABILITIES + +FEE = 5 # what the rows below publish; the SDK reads it, it never assumes it + + +class TestPlatformFeePercent: + def test_reads_the_field_inside_pricing(self): + row = { + "id": "a/b", + "billing_mode": "paid", + "pricing": {"input": 1, "output": 2, "platform_fee_percent": FEE}, + } + assert platform_fee_percent(row) == FEE + + def test_falls_back_to_the_top_level_field(self): + row = { + "id": "a/b", + "billing_mode": "paid", + "platform_fee_percent": FEE, + "pricing": {"input": 1, "output": 2}, + } + assert platform_fee_percent(row) == FEE + + def test_prefers_the_nested_field_over_the_top_level_one(self): + row = { + "id": "a/b", + "billing_mode": "paid", + "platform_fee_percent": 9, + "pricing": {"input": 1, "output": 2, "platform_fee_percent": 3}, + } + assert platform_fee_percent(row) == 3 + + def test_is_zero_when_the_gateway_does_not_send_it(self): + # Older gateways, and enterprise (PF-9), publish no fee. + assert platform_fee_percent({"id": "a/b", "pricing": {"input": 1, "output": 2}}) == 0 + assert platform_fee_percent({"id": "a/b", "inputPrice": 1, "outputPrice": 2}) == 0 + + @pytest.mark.parametrize("bad", [None, "5", True, -1, math.nan, math.inf, [5]]) + def test_an_unusable_value_is_zero(self, bad): + row = { + "id": "a/b", + "billing_mode": "paid", + "pricing": {"input": 1, "platform_fee_percent": bad}, + } + assert platform_fee_percent(row) == 0 + + def test_an_unusable_nested_value_still_falls_back_to_the_top_level(self): + row = { + "id": "a/b", + "billing_mode": "paid", + "platform_fee_percent": FEE, + "pricing": {"input": 1, "platform_fee_percent": "oops"}, + } + assert platform_fee_percent(row) == FEE + + @pytest.mark.parametrize( + "row", + [ + # Free rows publish 0 at top level and nothing nested. + { + "id": "nvidia/x", + "billing_mode": "free", + "platform_fee_percent": FEE, + "pricing": {"input": 0, "output": 0, "platform_fee_percent": FEE}, + }, + # Flat rows: the flat price is final. + { + "id": "openai/gpt-oss-20b", + "billing_mode": "flat", + "platform_fee_percent": FEE, + "pricing": {"flat": 0.002, "platform_fee_percent": FEE}, + }, + {"id": "a/flat", "platform_fee_percent": FEE, "pricing": {"flat": 0.002}}, + # Media rows. + { + "id": "openai/gpt-image-2", + "billing_mode": "per_image", + "pricing": {"per_image": 0.04, "platform_fee_percent": FEE}, + }, + # Decisions bill per token but pay no platform fee (PF-5). + { + "id": "openai/gpt-6-luna-decisions", + "billing_mode": "per_token", + "pricing": {"input": 0.1, "output": 0, "platform_fee_percent": FEE}, + }, + ], + ids=["free", "flat", "flat-no-billing-mode", "media", "decisions"], + ) + def test_never_applies_outside_per_token_paid_chat(self, row): + assert platform_fee_percent(row) == 0 + + +class TestPricingMap: + def test_entries_carry_the_fee(self): + pricing = build_model_pricing( + [ + { + "id": "base/row", + "billing_mode": "paid", + "platform_fee_percent": FEE, + "pricing": {"input": 1, "output": 2, "platform_fee_percent": FEE}, + }, + { + "id": "sol/row", + "billing_mode": "paid", + "pricing": {"input": 1, "output": 2, "platform_fee_percent": FEE}, + }, + { + "id": "enterprise/row", + "billing_mode": "paid", + "pricing": {"input": 1, "output": 2}, + }, + { + "id": "nvidia/free", + "billing_mode": "free", + "platform_fee_percent": 0, + "pricing": {"input": 0, "output": 0}, + }, + ] + ) + assert pricing["base/row"]["platform_fee_percent"] == FEE + assert pricing["sol/row"]["platform_fee_percent"] == FEE + assert pricing["enterprise/row"]["platform_fee_percent"] == 0 + assert pricing["nvidia/free"]["platform_fee_percent"] == 0 + # The list rates are untouched: the fee is applied to the estimate only. + assert pricing["base/row"]["input_price"] == 1 + assert pricing["base/row"]["output_price"] == 2 + + +class TestTokenCost: + def test_multiplies_the_list_cost_by_the_fee(self): + entry = {"input_price": 2, "output_price": 10, "flat_price": 0, "platform_fee_percent": FEE} + list_cost = (1_000 * 2 + 500 * 10) / 1_000_000 + assert token_cost_usd(entry, 1_000, 500) == pytest.approx(list_cost * (1 + FEE / 100)) + + def test_no_fee_field_is_the_list_cost(self): + entry = {"input_price": 2, "output_price": 10, "flat_price": 0} + assert token_cost_usd(entry, 1_000, 500) == pytest.approx((1_000 * 2 + 500 * 10) / 1e6) + + def test_flat_and_unpriced_entries_are_not_token_priced(self): + assert ( + token_cost_usd({"flat_price": 0.002, "platform_fee_percent": FEE}, 1_000, 500) is None + ) + assert token_cost_usd(None, 1_000, 500) is None + assert token_cost_usd({"input_price": math.nan, "output_price": 1}, 1_000, 500) is None + + +PROMPT = "Design a distributed ledger with Byzantine fault tolerance and prove liveness" + + +def _catalog(**row_extra): + """Every model the router can rank, priced alike, so whatever it picks is priced.""" + return [ + { + "id": model, + "billing_mode": "paid", + **row_extra.get("top", {}), + "pricing": {"input": 2, "output": 10, **row_extra.get("nested", {})}, + } + for model in DEFAULT_MODEL_CAPABILITIES + ] + + +def _route(catalog, max_tokens=4_000, profile="auto"): + return route_with_catalog( + PROMPT, + None, + max_tokens, + build_model_pricing(catalog), + routing_profile=profile, + minimum_payment_usd=BASE_MINIMUM_PAYMENT_USD, + ) + + +def _list_cost(max_tokens): + prompt_tokens = math.ceil(len(f" {PROMPT}") / 4) + return (prompt_tokens * 2 + max_tokens * 10) / 1_000_000 + + +class TestCostEstimate: + def test_paid_chat_estimate_includes_the_nested_fee(self): + decision = _route(_catalog(nested={"platform_fee_percent": FEE})) + assert decision["cost_estimate"] == pytest.approx(_list_cost(4_000) * (1 + FEE / 100)) + + def test_top_level_fee_is_used_when_pricing_has_none(self): + decision = _route(_catalog(top={"platform_fee_percent": FEE})) + assert decision["cost_estimate"] == pytest.approx(_list_cost(4_000) * (1 + FEE / 100)) + + def test_absent_fee_estimates_at_list_price(self): + # Older gateways and enterprise send no fee: no hidden margin is added. + decision = _route(_catalog()) + assert decision["cost_estimate"] == pytest.approx(_list_cost(4_000)) + + def test_the_fee_does_not_change_which_model_is_picked(self): + with_fee = _route(_catalog(nested={"platform_fee_percent": FEE})) + without = _route(_catalog()) + assert with_fee["model"] == without["model"] + assert with_fee["fallbacks"] == without["fallbacks"] + + def test_free_models_stay_at_zero(self): + catalog = [ + { + "id": model, + "billing_mode": "free", + "platform_fee_percent": 0, + "pricing": {"input": 0, "output": 0}, + } + for model in ( + "nvidia/nemotron-3.5-lightning", + "nvidia/nemotron-3-ultra-550b", + "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning", + "nvidia/nemotron-3.5-bolt", + "poolside/laguna-xs-2.1", + ) + ] + assert _route(catalog, profile="free")["cost_estimate"] == 0 + + def test_a_small_paid_call_is_still_floored(self): + decision = _route(_catalog(nested={"platform_fee_percent": FEE}), max_tokens=1) + assert decision["cost_estimate"] == pytest.approx(BASE_MINIMUM_PAYMENT_USD) diff --git a/tests/unit/test_routing_parity.py b/tests/unit/test_routing_parity.py index 1d0cfc8..5c7e573 100644 --- a/tests/unit/test_routing_parity.py +++ b/tests/unit/test_routing_parity.py @@ -104,6 +104,7 @@ def test_skips_rows_the_catalog_marks_unavailable(self): "input_price": 0.15, "output_price": 0.6, "flat_price": 0.0, + "platform_fee_percent": 0.0, } def test_accepts_the_legacy_top_level_price_shape(self):