metergraph-core 0.8.0__tar.gz → 0.8.2__tar.gz

{metergraph_core-0.8.0/src/metergraph_core.egg-info → metergraph_core-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph-core
-Version: 0.8.0
+Version: 0.8.2
 Summary: Open, effective-dated LLM pricing catalog and deterministic cost calculator for popular models across major providers and gateways, including OpenAI, Anthropic, Google Gemini, AWS Bedrock, OpenRouter, Vercel AI Gateway, and more.
 Author: Metergraph
 License-Expression: Apache-2.0
@@ -210,6 +210,11 @@ A call after it ended resolves to that price, stays `priced`, and carries
 applied `price.effective_to` says when it ended. A closed price followed by a
 later one never extends, so a gap before a scheduled price stays `unpriced`.
 
+An `unpriced` result whose cause is a value you passed, such as an unknown
+channel, provider or model, says why in `warnings`. Each `PricingWarning` has
+a stable `code` and a `message` that may suggest the value you meant. Match on
+`code`; the message text may change.
+
 ### Costing a provider response
 
 `cost_from_response` reads the usage out of a response you already have and
@@ -351,6 +356,41 @@ effective_from)` on a model the catalog already has:
   start on a later UTC date than the row it replaces, for the same reason.
 - `close_price` sets `effective_to` on the open row without a replacement.
 
+Catalog operations change which models exist and what calls they match:
+
+- `add_model` appends one complete model entry.
+- `add_alias` appends one alias to an existing model. A spelling another
+  model already holds is a conflict only while both aliases are in effect.
+- `close_alias` sets `effective_to` on an open alias, named by
+  `(canonical_id, provider, alias, channel)`; `expect` is the exact current
+  alias. An alias with dates must cite its source, so a close carries
+  `source_url` when the alias has none and must not when it has one.
+
+A `close_alias`, `close_price`, `add_alias` and `add_price` together move a
+spelling from a duplicate entry to the model it duplicates from a date. Calls
+before that date keep the old model and price, calls from it resolve to the
+surviving model, and the old entry stays for history with nothing in effect:
+
+```yaml
+  - op: close_alias
+    key: {canonical_id: example-host/model-a-instruct, provider: openrouter,
+          alias: example-host/model-a-instruct, channel: openrouter-api}
+    expect: {provider: openrouter, alias: example-host/model-a-instruct, channel: openrouter-api}
+    effective_to: "2026-10-20"
+    source_url: "https://..."
+  - op: close_price      # the duplicate's open openrouter-api row
+  - op: add_alias
+    key: {canonical_id: example/model-a, provider: openrouter,
+          alias: example-host/model-a-instruct, channel: openrouter-api}
+    expect: null
+    alias: {provider: openrouter, alias: example-host/model-a-instruct,
+            channel: openrouter-api, effective_from: "2026-10-20", source_url: "https://..."}
+  - op: add_price        # the same rate on example/model-a from 2026-10-20
+```
+
+Gateway discovery matches a spelling only through aliases in effect on the
+observation date, so it follows a moved spelling to its new model.
+
 A price id ends with the UTC date of its row's start. If two rows for one
 model, channel and region would still share an id (possible in a hand-edited
 catalog), each that does not start at UTC midnight also names its UTC start

{metergraph_core-0.8.0 → metergraph_core-0.8.2}/README.md

@@ -180,6 +180,11 @@ A call after it ended resolves to that price, stays `priced`, and carries
 applied `price.effective_to` says when it ended. A closed price followed by a
 later one never extends, so a gap before a scheduled price stays `unpriced`.
 
+An `unpriced` result whose cause is a value you passed, such as an unknown
+channel, provider or model, says why in `warnings`. Each `PricingWarning` has
+a stable `code` and a `message` that may suggest the value you meant. Match on
+`code`; the message text may change.
+
 ### Costing a provider response
 
 `cost_from_response` reads the usage out of a response you already have and
@@ -321,6 +326,41 @@ effective_from)` on a model the catalog already has:
   start on a later UTC date than the row it replaces, for the same reason.
 - `close_price` sets `effective_to` on the open row without a replacement.
 
