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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph-core
-Version: 0.7.0
+Version: 0.7.4
 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
@@ -179,6 +179,14 @@ of the applied price. The bundled catalog is USD. `cost` and
 `components.input`, `output`, `cache_read`, `cache_write` and `request` are in
 that currency; the older `cost_usd` and `*_usd` names return the same values.
 
+`ModelUsage(batch=True)`, or `batch=True` on `price` and `cost`, bills at the
+row's batch input and output rates. Its cache reads bill at
+`Price.batch_cache_read_per_mtok` when the row has one, and otherwise at the
+standard `cache_read_per_mtok`, as before. A standard call always uses the
+standard cache-read rate. A row with only a batch cache rate fully prices a
+cached batch call, while a cached standard call on it is `partial` with
+`cache_read_rate_unavailable`.
+
 A `ModelUsage` count left `None` is unknown, not zero. A missing input or
 output count keeps the subtotal that is known, marks the result `partial`, and
 lists `input_tokens` or `output_tokens` in `missing_dimensions`.
@@ -225,7 +233,9 @@ It accepts the object a provider SDK returned or the same response as JSON:
 | 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
+`channel` is given. The response format is detected from its fields; pass
+`format=`, one of `RESPONSE_FORMATS`, for a response too sparse to detect.
+`response_format(response)` returns the detected format, or `None`. Only the
 model, usage counts, service tier and creation time are read; prompt and
 output content never are.
 
@@ -240,7 +250,9 @@ The price in effect when the response was created applies, from `created`,
 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,
