metergraph-core 0.2.27__tar.gz → 0.2.30__tar.gz

{metergraph_core-0.2.27/src/metergraph_core.egg-info → metergraph_core-0.2.30}/PKG-INFO

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

{metergraph_core-0.2.27 → metergraph_core-0.2.30}/pyproject.toml

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

{metergraph_core-0.2.27 → metergraph_core-0.2.30}/src/metergraph_core/billing.py

@@ -6,11 +6,49 @@ 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 _QualifiedSource:
+    """A gateway whose reported amount this module will bill from.
+
+    Three things have to line up before an amount is believed, because the field
+    carrying one is open: a customer's own client can write to it.
+
+    * The **gateway**, so an amount is attributed to a system we have checked.
+    * The **endpoint**, because a gateway prices its endpoints differently and a
+      figure is only interpretable alongside the one that produced it.
+    * The **source**, naming the field the amount was read from, so a row cannot
+      qualify by claiming a gateway name alone.
+
+    A gateway absent from this table is not distrusted so much as unverified:
+    its amount is still recorded, and the catalog still prices the call, so the
+    two can be compared before it is added here.
+    """
+
+    gateway: str
+    endpoints: frozenset[str]
+    cost_source: str
+    upstream_cost_source: str | None = None
+
+
+# Each entry reconciles against the providers' own published rates, including
+# the per-request and per-query charges a token rate cannot express. Portkey was
+# checked across a 46,241-call export: its figure matches published rates for
+# Anthropic, xAI and Perplexity to the cent, and for OpenAI once the per-search
+# charge is counted -- 20,590 of 20,590 rows, exactly.
+_QUALIFIED_SOURCES = (
+    _QualifiedSource(
+        gateway="openrouter",
+        endpoints=frozenset({"chat.completions"}),
+        cost_source="openrouter.usage.cost",
+        upstream_cost_source=(
+            "openrouter.usage.cost_details.upstream_inference_cost"
+        ),
+    ),
+    _QualifiedSource(
+        gateway="portkey",
+        endpoints=frozenset({"chat.completions", "responses"}),
+        cost_source="portkey.cost",
+    ),
 )
 
 
@@ -82,11 +120,12 @@ def normalize_gateway_evidence(row: Mapping[str, Any]) -> GatewayBillingEvidence
     )
 
 
