unitysvc-core 0.2.27__tar.gz → 0.2.29__tar.gz

{unitysvc_core-0.2.27/src/unitysvc_core.egg-info → unitysvc_core-0.2.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.2.27
+Version: 0.2.29
 Summary: Shared data models and validation helpers for UnitySVC packages
 Author-email: Bo Peng <bo.peng@unitysvc.com>
 Maintainer-email: Bo Peng <bo.peng@unitysvc.com>

{unitysvc_core-0.2.27 → unitysvc_core-0.2.29}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unitysvc-core"
-version = "0.2.27"
+version = "0.2.29"
 description = "Shared data models and validation helpers for UnitySVC packages"
 readme = "README.md"
 authors = [{ name = "Bo Peng", email = "bo.peng@unitysvc.com" }]

{unitysvc_core-0.2.27 → unitysvc_core-0.2.29}/src/unitysvc_core/models/__init__.py

@@ -38,6 +38,7 @@ from .pricing import (
     ConstantPriceData,
     CountPriceData,
     DataPriceData,
+    EffectivePrice,
     ExprPriceData,
     FirstPriceData,
     GraduatedPriceData,
@@ -56,6 +57,7 @@ from .pricing import (
     TimePriceData,
     TokenPriceData,
     UsageData,
+    upstream_price_from_description,
     validate_pricing,
 )
 from .promotion_data import (
@@ -146,6 +148,8 @@ __all__ = [
     "Pricing",
     "validate_pricing",
     "BasePriceData",
+    "EffectivePrice",
+    "upstream_price_from_description",
     # Pricing — simple types
     "TokenPriceData",
     "TimePriceData",

{unitysvc_core-0.2.27 → unitysvc_core-0.2.29}/src/unitysvc_core/models/pricing.py

@@ -13,6 +13,8 @@ from __future__ import annotations
 
 import ast
 import operator
+import re
+from collections.abc import Callable, Iterable
 from decimal import Decimal, InvalidOperation
 from typing import Annotated, Any, Literal
 
@@ -171,6 +173,192 @@ class UsageData(BaseModel):
     one_million: float | None = None
 
 
+# ============================================================================
+# Effective price — a per-unit comparison figure, never billed
+# ============================================================================
+
+#: Normalized units an effective price is expressed in. Each dimension has one,
+#: so figures of the same dimension always compare directly.
+UNIT_TOKENS = "one_million_tokens"
+UNIT_REQUEST = "request"
+UNIT_TIME = "one_hour"
+UNIT_DATA = "one_gigabyte"
+UNIT_CHARACTERS = "one_million_characters"
+UNIT_IMAGE = "image"
+UNIT_STEP = "step"
+
+#: Each measured equivalence group's normalized unit (counts compare per request).
+_GROUP_UNIT = {
+    "tokens": UNIT_TOKENS,
+    "time": UNIT_TIME,
+    "data": UNIT_DATA,
+    "characters": UNIT_CHARACTERS,
+}
+
+#: When figures in different units must be reduced to one (``max``, ``min``,
+#: ``tiered``, ``channel``), the first unit present in this order wins; any
+#: other unit follows alphabetically.
+_UNIT_PRIORITY = (UNIT_TOKENS, UNIT_REQUEST)
+
+#: Output tokens weigh 4x input: typical chat traffic, and the platform's
+#: long-standing blend convention.
+_OUTPUT_WEIGHT = Decimal(4)
+
+
+class EffectivePrice(BaseModel):
+    """What using a service realistically costs per unit, for comparison.
+
+    A best-effort estimate for sorting, filtering and routing — never billed.
+    ``price`` (when set) is what is charged; this is computed from the pricing
+    object by ``effective_price()`` and never written back into it.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    amount: Decimal = Field(description="Cost per one ``unit``")
+    unit: str = Field(
+        description="Normalized unit: 'one_million_tokens', 'request', 'one_hour', 'one_gigabyte', "
+        "'one_million_characters', 'image' or 'step'",
+    )
+    source: Literal["rate", "upstream"] = Field(
+        default="rate",
+        description="'rate': from the price itself. 'upstream': a $0 price whose description states what the "
+        "customer pays the upstream provider (bring-your-own-key).",
+    )
+
+
+def _blend(tokens_in: Decimal, tokens_out: Decimal) -> Decimal:
+    return (tokens_in + _OUTPUT_WEIGHT * tokens_out) / (1 + _OUTPUT_WEIGHT)
+
+
+def _unit_rank(unit: str) -> tuple[int, str]:
+    return (_UNIT_PRIORITY.index(unit), "") if unit in _UNIT_PRIORITY else (len(_UNIT_PRIORITY), unit)
+
+
+def _child_effective_price(price_data: Any) -> EffectivePrice | None:
+    """The effective price of a nested pricing dict; None if it is unknown or invalid."""
+    if not isinstance(price_data, dict):
+        return None
+    try:
+        return validate_pricing(price_data).effective_price()
+    except Exception:
+        return None
+
+
+def _pick(
+    figures: Iterable[EffectivePrice | None],
+    choose: Callable[[Iterable[EffectivePrice]], EffectivePrice],
+) -> EffectivePrice | None:
+    """Reduce known figures to one, comparing only within the dominant unit."""
+    known = [f for f in figures if f is not None]
+    if not known:
+        return None
+    unit = min((f.unit for f in known), key=_unit_rank)
+    return choose(f for f in known if f.unit == unit)
+
+
+def _largest(figures: Iterable[EffectivePrice | None]) -> EffectivePrice | None:
+    return _pick(figures, lambda fs: max(fs, key=lambda f: f.amount))
+
+
+def _smallest(figures: Iterable[EffectivePrice | None]) -> EffectivePrice | None:
+    return _pick(figures, lambda fs: min(fs, key=lambda f: f.amount))
+
+
+def _rate(amount: Decimal, unit: str) -> EffectivePrice:
+    return EffectivePrice(amount=amount, unit=unit)
+
+
+def _per_normalized_unit(metric: str, unit_price: Decimal) -> EffectivePrice | None:
+    """Express a price per one ``metric`` in the metric dimension's normalized unit.
+
+    ``metric`` is a pricing type or a ``based_on`` name: an equivalence-group
+    unit, a token counter, ``request_count``, or a gateway byte counter. Any
+    other metric (``customer_charge``, an expression) has no unit: None.
+    """
+    if metric in ("input_tokens", "output_tokens", "cached_input_tokens", "total_tokens"):
+        metric = "one_token"
+    elif metric in ("bytes_in", "bytes_out", "bytes_total"):
+        metric = "one_byte"
+    if metric == "request_count":
+        return _rate(unit_price, UNIT_REQUEST)
+    if metric == "images_generated":
+        return _rate(unit_price, UNIT_IMAGE)
+    if metric not in _UNIT_TO_GROUP:
+        return None
+    group, factor = _UNIT_TO_GROUP[metric]
+    if group == "count":
+        # One count is one call, event or message: compared per request.
+        return _rate(unit_price / factor, UNIT_REQUEST)
+    target = _GROUP_UNIT[group]
+    return _rate(unit_price * EQUIVALENCE_GROUPS[group][target] / factor, target)
+
+
+_DOLLARS = r"\$\s*\d+(?:\.\d+)?"
+# "$1.4 / $4.4 per 1M input/output tokens", "$1.518/$4.554 / 1M input/output
+# tokens", "$4 / $20 / $0.2 per 1M input/output/cached tokens",
+# "$3.45/$0.345/$17.25 / 1M in/cached/out tokens", "$0.50 / 1M tokens".
+_UPSTREAM_TOKEN_PRICE = re.compile(
+    rf"(?P<amounts>{_DOLLARS}(?:\s*/\s*{_DOLLARS})*)\s*(?:/|per)\s*1\s*(?P<scale>[MK])\s+"
+    r"(?:(?P<labels>[a-z_]+(?:\s*/\s*[a-z_]+)*)\s+)?tokens\b",
+    re.IGNORECASE,
+)
+_UPSTREAM_LABELS = {
+    "input": "in",
+    "in": "in",
+    "output": "out",
+    "out": "out",
+    "cached": "cached",
+    "cache": "cached",
+    "cached_input": "cached",
+}
+
+
+def upstream_price_from_description(text: str | None) -> Decimal | None:
+    """The upstream price per 1M tokens a description states, blended; or None.
+
+    Bring-your-own-key prices are ``0`` (we bill nothing) and their generators
+    write what the provider charges into the description, e.g. "billed by
+    Hugging Face directly at $1.4 / $4.4 per 1M input/output tokens".
+
+    Fails closed: text not in a known shape (labels that don't match the
+    amounts, no input/output pair, no token unit) is None, never 0.
+    """
+    if not text:
+        return None
+    match = _UPSTREAM_TOKEN_PRICE.search(text)
+    if match is None:
+        return None
+    amounts = [Decimal(a) for a in re.findall(r"\d+(?:\.\d+)?", match["amounts"])]
+    scale = Decimal(1000) if match["scale"].upper() == "K" else Decimal(1)
+    if not match["labels"]:
+        return amounts[0] * scale if len(amounts) == 1 else None
+    labels = [_UPSTREAM_LABELS.get(label.strip().lower()) for label in match["labels"].split("/")]
+    if len(labels) != len(amounts) or None in labels:
+        return None
+    by_label = dict(zip(labels, amounts, strict=True))
+    if "in" not in by_label or "out" not in by_label:
+        return None
+    return _blend(by_label["in"], by_label["out"]) * scale
+
+
+def _zero_rate(figure: EffectivePrice, description: str | None) -> EffectivePrice | None:
+    """A zero-rate price's effective price: free, or what the customer pays upstream.
+
+    A ``0`` with a description is a bring-your-own-key price: the customer pays
+    the upstream provider, at the rate the description states. A description
+    that states no parseable rate, or $0/$0 (what generators write when they
+    lack the provider's price), is unknown. A ``0`` with no description is
+    genuinely free.
+    """
+    if figure.amount != 0 or not description:
+        return figure
+    upstream = upstream_price_from_description(description)
+    if upstream is None or upstream == 0:
+        return None
+    return EffectivePrice(amount=upstream, unit=UNIT_TOKENS, source="upstream")
+
+
 # ============================================================================
 # Pricing Models - Discriminated Union for type-safe pricing validation
 # ============================================================================
@@ -207,6 +395,15 @@ class BasePriceData(BaseModel):
         description="URL to upstream provider's pricing page",
     )
 
+    def effective_price(self) -> EffectivePrice | None:
+        """What using this price realistically costs per unit, or None if unknown.
+
+        A comparison figure for sorting, filtering and routing; never billed.
+        Every pricing type defines it, so a composite price computes its figure
+        from its children. Unknown is never 0. Never raises.
+        """
+        return None
+
 
 class TokenPriceData(BasePriceData):
     """
@@ -294,6 +491,21 @@ class TokenPriceData(BasePriceData):
         """Token divisor based on the pricing type."""
         return {"one_million_tokens": 1_000_000, "one_thousand_tokens": 1_000, "one_token": 1}[self.type]
 
+    def effective_price(self) -> EffectivePrice | None:
+        """``(input + 4*output) / 5`` when priced separately, else ``price``; per 1M tokens.
+
+        A zero rate with a description is a bring-your-own-key price: see
+        ``_zero_rate``.
+        """
+        if self.input is not None and self.output is not None:
+            per_unit = _blend(Decimal(self.input), Decimal(self.output))
+        elif self.price is not None:
+            per_unit = Decimal(self.price)
+        else:
+            return None
+        figure = _per_normalized_unit(self.type, per_unit)
+        return None if figure is None else _zero_rate(figure, self.description)
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -361,6 +573,10 @@ class TimePriceData(BasePriceData):
         description="Price per one unit of the specified type",
     )
 
+    def effective_price(self) -> EffectivePrice | None:
+        """``price`` in the dimension's normalized unit."""
+        return _per_normalized_unit(self.type, Decimal(self.price))
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -402,6 +618,10 @@ class ImagePriceData(BasePriceData):
         description="Price per image",
     )
 
+    def effective_price(self) -> EffectivePrice | None:
+        """``price`` per image."""
+        return _rate(Decimal(self.price), UNIT_IMAGE)
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -442,6 +662,10 @@ class StepPriceData(BasePriceData):
         description="Price per step/iteration",
     )
 
+    def effective_price(self) -> EffectivePrice | None:
+        """``price`` per step."""
+        return _rate(Decimal(self.price), UNIT_STEP)
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -495,6 +719,10 @@ class DataPriceData(BasePriceData):
         description="Price per one unit of the specified type",
     )
 
+    def effective_price(self) -> EffectivePrice | None:
+        """``price`` in the dimension's normalized unit."""
+        return _per_normalized_unit(self.type, Decimal(self.price))
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -556,6 +784,10 @@ class CountPriceData(BasePriceData):
         description="Price per one unit of the specified type",
     )
 