+Catalog operations change which models exist and what calls they match:
+
+- `add_model` appends one complete model entry.
+- `add_alias` appends one alias to an existing model. A spelling another
+  model already holds is a conflict only while both aliases are in effect.
+- `close_alias` sets `effective_to` on an open alias, named by
+  `(canonical_id, provider, alias, channel)`; `expect` is the exact current
+  alias. An alias with dates must cite its source, so a close carries
+  `source_url` when the alias has none and must not when it has one.
+
+A `close_alias`, `close_price`, `add_alias` and `add_price` together move a
+spelling from a duplicate entry to the model it duplicates from a date. Calls
+before that date keep the old model and price, calls from it resolve to the
+surviving model, and the old entry stays for history with nothing in effect:
+
+```yaml
+  - op: close_alias
+    key: {canonical_id: example-host/model-a-instruct, provider: openrouter,
+          alias: example-host/model-a-instruct, channel: openrouter-api}
+    expect: {provider: openrouter, alias: example-host/model-a-instruct, channel: openrouter-api}
+    effective_to: "2026-10-20"
+    source_url: "https://..."
+  - op: close_price      # the duplicate's open openrouter-api row
+  - op: add_alias
+    key: {canonical_id: example/model-a, provider: openrouter,
+          alias: example-host/model-a-instruct, channel: openrouter-api}
+    expect: null
+    alias: {provider: openrouter, alias: example-host/model-a-instruct,
+            channel: openrouter-api, effective_from: "2026-10-20", source_url: "https://..."}
+  - op: add_price        # the same rate on example/model-a from 2026-10-20
+```
+
+Gateway discovery matches a spelling only through aliases in effect on the
+observation date, so it follows a moved spelling to its new model.
+
 A price id ends with the UTC date of its row's start. If two rows for one
 model, channel and region would still share an id (possible in a hand-edited
 catalog), each that does not start at UTC midnight also names its UTC start

