metergraph-core 0.8.3__tar.gz → 0.8.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (25) hide show
  1. {metergraph_core-0.8.3/src/metergraph_core.egg-info → metergraph_core-0.8.5}/PKG-INFO +31 -1
  2. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/README.md +30 -0
  3. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/pyproject.toml +1 -1
  4. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core/__init__.py +6 -0
  5. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core/billing.py +5 -1
  6. metergraph_core-0.8.5/src/metergraph_core/calls.py +184 -0
  7. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core/data/models.yaml +32 -1
  8. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core/data/prices.yaml +1801 -79
  9. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core/extractors.py +7 -2
  10. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core/models.py +5 -1
  11. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core/retrieval.py +2 -1
  12. {metergraph_core-0.8.3 → metergraph_core-0.8.5/src/metergraph_core.egg-info}/PKG-INFO +31 -1
  13. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core.egg-info/SOURCES.txt +1 -0
  14. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/MANIFEST.in +0 -0
  15. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/setup.cfg +0 -0
  16. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core/catalog.py +0 -0
  17. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core/catalog_delta.py +0 -0
  18. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core/data/sources.yaml +0 -0
  19. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core/loader.py +0 -0
  20. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core/refresh.py +0 -0
  21. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core/responses.py +0 -0
  22. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core/sources.py +0 -0
  23. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core.egg-info/dependency_links.txt +0 -0
  24. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core.egg-info/requires.txt +0 -0
  25. {metergraph_core-0.8.3 → metergraph_core-0.8.5}/src/metergraph_core.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: metergraph-core
3
- Version: 0.8.3
3
+ Version: 0.8.5
4
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.
5
5
  Author: Metergraph
6
6
  License-Expression: Apache-2.0
@@ -603,3 +603,33 @@ lifecycles.
603
603
  The model registry version is an ISO date. When more than one registry ships on
604
604
  the same date, append a positive revision such as `2026-09-25.2` so consumers
605
605
  can distinguish the policies while pricing validation still uses that date.
606
+
607
+
608
+ ## Complete call pricing
609
+
610
+ `price_call_from_response` combines token costs with supported retrieval fees.
611
+ `cost_from_response` remains token-only. Retrieval pricing supports Anthropic
612
+ `web_search` and `web_fetch` on `anthropic-api`; other observed scopes are unresolved.
613
+
614
+ ```python
615
+ from metergraph_core import price_call_from_response
616
+
617
+ result = price_call_from_response(
618
+ "anthropic",
619
+ {"type": "message", "model": "claude-sonnet-5-5", "usage": {
620
+ "input_tokens": 1000, "output_tokens": 100,
621
+ "server_tool_use": {"web_search_requests": 2},
622
+ }},
623
+ at="2026-10-20T00:00:00Z",
624
+ )
625
+ assert str(result.cost_usd) == "0.02300000"
626
+ ```
627
+
628
+ `cost_usd` is set only when the call is fully priced. `known_subtotal_usd`
629
+ contains exact components; `estimated_total_usd` separates token fallback
630
+ estimates when all retrieval fees are known. Missing charges are reported in
631
+ `missing_dimensions`. Counts must be nonnegative integers.
632
+
633
+ For normalized usage, use `price_call` with `ModelUsage` and `RetrievalUsage`.
634
+ To compose an existing token result from the same catalog, use `compose_call_cost`.
635
+ `resolve_billing` accepts complete-call results for gateway reconciliation.
@@ -573,3 +573,33 @@ lifecycles.
573
573
  The model registry version is an ISO date. When more than one registry ships on
574
574
  the same date, append a positive revision such as `2026-09-25.2` so consumers
575
575
  can distinguish the policies while pricing validation still uses that date.
576
+
577
+
578
+ ## Complete call pricing
579
+
580
+ `price_call_from_response` combines token costs with supported retrieval fees.
581
+ `cost_from_response` remains token-only. Retrieval pricing supports Anthropic
582
+ `web_search` and `web_fetch` on `anthropic-api`; other observed scopes are unresolved.
583
+
584
+ ```python
585
+ from metergraph_core import price_call_from_response
586
+
587
+ result = price_call_from_response(
588
+ "anthropic",
589
+ {"type": "message", "model": "claude-sonnet-5-5", "usage": {
590
+ "input_tokens": 1000, "output_tokens": 100,
591
+ "server_tool_use": {"web_search_requests": 2},
592
+ }},
593
+ at="2026-10-20T00:00:00Z",
594
+ )
595
+ assert str(result.cost_usd) == "0.02300000"
596
+ ```
597
+
598
+ `cost_usd` is set only when the call is fully priced. `known_subtotal_usd`
599
+ contains exact components; `estimated_total_usd` separates token fallback
600
+ estimates when all retrieval fees are known. Missing charges are reported in
601
+ `missing_dimensions`. Counts must be nonnegative integers.
602
+
603
+ For normalized usage, use `price_call` with `ModelUsage` and `RetrievalUsage`.
604
+ To compose an existing token result from the same catalog, use `compose_call_cost`.
605
+ `resolve_billing` accepts complete-call results for gateway reconciliation.
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "metergraph-core"
3
- version = "0.8.3"
3
+ version = "0.8.5"
4
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."
5
5
  readme = "README.md"