+    def effective_price(self) -> EffectivePrice | None:
+        """``price`` in the dimension's normalized unit."""
+        return _per_normalized_unit(self.type, Decimal(self.price))
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -602,6 +834,10 @@ class CharacterPriceData(BasePriceData):
         description="Price per one unit of the specified type",
     )
 
+    def effective_price(self) -> EffectivePrice | None:
+        """``price`` in the dimension's normalized unit."""
+        return _per_normalized_unit(self.type, Decimal(self.price))
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -670,6 +906,10 @@ class RevenueSharePriceData(BasePriceData):
         description="Percentage of customer charge that goes to the seller (0-100)",
     )
 
+    def effective_price(self) -> EffectivePrice | None:
+        """A share of the customer charge has no per-unit rate: unknown."""
+        return None
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -710,6 +950,14 @@ class ConstantPriceData(BasePriceData):
         description="Fixed price (positive for charge, negative for discount)",
     )
 
+    def effective_price(self) -> EffectivePrice | None:
+        """``price`` per request.
+
+        A ``0`` with a description is a bring-your-own-key price: see
+        ``_zero_rate``.
+        """
+        return _zero_rate(_rate(Decimal(self.price), UNIT_REQUEST), self.description)
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -783,6 +1031,15 @@ class AddPriceData(BasePriceData):
             self.price = _extract_nominal_price(self.prices[0])
         return self
 
