metergraph-core 0.1.0__py3-none-any.whl

metergraph_core/loader.py

@@ -0,0 +1,167 @@
+"""Parse and load the bundled prices.yaml into a CatalogSnapshot."""
+
+import hashlib
+from dataclasses import dataclass
+from datetime import date, datetime, timezone
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any
+
+import yaml
+
+from .catalog import Alias, CatalogSnapshot, Price, _decimal
+
+DEFAULT_CATALOG_PATH = Path(__file__).parent / "data" / "prices.yaml"
+_PROVIDER_SYNONYMS = {"bedrock": ("aws-bedrock", "aws")}
+
+
+class CatalogError(ValueError):
+    pass
+
+
+def _freeze(value: Any) -> Any:
+    if isinstance(value, dict):
+        return MappingProxyType({key: _freeze(item) for key, item in value.items()})
+    if isinstance(value, list):
+        return tuple(_freeze(item) for item in value)
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedCatalog:
+    version: str
+    currency: str
+    pricing_verified_at: date
+    content_hash: str
+    document: dict[str, Any]
+    snapshot: CatalogSnapshot
+
+
+def _date(value: Any, *, field: str, model: str) -> datetime:
+    if value is None:
+        raise CatalogError(f"{model}: missing {field}")
+    try:
+        parsed = datetime.fromisoformat(str(value))
+    except ValueError as exc:
+        raise CatalogError(f"{model}: invalid {field} {value!r}") from exc
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+def _catalog_metadata(document: dict[str, Any]) -> tuple[str, date]:
+    currency = str(document.get("currency") or "").strip().upper()
+    if currency != "USD":
+        raise CatalogError("prices document currency must be USD")
+    try:
+        pricing_verified_at = date.fromisoformat(
+            str(document.get("pricing_verified_at") or "")
+        )
+    except ValueError as exc:
+        raise CatalogError(
+            "prices document must have an ISO pricing_verified_at date"
+        ) from exc
+    return currency, pricing_verified_at
+
+
+def parse_catalog(
+    document: Any,
+) -> tuple[str, dict[tuple[str, str], Alias], list[Price]]:
+    if not isinstance(document, dict) or not isinstance(document.get("models"), list):
+        raise CatalogError("prices document must have a models list")
+    version = str(document.get("version") or "")
+    if not version:
+        raise CatalogError("prices document must have a version")
+    _catalog_metadata(document)
+    aliases: dict[tuple[str, str], Alias] = {}
+    prices: list[Price] = []
+    for entry in document["models"]:
+        canonical = str(entry.get("canonical_id") or "")
+        if not canonical:
+            raise CatalogError("model entry missing canonical_id")
+        for alias in entry.get("aliases") or []:
+            provider = str(alias.get("provider") or "").lower()
+            name = str(alias.get("alias") or "").lower()
+            channel = str(alias.get("channel") or "")
+            if not provider or not name or not channel:
+                raise CatalogError(f"{canonical}: alias needs provider/alias/channel")
+            keys = [(provider, name)]
+            for synonym in _PROVIDER_SYNONYMS.get(provider, ()):
+                keys.append((synonym, name))
+            for key in keys:
+                if key in aliases:
+                    raise CatalogError(f"{canonical}: duplicate alias {key}")
+                aliases[key] = Alias(
+                    model_id=canonical,
+                    canonical_id=canonical,
+                    pricing_channel=channel,
+                    rules=_freeze(alias.get("rules") or {}),
+                )
+        seen_windows: list[tuple[str, str, datetime, datetime | None]] = []
+        for price in entry.get("prices") or []:
+            channel = str(price.get("channel") or "")
+            region = str(price.get("region") or "global")
+            if not channel:
+                raise CatalogError(f"{canonical}: price entry needs channel")
+            if not str(price.get("source_url") or "").strip():
+                raise CatalogError(f"{canonical}: price entry needs source_url")
+            effective_from = _date(
+                price.get("effective_from"), field="effective_from", model=canonical
+            )
+            effective_to = (
+                _date(price.get("effective_to"), field="effective_to", model=canonical)
+                if price.get("effective_to") is not None
+                else None
+            )
+            if effective_to is not None and effective_to <= effective_from:
+                raise CatalogError(f"{canonical}: effective_to before effective_from")
+            for other_channel, other_region, other_from, other_to in seen_windows:
+                if (other_channel, other_region) != (channel, 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"{canonical}: overlapping {channel}/{region} price windows"
+                    )
+            seen_windows.append((channel, region, effective_from, effective_to))
+            prices.append(
+                Price(
+                    id=f"{canonical}:{channel}:{region}:{effective_from.date()}",
+                    model_id=canonical,
+                    pricing_channel=channel,
+                    region=region,
+                    input_per_mtok=_decimal(price.get("input_per_mtok")),
+                    output_per_mtok=_decimal(price.get("output_per_mtok")),
+                    cache_read_per_mtok=_decimal(price.get("cache_read_per_mtok")),
+                    cache_write_5m_per_mtok=_decimal(
+                        price.get("cache_write_5m_per_mtok")
+                    ),
+                    cache_write_1h_per_mtok=_decimal(
+                        price.get("cache_write_1h_per_mtok")
+                    ),
+                    batch_input_per_mtok=_decimal(price.get("batch_input_per_mtok")),
+                    batch_output_per_mtok=_decimal(price.get("batch_output_per_mtok")),
+                    rules=_freeze(price.get("rules") or {}),
+                    effective_from=effective_from,
+                    effective_to=effective_to,
+                    source_url=str(price["source_url"]).strip(),
+                )
+            )
+    return version, aliases, prices
+
+
+def load_catalog(
+    path: str | Path | None = None, *, region: str = "global"
+) -> LoadedCatalog:
+    resolved = Path(path) if path is not None else DEFAULT_CATALOG_PATH
+    content = resolved.read_bytes()
+    document = yaml.safe_load(content)
+    version, aliases, prices = parse_catalog(document)
+    currency, pricing_verified_at = _catalog_metadata(document)
+    return LoadedCatalog(
+        version=version,
+        currency=currency,
+        pricing_verified_at=pricing_verified_at,
+        content_hash=hashlib.sha256(content).hexdigest(),
+        document=document,
+        snapshot=CatalogSnapshot(aliases, prices, region=region),
+    )

metergraph_core-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+metergraph_core/__init__.py,sha256=P9swsQXDsqRz4_XN3YA7XQCd2xFuZbydZLdAQ4N11KQ,439
+metergraph_core/catalog.py,sha256=rpuvaCRIKthnOJ2RvextEj6y5nLs1mOnGT61NQuMalA,9545
+metergraph_core/loader.py,sha256=RfaZZKNk0rNjlOE1bkBYCyRWMhPCjO-5fCplXk5EQsE,6927
+metergraph_core/data/prices.yaml,sha256=GJFTuC6Sj6RJTRwPROOvgFaQiGUJBM-N_2wPXsYJcfc,31937
+metergraph_core-0.1.0.dist-info/METADATA,sha256=6NWNuBtAB1z5-L7zfEdqULJ1mbW9pogy7Oso0EVrRxI,3538
+metergraph_core-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+metergraph_core-0.1.0.dist-info/top_level.txt,sha256=N9yCRr05z4tcQCXAyi9_XFieR-yBZ9dcHNjlolBnn8o,16
+metergraph_core-0.1.0.dist-info/RECORD,,

metergraph_core-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

metergraph_core-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+metergraph_core