metergraph 0.6.0__tar.gz → 0.6.3__tar.gz

{metergraph-0.6.0 → metergraph-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph
-Version: 0.6.0
+Version: 0.6.3
 Summary: Fire-and-forget LLM spend capture for Metergraph
 Author: Pioneer Square Labs
 License-Expression: Apache-2.0
@@ -13,12 +13,15 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
+Provides-Extra: otel
+Requires-Dist: opentelemetry-sdk>=1.30; extra == "otel"
 Provides-Extra: dev
 Requires-Dist: build>=1; extra == "dev"
 Requires-Dist: pytest>=8; extra == "dev"
-Requires-Dist: openai>=2.50.0; extra == "dev"
-Requires-Dist: anthropic>=0.40; extra == "dev"
+Requires-Dist: openai<3,>=2.50.0; extra == "dev"
+Requires-Dist: anthropic<1,>=0.40; extra == "dev"
 Requires-Dist: google-genai>=1; extra == "dev"
+Requires-Dist: opentelemetry-sdk>=1.30; extra == "dev"
 
 # metergraph (Python)
 
@@ -38,12 +41,15 @@ from openai import OpenAI
 metergraph.init(repository="owner/repository")
 # 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=[...])
+with metergraph.context(
+    session_id="ticket-123",
+    tags={"customer": "acme"},
+):
+    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.
@@ -57,6 +63,14 @@ metergraph.record_outcome(
 )
 ```
 
+Use `metergraph.context()` for request or job identity. It follows async work
+created inside the scope and is restored afterward, so concurrent and reused
+workers cannot leak session IDs or tags into one another. The narrower
+`metergraph.session()` and `metergraph.tags()` scopes compose with it.
+`metergraph.set_default_tags()` sets process-wide service metadata. Legacy
+`set_session()` and `set_tags()` calls only update an active Metergraph scope;
+outside one they warn once and do nothing.
+
 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:
@@ -83,12 +97,44 @@ 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.
 
+## OpenTelemetry GenAI export
+
+`MetergraphGenAIExporter` is a standard OpenTelemetry span exporter for GenAI
+semantic-convention spans. The currently qualified integration is LiteLLM:
+install the optional integration and configure MeterGraph as LiteLLM's custom
+exporter. Existing LiteLLM call sites remain unchanged and must not also be
+wrapped.
+
+```bash
+python -m pip install 'metergraph[otel]' 'litellm[proxy]>=1.96.2,<2'
+```
+
+```python
+import litellm
+from litellm.integrations.opentelemetry import OpenTelemetry, OpenTelemetryConfig
+from metergraph.opentelemetry import MetergraphGenAIExporter
+
+litellm.callbacks.append(OpenTelemetry(OpenTelemetryConfig(
+    exporter=MetergraphGenAIExporter(),
+    capture_message_content="SPAN_ONLY",
+)))
+```
+
+The exporter preserves OpenTelemetry trace identity, model/provider metadata,
+token usage, latency, system instructions, ordered messages, and text output.
+Message content is explicitly enabled because it may be sensitive. Text parts
+are retained and replayable in the current POC pipeline. Calls containing other
+part types retain their model, usage, timing, and status metadata, but those
+parts are not replayable yet. See the runnable
+[`python-litellm-otel` example](../examples/python-litellm-otel/).
+
 Configuration:
 
 - `METERGRAPH_APP_TOKEN` — required bearer token
 - `METERGRAPH_INGEST_URL` — optional override; defaults to the hosted HTTPS endpoint
 - `METERGRAPH_REPOSITORY` — optional `owner/repository` identity; used by [MeterGraph Bot](https://github.com/apps/metergraph)
 - `METERGRAPH_CAPTURE_TEXT=0` — opt out of content capture globally
+- `METERGRAPH_TEXT_MAX_BYTES` — per-field content limit; defaults to 1 MiB
 - `METERGRAPH_DISABLED=1` — process kill switch
 - `METERGRAPH_QUEUE_SIZE`, `METERGRAPH_BATCH_SIZE`, `METERGRAPH_FLUSH_SECONDS`
 
@@ -110,11 +156,13 @@ identity, it warns once and continues capture without repository attribution.
 
 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.
+provider call. Each wire batch is bounded to 4 MiB after optional gzip.
 By default, Metergraph captures the scrubbed provider request and a normalized
 response envelope, including assistant content and tool calls. Provider
 credentials and transport headers are removed. Request and response are each
-limited to 100 KiB of UTF-8 with an explicit truncation marker.
+limited to 1 MiB of UTF-8 by default with an explicit truncation marker. Set
+`METERGRAPH_TEXT_MAX_BYTES` or initialize with `text_max_bytes=...` to raise
+the per-field limit for larger prompts and responses.
 `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

metergraph-0.6.0/src/metergraph.egg-info/PKG-INFO → metergraph-0.6.3/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.4
-Name: metergraph
-Version: 0.6.0
-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,vercel-ai-gateway,cost-tracking
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Typing :: Typed
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-Provides-Extra: dev
-Requires-Dist: build>=1; extra == "dev"
-Requires-Dist: pytest>=8; extra == "dev"
-Requires-Dist: openai>=2.50.0; extra == "dev"
-Requires-Dist: anthropic>=0.40; extra == "dev"
-Requires-Dist: google-genai>=1; extra == "dev"
-
 # metergraph (Python)
 
 Zero-runtime-dependency capture for OpenAI, Anthropic, Gemini, and Python
@@ -38,12 +16,15 @@ from openai import OpenAI
 metergraph.init(repository="owner/repository")
 # 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=[...])
+with metergraph.context(
+    session_id="ticket-123",
+    tags={"customer": "acme"},
+):
+    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.
@@ -57,6 +38,14 @@ metergraph.record_outcome(
 )
 ```
 
+Use `metergraph.context()` for request or job identity. It follows async work
+created inside the scope and is restored afterward, so concurrent and reused
+workers cannot leak session IDs or tags into one another. The narrower
+`metergraph.session()` and `metergraph.tags()` scopes compose with it.
+`metergraph.set_default_tags()` sets process-wide service metadata. Legacy
+`set_session()` and `set_tags()` calls only update an active Metergraph scope;
+outside one they warn once and do nothing.
+
 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:
@@ -83,12 +72,44 @@ 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.
 
+## OpenTelemetry GenAI export
+
+`MetergraphGenAIExporter` is a standard OpenTelemetry span exporter for GenAI
+semantic-convention spans. The currently qualified integration is LiteLLM:
+install the optional integration and configure MeterGraph as LiteLLM's custom
+exporter. Existing LiteLLM call sites remain unchanged and must not also be
+wrapped.
+
+```bash
+python -m pip install 'metergraph[otel]' 'litellm[proxy]>=1.96.2,<2'
+```
+
+```python
+import litellm
+from litellm.integrations.opentelemetry import OpenTelemetry, OpenTelemetryConfig
+from metergraph.opentelemetry import MetergraphGenAIExporter
+
+litellm.callbacks.append(OpenTelemetry(OpenTelemetryConfig(
+    exporter=MetergraphGenAIExporter(),
+    capture_message_content="SPAN_ONLY",
+)))
+```
+
+The exporter preserves OpenTelemetry trace identity, model/provider metadata,
+token usage, latency, system instructions, ordered messages, and text output.
+Message content is explicitly enabled because it may be sensitive. Text parts
+are retained and replayable in the current POC pipeline. Calls containing other
+part types retain their model, usage, timing, and status metadata, but those
+parts are not replayable yet. See the runnable
+[`python-litellm-otel` example](../examples/python-litellm-otel/).
+
 Configuration:
 
 - `METERGRAPH_APP_TOKEN` — required bearer token
 - `METERGRAPH_INGEST_URL` — optional override; defaults to the hosted HTTPS endpoint
 - `METERGRAPH_REPOSITORY` — optional `owner/repository` identity; used by [MeterGraph Bot](https://github.com/apps/metergraph)
 - `METERGRAPH_CAPTURE_TEXT=0` — opt out of content capture globally
+- `METERGRAPH_TEXT_MAX_BYTES` — per-field content limit; defaults to 1 MiB
 - `METERGRAPH_DISABLED=1` — process kill switch
 - `METERGRAPH_QUEUE_SIZE`, `METERGRAPH_BATCH_SIZE`, `METERGRAPH_FLUSH_SECONDS`
 
@@ -110,11 +131,13 @@ identity, it warns once and continues capture without repository attribution.
 
 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.
+provider call. Each wire batch is bounded to 4 MiB after optional gzip.
 By default, Metergraph captures the scrubbed provider request and a normalized
 response envelope, including assistant content and tool calls. Provider
 credentials and transport headers are removed. Request and response are each
-limited to 100 KiB of UTF-8 with an explicit truncation marker.
+limited to 1 MiB of UTF-8 by default with an explicit truncation marker. Set
+`METERGRAPH_TEXT_MAX_BYTES` or initialize with `text_max_bytes=...` to raise
+the per-field limit for larger prompts and responses.
 `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

{metergraph-0.6.0 → metergraph-0.6.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metergraph"
-version = "0.6.0"
+version = "0.6.3"
 description = "Fire-and-forget LLM spend capture for Metergraph"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -20,7 +20,8 @@ Repository = "https://github.com/PioneerSquareLabs/metergraphsdk"
 Issues = "https://github.com/PioneerSquareLabs/metergraphsdk/issues"
 
 [project.optional-dependencies]
-dev = ["build>=1", "pytest>=8", "openai>=2.50.0", "anthropic>=0.40", "google-genai>=1"]
+otel = ["opentelemetry-sdk>=1.30"]
+dev = ["build>=1", "pytest>=8", "openai>=2.50.0,<3", "anthropic>=0.40,<1", "google-genai>=1", "opentelemetry-sdk>=1.30"]
 
 [build-system]
 requires = ["setuptools>=68"]

{metergraph-0.6.0 → metergraph-0.6.3}/src/metergraph/__init__.py

@@ -10,10 +10,21 @@ import uuid
 from datetime import datetime, timezone
 from typing import Any, Callable
 
-from ._capture import Options, Runtime, set_runtime
+from ._capture import DEFAULT_TEXT_MAX_BYTES, Options, Runtime, set_runtime
 from ._capture import wrap as _wrap
 from ._config import ConfigPoller
-from ._context import route, set_session, set_tags, snapshot, trace, wrap_executor
+from ._context import (
+    context,
+    route,
+    session,
+    set_default_tags,
+    set_session,
+    set_tags,
+    snapshot,
+    tags,
+    trace,
+    wrap_executor,
+)
 from ._batch_first import (
     BatchFirstIneligibleError,
     BatchFirstMetadata,
@@ -69,6 +80,7 @@ def init(
     skip_frames: list[str] | None = None,
     environment: str | None = None,
     disabled: bool | None = None,
+    text_max_bytes: int | None = None,
 ) -> None:
     """Initialize capture. This function is idempotent and never raises."""
     global _initialized, _warned_no_token, _warned_no_repository
@@ -136,15 +148,14 @@ def init(
             repo_root=repo_config.repo_root if repo_config is not None else None,
             skip_frames=tuple(skip_frames or ()),
             environment=environment or os.getenv("METERGRAPH_ENV"),
-            text_max_bytes=min(
-                100 * 1024,
-                max(
-                    1,
-                    int(
-                        os.getenv(
-                            "METERGRAPH_TEXT_MAX_BYTES", str(100 * 1024)
-                        )
-                    ),
+            text_max_bytes=max(
+                1,
+                int(
+                    text_max_bytes
+                    if text_max_bytes is not None
+                    else os.getenv(
+                        "METERGRAPH_TEXT_MAX_BYTES", str(DEFAULT_TEXT_MAX_BYTES)
+                    )
                 ),
             ),
         )
@@ -290,14 +301,18 @@ __all__ = [
     "BatchFirstResult",
     "LateBatchInfo",
     "batch_first",
+    "context",
     "flush",
     "init",
     "model_for",
     "record_outcome",
     "route",
+    "session",
+    "set_default_tags",
     "set_session",
     "set_tags",
     "shutdown",
+    "tags",
     "track",
     "trace",
     "wrap",

{metergraph-0.6.0 → metergraph-0.6.3}/src/metergraph/_capture.py

@@ -24,6 +24,7 @@ from ._version import SDK_VERSION
 
 
 log = logging.getLogger("metergraph")
+DEFAULT_TEXT_MAX_BYTES = 1024 * 1024
 
 
 def _get(value: Any, name: str, default: Any = None) -> Any:
@@ -254,6 +255,48 @@ def _stop_reason(response: Any) -> str | None:
     return str(reason) if reason is not None else None
 
 
+def _normalize_finish_reason(value: str) -> str:
+    normalized = "-".join(value.strip().lower().replace("_", "-").split())
+    if normalized in {"stop", "end-turn", "stop-sequence", "completed", "succeeded"}:
+        return "stop"
+    if normalized in {"length", "max-tokens", "max-output-tokens"}:
+        return "length"
+    if normalized in {"content-filter", "safety", "blocked"}:
+        return "content-filter"
+    if normalized in {"tool-calls", "tool-use", "function-call"}:
+        return "tool-calls"
+    if normalized in {"error", "failed"}:
+        return "error"
+    if normalized in {"other", "unknown"}:
+        return "other"
+    return normalized
+
+
+def _finish_reason_details(response: Any) -> tuple[str | None, str | None]:
+    response_status = _get(response, "status")
+    incomplete_reason = (
+        _get(_get(response, "incomplete_details"), "reason")
+        if response_status == "incomplete"
+        else None
+    )
+    value = (
+        _get(response, "stop_reason")
+        or incomplete_reason
+        or response_status
+        or _get(response, "finishReason")
+        or _get(response, "finish_reason")
+        or _get(_first(_get(response, "choices")), "finish_reason")
+    )
+    unified = _get(value, "unified")
+    raw_value = _get(value, "raw") or (value if unified is None else None)
+    source = unified if unified is not None else raw_value
+    if source is None:
+        return None, None
+    finish_reason = _normalize_finish_reason(str(source))
+    raw = str(raw_value) if raw_value is not None else None
+    return finish_reason, raw if raw != finish_reason else None
+
+
 def _request_id(response: Any) -> str | None:
     value = (
         _get(response, "_request_id")
@@ -597,7 +640,7 @@ class Options:
     repo_root: str | None = None
     skip_frames: tuple[str, ...] = ()
     environment: str | None = None
-    text_max_bytes: int = 100 * 1024
+    text_max_bytes: int = DEFAULT_TEXT_MAX_BYTES
 
 
 class Runtime:
@@ -740,6 +783,12 @@ class CallState:
         effective_status = status or (
             "error" if error else _stop_reason(response) or "success"
         )
+        finish_reason, finish_reason_raw = _finish_reason_details(response)
+        status_code = (
+            "error"
+            if error or status == "error" or finish_reason == "error"
+            else "unset"
+        )
         response_json, response_truncated = self.runtime._text(
             json.dumps(
                 _response_envelope(
@@ -764,6 +813,9 @@ class CallState:
             **_usage(response),
             "latency_ms": round((time.perf_counter() - self.started) * 1000),
             "status": effective_status,
+            "status_code": status_code,
+            "finish_reason": finish_reason,
+            "finish_reason_raw": finish_reason_raw,
             "session_id": self.context.session_id,
             "conversation_id": self.context.session_id,
             "trace_id": self.trace_id,
@@ -792,7 +844,7 @@ class CallState:
             "frames_json": self.frames,
             "tags": dict(self.context.tags),
             "environment": self.runtime.options.environment,
-            "error": bool(error),
+            "error": status_code == "error",
             "error_type": type(error).__name__ if error else None,
             "sdk": "python",
             "sdk_version": SDK_VERSION,
@@ -806,14 +858,22 @@ class CallState:
 
 class _StreamState:
     def __init__(self, stream: Any, call: CallState) -> None:
+        self.manager = stream
         self.stream = stream
         self.call = call
         self.iterator = None
+        self.entered = False
         self.last = None
         self.parts: list[str] = []
         self.chunks: list[Any] = []
         self.ttft_ms: int | None = None
 
+    def use_entered_stream(self, stream: Any) -> None:
+        if stream is not None:
+            self.stream = stream
+            self.iterator = None
+        self.entered = True
+
     def chunk(self, value: Any) -> Any:
         self.last = value
         self.chunks.append(value)
@@ -903,17 +963,21 @@ class SyncStream:
                 raise
 
     def __enter__(self) -> "SyncStream":
-        enter = getattr(self._state.stream, "__enter__", None)
+        enter = getattr(self._state.manager, "__enter__", None)
         if enter:
-            enter()
+            try:
+                self._state.use_entered_stream(enter())
+            except BaseException as exc:
+                self._state.finish(error=exc)
+                raise
         return self
 
     def __exit__(self, exc_type, exc, tb) -> Any:
         if exc:
             self._state.finish(error=exc)
         elif not self._state.call.done:
-            self._state.finish(status="abandoned")
-        exit_fn = getattr(self._state.stream, "__exit__", None)
+            self._state.finish(status=None if self._state.entered else "abandoned")
+        exit_fn = getattr(self._state.manager, "__exit__", None)
         return exit_fn(exc_type, exc, tb) if exit_fn else None
 
     def close(self) -> None:
@@ -960,17 +1024,23 @@ class AsyncStream:
                 raise
 
     async def __aenter__(self) -> "AsyncStream":
-        enter = getattr(self._state.stream, "__aenter__", None)
+        enter = getattr(self._state.manager, "__aenter__", None)
         if enter:
-            await enter()
+            try:
+                self._state.use_entered_stream(await enter())
+            except BaseException as exc:
+                await self._state.finish_async(error=exc)
+                raise
         return self
 
     async def __aexit__(self, exc_type, exc, tb) -> Any:
         if exc:
             await self._state.finish_async(error=exc)
         elif not self._state.call.done:
-            await self._state.finish_async(status="abandoned")
-        exit_fn = getattr(self._state.stream, "__aexit__", None)
+            await self._state.finish_async(
+                status=None if self._state.entered else "abandoned"
+            )
+        exit_fn = getattr(self._state.manager, "__aexit__", None)
         return await exit_fn(exc_type, exc, tb) if exit_fn else None
 
     async def aclose(self) -> None:
@@ -1004,6 +1074,11 @@ def set_runtime(runtime: Runtime | None) -> None:
     _runtime = runtime
 
 
+def _get_runtime() -> Runtime | None:
+    """Return the active runtime to internal capture integrations."""
+    return _runtime
+
+
 def _request(args: tuple, kwargs: dict) -> dict[str, Any]:
     request: dict[str, Any] = {}
     if args and isinstance(args[0], Mapping):
@@ -1318,9 +1393,15 @@ def _finish_or_stream(
     result: Any, call: CallState, endpoint: str, request: Mapping[str, Any]
 ):
     is_stream = endpoint.endswith(".stream") or bool(request.get("stream"))
-    if is_stream and hasattr(result, "__aiter__"):
+    if is_stream and (
+        hasattr(result, "__aiter__")
+        or (hasattr(result, "__aenter__") and hasattr(result, "__aexit__"))
+    ):
         return AsyncStream(result, call)
-    if is_stream and hasattr(result, "__iter__"):
+    if is_stream and (
+        hasattr(result, "__iter__")
+        or (hasattr(result, "__enter__") and hasattr(result, "__exit__"))
+    ):
         return SyncStream(result, call)
     call.finish(result)
     return result