struct-sdk 0.2.10__tar.gz → 0.2.12__tar.gz

{struct_sdk-0.2.10 → struct_sdk-0.2.12}/.gitignore

@@ -87,12 +87,9 @@ apps/edgedive-functions/local.settings.json
 # Claude
 .claude/worktrees/
 .claude/scheduled_tasks.lock
-.superpowers/
-docs/superpowers/
 
-# Superpowers
+# Superpowers working state (design specs and plans under docs/superpowers/ ARE committed)
 .superpowers/
-docs/superpowers/
 
 .playwright-mcp/
 struct-agent-key.json

{struct_sdk-0.2.10 → struct_sdk-0.2.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: struct-sdk
-Version: 0.2.10
+Version: 0.2.12
 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
@@ -8,7 +8,7 @@ Project-URL: Issues, https://struct.ai/support
 Author-email: Struct <support@struct.ai>
 License: Apache-2.0
 License-File: LICENSE
-Keywords: agent,ai,anthropic,langchain,observability,opentelemetry,struct,tracing
+Keywords: agent,ai,anthropic,langchain,observability,openai,opentelemetry,struct,tracing
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -42,14 +42,16 @@ Requires-Dist: pytest>=9.0.3; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
 Provides-Extra: langchain
 Requires-Dist: langchain-core>=1.3.3; extra == 'langchain'
+Provides-Extra: openai
+Requires-Dist: openai>=1.66.0; extra == 'openai'
 Description-Content-Type: text/markdown
 
 # struct-sdk
 
 OpenTelemetry instrumentation for AI agents in Python. Captures spans,
-token usage, and message events from the Anthropic SDK, the Claude Agent
-SDK, and LangChain / LangGraph, and exports them to
-[struct.ai](https://struct.ai) for observability.
+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.
 
 A TypeScript version is available as
 [`@struct-ai/sdk`](https://www.npmjs.com/package/@struct-ai/sdk). Both
@@ -62,6 +64,7 @@ mix languages without a fragmented view.
 pip install struct-sdk
 # optional — the SDK auto-instruments these if present
 pip install anthropic
+pip install openai
 pip install claude-agent-sdk
 pip install langchain-core langgraph
 ```
@@ -106,6 +109,7 @@ async with struct.agent(name="checkout"):
 | Library | Span type | Notes |
 |---|---|---|
 | `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). |
 | `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}` | Skipped when an underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic` → a single span). |
 | `langchain_core` `BaseTool` | `execute_tool {name}` | `tool_call_id` extracted from the LangChain ToolCall when present. |

{struct_sdk-0.2.10 → struct_sdk-0.2.12}/README.md

@@ -1,9 +1,9 @@
 # struct-sdk
 
 OpenTelemetry instrumentation for AI agents in Python. Captures spans,
-token usage, and message events from the Anthropic SDK, the Claude Agent
-SDK, and LangChain / LangGraph, and exports them to
-[struct.ai](https://struct.ai) for observability.
+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.
 
 A TypeScript version is available as
 [`@struct-ai/sdk`](https://www.npmjs.com/package/@struct-ai/sdk). Both
@@ -16,6 +16,7 @@ mix languages without a fragmented view.
 pip install struct-sdk
 # optional — the SDK auto-instruments these if present
 pip install anthropic
+pip install openai
 pip install claude-agent-sdk
 pip install langchain-core langgraph
 ```
@@ -60,6 +61,7 @@ async with struct.agent(name="checkout"):
 | Library | Span type | Notes |
 |---|---|---|
 | `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). |
 | `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}` | Skipped when an underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic` → a single span). |
 | `langchain_core` `BaseTool` | `execute_tool {name}` | `tool_call_id` extracted from the LangChain ToolCall when present. |

{struct_sdk-0.2.10 → struct_sdk-0.2.12}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.2.10"
+version = "0.2.12"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "Apache-2.0" }
 authors = [{ name = "Struct", email = "support@struct.ai" }]
