struct-sdk 0.3.1__tar.gz → 0.3.2__tar.gz

{struct_sdk-0.3.1 → struct_sdk-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: struct-sdk
-Version: 0.3.1
+Version: 0.3.2
 Summary: Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry
 Project-URL: Homepage, https://struct.ai
 Project-URL: Documentation, https://struct.ai/docs
@@ -92,6 +92,8 @@ Provides-Extra: langchain
 Requires-Dist: langchain-core>=1.3.3; extra == 'langchain'
 Provides-Extra: openai
 Requires-Dist: openai>=1.66.0; extra == 'openai'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai-slim>=2.53.0; extra == 'pydantic-ai'
 Provides-Extra: structlog
 Requires-Dist: opentelemetry-instrumentation-structlog; extra == 'structlog'
 Provides-Extra: temporal
@@ -102,8 +104,8 @@ Description-Content-Type: text/markdown
 
 OpenTelemetry instrumentation for AI agents in Python. Captures spans,
 token usage, and message events from the Anthropic SDK, the OpenAI SDK
-(Responses API), the Claude Agent SDK, and LangChain / LangGraph, and
-exports them to [struct.ai](https://struct.ai) for observability.
+(Responses API), pydantic-ai, the Claude Agent SDK, and LangChain /
+LangGraph, and exports them to [struct.ai](https://struct.ai) for observability.
 
 A TypeScript version is available as
 [`@struct-ai/sdk`](https://www.npmjs.com/package/@struct-ai/sdk). Both
@@ -117,6 +119,7 @@ pip install struct-sdk
 # optional — the SDK auto-instruments these if present
 pip install anthropic
 pip install openai
+pip install pydantic-ai-slim
 pip install claude-agent-sdk
 pip install langchain-core langgraph
 ```
@@ -162,6 +165,7 @@ async with struct.agent(name="checkout"):
 |---|---|---|
 | `anthropic` | `chat {model}` | Cache-token accounting; streaming chats with tool-use reconstruction. Bedrock and Vertex variants supported if installed. |
 | `openai` (Responses API) | `chat {model}` | Non-streaming `responses.create` on sync and async clients (Azure clients included). Cached-token accounting from `usage.input_tokens_details`. Streaming and `chat.completions` calls pass through untraced. Message-content capture at parity with the Anthropic integration: per-message events (`gen_ai.system/user/assistant/tool.message`) and `gen_ai.choice`, plus `gen_ai.input.messages` / `gen_ai.output.messages` in span-content mode. Reasoning items are skipped (`encrypted_content` is never emitted). |
+| `pydantic_ai` | `invoke_agent {agent}`, `chat {model}`, `execute_tool {tool}` | pydantic-ai's own instrumentation, turned on with Struct's tracer provider. See [pydantic-ai](#pydantic-ai). |
 | `claude_agent_sdk` | `agent`, `chat`, `execute_tool` | Telemetry comes from Claude Code itself in the subprocess; ingest credentials are propagated to it via `ClaudeAgentOptions`. Subagents inherit the configuration. |
 | `langchain_core` `BaseChatModel` | `chat {model}` | When the underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic`), the provider's span is suppressed, so there is a single span. |
 | `langchain_core` `BaseTool` | `execute_tool {name}` | `tool_call_id` extracted from the LangChain ToolCall when present. |
@@ -202,6 +206,40 @@ from claude_agent_sdk import ClaudeAgentOptions, query
 # credentials on ClaudeAgentOptions; subagents inherit them automatically.
 ```
 
+#### pydantic-ai
+
+```python
+from struct_sdk import struct
+struct.init(ingest_key="pk-...", service_name="support-agent")
+
+from pydantic_ai import Agent
+agent = Agent("openai:gpt-5.5", name="support")
+result = await agent.run("Refund order 42", conversation_id="thread-42")
+```
+
+pydantic-ai already emits OpenTelemetry GenAI spans; `struct.init()` turns
+that on for every agent (`Agent.instrument_all`) with Struct's tracer
+provider, unless you already set your own default (for example with
+logfire). You get pydantic-ai's `invoke_agent`, `chat` and `execute_tool`
+spans, with one `chat` span per model call (Struct's OpenAI and Anthropic
+patches stay out of the way for pydantic-ai's own provider calls; model
+calls your code makes while reading a stream keep their spans). During agent
+runs, Struct guards telemetry faults and caps content. Realtime sessions and
+direct `InstrumentedModel` exception recording are outside this guarantee.
+
+- **Content** goes on span attributes only (pydantic-ai has no message
+  events): `span_only` / `span_and_event` include prompts, answers and tool
+  arguments; `event_only` and `none` do not. Tool definitions are always
+  recorded.
+- **Sessions:** on Struct's provider, a `struct.agent(session_id=...)`
+  around the run wins; otherwise pydantic-ai's `conversation_id` is used.
+  Instrumentation configured on your own provider keeps its conversation IDs.
+- **Turn it off** with
+  `struct.init(..., instrumentation_options={"pydantic_ai": {"enabled": False}})`,
+  or for one agent with `agent.instrument = False`. An
+  `Agent.instrument_all(False)` before `struct.init()` is pydantic-ai's
+  initial value, so it does not keep pydantic-ai off.
+
 #### LangChain / LangGraph (with an agent or graph)
 
 ```python

{struct_sdk-0.3.1 → struct_sdk-0.3.2}/README.md

@@ -2,8 +2,8 @@
 
 OpenTelemetry instrumentation for AI agents in Python. Captures spans,
 token usage, and message events from the Anthropic SDK, the OpenAI SDK
-(Responses API), the Claude Agent SDK, and LangChain / LangGraph, and
-exports them to [struct.ai](https://struct.ai) for observability.
+(Responses API), pydantic-ai, the Claude Agent SDK, and LangChain /
+LangGraph, and exports them to [struct.ai](https://struct.ai) for observability.
 
 A TypeScript version is available as
 [`@struct-ai/sdk`](https://www.npmjs.com/package/@struct-ai/sdk). Both
@@ -17,6 +17,7 @@ pip install struct-sdk
 # optional — the SDK auto-instruments these if present
 pip install anthropic
 pip install openai
+pip install pydantic-ai-slim
 pip install claude-agent-sdk
 pip install langchain-core langgraph
 ```
@@ -62,6 +63,7 @@ async with struct.agent(name="checkout"):
 |---|---|---|
 | `anthropic` | `chat {model}` | Cache-token accounting; streaming chats with tool-use reconstruction. Bedrock and Vertex variants supported if installed. |
 | `openai` (Responses API) | `chat {model}` | Non-streaming `responses.create` on sync and async clients (Azure clients included). Cached-token accounting from `usage.input_tokens_details`. Streaming and `chat.completions` calls pass through untraced. Message-content capture at parity with the Anthropic integration: per-message events (`gen_ai.system/user/assistant/tool.message`) and `gen_ai.choice`, plus `gen_ai.input.messages` / `gen_ai.output.messages` in span-content mode. Reasoning items are skipped (`encrypted_content` is never emitted). |
+| `pydantic_ai` | `invoke_agent {agent}`, `chat {model}`, `execute_tool {tool}` | pydantic-ai's own instrumentation, turned on with Struct's tracer provider. See [pydantic-ai](#pydantic-ai). |
 | `claude_agent_sdk` | `agent`, `chat`, `execute_tool` | Telemetry comes from Claude Code itself in the subprocess; ingest credentials are propagated to it via `ClaudeAgentOptions`. Subagents inherit the configuration. |
 | `langchain_core` `BaseChatModel` | `chat {model}` | When the underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic`), the provider's span is suppressed, so there is a single span. |
 | `langchain_core` `BaseTool` | `execute_tool {name}` | `tool_call_id` extracted from the LangChain ToolCall when present. |
@@ -102,6 +104,40 @@ from claude_agent_sdk import ClaudeAgentOptions, query
 # credentials on ClaudeAgentOptions; subagents inherit them automatically.
 ```
 
+#### pydantic-ai
+
+```python
+from struct_sdk import struct
+struct.init(ingest_key="pk-...", service_name="support-agent")
+
+from pydantic_ai import Agent
+agent = Agent("openai:gpt-5.5", name="support")
+result = await agent.run("Refund order 42", conversation_id="thread-42")
+```
+
+pydantic-ai already emits OpenTelemetry GenAI spans; `struct.init()` turns
+that on for every agent (`Agent.instrument_all`) with Struct's tracer
+provider, unless you already set your own default (for example with
+logfire). You get pydantic-ai's `invoke_agent`, `chat` and `execute_tool`
+spans, with one `chat` span per model call (Struct's OpenAI and Anthropic
+patches stay out of the way for pydantic-ai's own provider calls; model
+calls your code makes while reading a stream keep their spans). During agent
+runs, Struct guards telemetry faults and caps content. Realtime sessions and
+direct `InstrumentedModel` exception recording are outside this guarantee.
+
+- **Content** goes on span attributes only (pydantic-ai has no message
+  events): `span_only` / `span_and_event` include prompts, answers and tool
+  arguments; `event_only` and `none` do not. Tool definitions are always
+  recorded.
+- **Sessions:** on Struct's provider, a `struct.agent(session_id=...)`
+  around the run wins; otherwise pydantic-ai's `conversation_id` is used.
+  Instrumentation configured on your own provider keeps its conversation IDs.
+- **Turn it off** with
+  `struct.init(..., instrumentation_options={"pydantic_ai": {"enabled": False}})`,
+  or for one agent with `agent.instrument = False`. An
+  `Agent.instrument_all(False)` before `struct.init()` is pydantic-ai's
+  initial value, so it does not keep pydantic-ai off.
+
 #### LangChain / LangGraph (with an agent or graph)
 
 ```python

{struct_sdk-0.3.1 → struct_sdk-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.3.1"
+version = "0.3.2"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -48,6 +48,9 @@ claude-agent-sdk = ["claude-agent-sdk>=0.2.121", "mcp>=1.30.0,<2"]
 langchain = ["langchain-core>=1.3.3"]
 # Responses API (openai.resources.responses) exists from 1.66.0 onward.
 openai = ["openai>=1.66.0"]
+# pydantic-ai's own OpenTelemetry instrumentation, driven with Struct's
+# provider. 2.53.0 is the oldest release the suite runs against.
+pydantic-ai = ["pydantic-ai-slim>=2.53.0"]
 # Full-app mode (the default). Each instrumentor only activates when its
 # target library is installed. Otherwise unpinned so the resolver picks the
 # release matching the host's opentelemetry-sdk. The floor is contrib 0.51b0
@@ -154,6 +157,9 @@ dev = [
     # Zero-code activation is tested next to the standard distro's configurator.
     "opentelemetry-distro",
     "temporalio>=1.11.0",
+    # pydantic-ai conformance suite (tests/test_pydantic_ai.py): real Agent
+    # runs, and pydantic-ai's OpenAI model over the transport-mocked client.
+    "pydantic-ai-slim[openai]>=2.53.0",
 ]
 
 [tool.uv]
@@ -177,7 +183,7 @@ markers = [
 
 [tool.mypy]
 [[tool.mypy.overrides]]
-module = ["anthropic", "anthropic.*", "claude_agent_sdk", "claude_agent_sdk.*", "langchain_core", "langchain_core.*", "langchain", "langchain.*", "langgraph", "langgraph.*", "openai", "openai.*", "opentelemetry.instrumentation.*", "azure.core.*", "temporalio", "temporalio.*", "requests", "requests.*", "opentelemetry.resource.*", "ddtrace", "ddtrace.*"]
+module = ["anthropic", "anthropic.*", "pydantic_ai", "pydantic_ai.*", "claude_agent_sdk", "claude_agent_sdk.*", "langchain_core", "langchain_core.*", "langchain", "langchain.*", "langgraph", "langgraph.*", "openai", "openai.*", "opentelemetry.instrumentation.*", "azure.core.*", "temporalio", "temporalio.*", "requests", "requests.*", "opentelemetry.resource.*", "ddtrace", "ddtrace.*"]
 ignore_missing_imports = true
 
 [tool.hatch.build.targets.wheel]

{struct_sdk-0.3.1 → struct_sdk-0.3.2}/src/struct_sdk/_genai_content.py

@@ -60,29 +60,26 @@ def truncate_field(value: "str | Any", max_len: int = _MAX_FIELD_SIZE) -> "str |
     return value
 
 
+# Part fields that hold a structured payload (tool arguments and results), capped as
+# serialized JSON. pydantic-ai puts a tool's output under ``result``, OTel under
+# ``response``.
+_STRUCTURED_PART_FIELDS = ("arguments", "response", "result")
+
+
 def truncate_parts(parts: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    """Truncate content fields within message parts (content/arguments/response)."""
+    """Cap every field of message parts: any string field (text, reasoning, ids, URIs,
+    inline data, tool results) at 16 KiB, and a structured tool payload at 16 KiB of
+    its JSON. Keys are kept."""
     result = []
     for part in parts:
         part = dict(part)  # shallow copy
-        if "content" in part and isinstance(part["content"], str):
-            part["content"] = truncate_field(part["content"])
-        if "arguments" in part:
-            arg = part["arguments"]
-            if isinstance(arg, str):
-                part["arguments"] = truncate_field(arg)
-            elif isinstance(arg, dict):
-                serialized = json.dumps(arg, default=str)
+        for key, value in part.items():
+            if isinstance(value, str):
+                part[key] = truncate_field(value)
+            elif key in _STRUCTURED_PART_FIELDS and isinstance(value, (dict, list)):
+                serialized = json.dumps(value, default=str)
                 if len(serialized) > _MAX_FIELD_SIZE:
-                    part["arguments"] = serialized[:_MAX_FIELD_SIZE] + _TRUNCATION_MARKER
-        if "response" in part:
-            resp = part["response"]
-            if isinstance(resp, str):
-                part["response"] = truncate_field(resp)
-            elif isinstance(resp, (dict, list)):
-                serialized = json.dumps(resp, default=str)
-                if len(serialized) > _MAX_FIELD_SIZE:
-                    part["response"] = serialized[:_MAX_FIELD_SIZE] + _TRUNCATION_MARKER
+                    part[key] = serialized[:_MAX_FIELD_SIZE] + _TRUNCATION_MARKER
         result.append(part)
     return result
 
@@ -92,10 +89,10 @@ def truncate_and_serialize(obj: Any, max_size: int = _MAX_CONTENT_SIZE) -> str:
 
     Unlike a blind string slice, this preserves valid JSON by truncating
     content/arguments/response fields within parts before serialization.
-    If the result still exceeds ``max_size`` after field truncation, applies
-    a final hard cap that tries to keep the JSON array parseable.
+    If the result still exceeds ``max_size`` after field truncation, keeps the
+    whole leading array elements that fit, so the result stays valid JSON.
     """
-    if isinstance(obj, list):
+    if isinstance(obj, (list, tuple)):
         truncated = []
         for item in obj:
             if isinstance(item, dict):
@@ -110,19 +107,72 @@ def truncate_and_serialize(obj: Any, max_size: int = _MAX_CONTENT_SIZE) -> str:
     else:
         result = json.dumps(obj, default=str)
 
-    # If still too large after field-level truncation, do a final hard cap
-    # but try to close the JSON array to keep it parseable.
+    # Still too large after field-level truncation: keep whole leading array
+    # elements that fit, so the result is always valid JSON. (Cutting at the last
+    # "}" could land inside a nested part and leave its message open.)
     if len(result) > max_size:
-        cut = result[:max_size - 50]  # leave room for closing
-        last_brace = cut.rfind("}")
-        if last_brace > 0:
-            result = cut[:last_brace + 1] + "]"
-        else:
-            result = "[]"
+        if not isinstance(obj, (list, tuple)):
+            return "[]"
+        kept: list[str] = []
+        size = 2  # the enclosing brackets
+        for item in truncated:
+            encoded = json.dumps(item, default=str)
+            if not kept and size + len(encoded) > max_size:
+                # A first message too large on its own keeps its whole leading
+                # parts instead, so a single oversize message is never dropped.
+                encoded = _leading_parts_that_fit(item, max_size - size) or ""
+                if encoded:
+                    kept.append(encoded)
+                break
+            extra = len(encoded) + (2 if kept else 0)  # ", " between elements
+            if size + extra > max_size:
+                break
+            kept.append(encoded)
+            size += extra
+        result = "[" + ", ".join(kept) + "]"
 
     return result
 
 
+def _leading_parts_that_fit(item: Any, budget: int) -> Optional[str]:
+    """``item`` (a message) serialized with only the leading ``parts`` that fit in
+    ``budget`` characters, or ``None`` when it has no parts or none fit."""
+    if not isinstance(item, dict) or not isinstance(item.get("parts"), list):
+        return None
+    # Linear: the envelope and each part are serialized once (re-serializing the
+    # growing prefix per part was quadratic on the host's request path).
+    marker = "\x00struct-parts\x00"
+    envelope = json.dumps({**item, "parts": marker}, default=str)
+    marker_json = json.dumps(marker)
+    if envelope.count(marker_json) != 1:  # the message itself holds the marker text
+        return _leading_parts_that_fit_slow(item, budget)
+    size = len(envelope) - len(marker_json) + 2  # the parts list's brackets
+    kept: list[str] = []
+    for part in item["parts"]:
+        encoded = json.dumps(part, default=str)
+        extra = len(encoded) + (2 if kept else 0)  # ", " between parts
+        if size + extra > budget:
+            break
+        kept.append(encoded)
+        size += extra
+    if not kept:
+        return None
+    return envelope.replace(marker_json, "[" + ", ".join(kept) + "]", 1)
+
+
+def _leading_parts_that_fit_slow(item: Any, budget: int) -> Optional[str]:
+    """``_leading_parts_that_fit`` for a message containing its marker text."""
+    parts: list[Any] = []
+    best: Optional[str] = None
+    for part in item["parts"]:
+        candidate = json.dumps({**item, "parts": [*parts, part]}, default=str)
+        if len(candidate) > budget:
+            break
+        parts.append(part)
+        best = candidate
+    return best
+
+
 def safe_json(obj: Any) -> str:
     """Safely serialize to JSON string with field-level truncation."""
     try:
@@ -578,9 +628,15 @@ def stamp_provider_once(agent_span: Any, provider: Optional[str]) -> None:
 
 
 def propagate_provider_to_parent(provider: Optional[str]) -> None:
-    """Stamp the ambient ``_current_agent_span`` with the child call's provider."""
+    """Stamp the ambient ``_current_agent_span`` with the child call's provider,
+    unless a framework span that stamps it itself owns this call (SDK-PY-9)."""
     try:
-        from struct_sdk.core import _current_agent_span
+        from opentelemetry import context as otel_context
+
+        from struct_sdk.core import _PROVIDER_STAMP_OWNED_KEY, _current_agent_span
+
+        if otel_context.get_value(_PROVIDER_STAMP_OWNED_KEY):
+            return
         stamp_provider_once(_current_agent_span.get(None), provider)
     except Exception:
         pass  # Never break the application for telemetry

{struct_sdk-0.3.1 → struct_sdk-0.3.2}/src/struct_sdk/core.py

@@ -190,6 +190,10 @@ _pending_tool_calls: contextvars.ContextVar[Optional[dict[str, list[str]]]] = co
 # and whose contextvar token could raise ``ValueError: Token created in a different
 # Context`` when detached from a different async context).
 _GENAI_SUPPRESS_KEY = create_key("struct.suppress_genai")
+# Set with the suppression key when the owning framework span stamps the agent's
+# provider itself (pydantic-ai, from the call that answered): a stood-down provider
+# patch then leaves the agent span's provider to it (SDK-PY-9).
+_PROVIDER_STAMP_OWNED_KEY = _otel_context.create_key("struct_provider_stamp_owned")
 
 
 def is_genai_suppressed() -> bool:
@@ -199,7 +203,7 @@ def is_genai_suppressed() -> bool:
     return bool(_otel_context.get_value(_GENAI_SUPPRESS_KEY))
 
 
-def suppress_genai_token() -> "tuple[Token[_OtelContext], Optional[asyncio.Task[Any]]]":
+def suppress_genai_token(*, owns_provider_stamp: bool = False) -> "tuple[Token[_OtelContext], Optional[asyncio.Task[Any]]]":
     """Attach the suppression key to the current OTel context.
 
     Returns ``(token, enter_task)`` that MUST be passed to ``reset_genai()`` when
@@ -208,7 +212,10 @@ def suppress_genai_token() -> "tuple[Token[_OtelContext], Optional[asyncio.Task[
     schedule on DIFFERENT asyncio tasks, so the enter-task travels with the token
     for a task-affinity-safe detach.
     """
-    token = _otel_context.attach(_otel_context.set_value(_GENAI_SUPPRESS_KEY, True))
+    context = _otel_context.set_value(_GENAI_SUPPRESS_KEY, True)
+    if owns_provider_stamp:
+        context = _otel_context.set_value(_PROVIDER_STAMP_OWNED_KEY, True, context)
+    token = _otel_context.attach(context)
     return token, _current_task_or_none()
 
 
@@ -812,6 +819,9 @@ class StructSDK:
                 Other keys are passed to that instrumentor's ``instrument()``.
                 Names listed in ``OTEL_PYTHON_DISABLED_INSTRUMENTATIONS`` (or
                 ``*``) default to disabled; an explicit entry here wins.
+                ``{"enabled": False}`` also turns off a GenAI integration in
+                any mode: ``anthropic``, ``claude_agent_sdk``,
+                ``langchain_core``, ``openai``, ``pydantic_ai``.
             redact_attributes: Glob patterns (case-insensitive) for span,
                 span-event and log attributes whose values Struct sends as
                 "[REDACTED]", e.g. ``["http.request.header.authorization",
@@ -878,7 +888,7 @@ class StructSDK:
                 global _init_pid
                 _init_pid = os.getpid()
 
-                self._auto_instrument()
+                self._auto_instrument(instrumentation_options or {})
             except Exception:
                 logger.warning(
                     "Struct SDK init failed; SDK disabled: service=%s endpoint=%s",
@@ -905,18 +915,22 @@ class StructSDK:
                 self._service_name, endpoint, self._content_capture.value,
             )
 
-    def _auto_instrument(self):
-        """Detect and patch installed libraries."""
+    def _auto_instrument(self, options: Optional[Mapping[str, Mapping[str, Any]]] = None):
+        """Detect and patch installed libraries, except those turned off with
+        ``instrumentation_options={name: {"enabled": False}}``."""
         integrations = [
             ("anthropic", "struct_sdk.anthropic"),
             ("claude_agent_sdk", "struct_sdk.claude_agent"),
             ("langchain_core", "struct_sdk.langchain"),
             ("openai", "struct_sdk.openai"),
+            ("pydantic_ai", "struct_sdk.pydantic_ai"),
         ]
 
         for lib_name, module_path in integrations:
             if lib_name in _patched_integrations:
                 continue
+            if (options or {}).get(lib_name, {}).get("enabled", True) is False:
+                continue
             try:
                 import importlib
                 mod = importlib.import_module(module_path)