metergraph 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph
-Version: 0.2.0
+Version: 0.3.0
 Summary: Fire-and-forget LLM spend capture for Metergraph
 Author: Pioneer Square Labs
 License-Expression: Apache-2.0
@@ -15,6 +15,9 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 Provides-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)
 
@@ -31,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.
@@ -51,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.
@@ -85,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.0 → 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.0 → metergraph-0.3.0}/pyproject.toml

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

{metergraph-0.2.0 → 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",
 ]