metergraph 0.2.1__tar.gz → 0.3.2__tar.gz

{metergraph-0.2.1 → metergraph-0.3.2}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: metergraph
-Version: 0.2.1
+Version: 0.3.2
 Summary: Fire-and-forget LLM spend capture for Metergraph
 Author: Pioneer Square Labs
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://www.metergraph.dev/
 Project-URL: Repository, https://github.com/PioneerSquareLabs/metergraphsdk
 Project-URL: Issues, https://github.com/PioneerSquareLabs/metergraphsdk/issues
-Keywords: llm,observability,openai,anthropic,gemini,cost-tracking
+Keywords: llm,observability,openai,anthropic,gemini,vercel-ai-gateway,cost-tracking
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
@@ -21,7 +21,8 @@ Requires-Dist: google-genai>=1; extra == "dev"
 
 # metergraph (Python)
 
-Zero-runtime-dependency capture for OpenAI, Anthropic, and Gemini clients.
+Zero-runtime-dependency capture for OpenAI, Anthropic, Gemini, and Python
+Vercel AI Gateway clients.
 `wrap()` initializes capture from the environment, so setup is one line per
 client; call `metergraph.init(...)` before the first `wrap()` only to pass
 options in code.
@@ -34,9 +35,10 @@ from openai import OpenAI
 client = metergraph.wrap(OpenAI())
 metergraph.set_session("ticket-123")
 
-with metergraph.route("ticket-classifier", unit="answer", capture_text=True):
-    model = metergraph.model_for("ticket-classifier", default="gpt-4.1-mini")
-    client.chat.completions.create(model=model, messages=[...])
+with metergraph.trace("ticket-workflow"):
+    with metergraph.route("ticket-classifier", unit="answer"):
+        model = metergraph.model_for("ticket-classifier", default="gpt-4.1-mini")
+        client.chat.completions.create(model=model, messages=[...])
 
 # Emit this after the user-visible task resolves. It shares the bounded async
 # transport and contains no prompt or output content.
