metergraph 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph
-Version: 0.2.1
+Version: 0.3.0
 Summary: Fire-and-forget LLM spend capture for Metergraph
 Author: Pioneer Square Labs
 License-Expression: Apache-2.0
@@ -34,9 +34,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.
@@ -54,15 +55,30 @@ 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.
@@ -88,11 +104,15 @@ genai.Client() construction in place, e.g. client = metergraph.wrap(OpenAI()).
 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.2.1 → metergraph-0.3.0}/README.md

@@ -13,9 +13,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.
@@ -33,15 +34,30 @@ 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.
@@ -67,11 +83,15 @@ genai.Client() construction in place, e.g. client = metergraph.wrap(OpenAI()).
 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.2.1 → metergraph-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metergraph"
-version = "0.2.1"
+version = "0.3.0"
 description = "Fire-and-forget LLM spend capture for Metergraph"
 readme = "README.md"
 requires-python = ">=3.10"

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

@@ -12,7 +12,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 +73,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 +81,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(
@@ -214,6 +224,7 @@ __all__ = [
     "set_tags",
     "shutdown",
     "track",
+    "trace",
     "wrap",
     "wrap_executor",
 ]

{metergraph-0.2.1 → metergraph-0.3.0}/src/metergraph/_capture.py

@@ -8,6 +8,7 @@ import json
 import logging
 import os
 import platform
+import secrets
 import sys
 import time
 from dataclasses import dataclass
@@ -223,11 +224,68 @@ def _request_id(response: Any) -> str | None:
     value = (
         _get(response, "_request_id")
         or _get(response, "response_id")
+        or _get(response, "responseId")
         or _get(response, "id")
     )
     return str(value) if value is not None else None
 
 
+def _response_content(response: Any, aggregate_text: str | None = None) -> Any:
+    if aggregate_text is not None:
+        return aggregate_text
+    direct = _get(response, "output_text") or _get(response, "text")
+    if direct is not None:
+        return scrub(direct)
+    choice = _first(_get(response, "choices"))
+    message = _get(choice, "message")
+    content = _get(message, "content")
+    if content is not None:
+        return scrub(content)
+    parsed = _get(message, "parsed")
+    if parsed is not None:
+        return scrub(parsed)
+    normalized_text = _response_text(response)
+    if normalized_text is not None:
+        return normalized_text
+    blocks = _get(response, "content")
+    if blocks is not None:
+        return scrub(blocks)
+    outputs = _get(response, "output")
+    if outputs is not None:
+        return scrub(outputs)
+    candidates = _get(response, "candidates")
+    if candidates is not None:
+        return scrub(candidates)
+    return None
+
+
+def _response_envelope(
+    response: Any,
+    *,
+    aggregate_text: str | None,
+    tool_calls: list[dict] | None,
+    error: BaseException | None,
+    status: str,
+) -> dict[str, Any]:
+    envelope: dict[str, Any] = {
+        "role": "assistant",
+        "content": _response_content(response, aggregate_text),
+        "tool_calls": tool_calls or [],
+        "finish_reason": _stop_reason(response),
+        "request_id": _request_id(response),
+        "model": _get(response, "model")
+        or _get(response, "model_version")
+        or _get(response, "modelVersion"),
+        "status": status,
+    }
+    if error is not None:
+        envelope["error"] = {
+            "type": type(error).__name__,
+            "message": str(error),
+        }
+    return {key: value for key, value in envelope.items() if value is not None}
+
+
 def _tool_names(request: Mapping[str, Any]) -> list[dict[str, str]] | None:
     tools = request.get("tools")
     if not isinstance(tools, list):
@@ -273,7 +331,11 @@ def _tool_policies(request: Mapping[str, Any]) -> dict[str, str]:
     return policies
 
 
-def _tool_events(request: Mapping[str, Any], response: Any) -> list[dict] | None:
+def _tool_events(
+    request: Mapping[str, Any],
+    response: Any,
+    stream_chunks: list[Any] | None = None,
+) -> list[dict] | None:
     """Normalize completed history and newly requested provider tool calls."""
     policies = _tool_policies(request)
     calls: dict[str, dict] = {}
@@ -320,9 +382,37 @@ def _tool_events(request: Mapping[str, Any], response: Any) -> list[dict] | None
                     bool(_get(block, "is_error", False)),
                 )
 