+A batch service tier bills at batch rates, with cache reads priced as for
+`ModelUsage(batch=True)` above. Pass `service_tier=` when the
+response does not state its tier, such as an OpenAI batch output line. 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,
@@ -508,6 +520,7 @@ from metergraph_core import (
     PriceResult,
     PriceRowKey,
     PriceSource,
+    RESPONSE_FORMATS,
     RefreshResult,
     ResolvedPrice,
     SourceRegistry,
@@ -524,6 +537,7 @@ from metergraph_core import (
     parse_catalog_delta,
     plan_low_risk_refresh,
     resolve_billing,
+    response_format,
     structural_fingerprint,
     validate_model_registry,
     validate_source_registry,

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

@@ -149,6 +149,14 @@ of the applied price. The bundled catalog is USD. `cost` and
 `components.input`, `output`, `cache_read`, `cache_write` and `request` are in
 that currency; the older `cost_usd` and `*_usd` names return the same values.
 
+`ModelUsage(batch=True)`, or `batch=True` on `price` and `cost`, bills at the
+row's batch input and output rates. Its cache reads bill at
+`Price.batch_cache_read_per_mtok` when the row has one, and otherwise at the
+standard `cache_read_per_mtok`, as before. A standard call always uses the
+standard cache-read rate. A row with only a batch cache rate fully prices a
+cached batch call, while a cached standard call on it is `partial` with
+`cache_read_rate_unavailable`.
+
 A `ModelUsage` count left `None` is unknown, not zero. A missing input or
 output count keeps the subtotal that is known, marks the result `partial`, and
 lists `input_tokens` or `output_tokens` in `missing_dimensions`.
@@ -195,7 +203,9 @@ It accepts the object a provider SDK returned or the same response as JSON:
 | 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
+`channel` is given. The response format is detected from its fields; pass
+`format=`, one of `RESPONSE_FORMATS`, for a response too sparse to detect.
+`response_format(response)` returns the detected format, or `None`. Only the
 model, usage counts, service tier and creation time are read; prompt and
 output content never are.
 
@@ -210,7 +220,9 @@ The price in effect when the response was created applies, from `created`,
 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,
+A batch service tier bills at batch rates, with cache reads priced as for
+`ModelUsage(batch=True)` above. Pass `service_tier=` when the
+response does not state its tier, such as an OpenAI batch output line. 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,
@@ -478,6 +490,7 @@ from metergraph_core import (
     PriceResult,
     PriceRowKey,
     PriceSource,
+    RESPONSE_FORMATS,
     RefreshResult,
     ResolvedPrice,
     SourceRegistry,
@@ -494,6 +507,7 @@ from metergraph_core import (
     parse_catalog_delta,
     plan_low_risk_refresh,
     resolve_billing,
+    response_format,
     structural_fingerprint,
     validate_model_registry,
     validate_source_registry,

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

@@ -1,6 +1,6 @@
 [project]
 name = "metergraph-core"
-version = "0.7.0"
+version = "0.7.4"
 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.7.0 → metergraph_core-0.7.4}/src/metergraph_core/__init__.py

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

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

@@ -225,6 +225,22 @@ class Price:
     # The currency every rate on this row is stated in. The `_usd` names on
     # rates and results predate it and are kept for existing callers.
     currency: str = "USD"
+    # The rate a batch call's cache reads bill at, when the provider publishes
+    # one. Absent, batch cache reads keep the standard cache-read rate; it is
+    # never inferred from another rate.
+    batch_cache_read_per_mtok: Decimal | None = None
+
+    def __post_init__(self) -> None:
+        # The loader checks the rate it reads, but a row built or replaced
+        # directly must not bill a negative or undefined cache component.
+        rate = self.batch_cache_read_per_mtok
+        if rate is not None and not (
+            isinstance(rate, Decimal) and rate.is_finite() and rate >= 0
+        ):
+            raise ValueError(
+                "batch_cache_read_per_mtok must be a finite non-negative "
+                f"Decimal or None, not {rate!r}"
+            )
 
 
 @dataclass(frozen=True, slots=True)
@@ -353,6 +369,7 @@ def _billed_terms(resolved: ResolvedPrice) -> tuple[Any, ...]:
         price.cache_write_1h_per_mtok,
         price.batch_input_per_mtok,
         price.batch_output_per_mtok,
+        price.batch_cache_read_per_mtok,
         price.request_fee_per_1k_usd,
         resolved.rules,
     )
@@ -505,12 +522,17 @@ def _price_tokens(
 
     input_rate = price.input_per_mtok
     output_rate = price.output_per_mtok
+    cache_read_rate = price.cache_read_per_mtok
     if batch:
         if price.batch_input_per_mtok is None or price.batch_output_per_mtok is None:
             reasons.append("batch_rate_unavailable")
         else:
             input_rate = price.batch_input_per_mtok
             output_rate = price.batch_output_per_mtok
+        # A row without a batch cache rate keeps billing batch cache reads at
+        # the standard rate, as it always has.
+        if price.batch_cache_read_per_mtok is not None:
+            cache_read_rate = price.batch_cache_read_per_mtok
 
     input_multiplier = Decimal("1")
     output_multiplier = Decimal("1")
@@ -547,12 +569,12 @@ def _price_tokens(
     else:
         output_usd = Decimal(output_count) * output_rate * output_multiplier / _MILLION
     if cache_read_count:
-        if price.cache_read_per_mtok is None:
+        if cache_read_rate is None:
             reasons.append("cache_read_rate_unavailable")
         else:
             cache_read_usd = (
                 Decimal(cache_read_count)
-                * price.cache_read_per_mtok
+                * cache_read_rate
                 * input_multiplier
                 / _MILLION
             )

{metergraph_core-0.7.0 → metergraph_core-0.7.4}/src/metergraph_core/catalog_delta.py

@@ -45,6 +45,7 @@ RATE_FIELDS = (
     "cache_write_1h_per_mtok",
     "batch_input_per_mtok",
     "batch_output_per_mtok",
+    "batch_cache_read_per_mtok",
     "request_fee_per_1k_usd",
 )
 _PRICE_FIELDS = frozenset(

{metergraph_core-0.7.0 → metergraph_core-0.7.4}/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-23"
+version: "2026-10-25"
 currency: USD
-pricing_verified_at: "2026-10-23"
+pricing_verified_at: "2026-10-25"
 models:
   - canonical_id: openai/gpt-6-sol
     publisher: openai
@@ -1599,18 +1599,32 @@ models:
       - channel: google-api
         region: global
         effective_from: "2026-10-13"
-        effective_to: "2026-12-01"
+        effective_to: "2026-10-25"
         input_per_mtok: 2.00
         output_per_mtok: 10.00
         cache_read_per_mtok: 0.10
         source_url: https://ai.google.dev/gemini-api/docs/generate-content/latest-model
+      - channel: google-api
+        region: global
+        effective_from: "2026-10-25"
+        effective_to: "2026-12-01"
+        input_per_mtok: 2.00
+        output_per_mtok: 10.00
+        cache_read_per_mtok: 0.10
+        batch_input_per_mtok: 1.00
+        batch_output_per_mtok: 5.00
+        batch_cache_read_per_mtok: 0.05
+        source_url: https://ai.google.dev/gemini-api/docs/pricing
       - channel: google-api
         region: global
         effective_from: "2026-12-01"
         input_per_mtok: 4.00
         output_per_mtok: 20.00
         cache_read_per_mtok: 0.20
-        source_url: https://ai.google.dev/gemini-api/docs/generate-content/latest-model
+        batch_input_per_mtok: 2.00
+        batch_output_per_mtok: 10.00
+        batch_cache_read_per_mtok: 0.10
+        source_url: https://ai.google.dev/gemini-api/docs/pricing
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2026-10-13"
@@ -2506,15 +2520,24 @@ models:
         rules:
           uncaptured_fees: true
         source_url: https://docs.perplexity.ai/docs/getting-started/pricing
-      # The gateway bills Sonar's built-in search per call, so the row carries
-      # it as a request fee and the call is priced in full.
       - channel: vercel-ai-gateway
         region: global
         effective_from: "2026-10-11"
+        effective_to: "2026-10-24"
         input_per_mtok: 0.25
         output_per_mtok: 2.50
         request_fee_per_1k_usd: 2.50
         source_url: https://vercel.com/ai-gateway/models/sonar
+      # The gateway lists Sonar's web searches as a charge of their own, billed
+      # per search and not per request, so no request fee applies.
+      - channel: vercel-ai-gateway
+        region: global
+        effective_from: "2026-10-24"
+        input_per_mtok: 0.25
+        output_per_mtok: 2.50
+        rules:
+          uncaptured_fees: true
+        source_url: https://vercel.com/ai-gateway/models/sonar
 
   - canonical_id: openai/gpt-5-mini
     publisher: openai

{metergraph_core-0.7.0 → metergraph_core-0.7.4}/src/metergraph_core/loader.py

@@ -388,6 +388,17 @@ def parse_catalog(
                         f"{canonical}: overlapping {channel}/{region} price windows"
                     )
             seen_windows.append((channel, region, effective_from, effective_to))
+            batch_cache_read = price.get("batch_cache_read_per_mtok")
+            batch_cache_read_per_mtok = _decimal(batch_cache_read)
+            # A stated batch cache rate replaces the standard one on batch
+            # calls, so one that cannot be read must not quietly fall back.
+            if batch_cache_read is not None and (
+                batch_cache_read_per_mtok is None or batch_cache_read_per_mtok < 0
+            ):
+                raise CatalogError(
+                    f"{canonical}: invalid batch_cache_read_per_mtok "
+                    f"{batch_cache_read!r}"
+                )
             prices.append(
                 Price(
                     id=f"{canonical}:{channel}:{region}:{_id_date(effective_from)}",
@@ -412,6 +423,7 @@ def parse_catalog(
                     source_url=str(price["source_url"]).strip(),
                     publisher=publisher,
                     currency=currency,
+                    batch_cache_read_per_mtok=batch_cache_read_per_mtok,
                 )
             )
     return version, {key: tuple(value) for key, value in aliases.items()}, _unique_ids(prices)

{metergraph_core-0.7.0 → metergraph_core-0.7.4}/src/metergraph_core/responses.py

@@ -12,7 +12,7 @@ from datetime import datetime, timezone
 from functools import lru_cache
 from typing import Any, Callable, Mapping
 
-from .catalog import CostResult, ModelUsage
+from .catalog import CostResult, ModelUsage, _coerce_datetime
 from .loader import LoadedCatalog, load_catalog
 
 _STANDARD_TIERS = frozenset({"default", "standard", "standard_only", "auto", "on_demand"})
@@ -188,23 +188,41 @@ def _bedrock_converse(response: Mapping[str, Any]) -> _Facts:
     )
 
 
-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."""
+_READERS: dict[str, Callable[[Mapping[str, Any]], _Facts]] = {
+    "openai.chat_completions": _openai_chat_completions,
+    "openai.responses": _openai_responses,
+    "anthropic.messages": _anthropic_messages,
+    "gemini.generate_content": _gemini,
+    "bedrock.converse": _bedrock_converse,
+}
+
+# The response formats :func:`cost_from_response` reads.
+RESPONSE_FORMATS = tuple(_READERS)
+
+
+def _detect(response: Mapping[str, Any]) -> str | None:
+    """The format of this response, told apart by the fields each API
+    always returns."""
     if _first(response, "usage_metadata", "usageMetadata") is not None:
-        return _gemini
+        return "gemini.generate_content"
     usage = _object(response.get("usage"))
     if "prompt_tokens" in usage:
-        return _openai_chat_completions
+        return "openai.chat_completions"
     if "inputTokens" in usage:
-        return _bedrock_converse
+        return "bedrock.converse"
     if response.get("type") == "message" or "cache_read_input_tokens" in usage:
-        return _anthropic_messages
+        return "anthropic.messages"
     if response.get("object") == "response" or "input_tokens_details" in usage:
-        return _openai_responses
+        return "openai.responses"
     return None
 
 
+def response_format(response: Any) -> str | None:
+    """The :data:`RESPONSE_FORMATS` entry ``response`` is in, or None when its
+    shape is not recognized."""
+    return _detect(_as_mapping(response))
+
+
 def _as_mapping(response: Any) -> Mapping[str, Any]:
     if isinstance(response, Mapping):
         return response
@@ -270,6 +288,8 @@ def cost_from_response(
     at: Any = None,
     channel: str | None = None,
     region: str | None = None,
+    service_tier: str | None = None,
+    format: str | None = None,
 ) -> CostResult:
     """The cost of one provider response, from the usage it reports.
 
@@ -280,24 +300,36 @@ def cost_from_response(
     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.
+    defaults to the catalog bundled with this package. ``format``, one of
+    :data:`RESPONSE_FORMATS`, names the response's format; without it the
+    format is detected from the response's fields.
 
     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.
+    Fees outside token usage, such as web search, are not included.
+    ``service_tier`` overrides the tier the response reports, for responses
+    that do not state it, such as an OpenAI batch output line. A 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:
+    if format is not None and format not in _READERS:
+        raise ValueError(f"format must be one of {', '.join(RESPONSE_FORMATS)}")
+    detected = format or _detect(data)
+    if detected is None:
         raise ValueError("response carries no usage this function can read")
-    facts = reader(data)
+    facts = _READERS[detected](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
+    tier = (_text(service_tier) or facts.service_tier or "").lower() or None
     if model_id is None:
         return CostResult(
-            None, None, None, "unpriced", ("missing_model",), missing_dimensions=("model",)
+            None,
+            None,
+            None,
+            "unpriced",
+            ("missing_model",),
+            effective_at=_coerce_datetime(when),
+            missing_dimensions=("model",),
         )
     loaded = catalog if catalog is not None else _bundled_catalog()
     batch = tier == _BATCH_TIER

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph-core
-Version: 0.7.0
+Version: 0.7.4
 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
@@ -179,6 +179,14 @@ of the applied price. The bundled catalog is USD. `cost` and
 `components.input`, `output`, `cache_read`, `cache_write` and `request` are in
 that currency; the older `cost_usd` and `*_usd` names return the same values.
 
+`ModelUsage(batch=True)`, or `batch=True` on `price` and `cost`, bills at the
+row's batch input and output rates. Its cache reads bill at
+`Price.batch_cache_read_per_mtok` when the row has one, and otherwise at the
+standard `cache_read_per_mtok`, as before. A standard call always uses the
+standard cache-read rate. A row with only a batch cache rate fully prices a
+cached batch call, while a cached standard call on it is `partial` with
+`cache_read_rate_unavailable`.
+
 A `ModelUsage` count left `None` is unknown, not zero. A missing input or
 output count keeps the subtotal that is known, marks the result `partial`, and
 lists `input_tokens` or `output_tokens` in `missing_dimensions`.
@@ -225,7 +233,9 @@ It accepts the object a provider SDK returned or the same response as JSON:
 | 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
+`channel` is given. The response format is detected from its fields; pass
+`format=`, one of `RESPONSE_FORMATS`, for a response too sparse to detect.
+`response_format(response)` returns the detected format, or `None`. Only the
 model, usage counts, service tier and creation time are read; prompt and
 output content never are.
 
@@ -240,7 +250,9 @@ The price in effect when the response was created applies, from `created`,
 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,
+A batch service tier bills at batch rates, with cache reads priced as for
+`ModelUsage(batch=True)` above. Pass `service_tier=` when the
+response does not state its tier, such as an OpenAI batch output line. 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,
@@ -508,6 +520,7 @@ from metergraph_core import (
     PriceResult,
     PriceRowKey,
     PriceSource,
+    RESPONSE_FORMATS,
     RefreshResult,
     ResolvedPrice,
     SourceRegistry,
@@ -524,6 +537,7 @@ from metergraph_core import (
     parse_catalog_delta,
     plan_low_risk_refresh,
     resolve_billing,
+    response_format,
     structural_fingerprint,
     validate_model_registry,
     validate_source_registry,