struct-sdk 0.2.30__tar.gz → 0.2.32__tar.gz

{struct_sdk-0.2.30 → struct_sdk-0.2.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: struct-sdk
-Version: 0.2.30
+Version: 0.2.32
 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

{struct_sdk-0.2.30 → struct_sdk-0.2.32}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.2.30"
+version = "0.2.32"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -72,6 +72,9 @@ dev = [
     # `uv run pytest` with no extras).
     "openai>=1.66.0",
     "httpx>=0.27.0",
+    # The Anthropic raw-stream suite (tests/test_anthropic_raw_stream.py) drives
+    # the REAL anthropic client over a mocked httpx transport, for the same reason.
+    "anthropic>=0.30.0",
 ]
 
 [tool.uv]

{struct_sdk-0.2.30 → struct_sdk-0.2.32}/src/struct_sdk/_genai_content.py

@@ -38,6 +38,8 @@ from urllib.parse import urlparse
 from opentelemetry import trace
 from opentelemetry.trace import StatusCode
 
+from struct_sdk.core import _contain_logged
+
 logger = logging.getLogger("struct_sdk._genai_content")
 
 # Max size for content attributes (JSON strings on spans).
@@ -251,20 +253,24 @@ def _contain(fn: Any, site: str) -> None:
     guarantees cannot happen. Deliberately NOT the global ``_safe``
     semantics: everywhere else, delaying a genuine Ctrl-C matters more than
     a hostile input.
+
+    Only the first fault per site carries a traceback (SDK-PY-19): a stream's
+    per-event hooks would otherwise format one per event.
     """
-    try:
-        fn()
-    except BaseException:  # noqa: BLE001 — containment is the contract here
-        try:
-            logger.debug("telemetry self-fault contained at %s", site, exc_info=True)
-        except BaseException:  # noqa: BLE001
-            pass
+    _contain_logged(fn, site=site)
 
 
 @contextlib.contextmanager
-def guarded_client_span(tracer: Any, span_name: str) -> Iterator[Any]:
+def guarded_client_span(
+    tracer: Any, span_name: str, *, keep_open: Optional[Callable[[], bool]] = None,
+) -> Iterator[Any]:
     """Explicit CLIENT span with ``_safe``-guarded start and end.
 
+    ``keep_open`` hands the span's END to another owner: when it returns True at
+    exit, everything else still runs (the ambient context is detached on this
+    task) but the span stays open, and that owner must end it exactly once — the
+    raw ``create(stream=True)`` event stream, which ends it when the stream does.
+
     Deliberately NOT ``start_as_current_span``: ``use_span``'s exit runs
     ``span.end()`` — and with it every customer-added ``SpanProcessor.on_end``
     — plus its own ``record_exception``/``set_status`` (which stringify the
@@ -344,7 +350,7 @@ def guarded_client_span(tracer: Any, span_name: str) -> Iterator[Any]:
 
             _contain(finalize_base_exception, "genai.client_span.finalize_base")
         _contain(lambda: _detach_current_span(token, enter_task), "genai.client_span.detach")
-        if span is not None:
+        if span is not None and not (keep_open is not None and keep_open()):
             _contain(span.end, "genai.client_span.end")
 
 

{struct_sdk-0.2.30 → struct_sdk-0.2.32}/src/struct_sdk/anthropic.py

@@ -25,12 +25,16 @@ import functools
 import inspect
 import json
 import logging
+import contextvars
+import threading
+from types import SimpleNamespace
 from typing import TYPE_CHECKING, Any, Callable, Generator, Optional
 
 from opentelemetry import trace
 from opentelemetry.trace import StatusCode
 
 from struct_sdk._genai_content import (
+    _MAX_FIELD_SIZE,
     detect_provider_from_resource,
     emit_choice_event,
     emit_message_event,
@@ -54,6 +58,9 @@ logger = logging.getLogger("struct_sdk.anthropic")
 # Truncation helpers are shared with the OpenAI integration via
 # ``struct_sdk._genai_content``; re-exported here under their original private
 # names so existing internal callers keep working unchanged.
+_AMBIENT: Any = object()
+"""Sentinel: record tool-use ids into the current context's queue (the default)."""
+
 _truncate_field = truncate_field
 _truncate_parts = truncate_parts
 _truncate_and_serialize = truncate_and_serialize
@@ -146,6 +153,10 @@ def patch(sdk: StructSDK) -> None:
         if hasattr(async_cls, "stream") and not getattr(async_cls.stream, "__struct_wrapped__", False):
             async_cls.stream = _wrap_stream(async_cls.stream, tracer, sdk, otel_logger, is_async=True)  # type: ignore[method-assign]
 
+    for stream_cls in (anthropic.Stream, anthropic.AsyncStream):
+        if not getattr(stream_cls.close, "__struct_close_hook__", False):
+            stream_cls.close = _close_hook(stream_cls.close)  # type: ignore[method-assign]
+
     anthropic.__struct_patched = True  # type: ignore[attr-defined]
 
 
@@ -165,6 +176,9 @@ def unpatch() -> None:
             method = getattr(cls, method_name, None)
             if method and getattr(method, "__struct_wrapped__", False):
                 setattr(cls, method_name, method.__struct_original__)
+    for stream_cls in (anthropic.Stream, anthropic.AsyncStream):
+        if getattr(stream_cls.close, "__struct_close_hook__", False):
+            stream_cls.close = getattr(stream_cls.close, "__struct_original__")  # type: ignore[method-assign]
 
     anthropic.__struct_patched = False  # type: ignore[attr-defined]
 
@@ -214,7 +228,9 @@ def _create_common(
     # guarded_client_span, not start_as_current_span: use_span's exit runs
     # span.end() (=> every customer SpanProcessor.on_end) and its own
     # record_exception unguarded on the gen.send/gen.throw host path.
-    with guarded_client_span(tracer, f"chat {model}") as span:
+    # ``handed_off``: a raw ``stream=True`` result took over ending the span.
+    handed_off = False
+    with guarded_client_span(tracer, f"chat {model}", keep_open=lambda: handed_off) as span:
         def set_pre_call_attrs() -> None:
             # Required attributes
             span.set_attribute("gen_ai.operation.name", "chat")
@@ -285,6 +301,16 @@ def _create_common(
                 site="anthropic.create.record_exception",
             )
             raise
+        if kwargs.get("stream") and span is not None:
+            # The raw event stream: the response (and its usage) is still to
+            # come, so the span ends when the stream does ([SDK-PY-24]).
+            def hand_off() -> None:
+                nonlocal handed_off
+                handed_off = _instrument_raw_stream(result, span, sdk, model, otel_logger, provider)
+
+            _safe(hand_off, site="anthropic.create.raw_stream")
+            if handed_off:
+                return result  # noqa: B901
         _safe(lambda: _set_response_attrs(span, sdk, model, result, otel_logger, provider),
               site="anthropic.create.set_response_attrs")
         _safe(lambda: span.set_status(StatusCode.OK),
@@ -292,6 +318,370 @@ def _create_common(
         return result  # noqa: B901
 
 
+# ---------------------------------------------------------------------------
+# messages.create(stream=True) — the raw event stream
+# ---------------------------------------------------------------------------
+#
+# ``create(stream=True)`` returns the provider's ``Stream`` / ``AsyncStream`` of
+# raw SSE events; usage, the response id and the content only arrive as the
+# caller iterates. The SDK keeps the host's stream object (identity, type and
+# every event unchanged) and swaps in an iterator that observes each event and
+# ends the ``chat`` span exactly once: on exhaustion, an error or cancellation
+# mid-stream, ``close()`` (which ``with`` / ``async with`` exit calls), or
+# garbage collection of an abandoned stream. Mirrors struct-sdk-typescript's
+# ``instrumentRawStream``. No ambient context is held across the caller's
+# iteration: the span was detached when ``create()`` returned.
+
+_ITERATOR_SLOT = "_iterator"
+"""The attribute anthropic's ``Stream`` / ``AsyncStream`` iterate (``__iter__``,
+``__next__`` and their async twins all read it). A stream without it keeps the
+pre-0.2.32 behaviour: the span ends when ``create()`` returns."""
+
+
+_TELEMETRY_SLOT = "_struct_raw_stream_telemetry"
+"""Where a hooked stream keeps its ``_RawStreamTelemetry``, read by the
+class-level close hook. The stream holds the telemetry, never the reverse."""
+
+
+def _close_hook(original: Any) -> Any:
+    """Stream / AsyncStream ``close``, hooked once at the class: a stream with
+    telemetry ends its span after the provider's close (with the error, if it
+    raised); any other stream just closes. The method stays bound to the
+    stream, so cleanup the host defers (an ExitStack callback) keeps it alive."""
+    if inspect.iscoroutinefunction(original):
+        @functools.wraps(original)
+        async def aclose(self: Any) -> Any:
+            telemetry = _attached_telemetry(self)
+            try:
+                result = await original(self)
+            except BaseException as e:
+                if telemetry is not None:
+                    telemetry.end((type(e), e, None))
+                raise
+            if telemetry is not None:
+                telemetry.end(())
+            return result
+        hooked: Any = aclose
+    else:
+        @functools.wraps(original)
+        def close(self: Any) -> Any:
+            telemetry = _attached_telemetry(self)
+            try:
+                result = original(self)
+            except BaseException as e:
+                if telemetry is not None:
+                    telemetry.end((type(e), e, None))
+                raise
+            if telemetry is not None:
+                telemetry.end(())
+            return result
+        hooked = close
+    hooked.__struct_close_hook__ = True
+    hooked.__struct_original__ = original
+    return hooked
+
+
+def _attached_telemetry(stream: Any) -> Any:
+    try:
+        return vars(stream).get(_TELEMETRY_SLOT)
+    except BaseException:  # noqa: BLE001 — never fail the host's close
+        return None
+
+
+_TEXT_BUDGET = _MAX_FIELD_SIZE + 1
+"""Characters of text or reasoning one content block retains: one over the
+exported field cap, so truncation (and its marker) still applies downstream."""
+
+
+class _StreamAccumulator:
+    """Rebuilds the final message from raw events, for ``_set_response_attrs``.
+
+    Text, reasoning and tool arguments are kept only when content is captured;
+    tool-use ids and names always are (tool-call linkage is structural).
+    """
+
+    def __init__(self, keep_text: bool) -> None:
+        self._keep_text = keep_text
+        self._seen = False
+        self.id: Optional[str] = None
+        self.model: Optional[str] = None
+        self.stop_reason: Optional[str] = None
+        self._usage: dict[str, int] = {}
+        self._blocks: dict[int, dict[str, Any]] = {}
+
+    def _take_usage(self, usage: Any) -> None:
+        for key in ("input_tokens", "output_tokens", "cache_read_input_tokens",
+                    "cache_creation_input_tokens"):
+            value = getattr(usage, key, None)
+            if isinstance(value, int):
+                self._usage[key] = value
+
+    def add(self, event: Any) -> None:
+        kind = getattr(event, "type", None)
+        index = getattr(event, "index", None)
+        if kind == "message_start":
+            message = getattr(event, "message", None)
+            self._seen = True
+            self.id = getattr(message, "id", None)
+            self.model = getattr(message, "model", None)
+            self._take_usage(getattr(message, "usage", None))
+        elif kind == "message_delta":
+            self.stop_reason = getattr(getattr(event, "delta", None), "stop_reason", None) or self.stop_reason
+            # Cumulative counts: output always, input/cache when the API sends them.
+            self._take_usage(getattr(event, "usage", None))
+        elif kind == "content_block_start" and isinstance(index, int):
+            block = getattr(event, "content_block", None)
+            block_type = getattr(block, "type", None)
+            entry: dict[str, Any] = {"type": block_type}
+            # Text pieces are collected in lists and joined once in
+            # final_message: += on a stored str copies it on every delta.
+            if block_type == "tool_use":
+                # Linkage needs only the id and name; the arguments are content.
+                entry.update(id=getattr(block, "id", None), name=getattr(block, "name", None))
+                if self._keep_text:
+                    entry["json"] = []
+            elif block_type == "text" and self._keep_text:
+                entry.update(text=[], budget=_TEXT_BUDGET)
+                self._keep(entry, "text", getattr(block, "text", "") or "")
+            elif block_type == "thinking" and self._keep_text:
+                entry.update(thinking=[], budget=_TEXT_BUDGET)
+                self._keep(entry, "thinking", getattr(block, "thinking", "") or "")
+            self._blocks[index] = entry
+        elif kind == "content_block_delta" and isinstance(index, int):
+            open_block = self._blocks.get(index)
+            delta = getattr(event, "delta", None)
+            delta_type = getattr(delta, "type", None)
+            if open_block is None:
+                return
+            if delta_type == "input_json_delta" and "json" in open_block:
+                open_block["json"].append(getattr(delta, "partial_json", "") or "")
+            elif delta_type == "text_delta" and "text" in open_block:
+                self._keep(open_block, "text", getattr(delta, "text", "") or "")
+            elif delta_type == "thinking_delta" and "thinking" in open_block:
+                self._keep(open_block, "thinking", getattr(delta, "thinking", "") or "")
+
+    @staticmethod
+    def _keep(block: dict[str, Any], key: str, piece: str) -> None:
+        """Text and reasoning are exported truncated to the field cap, so each block
+        retains only that much (its own budget: a long reasoning block never
+        crowds out the answer); tool arguments are always kept whole."""
+        if block["budget"] <= 0 or not piece:
+            return
+        block[key].append(piece[: block["budget"]])
+        block["budget"] -= len(piece)
+
+    def final_message(self) -> Any:
+        if not self._seen:
+            return None
+        content = []
+        for index in sorted(self._blocks):
+            entry = {key: "".join(value) if isinstance(value, list) else value
+                     for key, value in self._blocks[index].items() if key != "budget"}
+            raw = entry.pop("json", None)
+            if raw is not None:
+                try:
+                    entry["input"] = json.loads(raw) if raw else {}
+                except (ValueError, RecursionError):
+                    entry["input"] = raw  # malformed or too deep: keep the raw arguments
+            content.append(SimpleNamespace(**entry))
+        return SimpleNamespace(
+            id=self.id, model=self.model, stop_reason=self.stop_reason, content=content,
+            usage=SimpleNamespace(**self._usage),
+        )
+
+
+def _ambient_pending_tool_calls() -> dict[str, list[str]]:
+    """The current context's tool-use queue, created (as a non-streaming call does)
+    when no agent scope set one."""
+    from struct_sdk.core import _pending_tool_calls
+    pending = _pending_tool_calls.get(None)
+    if pending is None:
+        pending = {}
+        _pending_tool_calls.set(pending)
+    return pending
+
+
+class _RawStreamTelemetry:
+    """Owns the ``chat`` span of one raw stream; ``end`` is idempotent and
+    thread-safe (garbage collection may finalize on any thread)."""
+
+    def __init__(self, span: trace.Span, sdk: "StructSDK", model: str, otel_logger: Any,
+                 provider: str) -> None:
+        # The creating call's tool-use queue, created here when none exists (as the
+        # non-streaming path does on response): child tasks that pull events, and
+        # whatever context finally ends the stream, all feed THIS queue.
+        pending = _ambient_pending_tool_calls()
+        # The creating call's context: the stream may end (or be collected) in
+        # another request's, whose session must not label this one's events.
+        self._origin: Optional[contextvars.Context] = contextvars.copy_context()
+        self._span, self._sdk, self._model = span, sdk, model
+        self._otel_logger, self._provider = otel_logger, provider
+        self._acc: Optional[_StreamAccumulator] = _StreamAccumulator(
+            keep_text=bool(sdk.emit_events or sdk.emit_span_content))
+        self._pending_tool_calls: Optional[dict[str, list[str]]] = pending
+        self._lock = threading.Lock()
+        # Armed only once every hook is in place: a half-installed stream leaves
+        # the span to create(), and these hooks must then never end it again.
+        self.armed = False
+        self._ended = False
+
+    def release(self) -> None:
+        """Drop what pins the creating request (its context and tool queue)."""
+        self._origin = None
+        self._pending_tool_calls = None
+        self._acc = None
+
+    def observe(self, event: Any) -> None:
+        acc = self._acc
+        if acc is not None:
+            # Runs inside the host's next(): contained like every host-path satellite.
+            _contain(lambda: acc.add(event), "anthropic.raw_stream.accumulate")
+        # The response is complete at message_stop: end now, so a consumer that
+        # acts on the terminal event (e.g. runs the tools) already has the
+        # tool-use ids. Contained: the event's own getters may raise.
+        def end_if_complete() -> None:
+            if getattr(event, "type", None) == "message_stop":
+                self.end(())
+
+        _contain(end_if_complete, "anthropic.raw_stream.terminal")
+
+    def end(self, exc: tuple) -> None:
+        with self._lock:
+            if self._ended or not self.armed:
+                return
+            self._ended = True
+        acc, self._acc = self._acc, None  # release what was accumulated
+        pending: Any = self._pending_tool_calls  # captured at create; always set here
+        final: Any = None
+
+        def build() -> None:
+            nonlocal final
+            if acc is not None:
+                final = acc.final_message()
+
+        # Its own guard: a fault rebuilding the message loses response attributes,
+        # never the span's end.
+        _contain(build, "anthropic.raw_stream.final_message")
+        origin = self._origin or contextvars.copy_context()  # set until the one end
+        try:
+            _contain(
+                lambda: origin.run(
+                    _finish_stream_span_with_final,
+                    self._span, final, self._sdk, self._model, self._otel_logger, exc,
+                    self._provider, pending_tool_calls=pending,
+                ),
+                "anthropic.raw_stream.end",
+            )
+        finally:
+            # Ended: drop what pins the creating request (its whole context and
+            # tool queue) for as long as the host keeps the stream object.
+            self._origin = None
+            self._pending_tool_calls = None
+
+
+class _ObservedEvents:
+    """The stream's iterator, observed: every event passes through unchanged."""
+
+    __slots__ = ("_inner", "_telemetry")
+
+    def __init__(self, inner: Any, telemetry: _RawStreamTelemetry) -> None:
+        self._inner, self._telemetry = inner, telemetry
+
+    def __iter__(self) -> "_ObservedEvents":
+        return self
+
+    def __del__(self) -> None:
+        # The stream was collected without ending: GC ends the span. (No
+        # weakref.finalize: its first use registers a process exit hook.)
+        try:
+            self._telemetry.end(())
+        except BaseException:  # noqa: BLE001 — never raise out of a finalizer
+            pass
+
+    def __next__(self) -> Any:
+        try:
+            event = next(self._inner)
+        except StopIteration:
+            self._telemetry.end(())
+            raise
+        except BaseException as e:
+            # No traceback read here: a host exception's __traceback__ getter
+            # can raise, and nothing may replace the host's error.
+            self._telemetry.end((type(e), e, None))
+            raise
+        self._telemetry.observe(event)
+        return event
+
+
+class _ObservedAsyncEvents:
+    __slots__ = ("_inner", "_telemetry")
+
+    def __init__(self, inner: Any, telemetry: _RawStreamTelemetry) -> None:
+        self._inner, self._telemetry = inner, telemetry
+
+    def __aiter__(self) -> "_ObservedAsyncEvents":
+        return self
+
+    def __del__(self) -> None:
+        try:
+            self._telemetry.end(())
+        except BaseException:  # noqa: BLE001 — never raise out of a finalizer
+            pass
+
+    async def __anext__(self) -> Any:
+        try:
+            event = await self._inner.__anext__()
+        except StopAsyncIteration:
+            self._telemetry.end(())
+            raise
+        except BaseException as e:
+            self._telemetry.end((type(e), e, None))
+            raise
+        self._telemetry.observe(event)
+        return event
+
+
+def _instrument_raw_stream(
+    stream: Any, span: trace.Span, sdk: "StructSDK", model: str, otel_logger: Any, provider: str,
+) -> bool:
+    """Make ``stream`` end ``span`` when it ends. False when it can't be hooked
+    (the caller then ends the span now, as before)."""
+    # Another tracer may hand back a proxy around the provider's stream (ddtrace's
+    # wrapt TracedStream): hook the stream it wraps, which the proxy delegates to.
+    for _ in range(8):
+        if getattr(type(stream), "close", None) is not None or not hasattr(stream, "__wrapped__"):
+            break
+        stream = stream.__wrapped__
+    inner = getattr(stream, _ITERATOR_SLOT, None)
+    class_close = getattr(type(stream), "close", None)
+    if inner is None or class_close is None:
+        return False
+    if "close" in getattr(stream, "__dict__", {}):
+        # Someone already replaced close on this instance (the host, another
+        # tracer): calling the class's would bypass their cleanup. Decline.
+        return False
+    if not getattr(class_close, "__struct_close_hook__", False):
+        # The class overrides close below the hooked Stream / AsyncStream: its
+        # close would never reach the hook. Decline.
+        return False
+    telemetry = _RawStreamTelemetry(span, sdk, model, otel_logger, provider)
+    inner_async = hasattr(inner, "__anext__")
+    observed: Any = _ObservedAsyncEvents(inner, telemetry) if inner_async else _ObservedEvents(inner, telemetry)
+    # close stays the class's own method (the class-level hook reads this slot),
+    # so a host that keeps ``stream.close`` for later cleanup keeps the stream.
+    setattr(stream, _TELEMETRY_SLOT, telemetry)
+    try:
+        setattr(stream, _ITERATOR_SLOT, observed)
+    except BaseException:
+        # Half-installed: detach the telemetry, and let go of the creating
+        # request's context; create() ends the span itself.
+        _contain(lambda: delattr(stream, _TELEMETRY_SLOT), "anthropic.raw_stream.detach")
+        telemetry.release()
+        raise
+    telemetry.armed = True
+    return True
+
+
 def _wrap_create(original: Any, tracer: trace.Tracer, sdk: StructSDK, otel_logger: Any, is_async: bool) -> Any:
     # All host-boundary mechanics (prime / error-forward / complete, each
     # BaseException-contained) live in the shared drivers — the choke point.
@@ -367,17 +757,17 @@ async def _resolve_final_message_async(stream: Any) -> Any:
 
 def _finish_stream_span_with_final(
     span: trace.Span, final_msg: Any, sdk: "StructSDK", model: str, otel_logger: Any, exc: tuple,
-    provider: str = "anthropic",
+    provider: str = "anthropic", *, pending_tool_calls: Any = _AMBIENT,
 ) -> None:
     """End the streaming ``chat`` span EXACTLY ONCE on block exit: populate
     response attributes from the already-resolved final message (best-effort —
     the stream may have been left partially consumed), set status, and end. All
-    _safe-wrapped so a broken stream can never fault the host's ``with`` block."""
-    from struct_sdk.core import _safe
+    contained so a broken stream can never fault the host's ``with`` block."""
 
     def body() -> None:
         if final_msg is not None:
-            _set_response_attrs(span, sdk, model, final_msg, otel_logger, provider)
+            _set_response_attrs(span, sdk, model, final_msg, otel_logger, provider,
+                                pending_tool_calls=pending_tool_calls)
         if exc and exc[0] is not None:
             span.set_attribute("error.type", exc[0].__name__)
             span.set_status(StatusCode.ERROR, str(exc[1]))
@@ -385,8 +775,10 @@ def _finish_stream_span_with_final(
         else:
             span.set_status(StatusCode.OK)
 
-    _safe(body, site="anthropic.stream.finish")
-    _safe(span.end, site="anthropic.stream.end")
+    # Contained separately, BaseException-safe (a failing log handler included):
+    # whatever happens to the attributes, the span still ends.
+    _contain(body, "anthropic.stream.finish")
+    _contain(span.end, "anthropic.stream.end")
 
 
 def _finish_stream_span(
@@ -710,15 +1102,23 @@ def _iter_tool_uses(content_blocks: Any) -> list[tuple[str, str]]:
     return result
 
 
-def _record_pending_tool_calls(content_blocks: Any) -> None:
+def _record_pending_tool_calls(content_blocks: Any, into: Any = _AMBIENT) -> None:
     """Push every tool_use (name, id) from the response into the SDK contextvar.
 
+    ``into`` selects a captured queue: the creating agent scope's dictionary or
+    the ambient dictionary created for a raw stream outside an agent. The default
+    uses the current context's queue; passing None skips recording.
+
     Always runs (not gated on content-capture mode) — the linkage between a
     chat span and its child execute_tool spans is structural, not content.
     """
     from struct_sdk.core import _pending_tool_calls
     pairs = _iter_tool_uses(content_blocks)
-    if not pairs:
+    if not pairs or into is None:
+        return
+    if into is not _AMBIENT:
+        for name, tool_id in pairs:
+            into.setdefault(name, []).append(tool_id)
         return
     pending = _pending_tool_calls.get()
     if pending is None:
@@ -733,7 +1133,7 @@ def _record_pending_tool_calls(content_blocks: Any) -> None:
 
 def _set_response_attrs(
     span: trace.Span, sdk: StructSDK, model: str, response: Any, otel_logger: Any = None,
-    provider: str = "anthropic",
+    provider: str = "anthropic", *, pending_tool_calls: Any = _AMBIENT,
 ) -> None:
     if not hasattr(response, "usage"):
         return
@@ -764,7 +1164,7 @@ def _set_response_attrs(
     if hasattr(response, "content"):
         # Populate pending tool_use ids for @struct.tool() auto-linkage.
         # Runs unconditionally — independent of content-capture mode.
-        _record_pending_tool_calls(response.content)
+        _record_pending_tool_calls(response.content, into=pending_tool_calls)
 
         finish_reason = getattr(response, "stop_reason", None)
 

{struct_sdk-0.2.30 → struct_sdk-0.2.32}/src/struct_sdk/core.py

@@ -16,7 +16,7 @@ import json
 import logging
 import threading
 from enum import Enum
-from typing import Any, Callable, Optional
+from typing import Any, Callable, Mapping, Optional, TypeGuard, Union
 from importlib.metadata import version as _pkg_version
 
 from opentelemetry import context as _otel_context
@@ -28,9 +28,10 @@ from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExport
 from opentelemetry.sdk._logs import LoggerProvider
 from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
 from opentelemetry.sdk.resources import Resource
-from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace import SpanProcessor, TracerProvider
 from opentelemetry.sdk.trace.export import BatchSpanProcessor
 from opentelemetry.trace import StatusCode
+from opentelemetry.util.types import AttributeValue
 
 logger = logging.getLogger("struct_sdk")
 # A library must not configure logging on the host's behalf. Attach a NullHandler
@@ -68,6 +69,72 @@ _current_agent_span: contextvars.ContextVar[Optional[trace.Span]] = contextvars.
 # invoke_agent span and instead parents its children to this span.
 _manual_agent_active: contextvars.ContextVar[Optional[trace.Span]] = contextvars.ContextVar("_manual_agent_active", default=None)
 
+AgentMetadataValue = Union[
+    str, bool, int, float,
+    list[str], list[bool], list[int], list[float],
+    tuple[str, ...], tuple[bool, ...], tuple[int, ...], tuple[float, ...],
+    None,
+]
+"""What ``struct.agent(metadata=...)`` accepts per key (SDK-PY-25): a scalar, a list or
+tuple of one scalar type, or None (inherits the enclosing value)."""
+
+# The enclosing struct.agent() scopes' metadata, merged (inner wins). The
+# _MetadataSpanProcessor stamps it on every span started on Struct's provider
+# inside the scope ([SDK-PY-25]). Never Baggage: it is propagated in-process
+# only and exported as span attributes, never sent on outgoing request headers.
+_current_metadata: contextvars.ContextVar[Optional["_MetadataFrame"]] = contextvars.ContextVar("_current_metadata", default=None)
+
+
+class _MetadataFrame:
+    """One struct.agent() scope's OWN metadata entries, linked to its nearest open
+    enclosing scope. Teardown marks it closed, so a scope ended on another task
+    (where the contextvar reset can't run) stops applying in every context that
+    still points at it, including through open scopes nested inside it: lookups
+    merge only the open frames, outer to inner."""
+
+    __slots__ = ("metadata", "parent", "closed")
+
+    def __init__(self, metadata: Mapping[str, AttributeValue], parent: Optional["_MetadataFrame"]) -> None:
+        self.metadata = metadata
+        self.parent = parent
+        self.closed = False
+
+
+def _open_frame(frame: Optional[_MetadataFrame]) -> Optional[_MetadataFrame]:
+    while frame is not None and frame.closed:
+        frame = frame.parent
+    return frame
+
+
+def _compacted(frame: Optional[_MetadataFrame]) -> Optional[_MetadataFrame]:
+    """The nearest open frame, with every open ancestor relinked past closed ones
+    (overlapping task handoffs close scopes out of order). Run on scope entry and
+    on lookup, so the chain stays bounded even when no span processor runs (an
+    unsampled trace)."""
+    head = _open_frame(frame)
+    node = head
+    while node is not None:
+        node.parent = _open_frame(node.parent)
+        node = node.parent
+    return head
+
+
+def _active_metadata() -> Mapping[str, AttributeValue]:
+    chain: list[Mapping[str, AttributeValue]] = []
+    current = _current_metadata.get(None)
+    frame = _compacted(current)
+    if frame is not current:
+        # Keep the compacted head, so closed scopes are released rather than
+        # rescanned by every later span (open scopes keep their head identity).
+        _current_metadata.set(frame)
+    while frame is not None:
+        chain.append(frame.metadata)
+        frame = frame.parent
+    merged: dict[str, AttributeValue] = {}
+    for metadata in reversed(chain):  # outer first: inner entries win
+        merged.update(metadata)
+    return merged
+
 # Pending tool_use ids keyed by tool name (FIFO per name).
 # Populated by the Anthropic monkey-patch when a chat response arrives with
 # tool_use blocks, consumed by @struct.tool() / struct.tool(...) when the
@@ -227,6 +294,21 @@ def _safe(fn: Callable[[], None], *, site: str) -> None:
             logger.debug("Struct SDK suppressed exception at %s", site, exc_info=True)
 
 
+def _contain_logged(fn: Callable[[], None], *, site: str) -> None:
+    """``_safe`` for hooks that run inside the host's own calls (a span
+    processor's ``on_start``): contains BaseException and a failing log handler
+    too, with the same first-failure-per-site traceback policy (SDK-PY-19)."""
+    try:
+        fn()
+    except BaseException:  # noqa: BLE001 — the host's call must always proceed
+        try:
+            first = site not in _first_failure_logged
+            _first_failure_logged.add(site)
+            logger.debug("Struct SDK suppressed exception at %s", site, exc_info=True if first else None)
+        except BaseException:  # noqa: BLE001
+            pass
+
+
 class StructSDK:
     """Global SDK instance. Call init() once at startup."""
 
@@ -331,6 +413,7 @@ class StructSDK:
                     }
                 )
                 self._tracer_provider = TracerProvider(resource=resource)
+                self._tracer_provider.add_span_processor(_MetadataSpanProcessor())
                 self._tracer_provider.add_span_processor(span_processor)
 
                 # --- LoggerProvider (for gen_ai message events) ---
@@ -434,7 +517,7 @@ class StructSDK:
         session_id: Optional[str] = None,
         agent_id: Optional[str] = None,
         version: Optional[str] = None,
-        metadata: Optional[dict[str, str]] = None,
+        metadata: Optional[Mapping[str, AgentMetadataValue]] = None,
     ) -> Any:
         """Mark a function or block as an agent session.
 
@@ -565,10 +648,85 @@ class _NoOpContext:
 # Agent context — invoke_agent span (GenAI spec)
 # ---------------------------------------------------------------------------
 
+_ATTRIBUTE_SCALARS = (str, bool, int, float)
+# Inherited metadata keys stamped per span, and the attribute slots left free for
+# the span's own later fields (a model call's response and usage).
+MAX_METADATA_KEYS = 32
+METADATA_HEADROOM = 32
+_INT64_MIN, _INT64_MAX = -(2**63), 2**63 - 1
+
+
+def _encodable(item: Any) -> bool:
+    """What OTLP's protobuf can encode: integers within signed 64 bits, and
+    strings that are valid UTF-8 (a lone surrogate, as ``json.loads`` can
+    produce, fails at export with an ERROR per span)."""
+    if isinstance(item, str):
+        try:
+            item.encode("utf-8")
+        except UnicodeEncodeError:
+            return False
+        return True
+    return not isinstance(item, int) or isinstance(item, bool) or _INT64_MIN <= item <= _INT64_MAX
+
+
+def _is_attribute_value(value: Any) -> TypeGuard[AttributeValue]:
+    """The metadata values propagated to child spans: str, bool, int or float, or a
+    list/tuple (empty, or all of one of those types). A subset of what OTel itself
+    accepts (it also takes other sequences and None items); anything else is
+    skipped silently and inherits the enclosing value."""
+    if isinstance(value, _ATTRIBUTE_SCALARS):
+        return _encodable(value)
+    if isinstance(value, (list, tuple)):
+        if not value:
+            return True
+        kind = type(value[0])
+        return kind in _ATTRIBUTE_SCALARS and all(type(item) is kind and _encodable(item) for item in value)
+    return False
+
+
+class _MetadataSpanProcessor(SpanProcessor):
+    """Stamps the enclosing agents' ``struct.metadata.*`` on each span as it
+    starts, so chat, tool and the host's own spans carry them without a join
+    back to ``invoke_agent``. An attribute the span already has at start wins.
+    Runs inside ``start_span``, where the OTel SDK does not guard processors,
+    so nothing may escape."""
+
+    def on_start(self, span: Any, parent_context: Optional[_OtelContext] = None) -> None:
+        def stamp() -> None:
+            metadata = _active_metadata()  # validated once, at scope entry
+            if not metadata:
+                return
+            # A snapshot: the span's attributes are a live view.
+            existing = set(span.attributes or ())
+            # OTel evicts the OLDEST attribute past the span's limit, so inherited
+            # keys only fill room left after the headroom (SDK-PY-25).
+            limit = getattr(getattr(span, "_limits", None), "max_span_attributes", None)
+            budget = MAX_METADATA_KEYS if limit is None else min(
+                MAX_METADATA_KEYS, limit - len(existing) - METADATA_HEADROOM)
+            for key, value in metadata.items():
+                if budget <= 0:
+                    break
+                attribute = f"struct.metadata.{key}"
+                if attribute not in existing:
+                    span.set_attribute(attribute, value)
+                    budget -= 1
+
+        _contain_logged(stamp, site="metadata.on_start")
+
+    def on_end(self, span: Any) -> None:
+        pass
+
+    def shutdown(self) -> None:
+        pass
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True
+
+
 class _AgentContext:
     """Creates an ``invoke_agent {name}`` span per the OTel GenAI spec."""
 
-    def __init__(self, sdk: StructSDK, *, name: Optional[str] = None, session_id: Optional[str] = None, agent_id: Optional[str] = None, version: Optional[str] = None, metadata: Optional[dict[str, str]] = None):
+    def __init__(self, sdk: StructSDK, *, name: Optional[str] = None, session_id: Optional[str] = None, agent_id: Optional[str] = None, version: Optional[str] = None, metadata: Optional[Mapping[str, AgentMetadataValue]] = None):
         self._sdk = sdk
         self._name = name
         # _explicit_session_id is the CALLER-SUPPLIED value (may be None).
@@ -589,6 +747,8 @@ class _AgentContext:
         self._agent_span_token: Optional[contextvars.Token[Optional[trace.Span]]] = None
         self._pending_tool_token: Optional[contextvars.Token[Optional[dict[str, list[str]]]]] = None
         self._manual_token: Optional[contextvars.Token[Optional[trace.Span]]] = None
+        self._metadata_token: Optional[contextvars.Token[Optional[_MetadataFrame]]] = None
+        self._metadata_frame: Optional[_MetadataFrame] = None
 
     def __call__(self, fn: Any) -> Any:
         """Use as decorator."""
@@ -736,10 +896,17 @@ class _AgentContext:
                 # enclosing span (break_out was False). Records the cross-session
                 # parent. Same-session inline subagents fall through with nothing.
                 self._span.set_attribute("struct.agent.parent_session_id", enclosing_session_id)
-            # Custom metadata
-            if self._metadata:
-                for key, value in self._metadata.items():
-                    self._span.set_attribute(f"struct.metadata.{key}", value)
+            # Custom metadata, snapshotted once (lists become tuples: a caller's
+            # list may change after the scope starts) and validated once, for
+            # this span and its children alike. Values OTel can't store (None
+            # included) are dropped, so they inherit the enclosing value.
+            own: dict[str, AttributeValue] = {}
+            for key, supplied in (self._metadata or {}).items():
+                snapshot = tuple(supplied) if isinstance(supplied, list) else supplied
+                if isinstance(key, str) and _encodable(key) and _is_attribute_value(snapshot):
+                    own[key] = snapshot
+            for key, value in own.items():
+                self._span.set_attribute(f"struct.metadata.{key}", value)
 
             # Make this the current OTel span so children (incl. customer raw
             # spans) nest under it. Detach is TASK-SAFE on exit (see
@@ -761,6 +928,13 @@ class _AgentContext:
             # the same top-level chain (parent_run_id is None) and parent its
             # children under this span instead.
             self._manual_token = _manual_agent_active.set(self._span)
+            if self._metadata:
+                # Every span started inside this scope gets the merged metadata
+                # (the span above got the enclosing scope's from the processor,
+                # then its own keys on top).
+                # Linked to the nearest OPEN scope: closed frames never pile up.
+                self._metadata_frame = _MetadataFrame(own, _compacted(_current_metadata.get(None)))
+                self._metadata_token = _current_metadata.set(self._metadata_frame)
             started = True
 
         _safe(body, site="agent.start_span")
@@ -769,6 +943,14 @@ class _AgentContext:
             # _end_span see a clean "no telemetry" view: tokens are reset
             # best-effort, the OTel context stack is popped if it was pushed,
             # the span is ended if it was started, and references are dropped.
+            if self._metadata_frame is not None:
+                self._metadata_frame.closed = True
+                self._metadata_frame = None
+            metadata_tok = self._metadata_token
+            if metadata_tok is not None:
+                _safe(lambda: _current_metadata.reset(metadata_tok),
+                      site="agent.start_span.reset_metadata")
+                self._metadata_token = None
             manual_tok = self._manual_token
             if manual_tok is not None:
                 _safe(lambda: _manual_agent_active.reset(manual_tok),
@@ -808,6 +990,17 @@ class _AgentContext:
     def _end_span(self, exc_val: Any = None) -> None:
         # Contextvar resets must always run — they're cheap, can't fault on the
         # span, and leaving them set leaks session context into the caller.
+        frame = self._metadata_frame
+        if frame is not None:
+            frame.closed = True  # stops applying even where the reset can't run
+        metadata_tok = self._metadata_token
+        if metadata_tok is not None:
+            # Only while this scope is still the head: when scopes close out of
+            # order on one task (async generators), resetting would discard a
+            # still-open inner scope; compaction skips this closed frame instead.
+            _safe(lambda: _current_metadata.reset(metadata_tok)
+                  if _current_metadata.get(None) is frame else None,
+                  site="agent.end_span.reset_metadata")
         manual_tok = self._manual_token
         if manual_tok is not None:
             _safe(lambda: _manual_agent_active.reset(manual_tok),