metergraph 0.6.9__tar.gz → 0.6.11__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 (28) hide show
  1. {metergraph-0.6.9 → metergraph-0.6.11}/PKG-INFO +62 -13
  2. metergraph-0.6.9/src/metergraph.egg-info/PKG-INFO → metergraph-0.6.11/README.md +54 -32
  3. metergraph-0.6.11/pyproject.toml +49 -0
  4. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/__init__.py +19 -4
  5. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_capture.py +208 -0
  6. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_genai_attrs.py +185 -4
  7. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_version.py +1 -1
  8. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/opentelemetry.py +8 -1
  9. metergraph-0.6.9/README.md → metergraph-0.6.11/src/metergraph.egg-info/PKG-INFO +81 -7
  10. metergraph-0.6.9/pyproject.toml +0 -34
  11. {metergraph-0.6.9 → metergraph-0.6.11}/MANIFEST.in +0 -0
  12. {metergraph-0.6.9 → metergraph-0.6.11}/setup.cfg +0 -0
  13. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_batch_first.py +0 -0
  14. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_config.py +0 -0
  15. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_context.py +0 -0
  16. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_failure_log.py +0 -0
  17. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_gateway.py +0 -0
  18. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_provider_batch.py +0 -0
  19. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_repo_config.py +0 -0
  20. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_session.py +0 -0
  21. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_template.py +0 -0
  22. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_tool_definitions.py +0 -0
  23. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_track.py +0 -0
  24. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph/_transport.py +0 -0
  25. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph.egg-info/SOURCES.txt +0 -0
  26. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph.egg-info/dependency_links.txt +0 -0
  27. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph.egg-info/requires.txt +0 -0
  28. {metergraph-0.6.9 → metergraph-0.6.11}/src/metergraph.egg-info/top_level.txt +0 -0
@@ -1,13 +1,15 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: metergraph
3
- Version: 0.6.9
4
- Summary: Fire-and-forget LLM spend capture for Metergraph
5
- Author: Pioneer Square Labs
3
+ Version: 0.6.11
4
+ Summary: Zero-dependency Python SDK for function-level LLM cost attribution across major LLM providers and gateways, including OpenAI, Anthropic, Gemini, and Vercel AI Gateway.
5
+ Author: Metergraph
6
6
  License-Expression: Apache-2.0
7
7
  Project-URL: Homepage, https://www.metergraph.dev/
8
- Project-URL: Repository, https://github.com/PioneerSquareLabs/metergraphsdk
9
- Project-URL: Issues, https://github.com/PioneerSquareLabs/metergraphsdk/issues
10
- Keywords: llm,observability,openai,anthropic,gemini,vercel-ai-gateway,cost-tracking
8
+ Project-URL: Documentation, https://github.com/metergraph/metergraphsdk/tree/main/python#readme
9
+ Project-URL: Repository, https://github.com/metergraph/metergraphsdk
10
+ Project-URL: Issues, https://github.com/metergraph/metergraphsdk/issues
11
+ Project-URL: Release notes, https://github.com/metergraph/metergraphsdk/releases
12
+ Keywords: llm,llm-cost,llm-observability,cost-attribution,ai-agents,openai,anthropic,gemini,vercel-ai-sdk,vercel-ai-gateway,opentelemetry,self-hosted
11
13
  Classifier: Intended Audience :: Developers
12
14
  Classifier: Topic :: Software Development :: Libraries :: Python Modules
13
15
  Classifier: Typing :: Typed
@@ -25,8 +27,18 @@ Requires-Dist: opentelemetry-sdk>=1.30; extra == "dev"
25
27
 
26
28
  # metergraph (Python)
27
29
 