+    def gemini_parts(value: Any) -> None:
+        parts = _get(value, "parts")
+        if not isinstance(parts, list):
+            return
+        for part in parts:
+            function_call = _get(part, "function_call") or _get(
+                part, "functionCall"
+            )
+            if function_call is not None:
+                call(
+                    _get(function_call, "id"),
+                    _get(function_call, "name"),
+                    _get(function_call, "args")
+                    or _get(function_call, "arguments"),
+                )
+            function_response = _get(part, "function_response") or _get(
+                part, "functionResponse"
+            )
+            if function_response is not None:
+                complete(
+                    _get(function_response, "id")
+                    or _get(function_response, "name"),
+                    _get(function_response, "response"),
+                    False,
+                )
+
     history = request.get("messages")
     if not isinstance(history, list):
         history = request.get("input")
+    if not isinstance(history, list):
+        history = request.get("contents")
     if isinstance(history, list):
         for message in history:
             for tool_call in _get(message, "tool_calls", []) or []:
@@ -353,6 +443,7 @@ def _tool_events(request: Mapping[str, Any], response: Any) -> list[dict] | None
                     bool(_get(message, "is_error", False)),
                 )
             content_blocks(_get(message, "content"))
+            gemini_parts(message)
 
     choice = _first(_get(response, "choices"))
     response_message = _get(choice, "message")
@@ -372,6 +463,60 @@ def _tool_events(request: Mapping[str, Any], response: Any) -> list[dict] | None
                 _get(output, "name"),
                 _get(output, "arguments"),
             )
+    for candidate in _get(response, "candidates", []) or []:
+        gemini_parts(_get(candidate, "content"))
+
+    openai_deltas: dict[str, dict[str, str]] = {}
+    anthropic_deltas: dict[str, dict[str, str]] = {}
+    for chunk in stream_chunks or []:
+        for choice in _get(chunk, "choices", []) or []:
+            delta = _get(choice, "delta")
+            for position, tool_call in enumerate(
+                _get(delta, "tool_calls", []) or []
+            ):
+                key = str(
+                    _get(tool_call, "index")
+                    if _get(tool_call, "index") is not None
+                    else position
+                )
+                item = openai_deltas.setdefault(
+                    key, {"id": key, "name": "", "arguments": ""}
+                )
+                if _get(tool_call, "id"):
+                    item["id"] = str(_get(tool_call, "id"))
+                fn = _get(tool_call, "function")
+                if _get(fn, "name"):
+                    item["name"] += str(_get(fn, "name"))
+                if _get(fn, "arguments"):
+                    item["arguments"] += str(_get(fn, "arguments"))
+        kind = _get(chunk, "type")
+        if kind == "content_block_start":
+            block = _get(chunk, "content_block")
+            if _get(block, "type") == "tool_use":
+                key = str(_get(chunk, "index", len(anthropic_deltas)))
+                initial_input = scrub(_get(block, "input", {}))
+                anthropic_deltas[key] = {
+                    "id": str(_get(block, "id") or key),
+                    "name": str(_get(block, "name") or ""),
+                    "arguments": (
+                        ""
+                        if initial_input == {}
+                        else json.dumps(initial_input, separators=(",", ":"))
+                    ),
+                }
+        elif kind == "content_block_delta":
+            delta = _get(chunk, "delta")
+            if _get(delta, "type") == "input_json_delta":
+                key = str(_get(chunk, "index", "0"))
+                item = anthropic_deltas.setdefault(
+                    key, {"id": key, "name": "", "arguments": ""}
+                )
+                item["arguments"] += str(_get(delta, "partial_json") or "")
+        for candidate in _get(chunk, "candidates", []) or []:
+            gemini_parts(_get(candidate, "content"))
+    for item in [*openai_deltas.values(), *anthropic_deltas.values()]:
+        if item["name"]:
+            call(item["id"], item["name"], item["arguments"])
 
     return [calls[key] for key in order] or None
 