@@ -50,19 +52,59 @@ metergraph.record_outcome(
 )
 ```
 
+Vercel's supported Python surface is AI Gateway through the OpenAI or
+Anthropic SDK. Point either client at the public gateway and `wrap()` detects
+it automatically:
+
+```python
+import os
+import metergraph
+from openai import OpenAI
+
+gateway = metergraph.wrap(OpenAI(
+    api_key=os.getenv("AI_GATEWAY_API_KEY") or os.getenv("VERCEL_OIDC_TOKEN"),
+    base_url="https://ai-gateway.vercel.sh/v1",
+))
+
+gateway.chat.completions.create(
+    model="anthropic/claude-sonnet-4.6",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+Creator-qualified model IDs are normalized for gateway catalog pricing. Sync,
+async, streaming, tool calls, and OpenAI Responses API calls are captured. Use
+`metergraph.wrap(client, provider="vercel")` only when a compatible client is
+behind a custom gateway URL that cannot be detected automatically.
+
 Configuration:
 
 - `METERGRAPH_APP_TOKEN` — required bearer token
 - `METERGRAPH_INGEST_URL` — optional override; defaults to the hosted HTTPS endpoint
-- `METERGRAPH_CAPTURE_TEXT=1` — opt in to content capture globally; default is metadata-only
+- `METERGRAPH_CAPTURE_TEXT=0` — opt out of content capture globally
 - `METERGRAPH_DISABLED=1` — process kill switch
 - `METERGRAPH_QUEUE_SIZE`, `METERGRAPH_BATCH_SIZE`, `METERGRAPH_FLUSH_SECONDS`
 
 Delivery is bounded and off the request path. Queue overflow or a collector
 outage drops capture and increments internal counters; it never changes the
 provider call. Each wire batch is bounded to 512 KiB after optional gzip.
-`capture_text=True` or `False` on `route()` overrides the global content policy
-for that route. Config reads are ETag-aware and fail open to the default model.
+SDK 0.3 captures the scrubbed provider request and a normalized response
+envelope, including assistant content and tool calls, by default. Provider
+credentials and transport headers are removed. Request and response are each
+limited to 100 KiB of UTF-8 with an explicit truncation marker.
+`capture_text=False` on `route()` or `trace()` overrides the global content
+policy for a sensitive operation. The equivalent initialization option is
+`metergraph.init(capture_text=False)`. The public open-source server continues
+to discard content even when the SDK sends it; the hosted dashboard retains
+content under the workspace retention period.
+
+`metergraph.trace(name, trace_id=..., parent_span_id=...)` is a sync/async
+context manager and decorator. Calls inside one trace share a trace ID and
+receive distinct span IDs. Calls outside a trace become deterministic
+single-span traces after ingestion. Manual IDs can join work across process
+boundaries; automatic W3C HTTP propagation is not included.
+
+Config reads are ETag-aware and fail open to the default model.
 `record_outcome` requires a stable session ID and the model actually used so a
 session-sticky canary can compare task completion and optional feedback,
 turn-count, escalation, abandonment, edit-distance, and regeneration signals.
@@ -85,14 +127,21 @@ Instrument this codebase's LLM API costs with the `metergraph` PyPI package
 (https://github.com/PioneerSquareLabs/metergraphsdk): pip install metergraph,
 then wrap every OpenAI()/AsyncOpenAI(), Anthropic()/AsyncAnthropic(), and
 genai.Client() construction in place, e.g. client = metergraph.wrap(OpenAI()).
+OpenAI or Anthropic clients pointed at https://ai-gateway.vercel.sh are Vercel
+AI Gateway clients and are detected automatically; keep their creator/model ID
+and AI_GATEWAY_API_KEY / VERCEL_OIDC_TOKEN configuration unchanged.
 wrap() returns the same client and initializes itself from the environment:
 METERGRAPH_APP_TOKEN is required (capture is silently off without it) and
 METERGRAPH_INGEST_URL is only for self-hosted servers. Add both to
-.env.example, and never commit a real token. Capture is metadata-only (tokens,
-latency, model, no prompt/completion content) and fail-open, so do not change
-call sites, arguments, or error handling; sync, async, and streaming work
-unchanged. Attribution to the calling function is automatic; optionally pin
-stable names on key LLM-calling functions with @metergraph.track. On
+.env.example, and never commit a real token. SDK 0.3 captures scrubbed provider
+requests and normalized responses by default for the hosted dashboard; use
+METERGRAPH_CAPTURE_TEXT=0 or capture_text=False around sensitive operations.
+Provider credentials and transport headers must never be captured. Capture is
+fail-open, so do not change call sites, arguments, or error handling; sync,
+async, and streaming work unchanged. Use metergraph.trace("stable-name") to
+group multi-call workflows. Attribution to the calling function is automatic;
+optionally pin stable names on key LLM-calling functions with
+@metergraph.track. On
 serverless, call metergraph.flush() before the handler returns. When done,
 list every client you wrapped and flag LLM calls made outside the official
 openai / anthropic / google-genai SDKs, since those are not captured.

metergraph-0.3.2/README.md

@@ -0,0 +1,127 @@
+# metergraph (Python)
+
+Zero-runtime-dependency capture for OpenAI, Anthropic, Gemini, and Python
+Vercel AI Gateway clients.
+`wrap()` initializes capture from the environment, so setup is one line per
+client; call `metergraph.init(...)` before the first `wrap()` only to pass
+options in code.
+
+```python
+import metergraph
+from openai import OpenAI
+
+# Anthropic() and google-genai's genai.Client() wrap the same way.
+client = metergraph.wrap(OpenAI())
+metergraph.set_session("ticket-123")
+
+with metergraph.trace("ticket-workflow"):
+    with metergraph.route("ticket-classifier", unit="answer"):
+        model = metergraph.model_for("ticket-classifier", default="gpt-4.1-mini")
+        client.chat.completions.create(model=model, messages=[...])
+
+# Emit this after the user-visible task resolves. It shares the bounded async
+# transport and contains no prompt or output content.
+metergraph.record_outcome(
+    "ticket-classifier",
+    model=model,
+    task_completed=True,
+    feedback_score=1,
+    turns_to_resolution=2,
+    escalated=False,
+)
+```
+
+Vercel's supported Python surface is AI Gateway through the OpenAI or
+Anthropic SDK. Point either client at the public gateway and `wrap()` detects
+it automatically:
+
+```python
+import os
+import metergraph
+from openai import OpenAI
+
+gateway = metergraph.wrap(OpenAI(
+    api_key=os.getenv("AI_GATEWAY_API_KEY") or os.getenv("VERCEL_OIDC_TOKEN"),
+    base_url="https://ai-gateway.vercel.sh/v1",
+))
+
+gateway.chat.completions.create(
+    model="anthropic/claude-sonnet-4.6",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+Creator-qualified model IDs are normalized for gateway catalog pricing. Sync,
+async, streaming, tool calls, and OpenAI Responses API calls are captured. Use
+`metergraph.wrap(client, provider="vercel")` only when a compatible client is
+behind a custom gateway URL that cannot be detected automatically.
+
+Configuration:
+
+- `METERGRAPH_APP_TOKEN` — required bearer token
+- `METERGRAPH_INGEST_URL` — optional override; defaults to the hosted HTTPS endpoint
+- `METERGRAPH_CAPTURE_TEXT=0` — opt out of content capture globally
+- `METERGRAPH_DISABLED=1` — process kill switch
+- `METERGRAPH_QUEUE_SIZE`, `METERGRAPH_BATCH_SIZE`, `METERGRAPH_FLUSH_SECONDS`
+
+Delivery is bounded and off the request path. Queue overflow or a collector
+outage drops capture and increments internal counters; it never changes the
+provider call. Each wire batch is bounded to 512 KiB after optional gzip.
+SDK 0.3 captures the scrubbed provider request and a normalized response
+envelope, including assistant content and tool calls, by default. Provider
+credentials and transport headers are removed. Request and response are each
+limited to 100 KiB of UTF-8 with an explicit truncation marker.
+`capture_text=False` on `route()` or `trace()` overrides the global content
+policy for a sensitive operation. The equivalent initialization option is
+`metergraph.init(capture_text=False)`. The public open-source server continues
+to discard content even when the SDK sends it; the hosted dashboard retains
+content under the workspace retention period.
+
+`metergraph.trace(name, trace_id=..., parent_span_id=...)` is a sync/async
+context manager and decorator. Calls inside one trace share a trace ID and
+receive distinct span IDs. Calls outside a trace become deterministic
+single-span traces after ingestion. Manual IDs can join work across process
+boundaries; automatic W3C HTTP propagation is not included.
+
+Config reads are ETag-aware and fail open to the default model.
+`record_outcome` requires a stable session ID and the model actually used so a
+session-sticky canary can compare task completion and optional feedback,
+turn-count, escalation, abandonment, edit-distance, and regeneration signals.
+
+OpenAI Batch API output JSONL is captured per inference when a wrapped
+`client.files.content()` / `retrieve_content()` result is read. Anthropic
+message batches are captured per inference while iterating a wrapped
+`client.messages.batches.results()` result. Run result consumption inside a
+`route()` context so the asynchronous batch retains its product route. Batch
+rows carry real per-result usage and the batch pricing flag; job-management
+polls themselves are not miscounted as model calls.
+
+## Set up with an AI coding agent
+
+Paste this into Claude Code, Codex, Cursor, or any coding agent inside the
+codebase you want instrumented:
+
+```text
+Instrument this codebase's LLM API costs with the `metergraph` PyPI package
+(https://github.com/PioneerSquareLabs/metergraphsdk): pip install metergraph,
+then wrap every OpenAI()/AsyncOpenAI(), Anthropic()/AsyncAnthropic(), and
+genai.Client() construction in place, e.g. client = metergraph.wrap(OpenAI()).
+OpenAI or Anthropic clients pointed at https://ai-gateway.vercel.sh are Vercel
+AI Gateway clients and are detected automatically; keep their creator/model ID
+and AI_GATEWAY_API_KEY / VERCEL_OIDC_TOKEN configuration unchanged.
+wrap() returns the same client and initializes itself from the environment:
+METERGRAPH_APP_TOKEN is required (capture is silently off without it) and
+METERGRAPH_INGEST_URL is only for self-hosted servers. Add both to
+.env.example, and never commit a real token. SDK 0.3 captures scrubbed provider
+requests and normalized responses by default for the hosted dashboard; use
+METERGRAPH_CAPTURE_TEXT=0 or capture_text=False around sensitive operations.
+Provider credentials and transport headers must never be captured. Capture is
+fail-open, so do not change call sites, arguments, or error handling; sync,
+async, and streaming work unchanged. Use metergraph.trace("stable-name") to
+group multi-call workflows. Attribution to the calling function is automatic;
+optionally pin stable names on key LLM-calling functions with
+@metergraph.track. On
+serverless, call metergraph.flush() before the handler returns. When done,
+list every client you wrapped and flag LLM calls made outside the official
+openai / anthropic / google-genai SDKs, since those are not captured.
+```

{metergraph-0.2.1 → metergraph-0.3.2}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "metergraph"
-version = "0.2.1"
+version = "0.3.2"
 description = "Fire-and-forget LLM spend capture for Metergraph"
 readme = "README.md"
 requires-python = ">=3.10"
 license = "Apache-2.0"
 authors = [{ name = "Pioneer Square Labs" }]
-keywords = ["llm", "observability", "openai", "anthropic", "gemini", "cost-tracking"]
+keywords = ["llm", "observability", "openai", "anthropic", "gemini", "vercel-ai-gateway", "cost-tracking"]
 classifiers = [
     "Intended Audience :: Developers",
     "Topic :: Software Development :: Libraries :: Python Modules",

{metergraph-0.2.1 → metergraph-0.3.2}/src/metergraph/__init__.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import atexit
 import logging
+import math
 import os
 import uuid
 from datetime import datetime, timezone
@@ -12,7 +13,7 @@ from typing import Any, Callable
 from ._capture import Options, Runtime, set_runtime
 from ._capture import wrap as _wrap
 from ._config import ConfigPoller
-from ._context import route, set_session, set_tags, snapshot, wrap_executor
+from ._context import route, set_session, set_tags, snapshot, trace, wrap_executor
 from ._track import track
 from ._transport import Writer
 from ._version import SDK_VERSION
@@ -73,7 +74,7 @@ def init(
         )
         options = Options(
             capture_text=(
-                _env_bool("METERGRAPH_CAPTURE_TEXT", False)
+                _env_bool("METERGRAPH_CAPTURE_TEXT", True)
                 if capture_text is None
                 else capture_text
             ),
@@ -81,7 +82,17 @@ def init(
             app_root=os.path.realpath(app_root or os.getcwd()),
             skip_frames=tuple(skip_frames or ()),
             environment=environment or os.getenv("METERGRAPH_ENV"),
-            text_max_bytes=int(os.getenv("METERGRAPH_TEXT_MAX_BYTES", "100000")),
+            text_max_bytes=min(
+                100 * 1024,
+                max(
+                    1,
+                    int(
+                        os.getenv(
+                            "METERGRAPH_TEXT_MAX_BYTES", str(100 * 1024)
+                        )
+                    ),
+                ),
+            ),
         )
         set_runtime(Runtime(_writer, options))
         _config = ConfigPoller(
@@ -105,10 +116,13 @@ def init(
 
 
 def wrap(client: Any, *, provider: str | None = None) -> Any:
-    """Wrap an OpenAI, Anthropic, or Google client for capture.
+    """Wrap an OpenAI, Anthropic, Google, or Vercel AI Gateway client.
 
     Calls init() automatically, so with env-var configuration this is the
-    only setup line needed. Call init(...) first to pass options in code.
+    only setup line needed. OpenAI and Anthropic clients using Vercel's public
+    AI Gateway URL are detected automatically; pass ``provider="vercel"`` to
+    force gateway handling for a compatible client with a custom URL. Call
+    init(...) first to pass Metergraph options in code.
     """
     init()
     return _wrap(client, provider=provider)
@@ -144,26 +158,33 @@ def record_outcome(
     event_id = str(event_id or uuid.uuid4()).strip()[:128]
     try:
         feedback_score = float(feedback_score) if feedback_score is not None else None
-        turns_to_resolution = (
-            int(turns_to_resolution) if turns_to_resolution is not None else None
-        )
         edit_distance_ratio = (
             float(edit_distance_ratio) if edit_distance_ratio is not None else None
         )
-        regeneration_count = (
-            int(regeneration_count) if regeneration_count is not None else None
-        )
     except (TypeError, ValueError, OverflowError):
         return False
     if not route_name or not model or not session_key or not event_id:
         return False
-    if feedback_score is not None and not -1 <= feedback_score <= 1:
+    if feedback_score is not None and (
+        not math.isfinite(feedback_score) or not -1 <= feedback_score <= 1
+    ):
         return False
-    if turns_to_resolution is not None and not 1 <= turns_to_resolution <= 1_000_000:
+    if turns_to_resolution is not None and (
+        isinstance(turns_to_resolution, bool)
+        or not isinstance(turns_to_resolution, int)
+        or not 1 <= turns_to_resolution <= 1_000_000
+    ):
         return False
-    if edit_distance_ratio is not None and not 0 <= edit_distance_ratio <= 1:
+    if edit_distance_ratio is not None and (
+        not math.isfinite(edit_distance_ratio)
+        or not 0 <= edit_distance_ratio <= 1
+    ):
         return False
-    if regeneration_count is not None and not 0 <= regeneration_count <= 1_000_000:
+    if regeneration_count is not None and (
+        isinstance(regeneration_count, bool)
+        or not isinstance(regeneration_count, int)
+        or not 0 <= regeneration_count <= 1_000_000
+    ):
         return False
     if escalated is not None and not isinstance(escalated, bool):
         return False
@@ -214,6 +235,7 @@ __all__ = [
     "set_tags",
     "shutdown",
     "track",
+    "trace",
     "wrap",
     "wrap_executor",
 ]