+    def effective_price(self) -> EffectivePrice | None:
+        """The sum of the children; unknown if any child is unknown or the units differ."""
+        figures = [_child_effective_price(p) for p in self.prices]
+        known = [f for f in figures if f is not None]
+        if len(known) != len(figures) or len({f.unit for f in known}) != 1:
+            return None
+        source: Literal["rate", "upstream"] = "upstream" if any(f.source == "upstream" for f in known) else "rate"
+        return EffectivePrice(amount=sum((f.amount for f in known), Decimal(0)), unit=known[0].unit, source=source)
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -843,6 +1100,13 @@ class MultiplyPriceData(BasePriceData):
                     self.price = base_price
         return self
 
+    def effective_price(self) -> EffectivePrice | None:
+        """The base's figure times ``factor``."""
+        base = _child_effective_price(self.base)
+        if base is None:
+            return None
+        return base.model_copy(update={"amount": base.amount * Decimal(self.factor)})
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -897,6 +1161,10 @@ class MaxPriceData(BasePriceData):
             self.price = _extract_nominal_price(self.prices[0])
         return self
 
+    def effective_price(self) -> EffectivePrice | None:
+        """The largest child, as billed."""
+        return _largest(_child_effective_price(p) for p in self.prices)
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -955,6 +1223,10 @@ class MinPriceData(BasePriceData):
             self.price = _extract_nominal_price(self.prices[0])
         return self
 