@@ -399,12 +544,12 @@ def _capture_frames(
 
 @dataclass
 class Options:
-    capture_text: bool = False
+    capture_text: bool = True
     redact: Callable[[str, str], str] | None = None
     app_root: str = os.getcwd()
     skip_frames: tuple[str, ...] = ()
     environment: str | None = None
-    text_max_bytes: int = 100_000
+    text_max_bytes: int = 100 * 1024
 
 
 class Runtime:
@@ -442,6 +587,14 @@ class Runtime:
             func=context.func_name or func,
             module=context.func_module or module,
             frames=frames,
+            trace_id=context.trace_id or secrets.token_hex(16),
+            span_id=secrets.token_hex(8),
+            parent_span_id=context.parent_span_id,
+            trace_name=context.trace_name
+            or context.route
+            or context.func_name
+            or func
+            or endpoint,
         )
 
     def _text(
@@ -476,6 +629,10 @@ class CallState:
     func: str | None
     module: str | None
     frames: list[dict]
+    trace_id: str
+    span_id: str
+    parent_span_id: str | None
+    trace_name: str
     done: bool = False
 
     def finish(
@@ -487,6 +644,7 @@ class CallState:
         stream: bool = False,
         ttft_ms: int | None = None,
         response_text: str | None = None,
+        stream_chunks: list[Any] | None = None,
     ) -> None:
         if self.done:
             return
@@ -502,17 +660,13 @@ class CallState:
             "request",
             enabled=capture_text,
         )
-        response_json, response_truncated = self.runtime._text(
-            response_text if response_text is not None else _response_text(response),
-            "response",
-            enabled=capture_text,
-        )
-        tool_calls = _tool_events(request_clean, response)
+        full_tool_calls = _tool_events(request_clean, response, stream_chunks)
+        tool_calls = full_tool_calls
         tool_truncated = False
         if tool_calls and capture_text:
             encoded_tools, tool_truncated = self.runtime._text(
                 json.dumps(tool_calls, separators=(",", ":"), default=repr),
-                "tool_calls",
+                "response",
                 enabled=True,
             )
             try:
@@ -529,6 +683,25 @@ class CallState:
                 }
                 for item in tool_calls
             ]
+        effective_status = status or (
+            "error" if error else _stop_reason(response) or "success"
+        )
+        response_json, response_truncated = self.runtime._text(
+            json.dumps(
+                _response_envelope(
+                    response,
+                    aggregate_text=response_text,
+                    tool_calls=full_tool_calls if capture_text else None,
+                    error=error,
+                    status=effective_status,
+                ),
+                ensure_ascii=False,
+                separators=(",", ":"),
+                default=repr,
+            ),
+            "response",
+            enabled=capture_text,
+        )
         row: dict[str, Any] = {
             "ts": self.ts,
             "route": self.context.route,
@@ -536,10 +709,13 @@ class CallState:
             "model": self.request.get("model"),
             **_usage(response),
             "latency_ms": round((time.perf_counter() - self.started) * 1000),
-            "status": status
-            or ("error" if error else _stop_reason(response) or "success"),
+            "status": effective_status,
             "session_id": self.context.session_id,
             "conversation_id": self.context.session_id,
+            "trace_id": self.trace_id,
+            "span_id": self.span_id,
+            "parent_span_id": self.parent_span_id,
+            "trace_name": self.trace_name,
             "template_hash": template_hash(self.request),
             "unit_name": self.context.unit_name,
             "unit_count": self.context.unit_count,
@@ -548,8 +724,8 @@ class CallState:
             "request_id": _request_id(response),
             "batch": self.request.get("batch") is True,
             "batch_custom_id": self.request.get("batch_custom_id"),
-            # The worker requires an explicit positive stamp before sending
-            # any content to Bedrock. Missing/old rows therefore fail closed.
+            # An explicit false is the application-level sensitive-operation
+            # opt-out. Hosted ingestion otherwise preserves available content.
             "content_opted_in": capture_text,
             "request_json": request_json,
             "response_text": response_json,
@@ -580,10 +756,12 @@ class _StreamState:
         self.iterator = None
         self.last = None
         self.parts: list[str] = []
+        self.chunks: list[Any] = []
         self.ttft_ms: int | None = None
 
     def chunk(self, value: Any) -> Any:
         self.last = value
+        self.chunks.append(value)
         text = _chunk_text(value)
         if text:
             if self.ttft_ms is None:
@@ -614,6 +792,7 @@ class _StreamState:
             stream=True,
             ttft_ms=self.ttft_ms,
             response_text="".join(self.parts) or None,
+            stream_chunks=self.chunks,
         )
 
     async def finish_async(
@@ -636,6 +815,7 @@ class _StreamState:
             stream=True,
             ttft_ms=self.ttft_ms,
             response_text="".join(self.parts) or None,
+            stream_chunks=self.chunks,
         )
 
 
