metergraph-core 0.1.0__tar.gz

metergraph_core-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+# Tests are not part of the distributed package. setuptools would otherwise
+# auto-include top-level test modules in the sdist; prune the whole tree so the
+# sdist matches the wheel and ships only the package and its bundled catalog.
+prune tests

metergraph_core-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: metergraph-core
+Version: 0.1.0
+Summary: Reusable MeterGraph catalog and deterministic token-cost pricing engine
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+
+# metergraph-core
+
+Reusable catalog and deterministic token-cost pricing engine for MeterGraph.
+
+`metergraph-core` owns the public effective-dated model catalog and the pricing
+logic shared across MeterGraph systems: catalog parsing and validation, provider
+and model alias resolution, channel and region selection, input/output/cache/
+batch/long-context pricing rules, deterministic cost calculation with reason
+codes, stable logical price identifiers, and catalog version and content-hash
+reporting.
+
+It does not own HTTP routes, database access, migrations, authentication,
+tenancy, ingest, dashboard code, or any hosted-only concern, and it never reads
+server environment variables.
+
+## Install
+
+```bash
+python -m pip install metergraph-core
+```
+
+## Usage
+
+```python
+from datetime import datetime, timezone
+
+from metergraph_core import load_catalog
+
+catalog = load_catalog(region="global")
+result = catalog.snapshot.cost(
+    provider="openai",
+    model="gpt-5.4-mini",
+    at=datetime(2026, 8, 17, tzinfo=timezone.utc),
+    input_tokens=1000,
+    output_tokens=200,
+)
+print(result.canonical_model, result.price_id, result.cost_usd, result.status)
+```
+
+`load_catalog()` loads the catalog bundled in the installed package. Pass an
+explicit `path` for tests or a self-hosted catalog replacement. The returned
+`LoadedCatalog` exposes the declared catalog `version`, the SHA-256
+`content_hash` of the loaded bytes, the parsed `document`, and the immutable
+`snapshot` used for pricing.
+
+Planning and evaluation systems that know the deployment channel before making
+a call can resolve the exact effective price without emulating a provider
+response:
+
+```python
+price = catalog.snapshot.resolve_price(
+    model="openai/gpt-5.6-luna",
+    channel="vercel-ai-gateway",
+    at=datetime(2026, 8, 17, tzinfo=timezone.utc),
+)
+if price is not None:
+    print(
+        price.canonical_model,
+        price.price.id,
+        price.price.input_per_mtok,
+        price.price.source_url,
+    )
+```
+
+Resolution accepts canonical IDs and channel-scoped aliases, normalizes case
+and surrounding whitespace, applies the configured region fallback and
+effective-date windows, and returns `None` when no exact model/channel price
+exists. It never substitutes a direct-provider price for a gateway price.
+
+`LoadedCatalog.currency` is currently always `USD`, and
+`LoadedCatalog.pricing_verified_at` records when the bundled catalog was last
+checked against its linked provider sources.
+
+## Public API
+
+```python
+from metergraph_core import (
+    Alias,
+    CatalogError,
+    CatalogSnapshot,
+    CostResult,
+    LoadedCatalog,
+    Price,
+    ResolvedPrice,
+    load_catalog,
+    parse_catalog,
+)
+```
+
+## Catalog maintenance
+
+The only manually maintained public catalog lives at
+`src/metergraph_core/data/prices.yaml`. Every record requires its provider
+source URL and effective date. Corrections close or add effective windows; they
+never rewrite historical prices in place. A catalog change updates the declared
+catalog version and produces a patch release of `metergraph-core`. Software
+version and catalog version are separate values because code and price data have
+different lifecycles.

metergraph_core-0.1.0/README.md

@@ -0,0 +1,98 @@
+# metergraph-core
+
+Reusable catalog and deterministic token-cost pricing engine for MeterGraph.
+
+`metergraph-core` owns the public effective-dated model catalog and the pricing
+logic shared across MeterGraph systems: catalog parsing and validation, provider
+and model alias resolution, channel and region selection, input/output/cache/
+batch/long-context pricing rules, deterministic cost calculation with reason
+codes, stable logical price identifiers, and catalog version and content-hash
+reporting.
+
+It does not own HTTP routes, database access, migrations, authentication,
+tenancy, ingest, dashboard code, or any hosted-only concern, and it never reads
+server environment variables.
+
+## Install
+
+```bash
+python -m pip install metergraph-core
+```
+
+## Usage
+
+```python
+from datetime import datetime, timezone
+
+from metergraph_core import load_catalog
+
+catalog = load_catalog(region="global")
+result = catalog.snapshot.cost(
+    provider="openai",
+    model="gpt-5.4-mini",
+    at=datetime(2026, 8, 17, tzinfo=timezone.utc),
+    input_tokens=1000,
+    output_tokens=200,
+)
+print(result.canonical_model, result.price_id, result.cost_usd, result.status)
+```
+
+`load_catalog()` loads the catalog bundled in the installed package. Pass an
+explicit `path` for tests or a self-hosted catalog replacement. The returned
+`LoadedCatalog` exposes the declared catalog `version`, the SHA-256
+`content_hash` of the loaded bytes, the parsed `document`, and the immutable
+`snapshot` used for pricing.
+
+Planning and evaluation systems that know the deployment channel before making
+a call can resolve the exact effective price without emulating a provider
+response:
+
+```python
+price = catalog.snapshot.resolve_price(
+    model="openai/gpt-5.6-luna",
+    channel="vercel-ai-gateway",
+    at=datetime(2026, 8, 17, tzinfo=timezone.utc),
+)
+if price is not None:
+    print(
+        price.canonical_model,
+        price.price.id,
+        price.price.input_per_mtok,
+        price.price.source_url,
+    )
+```
+
+Resolution accepts canonical IDs and channel-scoped aliases, normalizes case
+and surrounding whitespace, applies the configured region fallback and
+effective-date windows, and returns `None` when no exact model/channel price
+exists. It never substitutes a direct-provider price for a gateway price.
+
+`LoadedCatalog.currency` is currently always `USD`, and
+`LoadedCatalog.pricing_verified_at` records when the bundled catalog was last
+checked against its linked provider sources.
+
+## Public API
+
+```python
+from metergraph_core import (
+    Alias,
+    CatalogError,
+    CatalogSnapshot,
+    CostResult,
+    LoadedCatalog,
+    Price,
+    ResolvedPrice,
+    load_catalog,
+    parse_catalog,
+)
+```
+
+## Catalog maintenance
+
+The only manually maintained public catalog lives at
+`src/metergraph_core/data/prices.yaml`. Every record requires its provider
+source URL and effective date. Corrections close or add effective windows; they
+never rewrite historical prices in place. A catalog change updates the declared
+catalog version and produces a patch release of `metergraph-core`. Software
+version and catalog version are separate values because code and price data have
+different lifecycles.