6
6
  license = "Apache-2.0"
@@ -155,3 +155,9 @@ __all__ = [
155
155
  "search_operation_for_channel",
156
156
  "validate_model_registry",
157
157
  ]
158
+
159
+ from .calls import (CallCostResult, RetrievalComponent, RetrievalUsage, compose_call_cost,
160
+ price_call, price_call_from_response, response_retrieval_usage)
161
+
162
+ __all__ += ["CallCostResult", "RetrievalComponent", "RetrievalUsage", "compose_call_cost",
163
+ "price_call", "price_call_from_response", "response_retrieval_usage"]
@@ -168,7 +168,7 @@ def _disputed(
168
168
 
169
169
 
170
170
  def resolve_billing(
171
- catalog_result: CostResult,
171
+ catalog_result: "CostResult | CallCostResult",
172
172
  evidence: GatewayBillingEvidence,
173
173
  *,
174
174
  disputes: Iterable[Dispute] = (),
@@ -231,3 +231,7 @@ def resolve_billing(
231
231
  catalog_price_id=catalog_result.price_id,
232
232
  catalog_reasons=reasons,
233
233
  )
234
+
235
+ from typing import TYPE_CHECKING
236
+ if TYPE_CHECKING:
237
+ from .calls import CallCostResult
@@ -0,0 +1,184 @@
1
+ """Compose token and counted retrieval costs from one catalog snapshot."""
2
+ from __future__ import annotations
3
+
4
+ from dataclasses import dataclass
5
+ from decimal import Decimal
6
+ from typing import Any, Mapping, Sequence
7
+
8
+ from .catalog import CostResult, ModelUsage, direct_channel_for_provider, normalize_provider
9
+ from .loader import LoadedCatalog
10
+ from .responses import _as_mapping, _bundled_catalog, cost_from_response, response_format
11
+
12
+ _ZERO = Decimal('0')
13
+
14
+
15
+ @dataclass(frozen=True, slots=True)
16
+ class RetrievalUsage:
17
+ operation: str
18
+ units: Any
19
+
20
+
21
+ @dataclass(frozen=True, slots=True)
22
+ class RetrievalComponent:
23
+ operation: str
24
+ units: Any
25
+ cost_usd: Decimal | None
26
+ price_id: str | None
27
+ basis: str
28
+ reasons: tuple[str, ...] = ()
29
+ source_url: str | None = None
30
+
31
+
32
+ @dataclass(frozen=True, slots=True)
33
+ class CallCostResult:
34
+ token_cost: CostResult
35
+ retrieval: tuple[RetrievalComponent, ...]
36
+ cost_usd: Decimal | None
37
+ known_subtotal_usd: Decimal
38
+ estimated_total_usd: Decimal | None
39
+ status: str
40
+ token_basis: str
41
+ missing_dimensions: tuple[str, ...]
42
+ catalog_hash: str
43
+
44
+
45
+ @property
46
+ def publisher(self) -> str | None:
47
+ return self.token_cost.publisher
48
+
49
+ @property
50
+ def price_id(self) -> str | None:
51
+ return self.token_cost.price_id
52
+
53
+ @property
54
+ def reasons(self) -> tuple[str, ...]:
55
+ return tuple(dict.fromkeys((*self.token_cost.reasons,
56
+ *(f"missing_{d}" for d in self.missing_dimensions))))
57
+
58
+
59
+ def compose_call_cost(
60
+ token_cost: CostResult, *, catalog: LoadedCatalog,
61
+ retrieval: Sequence[RetrievalUsage] = (), provider: str | None = None,
62
+ channel: str | None = None, region: str = 'global',
63
+ ) -> CallCostResult:
64
+ """Combine retrieval with a token result from the same catalog and time.
65
+
66
+ Partial token results remain estimates, excluded from the known subtotal.
67
+ """
68
+ if token_cost.effective_at is None:
69
+ raise ValueError('token_cost must carry its effective_at')
70
+ if token_cost.price is not None:
71
+ selected = catalog.lookup_price(model=token_cost.canonical_model,
72
+ channel=token_cost.price.pricing_channel, region=token_cost.price.region,
73
+ at=token_cost.effective_at)
74
+ if selected.price != token_cost.price:
75
+ raise ValueError('token price does not match the catalog snapshot')
76
+ if len({item.operation for item in retrieval}) != len(retrieval):
77
+ raise ValueError('retrieval operations must be aggregated once per call')
78
+ resolved_channel = token_cost.price.pricing_channel if token_cost.price else (channel or direct_channel_for_provider(provider))
79
+ publisher = token_cost.publisher or normalize_provider(provider or '')
80
+ missing = list(token_cost.missing_dimensions)
81
+ token_basis = ('exact' if token_cost.status == 'priced' else
82
+ 'fallback_estimate' if token_cost.cost_usd is not None else 'unknown')
83
+ # Retrieval rates are USD. Do not add them to a different currency.
84
+ currency_ok = token_cost.currency in (None, 'USD')
85
+ known = token_cost.cost_usd if token_basis == 'exact' and currency_ok else _ZERO
86
+ if not currency_ok:
87
+ missing.append('currency')
88
+ token_basis = 'unknown'
89
+ parts = []
90
+ for usage in retrieval:
91
+ if resolved_channel == 'anthropic-api' and publisher == 'anthropic' and usage.operation in {'web_search', 'web_fetch'}:
92
+ fee = catalog.price_retrieval(channel=resolved_channel, operation=usage.operation,
93
+ units=usage.units, at=token_cost.effective_at, region=region)
94
+ part = RetrievalComponent(usage.operation, usage.units, fee.cost_usd,
95
+ fee.price_id, 'exact' if fee.status == 'priced' else 'unknown', fee.reasons, fee.source_url)
96
+ else:
97
+ part = RetrievalComponent(usage.operation, usage.units, None, None,
98
+ 'unknown', ('unsupported_retrieval_scope',))
99
+ part = RetrievalComponent(part.operation,
100
+ part.units if type(part.units) is int and part.units >= 0 else None,
101
+ part.cost_usd, part.price_id, part.basis, part.reasons, part.source_url)
102
+ parts.append(part)
103
+ if part.cost_usd is None:
104
+ missing.append(f'retrieval.{usage.operation}')
105
+ else:
106
+ known += part.cost_usd
107
+ unresolved = any(p.basis == 'unknown' for p in parts)
108
+ status = ('unpriced' if token_cost.price is None or token_cost.status == 'unpriced' else
109
+ 'partial' if token_basis != 'exact' or unresolved or missing else 'priced')
110
+ estimated = None
111
+ if token_basis == 'fallback_estimate' and not unresolved:
112
+ estimated = token_cost.cost_usd + sum((p.cost_usd or _ZERO for p in parts), _ZERO)
113
+ return CallCostResult(token_cost, tuple(parts), known if status == 'priced' else None,
114
+ known, estimated, status, token_basis, tuple(dict.fromkeys(missing)), catalog.content_hash)
115
+
116
+
117
+ def price_call(
118
+ *, model: Any, usage: ModelUsage, at: Any, catalog: LoadedCatalog | None = None,
119
+ provider: str | None = None, channel: str | None = None, region: str | None = None,
120
+ retrieval: Sequence[RetrievalUsage] = (),
121
+ ) -> CallCostResult:
122
+ """Price normalized token and retrieval usage against one snapshot."""
123
+ loaded = catalog if catalog is not None else _bundled_catalog()
124
+ tokens = loaded.calculate_cost(model=model, usage=usage, at=at, provider=provider,
125
+ channel=channel, region=region)
126
+ return compose_call_cost(tokens, catalog=loaded, retrieval=retrieval, provider=provider,
127
+ channel=channel or direct_channel_for_provider(provider), region=region or 'global')
128
+
129
+
130
+ def response_retrieval_usage(response: Any, *, format: str | None = None) -> tuple[RetrievalUsage, ...]:
131
+ """Read operation metadata without reading prompt or response text.
132
+
133
+ Tool evidence without a valid usage counter remains unresolved.
134
+ """
135
+ data = _as_mapping(response)
136
+ detected = format or response_format(data)
137
+ if detected == 'anthropic.messages':
138
+ usage = data.get('usage')
139
+ usage = usage if isinstance(usage, Mapping) else {}
140
+ server = usage.get('server_tool_use')
141
+ if 'server_tool_use' in usage and not isinstance(server, Mapping):
142
+ return (RetrievalUsage('web_search', None),)
143
+ server = server or {}
144
+ found = [RetrievalUsage(op, server[key]) for key, op in (
145
+ ('web_search_requests', 'web_search'), ('web_fetch_requests', 'web_fetch')) if key in server]
146
+ observed = set()
147
+ content = data.get('content')
148
+ if isinstance(content, list):
149
+ for block in content:
150
+ if isinstance(block, Mapping) and block.get('type') == 'server_tool_use':
151
+ name = block.get('name')
152
+ if name in ('web_search', 'web_fetch'):
153
+ observed.add(name)
154
+ found.extend(RetrievalUsage(op, None) for op in sorted(observed) if op not in {f.operation for f in found})
155
+ return tuple(found)
156
+ if detected == 'gemini.generate_content':
157
+ candidates = data.get('candidates')
158
+ if isinstance(candidates, list):
159
+ for item in candidates:
160
+ metadata = item.get('groundingMetadata') if isinstance(item, Mapping) else None
161
+ if isinstance(metadata, Mapping) and ('webSearchQueries' in metadata or 'groundingChunks' in metadata):
162
+ # Grounding evidence does not establish billable query count.
163
+ return (RetrievalUsage('google_search_grounding', None),)
164
+ if detected == 'openai.responses':
165
+ output = data.get('output')
166
+ if isinstance(output, list):
167
+ count = sum(1 for item in output if isinstance(item, Mapping) and item.get('type') == 'web_search_call')
168
+ if count:
169
+ return (RetrievalUsage('web_search', count),)
170
+ return ()
171
+
172
+
173
+ def price_call_from_response(
174
+ provider: str, response: Any, *, catalog: LoadedCatalog | None = None,
175
+ model: str | None = None, at: Any = None, channel: str | None = None,
176
+ region: str | None = None, service_tier: str | None = None, format: str | None = None,
177
+ ) -> CallCostResult:
178
+ """Price a provider response, including supported counted retrieval fees."""
179
+ loaded = catalog if catalog is not None else _bundled_catalog()
180
+ tokens = cost_from_response(provider, response, catalog=loaded, model=model, at=at,
181
+ channel=channel, region=region, service_tier=service_tier, format=format)
182
+ return compose_call_cost(tokens, catalog=loaded,
183
+ retrieval=response_retrieval_usage(response, format=format), provider=provider,
184
+ channel=channel or direct_channel_for_provider(provider), region=region or 'global')
@@ -1,4 +1,4 @@
1
- version: '2026-10-27'
1
+ version: '2026-10-29'
2
2
  models:
3
3
  - canonical_id: openai/gpt-5.6-sol
4
4
  display_name: GPT-5.6 Sol
@@ -888,6 +888,30 @@ models:
888
888
  execution_profiles:
889
889
  - default
890
890
  display_name: Kimi K3.1 Pro Highspeed (direct)
891
+ - canonical_id: minimax/minimax-m3.1-flash
892
+ display_name: MiniMax M3.1 Flash
893
+ publisher: minimax
894
+ released: '2026-10-19' # https://www.minimax.io/blog/minimax-m31f
895
+ routes:
896
+ - key: default:minimax/minimax-m3.1-flash
897
+ id: minimax/minimax-m3.1-flash
898
+ provider: vercel
899
+ model_id: minimax/minimax-m3.1-flash
900
+ pricing_channel: vercel-ai-gateway
901
+ execution_profiles:
902
+ - default
903
+ - canonical_id: mistral/mistral-small-4
904
+ display_name: Mistral Small 4
905
+ publisher: mistral
906
+ released: '2026-03-16' # https://docs.mistral.ai/models/mistral-small-4-0-26-03
907
+ routes:
908
+ - key: default:mistral:mistral-small-2603
909
+ id: mistral:mistral-small-2603
910
+ provider: mistral
911
+ model_id: mistral-small-2603
912
+ pricing_channel: mistral-api
913
+ execution_profiles:
914
+ - default
891
915
  execution_profiles:
892
916
  - id: default
893
917
  routes:
@@ -963,6 +987,8 @@ execution_profiles:
963
987
  - default:openai:gpt-6.1-terra
964
988
  - default:moonshotai:kimi-k3.1-pro
965
989
  - default:moonshotai:kimi-k3.1-pro-highspeed
990
+ - default:minimax/minimax-m3.1-flash
991
+ - default:mistral:mistral-small-2603
966
992
  - id: bedrock
967
993
  routes:
968
994
  - bedrock:anthropic/claude-sonnet-5
@@ -1029,6 +1055,7 @@ offer_groups:
1029
1055
  - default:deepseek/deepseek-v4.1-flash-1017
1030
1056
  - default:deepseek/deepseek-v4.1-flash-1017-fast
1031
1057
  - default:inception/mercury-3
1058
+ - default:minimax/minimax-m3.1-flash
1032
1059
  - id: fireworks
1033
1060
  credential: FIREWORKS_API_KEY
1034
1061
  routes:
@@ -1059,6 +1086,10 @@ offer_groups:
1059
1086
  routes:
1060
1087
  - default:moonshotai:kimi-k3.1-pro
1061
1088
  - default:moonshotai:kimi-k3.1-pro-highspeed
1089
+ - id: mistral-direct
1090
+ credential: MISTRAL_API_KEY
1091
+ routes:
1092
+ - default:mistral:mistral-small-2603
1062
1093
  - id: bedrock
1063
1094
  credential: null
1064
1095
  routes: