metergraph 0.5.0__tar.gz → 0.6.2__tar.gz

metergraph-0.6.2/MANIFEST.in

@@ -0,0 +1 @@
+prune tests

{metergraph-0.5.0 → metergraph-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metergraph
-Version: 0.5.0
+Version: 0.6.2
 Summary: Fire-and-forget LLM spend capture for Metergraph
 Author: Pioneer Square Labs
 License-Expression: Apache-2.0
@@ -13,32 +13,43 @@ 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)
 
 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.
+Initialize Metergraph once, then wrap each provider client. `init()` reads the
+token and other omitted options from the environment.
+
+Initialization is process-wide. The first `init()` configuration remains
+active; later explicit calls are ignored and produce one generic warning
+without option names, token values, or other secrets.
 
 ```python
 import metergraph
 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.
@@ -52,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:
@@ -61,6 +80,7 @@ import os
 import metergraph
 from openai import OpenAI
 
+metergraph.init(repository="owner/repository")
 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",
@@ -77,29 +97,72 @@ 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`
 
-SDK 0.4 associates traces with their GitHub repository automatically. On the
-first `init()` in a Git checkout, it reads the `origin` remote and creates
-`.metergraph/config.json` at the repository root if that file is absent.
-Commit this non-secret file so production can use repository-aware ingest
-without Git metadata. An existing file is authoritative and is never changed
-by the SDK. If discovery or creation is unavailable, ingest remains compatible
-with protocol v1.
+Repository identity enables repository-level attribution and
+[MeterGraph Bot](https://github.com/apps/metergraph). Choose any one of these
+options; each is sufficient on its own:
+
+- Pass `repository="owner/repository"` to `metergraph.init()`.
+- Set `METERGRAPH_REPOSITORY=owner/repository` in the environment.
+- Store the identity with the source code in `.metergraph/config.json`:
+
+```json
+{"repository":"owner/repository"}
+```
+
+Resolution order is the explicit option, environment variable, then
+configuration file. The SDK treats the file as read-only. Without repository
+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.
-SDK 0.4 captures the scrubbed provider request and a normalized response
-envelope, including assistant content and tool calls, by default. Provider
+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
@@ -167,11 +230,13 @@ 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.4 captures scrubbed provider
-requests and normalized responses by default for the hosted dashboard; use
+Before wrapping, call metergraph.init(repository="owner/repository") using the
+actual GitHub owner and repository name. METERGRAPH_APP_TOKEN is required; the
+SDK warns and disables capture when it is missing. METERGRAPH_INGEST_URL is
+only for self-hosted servers. Document variable names with placeholders in
+.env.example, and put real values only in deployment configuration. Metergraph
+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,

{metergraph-0.5.0 → metergraph-0.6.2}/README.md

@@ -2,22 +2,29 @@
 
 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.
+Initialize Metergraph once, then wrap each provider client. `init()` reads the
+token and other omitted options from the environment.
+
+Initialization is process-wide. The first `init()` configuration remains
+active; later explicit calls are ignored and produce one generic warning
+without option names, token values, or other secrets.
 
 ```python
 import metergraph
 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.
@@ -31,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:
@@ -40,6 +55,7 @@ import os
 import metergraph
 from openai import OpenAI
 
+metergraph.init(repository="owner/repository")
 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",
@@ -56,29 +72,72 @@ 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`
 
-SDK 0.4 associates traces with their GitHub repository automatically. On the
-first `init()` in a Git checkout, it reads the `origin` remote and creates
-`.metergraph/config.json` at the repository root if that file is absent.
-Commit this non-secret file so production can use repository-aware ingest
-without Git metadata. An existing file is authoritative and is never changed
-by the SDK. If discovery or creation is unavailable, ingest remains compatible
-with protocol v1.
+Repository identity enables repository-level attribution and
+[MeterGraph Bot](https://github.com/apps/metergraph). Choose any one of these
+options; each is sufficient on its own:
+
+- Pass `repository="owner/repository"` to `metergraph.init()`.
+- Set `METERGRAPH_REPOSITORY=owner/repository` in the environment.
+- Store the identity with the source code in `.metergraph/config.json`:
+
+```json
+{"repository":"owner/repository"}
+```
+
+Resolution order is the explicit option, environment variable, then
+configuration file. The SDK treats the file as read-only. Without repository
+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.
-SDK 0.4 captures the scrubbed provider request and a normalized response
-envelope, including assistant content and tool calls, by default. Provider
+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
@@ -146,11 +205,13 @@ 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.4 captures scrubbed provider
-requests and normalized responses by default for the hosted dashboard; use
+Before wrapping, call metergraph.init(repository="owner/repository") using the
+actual GitHub owner and repository name. METERGRAPH_APP_TOKEN is required; the
+SDK warns and disables capture when it is missing. METERGRAPH_INGEST_URL is
+only for self-hosted servers. Document variable names with placeholders in
+.env.example, and put real values only in deployment configuration. Metergraph
+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,

{metergraph-0.5.0 → metergraph-0.6.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metergraph"
-version = "0.5.0"
+version = "0.6.2"
 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 = ["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.5.0 → metergraph-0.6.2}/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,
@@ -21,7 +32,7 @@ from ._batch_first import (
     LateBatchInfo,
     batch_first,
 )
-from ._repo_config import ensure_repo_config
+from ._repo_config import RepoConfig, discover_repo_config
 from ._session import SessionManager
 from ._track import track
 from ._transport import Writer
@@ -36,6 +47,8 @@ _config: ConfigPoller | None = None
 _session_manager: SessionManager | None = None
 _initialized = False
 _warned_no_token = False
+_warned_no_repository = False
+_warned_repeated_init = False
 
 
 def _env_bool(name: str, default: bool) -> bool:
@@ -45,6 +58,17 @@ def _env_bool(name: str, default: bool) -> bool:
     return value.lower() not in {"0", "false", "no", "off"}
 
 
+def _warn_repeated_init() -> None:
+    global _warned_repeated_init
+    if _warned_repeated_init:
+        return
+    _warned_repeated_init = True
+    log.warning(
+        "Metergraph init() was called more than once; "
+        "the first configuration remains active."
+    )
+
+
 def init(
     *,
     token: str | None = None,
@@ -52,13 +76,17 @@ def init(
     capture_text: bool | None = None,
     redact: Callable[[str, str], str] | None = None,
     app_root: str | None = None,
+    repository: str | None = None,
     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, _writer, _config, _session_manager
+    global _initialized, _warned_no_token, _warned_no_repository
+    global _writer, _config, _session_manager
     if _initialized:
+        _warn_repeated_init()
         return
     if os.getenv("METERGRAPH_DISABLED") == "1" or disabled:
         _initialized = True
@@ -73,10 +101,23 @@ def init(
                 "Metergraph capture disabled: token and ingest URL are required"
             )
         return
-    _initialized = True
     try:
         app_root_resolved = os.path.realpath(app_root or os.getcwd())
-        repo_config = ensure_repo_config(app_root_resolved)
+        repository_value = repository or os.getenv("METERGRAPH_REPOSITORY")
+        repo_config = (
+            RepoConfig(repository_value.strip(), app_root_resolved)
+            if isinstance(repository_value, str)
+            and "/" in repository_value.strip()
+            else discover_repo_config(app_root_resolved)
+        )
+        _initialized = True
+        if repo_config is None and not _warned_no_repository:
+            _warned_no_repository = True
+            log.warning(
+                "Metergraph repository identity is not configured; set "
+                "init(repository='owner/repository'), METERGRAPH_REPOSITORY, "
+                "or provide .metergraph/config.json. Continuing with legacy ingestion."
+            )
         session = (
             SessionManager(
                 token,
@@ -107,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)
+                    )
                 ),
             ),
         )
@@ -150,7 +190,8 @@ def wrap(client: Any, *, provider: str | None = None) -> Any:
     force gateway handling for a compatible client with a custom URL. Call
     init(...) first to pass Metergraph options in code.
     """
-    init()
+    if not _initialized:
+        init()
     return _wrap(client, provider=provider)
 
 
@@ -260,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.5.0 → metergraph-0.6.2}/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,
@@ -1004,6 +1056,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):