metergraph-core 0.2.42__tar.gz → 0.2.53__tar.gz

{metergraph_core-0.2.42/src/metergraph_core.egg-info → metergraph_core-0.2.53}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph-core
-Version: 0.2.42
+Version: 0.2.53
 Summary: Reusable MeterGraph catalog and deterministic billing engine
 License-Expression: Apache-2.0
 Requires-Python: >=3.10

{metergraph_core-0.2.42 → metergraph_core-0.2.53}/pyproject.toml

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

{metergraph_core-0.2.42 → metergraph_core-0.2.53}/src/metergraph_core/catalog.py

@@ -81,6 +81,7 @@ _BEDROCK_CHANNEL = "aws-bedrock"
 _BEDROCK_CHANNELS = frozenset({_BEDROCK_CHANNEL, "aws-bedrock-geo"})
 _BEDROCK_VERSION_SUFFIX = re.compile(r"-v\d+(?::\d+)?$")
 _BEDROCK_GLOBAL_PREFIX = "global."
+_GLOBAL_REGION = "global"
 
 
 def _bedrock_fallback_ids(model_key: str) -> tuple[tuple[str, bool], ...]:
@@ -163,6 +164,28 @@ class Alias:
     pricing_channel: str
     rules: Mapping[str, Any]
     publisher: str | None = None
+    effective_from: datetime | None = None
+    effective_to: datetime | None = None
+    source_url: str | None = None
+    # Limits an identifier to matching regions; global matches every snapshot.
+    price_region: tuple[str, ...] = ()
+
+
+def _crosses_price_region(alias: Alias) -> bool:
+    """Whether global-prefix fallback would cross a price-region boundary."""
+    return bool(alias.price_region) and alias.price_region != (_GLOBAL_REGION,)
+
+
+def _effective_windows_overlap(left: Alias, right: Alias) -> bool:
+    return (
+        left.effective_to is None
+        or right.effective_from is None
+        or right.effective_from < left.effective_to
+    ) and (
+        right.effective_to is None
+        or left.effective_from is None
+        or left.effective_from < right.effective_to
+    )
 
 
 @dataclass(frozen=True, slots=True)
@@ -421,28 +444,40 @@ def _price_tokens(
 class CatalogSnapshot:
     def __init__(
         self,
-        aliases: Mapping[tuple[str, str], Alias],
+        aliases: Mapping[tuple[str, str], Alias | tuple[Alias, ...] | list[Alias]],
         prices: list[Price],
         *,
         region: str,
     ) -> None:
-        self._aliases = dict(aliases)
+        self._aliases = {
+            key: (value,) if isinstance(value, Alias) else tuple(value)
+            for key, value in aliases.items()
+        }
         self._prices: dict[tuple[str, str], list[Price]] = {}
-        self._deployment_aliases: dict[tuple[str, str], Alias] = {}
+        deployment_aliases: dict[tuple[str, str], list[Alias]] = {}
         self._region = region.strip().lower()
-        for (_, observed_model), alias in aliases.items():
-            channel = alias.pricing_channel.strip().lower()
-            for model in (observed_model, alias.canonical_id):
-                key = (model.strip().lower(), channel)
-                existing = self._deployment_aliases.get(key)
-                if existing is not None and (
-                    existing.canonical_id != alias.canonical_id
-                    or dict(existing.rules) != dict(alias.rules)
-                ):
-                    raise ValueError(
-                        f"ambiguous deployment alias {model!r} for channel {channel!r}"
-                    )
-                self._deployment_aliases[key] = alias
+        for (_, observed_model), candidates in self._aliases.items():
+            for alias in candidates:
+                channel = alias.pricing_channel.strip().lower()
+                for model in (observed_model, alias.canonical_id):
+                    key = (model.strip().lower(), channel)
+                    deployment_aliases.setdefault(key, []).append(alias)
+        self._deployment_aliases = {
+            key: tuple(candidates) for key, candidates in deployment_aliases.items()
+        }
+        for (model, channel), candidates in self._deployment_aliases.items():
+            for index, alias in enumerate(candidates):
+                for other in candidates[index + 1:]:
+                    if not _effective_windows_overlap(alias, other):
+                        continue
+                    if (
+                        alias.canonical_id != other.canonical_id
+                        or dict(alias.rules) != dict(other.rules)
+                    ):
+                        raise ValueError(
+                            f"ambiguous deployment alias {model!r} "
+                            f"for channel {channel!r}"
+                        )
         for price in prices:
             self._prices.setdefault((price.model_id, price.pricing_channel), []).append(
                 price
@@ -450,10 +485,36 @@ 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:
+        when = _coerce_datetime(at)
+        effective = [
+            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)
+        ]
+        # Regional pins constrain availability; global pins match everywhere.
+        for region in dict.fromkeys((self._region, _GLOBAL_REGION)):
+            for alias in effective:
+                if region 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, ...]:
+        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 ()
+
     def _price_for(self, alias: Alias, at: datetime) -> 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 dict.fromkeys((self._region, "*", "global")):