-def _is_openrouter_chat_completions(evidence: GatewayBillingEvidence) -> bool:
-    return (
-        evidence.gateway == _OPENROUTER
-        and evidence.endpoint == _CHAT_COMPLETIONS
-    )
+def _qualified_source(evidence: GatewayBillingEvidence) -> _QualifiedSource | None:
+    """The entry this row's gateway and endpoint match, if any."""
+    for source in _QUALIFIED_SOURCES:
+        if evidence.gateway == source.gateway and evidence.endpoint in source.endpoints:
+            return source
+    return None
 
 
 def resolve_billing(
@@ -95,18 +134,18 @@ def resolve_billing(
 ) -> BillingDecision:
     """Select effective cost without combining independent reported amounts."""
 
-    qualified_openrouter = _is_openrouter_chat_completions(evidence)
+    qualified = _qualified_source(evidence)
     reported_cost = (
         evidence.reported_cost_usd
-        if qualified_openrouter
-        and evidence.reported_cost_source == _OPENROUTER_COST_SOURCE
+        if qualified is not None
+        and evidence.reported_cost_source == qualified.cost_source
         else None
     )
     upstream_cost = (
         evidence.reported_upstream_cost_usd
-        if qualified_openrouter
-        and evidence.reported_upstream_cost_source
-        == _OPENROUTER_UPSTREAM_COST_SOURCE
+        if qualified is not None
+        and qualified.upstream_cost_source is not None
+        and evidence.reported_upstream_cost_source == qualified.upstream_cost_source
         else None
     )
 

{metergraph_core-0.2.27 → metergraph_core-0.2.30}/src/metergraph_core/catalog.py

@@ -196,10 +196,76 @@ def _tokens(value: Any) -> int | None:
     return result if result >= 0 else None
 
 
+def _off_peak_multiplier(rules: Mapping[str, Any], at: datetime) -> Decimal:
+    """The discount a provider applies outside its published peak hours.
+
+    A row states the peak rate, which is the provider's list price, and the
+    window it applies in. A call outside that window is scaled by
+    ``multiplier``; a row with no window is time-independent.
+    """
+    discount = rules.get("off_peak_discount") or {}
+    windows = discount.get("peak_hours_utc") or ()
+    multiplier = _decimal(discount.get("multiplier"))
+    if not windows or multiplier is None:
+        return Decimal("1")
+    moment = at.astimezone(timezone.utc)
+    if discount.get("peak_weekdays_only") and moment.weekday() >= 5:
+        return multiplier
+    for window in windows:
+        try:
+            start, end = window
+        except (TypeError, ValueError):
+            continue
+        if _tokens(start) is None or _tokens(end) is None:
+            continue
+        if int(start) <= moment.hour < int(end):
+            return Decimal("1")
+    return multiplier
+
+# A count that was never given and a count that was given but cannot be read are
+# different facts with opposite billing consequences for cached tokens: absent
+# means there was no cache to discount, unusable means we do not know. `_tokens`
+# answers both with None, which is right for a count a caller may legitimately
+# omit and wrong for one it supplied.
+_UNUSABLE = object()
+
+
+def _token_count(value: Any) -> Any:
+    """A usable token count, ``None`` when none was given, or ``_UNUSABLE`` when
+    one was given that cannot be read as a count."""
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return _UNUSABLE
+    try:
+        result = int(value)
+    except (ValueError, TypeError, OverflowError):
+        return _UNUSABLE
+    return result if result >= 0 else _UNUSABLE
+
+
+def _cached_count(value: Any, name: str, reasons: list[str]) -> int | None:
+    """The count to bill for one cached-token field, recording why when the
+    value supplied cannot be used.
+
+    Returns ``None`` only when nothing was given, so a caller that omits a field
+    keeps the behaviour it had. An unusable value bills as nothing cached, which
+    is the same arithmetic as before, but it now says so: the reason turns the
+    result ``partial``, and a caller that trusts only a fully priced figure stops
+    reading a silent over-bill as a price.
+    """
+    count = _token_count(value)
+    if count is _UNUSABLE:
+        reasons.append(f"unusable_{name}")
+        return 0
+    return count
+
+
 def _price_tokens(
     price: Price,
     rules: Mapping[str, Any],
     *,
+    at: datetime,
     input_tokens: Any,
     output_tokens: Any,
     cache_read_tokens: Any,
@@ -214,11 +280,19 @@ def _price_tokens(
     reasons: list[str] = []
     input_count = _tokens(input_tokens)
     output_count = _tokens(output_tokens)
-    cache_read_count = _tokens(cache_read_tokens) or 0
-    cache_write_5m_count = _tokens(cache_write_5m_tokens)
+    cache_read_count = _cached_count(cache_read_tokens, "cache_read_tokens", reasons) or 0
+    cache_write_5m_count = _cached_count(
+        cache_write_5m_tokens, "cache_write_5m_tokens", reasons
+    )
     if cache_write_5m_count is None:
-        cache_write_5m_count = _tokens(cache_write_tokens) or 0
-    cache_write_1h_count = _tokens(cache_write_1h_tokens) or 0
+        # Only an absent split falls back to the aggregate. A stated split we
+        # cannot read is not an invitation to substitute a different field.
+        cache_write_5m_count = (
+            _cached_count(cache_write_tokens, "cache_write_tokens", reasons) or 0
+        )
+    cache_write_1h_count = (
+        _cached_count(cache_write_1h_tokens, "cache_write_1h_tokens", reasons) or 0
+    )
     cache_write_count = cache_write_5m_count + cache_write_1h_count
     if input_count is None:
         reasons.append("missing_input_tokens")
@@ -261,6 +335,11 @@ def _price_tokens(
         output_multiplier = _decimal(
             long_context.get("output_multiplier")
         ) or Decimal("1")
+    # Applies to every rate on the row, cache included, and composes with a
+    # long-context tier rather than replacing it.
+    off_peak = _off_peak_multiplier(rules, at)
+    input_multiplier *= off_peak
+    output_multiplier *= off_peak
 
     cost = Decimal("0")
     if input_rate is None:
@@ -439,6 +518,7 @@ class CatalogSnapshot:
         cost, reasons = _price_tokens(
             price,
             {**price.rules, **alias.rules},
+            at=_coerce_datetime(at),
             input_tokens=input_tokens,
             output_tokens=output_tokens,
             cache_read_tokens=cache_read_tokens,
@@ -486,6 +566,7 @@ class CatalogSnapshot:
         cost, reasons = _price_tokens(
             resolved.price,
             resolved.rules,
+            at=when,
             input_tokens=input_tokens,
             output_tokens=output_tokens,
             cache_read_tokens=cache_read_tokens,

{metergraph_core-0.2.27 → metergraph_core-0.2.30}/src/metergraph_core/data/prices.yaml

@@ -1235,12 +1235,28 @@ models:
       - channel: deepseek-api
         region: global
         effective_from: "2026-04-24"
+        effective_to: "2026-09-10T04:00:00+00:00"
         input_per_mtok: 0.14
         output_per_mtok: 0.28
         cache_read_per_mtok: 0.0028
         rules:
           input_includes_cache_read: true
         source_url: https://api-docs.deepseek.com/quick_start/pricing/
+      # This name is retired but still accepted, and billed at the Flash rate.
+      - channel: deepseek-api
+        region: global
+        effective_from: "2026-09-10T04:00:00+00:00"
+        input_per_mtok: 0.30
+        output_per_mtok: 1.20
+        cache_read_per_mtok: 0.006
+        rules:
+          input_includes_cache_read: true
+          # Peak rate; halved outside the window. Footnote (3) on the source.
+          off_peak_discount:
+            multiplier: 0.5
+            peak_hours_utc: [[1, 4], [6, 10]]
+            peak_weekdays_only: true
+        source_url: https://api-docs.deepseek.com/quick_start/pricing/
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2026-04-24"
@@ -1274,12 +1290,27 @@ models:
       - channel: deepseek-api
         region: global
         effective_from: "2026-04-24"
+        effective_to: "2026-09-10T04:00:00+00:00"
         input_per_mtok: 0.435
         output_per_mtok: 0.87
         cache_read_per_mtok: 0.003625
         rules:
           input_includes_cache_read: true
         source_url: https://api-docs.deepseek.com/quick_start/pricing/
+      - channel: deepseek-api
+        region: global
+        effective_from: "2026-09-10T04:00:00+00:00"
+        input_per_mtok: 1.32
+        output_per_mtok: 3.96
+        cache_read_per_mtok: 0.044
+        rules:
+          input_includes_cache_read: true
+          # Peak rate; halved outside the window. Footnote (3) on the source.
+          off_peak_discount:
+            multiplier: 0.5
+            peak_hours_utc: [[1, 4], [6, 10]]
+            peak_weekdays_only: true
+        source_url: https://api-docs.deepseek.com/quick_start/pricing/
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2026-04-24"
@@ -1581,11 +1612,28 @@ models:
   - canonical_id: deepseek/deepseek-v4.1-flash
     publisher: deepseek
     aliases:
+      - {provider: deepseek, alias: deepseek-flash, channel: deepseek-api}
+      - {provider: litellm, alias: deepseek-flash, channel: deepseek-api}
+      - {provider: unknown, alias: deepseek-flash, channel: deepseek-api}
       - provider: deepseek
         alias: deepseek/deepseek-v4.1-flash
         channel: vercel-ai-gateway
         rules: {input_includes_cache_read: true}
     prices:
+      - channel: deepseek-api
+        region: global
+        effective_from: "2026-09-10T04:00:00+00:00"
+        input_per_mtok: 0.30
+        output_per_mtok: 1.20
+        cache_read_per_mtok: 0.006
+        rules:
+          input_includes_cache_read: true
+          # Peak rate; halved outside the window. Footnote (3) on the source.
+          off_peak_discount:
+            multiplier: 0.5
+            peak_hours_utc: [[1, 4], [6, 10]]
+            peak_weekdays_only: true
+        source_url: https://api-docs.deepseek.com/quick_start/pricing/
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2026-09-08"

{metergraph_core-0.2.27 → metergraph_core-0.2.30/src/metergraph_core.egg-info}/PKG-INFO

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