{metergraph_core-0.8.0 → metergraph_core-0.8.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metergraph-core"
-version = "0.8.0"
+version = "0.8.2"
 description = "Open, effective-dated LLM pricing catalog and deterministic cost calculator for popular models across major providers and gateways, including OpenAI, Anthropic, Google Gemini, AWS Bedrock, OpenRouter, Vercel AI Gateway, and more."
 readme = "README.md"
 license = "Apache-2.0"

{metergraph_core-0.8.0 → metergraph_core-0.8.2}/src/metergraph_core/__init__.py

@@ -8,6 +8,7 @@ from .catalog import (
     ModelUsage,
     Price,
     PriceResult,
+    PricingWarning,
     ResolvedPrice,
     counts_cache_read_in_input,
     direct_channel_for_provider,
@@ -128,6 +129,7 @@ __all__ = [
     "GatewayBillingEvidence",
     "Price",
     "PriceResult",
+    "PricingWarning",
     "ResolvedPrice",
     "RetrievalCatalog",
     "RetrievalCostResult",

{metergraph_core-0.8.0 → metergraph_core-0.8.2}/src/metergraph_core/catalog.py

@@ -1,5 +1,6 @@
 """Effective-dated model catalog and deterministic token-cost enrichment."""
 
+import difflib
 import re
 from dataclasses import dataclass
 from datetime import date, datetime, timezone
@@ -86,6 +87,16 @@ _GLOBAL_REGION = "global"
 # Reason for a result priced at a price that ended and was not replaced.
 PRICE_ENDED = "price_ended"
 
+# Warning codes: why a result is unpriced, when the cause is a value the
+# caller sent. The codes are stable; the messages may change.
+UNKNOWN_CHANNEL = "unknown_channel"
+UNKNOWN_PROVIDER = "unknown_provider"
+UNKNOWN_MODEL = "unknown_model"
+MODEL_NOT_ON_CHANNEL = "model_not_on_channel"
+MODEL_NOT_IN_EFFECT = "model_not_in_effect"
+MODEL_NOT_IN_REGION = "model_not_in_region"
+PRICE_NOT_IN_EFFECT = "price_not_in_effect"
+
 
 def _bedrock_fallback_ids(model_key: str) -> tuple[tuple[str, bool], ...]:
     """Candidate ids for an unmatched Bedrock model, most specific first.
@@ -301,6 +312,9 @@ class CostResult:
     # Inputs the caller did not supply that the figure depends on: "region",
     # "channel", "input_tokens", "output_tokens".
     missing_dimensions: tuple[str, ...] = ()
+    # Why an unpriced result is unpriced, when the cause is a value the
+    # caller sent. Empty otherwise.
+    warnings: tuple["PricingWarning", ...] = ()
 
     @property
     def model_id(self) -> str | None:
@@ -343,6 +357,30 @@ class PriceResult:
     missing_dimensions: tuple[str, ...] = ()
     # Notes that do not make the result partial, such as ``price_ended``.
     reasons: tuple[str, ...] = ()
+    # Why an unpriced result is unpriced, when the cause is a value the
+    # caller sent. Empty otherwise.
+    warnings: tuple["PricingWarning", ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class PricingWarning:
+    """Why a result is unpriced, when the cause is a value the caller sent:
+    a channel or provider the catalog cannot bill on, a model name it does
+    not know, or a model the channel does not sell at that time. ``code`` is
+    stable; ``message`` names the value and, when one is close, the value
+    the caller probably meant."""
+
+    code: str
+    message: str
+
+
+def _did_you_mean(
+    value: str, options: Any, guess: str | None = None, cutoff: float = 0.6
+) -> str:
+    options = sorted(options)
+    close = difflib.get_close_matches(value, options, 1, cutoff)
+    match = guess if guess in options else next(iter(close), None)
+    return f' Did you mean "{match}"?' if match else ""
 
 
 @dataclass(frozen=True, slots=True)
@@ -713,6 +751,17 @@ class CatalogSnapshot:
             )
         for candidates in self._prices.values():
             candidates.sort(key=lambda price: price.effective_from, reverse=True)
+        # For explaining an unpriced result: the channels some price row
+        # bills on, and each model name with the channels that sell it under
+        # that name, an alias there and a price there, at any time.
+        priced = {(model_id, channel.lower()) for model_id, channel in self._prices}
+        self._priced_channels = frozenset(channel for _, channel in priced)
+        sold: dict[str, set[str]] = {}
+        for (model, channel), candidates in self._deployment_aliases.items():
+            found = sold.setdefault(model, set())
+            if any((alias.model_id, channel) in priced for alias in candidates):
+                found.add(channel)
+        self._sold = {model: frozenset(channels) for model, channels in sold.items()}
         # Every named region a price or pin exists for: the regions an omitted
         # query region could have meant.
         self._regions = tuple(sorted(
@@ -894,6 +943,147 @@ class CatalogSnapshot:
             return resolved, ("region",)
         return resolved, ()
 
+    def _explain(
+        self, *, model: Any, channel: Any, provider: Any, at: Any, region: Any
+    ) -> tuple[PricingWarning, ...]:
+        """Why :meth:`_lookup` found no price, when the cause is a value the
+        caller sent. Each check follows the step of the lookup it explains:
+        the channel, or the provider's direct channel, then the model name on
+        that channel, then the alias and price windows at ``at``."""
+        channel_key = str(channel or "").strip().lower()
+        if channel_key:
+            if channel_key not in self._priced_channels:
+                # A provider's name, with or without "-api", points at its
+                # direct channel.
+                guess = direct_channel_for_provider(
+                    channel_key
+                ) or direct_channel_for_provider(channel_key.removesuffix("-api"))
+                return (PricingWarning(
+                    UNKNOWN_CHANNEL,
+                    f'channel "{str(channel).strip()}" is not a channel the catalog prices.'
+                    f"{_did_you_mean(channel_key, self._priced_channels, guess)}",
+                ),)
+        else:
+            if provider is None or not str(provider).strip():
+                return ()
+            channel_key = direct_channel_for_provider(provider)
+            if channel_key is None:
+                providers = set(_DIRECT_CHANNEL_BY_PROVIDER) | {
+                    spelling for spelling, name in _PROVIDER_ALIASES.items()
+                    if name in _DIRECT_CHANNEL_BY_PROVIDER
+                }
+                return (PricingWarning(
+                    UNKNOWN_PROVIDER,
+                    f'provider "{str(provider).strip()}" has no billing channel of its own.'
+                    f"{_did_you_mean(str(provider).strip().lower(), providers)} If a gateway or "
+                    "proxy relayed the call, name the provider that served it or the channel "
+                    "that billed it.",
+                ),)
+        model_key = str(model or "").strip().lower()
+        if not model_key:
+            return ()
+        # Bedrock fallback ids, under the rules _resolve applies: dropping
+        # "global." is valid only on aws-bedrock, and never across a price
+        # region.
+        keys, dropped, forbidden = [model_key], set(), []
+        if channel_key in _BEDROCK_CHANNELS:
+            for candidate, dropped_global in _bedrock_fallback_ids(model_key):
+                if dropped_global and channel_key != _BEDROCK_CHANNEL:
+                    forbidden.append(candidate)
+                    continue
+                keys.append(candidate)
+                if dropped_global:
+                    dropped.add(candidate)
+        name = str(model).strip()
+        if not any(key in self._sold for key in keys):
+            # A "global." id on a geo channel points at the bare id that
+            # channel sells.
+            guess = next(
+                (key for key in forbidden if channel_key in self._sold.get(key, ())), None
+            )
+            return (PricingWarning(
+                UNKNOWN_MODEL,
+                f'model "{name}" is not in the catalog.'
+                f"{_did_you_mean(model_key, self._sold, guess, cutoff=0.8)}",
+            ),)
+        candidates = tuple(
+            alias
+            for key in keys
+            for alias in self._deployment_aliases.get((key, channel_key), ())
+            if key not in dropped or not _crosses_price_region(alias)
+        )
+        sold = sorted({channel for key in keys for channel in self._sold.get(key, ())})
+        if not candidates or channel_key not in sold:
+            where = (
+                f"It is priced on {', '.join(sold)}."
+                if sold
+                else "No channel prices it under that name."
+            )
+            return (PricingWarning(
+                MODEL_NOT_ON_CHANNEL,
+                f'model "{name}" has no price on channel "{channel_key}". {where}',
+            ),)
+        when = _coerce_datetime(at)
+        stated = str(region or "").strip().lower() or None
+        alias = self._alias_for(candidates, when, stated)
+        if alias is None:
+            return (self._unresolved(name, channel_key, candidates, when, stated),)
+        price, _ = self._price_for(alias, when, stated)
+        if price is None:
+            scope = f' in region "{stated}"' if stated else ""
+            return (PricingWarning(
+                PRICE_NOT_IN_EFFECT,
+                f'model "{name}" has no price on channel "{channel_key}"{scope} in effect at '
+                f"{when.isoformat()}.",
+            ),)
+        return ()
+
+    def _unresolved(
+        self,
+        name: str,
+        channel: str,
+        candidates: tuple[Alias, ...],
+        when: datetime,
+        region: str | None,
+    ) -> PricingWarning:
+        """Why no alias for ``name`` on ``channel`` applies at ``when``: its
+        windows close before or open after it, or the aliases in effect are
+        pinned to other regions."""
+        current = [
+            alias for alias in candidates
+            if (alias.effective_from is None or alias.effective_from <= when)
+            and (alias.effective_to is None or when < alias.effective_to)
+        ]
+        if current:
+            regions = sorted({pin for alias in current for pin in alias.price_region})
+            asked = region or self._region
+            return PricingWarning(
+                MODEL_NOT_IN_REGION,
+                f'model "{name}" resolves on channel "{channel}" only in '
+                f"{', '.join(regions)}, not {asked}.",
+            )
+        ended = [alias.effective_to for alias in candidates
+                 if alias.effective_to is not None and alias.effective_to <= when]
+        starts = [alias.effective_from for alias in candidates
+                  if alias.effective_from is not None and when < alias.effective_from]
+        if ended and starts:
+            when_text = (
+                f"between {max(ended).date().isoformat()} and "
+                f"{min(starts).date().isoformat()}"
+            )
+            message = f'model "{name}" does not resolve on channel "{channel}" {when_text}.'
+        elif ended:
+            message = (
+                f'model "{name}" stopped resolving on channel "{channel}" on '
+                f"{max(ended).date().isoformat()}."
+            )
+        else:
+            message = (
+                f'model "{name}" resolves on channel "{channel}" from '
+                f"{min(starts).date().isoformat()}."
+            )
+        return PricingWarning(MODEL_NOT_IN_EFFECT, message)
+
     def cost(
         self,
         *,

{metergraph_core-0.8.0 → metergraph_core-0.8.2}/src/metergraph_core/catalog_delta.py

@@ -15,7 +15,15 @@ catalog already has:
 It also supports reviewed catalog expansion:
 
 - ``add_model`` appends one complete model entry.
-- ``add_alias`` appends one alias to an existing model.
+- ``add_alias`` appends one alias to an existing model. A spelling another
+  model holds conflicts only while both aliases are in effect, so a spelling
+  can move to another model from a date.
+- ``close_alias`` sets ``effective_to`` on the open alias its ``expect``
+  names, so a spelling closed and reopened on one model keeps its earlier
+  window. With an
+  ``add_alias`` for the same spelling on another model in one delta, it
+  moves that spelling: calls before the date keep the old model, calls from
+  it resolve to the new one.
 
 ``provenance`` references the observations and evidence the delta came
 from.
@@ -34,7 +42,7 @@ from .loader import CatalogError, _canonical_json, load_catalog_document
 CATALOG_DELTA_SCHEMA_VERSION = 2
 PRICING_DELTA_KIND = "pricing_delta"
 PRICE_OPERATIONS = ("add_price", "replace_price", "close_price")
-CATALOG_OPERATIONS = ("add_model", "add_alias")
+CATALOG_OPERATIONS = ("add_model", "add_alias", "close_alias")
 OPERATIONS = PRICE_OPERATIONS + CATALOG_OPERATIONS
 
 RATE_FIELDS = (
@@ -116,12 +124,14 @@ class DeltaOperation:
     expect: Mapping[str, Any] | None
     # The new row for add/replace; None for close.
     price: Mapping[str, Any] | None
-    # The closing date for close_price.
+    # The closing date for close_price and close_alias.
     effective_to: str | None
     # The complete entry for add_model.
     model: Mapping[str, Any] | None = None
     # The alias row for add_alias.
     alias: Mapping[str, Any] | None = None
+    # The source a close_alias cites, for an alias that cites none.
+    source_url: str | None = None
 
 
 @dataclass(frozen=True, slots=True)
@@ -197,7 +207,7 @@ def _parse_model_key(raw: Any, label: str) -> ModelKey:
     return ModelKey(_text(raw["canonical_id"]))
 
 
-def _parse_alias_key(raw: Any, label: str) -> AliasKey:
+def _parse_alias_key(raw: Any, label: str, op: str) -> AliasKey:
     if not isinstance(raw, Mapping):
         raise CatalogDeltaError(f"{label}: key must be a mapping")
     fields = ("canonical_id", "provider", "alias", "channel")
@@ -205,7 +215,7 @@ def _parse_alias_key(raw: Any, label: str) -> AliasKey:
         if _text(raw.get(field)) is None:
             raise CatalogDeltaError(f"{label}: key needs {field}")
     if set(raw) != set(fields):
-        raise CatalogDeltaError(f"{label}: add_alias key has unknown fields")
+        raise CatalogDeltaError(f"{label}: {op} key has unknown fields")
     return AliasKey(
         _text(raw["canonical_id"]),
         _text(raw["provider"]).lower(),
@@ -324,8 +334,8 @@ def _parse_operation(index: int, raw: Any) -> DeltaOperation:
         raise CatalogDeltaError(f"{label}: unknown op {op!r}")
     if op == "add_model":
         key: OperationKey = _parse_model_key(raw.get("key"), label)
-    elif op == "add_alias":
-        key = _parse_alias_key(raw.get("key"), label)
+    elif op in ("add_alias", "close_alias"):
+        key = _parse_alias_key(raw.get("key"), label, op)
     else:
         key = _parse_key(raw.get("key"), label)
     expect = raw.get("expect")
@@ -338,6 +348,7 @@ def _parse_operation(index: int, raw: Any) -> DeltaOperation:
     effective_to = None
     model = None
     alias = None
+    source_url = None
     if op == "add_model":
         if "price" in raw or "alias" in raw or "effective_to" in raw:
             raise CatalogDeltaError(f"{label}: add_model takes only model")
@@ -346,6 +357,18 @@ def _parse_operation(index: int, raw: Any) -> DeltaOperation:
         if "price" in raw or "model" in raw or "effective_to" in raw:
             raise CatalogDeltaError(f"{label}: add_alias takes only alias")
         alias = _parse_alias(raw.get("alias"), key, label)
+    elif op == "close_alias":
+        if set(raw) - {"op", "key", "expect", "effective_to", "source_url"}:
+            raise CatalogDeltaError(
+                f"{label}: close_alias takes only effective_to and source_url"
+            )
+        effective_to = _iso_date(raw.get("effective_to"))
+        if effective_to is None:
+            raise CatalogDeltaError(f"{label}: invalid effective_to")
+        if "source_url" in raw:
+            source_url = _text(raw.get("source_url"))
+            if source_url is None:
+                raise CatalogDeltaError(f"{label}: invalid source_url")
     elif op == "close_price":
         if "price" in raw:
             raise CatalogDeltaError(f"{label}: close_price takes no price")
@@ -369,6 +392,7 @@ def _parse_operation(index: int, raw: Any) -> DeltaOperation:
         effective_to=effective_to,
         model=model,
         alias=alias,
+        source_url=source_url,
     )
 
 
@@ -480,8 +504,53 @@ def _key_label(key: OperationKey) -> str:
     return key.canonical_id
 
 
-def _precondition(document: Mapping[str, Any], operation: DeltaOperation) -> str | None:
-    """Why ``operation`` does not apply to ``document``, or None when it does."""
+def _alias_rows(
+    entry: Mapping[str, Any], key: AliasKey
+) -> list[Mapping[str, Any]]:
+    return [
+        alias
+        for alias in entry.get("aliases") or []
+        if isinstance(alias, Mapping)
+        and (_text(alias.get("provider")) or "").lower() == key.provider
+        and (_text(alias.get("alias")) or "").lower() == key.alias
+        and _text(alias.get("channel")) == key.channel
+    ]
+
+
+def _expected_aliases(
+    entry: Mapping[str, Any], operation: DeltaOperation
+) -> list[Mapping[str, Any]]:
+    """The rows under a close_alias key that equal its ``expect``. A key can
+    hold several windows of one spelling; ``expect`` names the one to end."""
+    expected = _canonical_json(operation.expect)
+    return [
+        alias
+        for alias in _alias_rows(entry, operation.key)
+        if _canonical_json(alias) == expected
+    ]
+
+
+def _windows_overlap(
+    left_from: Any, left_to: Any, right_from: Any, right_to: Any
+) -> bool:
+    """Whether two alias windows share an instant; a missing bound is open,
+    as the catalog loader reads it."""
+    left_from, left_to = _instant(left_from), _instant(left_to)
+    right_from, right_to = _instant(right_from), _instant(right_to)
+    return (left_to is None or right_from is None or right_from < left_to) and (
+        right_to is None or left_from is None or left_from < right_to
+    )
+
+
+def _precondition(
+    document: Mapping[str, Any],
+    operation: DeltaOperation,
+    closing: Mapping[AliasKey, str] | None = None,
+) -> str | None:
+    """Why ``operation`` does not apply to ``document``, or None when it does.
+
+    ``closing`` maps the key of each alias a close_alias in the same delta
+    ends to its ``effective_to``, so an alias can move in one delta."""
     if operation.op == "add_model":
         key = operation.key
         if _model_indexes(document, key.canonical_id):
@@ -502,13 +571,69 @@ def _precondition(document: Mapping[str, Any], operation: DeltaOperation) -> str
             return "unknown_model"
         if len(models) > 1:
             return "duplicate_model"
-        for canonical_id, provider, name in _aliases(document):
-            if (provider, name) == (key.provider, key.alias):
-                return (
-                    "alias_exists"
-                    if canonical_id == key.canonical_id
-                    else "alias_conflict"
-                )
+        closing = closing or {}
+        new = operation.alias or {}
+        for entry in document.get("models") or []:
+            if not isinstance(entry, Mapping):
+                continue
+            canonical_id = str(entry.get("canonical_id") or "")
+            for alias in entry.get("aliases") or []:
+                if not isinstance(alias, Mapping):
+                    continue
+                provider = (_text(alias.get("provider")) or "").lower()
+                name = (_text(alias.get("alias")) or "").lower()
+                if (provider, name) != (key.provider, key.alias):
+                    continue
+                ends = alias.get("effective_to")
+                if ends is None:
+                    ends = closing.get(
+                        AliasKey(
+                            canonical_id,
+                            provider,
+                            name,
+                            _text(alias.get("channel")) or "",
+                        )
+                    )
+                if _windows_overlap(
+                    alias.get("effective_from"),
+                    ends,
+                    new.get("effective_from"),
+                    new.get("effective_to"),
+                ):
+                    return (
+                        "alias_exists"
+                        if canonical_id == key.canonical_id
+                        else "alias_conflict"
+                    )
+        return None
+    if operation.op == "close_alias":
+        key = operation.key
+        models = _model_indexes(document, key.canonical_id)
+        if not models:
+            return "unknown_model"
+        if len(models) > 1:
+            return "duplicate_model"
+        entry = document["models"][models[0]]
+        if not _alias_rows(entry, key):
+            return "alias_missing"
+        rows = _expected_aliases(entry, operation)
+        if not rows:
+            return "expect_mismatch"
+        if len(rows) > 1:
+            return "duplicate_alias"
+        row = rows[0]
+        if row.get("effective_to") is not None:
+            return "alias_not_open"
+        starts = _instant(row.get("effective_from"))
+        if starts is not None and _instant(operation.effective_to) <= starts:
+            return "not_after_start"
+        # A dated alias must cite its source, so a close supplies one for an
+        # alias that has none, and never replaces one it has.
+        if _text(row.get("source_url")) is None:
+            if operation.source_url is None:
+                return "source_url_needed"
+        elif operation.source_url is not None:
+            return "source_url_exists"
         return None
     model_index, rows, reason = _locate(document, operation)
     if reason is not None:
@@ -565,10 +690,15 @@ def apply_catalog_delta(
     delta = parse_catalog_delta(delta_document)
     if not isinstance(document, Mapping):
         raise CatalogDeltaError("catalog document must be a mapping")
+    closing = {
+        operation.key: operation.effective_to
+        for operation in delta.operations
+        if operation.op == "close_alias"
+    }
     conflicts = tuple(
         DeltaConflict(operation.index, operation.op, operation.key, reason)
         for operation in delta.operations
-        if (reason := _precondition(document, operation)) is not None
+        if (reason := _precondition(document, operation, closing)) is not None
     )
     if conflicts:
         raise CatalogDeltaConflict(conflicts)
@@ -586,6 +716,16 @@ def apply_catalog_delta(
                 copy.deepcopy(dict(operation.alias))
             )
             continue
+        if operation.op == "close_alias":
+            [model_index] = _model_indexes(result, operation.key.canonical_id)
+            # The first equal row is the one checked: an alias this delta
+            # adds under the same key starts after this one ends, so it never
+            # equals ``expect``.
+            alias = _expected_aliases(result["models"][model_index], operation)[0]
+            alias["effective_to"] = operation.effective_to
+            if operation.source_url is not None:
+                alias["source_url"] = operation.source_url
+            continue
         model_index, rows, _ = _locate(result, operation)
         prices = result["models"][model_index].setdefault("prices", [])
         if operation.op == "add_price":

{metergraph_core-0.8.0 → metergraph_core-0.8.2}/src/metergraph_core/data/prices.yaml

@@ -4985,7 +4985,7 @@ models:
         cache_read_per_mtok: 0.125
         batch_input_per_mtok: 0.625
         batch_output_per_mtok: 5
-        source_url: https://ai-gateway.vercel.sh/v1/models
+        source_url: https://developers.openai.com/api/docs/models/gpt-5
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2026-10-02"
@@ -5010,7 +5010,7 @@ models:
         input_per_mtok: 1.75
         output_per_mtok: 14
         cache_read_per_mtok: 0.175
-        source_url: https://ai-gateway.vercel.sh/v1/models
+        source_url: https://developers.openai.com/api/docs/models/gpt-5.3-codex
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2026-10-02"
@@ -5141,11 +5141,22 @@ models:
       - channel: openai-api
         region: global
         effective_from: "2026-07-09"
+        effective_to: "2026-10-27"
         input_per_mtok: 12.5
         output_per_mtok: 75
         cache_read_per_mtok: 1.25
         cache_write_5m_per_mtok: 15.625
-        source_url: https://ai-gateway.vercel.sh/v1/models
+        source_url: https://developers.openai.com/api/docs/models/gpt-5.6-cyber
+      - channel: openai-api
+        region: global
+        effective_from: "2026-10-27"
+        input_per_mtok: 12.5
+        output_per_mtok: 75
+        cache_read_per_mtok: 1.25
+        cache_write_5m_per_mtok: 15.625
+        rules:
+          long_context: {threshold: 272000, threshold_counts_cached_tokens: true, input_multiplier: 2, output_multiplier: 1.5}
+        source_url: https://developers.openai.com/api/docs/models/gpt-5.6-cyber
   - canonical_id: openai/o4-mini
     publisher: openai
     aliases:
@@ -5163,7 +5174,7 @@ models:
         cache_read_per_mtok: 0.275
         batch_input_per_mtok: 0.55
         batch_output_per_mtok: 2.2
-        source_url: https://ai-gateway.vercel.sh/v1/models
+        source_url: https://developers.openai.com/api/docs/models/o4-mini
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2025-04-16"

{metergraph_core-0.8.0 → metergraph_core-0.8.2}/src/metergraph_core/loader.py

@@ -153,7 +153,8 @@ class LoadedCatalog:
             model=model, channel=channel, provider=provider, at=when, region=region
         )
         if resolved is None:
-            return PriceResult("unpriced", None, None, when, missing)
+            warnings = self._explain(model, channel, provider, when, region, missing)
+            return PriceResult("unpriced", None, None, when, missing, warnings=warnings)
         return PriceResult(
             "partial" if missing else "priced",
             resolved.canonical_model,
@@ -163,6 +164,15 @@ class LoadedCatalog:
             (PRICE_ENDED,) if resolved.ended else (),
         )
 
+    def _explain(self, model, channel, provider, at, region, missing):
+        """Warnings for an unpriced result. A missing region already says
+        why, so it gets none."""
+        if "region" in missing:
+            return ()
+        return self.snapshot._explain(
+            model=model, channel=channel, provider=provider, at=at, region=region
+        )
+
     def calculate_cost(
         self,
         *,
@@ -190,6 +200,7 @@ class LoadedCatalog:
                 reasons or ("unknown_deployment",),
                 effective_at=when,
                 missing_dimensions=missing,
+                warnings=self._explain(model, channel, provider, when, region, missing),
             )
         return _cost_result(resolved, at=when, usage=usage, missing=missing)
 

{metergraph_core-0.8.0 → metergraph_core-0.8.2}/src/metergraph_core/refresh.py

@@ -619,6 +619,8 @@ def _gateway_price(
 
 # Reviewed gateway spellings for publishers the catalog already names.
 _GATEWAY_PUBLISHER_PREFIXES = {
+    "bytedance-seed": "bytedance",
+    "meta-llama": "meta",
     "mistralai": "mistral",
     "qwen": "alibaba",
     "z-ai": "zai",
@@ -642,8 +644,48 @@ def _identity_shape(model_key: str) -> tuple[str, str]:
     return prefix, "".join(character for character in suffix if character.isalnum())
 
 
+def _current_identity(
+    entry: Mapping[str, Any], day: date
+) -> tuple[str | None, list[Mapping[str, Any]]]:
+    """``entry``'s canonical id and its aliases in effect on ``day``.
+
+    An alias that has ended no longer names the model, so a spelling moved to
+    another model matches only there. The canonical id is left out when it is
+    also one of the model's alias spellings and none of those is in effect,
+    as ``_names`` treats the canonical tail."""
+    aliases = [a for a in entry.get("aliases") or [] if isinstance(a, Mapping)]
+    current = [a for a in aliases if _in_effect(a, day, dated=False)]
+    canonical_id = str(entry.get("canonical_id") or "").strip().lower()
+    spelled = {str(a.get("alias") or "").strip().lower() for a in aliases}
+    active = {str(a.get("alias") or "").strip().lower() for a in current}
+    if canonical_id in spelled and canonical_id not in active:
+        return None, current
+    return canonical_id, current
+
+
+def _channel_models(
+    document: Mapping[str, Any], source: PriceSource, model_key: str, day: date
+) -> list[Mapping[str, Any]]:
+    """Models with an alias in effect on ``day`` that spells ``model_key`` on
+    the source's own channel. That alias is the reviewed mapping for this
+    gateway, so it decides even while another channel still gives the
+    spelling to a different model."""
+    provider, wanted = source.provider.lower(), model_key.strip().lower()
+    return [
+        entry
+        for entry in document.get("models") or []
+        if isinstance(entry, Mapping)
+        and any(
+            str(alias.get("provider") or "").strip().lower() == provider
+            and str(alias.get("alias") or "").strip().lower() == wanted
+            and alias.get("channel") == source.channel
+            for alias in _current_identity(entry, day)[1]
+        )
+    ]
+
+
 def _exact_models(
-    document: Mapping[str, Any], model_key: str
+    document: Mapping[str, Any], model_key: str, day: date
 ) -> list[Mapping[str, Any]]:
     publisher, _, _ = _catalog_gateway_identity(model_key).partition("/")
     wanted = {
@@ -654,17 +696,15 @@ def _exact_models(
     for entry in document.get("models") or []:
         if not isinstance(entry, Mapping):
             continue
-        names = {str(entry.get("canonical_id") or "").strip().lower()}
+        canonical_id, aliases = _current_identity(entry, day)
+        names = {canonical_id} if canonical_id else set()
         names.update(
-            str(alias.get("alias") or "").strip().lower()
-            for alias in entry.get("aliases") or []
-            if isinstance(alias, Mapping)
+            str(alias.get("alias") or "").strip().lower() for alias in aliases
         )
         names.update(
             f"{publisher}/{str(alias.get('alias') or '').strip().lower()}"
-            for alias in entry.get("aliases") or []
-            if isinstance(alias, Mapping)
-            and _catalog_publisher(alias.get("provider")) == publisher
+            for alias in aliases
+            if _catalog_publisher(alias.get("provider")) == publisher
         )
         if wanted & names:
             found.append(entry)
@@ -672,21 +712,21 @@ def _exact_models(
 
 
 def _near_models(
-    document: Mapping[str, Any], model_key: str
+    document: Mapping[str, Any], model_key: str, day: date
 ) -> list[Mapping[str, Any]]:
     wanted = _identity_shape(model_key)
     found = []
     for entry in document.get("models") or []:
         if not isinstance(entry, Mapping):
             continue
-        shapes = {_identity_shape(str(entry.get("canonical_id") or ""))}
+        canonical_id, aliases = _current_identity(entry, day)
+        shapes = {_identity_shape(canonical_id)} if canonical_id else set()
         shapes.update(
             _identity_shape(
                 f"{_catalog_publisher(alias.get('provider'))}/"
                 f"{str(alias.get('alias') or '').strip().lower()}"
             )
-            for alias in entry.get("aliases") or []
-            if isinstance(alias, Mapping)
+            for alias in aliases
         )
         if wanted in shapes:
             found.append(entry)
@@ -703,9 +743,11 @@ def _gateway_additions(
     operations: list[dict[str, Any]] = []
     identity_exclusions: list[dict[str, Any]] = []
     for rate in extraction.rates:
-        matches = _exact_models(document, rate.model_key)
+        matches = _channel_models(
+            document, source, rate.model_key, observed_on
+        ) or _exact_models(document, rate.model_key, observed_on)
         if not matches:
-            near = _near_models(document, rate.model_key)
+            near = _near_models(document, rate.model_key, observed_on)
             if near:
                 identity_exclusions.append(
                     {

{metergraph_core-0.8.0 → metergraph_core-0.8.2/src/metergraph_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph-core
-Version: 0.8.0
+Version: 0.8.2
 Summary: Open, effective-dated LLM pricing catalog and deterministic cost calculator for popular models across major providers and gateways, including OpenAI, Anthropic, Google Gemini, AWS Bedrock, OpenRouter, Vercel AI Gateway, and more.
 Author: Metergraph
 License-Expression: Apache-2.0
@@ -210,6 +210,11 @@ A call after it ended resolves to that price, stays `priced`, and carries
 applied `price.effective_to` says when it ended. A closed price followed by a
 later one never extends, so a gap before a scheduled price stays `unpriced`.
 
+An `unpriced` result whose cause is a value you passed, such as an unknown
+channel, provider or model, says why in `warnings`. Each `PricingWarning` has
+a stable `code` and a `message` that may suggest the value you meant. Match on
+`code`; the message text may change.
+
 ### Costing a provider response
 
 `cost_from_response` reads the usage out of a response you already have and
@@ -351,6 +356,41 @@ effective_from)` on a model the catalog already has:
   start on a later UTC date than the row it replaces, for the same reason.
 - `close_price` sets `effective_to` on the open row without a replacement.
 
+Catalog operations change which models exist and what calls they match:
+
+- `add_model` appends one complete model entry.
+- `add_alias` appends one alias to an existing model. A spelling another
+  model already holds is a conflict only while both aliases are in effect.
+- `close_alias` sets `effective_to` on an open alias, named by
+  `(canonical_id, provider, alias, channel)`; `expect` is the exact current
+  alias. An alias with dates must cite its source, so a close carries
+  `source_url` when the alias has none and must not when it has one.
+
+A `close_alias`, `close_price`, `add_alias` and `add_price` together move a
+spelling from a duplicate entry to the model it duplicates from a date. Calls
+before that date keep the old model and price, calls from it resolve to the
+surviving model, and the old entry stays for history with nothing in effect:
+
+```yaml
+  - op: close_alias
+    key: {canonical_id: example-host/model-a-instruct, provider: openrouter,
+          alias: example-host/model-a-instruct, channel: openrouter-api}
+    expect: {provider: openrouter, alias: example-host/model-a-instruct, channel: openrouter-api}
+    effective_to: "2026-10-20"
+    source_url: "https://..."
+  - op: close_price      # the duplicate's open openrouter-api row
+  - op: add_alias
+    key: {canonical_id: example/model-a, provider: openrouter,
+          alias: example-host/model-a-instruct, channel: openrouter-api}
+    expect: null
+    alias: {provider: openrouter, alias: example-host/model-a-instruct,
+            channel: openrouter-api, effective_from: "2026-10-20", source_url: "https://..."}
+  - op: add_price        # the same rate on example/model-a from 2026-10-20
+```
+
+Gateway discovery matches a spelling only through aliases in effect on the
+observation date, so it follows a moved spelling to its new model.
+
 A price id ends with the UTC date of its row's start. If two rows for one
 model, channel and region would still share an id (possible in a hand-edited
 catalog), each that does not start at UTC midnight also names its UTC start