@@ -754,6 +934,7 @@ class AsyncStream:
                     stream=True,
                     ttft_ms=self._state.ttft_ms,
                     response_text="".join(self._state.parts) or None,
+                    stream_chunks=self._state.chunks,
                 )
         except Exception:
             pass

{metergraph-0.2.1 → metergraph-0.3.0}/src/metergraph/_context.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import contextvars
 import functools
 import inspect
+import secrets
 from concurrent.futures import Executor
 from dataclasses import dataclass, field, replace
 from typing import Any, Callable, Mapping
@@ -20,6 +21,9 @@ class CaptureContext:
     capture_text: bool | None = None
     func_name: str | None = None
     func_module: str | None = None
+    trace_id: str | None = None
+    trace_name: str | None = None
+    parent_span_id: str | None = None
 
 
 _current: contextvars.ContextVar[CaptureContext] = contextvars.ContextVar(
@@ -108,6 +112,91 @@ class route:
         return wrapped
 
 
+class trace:
+    """Logical trace context manager and sync/async decorator."""
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        trace_id: str | None = None,
+        parent_span_id: str | None = None,
+        capture_text: bool | None = None,
+    ) -> None:
+        self.name = str(name)
+        self.trace_id = str(trace_id).strip() if trace_id is not None else None
+        self.parent_span_id = (
+            str(parent_span_id).strip() if parent_span_id is not None else None
+        )
+        self.capture_text = (
+            bool(capture_text) if capture_text is not None else None
+        )
+        self._token: contextvars.Token[CaptureContext] | None = None
+
+    def __enter__(self) -> "trace":
+        current = snapshot()
+        requested = self.trace_id
+        reuse = current.trace_id is not None and (
+            requested is None or requested == current.trace_id
+        )
+        self._token = _current.set(
+            replace(
+                current,
+                trace_id=(
+                    current.trace_id
+                    if reuse
+                    else requested or secrets.token_hex(16)
+                ),
+                trace_name=current.trace_name if reuse else self.name,
+                parent_span_id=(
+                    self.parent_span_id
+                    if self.parent_span_id is not None
+                    else current.parent_span_id
+                    if reuse
+                    else None
+                ),
+                capture_text=(
+                    self.capture_text
+                    if self.capture_text is not None
+                    else current.capture_text
+                ),
+            )
+        )
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self._token is not None:
+            _current.reset(self._token)
+            self._token = None
+
+    def __call__(self, fn: Callable):
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapped(*args, **kwargs):
+                with type(self)(
+                    self.name,
+                    trace_id=self.trace_id,
+                    parent_span_id=self.parent_span_id,
+                    capture_text=self.capture_text,
+                ):
+                    return await fn(*args, **kwargs)
+
+            return async_wrapped
+
+        @functools.wraps(fn)
+        def wrapped(*args, **kwargs):
+            with type(self)(
+                self.name,
+                trace_id=self.trace_id,
+                parent_span_id=self.parent_span_id,
+                capture_text=self.capture_text,
+            ):
+                return fn(*args, **kwargs)
+
+        return wrapped
+
+
 def set_session(session_id: str | None) -> None:
     _current.set(
         replace(snapshot(), session_id=str(session_id) if session_id else None)

{metergraph-0.2.1 → metergraph-0.3.0}/src/metergraph/_template.py

@@ -14,7 +14,23 @@ _EMAIL = re.compile(r"\b[^\s@]+@[^\s@]+\.[^\s@]+\b")
 _URL = re.compile(r"\bhttps?://\S+")
 _NUMBER = re.compile(r"(?<![A-Za-z])[-+]?\d+(?:\.\d+)?(?![A-Za-z])")
 _LONG_TOKEN = re.compile(r"\b[A-Za-z0-9_-]{24,}\b")
-_SENSITIVE_KEYS = {"api_key", "apikey", "authorization", "headers", "token", "secret"}
+_SENSITIVE_KEYS = {
+    "api-key",
+    "api_key",
+    "apikey",
+    "authorization",
+    "client_secret",
+    "cookie",
+    "headers",
+    "id_token",
+    "password",
+    "proxy-authorization",
+    "refresh_token",
+    "secret",
+    "set-cookie",
+    "token",
+    "x-api-key",
+}
 
 
 def _normalize_text(value: str) -> str:
@@ -31,7 +47,7 @@ def scrub(value: Any) -> Any:
         return {
             str(k): scrub(v)
             for k, v in value.items()
-            if str(k).lower() not in _SENSITIVE_KEYS
+            if str(k).strip().lower() not in _SENSITIVE_KEYS
         }
     if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
         return [scrub(item) for item in value]

{metergraph-0.2.1 → metergraph-0.3.0}/src/metergraph/_version.py

@@ -8,4 +8,4 @@ import importlib.metadata
 try:
     SDK_VERSION = importlib.metadata.version("metergraph")
 except Exception:
-    SDK_VERSION = "0.2.1"
+    SDK_VERSION = "0.3.0"

{metergraph-0.2.1 → metergraph-0.3.0}/src/metergraph.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph
-Version: 0.2.1
+Version: 0.3.0
 Summary: Fire-and-forget LLM spend capture for Metergraph
 Author: Pioneer Square Labs
 License-Expression: Apache-2.0
@@ -34,9 +34,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.
@@ -54,15 +55,30 @@ 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.
@@ -88,11 +104,15 @@ genai.Client() construction in place, e.g. client = metergraph.wrap(OpenAI()).
 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.2.1 → metergraph-0.3.0}/tests/test_sdk.py