28
- Zero-runtime-dependency capture for OpenAI, Anthropic, Gemini, and Python
29
- Vercel AI Gateway clients.
30
+ See where your agentic AI application's LLM spend comes from. Attribute usage
31
+ to functions, agents, and workflows without changing provider call sites, then
32
+ send it to Metergraph Cloud or your self-hosted Metergraph server.
33
+
34
+ [Metergraph](https://www.metergraph.dev/) helps teams understand and optimize
35
+ agentic AI applications. This open-source, zero-runtime-dependency package
36
+ provides function-level LLM cost attribution for OpenAI, Anthropic, Gemini, and
37
+ Python Vercel AI Gateway clients. Paid Metergraph builds on that attribution
38
+ with experimentation and optimization across models, prompts, tools,
39
+ retrieval, context, batching, and caching. This package captures and
40
+ attributes usage; it does not run experiments or optimize your application.
41
+
30
42
  Initialize Metergraph once, then wrap each provider client. `init()` reads the
31
43
  token and other omitted options from the environment.
32
44
 
@@ -103,7 +115,7 @@ OpenRouter is captured the same way: point an OpenAI client at
103
115
  `reported_cost_usd` to Chat Completions rows without changing the requested model
104
116
  or the capture provider. A trusted custom domain uses
105
117
  `metergraph.wrap(client, gateway="openrouter")`. The runnable
106
- [Python OpenRouter example](../examples/python-openrouter/) covers requested-vs-
118
+ [Python OpenRouter example](../examples/integrations/providers/openrouter/python/) covers requested-vs-
107
119
  served model, reported-vs-catalog cost, streaming usage, and the BYOK limitation.
108
120
 
109
121
  ## OpenTelemetry GenAI export
@@ -125,17 +137,40 @@ from metergraph.opentelemetry import MetergraphGenAIExporter
125
137
 
126
138
  litellm.callbacks.append(OpenTelemetry(OpenTelemetryConfig(
127
139
  exporter=MetergraphGenAIExporter(),
128
- capture_message_content="SPAN_ONLY",
129
140
  )))
141
+
142
+ response = litellm.completion(
143
+ model="openai/gpt-5-mini",
144
+ messages=messages,
145
+ metadata={"generation_name": "ticket-triage"},
146
+ )
130
147
  ```
131
148
 
149
+ - LiteLLM logs message content on its spans by default. Releases before 1.85
150
+ have no `capture_message_content` option, so leave it out.
151
+ - Do not set `litellm.turn_off_message_logging`. It removes messages, tool
152
+ definitions and outputs from the spans, so MeterGraph can count the calls but
153
+ cannot analyse them.
154
+ - Name each call with `metadata={"generation_name": "<workload name>"}`.
155
+ LiteLLM uses it as the span name and MeterGraph records it as the call's
156
+ route. Without it every call is stored under the route `chat`. A
157
+ `metergraph.route` or `gen_ai.prompt.name` span attribute still takes
158
+ precedence.
159
+ - To group the calls of a multi-step agent run into one trace, make them inside
160
+ one application span and set `USE_OTEL_LITELLM_REQUEST_SPAN=true`. Without
161
+ that variable LiteLLM writes each call onto the application span itself, and
162
+ only one of the calls is recorded.
163
+ - Pass a new `metadata` dict to each call. Reusing one dict across calls makes
164
+ LiteLLM 1.103 drop spans.
165
+
132
166
  The exporter preserves OpenTelemetry trace identity, model/provider metadata,
133
167
  token usage, latency, system instructions, ordered messages, and text output.
134
- Message content is explicitly enabled because it may be sensitive. Text parts
168
+ From LiteLLM spans it also records the provider response id as the request id,
169
+ the request's tool definitions, and the tool calls in the response. Text parts
135
170
  are retained and replayable in the current POC pipeline. Calls containing other
136
171
  part types retain their model, usage, timing, and status metadata, but those
137
172
  parts are not replayable yet. See the runnable
138
- [`python-litellm-otel` example](../examples/python-litellm-otel/).
173
+ [`LiteLLM OpenTelemetry example`](../examples/integrations/telemetry/litellm/python/).
139
174
 
140
175
  The exporter reads the OpenTelemetry `gen_ai.*` conventions, OpenInference
141
176
  (Arize Phoenix), Langfuse and LangSmith spans. Dialects that label span kind
@@ -212,6 +247,20 @@ message batches are captured per inference while iterating a wrapped
212
247
  rows carry real per-result usage and the batch pricing flag; job-management
213
248
  polls themselves are not miscounted as model calls.
214
249
 
250
+ OpenAI Responses created with `background=True` are recorded once, when a
251
+ wrapped `client.responses.retrieve()` or `cancel()` first returns a terminal
252
+ status (`completed`, `failed`, `cancelled` or `incomplete`), with that
253
+ response's usage and output. Polls that still report `queued` or
254
+ `in_progress` add no rows, and latency runs from `create` to the observed
255
+ terminal response. A background response whose terminal status the process
256
+ never observes is recorded at `shutdown()` with status `abandoned` and
257
+ unknown usage, never as a completed call with zero tokens. A streamed
258
+ `retrieve(..., stream=True)` or `responses.stream(response_id=...)` resume is
259
+ observed through its terminal response event. Only retrieves made through the same wrapped client in the same process
260
+ are observed: a client derived with `with_options()` or `copy()`,
261
+ `with_raw_response`/`with_streaming_response` retrieves, and polling from a
262
+ different process leave the call to be recorded as `abandoned`.
263
+
215
264
  ## Batch-first execution (opt-in)
216
265
 
217
266
  `metergraph.batch_first()` is a separate, explicitly opt-in code path from `wrap()`/capture: submit one request through a provider's Batch API, wait up to a caller-chosen deadline, and fall back to exactly one direct call if the batch hasn't finished in time. It is synchronous/blocking, matching this SDK's own background-work model — a daemon thread, not asyncio.
@@ -248,7 +297,7 @@ codebase you want instrumented:
248
297
 
249
298
  ```text
250
299
  Instrument this codebase's LLM API costs with the `metergraph` PyPI package
251
- (https://github.com/PioneerSquareLabs/metergraphsdk): pip install metergraph,
300
+ (https://github.com/metergraph/metergraphsdk): pip install metergraph,
252
301
  then wrap every OpenAI()/AsyncOpenAI(), Anthropic()/AsyncAnthropic(), and
253
302
  genai.Client() construction in place, e.g. client = metergraph.wrap(OpenAI()).
254
303
  OpenAI or Anthropic clients pointed at https://ai-gateway.vercel.sh are Vercel
@@ -1,32 +1,17 @@
1
- Metadata-Version: 2.4
2
- Name: metergraph
3
- Version: 0.6.9
4
- Summary: Fire-and-forget LLM spend capture for Metergraph
5
- Author: Pioneer Square Labs
6
- License-Expression: Apache-2.0
7
- Project-URL: Homepage, https://www.metergraph.dev/
8
- Project-URL: Repository, https://github.com/PioneerSquareLabs/metergraphsdk
9
- Project-URL: Issues, https://github.com/PioneerSquareLabs/metergraphsdk/issues
10
- Keywords: llm,observability,openai,anthropic,gemini,vercel-ai-gateway,cost-tracking
11
- Classifier: Intended Audience :: Developers
12
- Classifier: Topic :: Software Development :: Libraries :: Python Modules
13
- Classifier: Typing :: Typed
14
- Requires-Python: >=3.10
15
- Description-Content-Type: text/markdown
16
- Provides-Extra: otel
17
- Requires-Dist: opentelemetry-sdk>=1.30; extra == "otel"
18
- Provides-Extra: dev
19
- Requires-Dist: build>=1; extra == "dev"
20
- Requires-Dist: pytest>=8; extra == "dev"
21
- Requires-Dist: openai<3,>=2.50.0; extra == "dev"
22
- Requires-Dist: anthropic<1,>=0.40; extra == "dev"
23
- Requires-Dist: google-genai>=1; extra == "dev"
24
- Requires-Dist: opentelemetry-sdk>=1.30; extra == "dev"
25
-
26
1
  # metergraph (Python)
27
2
 
28
- Zero-runtime-dependency capture for OpenAI, Anthropic, Gemini, and Python
29
- Vercel AI Gateway clients.
3
+ See where your agentic AI application's LLM spend comes from. Attribute usage
4
+ to functions, agents, and workflows without changing provider call sites, then
5
+ send it to Metergraph Cloud or your self-hosted Metergraph server.
6
+
7
+ [Metergraph](https://www.metergraph.dev/) helps teams understand and optimize
8
+ agentic AI applications. This open-source, zero-runtime-dependency package
9
+ provides function-level LLM cost attribution for OpenAI, Anthropic, Gemini, and
10
+ Python Vercel AI Gateway clients. Paid Metergraph builds on that attribution
11
+ with experimentation and optimization across models, prompts, tools,
12
+ retrieval, context, batching, and caching. This package captures and
13
+ attributes usage; it does not run experiments or optimize your application.
14
+
30
15
  Initialize Metergraph once, then wrap each provider client. `init()` reads the
31
16
  token and other omitted options from the environment.
32
17
 
@@ -103,7 +88,7 @@ OpenRouter is captured the same way: point an OpenAI client at
103
88
  `reported_cost_usd` to Chat Completions rows without changing the requested model
104
89
  or the capture provider. A trusted custom domain uses
105
90
  `metergraph.wrap(client, gateway="openrouter")`. The runnable
106
- [Python OpenRouter example](../examples/python-openrouter/) covers requested-vs-
91
+ [Python OpenRouter example](../examples/integrations/providers/openrouter/python/) covers requested-vs-
107
92
  served model, reported-vs-catalog cost, streaming usage, and the BYOK limitation.
108
93
 
109
94
  ## OpenTelemetry GenAI export
@@ -125,17 +110,40 @@ from metergraph.opentelemetry import MetergraphGenAIExporter
125
110
 
126
111
  litellm.callbacks.append(OpenTelemetry(OpenTelemetryConfig(
127
112
  exporter=MetergraphGenAIExporter(),
128
- capture_message_content="SPAN_ONLY",
129
113
  )))
114
+
115
+ response = litellm.completion(
116
+ model="openai/gpt-5-mini",
117
+ messages=messages,
118
+ metadata={"generation_name": "ticket-triage"},
119
+ )
130
120
  ```
131
121
 
122
+ - LiteLLM logs message content on its spans by default. Releases before 1.85
123
+ have no `capture_message_content` option, so leave it out.
124
+ - Do not set `litellm.turn_off_message_logging`. It removes messages, tool
125
+ definitions and outputs from the spans, so MeterGraph can count the calls but
126
+ cannot analyse them.
127
+ - Name each call with `metadata={"generation_name": "<workload name>"}`.
128
+ LiteLLM uses it as the span name and MeterGraph records it as the call's
129
+ route. Without it every call is stored under the route `chat`. A
130
+ `metergraph.route` or `gen_ai.prompt.name` span attribute still takes
131
+ precedence.
132
+ - To group the calls of a multi-step agent run into one trace, make them inside
133
+ one application span and set `USE_OTEL_LITELLM_REQUEST_SPAN=true`. Without
134
+ that variable LiteLLM writes each call onto the application span itself, and
135
+ only one of the calls is recorded.
136
+ - Pass a new `metadata` dict to each call. Reusing one dict across calls makes
137
+ LiteLLM 1.103 drop spans.
138
+
132
139
  The exporter preserves OpenTelemetry trace identity, model/provider metadata,
133
140
  token usage, latency, system instructions, ordered messages, and text output.
134
- Message content is explicitly enabled because it may be sensitive. Text parts
141
+ From LiteLLM spans it also records the provider response id as the request id,
142
+ the request's tool definitions, and the tool calls in the response. Text parts
135
143
  are retained and replayable in the current POC pipeline. Calls containing other
136
144
  part types retain their model, usage, timing, and status metadata, but those
137
145
  parts are not replayable yet. See the runnable
138
- [`python-litellm-otel` example](../examples/python-litellm-otel/).
146
+ [`LiteLLM OpenTelemetry example`](../examples/integrations/telemetry/litellm/python/).
139
147
 
140
148
  The exporter reads the OpenTelemetry `gen_ai.*` conventions, OpenInference
141
149
  (Arize Phoenix), Langfuse and LangSmith spans. Dialects that label span kind
@@ -212,6 +220,20 @@ message batches are captured per inference while iterating a wrapped
212
220
  rows carry real per-result usage and the batch pricing flag; job-management
213
221
  polls themselves are not miscounted as model calls.
214
222
 
223
+ OpenAI Responses created with `background=True` are recorded once, when a
224
+ wrapped `client.responses.retrieve()` or `cancel()` first returns a terminal
225
+ status (`completed`, `failed`, `cancelled` or `incomplete`), with that
226
+ response's usage and output. Polls that still report `queued` or
227
+ `in_progress` add no rows, and latency runs from `create` to the observed
228
+ terminal response. A background response whose terminal status the process
229
+ never observes is recorded at `shutdown()` with status `abandoned` and
230
+ unknown usage, never as a completed call with zero tokens. A streamed
231
+ `retrieve(..., stream=True)` or `responses.stream(response_id=...)` resume is
232
+ observed through its terminal response event. Only retrieves made through the same wrapped client in the same process
233
+ are observed: a client derived with `with_options()` or `copy()`,
234
+ `with_raw_response`/`with_streaming_response` retrieves, and polling from a
235
+ different process leave the call to be recorded as `abandoned`.
236
+
215
237
  ## Batch-first execution (opt-in)
216
238
 
217
239
  `metergraph.batch_first()` is a separate, explicitly opt-in code path from `wrap()`/capture: submit one request through a provider's Batch API, wait up to a caller-chosen deadline, and fall back to exactly one direct call if the batch hasn't finished in time. It is synchronous/blocking, matching this SDK's own background-work model — a daemon thread, not asyncio.
@@ -248,7 +270,7 @@ codebase you want instrumented:
248
270
 
249
271
  ```text
250
272
  Instrument this codebase's LLM API costs with the `metergraph` PyPI package
251
- (https://github.com/PioneerSquareLabs/metergraphsdk): pip install metergraph,
273
+ (https://github.com/metergraph/metergraphsdk): pip install metergraph,
252
274
  then wrap every OpenAI()/AsyncOpenAI(), Anthropic()/AsyncAnthropic(), and
253
275
  genai.Client() construction in place, e.g. client = metergraph.wrap(OpenAI()).
254
276
  OpenAI or Anthropic clients pointed at https://ai-gateway.vercel.sh are Vercel
@@ -0,0 +1,49 @@
1
+ [project]
2
+ name = "metergraph"
3
+ version = "0.6.11"
4
+ description = "Zero-dependency Python SDK for function-level LLM cost attribution across major LLM providers and gateways, including OpenAI, Anthropic, Gemini, and Vercel AI Gateway."
5
+ readme = "README.md"
6
+ requires-python = ">=3.10"
7
+ license = "Apache-2.0"
8
+ authors = [{ name = "Metergraph" }]
9
+ keywords = [
10
+ "llm",
11
+ "llm-cost",
12
+ "llm-observability",
13
+ "cost-attribution",
14
+ "ai-agents",
15
+ "openai",
16
+ "anthropic",
17
+ "gemini",
18
+ "vercel-ai-sdk",
19
+ "vercel-ai-gateway",
20
+ "opentelemetry",
21
+ "self-hosted",
22
+ ]
23
+ classifiers = [
24
+ "Intended Audience :: Developers",
25
+ "Topic :: Software Development :: Libraries :: Python Modules",
26
+ "Typing :: Typed",
27
+ ]
28
+ dependencies = []
29
+
30
+ [project.urls]
31
+ Homepage = "https://www.metergraph.dev/"
32
+ Documentation = "https://github.com/metergraph/metergraphsdk/tree/main/python#readme"
33
+ Repository = "https://github.com/metergraph/metergraphsdk"
34
+ Issues = "https://github.com/metergraph/metergraphsdk/issues"
35
+ "Release notes" = "https://github.com/metergraph/metergraphsdk/releases"
36
+
37
+ [project.optional-dependencies]
38
+ otel = ["opentelemetry-sdk>=1.30"]
39
+ dev = ["build>=1", "pytest>=8", "openai>=2.50.0,<3", "anthropic>=0.40,<1", "google-genai>=1", "opentelemetry-sdk>=1.30"]
40
+
41
+ [build-system]
42
+ requires = ["setuptools>=68"]
43
+ build-backend = "setuptools.build_meta"
44
+
45
+ [tool.setuptools.packages.find]
46
+ where = ["src"]
47
+
48
+ [tool.pytest.ini_options]
49
+ testpaths = ["tests"]
@@ -10,7 +10,13 @@ import uuid
10
10
  from datetime import datetime, timezone
11
11
  from typing import Any, Callable
12
12
 
13
- from ._capture import DEFAULT_TEXT_MAX_BYTES, Options, Runtime, set_runtime
13
+ from ._capture import (
14
+ DEFAULT_TEXT_MAX_BYTES,
15
+ Options,
16
+ Runtime,
17
+ set_runtime,
18
+ )
19
+ from ._capture import finish_background_calls as _finish_background_calls
14
20
  from ._capture import wrap as _wrap
15
21
  from ._config import ConfigPoller
16
22
  from ._context import (
@@ -114,9 +120,12 @@ def init(
114
120
  if repo_config is None and not _warned_no_repository:
115
121
  _warned_no_repository = True
116
122
  log.warning(
117
- "Metergraph repository identity is not configured; set "
118
- "init(repository='owner/repository'), METERGRAPH_REPOSITORY, "
119
- "or provide .metergraph/config.json. Continuing with legacy ingestion."
123
+ "Metergraph is capturing calls normally. Repository identity is "
124
+ "optional and not set, so traces are not linked to a source "
125
+ "repository. To link them, commit .metergraph/config.json "
126
+ 'containing {"repository": "owner/name"}, set '
127
+ "METERGRAPH_REPOSITORY=owner/name, pass init(repository='owner/name'), "
128
+ "or run `metergraph setup` in the project."
120
129
  )
121
130
  session = (
122
131
  SessionManager(
@@ -289,6 +298,12 @@ def flush(timeout: float = 3.0) -> bool:
289
298
 
290
299
  def shutdown() -> None:
291
300
  global _writer, _config, _session_manager
301
+ # Background responses whose final result was never retrieved are
302
+ # recorded as abandoned before the writer drains, never as zero usage.
303
+ try:
304
+ _finish_background_calls()
305
+ except Exception:
306
+ pass
292
307
  if _config:
293
308
  _config.stop()
294
309
  _config = None
@@ -11,7 +11,9 @@ import os
11
11
  import platform
12
12
  import secrets
13
13
  import sys
14
+ import threading
14
15
  import time
16
+ from collections import OrderedDict
15
17
  from dataclasses import dataclass
16
18
  from datetime import datetime, timezone
17
19
  from pathlib import Path
@@ -1693,6 +1695,11 @@ def _patch(
1693
1695
  runtime = _runtime
1694
1696
  if runtime is None:
1695
1697
  return original(*args, **kwargs)
1698
+ if endpoint == "responses.stream" and kwargs.get("response_id") is not None:
1699
+ # Resuming an existing (background) response is not a new model
1700
+ # call: it retrieves with stream=True, and the retrieve observer
1701
+ # records the held create once from its terminal event.
1702
+ return original(*args, **kwargs)
1696
1703
  if (
1697
1704
  provider == "openai"
1698
1705
  and endpoint == "chat.completions"
@@ -1756,6 +1763,194 @@ def _safe_finish(call: CallState, response: Any = None, **kwargs: Any) -> None:
1756
1763
  pass
1757
1764
 
1758
1765
 
1766
+ # Background Responses (``background=True``) return a queued or in-progress
1767
+ # response from ``create``; output and usage arrive on a later ``retrieve`` or
1768
+ # ``cancel``. The capture is held until the client observes a terminal status,
1769
+ # then recorded once from that response. A held call the client never sees
1770
+ # finish is recorded as ``abandoned`` at shutdown (or when the bound is
1771
+ # exceeded), so it is never stored as a completed call with zero usage.
1772
+ _BACKGROUND_PENDING_STATUSES = frozenset({"queued", "in_progress"})
1773
+ _BACKGROUND_TERMINAL_STATUSES = frozenset({"completed", "failed", "cancelled", "incomplete"})
1774
+ _BACKGROUND_MAX_PENDING = 1024
1775
+ _background_lock = threading.Lock()
1776
+ _background: "OrderedDict[str, tuple[CallState, Any]]" = OrderedDict()
1777
+
1778
+
1779
+ def _clear_background_after_fork() -> None:
1780
+ # Held calls belong to the parent; the child must not record them again.
1781
+ global _background_lock
1782
+ _background_lock = threading.Lock()
1783
+ _background.clear()
1784
+
1785
+
1786
+ if hasattr(os, "register_at_fork"):
1787
+ os.register_at_fork(after_in_child=_clear_background_after_fork)
1788
+
1789
+
1790
+ def _hold_background(call: CallState, response: Any) -> bool:
1791
+ response_id = _get(response, "id")
1792
+ if not isinstance(response_id, str) or not response_id:
1793
+ return False
1794
+ evicted: list[tuple[CallState, Any]] = []
1795
+ with _background_lock:
1796
+ _background[response_id] = (call, response)
1797
+ _background.move_to_end(response_id)
1798
+ while len(_background) > _BACKGROUND_MAX_PENDING:
1799
+ evicted.append(_background.popitem(last=False)[1])
1800
+ for held, last_seen in evicted:
1801
+ _safe_finish(held, last_seen, status="abandoned")
1802
+ return True
1803
+
1804
+
1805
+ def _observe_background(response: Any) -> None:
1806
+ """Record a held background call once its response reaches a terminal
1807
+ status; a non-terminal poll only updates the last status seen."""
1808
+ try:
1809
+ status = _get(response, "status")
1810
+ response_id = _get(response, "id")
1811
+ if not isinstance(response_id, str):
1812
+ return
1813
+ if status in _BACKGROUND_PENDING_STATUSES:
1814
+ with _background_lock:
1815
+ held = _background.get(response_id)
1816
+ if held is not None:
1817
+ _background[response_id] = (held[0], response)
1818
+ return
1819
+ if status not in _BACKGROUND_TERMINAL_STATUSES:
1820
+ return
1821
+ with _background_lock:
1822
+ held = _background.pop(response_id, None)
1823
+ if held is not None:
1824
+ _safe_finish(held[0], response)
1825
+ except Exception:
1826
+ pass
1827
+
1828
+
1829
+ def _observe_background_event(event: Any) -> None:
1830
+ """Observe a streamed Responses event (``retrieve(..., stream=True)``)."""
1831
+ try:
1832
+ if str(_get(event, "type") or "").startswith("response."):
1833
+ response = _get(event, "response")
1834
+ if response is not None:
1835
+ _observe_background(response)
1836
+ except Exception:
1837
+ pass
1838
+
1839
+
1840
+ class _ObservedStream:
1841
+ """Pass a resumed background stream through unchanged, observing its
1842
+ response events so the terminal one finishes the held call."""
1843
+
1844
+ def __init__(self, stream: Any) -> None:
1845
+ self._stream = stream
1846
+
1847
+ def __getattr__(self, name: str) -> Any:
1848
+ return getattr(self._stream, name)
1849
+
1850
+ def __iter__(self):
1851
+ for event in self._stream:
1852
+ _observe_background_event(event)
1853
+ yield event
1854
+
1855
+ def __next__(self):
1856
+ event = next(self._stream)
1857
+ _observe_background_event(event)
1858
+ return event
1859
+
1860
+ def __enter__(self):
1861
+ entered = self._stream.__enter__()
1862
+ if entered is not self._stream:
1863
+ self._stream = entered
1864
+ return self
1865
+
1866
+ def __exit__(self, *exc: Any) -> Any:
1867
+ return self._stream.__exit__(*exc)
1868
+
1869
+ async def __aiter__(self):
1870
+ async for event in self._stream:
1871
+ _observe_background_event(event)
1872
+ yield event
1873
+
1874
+ async def __anext__(self):
1875
+ event = await self._stream.__anext__()
1876
+ _observe_background_event(event)
1877
+ return event
1878
+
1879
+ async def __aenter__(self):
1880
+ entered = await self._stream.__aenter__()
1881
+ if entered is not self._stream:
1882
+ self._stream = entered
1883
+ return self
1884
+
1885
+ async def __aexit__(self, *exc: Any) -> Any:
1886
+ return await self._stream.__aexit__(*exc)
1887
+
1888
+
1889
+ def _observed(result: Any, streamed: bool) -> Any:
1890
+ # Only a call that asked for a stream is wrapped, so a Response model
1891
+ # (which is itself iterable) is always returned unchanged.
1892
+ if streamed:
1893
+ try:
1894
+ if hasattr(result, "__iter__") or hasattr(result, "__aiter__"):
1895
+ return _ObservedStream(result)
1896
+ except Exception:
1897
+ pass
1898
+ return result
1899
+ _observe_background(result)
1900
+ return result
1901
+
1902
+
1903
+ def finish_background_calls(status: str = "abandoned") -> int:
1904
+ """Record every held background call whose final result was never observed."""
1905
+ with _background_lock:
1906
+ held = list(_background.values())
1907
+ _background.clear()
1908
+ for call, last_seen in held:
1909
+ _safe_finish(call, last_seen, status=status)
1910
+ return len(held)
1911
+
1912
+
1913
+ def _patch_background_observer(owner: Any, method_name: str) -> bool:
1914
+ original = getattr(owner, method_name, None)
1915
+ if not callable(original):
1916
+ return False
1917
+ if getattr(original, "__metergraph__", False):
1918
+ return True
1919
+
1920
+ @functools.wraps(original)
1921
+ def wrapped(*args, **kwargs):
1922
+ result = original(*args, **kwargs)
1923
+ streamed = kwargs.get("stream") is True
1924
+ if inspect.isawaitable(result):
1925
+
1926
+ async def await_result():
1927
+ return _observed(await result, streamed)
1928
+
1929
+ return await_result()
1930
+ return _observed(result, streamed)
1931
+
1932
+ wrapped.__metergraph__ = True # type: ignore[attr-defined]
1933
+ try:
1934
+ setattr(owner, method_name, wrapped)
1935
+ except Exception:
1936
+ return False
1937
+ return True
1938
+
1939
+
1940
+ def _apply_background_observers(client: Any) -> int:
1941
+ patched = 0
1942
+ for path in ("responses", "beta.responses"):
1943
+ try:
1944
+ owner = _resolve(client, path)
1945
+ except Exception:
1946
+ continue
1947
+ if owner is None:
1948
+ continue
1949
+ for method in ("retrieve", "cancel"):
1950
+ patched += int(_patch_background_observer(owner, method))
1951
+ return patched
1952
+
1953
+
1759
1954
  def _finish_or_stream(
1760
1955
  result: Any, call: CallState, endpoint: str, request: Mapping[str, Any]
1761
1956
  ):
@@ -1770,6 +1965,17 @@ def _finish_or_stream(
1770
1965
  or (hasattr(result, "__enter__") and hasattr(result, "__exit__"))
1771
1966
  ):
1772
1967
  return SyncStream(result, call)
1968
+ try:
1969
+ held = (
1970
+ endpoint in {"responses", "responses.parse"}
1971
+ and _get(result, "status") in _BACKGROUND_PENDING_STATUSES
1972
+ and (request.get("background") is True or _get(result, "background") is True)
1973
+ and _hold_background(call, result)
1974
+ )
1975
+ except Exception:
1976
+ held = False
1977
+ if held:
1978
+ return result
1773
1979
  _safe_finish(call, result)
1774
1980
  return result
1775
1981
 
@@ -1944,6 +2150,8 @@ def wrap(
1944
2150
  patched_count = len(patched)
1945
2151
  if not vercel:
1946
2152
  patched_count += _apply_batch_extras(client, resolved_provider)
2153
+ if resolved_provider == "openai":
2154
+ patched_count += _apply_background_observers(client)
1947
2155
  if vercel:
1948
2156
  client_label = f"Vercel AI Gateway via {resolved_provider}"
1949
2157
  elif gateway_name is not None:
@@ -687,6 +687,176 @@ _PRECEDENCE = (
687
687
  )
688
688
 
689
689
 
690
+ # LiteLLM's OpenTelemetry callback writes this on every call span it produces.
691
+ _LITELLM_CALL_ID = "litellm.call_id"
692
+ # LiteLLM's tracer, which names its spans after the caller's generation_name.
693
+ LITELLM_SCOPE = "litellm"
694
+ # Span names LiteLLM uses when the caller did not name the call.
695
+ _LITELLM_DEFAULT_SPAN_NAMES = frozenset({"litellm_request", "raw_gen_ai_request"})
696
+
697
+
698
+ def _is_litellm(attributes: Mapping[str, Any]) -> bool:
699
+ return _LITELLM_CALL_ID in attributes
700
+
701
+
702
+ def litellm_route(span_name: Any, attributes: Mapping[str, Any]) -> str | None:
703
+ """The caller's ``generation_name``, which LiteLLM writes as the span name.
704
+
705
+ None for a LiteLLM default name: ``litellm_request``, ``raw_gen_ai_request``
706
+ or the semantic-convention ``"<operation> <model>"``.
707
+ """
708
+ if not _is_litellm(attributes) or not isinstance(span_name, str):
709
+ return None
710
+ name = span_name.strip()
711
+ if not name or name in _LITELLM_DEFAULT_SPAN_NAMES:
712
+ return None
713
+ operations = {"chat", _string(attributes.get("gen_ai.operation.name")) or "chat"}
714
+ if any(name == op or name.startswith(op + " ") for op in operations):
715
+ return None
716
+ return name
717
+
718
+
719
+ def _indexed(attributes: Mapping[str, Any], prefix: str) -> dict[int, dict[str, Any]]:
720
+ """Group ``<prefix>.<i>.<field>`` attributes by index."""
721
+ grouped: dict[int, dict[str, Any]] = {}
722
+ lead = prefix + "."
723
+ for key, value in attributes.items():
724
+ if not key.startswith(lead):
725
+ continue
726
+ index, separator, rest = key[len(lead) :].partition(".")
727
+ if separator and index.isdigit() and rest:
728
+ grouped.setdefault(int(index), {})[rest] = value
729
+ return grouped
730
+
731
+
732
+ def _litellm_tools(attributes: Mapping[str, Any]) -> tuple[list[dict[str, Any]], bool]:
733
+ """Request tools from ``llm.request.functions.<i>.*``, in OpenAI chat shape."""
734
+ tools: list[dict[str, Any]] = []
735
+ degraded = False
736
+ for _, fields in sorted(_indexed(attributes, "llm.request.functions").items()):
737
+ name = _string(fields.get("name"))
738
+ if name is None:
739
+ continue
740
+ function: dict[str, Any] = {"name": name}
741
+ description = fields.get("description")
742
+ if isinstance(description, str):
743
+ function["description"] = description
744
+ parameters = fields.get("parameters")
745
+ if isinstance(parameters, str):
746
+ decoded, ok = _load_json(parameters)
747
+ function["parameters"] = decoded if ok else parameters
748
+ degraded = degraded or not ok
749
+ tools.append({"type": "function", "function": function})
750
+ return tools, degraded
751
+
752
+
753
+ def _output_message_tool_calls(attributes: Mapping[str, Any]) -> list[dict[str, Any]]:
754
+ """Output tool calls from ``tool_call`` parts of ``gen_ai.output.messages``."""
755
+ messages, ok = _load_json(attributes.get("gen_ai.output.messages"))
756
+ if not ok or not isinstance(messages, list):
757
+ return []
758
+ calls: list[dict[str, Any]] = []
759
+ for message in messages:
760
+ if not isinstance(message, Mapping) or not isinstance(message.get("parts"), list):
761
+ continue
762
+ for part in message["parts"]:
763
+ if not isinstance(part, Mapping) or part.get("type") != "tool_call":
764
+ continue
765
+ name = _string(part.get("name"))
766
+ if name is None or not name.strip():
767
+ continue
768
+ arguments = part.get("arguments")
769
+ calls.append(
770
+ {
771
+ "id": str(part.get("id") or part.get("call_id") or f"call-{len(calls)}"),
772
+ "type": "function",
773
+ "function": {
774
+ "name": name.strip(),
775
+ "arguments": arguments
776
+ if isinstance(arguments, str)
777
+ else json.dumps(arguments if arguments is not None else {}),
778
+ },
779
+ }
780
+ )
781
+ return calls
782
+
783
+
784
+ def _litellm_tool_calls(
785
+ attributes: Mapping[str, Any], response_id: str | None
786
+ ) -> list[dict[str, Any]]:
787
+ """Output tool calls from ``gen_ai.completion.<i>.function_call`` or ``.tool_calls``.
788
+
789
+ The legacy attributes carry no call id, so one is derived from the response
790
+ id and completion index exactly as the MeterGraph OTLP ingest does.
791
+ """
792
+ prefix = response_id or "completion"
793
+ calls: list[dict[str, Any]] = []
794
+
795
+ def add(call_id: Any, name: Any, arguments: Any) -> None:
796
+ name = _string(name)
797
+ if name is None or not name.strip():
798
+ return
799
+ calls.append(
800
+ {
801
+ "id": str(call_id),
802
+ "type": "function",
803
+ "function": {
804
+ "name": name.strip(),
805
+ "arguments": arguments if isinstance(arguments, str) else "",
806
+ },
807
+ }
808
+ )
809
+
810
+ for index, fields in sorted(_indexed(attributes, "gen_ai.completion").items()):
811
+ add(
812
+ f"{prefix}-{index}",
813
+ fields.get("function_call.name"),
814
+ fields.get("function_call.arguments"),
815
+ )
816
+ for position, call in sorted(_indexed(fields, "tool_calls").items()):
817
+ add(
818
+ _string(call.get("id")) or f"{prefix}-{index}-{position}",
819
+ call.get("name"),
820
+ call.get("arguments"),
821
+ )
822
+ return calls
823
+
824
+
825
+ def _apply_litellm(
826
+ attributes: Mapping[str, Any],
827
+ request: dict[str, Any],
828
+ response: dict[str, Any],
829
+ ) -> bool:
830
+ """Fill the request id, request tools and output tool calls from LiteLLM's
831
+ non-standard attributes, only where the standard ones are absent.
832
+
833
+ Returns whether any JSON was malformed.
834
+ """
835
+ response_id = _string(attributes.get("gen_ai.response.id"))
836
+ if response_id is not None and not any(
837
+ response.get(key) for key in ("_request_id", "response_id", "responseId", "id")
838
+ ):
839
+ response["id"] = response_id
840
+
841
+ degraded = False
842
+ if "tools" not in request and "gen_ai.tool.definitions" not in attributes:
843
+ tools, degraded = _litellm_tools(attributes)
844
+ if tools:
845
+ request["tools"] = tools
846
+
847
+ # The standard part carries the real call id; the legacy attributes do not.
848
+ tool_calls = _output_message_tool_calls(attributes) or _litellm_tool_calls(
849
+ attributes, response_id
850
+ )
851
+ if tool_calls:
852
+ choices = response.get("choices") or [{}]
853
+ response["choices"] = [
854
+ {**choices[0], "message": {"role": "assistant", "tool_calls": tool_calls}},
855
+ *choices[1:],
856
+ ]
857
+ return degraded
858
+
859
+
690
860
  def _first_value(contributions: list[_Fields], name: str) -> Any:
691
861
  for contribution in contributions:
692
862
  value = getattr(contribution, name)
@@ -749,6 +919,12 @@ def map_span_attributes(
749
919
  if output_structure is not None and response_text is None:
750
920
  response["output"] = output_structure
751
921
 
922
+ litellm_degraded = (
923
+ _apply_litellm(attributes, request, response)
924
+ if _is_litellm(attributes)
925
+ else False
926
+ )
927
+
752
928
  priced = next((c for c in contributions if c.cost is not None), None)
753
929
 
754
930
  dropped: set[str] = set()
@@ -769,12 +945,17 @@ def map_span_attributes(
769
945
  completion_start_time=_first_value(contributions, "completion_start_time"),
770
946
  error_message=_first_value(contributions, "error_message"),
771
947
  dialects=tuple(eligible),
772
- parse_degraded=any(
773
- contribution.parse_degraded for contribution in contributions
774
- ),
948
+ parse_degraded=litellm_degraded
949
+ or any(contribution.parse_degraded for contribution in contributions),
775
950
  usage_absent=usage_absent,
776
951
  dropped_usage_keys=tuple(sorted(dropped)),
777
952
  )
778
953
 
779
954
 
780
- __all__ = ["MappedCall", "SkipReason", "map_span_attributes"]
955
+ __all__ = [
956
+ "LITELLM_SCOPE",
957
+ "MappedCall",
958
+ "SkipReason",
959
+ "litellm_route",
960
+ "map_span_attributes",
961
+ ]
@@ -8,4 +8,4 @@ import importlib.metadata
8
8
  try:
9
9
  SDK_VERSION = importlib.metadata.version("metergraph")
10
10
  except Exception:
11
- SDK_VERSION = "0.6.9"
11
+ SDK_VERSION = "0.6.11"
@@ -18,7 +18,12 @@ from opentelemetry.trace import StatusCode
18
18
  from ._capture import _get_runtime
19
19
  from ._context import CaptureContext
20
20
  from ._failure_log import FailureLogger
21
- from ._genai_attrs import SkipReason, map_span_attributes
21
+ from ._genai_attrs import (
22
+ LITELLM_SCOPE,
23
+ SkipReason,
24
+ litellm_route,
25
+ map_span_attributes,
26
+ )
22
27
 
23
28
  _SKIP_SCOPE = "scope"
24
29
 
@@ -166,6 +171,8 @@ class MetergraphGenAIExporter(SpanExporter):
166
171
  ),
167
172
  None,
168
173
  )
174
+ if named_route is None and scope_name == LITELLM_SCOPE:
175
+ named_route = litellm_route(span.name, attributes)
169
176
  call = runtime.call_state(
170
177
  provider,
171
178
  mapped.operation,
@@ -1,7 +1,44 @@
1
+ Metadata-Version: 2.4
2
+ Name: metergraph
3
+ Version: 0.6.11
4
+ Summary: Zero-dependency Python SDK for function-level LLM cost attribution across major LLM providers and gateways, including OpenAI, Anthropic, Gemini, and Vercel AI Gateway.
5
+ Author: Metergraph
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://www.metergraph.dev/
8
+ Project-URL: Documentation, https://github.com/metergraph/metergraphsdk/tree/main/python#readme
9
+ Project-URL: Repository, https://github.com/metergraph/metergraphsdk
10
+ Project-URL: Issues, https://github.com/metergraph/metergraphsdk/issues
11
+ Project-URL: Release notes, https://github.com/metergraph/metergraphsdk/releases
12
+ Keywords: llm,llm-cost,llm-observability,cost-attribution,ai-agents,openai,anthropic,gemini,vercel-ai-sdk,vercel-ai-gateway,opentelemetry,self-hosted
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
15
+ Classifier: Typing :: Typed
16
+ Requires-Python: >=3.10
17
+ Description-Content-Type: text/markdown
18
+ Provides-Extra: otel
19
+ Requires-Dist: opentelemetry-sdk>=1.30; extra == "otel"
20
+ Provides-Extra: dev
21
+ Requires-Dist: build>=1; extra == "dev"
22
+ Requires-Dist: pytest>=8; extra == "dev"
23
+ Requires-Dist: openai<3,>=2.50.0; extra == "dev"
24
+ Requires-Dist: anthropic<1,>=0.40; extra == "dev"
25
+ Requires-Dist: google-genai>=1; extra == "dev"
26
+ Requires-Dist: opentelemetry-sdk>=1.30; extra == "dev"
27
+
1
28
  # metergraph (Python)
2
29
 
3
- Zero-runtime-dependency capture for OpenAI, Anthropic, Gemini, and Python
4
- Vercel AI Gateway clients.
30
+ See where your agentic AI application's LLM spend comes from. Attribute usage
31
+ to functions, agents, and workflows without changing provider call sites, then
32
+ send it to Metergraph Cloud or your self-hosted Metergraph server.
33
+
34
+ [Metergraph](https://www.metergraph.dev/) helps teams understand and optimize
35
+ agentic AI applications. This open-source, zero-runtime-dependency package
36
+ provides function-level LLM cost attribution for OpenAI, Anthropic, Gemini, and
37
+ Python Vercel AI Gateway clients. Paid Metergraph builds on that attribution
38
+ with experimentation and optimization across models, prompts, tools,
39
+ retrieval, context, batching, and caching. This package captures and
40
+ attributes usage; it does not run experiments or optimize your application.
41
+
5
42
  Initialize Metergraph once, then wrap each provider client. `init()` reads the
6
43
  token and other omitted options from the environment.
7
44
 
@@ -78,7 +115,7 @@ OpenRouter is captured the same way: point an OpenAI client at
78
115
  `reported_cost_usd` to Chat Completions rows without changing the requested model
79
116
  or the capture provider. A trusted custom domain uses
80
117
  `metergraph.wrap(client, gateway="openrouter")`. The runnable
81
- [Python OpenRouter example](../examples/python-openrouter/) covers requested-vs-
118
+ [Python OpenRouter example](../examples/integrations/providers/openrouter/python/) covers requested-vs-
82
119
  served model, reported-vs-catalog cost, streaming usage, and the BYOK limitation.
83
120
 
84
121
  ## OpenTelemetry GenAI export
@@ -100,17 +137,40 @@ from metergraph.opentelemetry import MetergraphGenAIExporter
100
137
 
101
138
  litellm.callbacks.append(OpenTelemetry(OpenTelemetryConfig(
102
139
  exporter=MetergraphGenAIExporter(),
103
- capture_message_content="SPAN_ONLY",
104
140
  )))
141
+
142
+ response = litellm.completion(
143
+ model="openai/gpt-5-mini",
144
+ messages=messages,
145
+ metadata={"generation_name": "ticket-triage"},
146
+ )
105
147
  ```
106
148
 
149
+ - LiteLLM logs message content on its spans by default. Releases before 1.85
150
+ have no `capture_message_content` option, so leave it out.
151
+ - Do not set `litellm.turn_off_message_logging`. It removes messages, tool
152
+ definitions and outputs from the spans, so MeterGraph can count the calls but
153
+ cannot analyse them.
154
+ - Name each call with `metadata={"generation_name": "<workload name>"}`.
155
+ LiteLLM uses it as the span name and MeterGraph records it as the call's
156
+ route. Without it every call is stored under the route `chat`. A
157
+ `metergraph.route` or `gen_ai.prompt.name` span attribute still takes
158
+ precedence.
159
+ - To group the calls of a multi-step agent run into one trace, make them inside
160
+ one application span and set `USE_OTEL_LITELLM_REQUEST_SPAN=true`. Without
161
+ that variable LiteLLM writes each call onto the application span itself, and
162
+ only one of the calls is recorded.
163
+ - Pass a new `metadata` dict to each call. Reusing one dict across calls makes
164
+ LiteLLM 1.103 drop spans.
165
+
107
166
  The exporter preserves OpenTelemetry trace identity, model/provider metadata,
108
167
  token usage, latency, system instructions, ordered messages, and text output.
109
- Message content is explicitly enabled because it may be sensitive. Text parts
168
+ From LiteLLM spans it also records the provider response id as the request id,
169
+ the request's tool definitions, and the tool calls in the response. Text parts
110
170
  are retained and replayable in the current POC pipeline. Calls containing other
111
171
  part types retain their model, usage, timing, and status metadata, but those
112
172
  parts are not replayable yet. See the runnable
113
- [`python-litellm-otel` example](../examples/python-litellm-otel/).
173
+ [`LiteLLM OpenTelemetry example`](../examples/integrations/telemetry/litellm/python/).
114
174
 
115
175
  The exporter reads the OpenTelemetry `gen_ai.*` conventions, OpenInference
116
176
  (Arize Phoenix), Langfuse and LangSmith spans. Dialects that label span kind
@@ -187,6 +247,20 @@ message batches are captured per inference while iterating a wrapped
187
247
  rows carry real per-result usage and the batch pricing flag; job-management
188
248
  polls themselves are not miscounted as model calls.
189
249
 
250
+ OpenAI Responses created with `background=True` are recorded once, when a
251
+ wrapped `client.responses.retrieve()` or `cancel()` first returns a terminal
252
+ status (`completed`, `failed`, `cancelled` or `incomplete`), with that
253
+ response's usage and output. Polls that still report `queued` or
254
+ `in_progress` add no rows, and latency runs from `create` to the observed
255
+ terminal response. A background response whose terminal status the process
256
+ never observes is recorded at `shutdown()` with status `abandoned` and
257
+ unknown usage, never as a completed call with zero tokens. A streamed
258
+ `retrieve(..., stream=True)` or `responses.stream(response_id=...)` resume is
259
+ observed through its terminal response event. Only retrieves made through the same wrapped client in the same process
260
+ are observed: a client derived with `with_options()` or `copy()`,
261
+ `with_raw_response`/`with_streaming_response` retrieves, and polling from a
262
+ different process leave the call to be recorded as `abandoned`.
263
+
190
264
  ## Batch-first execution (opt-in)
191
265
 
192
266
  `metergraph.batch_first()` is a separate, explicitly opt-in code path from `wrap()`/capture: submit one request through a provider's Batch API, wait up to a caller-chosen deadline, and fall back to exactly one direct call if the batch hasn't finished in time. It is synchronous/blocking, matching this SDK's own background-work model — a daemon thread, not asyncio.
@@ -223,7 +297,7 @@ codebase you want instrumented:
223
297
 
224
298
  ```text
225
299
  Instrument this codebase's LLM API costs with the `metergraph` PyPI package
226
- (https://github.com/PioneerSquareLabs/metergraphsdk): pip install metergraph,
300
+ (https://github.com/metergraph/metergraphsdk): pip install metergraph,
227
301
  then wrap every OpenAI()/AsyncOpenAI(), Anthropic()/AsyncAnthropic(), and
228
302
  genai.Client() construction in place, e.g. client = metergraph.wrap(OpenAI()).
229
303
  OpenAI or Anthropic clients pointed at https://ai-gateway.vercel.sh are Vercel
@@ -1,34 +0,0 @@
1
- [project]
2
- name = "metergraph"
3
- version = "0.6.9"
4
- description = "Fire-and-forget LLM spend capture for Metergraph"
5
- readme = "README.md"
6
- requires-python = ">=3.10"
7
- license = "Apache-2.0"
8
- authors = [{ name = "Pioneer Square Labs" }]
9
- keywords = ["llm", "observability", "openai", "anthropic", "gemini", "vercel-ai-gateway", "cost-tracking"]
10
- classifiers = [
11
- "Intended Audience :: Developers",
12
- "Topic :: Software Development :: Libraries :: Python Modules",
13
- "Typing :: Typed",
14
- ]
15
- dependencies = []
16
-
17
- [project.urls]
18
- Homepage = "https://www.metergraph.dev/"
19
- Repository = "https://github.com/PioneerSquareLabs/metergraphsdk"
20
- Issues = "https://github.com/PioneerSquareLabs/metergraphsdk/issues"
21
-
22
- [project.optional-dependencies]
23
- otel = ["opentelemetry-sdk>=1.30"]
24
- dev = ["build>=1", "pytest>=8", "openai>=2.50.0,<3", "anthropic>=0.40,<1", "google-genai>=1", "opentelemetry-sdk>=1.30"]
25
-
26
- [build-system]
27
- requires = ["setuptools>=68"]
28
- build-backend = "setuptools.build_meta"
29
-
30
- [tool.setuptools.packages.find]
31
- where = ["src"]
32
-
33
- [tool.pytest.ini_options]
34
- testpaths = ["tests"]
File without changes
File without changes