metergraph-core 0.6.1__tar.gz → 0.7.0__tar.gz

{metergraph_core-0.6.1/src/metergraph_core.egg-info → metergraph_core-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph-core
-Version: 0.6.1
+Version: 0.7.0
 Summary: Open, effective-dated LLM pricing catalog and deterministic cost calculator for popular models across major providers and gateways, including OpenAI, Anthropic, Google Gemini, AWS Bedrock, OpenRouter, Vercel AI Gateway, and more.
 Author: Metergraph
 License-Expression: Apache-2.0
@@ -200,6 +200,52 @@ A call after it ended resolves to that price, stays `priced`, and carries
 applied `price.effective_to` says when it ended. A closed price followed by a
 later one never extends, so a gap before a scheduled price stays `unpriced`.
 
+### Costing a provider response
+
+`cost_from_response` reads the usage out of a response you already have and
+costs it, so you do not extract token counts yourself:
+
+```python
+from openai import OpenAI
+from metergraph_core import cost_from_response
+
+response = OpenAI().chat.completions.create(model="gpt-5.4-mini", messages=messages)
+result = cost_from_response("openai", response)
+print(result.status, result.model_id, result.cost, result.currency)
+```
+
+It accepts the object a provider SDK returned or the same response as JSON:
+
+| Provider API | Example `provider` |
+|---|---|
+| OpenAI Chat Completions, and gateways that return its shape | `openai`, `openrouter`, `deepseek` |
+| OpenAI Responses | `openai` |
+| Anthropic Messages | `anthropic` |
+| Google Gemini `generateContent` | `google` |
+| Bedrock Converse (pass `model=`, the response does not name one) | `bedrock` |
+
+`provider` names who served the call and selects its direct channel unless
+`channel` is given. The response shape is detected from its fields. Only the
+model, usage counts, service tier and creation time are read; prompt and
+output content never are.
+
+Cached tokens are billed once whichever convention the response uses. OpenAI
+and Gemini count cached tokens inside the input total, so the total is
+restated in the convention of the price row that bills it, including a
+gateway row for another publisher's model. Gemini thinking tokens bill as
+output.
+
+The price in effect when the response was created applies, from `created`,
+`created_at` or `createTime`; `at=` overrides it, and a response with no
+creation time is priced now. `catalog=` costs against a catalog you loaded;
+the default is the bundled one.
+
+A batch service tier bills at batch rates. Any other tier besides standard,
+such as `priority` or `flex`, returns `partial` with `service_tier` in
+`missing_dimensions`, since the catalog carries no tier rates. Cost a streamed
+call from its final response or final usage chunk. Fees outside token usage,
+such as web search, are not included.
+
 ## Model registry
 
 ```python
@@ -466,6 +512,7 @@ from metergraph_core import (
     ResolvedPrice,
     SourceRegistry,
     apply_catalog_delta,
+    cost_from_response,
     discovery_evidence,
     extract,
     load_catalog,

{metergraph_core-0.6.1 → metergraph_core-0.7.0}/README.md

@@ -170,6 +170,52 @@ A call after it ended resolves to that price, stays `priced`, and carries
 applied `price.effective_to` says when it ended. A closed price followed by a
 later one never extends, so a gap before a scheduled price stays `unpriced`.
 
+### Costing a provider response
+
+`cost_from_response` reads the usage out of a response you already have and
+costs it, so you do not extract token counts yourself:
+
+```python
+from openai import OpenAI
+from metergraph_core import cost_from_response
+
+response = OpenAI().chat.completions.create(model="gpt-5.4-mini", messages=messages)
+result = cost_from_response("openai", response)
+print(result.status, result.model_id, result.cost, result.currency)
+```
+
+It accepts the object a provider SDK returned or the same response as JSON:
+
+| Provider API | Example `provider` |
+|---|---|
+| OpenAI Chat Completions, and gateways that return its shape | `openai`, `openrouter`, `deepseek` |
+| OpenAI Responses | `openai` |
+| Anthropic Messages | `anthropic` |
+| Google Gemini `generateContent` | `google` |
+| Bedrock Converse (pass `model=`, the response does not name one) | `bedrock` |
+
+`provider` names who served the call and selects its direct channel unless
+`channel` is given. The response shape is detected from its fields. Only the
+model, usage counts, service tier and creation time are read; prompt and
+output content never are.
+
+Cached tokens are billed once whichever convention the response uses. OpenAI
+and Gemini count cached tokens inside the input total, so the total is
+restated in the convention of the price row that bills it, including a
+gateway row for another publisher's model. Gemini thinking tokens bill as
+output.
+
+The price in effect when the response was created applies, from `created`,
+`created_at` or `createTime`; `at=` overrides it, and a response with no
+creation time is priced now. `catalog=` costs against a catalog you loaded;
+the default is the bundled one.
+
+A batch service tier bills at batch rates. Any other tier besides standard,
+such as `priority` or `flex`, returns `partial` with `service_tier` in
+`missing_dimensions`, since the catalog carries no tier rates. Cost a streamed
+call from its final response or final usage chunk. Fees outside token usage,
+such as web search, are not included.
+
 ## Model registry
 
 ```python
@@ -436,6 +482,7 @@ from metergraph_core import (
     ResolvedPrice,
     SourceRegistry,
     apply_catalog_delta,
+    cost_from_response,
     discovery_evidence,
     extract,
     load_catalog,

{metergraph_core-0.6.1 → metergraph_core-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metergraph-core"
-version = "0.6.1"
+version = "0.7.0"
 description = "Open, effective-dated LLM pricing catalog and deterministic cost calculator for popular models across major providers and gateways, including OpenAI, Anthropic, Google Gemini, AWS Bedrock, OpenRouter, Vercel AI Gateway, and more."
 readme = "README.md"
 license = "Apache-2.0"

{metergraph_core-0.6.1 → metergraph_core-0.7.0}/src/metergraph_core/__init__.py

@@ -59,6 +59,7 @@ from .catalog_delta import (
     apply_catalog_delta,
     parse_catalog_delta,
 )
+from .responses import cost_from_response
 from .extractors import (
     ExtractedRate,
     Extraction,
@@ -133,6 +134,7 @@ __all__ = [
     "RetrievalPrice",
     "count_fetch_units",
     "count_search_units",
+    "cost_from_response",
     "counts_cache_read_in_input",
     "direct_channel_for_provider",
     "normalize_provider",

{metergraph_core-0.6.1 → metergraph_core-0.7.0}/src/metergraph_core/catalog.py

@@ -522,7 +522,9 @@ def _price_tokens(
             prompt_count += cache_read_count
         if not rules.get("input_includes_cache_write"):
             prompt_count += cache_write_count
-    if threshold is not None and prompt_count > threshold:
+    # Some providers publish no long-context batch rate, so batch stays flat.
+    applies = not batch or long_context.get("applies_to_batch", True)
+    if applies and threshold is not None and prompt_count > threshold:
         input_multiplier = _decimal(long_context.get("input_multiplier")) or Decimal("1")
         output_multiplier = _decimal(
             long_context.get("output_multiplier")

{metergraph_core-0.6.1 → metergraph_core-0.7.0}/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-10-21"
+version: "2026-10-23"
 currency: USD
-pricing_verified_at: "2026-10-21"
+pricing_verified_at: "2026-10-23"
 models:
   - canonical_id: openai/gpt-6-sol
     publisher: openai
@@ -1824,9 +1824,12 @@ models:
       - {provider: google, alias: gemini-2.5-flash-image, channel: google-api}
       - {provider: google, alias: models/gemini-2.5-flash-image, channel: google-api}
     prices:
+      # Google shut this model down on 2026-10-02 and now states its output
+      # price per image, which no token rate can express.
       - channel: google-api
         region: global
         effective_from: "2025-10-02"
+        effective_to: "2026-10-02"
         input_per_mtok: 0.30
         output_per_mtok: 30.00
         source_url: https://ai.google.dev/gemini-api/docs/pricing
@@ -2497,6 +2500,7 @@ models:
       - channel: perplexity-api
         region: global
         effective_from: "2025-04-18"
+        effective_to: "2026-10-23"
         input_per_mtok: 1.00
         output_per_mtok: 1.00
         rules:
@@ -2729,6 +2733,9 @@ models:
         cache_read_per_mtok: 0.075
         source_url: https://ai-gateway.vercel.sh/v1/models
 
+      # The pricing page stopped listing this name when Google deprecated it on
+      # 2026-10-08 and began routing it to gemini-3.8-flash, whose rates these
+      # rows already match.
       - channel: google-api
         region: global
         effective_from: "2026-08-13"
@@ -3654,6 +3661,15 @@ models:
         rules:
           long_context: {threshold: 200000, input_multiplier: 2.0, output_multiplier: 2.0}
         source_url: https://docs.x.ai/developers/release-notes
+      - channel: xai-api
+        region: us
+        effective_from: "2026-08-12"
+        input_per_mtok: 2.2
+        output_per_mtok: 6.6
+        cache_read_per_mtok: 0.55
+        rules:
+          long_context: {threshold: 200000, input_multiplier: 2.0, output_multiplier: 2.0}
+        source_url: https://docs.x.ai/developers/advanced-api-usage/regions
   - canonical_id: xai/grok-4.7
     publisher: xai
     aliases:
@@ -4015,13 +4031,30 @@ models:
       - {provider: google, alias: gemini-omni-flash-preview, channel: google-api}
       - {provider: google, alias: models/gemini-omni-flash-preview, channel: google-api}
     prices:
+      # Google shuts this preview endpoint down on 2026-10-22; its traffic moves
+      # to google/gemini-omni-1.1-flash.
       - channel: google-api
         region: global
         effective_from: "2026-05-19"
+        effective_to: "2026-10-22"
         input_per_mtok: 1.50
         output_per_mtok: 9.00
         source_url: https://ai.google.dev/gemini-api/docs/pricing
 
+  - canonical_id: google/gemini-omni-1.1-flash
+    publisher: google
+    aliases:
+      - {provider: google, alias: gemini-omni-1.1-flash, channel: google-api}
+      - {provider: google, alias: models/gemini-omni-1.1-flash, channel: google-api}
+    prices:
+      # Uses the video output rate: video is this model's only output modality.
+      - channel: google-api
+        region: global
+        effective_from: "2026-08-27"
+        input_per_mtok: 1.50
+        output_per_mtok: 17.50
+        source_url: https://ai.google.dev/gemini-api/docs/pricing
+
 # 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
@@ -4618,9 +4651,12 @@ models:
       - {provider: litellm, alias: claude-opus-5-fast, channel: anthropic-api}
       - {provider: unknown, alias: claude-opus-5-fast, channel: anthropic-api}
     prices:
+      # Anthropic's own pricing and model-lifecycle pages name no
+      # claude-opus-5-fast, so only the gateway offering continues.
       - channel: anthropic-api
         region: global
         effective_from: "2026-07-24"
+        effective_to: "2026-10-22"
         input_per_mtok: 10
         output_per_mtok: 50
         source_url: https://ai-gateway.vercel.sh/v1/models
@@ -4921,7 +4957,9 @@ models:
         output_per_mtok: 180
         batch_input_per_mtok: 15
         batch_output_per_mtok: 90
-        source_url: https://ai-gateway.vercel.sh/v1/models
+        rules:
+          long_context: {threshold: 272000, input_multiplier: 2, output_multiplier: 1.5}
+        source_url: https://developers.openai.com/api/docs/models/gpt-5.4-pro
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2026-10-02"
@@ -4951,7 +4989,9 @@ models:
         cache_read_per_mtok: 0.5
         batch_input_per_mtok: 2.5
         batch_output_per_mtok: 15
-        source_url: https://ai-gateway.vercel.sh/v1/models
+        rules:
+          long_context: {threshold: 272000, input_multiplier: 2, output_multiplier: 1.5}
+        source_url: https://developers.openai.com/api/docs/models/gpt-5.5
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2026-04-24"
@@ -4983,6 +5023,7 @@ models:
       - {provider: unknown, alias: gpt-5.5-pro, channel: openai-api}
       - {provider: unknown, alias: gpt-5.5-pro-2026-04-23, channel: openai-api}
     prices:
+      # OpenAI lists no long-context batch rate, so batch stays flat.
       - channel: openai-api
         region: global
         effective_from: "2026-04-24"
@@ -4990,7 +5031,9 @@ models:
         output_per_mtok: 180
         batch_input_per_mtok: 15
         batch_output_per_mtok: 90
-        source_url: https://ai-gateway.vercel.sh/v1/models
+        rules:
+          long_context: {threshold: 272000, input_multiplier: 2, output_multiplier: 1.5, applies_to_batch: false}
+        source_url: https://developers.openai.com/api/docs/pricing
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2026-04-24"
@@ -8026,22 +8069,40 @@ models:
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2026-10-20"
+        effective_to: "2026-10-21"
         input_per_mtok: 0.14
         output_per_mtok: 0.28
         cache_read_per_mtok: 0.0028
         rules:
           varies_by_provider: true
         source_url: https://ai-gateway.vercel.sh/v1/models
+      - channel: vercel-ai-gateway
+        region: global
+        effective_from: "2026-10-21"
+        input_per_mtok: 0.119
+        output_per_mtok: 0.238
+        cache_read_per_mtok: 0.0025
+        source_url: https://ai-gateway.vercel.sh/v1/models
 
       - channel: openrouter-api
         region: global
         effective_from: "2026-10-20"
+        effective_to: "2026-10-21"
         input_per_mtok: 0.14
         output_per_mtok: 0.28
         cache_read_per_mtok: 0.0028
         rules:
           varies_by_provider: true
         source_url: https://openrouter.ai/api/v1/models
+      - channel: openrouter-api
+        region: global
+        effective_from: "2026-10-21"
+        input_per_mtok: 0.119
+        output_per_mtok: 0.238
+        cache_read_per_mtok: 0.00255
+        rules:
+          varies_by_provider: true
+        source_url: https://openrouter.ai/api/v1/models
   - canonical_id: xiaomi/mimo-v2.5-pro
     publisher: xiaomi
     aliases:
@@ -11014,15 +11075,15 @@ retrieval:
     per_1k_usd: 14.00
     effective_from: "2026-01-05"
     source_url: https://cloud.google.com/gemini-enterprise-agent-platform/generative-ai/pricing
-  # Sonar charges a request fee on top of tokens, by search context size;
-  # low is the default. The sonar token row keeps `uncaptured_fees` until
-  # callers price requests alongside tokens.
+  # Historical Sonar request fees end before the new API-specific rates.
+  # The current Sonar fee is unverified, so its token row stays partial.
   - channel: perplexity-api
     operation: search_request_low
     region: global
     unit: request
     per_1k_usd: 5.00
     effective_from: "2025-04-18"
+    effective_to: "2026-10-23"
     source_url: https://docs.perplexity.ai/docs/getting-started/pricing
   - channel: perplexity-api
     operation: search_request_medium
@@ -11030,6 +11091,7 @@ retrieval:
     unit: request
     per_1k_usd: 8.00
     effective_from: "2025-04-18"
+    effective_to: "2026-10-23"
     source_url: https://docs.perplexity.ai/docs/getting-started/pricing
   - channel: perplexity-api
     operation: search_request_high
@@ -11037,6 +11099,7 @@ retrieval:
     unit: request
     per_1k_usd: 12.00
     effective_from: "2025-04-18"
+    effective_to: "2026-10-23"
     source_url: https://docs.perplexity.ai/docs/getting-started/pricing
 
 # Gateways whose reported amount billing declines for one publisher's models

{metergraph_core-0.6.1 → metergraph_core-0.7.0}/src/metergraph_core/extractors.py

@@ -247,7 +247,8 @@ def parse_deepseek(html_text: str, *, duplicates: list[str] | None = None) -> Ta
     section = ""
     for rows_ in page_tables(html_text):
         for cells in rows_:
-            if cells and cells[0].upper().startswith("MODEL") and len(cells) > 1:
+            # MODEL VERSION is data, not a header.
+            if cells and cells[0].strip().upper() == "MODEL" and len(cells) > 1:
                 columns = [deepseek_name(c) for c in cells[1:]]
                 for column in columns:
                     table[column] = {}

metergraph_core-0.7.0/src/metergraph_core/responses.py

@@ -0,0 +1,325 @@
+"""Cost a provider response object as the caller received it.
+
+Each reader copies only the fields a price depends on: model, usage counts,
+service tier and creation time. Prompt, output and every other field are never
+read, so nothing downstream sees content the response carried.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from datetime import datetime, timezone
+from functools import lru_cache
+from typing import Any, Callable, Mapping
+
+from .catalog import CostResult, ModelUsage
+from .loader import LoadedCatalog, load_catalog
+
+_STANDARD_TIERS = frozenset({"default", "standard", "standard_only", "auto", "on_demand"})
+_BATCH_TIER = "batch"
+
+
+@dataclass(frozen=True, slots=True)
+class _Facts:
+    model: str | None
+    usage: Mapping[str, int | None] = field(default_factory=dict)
+    # The input total already counts cached tokens, so it is restated in the
+    # convention of the price row that bills it.
+    input_includes_cache: bool = False
+    service_tier: str | None = None
+    at: datetime | None = None
+
+
+def _object(value: Any) -> Mapping[str, Any]:
+    return value if isinstance(value, Mapping) else {}
+
+
+def _text(value: Any) -> str | None:
+    if isinstance(value, str) and value.strip():
+        return value.strip()
+    return None
+
+
+def _count(value: Any) -> int | None:
+    """A token count, or None for anything that is not a whole number."""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float) and value.is_integer():
+        return int(value)
+    return None
+
+
+def _sum(*values: Any) -> int | None:
+    counts = [_count(value) for value in values]
+    if counts[0] is None:
+        return None
+    return sum(count or 0 for count in counts)
+
+
+def _first(mapping: Mapping[str, Any], *keys: str) -> Any:
+    """The first present key: SDK objects dump snake_case, REST JSON is
+    camelCase."""
+    for key in keys:
+        if mapping.get(key) is not None:
+            return mapping[key]
+    return None
+
+
+def _epoch(value: Any) -> datetime | None:
+    seconds = _count(value)
+    if seconds is None:
+        return None
+    try:
+        return datetime.fromtimestamp(seconds, timezone.utc)
+    except (OverflowError, OSError, ValueError):
+        return None
+
+
+def _iso(value: Any) -> datetime | None:
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=timezone.utc)
+    if not isinstance(value, str) or not value.strip():
+        return None
+    text = value.strip().replace("Z", "+00:00")
+    # Python 3.10 parses at most six fractional digits; Vertex sends nine.
+    head, dot, rest = text.partition(".")
+    if dot:
+        digits = len(rest) - len(rest.lstrip("0123456789"))
+        text = f"{head}.{rest[:min(digits, 6)]}{rest[digits:]}"
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+def _anthropic_messages(response: Mapping[str, Any]) -> _Facts:
+    usage = _object(response.get("usage"))
+    creation = _object(usage.get("cache_creation"))
+    return _Facts(
+        model=_text(response.get("model")),
+        usage={
+            "input_tokens": _count(usage.get("input_tokens")),
+            "output_tokens": _count(usage.get("output_tokens")),
+            "cache_read_tokens": _count(usage.get("cache_read_input_tokens")),
+            "cache_write_tokens": _count(usage.get("cache_creation_input_tokens")),
+            "cache_write_5m_tokens": _count(creation.get("ephemeral_5m_input_tokens")),
+            "cache_write_1h_tokens": _count(creation.get("ephemeral_1h_input_tokens")),
+        },
+        service_tier=_text(usage.get("service_tier")),
+    )
+
+
+def _openai_responses(response: Mapping[str, Any]) -> _Facts:
+    usage = _object(response.get("usage"))
+    details = _object(usage.get("input_tokens_details"))
+    return _Facts(
+        model=_text(response.get("model")),
+        usage={
+            "input_tokens": _count(usage.get("input_tokens")),
+            "output_tokens": _count(usage.get("output_tokens")),
+            "cache_read_tokens": _count(details.get("cached_tokens")),
+            # Gateways such as OpenRouter report cache writes beside reads.
+            "cache_write_tokens": _count(details.get("cache_write_tokens")),
+        },
+        input_includes_cache=True,
+        service_tier=_text(response.get("service_tier")),
+        at=_epoch(response.get("created_at")),
+    )
+
+
+def _openai_chat_completions(response: Mapping[str, Any]) -> _Facts:
+    usage = _object(response.get("usage"))
+    details = _object(usage.get("prompt_tokens_details"))
+    return _Facts(
+        model=_text(response.get("model")),
+        usage={
+            "input_tokens": _count(usage.get("prompt_tokens")),
+            "output_tokens": _count(usage.get("completion_tokens")),
+            "cache_read_tokens": _count(details.get("cached_tokens")),
+            "cache_write_tokens": _count(details.get("cache_write_tokens")),
+        },
+        # Gateways relaying another publisher's model keep this shape, with
+        # cached tokens inside the prompt total.
+        input_includes_cache=True,
+        service_tier=_text(response.get("service_tier")),
+        at=_epoch(response.get("created")),
+    )
+
+
+def _gemini(response: Mapping[str, Any]) -> _Facts:
+    usage = _object(_first(response, "usage_metadata", "usageMetadata"))
+    return _Facts(
+        model=_text(_first(response, "model_version", "modelVersion")),
+        usage={
+            # Tool-use prompt tokens bill as input; thinking tokens bill as
+            # output but are reported outside the candidates count.
+            "input_tokens": _sum(
+                _first(usage, "prompt_token_count", "promptTokenCount"),
+                _first(usage, "tool_use_prompt_token_count", "toolUsePromptTokenCount"),
+            ),
+            "output_tokens": _sum(
+                _first(usage, "candidates_token_count", "candidatesTokenCount"),
+                _first(usage, "thoughts_token_count", "thoughtsTokenCount"),
+            ),
+            "cache_read_tokens": _count(
+                _first(usage, "cached_content_token_count", "cachedContentTokenCount")
+            ),
+        },
+        input_includes_cache=True,
+        at=_iso(_first(response, "create_time", "createTime")),
+    )
+
+
+def _bedrock_converse(response: Mapping[str, Any]) -> _Facts:
+    usage = _object(response.get("usage"))
+    return _Facts(
+        # Converse responses do not name the model; the caller supplies it.
+        model=None,
+        usage={
+            "input_tokens": _count(usage.get("inputTokens")),
+            "output_tokens": _count(usage.get("outputTokens")),
+            "cache_read_tokens": _count(usage.get("cacheReadInputTokens")),
+            "cache_write_tokens": _count(usage.get("cacheWriteInputTokens")),
+        },
+        service_tier=_text(_object(response.get("serviceTier")).get("type")),
+    )
+
+
+def _reader(response: Mapping[str, Any]) -> Callable[[Mapping[str, Any]], _Facts] | None:
+    """The reader for this response's shape, told apart by the fields each
+    API always returns."""
+    if _first(response, "usage_metadata", "usageMetadata") is not None:
+        return _gemini
+    usage = _object(response.get("usage"))
+    if "prompt_tokens" in usage:
+        return _openai_chat_completions
+    if "inputTokens" in usage:
+        return _bedrock_converse
+    if response.get("type") == "message" or "cache_read_input_tokens" in usage:
+        return _anthropic_messages
+    if response.get("object") == "response" or "input_tokens_details" in usage:
+        return _openai_responses
+    return None
+
+
+def _as_mapping(response: Any) -> Mapping[str, Any]:
+    if isinstance(response, Mapping):
+        return response
+    dump = getattr(response, "model_dump", None)
+    if callable(dump):
+        # OpenAI, Anthropic and Google GenAI SDK objects are pydantic models.
+        return dump()
+    to_dict = getattr(response, "to_dict", None)
+    if callable(to_dict):
+        return to_dict()
+    raise TypeError(
+        "response must be a mapping or a provider SDK response object, "
+        f"not {type(response).__name__}"
+    )
+
+
+@lru_cache(maxsize=1)
+def _bundled_catalog() -> LoadedCatalog:
+    return load_catalog(region="global")
+
+
+def _native_input_tokens(
+    usage: Mapping[str, int | None], probe: Callable[..., CostResult]
+) -> int | None:
+    """An input total that includes cache reads and writes, restated in the
+    convention the priced row uses.
+
+    The row records whether its input total already counts cached tokens
+    (OpenAI's includes reads, Anthropic's includes neither). A response whose
+    total includes them, priced on a row that does not deduct them, would
+    otherwise bill every cached token twice. ``probe`` costs a usage on the
+    same model and channel.
+    """
+    total = usage.get("input_tokens")
+    cache_read = usage.get("cache_read_tokens") or 0
+    cache_write = usage.get("cache_write_tokens") or 0
+    if total is None or cache_read < 0 or cache_write < 0 or not (cache_read or cache_write):
+        return total
+    # Cached tokens exceeding the total cannot have been included in it.
+    uncached = (
+        total - cache_read - cache_write
+        if cache_read + cache_write <= total
+        else total
+    )
+    # A zero-input probe reports which cached counts the row deducts from input.
+    reasons = probe(
+        input_tokens=0, output_tokens=0, cache_read_tokens=1, cache_write_tokens=1
+    ).reasons
+    native = uncached
+    if "cache_read_exceeds_input" in reasons:
+        native += cache_read
+    if "cache_write_exceeds_input" in reasons:
+        native += cache_write
+    return native
+
+
+def cost_from_response(
+    provider: str,
+    response: Any,
+    *,
+    catalog: LoadedCatalog | None = None,
+    model: str | None = None,
+    at: Any = None,
+    channel: str | None = None,
+    region: str | None = None,
+) -> CostResult:
+    """The cost of one provider response, from the usage it reports.
+
+    ``response`` is the object the provider SDK returned, or its JSON as a
+    mapping: OpenAI Chat Completions or Responses, Anthropic Messages, Google
+    Gemini ``generateContent``, or Bedrock Converse. ``provider`` names who
+    served the call and selects its direct pricing channel unless ``channel``
+    is given. ``model`` overrides the response's model id and is required for
+    Bedrock Converse, whose responses do not name one. ``at`` defaults to the
+    response's creation time when it reports one, else now. ``catalog``
+    defaults to the catalog bundled with this package.
+
+    A streamed call is costed from its final response or final usage chunk.
+    Fees outside token usage, such as web search, are not included. A service
+    tier other than standard or batch turns the result ``partial`` with
+    ``service_tier`` missing, since the catalog does not carry tier rates.
+    """
+    data = _as_mapping(response)
+    reader = _reader(data)
+    if reader is None:
+        raise ValueError("response carries no usage this function can read")
+    facts = reader(data)
+    when = at if at is not None else facts.at or datetime.now(timezone.utc)
+    model_id = _text(model) or facts.model
+    tier = (facts.service_tier or "").lower() or None
+    if model_id is None:
+        return CostResult(
+            None, None, None, "unpriced", ("missing_model",), missing_dimensions=("model",)
+        )
+    loaded = catalog if catalog is not None else _bundled_catalog()
+    batch = tier == _BATCH_TIER
+
+    def cost(**usage: Any) -> CostResult:
+        return loaded.calculate_cost(
+            model=model_id,
+            usage=ModelUsage(**usage, batch=batch),
+            at=when,
+            channel=channel,
+            provider=provider,
+            region=region,
+        )
+
+    usage = dict(facts.usage)
+    if facts.input_includes_cache:
+        usage["input_tokens"] = _native_input_tokens(usage, cost)
+    result = cost(**usage)
+    if tier is None or tier in _STANDARD_TIERS or batch or result.status == "unpriced":
+        return result
+    return replace(
+        result,
+        status="partial",
+        missing_dimensions=tuple(dict.fromkeys((*result.missing_dimensions, "service_tier"))),
+    )

{metergraph_core-0.6.1 → metergraph_core-0.7.0}/src/metergraph_core/retrieval.py

@@ -61,8 +61,8 @@ SEARCH_OPERATION_BY_CHANNEL: Mapping[str, str] = MappingProxyType({
     "anthropic-api": "web_search",
     "google-api": "google_search_grounding",
     "google-vertex-ai": "google_search_grounding",
-    # Perplexity bills a request fee by search context size, which no
-    # capture path records; the low tier is the floor every request pays.
+    # Historical Sonar request fees use this operation; no current fee is
+    # assigned until its API and billing unit can be verified.
     "perplexity-api": "search_request_low",
 })
 FETCH_OPERATION_BY_CHANNEL: Mapping[str, str] = MappingProxyType({

{metergraph_core-0.6.1 → metergraph_core-0.7.0/src/metergraph_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph-core
-Version: 0.6.1
+Version: 0.7.0
 Summary: Open, effective-dated LLM pricing catalog and deterministic cost calculator for popular models across major providers and gateways, including OpenAI, Anthropic, Google Gemini, AWS Bedrock, OpenRouter, Vercel AI Gateway, and more.
 Author: Metergraph
 License-Expression: Apache-2.0
@@ -200,6 +200,52 @@ A call after it ended resolves to that price, stays `priced`, and carries
 applied `price.effective_to` says when it ended. A closed price followed by a
 later one never extends, so a gap before a scheduled price stays `unpriced`.
 
+### Costing a provider response
+
+`cost_from_response` reads the usage out of a response you already have and
+costs it, so you do not extract token counts yourself:
+
+```python
+from openai import OpenAI
+from metergraph_core import cost_from_response
+
+response = OpenAI().chat.completions.create(model="gpt-5.4-mini", messages=messages)
+result = cost_from_response("openai", response)
+print(result.status, result.model_id, result.cost, result.currency)
+```
+
+It accepts the object a provider SDK returned or the same response as JSON:
+
+| Provider API | Example `provider` |
+|---|---|
+| OpenAI Chat Completions, and gateways that return its shape | `openai`, `openrouter`, `deepseek` |
+| OpenAI Responses | `openai` |
+| Anthropic Messages | `anthropic` |
+| Google Gemini `generateContent` | `google` |
+| Bedrock Converse (pass `model=`, the response does not name one) | `bedrock` |
+
+`provider` names who served the call and selects its direct channel unless
+`channel` is given. The response shape is detected from its fields. Only the
+model, usage counts, service tier and creation time are read; prompt and
+output content never are.
+
+Cached tokens are billed once whichever convention the response uses. OpenAI
+and Gemini count cached tokens inside the input total, so the total is
+restated in the convention of the price row that bills it, including a
+gateway row for another publisher's model. Gemini thinking tokens bill as
+output.
+
+The price in effect when the response was created applies, from `created`,
+`created_at` or `createTime`; `at=` overrides it, and a response with no
+creation time is priced now. `catalog=` costs against a catalog you loaded;
+the default is the bundled one.
+
+A batch service tier bills at batch rates. Any other tier besides standard,
+such as `priority` or `flex`, returns `partial` with `service_tier` in
+`missing_dimensions`, since the catalog carries no tier rates. Cost a streamed
+call from its final response or final usage chunk. Fees outside token usage,
+such as web search, are not included.
+
 ## Model registry
 
 ```python
@@ -466,6 +512,7 @@ from metergraph_core import (
     ResolvedPrice,
     SourceRegistry,
     apply_catalog_delta,
+    cost_from_response,
     discovery_evidence,
     extract,
     load_catalog,

{metergraph_core-0.6.1 → metergraph_core-0.7.0}/src/metergraph_core.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ src/metergraph_core/extractors.py
 src/metergraph_core/loader.py
 src/metergraph_core/models.py
 src/metergraph_core/refresh.py
+src/metergraph_core/responses.py
 src/metergraph_core/retrieval.py
 src/metergraph_core/sources.py
 src/metergraph_core.egg-info/PKG-INFO