@@ -63,6 +63,10 @@ def response(text="done"):
     )
 
 
+def captured_response(row):
+    return json.loads(row["response_text"])
+
+
 def test_wrap_auto_init_does_not_latch_before_a_token_is_available():
     class Completions:
         def create(self, **kwargs):
@@ -283,7 +287,7 @@ def test_wrap_google_records_usage_and_endpoint(tmp_path):
     assert row["output_tokens"] == 20
     assert row["cache_read_tokens"] == 10
     assert row["reasoning_tokens"] == 5
-    assert row["response_text"] == "gemini done"
+    assert captured_response(row)["content"] == "gemini done"
     assert row["request_id"] == "resp_g_1"
     assert row["sdk_version"] == metergraph.__version__
     _capture.set_runtime(None)
@@ -331,7 +335,7 @@ def test_wrap_google_stream_takes_usage_from_cumulative_last_chunk(tmp_path):
     assert row["input_tokens"] == 100
     assert row["output_tokens"] == 20
     assert row["cache_read_tokens"] == 10
-    assert row["response_text"] == "partial"
+    assert captured_response(row)["content"] == "partial"
     _capture.set_runtime(None)
 
 
@@ -376,11 +380,11 @@ def test_wrap_google_patches_async_models(tmp_path):
     assert len(asyncio.run(run())) == 1
     assert rows.rows[0]["provider"] == "google"
     assert rows.rows[0]["endpoint"] == "models.generate_content"
