metergraph-core 0.2.61__tar.gz → 0.3.0__tar.gz

{metergraph_core-0.2.61/src/metergraph_core.egg-info → metergraph_core-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph-core
-Version: 0.2.61
+Version: 0.3.0
 Summary: Reusable MeterGraph catalog and deterministic billing engine
 License-Expression: Apache-2.0
 Requires-Python: >=3.10
@@ -92,6 +92,58 @@ prefix, the latter only onto an `aws-bedrock` alias. Geographic prefixes such as
 `LoadedCatalog.pricing_verified_at` records when the bundled catalog was last
 checked against its linked provider sources.
 
+### Direct lookup and usage cost
+
+`lookup_price` returns the price a call is billed at, and `calculate_cost`
+costs a call's usage at that price:
+
+```python
+from metergraph_core import ModelUsage
+
+found = catalog.lookup_price(
+    model="gpt-5.4-mini",
+    provider="openai",
+    at=datetime(2026, 8, 17, tzinfo=timezone.utc),
+)
+print(found.status, found.model_id, found.price.id, found.price.currency)
+
+result = catalog.calculate_cost(
+    model="gpt-5.4-mini",
+    provider="openai",
+    at=datetime(2026, 8, 17, tzinfo=timezone.utc),
+    usage=ModelUsage(input_tokens=1000, output_tokens=200, cache_read_tokens=500),
+)
+print(result.status, result.model_id, result.cost, result.currency)
+print(result.components.input, result.components.cache_read)
+```
+
+Both resolve exactly as `resolve_price` and `price` do, including
+effective-date windows and the Bedrock fallback, and cost through the same
+arithmetic. `model_id` is the resolved catalog ID, not the alias passed in, and
+`price` is the applied catalog row. An explicit `channel` is authoritative;
+without one, `provider` supplies its direct channel, and with neither the
+result is `unpriced` with `missing_dimensions=("channel",)`.
+
+Every `Price` states its `currency`, and `CostResult.currency` is the currency
+of the applied price. The bundled catalog is USD. `cost` and
+`components.input`, `output`, `cache_read`, `cache_write` and `request` are in
+that currency; the older `cost_usd` and `*_usd` names return the same values.
+
+A `ModelUsage` count left `None` is unknown, not zero. A missing input or
+output count keeps the subtotal that is known, marks the result `partial`, and
+lists `input_tokens` or `output_tokens` in `missing_dimensions`.
+
+`region` selects a regional price and overrides the `region` passed to
+`load_catalog`. When neither names a region:
+
+- if every region bills the model the same, the result is `priced`;
+- if a global price applies but some region bills differently, the global
+  price is returned as `partial` with `missing_dimensions=("region",)`;
+- if only specific regions price the model, the result is `unpriced` with
+  `missing_dimensions=("region",)`.
+
+A region the model is not sold in is `unpriced` with nothing missing.
+
 ## Model registry
 
 ```python
@@ -165,7 +217,9 @@ from metergraph_core import (
     LoadedCatalog,
     ModelRegistry,
     ModelRoute,
+    ModelUsage,
     Price,
+    PriceResult,
     ResolvedPrice,
     load_catalog,
     load_model_registry,

{metergraph_core-0.2.61 → metergraph_core-0.3.0}/README.md

@@ -80,6 +80,58 @@ prefix, the latter only onto an `aws-bedrock` alias. Geographic prefixes such as
 `LoadedCatalog.pricing_verified_at` records when the bundled catalog was last
 checked against its linked provider sources.
 
+### Direct lookup and usage cost
+
+`lookup_price` returns the price a call is billed at, and `calculate_cost`
+costs a call's usage at that price:
+
+```python
+from metergraph_core import ModelUsage
+
+found = catalog.lookup_price(
+    model="gpt-5.4-mini",
+    provider="openai",
+    at=datetime(2026, 8, 17, tzinfo=timezone.utc),
+)
+print(found.status, found.model_id, found.price.id, found.price.currency)
+
+result = catalog.calculate_cost(
+    model="gpt-5.4-mini",
+    provider="openai",
+    at=datetime(2026, 8, 17, tzinfo=timezone.utc),
+    usage=ModelUsage(input_tokens=1000, output_tokens=200, cache_read_tokens=500),
+)
+print(result.status, result.model_id, result.cost, result.currency)
+print(result.components.input, result.components.cache_read)
+```
+
+Both resolve exactly as `resolve_price` and `price` do, including
+effective-date windows and the Bedrock fallback, and cost through the same
+arithmetic. `model_id` is the resolved catalog ID, not the alias passed in, and
+`price` is the applied catalog row. An explicit `channel` is authoritative;
+without one, `provider` supplies its direct channel, and with neither the
+result is `unpriced` with `missing_dimensions=("channel",)`.
+
+Every `Price` states its `currency`, and `CostResult.currency` is the currency
+of the applied price. The bundled catalog is USD. `cost` and
+`components.input`, `output`, `cache_read`, `cache_write` and `request` are in
+that currency; the older `cost_usd` and `*_usd` names return the same values.
+
+A `ModelUsage` count left `None` is unknown, not zero. A missing input or
+output count keeps the subtotal that is known, marks the result `partial`, and
+lists `input_tokens` or `output_tokens` in `missing_dimensions`.
+
+`region` selects a regional price and overrides the `region` passed to
+`load_catalog`. When neither names a region:
+
+- if every region bills the model the same, the result is `priced`;
+- if a global price applies but some region bills differently, the global
+  price is returned as `partial` with `missing_dimensions=("region",)`;
+- if only specific regions price the model, the result is `unpriced` with
+  `missing_dimensions=("region",)`.
+
+A region the model is not sold in is `unpriced` with nothing missing.
+
 ## Model registry
 
 ```python
@@ -153,7 +205,9 @@ from metergraph_core import (
     LoadedCatalog,
     ModelRegistry,
     ModelRoute,
+    ModelUsage,
     Price,
+    PriceResult,
     ResolvedPrice,
     load_catalog,
     load_model_registry,

{metergraph_core-0.2.61 → metergraph_core-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metergraph-core"
-version = "0.2.61"
+version = "0.3.0"
 description = "Reusable MeterGraph catalog and deterministic billing engine"
 readme = "README.md"
 license = "Apache-2.0"

{metergraph_core-0.2.61 → metergraph_core-0.3.0}/src/metergraph_core/__init__.py

@@ -5,7 +5,9 @@ from .catalog import (
     Alias,
     CatalogSnapshot,
     CostResult,
+    ModelUsage,
     Price,
+    PriceResult,
     ResolvedPrice,
     counts_cache_read_in_input,
     direct_channel_for_provider,
@@ -60,10 +62,12 @@ __all__ = [
     "ModelRegistry",
     "ModelRegistryError",
     "ModelRoute",
+    "ModelUsage",
     "OfferGroup",
     "ReleaseDate",
     "GatewayBillingEvidence",
     "Price",
+    "PriceResult",
     "ResolvedPrice",
     "RetrievalCatalog",
     "RetrievalCostResult",

{metergraph_core-0.2.61 → metergraph_core-0.3.0}/src/metergraph_core/catalog.py

@@ -212,6 +212,9 @@ class Price:
     # A fixed fee charged once per call on top of tokens, in USD per 1,000
     # calls: a gateway billing a model's built-in search per request.
     request_fee_per_1k_usd: Decimal | None = None
+    # The currency every rate on this row is stated in. The `_usd` names on
+    # rates and results predate it and are kept for existing callers.
+    currency: str = "USD"
 
 
 @dataclass(frozen=True, slots=True)
@@ -220,7 +223,9 @@ class CostComponents:
     ``cost_usd`` exactly: each is quantized and the rounding residue lands in
     the input part, so a consumer that stores them can rebuild the total
     without a second rounding. ``request_usd`` is a per-call fee, zero on
-    every row that has none."""
+    every row that has none. Each part is in the applied price's currency;
+    ``input``, ``output``, ``cache_read``, ``cache_write`` and ``request``
+    name the same values without implying USD."""
 
     input_usd: Decimal
     output_usd: Decimal
@@ -228,6 +233,26 @@ class CostComponents:
     cache_write_usd: Decimal
     request_usd: Decimal = Decimal("0")
 
+    @property
+    def input(self) -> Decimal:
+        return self.input_usd
+
+    @property
+    def output(self) -> Decimal:
+        return self.output_usd
+
+    @property
+    def cache_read(self) -> Decimal:
+        return self.cache_read_usd
+
+    @property
+    def cache_write(self) -> Decimal:
+        return self.cache_write_usd
+
+    @property
+    def request(self) -> Decimal:
+        return self.request_usd
+
 
 @dataclass(frozen=True, slots=True)
 class CostResult:
@@ -241,6 +266,53 @@ class CostResult:
     # The catalog's publisher for the priced model, for billing rules that
     # apply per publisher rather than per channel.
     publisher: str | None = None
+    # The applied price, its currency, and the time it was resolved at.
+    price: Price | None = None
+    currency: str | None = None
+    effective_at: datetime | None = None
+    # Inputs the caller did not supply that the figure depends on: "region",
+    # "channel", "input_tokens", "output_tokens".
+    missing_dimensions: tuple[str, ...] = ()
+
+    @property
+    def model_id(self) -> str | None:
+        """The resolved catalog model id; the same value as ``canonical_model``."""
+        return self.canonical_model
+
+    @property
+    def cost(self) -> Decimal | None:
+        """The total in ``currency``; the same value as ``cost_usd``."""
+        return self.cost_usd
+
+
+@dataclass(frozen=True, slots=True)
+class ModelUsage:
+    """Token usage for one model call. A count left ``None`` is unknown, not
+    zero: input and output turn the result partial, and cached counts bill as
+    nothing cached, as in :meth:`CatalogSnapshot.cost`."""
+
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    cache_read_tokens: int | None = None
+    cache_write_tokens: int | None = None
+    cache_write_5m_tokens: int | None = None
+    cache_write_1h_tokens: int | None = None
+    batch: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class PriceResult:
+    """The price a model call would be billed at.
+
+    ``status`` is ``priced``, ``partial`` (a price applies but depends on a
+    dimension listed in ``missing_dimensions``), or ``unpriced``. ``model_id``
+    is the resolved catalog id, not the alias the caller sent."""
+
+    status: str
+    model_id: str | None
+    price: Price | None
+    effective_at: datetime
+    missing_dimensions: tuple[str, ...] = ()
 
 
 @dataclass(frozen=True, slots=True)
@@ -252,6 +324,26 @@ class ResolvedPrice:
     rules: Mapping[str, Any]
 
 
+def _billed_terms(resolved: ResolvedPrice) -> tuple[Any, ...]:
+    """What a call is billed by: two resolutions with equal terms cost the
+    same for any usage, whichever region or source row they came from."""
+    price = resolved.price
+    return (
+        resolved.canonical_model,
+        price.pricing_channel,
+        price.currency,
+        price.input_per_mtok,
+        price.output_per_mtok,
+        price.cache_read_per_mtok,
+        price.cache_write_5m_per_mtok,
+        price.cache_write_1h_per_mtok,
+        price.batch_input_per_mtok,
+        price.batch_output_per_mtok,
+        price.request_fee_per_1k_usd,
+        resolved.rules,
+    )
+
+
 def _decimal(value: Any) -> Decimal | None:
     if value is None:
         return None
@@ -351,9 +443,9 @@ def _price_tokens(
     batch: bool,
 ) -> tuple[Decimal, list[str], CostComponents]:
     """Cost a token usage against one already-selected price and its merged
-    rules. Shared by ``cost`` (provider+model entry) and ``price_deployment``
-    (model+channel entry) so both compute identically. Returns the total, the
-    reasons it is partial, and the split by driver."""
+    rules. Every token entry point reaches it through ``_cost_result`` so all
+    compute identically. Returns the total, the reasons it is partial, and the
+    split by driver."""
     reasons: list[str] = []
     input_count = _tokens(input_tokens)
     output_count = _tokens(output_tokens)
@@ -489,6 +581,48 @@ def _price_tokens(
     return cost, reasons, CostComponents(*parts)
 
 
+def _cost_result(
+    resolved: ResolvedPrice,
+    *,
+    at: datetime,
+    usage: ModelUsage,
+    missing: tuple[str, ...] = (),
+) -> CostResult:
+    """Cost ``usage`` against a resolved price. Every token entry point builds
+    its result here, so all of them compute and report identically."""
+    cost, reasons, components = _price_tokens(
+        resolved.price,
+        resolved.rules,
+        at=at,
+        input_tokens=usage.input_tokens,
+        output_tokens=usage.output_tokens,
+        cache_read_tokens=usage.cache_read_tokens,
+        cache_write_tokens=usage.cache_write_tokens,
+        cache_write_5m_tokens=usage.cache_write_5m_tokens,
+        cache_write_1h_tokens=usage.cache_write_1h_tokens,
+        batch=usage.batch,
+    )
+    reasons = [f"missing_{dimension}" for dimension in missing] + reasons
+    missing += tuple(
+        dimension
+        for dimension in ("input_tokens", "output_tokens")
+        if f"missing_{dimension}" in reasons
+    )
+    return CostResult(
+        resolved.canonical_model,
+        resolved.price.id,
+        cost,
+        "partial" if reasons else "priced",
+        tuple(dict.fromkeys(reasons)),
+        components=components,
+        publisher=resolved.price.publisher,
+        price=resolved.price,
+        currency=resolved.price.currency,
+        effective_at=at,
+        missing_dimensions=missing,
+    )
+
+
 class CatalogSnapshot:
     def __init__(
         self,
@@ -532,8 +666,20 @@ class CatalogSnapshot:
             )
         for candidates in self._prices.values():
             candidates.sort(key=lambda price: price.effective_from, reverse=True)
-
-    def _alias_for(self, candidates: tuple[Alias, ...], at: datetime) -> Alias | None:
+        # Every named region a price or pin exists for: the regions an omitted
+        # query region could have meant.
+        self._regions = tuple(sorted(
+            {price.region.lower() for price in prices}.union(
+                region
+                for candidates in self._aliases.values()
+                for alias in candidates
+                for region in alias.price_region
+            ) - {"*", _GLOBAL_REGION}
+        ))
+
+    def _alias_for(
+        self, candidates: tuple[Alias, ...], at: datetime, region: str | None = None
+    ) -> Alias | None:
         when = _coerce_datetime(at)
         effective = [
             alias
@@ -542,29 +688,31 @@ class CatalogSnapshot:
             and (alias.effective_to is None or when < alias.effective_to)
         ]
         # Regional pins constrain availability; global pins match everywhere.
-        for region in dict.fromkeys((self._region, _GLOBAL_REGION)):
+        for pinned in dict.fromkeys((region or self._region, _GLOBAL_REGION)):
             for alias in effective:
-                if region in alias.price_region:
+                if pinned in alias.price_region:
                     return alias
         for alias in effective:
             if not alias.price_region:
                 return alias
         return None
 
-    def _price_regions(self, alias: Alias) -> tuple[str, ...]:
+    def _price_regions(self, alias: Alias, region: str) -> tuple[str, ...]:
         if not alias.price_region:
-            return tuple(dict.fromkeys((self._region, "*", _GLOBAL_REGION)))
-        for region in (self._region, _GLOBAL_REGION):
-            if region in alias.price_region:
-                return (region,)
+            return tuple(dict.fromkeys((region, "*", _GLOBAL_REGION)))
+        for candidate in (region, _GLOBAL_REGION):
+            if candidate in alias.price_region:
+                return (candidate,)
         return ()
 
-    def _price_for(self, alias: Alias, at: datetime) -> Price | None:
+    def _price_for(
+        self, alias: Alias, at: datetime, region: str | None = None
+    ) -> Price | None:
         at = at if at.tzinfo else at.replace(tzinfo=timezone.utc)
         candidates = self._prices.get((alias.model_id, alias.pricing_channel), [])
-        for region in self._price_regions(alias):
+        for scope in self._price_regions(alias, region or self._region):
             for price in candidates:
-                if price.region.lower() != region:
+                if price.region.lower() != scope:
                     continue
                 if price.effective_from <= at and (
                     price.effective_to is None or at < price.effective_to
@@ -611,25 +759,31 @@ class CatalogSnapshot:
         deployment channel before making a provider call. It never falls back
         to pricing from a different channel.
         """
+        return self._resolve(model=model, channel=channel, at=at)
 
+    def _resolve(
+        self, *, model: Any, channel: Any, at: Any, region: str | None = None
+    ) -> ResolvedPrice | None:
+        """``resolve_price`` in ``region``, or the snapshot's region when
+        ``None``."""
         model_key = str(model or "").strip().lower()
         channel_key = str(channel or "").strip().lower()
         when = _coerce_datetime(at)
         candidates = self._deployment_aliases.get((model_key, channel_key), ())
-        alias = self._alias_for(candidates, when)
+        alias = self._alias_for(candidates, when, region)
         if alias is None and channel_key in _BEDROCK_CHANNELS:
             for candidate, dropped_global in _bedrock_fallback_ids(model_key):
                 if dropped_global and channel_key != _BEDROCK_CHANNEL:
                     continue
                 candidates = self._deployment_aliases.get((candidate, channel_key), ())
-                alias = self._alias_for(candidates, when)
+                alias = self._alias_for(candidates, when, region)
                 if alias is not None and dropped_global and _crosses_price_region(alias):
                     alias = None
                 if alias is not None:
                     break
         if alias is None:
             return None
-        price = self._price_for(alias, when)
+        price = self._price_for(alias, when, region)
         if price is None:
             return None
         return ResolvedPrice(
@@ -638,6 +792,41 @@ class CatalogSnapshot:
             rules=MappingProxyType({**price.rules, **alias.rules}),
         )
 
+    def _lookup(
+        self, *, model: Any, channel: Any, provider: Any, at: Any, region: Any
+    ) -> tuple[ResolvedPrice | None, tuple[str, ...]]:
+        """Resolve a model call for the public lookup and cost entry points,
+        with the dimensions the answer depends on but the caller left out.
+
+        An explicit channel wins; otherwise a provider names its direct
+        channel. An explicit region resolves that region. An omitted one uses
+        the snapshot's region, and when that is the default ``global`` it is
+        checked against every named region: a global price that some region
+        bills differently is returned with ``region`` missing, and a model only
+        some region prices is unpriced with ``region`` missing.
+        """
+        if channel is None or not str(channel).strip():
+            channel = direct_channel_for_provider(provider)
+            if channel is None:
+                return None, ("channel",)
+        stated = str(region or "").strip().lower() or None
+        resolved = self._resolve(model=model, channel=channel, at=at, region=stated)
+        if stated is not None or self._region != _GLOBAL_REGION:
+            return resolved, ()
+        regional = [
+            found
+            for found in (
+                self._resolve(model=model, channel=channel, at=at, region=name)
+                for name in self._regions
+            )
+            if found is not None
+        ]
+        if resolved is None:
+            return None, ("region",) if regional else ()
+        if any(_billed_terms(found) != _billed_terms(resolved) for found in regional):
+            return resolved, ("region",)
+        return resolved, ()
+
     def cost(
         self,
         *,
@@ -688,27 +877,18 @@ class CatalogSnapshot:
                 "unpriced",
                 ("no_effective_price",),
             )
-
-        cost, reasons, components = _price_tokens(
-            price,
-            {**price.rules, **alias.rules},
+        return _cost_result(
+            ResolvedPrice(alias.canonical_id, price, {**price.rules, **alias.rules}),
             at=when,
-            input_tokens=input_tokens,
-            output_tokens=output_tokens,
-            cache_read_tokens=cache_read_tokens,
-            cache_write_tokens=cache_write_tokens,
-            cache_write_5m_tokens=cache_write_5m_tokens,
-            cache_write_1h_tokens=cache_write_1h_tokens,
-            batch=batch,
-        )
-        return CostResult(
-            alias.canonical_id,
-            price.id,
-            cost,
-            "partial" if reasons else "priced",
-            tuple(dict.fromkeys(reasons)),
-            components=components,
-            publisher=price.publisher,
+            usage=ModelUsage(
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                cache_read_tokens=cache_read_tokens,
+                cache_write_tokens=cache_write_tokens,
+                cache_write_5m_tokens=cache_write_5m_tokens,
+                cache_write_1h_tokens=cache_write_1h_tokens,
+                batch=batch,
+            ),
         )
 
     def price_deployment(
@@ -739,24 +919,16 @@ class CatalogSnapshot:
         resolved = self.resolve_price(model=model, channel=channel, at=when)
         if resolved is None:
             return CostResult(None, None, None, "unpriced", ("unknown_deployment",))
-        cost, reasons, components = _price_tokens(
-            resolved.price,
-            resolved.rules,
+        return _cost_result(
+            resolved,
             at=when,
-            input_tokens=input_tokens,
-            output_tokens=output_tokens,
-            cache_read_tokens=cache_read_tokens,
-            cache_write_tokens=cache_write_tokens,
-            cache_write_5m_tokens=cache_write_5m_tokens,
-            cache_write_1h_tokens=cache_write_1h_tokens,
-            batch=batch,
-        )
-        return CostResult(
-            resolved.canonical_model,
-            resolved.price.id,
-            cost,
-            "partial" if reasons else "priced",
-            tuple(dict.fromkeys(reasons)),
-            components=components,
-            publisher=resolved.price.publisher,
+            usage=ModelUsage(
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                cache_read_tokens=cache_read_tokens,
+                cache_write_tokens=cache_write_tokens,
+                cache_write_5m_tokens=cache_write_5m_tokens,
+                cache_write_1h_tokens=cache_write_1h_tokens,
+                batch=batch,
+            ),
         )

{metergraph_core-0.2.61 → metergraph_core-0.3.0}/src/metergraph_core/data/models.yaml

@@ -1,4 +1,4 @@
-version: '2026-10-16'
+version: '2026-10-19'
 models:
 - canonical_id: openai/gpt-5.6-sol
   display_name: GPT-5.6 Sol
@@ -447,6 +447,30 @@ models:
     pricing_channel: vercel-ai-gateway
     execution_profiles:
     - default
+- canonical_id: deepseek/deepseek-v4.1-flash-1017
+  display_name: DeepSeek V4.1 Flash 1017
+  publisher: deepseek
+  released: '2026-10-17'  # https://vercel.com/ai-gateway/models/deepseek-v4.1-flash-1017
+  routes:
+  - key: default:deepseek/deepseek-v4.1-flash-1017
+    id: deepseek/deepseek-v4.1-flash-1017
+    provider: vercel
+    model_id: deepseek/deepseek-v4.1-flash-1017
+    pricing_channel: vercel-ai-gateway
+    execution_profiles:
+    - default
+- canonical_id: deepseek/deepseek-v4.1-flash-1017-fast
+  display_name: DeepSeek V4.1 Flash 1017 Fast
+  publisher: deepseek
+  released: '2026-10-17'  # https://vercel.com/ai-gateway/models/deepseek-v4.1-flash-1017-fast
+  routes:
+  - key: default:deepseek/deepseek-v4.1-flash-1017-fast
+    id: deepseek/deepseek-v4.1-flash-1017-fast
+    provider: vercel
+    model_id: deepseek/deepseek-v4.1-flash-1017-fast
+    pricing_channel: vercel-ai-gateway
+    execution_profiles:
+    - default
 - canonical_id: alibaba/qwen3.8-flash
   display_name: Qwen 3.8 Flash
   publisher: alibaba
@@ -471,6 +495,18 @@ models:
     pricing_channel: vercel-ai-gateway
     execution_profiles:
     - default
+- canonical_id: inception/mercury-3
+  display_name: Mercury 3
+  publisher: inception
+  released: '2026-10-19'  # https://www.inceptionlabs.ai/blog/introducing-mercury-3
+  routes:
+  - key: default:inception/mercury-3
+    id: inception/mercury-3
+    provider: vercel
+    model_id: inception/mercury-3
+    pricing_channel: vercel-ai-gateway
+    execution_profiles:
+    - default
 - canonical_id: openai/gpt-5.4-mini
   display_name: GPT-5.4 Mini
   publisher: openai
@@ -882,6 +918,9 @@ execution_profiles:
   - default:meta/muse-wonder-1.0
   - default:meta/muse-spark-open
   - default:nvidia/nemotron-3.5-super-vl
+  - default:deepseek/deepseek-v4.1-flash-1017
+  - default:deepseek/deepseek-v4.1-flash-1017-fast
+  - default:inception/mercury-3
   - default:openai:gpt-6.1-sol
   - default:anthropic:claude-sonnet-5-5
   - default:anthropic:claude-haiku-5-5
@@ -948,6 +987,9 @@ offer_groups:
   - default:meta/muse-wonder-1.0
   - default:meta/muse-spark-open
   - default:nvidia/nemotron-3.5-super-vl
+  - default:deepseek/deepseek-v4.1-flash-1017
+  - default:deepseek/deepseek-v4.1-flash-1017-fast
+  - default:inception/mercury-3
 - id: fireworks
   credential: FIREWORKS_API_KEY
   routes:

{metergraph_core-0.2.61 → metergraph_core-0.3.0}/src/metergraph_core/data/prices.yaml

@@ -6,9 +6,9 @@
 #
 # Community updates welcome: add an alias or price entry with its provider
 # source_url and open a PR. CI validates structure and date overlaps.
-version: "2026-10-16"
+version: "2026-10-19"
 currency: USD
-pricing_verified_at: "2026-10-16"
+pricing_verified_at: "2026-10-19"
 models:
   - canonical_id: openai/gpt-6-sol
     publisher: openai
@@ -2709,12 +2709,28 @@ models:
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2026-10-02"
+        effective_to: "2026-10-19"
         input_per_mtok: 0.30
         output_per_mtok: 1.20
         cache_read_per_mtok: 0.007
         rules:
           varies_by_provider: true
         source_url: https://ai-gateway.vercel.sh/v1/models
+      - channel: vercel-ai-gateway
+        region: global
+        effective_from: "2026-10-19"
+        # Store Vercel's 2x peak rate; this rule restores its off-peak rate.
+        input_per_mtok: 0.15
+        output_per_mtok: 0.60
+        cache_read_per_mtok: 0.003
+        rules:
+          input_includes_cache_read: true
+          varies_by_provider: true
+          off_peak_discount:
+            multiplier: 0.5
+            peak_hours_utc: [[1, 4], [6, 10]]
+            peak_weekdays_only: true
+        source_url: https://ai-gateway.vercel.sh/v1/models
       # Displayed serverless billing rates take precedence over conflicting prose.
       - channel: fireworks-api
         region: global
@@ -4602,6 +4618,119 @@ models:
         input_per_mtok: 0.00
         output_per_mtok: 0.00
         source_url: https://vercel.com/ai-gateway/models/nemotron-3.5-lightning-free
+
+  - canonical_id: deepseek/deepseek-v4.1-flash-1017
+    publisher: deepseek
+    aliases:
+      - provider: deepseek
+        alias: deepseek/deepseek-v4.1-flash-1017
+        channel: vercel-ai-gateway
+        rules: {input_includes_cache_read: true}
+    prices:
+      - channel: vercel-ai-gateway
+        region: global
+        effective_from: "2026-10-17"
+        # Store Vercel's 2x peak rate; this rule restores its off-peak rate.
+        input_per_mtok: 0.15
+        output_per_mtok: 0.60
+        cache_read_per_mtok: 0.003
+        rules:
+          input_includes_cache_read: true
+          varies_by_provider: true
+          off_peak_discount:
+            multiplier: 0.5
+            peak_hours_utc: [[1, 4], [6, 10]]
+            peak_weekdays_only: true
+        source_url: https://vercel.com/ai-gateway/models/deepseek-v4.1-flash-1017
+
+  - canonical_id: deepseek/deepseek-v4.1-flash-1017-fast
+    publisher: deepseek
+    aliases:
+      - provider: deepseek
+        alias: deepseek/deepseek-v4.1-flash-1017-fast
+        channel: vercel-ai-gateway
+        rules: {input_includes_cache_read: true}
+    prices:
+      - channel: vercel-ai-gateway
+        region: global
+        effective_from: "2026-10-17"
+        # The source lists a fixed Baseten rate without peak pricing.
+        input_per_mtok: 0.60
+        output_per_mtok: 2.40
+        cache_read_per_mtok: 0.014
+        source_url: https://vercel.com/ai-gateway/models/deepseek-v4.1-flash-1017-fast
+
+  # Price observed traffic, but exclude this route from default execution while
+  # Vercel permits retention and prompt training.
+  - canonical_id: elorian/glimpse
+    publisher: elorian
+    aliases:
+      - provider: elorian
+        alias: elorian/glimpse
+        channel: vercel-ai-gateway
+        rules: {input_includes_cache_read: true}
+    prices:
+      - channel: vercel-ai-gateway
+        region: global
+        effective_from: "2026-10-16"
+        input_per_mtok: 0.60
+        output_per_mtok: 3.00
+        cache_read_per_mtok: 0.06
+        source_url: https://vercel.com/ai-gateway/models/glimpse
+
+  - canonical_id: inception/mercury-3
+    publisher: inception
+    aliases:
+      - provider: inception
+        alias: inception/mercury-3
+        channel: vercel-ai-gateway
+        rules: {input_includes_cache_read: true}
+    prices:
+      # No end date is published for this 50% launch price. Close the row when
+      # Inception or Vercel announces the standard rate.
+      - channel: vercel-ai-gateway
+        region: global
+        effective_from: "2026-10-19"
+        input_per_mtok: 0.10
+        output_per_mtok: 0.35
+        cache_read_per_mtok: 0.01
+        source_url: https://www.inceptionlabs.ai/blog/introducing-mercury-3
+
+  # Price observed traffic, but exclude this route from default execution while
+  # Vercel permits retention and prompt training.
+  - canonical_id: minimax/minimax-m3.1-flash
+    publisher: minimax
+    aliases:
+      - {provider: minimax, alias: minimax-m3.1-flash, channel: minimax-api}
+      - {provider: litellm, alias: minimax-m3.1-flash, channel: minimax-api}
+      - {provider: unknown, alias: minimax-m3.1-flash, channel: minimax-api}
+      - provider: minimax
+        alias: minimax/minimax-m3.1-flash
+        channel: vercel-ai-gateway
+        rules: {input_includes_cache_read: true}
+    prices:
+      - channel: minimax-api
+        region: global
+        effective_from: "2026-10-19"
+        input_per_mtok: 0.15
+        output_per_mtok: 0.60
+        cache_read_per_mtok: 0.015
+        source_url: https://www.minimax.io/blog/minimax-m31f
+      - channel: vercel-ai-gateway
+        region: global
+        effective_from: "2026-10-19"
+        effective_to: "2026-10-23"
+        input_per_mtok: 0.00
+        output_per_mtok: 0.00
+        cache_read_per_mtok: 0.00
+        source_url: https://vercel.com/changelog/minimax-m3-1-flash-now-available-on-ai-gateway-for-free
+      - channel: vercel-ai-gateway
+        region: global
+        effective_from: "2026-10-23"
+        input_per_mtok: 0.15
+        output_per_mtok: 0.60
+        cache_read_per_mtok: 0.015
+        source_url: https://vercel.com/changelog/minimax-m3-1-flash-now-available-on-ai-gateway-for-free
 retrieval:
   - channel: anthropic-api
     operation: web_search

{metergraph_core-0.2.61 → metergraph_core-0.3.0}/src/metergraph_core/loader.py

@@ -13,7 +13,11 @@ from .catalog import (
     Alias,
     CatalogSnapshot,
     CostResult,
+    ModelUsage,
     Price,
+    PriceResult,
+    _coerce_datetime,
+    _cost_result,
     _decimal,
     _effective_windows_overlap,
     normalize_provider,
@@ -123,6 +127,65 @@ class LoadedCatalog:
             batch=batch,
         )
 
+    def lookup_price(
+        self,
+        *,
+        model: Any,
+        at: Any,
+        channel: Any = None,
+        provider: Any = None,
+        region: Any = None,
+    ) -> PriceResult:
+        """The price a call to ``model`` at ``at`` is billed at.
+
+        ``channel`` is authoritative; without one, ``provider`` supplies its
+        direct channel. ``region`` overrides the region the catalog was
+        loaded with. A result that depends on a dimension the caller left out
+        lists it in ``missing_dimensions``."""
+        when = _coerce_datetime(at)
+        resolved, missing = self.snapshot._lookup(
+            model=model, channel=channel, provider=provider, at=when, region=region
+        )
+        if resolved is None:
+            return PriceResult("unpriced", None, None, when, missing)
+        return PriceResult(
+            "partial" if missing else "priced",
+            resolved.canonical_model,
+            resolved.price,
+            when,
+            missing,
+        )
+
+    def calculate_cost(
+        self,
+        *,
+        model: Any,
+        usage: ModelUsage,
+        at: Any,
+        channel: Any = None,
+        provider: Any = None,
+        region: Any = None,
+    ) -> CostResult:
+        """Cost ``usage`` at the price :meth:`lookup_price` resolves. A
+        missing dimension, from the lookup or the usage, turns the result
+        ``partial`` and keeps the subtotal that is known."""
+        when = _coerce_datetime(at)
+        resolved, missing = self.snapshot._lookup(
+            model=model, channel=channel, provider=provider, at=when, region=region
+        )
+        if resolved is None:
+            reasons = tuple(f"missing_{dimension}" for dimension in missing)
+            return CostResult(
+                None,
+                None,
+                None,
+                "unpriced",
+                reasons or ("unknown_deployment",),
+                effective_at=when,
+                missing_dimensions=missing,
+            )
+        return _cost_result(resolved, at=when, usage=usage, missing=missing)
+
     def price_retrieval(
         self,
         *,
@@ -191,7 +254,7 @@ def parse_catalog(
     version = str(document.get("version") or "")
     if not version:
         raise CatalogError("prices document must have a version")
-    _catalog_metadata(document)
+    currency, _ = _catalog_metadata(document)
     aliases: dict[tuple[str, str], list[Alias]] = {}
     prices: list[Price] = []
     for entry in document["models"]:
@@ -311,6 +374,7 @@ def parse_catalog(
                     effective_to=effective_to,
                     source_url=str(price["source_url"]).strip(),
                     publisher=publisher,
+                    currency=currency,
                 )
             )
     return version, {key: tuple(value) for key, value in aliases.items()}, prices

{metergraph_core-0.2.61 → metergraph_core-0.3.0/src/metergraph_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph-core
-Version: 0.2.61
+Version: 0.3.0
 Summary: Reusable MeterGraph catalog and deterministic billing engine
 License-Expression: Apache-2.0
 Requires-Python: >=3.10
@@ -92,6 +92,58 @@ prefix, the latter only onto an `aws-bedrock` alias. Geographic prefixes such as
 `LoadedCatalog.pricing_verified_at` records when the bundled catalog was last
 checked against its linked provider sources.
 
+### Direct lookup and usage cost
+
+`lookup_price` returns the price a call is billed at, and `calculate_cost`
+costs a call's usage at that price:
+
+```python
+from metergraph_core import ModelUsage
+
+found = catalog.lookup_price(
+    model="gpt-5.4-mini",
+    provider="openai",
+    at=datetime(2026, 8, 17, tzinfo=timezone.utc),
+)
+print(found.status, found.model_id, found.price.id, found.price.currency)
+
+result = catalog.calculate_cost(
+    model="gpt-5.4-mini",
+    provider="openai",
+    at=datetime(2026, 8, 17, tzinfo=timezone.utc),
+    usage=ModelUsage(input_tokens=1000, output_tokens=200, cache_read_tokens=500),
+)
+print(result.status, result.model_id, result.cost, result.currency)
+print(result.components.input, result.components.cache_read)
+```
+
+Both resolve exactly as `resolve_price` and `price` do, including
+effective-date windows and the Bedrock fallback, and cost through the same
+arithmetic. `model_id` is the resolved catalog ID, not the alias passed in, and
+`price` is the applied catalog row. An explicit `channel` is authoritative;
+without one, `provider` supplies its direct channel, and with neither the
+result is `unpriced` with `missing_dimensions=("channel",)`.
+
+Every `Price` states its `currency`, and `CostResult.currency` is the currency
+of the applied price. The bundled catalog is USD. `cost` and
+`components.input`, `output`, `cache_read`, `cache_write` and `request` are in
+that currency; the older `cost_usd` and `*_usd` names return the same values.
+
+A `ModelUsage` count left `None` is unknown, not zero. A missing input or
+output count keeps the subtotal that is known, marks the result `partial`, and
+lists `input_tokens` or `output_tokens` in `missing_dimensions`.
+
+`region` selects a regional price and overrides the `region` passed to
+`load_catalog`. When neither names a region:
+
+- if every region bills the model the same, the result is `priced`;
+- if a global price applies but some region bills differently, the global
+  price is returned as `partial` with `missing_dimensions=("region",)`;
+- if only specific regions price the model, the result is `unpriced` with
+  `missing_dimensions=("region",)`.
+
+A region the model is not sold in is `unpriced` with nothing missing.
+
 ## Model registry
 
 ```python
@@ -165,7 +217,9 @@ from metergraph_core import (
     LoadedCatalog,
     ModelRegistry,
     ModelRoute,
+    ModelUsage,
     Price,
+    PriceResult,
     ResolvedPrice,
     load_catalog,
     load_model_registry,