+        for region in self._price_regions(alias):
             for price in candidates:
                 if price.region.lower() != region:
                     continue
@@ -476,19 +537,21 @@ class CatalogSnapshot:
         model_key = model.strip().lower()
         canonical_ids = {
             alias.canonical_id
-            for (known_model, _channel), alias in self._deployment_aliases.items()
+            for (known_model, _channel), candidates in self._deployment_aliases.items()
             if known_model == model_key
+            for alias in candidates
         }
         if len(canonical_ids) != 1:
             return None
         channels: set[str] = set()
         for canonical_id in canonical_ids:
-            for alias in self._deployment_aliases.values():
-                if alias.canonical_id != canonical_id:
-                    continue
-                channel = direct_channel_for_provider(alias.publisher)
-                if channel is not None and (canonical_id, channel) in self._prices:
-                    channels.add(channel)
+            for candidates in self._deployment_aliases.values():
+                for alias in candidates:
+                    if alias.canonical_id != canonical_id:
+                        continue
+                    channel = direct_channel_for_provider(alias.publisher)
+                    if channel is not None and (canonical_id, channel) in self._prices:
+                        channels.add(channel)
         return next(iter(channels)) if len(channels) == 1 else None
 
     def resolve_price(
@@ -503,17 +566,22 @@ class CatalogSnapshot:
 
         model_key = str(model or "").strip().lower()
         channel_key = str(channel or "").strip().lower()
-        alias = self._deployment_aliases.get((model_key, channel_key))
+        when = _coerce_datetime(at)
+        candidates = self._deployment_aliases.get((model_key, channel_key), ())
+        alias = self._alias_for(candidates, when)
         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
-                alias = self._deployment_aliases.get((candidate, channel_key))
+                candidates = self._deployment_aliases.get((candidate, channel_key), ())
+                alias = self._alias_for(candidates, when)
+                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, at)
+        price = self._price_for(alias, when)
         if price is None:
             return None
         return ResolvedPrice(
@@ -539,19 +607,31 @@ class CatalogSnapshot:
         provider_key = str(provider or "").strip().lower()
         provider_key = _PROVIDER_ALIASES.get(provider_key, provider_key)
         model_key = str(model or "").strip().lower()
-        alias = self._aliases.get((provider_key, model_key))
+        when = _coerce_datetime(at)
+        candidates = self._aliases.get((provider_key, model_key), ())
+        alias_known = bool(candidates)
+        alias = self._alias_for(candidates, when)
         if alias is None and provider_key == "bedrock":
             for candidate, dropped_global in _bedrock_fallback_ids(model_key):
-                found = self._aliases.get((provider_key, candidate))
+                fallback = self._aliases.get((provider_key, candidate), ())
+                alias_known = alias_known or bool(fallback)
+                found = self._alias_for(fallback, when)
                 if found is None or found.pricing_channel not in _BEDROCK_CHANNELS:
                     continue
-                if dropped_global and found.pricing_channel != _BEDROCK_CHANNEL:
+                if dropped_global and (
+                    found.pricing_channel != _BEDROCK_CHANNEL
+                    or _crosses_price_region(found)
+                ):
                     continue
                 alias = found
                 break
         if alias is None:
+            if alias_known:
+                return CostResult(
+                    None, None, None, "unpriced", ("no_effective_alias",)
+                )
             return CostResult(None, None, None, "unpriced", ("unknown_model",))
-        price = self._price_for(alias, at)
+        price = self._price_for(alias, when)
         if price is None:
             return CostResult(
                 alias.canonical_id,
@@ -564,7 +644,7 @@ class CatalogSnapshot:
         cost, reasons = _price_tokens(
             price,
             {**price.rules, **alias.rules},
-            at=_coerce_datetime(at),
+            at=when,
             input_tokens=input_tokens,
             output_tokens=output_tokens,
             cache_read_tokens=cache_read_tokens,