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

{metergraph_core-0.6.4/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.4
+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.4 → 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.4 → metergraph_core-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metergraph-core"
-version = "0.6.4"
+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.4 → 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.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.4 → 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.4
+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.4 → 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