+    def effective_price(self) -> EffectivePrice | None:
+        """The smallest child, as billed."""
+        return _smallest(_child_effective_price(p) for p in self.prices)
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -1012,6 +1284,14 @@ class FirstPriceData(BasePriceData):
             self.price = _extract_nominal_price(self.prices[0])
         return self
 
+    def effective_price(self) -> EffectivePrice | None:
+        """The first child with a known figure, mirroring the billing order."""
+        for price_data in self.prices:
+            figure = _child_effective_price(price_data)
+            if figure is not None:
+                return figure
+        return None
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -1246,6 +1526,10 @@ class ExprPriceData(BasePriceData):
         description="Arithmetic expression using usage metrics (e.g., 'input_tokens / 1000000 * 2.5')",
     )
 
+    def effective_price(self) -> EffectivePrice | None:
+        """An arbitrary expression has no per-unit rate: unknown."""
+        return None
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -1320,6 +1604,10 @@ class TieredPriceData(BasePriceData):
                 self.price = _extract_nominal_price(first_tier.price)
         return self
 
+    def effective_price(self) -> EffectivePrice | None:
+        """The largest tier's figure: the worst case a customer can pay."""
+        return _largest(_child_effective_price(tier.price) for tier in self.tiers)
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -1403,6 +1691,13 @@ class GraduatedPriceData(BasePriceData):
             self.price = self.tiers[0].unit_price
         return self
 
