metergraph-core 0.1.4__tar.gz → 0.2.0__tar.gz

{metergraph_core-0.1.4/src/metergraph_core.egg-info → metergraph_core-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: metergraph-core
-Version: 0.1.4
-Summary: Reusable MeterGraph catalog and deterministic token-cost pricing engine
+Version: 0.2.0
+Summary: Reusable MeterGraph catalog and deterministic billing engine
 License-Expression: Apache-2.0
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -12,14 +12,15 @@ Requires-Dist: pytest>=8; extra == "dev"
 
 # metergraph-core
 
-Reusable catalog and deterministic token-cost pricing engine for MeterGraph.
+Reusable catalog and deterministic billing 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.
+reporting. It also owns the pure decision that selects a qualified
+gateway-reported charge or a catalog estimate as the effective call cost.
 
 It does not own HTTP routes, database access, migrations, authentication,
 tenancy, ingest, dashboard code, or any hosted-only concern, and it never reads
@@ -83,19 +84,51 @@ exists. It never substitutes a direct-provider price for a gateway price.
 `LoadedCatalog.pricing_verified_at` records when the bundled catalog was last
 checked against its linked provider sources.
 
+## Billing evidence
+
+Servers can pass content-blind, already-extracted gateway fields through the
+shared trust boundary and combine them with a catalog result:
+
+```python
+from metergraph_core import normalize_gateway_evidence, resolve_billing
+
+evidence = normalize_gateway_evidence({
+    "gateway": "openrouter",
+    "endpoint": "chat.completions",
+    "reported_cost_usd": "0.00482",
+    "reported_cost_source": "openrouter.usage.cost",
+})
+decision = resolve_billing(result, evidence)
+print(decision.cost_usd, decision.cost_provenance)
+```
+
+The initial qualified contract is OpenRouter Chat Completions. A finite,
+non-negative `openrouter.usage.cost` value, including zero, takes precedence
+over a catalog estimate. The decision retains both values and never adds the
+separately reported upstream inference cost to the OpenRouter account charge.
+Unsupported or malformed evidence falls back to the catalog result.
+
+The billing module validates only gateway, endpoint, fixed source names, and
+decimal cost values. It does not inspect provider response content or own SDK
+capture, HTTP, timestamps, trace context, persistence, or tenant behavior.
+
 ## Public API
 
 ```python
 from metergraph_core import (
     Alias,
+    BillingDecision,
     CatalogError,
     CatalogSnapshot,
     CostResult,
+    GatewayBillingEvidence,
     LoadedCatalog,
     Price,
     ResolvedPrice,
     load_catalog,
+    normalize_gateway_evidence,
     parse_catalog,
+    resolve_billing,
 )
 ```
 

{metergraph_core-0.1.4 → metergraph_core-0.2.0}/README.md

@@ -1,13 +1,14 @@
 # metergraph-core
 
-Reusable catalog and deterministic token-cost pricing engine for MeterGraph.
+Reusable catalog and deterministic billing 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.
+reporting. It also owns the pure decision that selects a qualified
+gateway-reported charge or a catalog estimate as the effective call cost.
 
 It does not own HTTP routes, database access, migrations, authentication,
 tenancy, ingest, dashboard code, or any hosted-only concern, and it never reads
@@ -71,19 +72,51 @@ exists. It never substitutes a direct-provider price for a gateway price.
 `LoadedCatalog.pricing_verified_at` records when the bundled catalog was last
 checked against its linked provider sources.
 
+## Billing evidence
+
+Servers can pass content-blind, already-extracted gateway fields through the
+shared trust boundary and combine them with a catalog result:
+
+```python
+from metergraph_core import normalize_gateway_evidence, resolve_billing
+
+evidence = normalize_gateway_evidence({
+    "gateway": "openrouter",
+    "endpoint": "chat.completions",
+    "reported_cost_usd": "0.00482",
+    "reported_cost_source": "openrouter.usage.cost",
+})
+decision = resolve_billing(result, evidence)
+print(decision.cost_usd, decision.cost_provenance)
+```
+
+The initial qualified contract is OpenRouter Chat Completions. A finite,
+non-negative `openrouter.usage.cost` value, including zero, takes precedence
+over a catalog estimate. The decision retains both values and never adds the
+separately reported upstream inference cost to the OpenRouter account charge.
+Unsupported or malformed evidence falls back to the catalog result.
+
+The billing module validates only gateway, endpoint, fixed source names, and
+decimal cost values. It does not inspect provider response content or own SDK
+capture, HTTP, timestamps, trace context, persistence, or tenant behavior.
+
 ## Public API
 
 ```python
 from metergraph_core import (
     Alias,
+    BillingDecision,
     CatalogError,
     CatalogSnapshot,
     CostResult,
+    GatewayBillingEvidence,
     LoadedCatalog,
     Price,
     ResolvedPrice,
     load_catalog,
+    normalize_gateway_evidence,
     parse_catalog,
+    resolve_billing,
 )
 ```
 

{metergraph_core-0.1.4 → metergraph_core-0.2.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "metergraph-core"
-version = "0.1.4"
-description = "Reusable MeterGraph catalog and deterministic token-cost pricing engine"
+version = "0.2.0"
+description = "Reusable MeterGraph catalog and deterministic billing engine"
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.10"

{metergraph_core-0.1.4 → metergraph_core-0.2.0}/src/metergraph_core/__init__.py

@@ -8,6 +8,12 @@ from .catalog import (
     ResolvedPrice,
     direct_channel_for_provider,
 )
+from .billing import (
+    BillingDecision,
+    GatewayBillingEvidence,
+    normalize_gateway_evidence,
+    resolve_billing,
+)
 from .loader import (
     CatalogError,
     LoadedCatalog,
@@ -17,13 +23,17 @@ from .loader import (
 
 __all__ = [
     "Alias",
+    "BillingDecision",
     "CatalogError",
     "CatalogSnapshot",
     "CostResult",
     "LoadedCatalog",
+    "GatewayBillingEvidence",
     "Price",
     "ResolvedPrice",
     "direct_channel_for_provider",
     "load_catalog",
+    "normalize_gateway_evidence",
     "parse_catalog",
+    "resolve_billing",
 ]

metergraph_core-0.2.0/src/metergraph_core/billing.py

@@ -0,0 +1,135 @@
+"""Pure selection of effective LLM cost from catalog and gateway evidence."""
+
+from dataclasses import dataclass
+from decimal import Decimal, InvalidOperation
+from typing import Any, Mapping
+
+from .catalog import CostResult
+
+_OPENROUTER = "openrouter"
+_CHAT_COMPLETIONS = "chat.completions"
+_OPENROUTER_COST_SOURCE = "openrouter.usage.cost"
+_OPENROUTER_UPSTREAM_COST_SOURCE = (
+    "openrouter.usage.cost_details.upstream_inference_cost"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class GatewayBillingEvidence:
+    """Validated gateway billing fields from one content-blind call row."""
+
+    gateway: str | None
+    endpoint: str | None
+    reported_cost_usd: Decimal | None
+    reported_cost_source: str | None
+    reported_upstream_cost_usd: Decimal | None
+    reported_upstream_cost_source: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class BillingDecision:
+    """Effective cost plus the independent evidence used to select it."""
+
+    cost_usd: Decimal | None
+    cost_status: str
+    cost_provenance: str
+    reported_cost_usd: Decimal | None
+    reported_upstream_cost_usd: Decimal | None
+    catalog_cost_usd: Decimal | None
+    catalog_price_id: str | None
+    catalog_reasons: tuple[str, ...]
+    cost_discrepancy_status: str | None = None
+
+
+def _text(value: Any, *, limit: int = 128) -> str | None:
+    if not isinstance(value, str):
+        return None
+    stripped = value.strip()
+    return stripped[:limit] if stripped else None
+
+
+def _non_negative_decimal(value: Any) -> Decimal | None:
+    if value is None or isinstance(value, bool):
+        return None
+    try:
+        result = Decimal(str(value))
+    except (InvalidOperation, ValueError, TypeError):
+        return None
+    if not result.is_finite() or result < 0:
+        return None
+    return result
+
+
+def normalize_gateway_evidence(row: Mapping[str, Any]) -> GatewayBillingEvidence:
+    """Allowlist and validate gateway billing evidence from a call mapping."""
+
+    gateway = _text(row.get("gateway"), limit=64)
+    if gateway is not None:
+        gateway = gateway.lower()
+    endpoint = _text(row.get("endpoint"), limit=64)
+    reported_source = _text(row.get("reported_cost_source"))
+    upstream_source = _text(row.get("reported_upstream_cost_source"))
+
+    return GatewayBillingEvidence(
+        gateway=gateway,
+        endpoint=endpoint,
+        reported_cost_usd=_non_negative_decimal(row.get("reported_cost_usd")),
+        reported_cost_source=reported_source,
+        reported_upstream_cost_usd=_non_negative_decimal(
+            row.get("reported_upstream_cost_usd")
+        ),
+        reported_upstream_cost_source=upstream_source,
+    )
+
+
+def _is_openrouter_chat_completions(evidence: GatewayBillingEvidence) -> bool:
+    return (
+        evidence.gateway == _OPENROUTER
+        and evidence.endpoint == _CHAT_COMPLETIONS
+    )
+
+
+def resolve_billing(
+    catalog_result: CostResult,
+    evidence: GatewayBillingEvidence,
+) -> BillingDecision:
+    """Select effective cost without combining independent reported amounts."""
+
+    qualified_openrouter = _is_openrouter_chat_completions(evidence)
+    reported_cost = (
+        evidence.reported_cost_usd
+        if qualified_openrouter
+        and evidence.reported_cost_source == _OPENROUTER_COST_SOURCE
+        else None
+    )
+    upstream_cost = (
+        evidence.reported_upstream_cost_usd
+        if qualified_openrouter
+        and evidence.reported_upstream_cost_source
+        == _OPENROUTER_UPSTREAM_COST_SOURCE
+        else None
+    )
+
+    if reported_cost is not None:
+        cost_usd = reported_cost
+        cost_status = "priced"
+        provenance = "gateway_reported"
+    elif catalog_result.cost_usd is not None:
+        cost_usd = catalog_result.cost_usd
+        cost_status = catalog_result.status
+        provenance = "catalog"
+    else:
+        cost_usd = None
+        cost_status = catalog_result.status
+        provenance = "none"
+
+    return BillingDecision(
+        cost_usd=cost_usd,
+        cost_status=cost_status,
+        cost_provenance=provenance,
+        reported_cost_usd=reported_cost,
+        reported_upstream_cost_usd=upstream_cost,
+        catalog_cost_usd=catalog_result.cost_usd,
+        catalog_price_id=catalog_result.price_id,
+        catalog_reasons=catalog_result.reasons,
+    )

{metergraph_core-0.1.4 → metergraph_core-0.2.0/src/metergraph_core.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: metergraph-core
-Version: 0.1.4
-Summary: Reusable MeterGraph catalog and deterministic token-cost pricing engine
+Version: 0.2.0
+Summary: Reusable MeterGraph catalog and deterministic billing engine
 License-Expression: Apache-2.0
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -12,14 +12,15 @@ Requires-Dist: pytest>=8; extra == "dev"
 
 # metergraph-core
 
-Reusable catalog and deterministic token-cost pricing engine for MeterGraph.
+Reusable catalog and deterministic billing 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.
+reporting. It also owns the pure decision that selects a qualified
+gateway-reported charge or a catalog estimate as the effective call cost.
 
 It does not own HTTP routes, database access, migrations, authentication,
 tenancy, ingest, dashboard code, or any hosted-only concern, and it never reads
@@ -83,19 +84,51 @@ exists. It never substitutes a direct-provider price for a gateway price.
 `LoadedCatalog.pricing_verified_at` records when the bundled catalog was last
 checked against its linked provider sources.
 
+## Billing evidence
+
+Servers can pass content-blind, already-extracted gateway fields through the
+shared trust boundary and combine them with a catalog result:
+
+```python
+from metergraph_core import normalize_gateway_evidence, resolve_billing
+
+evidence = normalize_gateway_evidence({
+    "gateway": "openrouter",
+    "endpoint": "chat.completions",
+    "reported_cost_usd": "0.00482",
+    "reported_cost_source": "openrouter.usage.cost",
+})
+decision = resolve_billing(result, evidence)
+print(decision.cost_usd, decision.cost_provenance)
+```
+
+The initial qualified contract is OpenRouter Chat Completions. A finite,
+non-negative `openrouter.usage.cost` value, including zero, takes precedence
+over a catalog estimate. The decision retains both values and never adds the
+separately reported upstream inference cost to the OpenRouter account charge.
+Unsupported or malformed evidence falls back to the catalog result.
+
+The billing module validates only gateway, endpoint, fixed source names, and
+decimal cost values. It does not inspect provider response content or own SDK
+capture, HTTP, timestamps, trace context, persistence, or tenant behavior.
+
 ## Public API
 
 ```python
 from metergraph_core import (
     Alias,
+    BillingDecision,
     CatalogError,
     CatalogSnapshot,
     CostResult,
+    GatewayBillingEvidence,
     LoadedCatalog,
     Price,
     ResolvedPrice,
     load_catalog,
+    normalize_gateway_evidence,
     parse_catalog,
+    resolve_billing,
 )
 ```
 

{metergraph_core-0.1.4 → metergraph_core-0.2.0}/src/metergraph_core.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ MANIFEST.in
 README.md
 pyproject.toml
 src/metergraph_core/__init__.py
+src/metergraph_core/billing.py
 src/metergraph_core/catalog.py
 src/metergraph_core/loader.py
 src/metergraph_core.egg-info/PKG-INFO