metergraph-core 0.2.1__tar.gz → 0.2.2__tar.gz

{metergraph_core-0.2.1/src/metergraph_core.egg-info → metergraph_core-0.2.2}/PKG-INFO

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

{metergraph_core-0.2.1 → metergraph_core-0.2.2}/pyproject.toml

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

{metergraph_core-0.2.1 → metergraph_core-0.2.2}/src/metergraph_core/__init__.py

@@ -19,6 +19,12 @@ from .loader import (
     LoadedCatalog,
     load_catalog,
     parse_catalog,
+    parse_retrieval,
+)
+from .retrieval import (
+    RetrievalCatalog,
+    RetrievalCostResult,
+    RetrievalPrice,
 )
 
 __all__ = [
@@ -31,9 +37,13 @@ __all__ = [
     "GatewayBillingEvidence",
     "Price",
     "ResolvedPrice",
+    "RetrievalCatalog",
+    "RetrievalCostResult",
+    "RetrievalPrice",
     "direct_channel_for_provider",
     "load_catalog",
     "normalize_gateway_evidence",
     "parse_catalog",
+    "parse_retrieval",
     "resolve_billing",
 ]

{metergraph_core-0.2.1 → metergraph_core-0.2.2}/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-08-25"
+version: "2026-08-26"
 currency: USD
-pricing_verified_at: "2026-08-25"
+pricing_verified_at: "2026-08-26"
 models:
   - canonical_id: openai/gpt-5.6-sol
     publisher: openai
@@ -975,3 +975,39 @@ models:
         output_per_mtok: 0.50
         cache_read_per_mtok: 0.05
         source_url: https://vercel.com/ai-gateway/models/grok-4.1-fast-reasoning/providers
+
+# Retrieval prices: USD per 1,000 counted operations (completed searches, tool
+# calls, executed grounding queries), billed on the provider's direct channel.
+# These sit alongside the model-token catalog above but are priced per unit, not
+# per token. Effective-dated like model prices: keep superseded entries and close
+# them with `effective_to` rather than editing in place. A $0 fee is an explicit
+# priced zero, not the absence of a price.
+retrieval:
+  - channel: anthropic-api
+    operation: web_search
+    region: global
+    unit: completed_search
+    per_1k_usd: 10.00
+    effective_from: "2026-08-26"
+    source_url: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/web-search-tool
+  - channel: anthropic-api
+    operation: web_fetch
+    region: global
+    unit: tool_call
+    per_1k_usd: 0.00
+    effective_from: "2026-08-26"
+    source_url: https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/web-fetch-tool
+  - channel: openai-api
+    operation: web_search
+    region: global
+    unit: tool_call
+    per_1k_usd: 10.00
+    effective_from: "2026-08-26"
+    source_url: https://platform.openai.com/docs/pricing
+  - channel: google-api
+    operation: google_search_grounding
+    region: global
+    unit: executed_query
+    per_1k_usd: 14.00
+    effective_from: "2026-08-26"
+    source_url: https://ai.google.dev/gemini-api/docs/pricing

{metergraph_core-0.2.1 → metergraph_core-0.2.2}/src/metergraph_core/loader.py

@@ -17,6 +17,7 @@ from .catalog import (
     _decimal,
     _normalize_provider,
 )
+from .retrieval import RetrievalCatalog, RetrievalCostResult, RetrievalPrice
 
 DEFAULT_CATALOG_PATH = Path(__file__).parent / "data" / "prices.yaml"
 _PROVIDER_SYNONYMS = {"bedrock": ("aws-bedrock", "aws")}
@@ -72,6 +73,7 @@ class LoadedCatalog:
     document: dict[str, Any]
     snapshot: CatalogSnapshot
     canonical_ids: Mapping[tuple[str, str], str]
+    retrieval: RetrievalCatalog
 
     def canonical_model_id(self, provider: str, model_id: str) -> str:
         """Resolve a captured provider-native model id to its canonical id,
@@ -113,6 +115,26 @@ class LoadedCatalog:
             batch=batch,
         )
 
+    def price_retrieval(
+        self,
+        *,
+        channel: Any,
+        operation: Any,
+        units: Any,
+        at: Any,
+        region: Any = "global",
+    ) -> RetrievalCostResult:
+        """Price a retrieval operation (searches, tool calls, grounded queries)
+        by counted unit. See :meth:`RetrievalCatalog.price`. This is kept
+        distinct from :meth:`price`, which costs model-token usage."""
+        return self.retrieval.price(
+            channel=channel,
+            operation=operation,
+            units=units,
+            at=at,
+            region=region,
+        )
+
 
 def _date(value: Any, *, field: str, model: str) -> datetime:
     if value is None:
@@ -228,6 +250,79 @@ def parse_catalog(
     return version, aliases, prices
 
 
+def parse_retrieval(document: Any) -> list[RetrievalPrice]:
+    """Parse the optional top-level ``retrieval`` list into effective-dated
+    per-1,000-unit prices, applying the same effective-date validation as the
+    token catalog (ISO dates, ``effective_to`` after ``effective_from``, no
+    overlapping windows per channel/operation/region). A per-unit rate must be
+    present and non-negative. An absent ``retrieval`` key yields no prices."""
+    if not isinstance(document, dict):
+        raise CatalogError("prices document must be a mapping")
+    entries = document.get("retrieval")
+    if entries is None:
+        return []
+    if not isinstance(entries, list):
+        raise CatalogError("prices document retrieval must be a list")
+    prices: list[RetrievalPrice] = []
+    seen_windows: list[tuple[str, str, str, datetime, datetime | None]] = []
+    for entry in entries:
+        channel = str(entry.get("channel") or "").strip().lower()
+        operation = str(entry.get("operation") or "").strip().lower()
+        region = str(entry.get("region") or "global")
+        unit = str(entry.get("unit") or "").strip()
+        if not channel or not operation:
+            raise CatalogError("retrieval entry needs channel/operation")
+        label = f"{channel}/{operation}"
+        if not unit:
+            raise CatalogError(f"{label}: retrieval entry needs a unit")
+        if not str(entry.get("source_url") or "").strip():
+            raise CatalogError(f"{label}: retrieval entry needs source_url")
+        per_1k_usd = _decimal(entry.get("per_1k_usd"))
+        if per_1k_usd is None or per_1k_usd < 0:
+            raise CatalogError(
+                f"{label}: retrieval entry needs a non-negative per_1k_usd"
+            )
+        effective_from = _date(
+            entry.get("effective_from"), field="effective_from", model=label
+        )
+        effective_to = (
+            _date(entry.get("effective_to"), field="effective_to", model=label)
+            if entry.get("effective_to") is not None
+            else None
+        )
+        if effective_to is not None and effective_to <= effective_from:
+            raise CatalogError(f"{label}: effective_to before effective_from")
+        for other in seen_windows:
+            other_channel, other_operation, other_region, other_from, other_to = other
+            if (other_channel, other_operation, other_region) != (
+                channel,
+                operation,
+                region,
+            ):
+                continue
+            if (effective_to is None or other_from < effective_to) and (
+                other_to is None or effective_from < other_to
+            ):
+                raise CatalogError(
+                    f"{label}: overlapping {region} retrieval price windows"
+                )
+        seen_windows.append((channel, operation, region, effective_from, effective_to))
+        prices.append(
+            RetrievalPrice(
+                id=f"{channel}:{operation}:{region}:{effective_from.date()}",
+                channel=channel,
+                operation=operation,
+                region=region,
+                unit=unit,
+                per_1k_usd=per_1k_usd,
+                effective_from=effective_from,
+                effective_to=effective_to,
+                source_url=str(entry["source_url"]).strip(),
+            )
+        )
+    return prices
+
+
 def load_catalog(
     path: str | Path | None = None, *, region: str = "global"
 ) -> LoadedCatalog:
@@ -244,4 +339,5 @@ def load_catalog(
         document=document,
         snapshot=CatalogSnapshot(aliases, prices, region=region),
         canonical_ids=_canonical_index(document),
+        retrieval=RetrievalCatalog(parse_retrieval(document)),
     )

metergraph_core-0.2.2/src/metergraph_core/retrieval.py

@@ -0,0 +1,141 @@
+"""Effective-dated retrieval pricing: searches, tool calls, grounded queries.
+
+Retrieval pricing sits alongside -- and deliberately apart from -- the
+model-token catalog. A retrieval operation is billed per counted unit (a
+completed web search, a tool call, an executed grounding query), never per
+token, so it carries its own price shape and its own catalog object.
+
+The contract mirrors the token path's explicit priced/partial/unpriced
+semantics: a resolved operation with a valid unit count is ``priced`` (a $0
+fee is a real priced zero), while a missing, non-integer, or negative unit
+count and an unknown operation or channel come back ``unpriced`` with a reason
+-- never silently priced at zero.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from decimal import Decimal, ROUND_HALF_UP
+from typing import Any
+
+from .catalog import _COST_QUANTUM, _coerce_datetime
+
+_THOUSAND = Decimal("1000")
+
+
+@dataclass(frozen=True, slots=True)
+class RetrievalPrice:
+    """An effective-dated per-1,000-unit price for one channel/operation."""
+
+    id: str
+    channel: str
+    operation: str
+    region: str
+    unit: str
+    per_1k_usd: Decimal
+    effective_from: datetime
+    effective_to: datetime | None
+    source_url: str
+
+
+@dataclass(frozen=True, slots=True)
+class RetrievalCostResult:
+    """The outcome of pricing a retrieval operation.
+
+    ``status`` reuses the token path's vocabulary (``priced``/``partial``/
+    ``unpriced``); retrieval never produces ``partial`` because a unit count is
+    all-or-nothing -- a bad count leaves nothing knowable to price.
+    """
+
+    price_id: str | None
+    cost_usd: Decimal | None
+    status: str
+    reasons: tuple[str, ...] = ()
+
+
+def _units(value: Any) -> tuple[int | None, str | None]:
+    """Coerce a retrieval unit count under a strict-integer contract.
+
+    Only a real, non-negative ``int`` is a valid count. ``bool`` (``type`` is
+    ``bool``, not ``int``), ``float``, strings, and ``Decimal`` are rejected as
+    ``invalid_units`` rather than truncated or parsed; ``None`` is
+    ``missing_units`` and a negative int is ``negative_units``. Each rejection
+    keeps the operation explicitly unpriced instead of turning it into zero.
+    """
+    if value is None:
+        return None, "missing_units"
+    if type(value) is not int:
+        return None, "invalid_units"
+    if value < 0:
+        return None, "negative_units"
+    return value, None
+
+
+class RetrievalCatalog:
+    """Resolve and cost retrieval operations by ``(channel, operation)``.
+
+    Channel selection is exact and region resolution falls back
+    ``region -> "*" -> "global"``, mirroring the token snapshot: an operation a
+    channel does not carry stays unpriced rather than being repriced off another
+    channel or region.
+    """
+
+    def __init__(self, prices: list[RetrievalPrice]) -> None:
+        self._by_key: dict[tuple[str, str], list[RetrievalPrice]] = {}
+        self._channels: set[str] = set()
+        for price in prices:
+            self._channels.add(price.channel)
+            self._by_key.setdefault((price.channel, price.operation), []).append(price)
+        for candidates in self._by_key.values():
+            candidates.sort(key=lambda price: price.effective_from, reverse=True)
+
+    def _select(
+        self, channel: str, operation: str, region: str, at: datetime
+    ) -> RetrievalPrice | None:
+        at = at if at.tzinfo else at.replace(tzinfo=timezone.utc)
+        candidates = self._by_key.get((channel, operation), [])
+        for candidate_region in dict.fromkeys((region, "*", "global")):
+            for price in candidates:
+                if price.region.lower() != candidate_region:
+                    continue
+                if price.effective_from <= at and (
+                    price.effective_to is None or at < price.effective_to
+                ):
+                    return price
+        return None
+
+    def price(
+        self,
+        *,
+        channel: Any,
+        operation: Any,
+        units: Any,
+        at: Any,
+        region: Any = "global",
+    ) -> RetrievalCostResult:
+        """Price ``units`` of ``operation`` on ``channel`` at time ``at``.
+
+        Resolution happens before unit validation: an unknown channel or
+        operation is reported as such regardless of the unit count, because an
+        operation that cannot be identified cannot be priced at all.
+        """
+        channel_key = str(channel or "").strip().lower()
+        operation_key = str(operation or "").strip().lower()
+        region_key = str(region or "global").strip().lower() or "global"
+
+        if channel_key not in self._channels:
+            return RetrievalCostResult(None, None, "unpriced", ("unknown_channel",))
+        if (channel_key, operation_key) not in self._by_key:
+            return RetrievalCostResult(None, None, "unpriced", ("unknown_operation",))
+
+        price = self._select(channel_key, operation_key, region_key, _coerce_datetime(at))
+        if price is None:
+            return RetrievalCostResult(None, None, "unpriced", ("no_effective_price",))
+
+        count, reason = _units(units)
+        if reason is not None:
+            return RetrievalCostResult(None, None, "unpriced", (reason,))
+
+        cost = (Decimal(count) * price.per_1k_usd / _THOUSAND).quantize(
+            _COST_QUANTUM, rounding=ROUND_HALF_UP
+        )
+        return RetrievalCostResult(price.id, cost, "priced", ())

{metergraph_core-0.2.1 → metergraph_core-0.2.2/src/metergraph_core.egg-info}/PKG-INFO

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

{metergraph_core-0.2.1 → metergraph_core-0.2.2}/src/metergraph_core.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ src/metergraph_core/__init__.py
 src/metergraph_core/billing.py
 src/metergraph_core/catalog.py
 src/metergraph_core/loader.py
+src/metergraph_core/retrieval.py
 src/metergraph_core.egg-info/PKG-INFO
 src/metergraph_core.egg-info/SOURCES.txt
 src/metergraph_core.egg-info/dependency_links.txt