metergraph_core-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "metergraph-core"
+version = "0.1.0"
+description = "Reusable MeterGraph catalog and deterministic token-cost pricing engine"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = [
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "pytest>=8"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+metergraph_core = ["data/prices.yaml"]

metergraph_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

metergraph_core-0.1.0/src/metergraph_core/__init__.py

@@ -0,0 +1,21 @@
+"""Reusable MeterGraph catalog and deterministic token-cost pricing core."""
+
+from .catalog import Alias, CatalogSnapshot, CostResult, Price, ResolvedPrice
+from .loader import (
+    CatalogError,
+    LoadedCatalog,
+    load_catalog,
+    parse_catalog,
+)
+
+__all__ = [
+    "Alias",
+    "CatalogError",
+    "CatalogSnapshot",
+    "CostResult",
+    "LoadedCatalog",
+    "Price",
+    "ResolvedPrice",
+    "load_catalog",
+    "parse_catalog",
+]

metergraph_core-0.1.0/src/metergraph_core/catalog.py

@@ -0,0 +1,275 @@
+"""Effective-dated model catalog and deterministic token-cost enrichment."""
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from decimal import Decimal, InvalidOperation, ROUND_HALF_UP
+from types import MappingProxyType
+from typing import Any, Mapping
+
+_MILLION = Decimal("1000000")
+_COST_QUANTUM = Decimal("0.00000001")
+_PROVIDER_ALIASES = {
+    "amazon-bedrock": "bedrock",
+    "aws": "bedrock",
+    "aws-bedrock": "bedrock",
+    "gemini": "google",
+    "google-genai": "google",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class Alias:
+    model_id: str
+    canonical_id: str
+    pricing_channel: str
+    rules: Mapping[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class Price:
+    id: str
+    model_id: str
+    pricing_channel: str
+    region: str
+    input_per_mtok: Decimal | None
+    output_per_mtok: Decimal | None
+    cache_read_per_mtok: Decimal | None
+    cache_write_5m_per_mtok: Decimal | None
+    cache_write_1h_per_mtok: Decimal | None
+    batch_input_per_mtok: Decimal | None
+    batch_output_per_mtok: Decimal | None
+    rules: Mapping[str, Any]
+    effective_from: datetime
+    effective_to: datetime | None
+    source_url: str
+
+
+@dataclass(frozen=True, slots=True)
+class CostResult:
+    canonical_model: str | None
+    price_id: str | None
+    cost_usd: Decimal | None
+    status: str
+    reasons: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedPrice:
+    """An effective price selected for a planned model deployment."""
+
+    canonical_model: str
+    price: Price
+    rules: Mapping[str, Any]
+
+
+def _decimal(value: Any) -> Decimal | None:
+    if value is None:
+        return None
+    try:
+        result = Decimal(str(value))
+    except (InvalidOperation, ValueError, TypeError):
+        return None
+    return result if result.is_finite() else None
+
+
+def _tokens(value: Any) -> int | None:
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        result = int(value)
+    except (ValueError, TypeError, OverflowError):
+        return None
+    return result if result >= 0 else None
+
+
+class CatalogSnapshot:
+    def __init__(
+        self,
+        aliases: Mapping[tuple[str, str], Alias],
+        prices: list[Price],
+        *,
+        region: str,
+    ) -> None:
+        self._aliases = dict(aliases)
+        self._prices: dict[tuple[str, str], list[Price]] = {}
+        self._deployment_aliases: dict[tuple[str, str], 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 price in prices:
+            self._prices.setdefault((price.model_id, price.pricing_channel), []).append(
+                price
+            )
+        for candidates in self._prices.values():
+            candidates.sort(key=lambda price: price.effective_from, reverse=True)
+
+    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 price in candidates:
+                if price.region.lower() != region:
+                    continue
+                if price.effective_from <= at and (
+                    price.effective_to is None or at < price.effective_to
+                ):
+                    return price
+        return None
+
+    def resolve_price(
+        self, *, model: Any, channel: Any, at: datetime
+    ) -> ResolvedPrice | None:
+        """Resolve pricing for an explicitly selected model and channel.
+
+        This is intended for planners and evaluation pipelines that know the
+        deployment channel before making a provider call. It never falls back
+        to pricing from a different channel.
+        """
+
+        model_key = str(model or "").strip().lower()
+        channel_key = str(channel or "").strip().lower()
+        alias = self._deployment_aliases.get((model_key, channel_key))
+        if alias is None:
+            return None
+        price = self._price_for(alias, at)
+        if price is None:
+            return None
+        return ResolvedPrice(
+            canonical_model=alias.canonical_id,
+            price=price,
+            rules=MappingProxyType({**price.rules, **alias.rules}),
+        )
+
+    def cost(
+        self,
+        *,
+        provider: Any,
+        model: Any,
+        at: datetime,
+        input_tokens: Any,
+        output_tokens: Any,
+        cache_read_tokens: Any = None,
+        cache_write_tokens: Any = None,
+        batch: bool = False,
+    ) -> CostResult:
+        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))
+        if alias is None:
+            return CostResult(None, None, None, "unpriced", ("unknown_model",))
+        price = self._price_for(alias, at)
+        if price is None:
+            return CostResult(
+                alias.canonical_id,
+                None,
+                None,
+                "unpriced",
+                ("no_effective_price",),
+            )
+
+        reasons: list[str] = []
+        input_count = _tokens(input_tokens)
+        output_count = _tokens(output_tokens)
+        cache_read_count = _tokens(cache_read_tokens) or 0
+        cache_write_count = _tokens(cache_write_tokens) or 0
+        if input_count is None:
+            reasons.append("missing_input_tokens")
+            input_count = 0
+        if output_count is None:
+            reasons.append("missing_output_tokens")
+            output_count = 0
+
+        rules = {**price.rules, **alias.rules}
+        billable_input = input_count
+        deducted_input = 0
+        if rules.get("input_includes_cache_read"):
+            if cache_read_count > input_count:
+                reasons.append("cache_read_exceeds_input")
+                deducted_input = input_count
+            else:
+                deducted_input += cache_read_count
+        if rules.get("input_includes_cache_write"):
+            if cache_write_count > input_count - deducted_input:
+                reasons.append("cache_write_exceeds_input")
+                deducted_input = input_count
+            else:
+                deducted_input += cache_write_count
+        billable_input -= deducted_input
+
+        input_rate = price.input_per_mtok
+        output_rate = price.output_per_mtok
+        if batch:
+            if (
+                price.batch_input_per_mtok is None
+                or price.batch_output_per_mtok is None
+            ):
+                reasons.append("batch_rate_unavailable")
+            else:
+                input_rate = price.batch_input_per_mtok
+                output_rate = price.batch_output_per_mtok
+
+        input_multiplier = Decimal("1")
+        output_multiplier = Decimal("1")
+        long_context = rules.get("long_context") or {}
+        threshold = _tokens(long_context.get("threshold"))
+        if threshold is not None and input_count > threshold:
+            input_multiplier = _decimal(
+                long_context.get("input_multiplier")
+            ) or Decimal("1")
+            output_multiplier = _decimal(
+                long_context.get("output_multiplier")
+            ) or Decimal("1")
+
+        cost = Decimal("0")
+        if input_rate is None:
+            if billable_input:
+                reasons.append("input_rate_unavailable")
+        else:
+            cost += Decimal(billable_input) * input_rate * input_multiplier / _MILLION
+        if output_rate is None:
+            if output_count:
+                reasons.append("output_rate_unavailable")
+        else:
+            cost += Decimal(output_count) * output_rate * output_multiplier / _MILLION
+        if cache_read_count:
+            if price.cache_read_per_mtok is None:
+                reasons.append("cache_read_rate_unavailable")
+            else:
+                cost += (
+                    Decimal(cache_read_count)
+                    * price.cache_read_per_mtok
+                    * input_multiplier
+                    / _MILLION
+                )
+        if cache_write_count:
+            if price.cache_write_5m_per_mtok is None:
+                reasons.append("cache_write_rate_unavailable")
+            else:
+                cost += (
+                    Decimal(cache_write_count)
+                    * price.cache_write_5m_per_mtok
+                    * input_multiplier
+                    / _MILLION
+                )
+        if rules.get("uncaptured_fees"):
+            reasons.append("uncaptured_fees")
+
+        return CostResult(
+            alias.canonical_id,
+            price.id,
+            cost.quantize(_COST_QUANTUM, rounding=ROUND_HALF_UP),
+            "partial" if reasons else "priced",
+            tuple(dict.fromkeys(reasons)),
+        )