-    assert rows.rows[0]["response_text"] == "gemini async done"
+    assert captured_response(rows.rows[0])["content"] == "gemini async done"
     assert rows.rows[1]["endpoint"] == "models.generate_content.stream"
     assert rows.rows[1]["stream"] is True
     assert rows.rows[1]["input_tokens"] == 100
-    assert rows.rows[1]["response_text"] == "gemini async stream"
+    assert captured_response(rows.rows[1])["content"] == "gemini async stream"
     _capture.set_runtime(None)
 
 
@@ -550,6 +554,55 @@ def test_anthropic_response_tool_use_is_requested_not_replayable(tmp_path):
             "idempotency": "non_idempotent",
         }
     ]
+    assert captured_response(rows.rows[0])["tool_calls"] == rows.rows[0]["tool_calls"]
+
+
+def test_gemini_response_normalizes_function_calls(tmp_path):
+    rows = Rows()
+    runtime = Runtime(rows, Options(app_root=str(tmp_path)))
+    call = runtime.call_state(
+        "google",
+        "models.generate_content",
+        {
+            "model": "gemini-test",
+            "contents": [{"role": "user", "parts": [{"text": "Find order"}]}],
+            "tools": [{"name": "lookup_order"}],
+        },
+    )
+    result = SimpleNamespace(
+        candidates=[
+            SimpleNamespace(
+                content=SimpleNamespace(
+                    parts=[
+                        SimpleNamespace(
+                            functionCall=SimpleNamespace(
+                                id="call_g_1",
+                                name="lookup_order",
+                                args={"order_id": "ord_g_1"},
+                            )
+                        )
+                    ]
+                )
+            )
+        ],
+        usage_metadata=SimpleNamespace(
+            prompt_token_count=10, candidates_token_count=2
+        ),
+    )
+
+    call.finish(result)
+
+    assert rows.rows[0]["tool_calls"] == [
+        {
+            "call_id": "call_g_1",
+            "name": "lookup_order",
+            "arguments": {"order_id": "ord_g_1"},
+            "result": None,
+            "status": "requested",
+            "idempotency": "non_idempotent",
+        }
+    ]
+    assert captured_response(rows.rows[0])["tool_calls"] == rows.rows[0]["tool_calls"]
 
 
 def test_openai_batch_output_file_captures_each_inference(tmp_path):
@@ -595,7 +648,7 @@ def test_openai_batch_output_file_captures_each_inference(tmp_path):
     assert row["batch_custom_id"] == "ticket-1"
     assert row["input_tokens"] == 11
     assert row["output_tokens"] == 3
-    assert row["response_text"] == "batch answer"
+    assert captured_response(row)["content"] == "batch answer"
     assert row["request_id"] == "req_batch_1"
 
     # Re-reading the same output file in one process cannot double count it.