+    def effective_price(self) -> EffectivePrice | None:
+        """The largest ``unit_price`` (the worst case), per ``based_on``'s normalized unit.
+
+        Unknown when ``based_on`` has no unit (``customer_charge``, an expression).
+        """
+        return _per_normalized_unit(self.based_on, max(Decimal(tier.unit_price) for tier in self.tiers))
+
     def calculate_cost(
         self,
         usage: UsageData,
@@ -1526,6 +1821,10 @@ class ChannelPriceData(BasePriceData):
                 self.description = f"{lo} - {hi}"
         return self
 
+    def effective_price(self) -> EffectivePrice | None:
+        """The largest figure among all channels: the worst case a customer can pay."""
+        return _largest(_child_effective_price(p) for p in self.channels.values())
+
     def calculate_cost(
         self,
         usage: UsageData,

{unitysvc_core-0.2.27 → unitysvc_core-0.2.29/src/unitysvc_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: unitysvc-core
-Version: 0.2.27
+Version: 0.2.29
 Summary: Shared data models and validation helpers for UnitySVC packages
 Author-email: Bo Peng <bo.peng@unitysvc.com>
 Maintainer-email: Bo Peng <bo.peng@unitysvc.com>

{unitysvc_core-0.2.27 → unitysvc_core-0.2.29}/src/unitysvc_core.egg-info/SOURCES.txt

@@ -31,6 +31,7 @@ src/unitysvc_core/schema/promotion_v1.json
 src/unitysvc_core/schema/provider_v1.json
 src/unitysvc_core/schema/service_group_v1.json
 tests/test_access_interface_routing.py
+tests/test_effective_price.py
 tests/test_hidden_path_skip.py
 tests/test_offering_data.py
 tests/test_pricing.py

unitysvc_core-0.2.29/tests/test_effective_price.py

@@ -0,0 +1,311 @@
+"""Tests for ``effective_price()``: the per-unit comparison figure every pricing type defines."""
+
+import typing
+from decimal import Decimal
+from typing import Any
+
+import pytest
+
+from unitysvc_core.models.pricing import (
+    BasePriceData,
+    EffectivePrice,
+    Pricing,
+    upstream_price_from_description,
+    validate_pricing,
+)
+
+
+def ep(data: dict[str, Any]) -> EffectivePrice | None:
+    return validate_pricing(data).effective_price()
+
+
+def rate(amount: str, unit: str, source: str = "rate") -> EffectivePrice:
+    return EffectivePrice(amount=Decimal(amount), unit=unit, source=source)  # type: ignore[arg-type]
+
+
+TOKENS = {"type": "one_million_tokens", "input": "1", "output": "2"}  # blend 1.8
+CHEAP_TOKENS = {"type": "one_million_tokens", "price": "0.5"}
+PER_REQUEST = {"type": "constant", "price": "0.01"}
+HF_UPSTREAM = "billed by Hugging Face directly at $1.4 / $4.4 per 1M input/output tokens"
+BYOK = {"type": "constant", "price": "0", "description": HF_UPSTREAM}
+NO_AMOUNT = {"type": "constant", "price": "0", "description": "Bring your own key"}
+
+
+def test_every_pricing_type_defines_its_own_effective_price() -> None:
+    members = typing.get_args(typing.get_args(Pricing)[0])
+    assert len(members) == 18
+    for cls in members:
+        assert "effective_price" in vars(cls), f"{cls.__name__} does not define effective_price()"
+    assert BasePriceData().effective_price() is None
+
+
+class TestSimpleTypes:
+    def test_token_split_is_blended(self) -> None:
+        assert ep({"type": "one_million_tokens", "input": "1.4", "output": "4.4"}) == rate("3.8", "one_million_tokens")
+
+    def test_token_split_ignores_cached_input(self) -> None:
+        figure = ep({"type": "one_million_tokens", "input": "1", "cached_input": "0.1", "output": "2"})
+        assert figure == rate("1.8", "one_million_tokens")
+
+    def test_token_unified(self) -> None:
+        assert ep(CHEAP_TOKENS) == rate("0.5", "one_million_tokens")
+
+    @pytest.mark.parametrize(
+        ("kind", "price", "per_million"),
+        [("one_thousand_tokens", "0.002", "2"), ("one_token", "0.000003", "3")],
+    )
+    def test_token_scales_normalize_to_per_million(self, kind: str, price: str, per_million: str) -> None:
+        assert ep({"type": kind, "price": price}) == rate(per_million, "one_million_tokens")
+
+    def test_count_is_per_request(self) -> None:
+        assert ep({"type": "one_thousand", "price": "10"}) == rate("0.01", "request")
+        assert ep({"type": "one_million", "price": "2"}) == rate("0.000002", "request")
+
+    @pytest.mark.parametrize(
+        ("kind", "price", "per_hour"),
+        [
+            ("one_second", "0.001", "3.6"),
+            ("one_minute", "0.006", "0.36"),
+            ("one_hour", "2", "2"),
+            ("one_day", "24", "1"),
+        ],
+    )
+    def test_time_normalizes_to_per_hour(self, kind: str, price: str, per_hour: str) -> None:
+        assert ep({"type": kind, "price": price}) == rate(per_hour, "one_hour")
+
+    def test_data_normalizes_to_per_gigabyte(self) -> None:
+        assert ep({"type": "one_megabyte", "price": "0.001"}) == rate("1.024", "one_gigabyte")
+        assert ep({"type": "one_gigabyte", "price": "0.09"}) == rate("0.09", "one_gigabyte")
+
+    def test_characters_normalize_to_per_million(self) -> None:
+        assert ep({"type": "one_thousand_characters", "price": "0.015"}) == rate("15", "one_million_characters")
+
+    def test_image_and_step(self) -> None:
+        assert ep({"type": "image", "price": "0.04"}) == rate("0.04", "image")
+        assert ep({"type": "step", "price": "0.001"}) == rate("0.001", "step")
+
+    def test_constant_is_per_request(self) -> None:
+        assert ep(PER_REQUEST) == rate("0.01", "request")
+
+    def test_revenue_share_and_expr_are_unknown(self) -> None:
+        assert ep({"type": "revenue_share", "percentage": "70"}) is None
+        assert ep({"type": "expr", "expr": "input_tokens / 1000000 * 2.5"}) is None
+
+
+class TestByokConstant:
+    def test_zero_with_upstream_description(self) -> None:
+        assert ep(BYOK) == rate("3.8", "one_million_tokens", "upstream")
+
+    def test_zero_without_description_is_free(self) -> None:
+        assert ep({"type": "constant", "price": "0"}) == rate("0", "request")
+
+    def test_zero_with_unparseable_description_is_unknown(self) -> None:
+        assert ep(NO_AMOUNT) is None
+
+    def test_zero_zero_placeholder_is_unknown(self) -> None:
+        text = "billed directly at $0 / $0 per 1M input/output tokens"
+        placeholder = {"type": "constant", "price": "0", "description": text}
+        assert ep(placeholder) is None
+
+    def test_nonzero_ignores_description(self) -> None:
+        priced = {"type": "constant", "price": "0.02", "description": "$1 / $2 per 1M input/output tokens"}
+        assert ep(priced) == rate("0.02", "request")
+
+
+class TestByokZeroRateTokens:
+    """Generators also write BYOK as a zero token rate, e.g. Mistral models."""
+
+    MISTRAL = (
+        "Free ~ BYOK | usage is billed by Mistral AI directly at $1.5 / $7.5 / $0.15 per 1M input/output/cached tokens"
+    )
+
+    def test_zero_split_rate_reads_description(self) -> None:
+        byok = {"type": "one_million_tokens", "input": "0", "output": "0", "cached_input": "0"}
+        figure = ep({**byok, "description": self.MISTRAL})
+        assert figure == rate("6.3", "one_million_tokens", "upstream")
+
+    def test_zero_unified_rate_reads_description(self) -> None:
+        figure = ep({"type": "one_thousand_tokens", "price": "0", "description": HF_UPSTREAM})
+        assert figure == rate("3.8", "one_million_tokens", "upstream")
+
+    def test_zero_rate_without_description_is_free(self) -> None:
+        assert ep({"type": "one_million_tokens", "input": "0", "output": "0"}) == rate("0", "one_million_tokens")
+
+    def test_zero_rate_with_unparseable_description_is_unknown(self) -> None:
+        assert ep({"type": "one_million_tokens", "price": "0", "description": "Bring your own key"}) is None
+
+    def test_nonzero_rate_ignores_description(self) -> None:
+        priced = {**TOKENS, "description": self.MISTRAL}
+        assert ep(priced) == rate("1.8", "one_million_tokens")
+
+
+class TestUpstreamPriceFromDescription:
+    @pytest.mark.parametrize(
+        ("text", "expected"),
+        [
+            ("billed by Hugging Face directly at $1.4 / $4.4 per 1M input/output tokens", "3.8"),
+            ("$1.518/$4.554 / 1M input/output tokens", "3.9468"),
+            ("$4 / $20 / $0.2 per 1M input/output/cached tokens", "16.8"),
+            ("$3.45/$0.345/$17.25 / 1M in/cached/out tokens", "14.49"),
+            ("$0.50 / 1M tokens", "0.50"),
+            ("$0.001 / $0.002 per 1K input/output tokens", "1.8"),
+        ],
+    )
+    def test_known_shapes(self, text: str, expected: str) -> None:
+        assert upstream_price_from_description(text) == Decimal(expected)
+
+    @pytest.mark.parametrize(
+        "text",
+        [
+            None,
+            "",
+            "Bring your own OpenAI key",
+            "$1 / $2 per 1M input/output/cached tokens",  # three labels, two amounts
+            "$1 / $2 per 1M input/cached tokens",  # no output
+            "$0.01 per message",  # not tokens
+            "$1 / $2 per 1M tokens",  # two amounts, no labels
+        ],
+    )
+    def test_unknown_shapes_fail_closed(self, text: str | None) -> None:
+        assert upstream_price_from_description(text) is None
+
+
+class TestComposites:
+    def test_add_sums_one_unit(self) -> None:
+        figure = ep({"type": "add", "prices": [PER_REQUEST, {"type": "constant", "price": "0.005"}]})
+        assert figure == rate("0.015", "request")
+
+    def test_add_with_mixed_units_is_unknown(self) -> None:
+        assert ep({"type": "add", "prices": [TOKENS, PER_REQUEST]}) is None
+
+    def test_add_with_unknown_child_is_unknown(self) -> None:
+        assert ep({"type": "add", "prices": [PER_REQUEST, {"type": "revenue_share", "percentage": "10"}]}) is None
+
+    def test_multiply_scales_base(self) -> None:
+        assert ep({"type": "multiply", "factor": "0.5", "base": TOKENS}) == rate("0.9", "one_million_tokens")
+
+    def test_multiply_keeps_upstream_source(self) -> None:
+        assert ep({"type": "multiply", "factor": "2", "base": BYOK}) == rate("7.6", "one_million_tokens", "upstream")
+
+    def test_max_and_min(self) -> None:
+        prices = [TOKENS, CHEAP_TOKENS]
+        assert ep({"type": "max", "prices": prices}) == rate("1.8", "one_million_tokens")
+        assert ep({"type": "min", "prices": prices}) == rate("0.5", "one_million_tokens")
+
+    def test_mixed_units_compare_within_dominant_unit(self) -> None:
+        # Tokens outrank requests, which outrank every other unit.
+        prices = [{"type": "one_second", "price": "100"}, PER_REQUEST, CHEAP_TOKENS]
+        assert ep({"type": "max", "prices": prices}) == rate("0.5", "one_million_tokens")
+        prices = [{"type": "one_second", "price": "100"}, PER_REQUEST]
+        assert ep({"type": "max", "prices": prices}) == rate("0.01", "request")
+
+    def test_first_takes_first_known(self) -> None:
+        prices = [{"type": "revenue_share", "percentage": "10"}, PER_REQUEST, TOKENS]
+        assert ep({"type": "first", "prices": prices}) == rate("0.01", "request")
+
+    def test_invalid_child_is_skipped_not_raised(self) -> None:
+        assert ep({"type": "max", "prices": [{"type": "nonsense"}, PER_REQUEST]}) == rate("0.01", "request")
+
+
+class TestWorstCase:
+    def test_tiered_takes_largest_tier_not_first(self) -> None:
+        tiered = {
+            "type": "tiered",
+            "based_on": "request_count",
+            "tiers": [
+                {"up_to": 1000, "price": CHEAP_TOKENS},
+                {"up_to": None, "price": TOKENS},
+            ],
+        }
+        assert ep(tiered) == rate("1.8", "one_million_tokens")
+
+    @pytest.mark.parametrize(
+        ("based_on", "unit_prices", "expected"),
+        [
+            ("request_count", ["0.005", "0.01", "0.008"], rate("0.01", "request")),
+            ("input_tokens", ["0.000001", "0.000002"], rate("2", "one_million_tokens")),
+            ("one_thousand_tokens", ["0.003"], rate("3", "one_million_tokens")),
+            ("one_minute", ["0.01"], rate("0.6", "one_hour")),
+            ("bytes_out", ["0.000000001"], rate("1.073741824", "one_gigabyte")),
+            ("images_generated", ["0.04"], rate("0.04", "image")),
+            ("count", ["0.002"], rate("0.002", "request")),
+        ],
+    )
+    def test_graduated_takes_largest_unit_price(
+        self, based_on: str, unit_prices: list[str], expected: EffectivePrice
+    ) -> None:
+        tiers: list[dict[str, Any]] = [{"up_to": (i + 1) * 1000, "unit_price": p} for i, p in enumerate(unit_prices)]
+        tiers[-1]["up_to"] = None
+        assert ep({"type": "graduated", "based_on": based_on, "tiers": tiers}) == expected
+
+    @pytest.mark.parametrize("based_on", ["customer_charge", "input_tokens + output_tokens"])
+    def test_graduated_without_unit_is_unknown(self, based_on: str) -> None:
+        graduated = {"type": "graduated", "based_on": based_on, "tiers": [{"up_to": None, "unit_price": "0.1"}]}
+        assert ep(graduated) is None
+
+    def test_channel_takes_largest_not_default(self) -> None:
+        channel = {
+            "type": "channel",
+            "default": "byok",
+            "channels": {"byok": {"type": "constant", "price": "0"}, "plus": PER_REQUEST},
+        }
+        assert ep(channel) == rate("0.01", "request")
+
+    def test_channel_byok_upstream_beats_cheaper_managed(self) -> None:
+        channel = {"type": "channel", "default": "managed", "channels": {"managed": TOKENS, "byok": BYOK}}
+        assert ep(channel) == rate("3.8", "one_million_tokens", "upstream")
+
+    def test_channel_ignores_unknown_channels(self) -> None:
+        channel = {
+            "type": "channel",
+            "default": "managed",
+            "channels": {"managed": TOKENS, "byok": NO_AMOUNT},
+        }
+        assert ep(channel) == rate("1.8", "one_million_tokens")
+
+    def test_all_unknown_is_unknown(self) -> None:
+        channel = {
+            "type": "channel",
+            "default": "byok",
+            "channels": {"byok": NO_AMOUNT},
+        }
+        assert ep(channel) is None
+
+    def test_nested_composites_resolve_recursively(self) -> None:
+        nested = {
+            "type": "channel",
+            "default": "managed",
+            "channels": {
+                "managed": {
+                    "type": "tiered",
+                    "based_on": "request_count",
+                    "tiers": [
+                        {"up_to": 100, "price": {"type": "multiply", "factor": "2", "base": TOKENS}},
+                        {"up_to": None, "price": CHEAP_TOKENS},
+                    ],
+                },
+                "byok": {"type": "constant", "price": "0"},
+            },
+        }
+        assert ep(nested) == rate("3.6", "one_million_tokens")
+
+
+def test_does_not_read_the_stored_nominal() -> None:
+    # The auto-filled composite ``price`` (first tier) is not the effective price.
+    tiered = validate_pricing(
+        {
+            "type": "tiered",
+            "based_on": "request_count",
+            "tiers": [{"up_to": 10, "price": CHEAP_TOKENS}, {"up_to": None, "price": TOKENS}],
+        }
+    )
+    assert tiered.price == "0.5"
+    assert tiered.effective_price() == rate("1.8", "one_million_tokens")
+
+
+def test_effective_price_serializes_compactly() -> None:
+    assert rate("3.8", "one_million_tokens", "upstream").model_dump(mode="json") == {
+        "amount": "3.8",
+        "unit": "one_million_tokens",
+        "source": "upstream",
+    }