-keywords = ["struct", "observability", "opentelemetry", "anthropic", "langchain", "agent", "ai", "tracing"]
+keywords = ["struct", "observability", "opentelemetry", "anthropic", "openai", "langchain", "agent", "ai", "tracing"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
@@ -39,6 +39,8 @@ Issues = "https://struct.ai/support"
 anthropic = ["anthropic>=0.30.0"]
 claude-agent-sdk = ["claude-agent-sdk>=0.1.59"]
 langchain = ["langchain-core>=1.3.3"]
+# Responses API (openai.resources.responses) exists from 1.66.0 onward.
+openai = ["openai>=1.66.0"]
 demo = [
     "langchain>=1.3.9",
     "langchain-core>=1.3.3",
@@ -60,6 +62,12 @@ dev = [
     "pytest-asyncio>=1.3.0",
     "mypy>=1.10",
     "ruff>=0.5",
+    # The OpenAI conformance suite (tests/test_openai_conformance.py) exercises
+    # the REAL openai client with HTTP mocked at the httpx transport boundary,
+    # so both must be present in the default test environment (CI runs
+    # `uv run pytest` with no extras).
+    "openai>=1.66.0",
+    "httpx>=0.27.0",
 ]
 
 [tool.uv]
@@ -81,7 +89,7 @@ markers = [
 
 [tool.mypy]
 [[tool.mypy.overrides]]
-module = ["anthropic", "anthropic.*", "claude_agent_sdk", "claude_agent_sdk.*", "langchain_core", "langchain_core.*", "langchain", "langchain.*", "langgraph", "langgraph.*"]
+module = ["anthropic", "anthropic.*", "claude_agent_sdk", "claude_agent_sdk.*", "langchain_core", "langchain_core.*", "langchain", "langchain.*", "langgraph", "langgraph.*", "openai", "openai.*"]
 ignore_missing_imports = true
 
 [tool.hatch.build.targets.wheel]

struct_sdk-0.2.12/src/struct_sdk/_genai_content.py

@@ -0,0 +1,265 @@
+"""Provider-agnostic GenAI content primitives — shared by the anthropic and
+openai integrations.
+
+This module is the single home for the pieces that are genuinely the same
+across providers once a message/response has been mapped to the spec's
+``{"role", "parts"}`` shape:
+
+- Truncation constants + helpers (``truncate_field`` / ``truncate_parts`` /
+  ``truncate_and_serialize`` / ``safe_json``).
+- The low-level per-message and choice LogRecord emitters
+  (``emit_message_event`` / ``emit_choice_event``) — they take already-built
+  ``parts`` and a ``provider`` string, so the OTel logs data-model wiring
+  (``body`` = event tag, ``attributes['body']`` = JSON payload, span-context
+  from the EXPLICIT span) lives in exactly one place.
+- ``propagate_user_prompt_to_parent`` — write-once parent ``gen_ai.input.messages``
+  from the last user message's parts.
+
+The per-provider MAPPER (Anthropic message blocks vs OpenAI Responses items ->
+``parts``) is the only content code that stays provider-specific; it lives in
+``anthropic.py`` / ``openai.py`` and calls into this module.
+
+Both this bug (OpenAI emitting zero content) and the earlier reset bug came from
+``openai.py`` diverging from ``anthropic.py``; sharing these primitives is the
+structural fix. Everything here is written to NEVER fault the customer call —
+each public emitter is wrapped in try/except -> ``logger.debug``.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+from typing import Any, Optional
+
+from opentelemetry import trace
+
+logger = logging.getLogger("struct_sdk._genai_content")
+
+# Max size for content attributes (JSON strings on spans).
+_MAX_CONTENT_SIZE = 128 * 1024  # 128KB — generous limit for full message capture
+_TRUNCATION_MARKER = "… [truncated]"
+# Per-field cap: individual text/content fields longer than this get truncated.
+_MAX_FIELD_SIZE = 16384  # 16KB per field
+
+
+# ---------------------------------------------------------------------------
+# Truncation / serialization
+# ---------------------------------------------------------------------------
+
+def truncate_field(value: "str | Any", max_len: int = _MAX_FIELD_SIZE) -> "str | Any":
+    """Truncate a single string field if it exceeds ``max_len``."""
+    if isinstance(value, str) and len(value) > max_len:
+        return value[:max_len] + _TRUNCATION_MARKER
+    return value
+
+
+def truncate_parts(parts: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Truncate content fields within message parts (content/arguments/response)."""
+    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)
+                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
+        result.append(part)
+    return result
+
+
+def truncate_and_serialize(obj: Any, max_size: int = _MAX_CONTENT_SIZE) -> str:
+    """Truncate individual fields in message structures, then serialize.
+
+    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 isinstance(obj, list):
+        truncated = []
+        for item in obj:
+            if isinstance(item, dict):
+                item = dict(item)  # shallow copy
+                if "parts" in item and isinstance(item["parts"], list):
+                    item["parts"] = truncate_parts(item["parts"])
+                elif "content" in item and isinstance(item["content"], str):
+                    # Top-level content (e.g. system_instructions format)
+                    item["content"] = truncate_field(item["content"])
+            truncated.append(item)
+        result = json.dumps(truncated, default=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.
+    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 = "[]"
+
+    return result
+
+
+def safe_json(obj: Any) -> str:
+    """Safely serialize to JSON string with field-level truncation."""
+    try:
+        return truncate_and_serialize(obj)
+    except Exception:
+        return "[]"
+
+
+# ---------------------------------------------------------------------------
+# LogRecord emission — OTel logs data model
+# ---------------------------------------------------------------------------
+
+def emit_message_event(
+    otel_logger: Any,
+    *,
+    role: str,
+    parts: list[dict[str, Any]],
+    event_name: str,
+    provider: str,
+    message_index: int,
+    span: Optional[trace.Span] = None,
+) -> None:
+    """Emit ONE per-message LogRecord linked to ``span``.
+
+    OTel logs data-model convention:
+    - ``body`` (log record body): the event tag (``gen_ai.user.message`` etc.).
+    - ``attributes['body']``: the JSON payload ``{"role": ..., "parts": [...]}``.
+    - Other attributes: ``event.name``, ``gen_ai.provider.name``,
+      ``gen_ai.message.index``, and ``gen_ai.conversation.id`` when a session is
+      active.
+
+    Span-context is taken from the EXPLICIT ``span`` when given —
+    ``trace.get_current_span()`` can drop the active span across the generator
+    wrapper's async awaits. All work is best-effort: a failure here NEVER
+    reaches the customer's call (it becomes a ``logger.debug``).
+    """
+    try:
+        from opentelemetry._logs import LogRecord, SeverityNumber
+
+        span_ctx = (span or trace.get_current_span()).get_span_context()
+        from struct_sdk.core import _current_session_id
+        session_id = _current_session_id.get(None)
+
+        payload = json.dumps({"role": role, "parts": truncate_parts(parts)}, default=str)
+        attrs: dict[str, Any] = {
+            "event.name": event_name,
+            "body": payload,
+            "gen_ai.provider.name": provider,
+            "gen_ai.message.index": message_index,
+        }
+        if session_id:
+            attrs["gen_ai.conversation.id"] = session_id
+
+        otel_logger.emit(LogRecord(
+            timestamp=int(time.time_ns()),
+            trace_id=span_ctx.trace_id,
+            span_id=span_ctx.span_id,
+            trace_flags=span_ctx.trace_flags,
+            severity_number=SeverityNumber.INFO,
+            body=event_name,
+            attributes=attrs,
+        ))
+    except Exception:
+        logger.debug("Failed to emit message event", exc_info=True)
+
+
+def emit_choice_event(
+    otel_logger: Any,
+    *,
+    parts: list[dict[str, Any]],
+    finish_reason: str,
+    provider: str,
+    span: Optional[trace.Span] = None,
+) -> None:
+    """Emit a ``gen_ai.choice`` LogRecord for the assistant's response.
+
+    ``parts`` are already spec-shaped assistant parts and ``finish_reason`` is
+    already mapped to the spec name by the caller (mapping is provider-specific).
+    The ``choice`` event omits ``gen_ai.message.index``.
+    """
+    try:
+        from opentelemetry._logs import LogRecord, SeverityNumber
+
+        span_ctx = (span or trace.get_current_span()).get_span_context()
+        from struct_sdk.core import _current_session_id
+        session_id = _current_session_id.get(None)
+
+        choice_body = {
+            "index": 0,
+            "finish_reason": finish_reason or "stop",
+            "message": {"role": "assistant", "parts": truncate_parts(parts)},
+        }
+        payload = json.dumps(choice_body, default=str)
+        event_name = "gen_ai.choice"
+        attrs: dict[str, Any] = {
+            "event.name": event_name,
+            "body": payload,
+            "gen_ai.provider.name": provider,
+        }
+        if session_id:
+            attrs["gen_ai.conversation.id"] = session_id
+
+        otel_logger.emit(LogRecord(
+            timestamp=int(time.time_ns()),
+            trace_id=span_ctx.trace_id,
+            span_id=span_ctx.span_id,
+            trace_flags=span_ctx.trace_flags,
+            severity_number=SeverityNumber.INFO,
+            body=event_name,
+            attributes=attrs,
+        ))
+    except Exception:
+        logger.debug("Failed to emit choice event", exc_info=True)
+
+
+# ---------------------------------------------------------------------------
+# Parent-span propagation
+# ---------------------------------------------------------------------------
+
+def propagate_user_prompt_to_parent(last_user_parts: Optional[list[dict[str, Any]]]) -> None:
+    """Set the last user message on the parent invoke_agent span (write-once).
+
+    This lets the waterfall UI show what the user asked without drilling into
+    the child chat span. Provider-agnostic: the caller extracts the last user
+    message's spec parts (Anthropic message blocks vs Responses items differ);
+    this just stamps them once on the ambient ``_current_agent_span``.
+    """
+    try:
+        if not last_user_parts:
+            return
+        from struct_sdk.core import _current_agent_span
+        agent_span = _current_agent_span.get(None)
+        if agent_span is None:
+            return
+        # Only set once — the first chat call within an invoke_agent scope wins.
+        existing = None
+        if hasattr(agent_span, "attributes"):
+            existing = agent_span.attributes.get("gen_ai.input.messages")  # type: ignore[union-attr]
+        if existing:
+            return
+        agent_span.set_attribute(
+            "gen_ai.input.messages",
+            truncate_and_serialize([{"role": "user", "parts": last_user_parts}]),
+        )
+    except Exception:
+        pass  # Never break the application for telemetry