@@ -653,11 +706,11 @@ def test_anthropic_batch_results_capture_usage_without_changing_iteration(tmp_pa
     assert row["cache_write_5m_tokens"] == 2
     assert row["cache_write_1h_tokens"] == 5
     assert "cost_usd" not in row
-    assert row["response_text"] == "anthropic batch answer"
+    assert captured_response(row)["content"] == "anthropic batch answer"
     _capture.set_runtime(None)
 
 
-def test_content_defaults_off_and_route_can_override_global_consent(tmp_path):
+def test_content_defaults_on_and_route_can_override_capture(tmp_path):
     rows = Rows()
     runtime = Runtime(rows, Options(app_root=str(tmp_path)))
     call = runtime.call_state(
@@ -665,9 +718,9 @@ def test_content_defaults_off_and_route_can_override_global_consent(tmp_path):
     )
     call.finish(response("private output"))
 
-    assert rows.rows[0]["content_opted_in"] is False
-    assert rows.rows[0]["request_json"] is None
-    assert rows.rows[0]["response_text"] is None
+    assert rows.rows[0]["content_opted_in"] is True
+    assert "private" in rows.rows[0]["request_json"]
+    assert captured_response(rows.rows[0])["content"] == "private output"
 
     _capture.set_runtime(runtime)
 
@@ -682,7 +735,7 @@ def test_content_defaults_off_and_route_can_override_global_consent(tmp_path):
 
     assert rows.rows[1]["content_opted_in"] is True
     assert "consented input" in rows.rows[1]["request_json"]
-    assert rows.rows[1]["response_text"] == "consented output"
+    assert captured_response(rows.rows[1])["content"] == "consented output"
     _capture.set_runtime(None)
 
 
@@ -706,6 +759,99 @@ def test_route_opt_out_overrides_global_content_capture(tmp_path):
     _capture.set_runtime(None)
 
 
+def test_trace_groups_spans_propagates_ids_and_supports_decorators(tmp_path):
+    rows = Rows()
+    runtime = Runtime(rows, Options(app_root=str(tmp_path)))
+    _capture.set_runtime(runtime)
+
+    class Responses:
+        def create(self, **kwargs):
+            return response(kwargs["input"])
+
+    client = SimpleNamespace(responses=Responses())
+    metergraph.wrap(client, provider="openai")
+    manual_trace_id = "a" * 32
+    parent_span_id = "b" * 16
+
+    with metergraph.trace(
+        "checkout", trace_id=manual_trace_id, parent_span_id=parent_span_id
+    ):
+        client.responses.create(model="test", input="first")
+        with metergraph.trace("nested-reuses-active"):
+            client.responses.create(model="test", input="second")
+        with metergraph.trace("explicit-fork", trace_id="c" * 32):
+            client.responses.create(model="test", input="forked")
+
+    @metergraph.trace("async-checkout")
+    async def traced_async():
+        await asyncio.sleep(0)
+        client.responses.create(model="test", input="third")
+        client.responses.create(model="test", input="fourth")
+
+    asyncio.run(traced_async())
+
+    assert {row["trace_id"] for row in rows.rows[:2]} == {manual_trace_id}
+    assert {row["trace_name"] for row in rows.rows[:2]} == {"checkout"}
+    assert {row["parent_span_id"] for row in rows.rows[:2]} == {parent_span_id}
+    assert len({row["span_id"] for row in rows.rows[:2]}) == 2
+    assert rows.rows[2]["trace_id"] == "c" * 32
+    assert rows.rows[2]["trace_name"] == "explicit-fork"
+    assert rows.rows[3]["trace_id"] == rows.rows[4]["trace_id"]
+    assert rows.rows[3]["trace_name"] == "async-checkout"
+    assert rows.rows[3]["trace_id"] != manual_trace_id
+    _capture.set_runtime(None)
+
+
+def test_trace_capture_override_scrubbing_redaction_and_utf8_limits(tmp_path):
+    rows = Rows()
+
+    def redact(value, kind):
+        return value.replace("customer-secret", f"<redacted-{kind}>")
+
+    runtime = Runtime(
+        rows,
+        Options(
+            app_root=str(tmp_path),
+            capture_text=True,
+            redact=redact,
+            text_max_bytes=100 * 1024,
+        ),
+    )
+    hidden = runtime.call_state(
+        "openai", "responses", {"model": "test", "input": "hidden"}
+    )
+    with metergraph.trace("sensitive", capture_text=False):
+        # CaptureContext is read when the call starts.
+        hidden = runtime.call_state(
+            "openai", "responses", {"model": "test", "input": "hidden"}
+        )
+        hidden.finish(response("hidden output"))
+    assert rows.rows[0]["content_opted_in"] is False
+    assert rows.rows[0]["request_json"] is None
+    assert rows.rows[0]["response_text"] is None
+
+    call = runtime.call_state(
+        "openai",
+        "responses",
+        {
+            "model": "test",
+            "authorization": "Bearer provider-secret",
+            "headers": {"x-api-key": "provider-secret"},
+            "input": "customer-secret" + ("ü" * 80_000),
+        },
+    )
+    call.finish(response("customer-secret" + ("é" * 80_000)))
+    row = rows.rows[1]
+    assert "provider-secret" not in row["request_json"]
+    assert "customer-secret" not in row["request_json"]
+    assert "customer-secret" not in row["response_text"]
+    assert len(row["request_json"].encode()) <= 100 * 1024
+    assert len(row["response_text"].encode()) <= 100 * 1024
+    assert row["text_truncated"] is True
+    assert row["request_json"].endswith("<metergraph:truncated>")
+    assert row["response_text"].endswith("<metergraph:truncated>")
+
+
 def test_wrap_async_errors_are_recorded_and_original_error_is_raised(tmp_path):
     rows = Rows()
     _capture.set_runtime(
@@ -730,6 +876,10 @@ def test_wrap_async_errors_are_recorded_and_original_error_is_raised(tmp_path):
     asyncio.run(run())
     assert rows.rows[0]["error"] is True
     assert rows.rows[0]["error_type"] == "ValueError"
+    assert captured_response(rows.rows[0])["error"] == {
+        "type": "ValueError",
+        "message": "provider down",
+    }
     _capture.set_runtime(None)
 
 
@@ -747,6 +897,44 @@ def test_stream_records_ttft_and_final_usage(tmp_path):
                         choices=[SimpleNamespace(delta=SimpleNamespace(content="hi"))],
                         usage=None,
                     ),
+                    SimpleNamespace(
+                        choices=[
+                            SimpleNamespace(
+                                delta=SimpleNamespace(
+                                    content=None,
+                                    tool_calls=[
+                                        SimpleNamespace(
+                                            index=0,
+                                            id="call_1",
+                                            function=SimpleNamespace(
+                                                name="lookup", arguments='{"id":'
+                                            ),
+                                        )
+                                    ],
+                                )
+                            )
+                        ],
+                        usage=None,
+                    ),
+                    SimpleNamespace(
+                        choices=[
+                            SimpleNamespace(
+                                delta=SimpleNamespace(
+                                    content=None,
+                                    tool_calls=[
+                                        SimpleNamespace(
+                                            index=0,
+                                            id=None,
+                                            function=SimpleNamespace(
+                                                name=None, arguments='"ord_1"}'
+                                            ),
+                                        )
+                                    ],
+                                )
+                            )
+                        ],
+                        usage=None,
+                    ),
                     SimpleNamespace(
                         choices=[],
                         usage=SimpleNamespace(
@@ -767,14 +955,22 @@ def test_stream_records_ttft_and_final_usage(tmp_path):
     )
     # The SDK-added OpenAI usage-only chunk is consumed for metering but is
     # not exposed to an application that did not ask for it.
-    assert len(chunks) == 1
+    assert len(chunks) == 3
     assert rows.rows[0]["stream"] is True
     assert rows.rows[0]["ttft_ms"] is not None
     assert rows.rows[0]["input_tokens"] == 2
     assert rows.rows[0]["cache_read_tokens"] == 1
     assert rows.rows[0]["cache_write_tokens"] == 2
     assert "cost_usd" not in rows.rows[0]
-    assert rows.rows[0]["response_text"] == "hi"
+    assert captured_response(rows.rows[0])["content"] == "hi"
+    assert captured_response(rows.rows[0])["tool_calls"][0] == {
+        "call_id": "call_1",
+        "name": "lookup",
+        "arguments": {"id": "ord_1"},
+        "result": None,
+        "status": "requested",
+        "idempotency": "non_idempotent",
+    }
     assert rows.rows[0]["request_json"].find("include_usage") >= 0
     _capture.set_runtime(None)
 
@@ -829,7 +1025,7 @@ def test_async_stream_awaits_anthropic_final_message(tmp_path):
     assert rows.rows[0]["cache_write_5m_tokens"] == 2
     assert rows.rows[0]["cache_write_1h_tokens"] == 3
     assert "cost_usd" not in rows.rows[0]
-    assert rows.rows[0]["response_text"] == "ok"
+    assert captured_response(rows.rows[0])["content"] == "ok"
     _capture.set_runtime(None)