Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
83 changes: 81 additions & 2 deletions blockrun_llm/router_adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
get_fallback_chain,
route,
)
from .router_core.selector import usable_pricing
from .router_core.types import (
Capacity,
ModelPricing,
Expand All @@ -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.

Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down
244 changes: 244 additions & 0 deletions tests/unit/test_platform_fee_estimate.py
Original file line number Diff line number Diff line change
@@ -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)
1 change: 1 addition & 0 deletions tests/unit/test_routing_parity.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
Loading