struct-sdk 0.1.0__py3-none-any.whl

struct_sdk/anthropic.py

@@ -0,0 +1,938 @@
+"""Anthropic SDK auto-instrumentation — OTel GenAI Semantic Conventions v1.37+.
+
+Patches anthropic.Messages.create() and messages.stream() at the CLASS level.
+Supports multiple content capture modes:
+- EVENT_ONLY (default): per-message log events linked to the chat span
+- SPAN_ONLY: content as JSON string span attributes (legacy)
+- SPAN_AND_EVENT: both log events and span attributes
+
+Follows the OTel GenAI spec:
+- Span name: "chat {model}"
+- gen_ai.operation.name = "chat"
+- gen_ai.provider.name = "anthropic"
+- Structured message format with parts (text, tool_call, tool_call_response)
+- Per-message log events: gen_ai.user.message, gen_ai.assistant.message, etc.
+- Choice log event: gen_ai.choice
+
+Auto-applied by struct.init() when the anthropic package is installed.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import logging
+import time
+from typing import TYPE_CHECKING, Any, Generator, Optional
+
+from opentelemetry import trace
+from opentelemetry.trace import StatusCode
+
+if TYPE_CHECKING:
+    from struct_sdk.core import StructSDK
+
+logger = logging.getLogger("struct_sdk.anthropic")
+
+# 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
+
+
+def patch(sdk: StructSDK) -> None:
+    """Patch anthropic SDK classes. Raises ImportError if not installed."""
+    import anthropic
+    from anthropic.resources import Messages, AsyncMessages
+
+    if getattr(anthropic, "__struct_patched", False):
+        return
+
+    tracer = sdk.get_tracer("struct-sdk-anthropic")
+    otel_logger = sdk.get_logger("struct-sdk-anthropic") if sdk.emit_events else None
+
+    # Collect all Messages classes to patch: regular, beta, and Bedrock beta.
+    sync_classes = [Messages]
+    async_classes = [AsyncMessages]
+
+    for import_path in [
+        ("anthropic.resources.beta.messages.messages", "Messages", "AsyncMessages"),
+        ("anthropic.lib.bedrock._beta_messages", "Messages", "AsyncMessages"),
+        ("anthropic.lib.vertex._beta_messages", "Messages", "AsyncMessages"),
+    ]:
+        try:
+            mod = __import__(import_path[0], fromlist=[import_path[1], import_path[2]])
+            sync_classes.append(getattr(mod, import_path[1]))
+            async_classes.append(getattr(mod, import_path[2]))
+        except (ImportError, AttributeError):
+            pass
+
+    for sync_cls in sync_classes:
+        if not getattr(sync_cls.create, "__struct_wrapped__", False):
+            sync_cls.create = _wrap_create(sync_cls.create, tracer, sdk, otel_logger, is_async=False)  # type: ignore[method-assign]
+        if hasattr(sync_cls, "stream") and not getattr(sync_cls.stream, "__struct_wrapped__", False):
+            sync_cls.stream = _wrap_stream(sync_cls.stream, tracer, sdk, otel_logger, is_async=False)  # type: ignore[method-assign]
+
+    for async_cls in async_classes:
+        if not getattr(async_cls.create, "__struct_wrapped__", False):
+            async_cls.create = _wrap_create(async_cls.create, tracer, sdk, otel_logger, is_async=True)  # type: ignore[method-assign]
+        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]
+
+    anthropic.__struct_patched = True  # type: ignore[attr-defined]
+
+
+def unpatch() -> None:
+    """Remove patches. Restores original methods."""
+    try:
+        import anthropic
+    except ImportError:
+        return
+
+    if not getattr(anthropic, "__struct_patched", False):
+        return
+
+    from anthropic.resources import Messages, AsyncMessages
+    for cls in (Messages, AsyncMessages):
+        for method_name in ("create", "stream"):
+            method = getattr(cls, method_name, None)
+            if method and getattr(method, "__struct_wrapped__", False):
+                setattr(cls, method_name, method.__struct_original__)
+
+    anthropic.__struct_patched = False  # type: ignore[attr-defined]
+
+
+# ---------------------------------------------------------------------------
+# messages.create — sync/async via generator
+# ---------------------------------------------------------------------------
+
+def _create_common(
+    f: Any, args: tuple, kwargs: dict, tracer: trace.Tracer, sdk: StructSDK,
+    otel_logger: Any = None,
+) -> Generator:
+    """Shared pre/post logic for messages.create. Generator pattern.
+
+    Telemetry side-effects (pre-call attribute setup, post-call attribute
+    extraction, error-path attribute writes) are wrapped in ``_safe`` so a
+    failure inside instrumentation can never replace the user's response or
+    mask the user's API exception.
+    """
+    from struct_sdk.core import _safe
+
+    model = kwargs.get("model", "unknown")
+
+    with tracer.start_as_current_span(
+        f"chat {model}", kind=trace.SpanKind.CLIENT
+    ) as span:
+        def set_pre_call_attrs() -> None:
+            # Required attributes
+            span.set_attribute("gen_ai.operation.name", "chat")
+            span.set_attribute("gen_ai.provider.name", "anthropic")
+
+            # Conditionally required
+            span.set_attribute("gen_ai.request.model", model)
+            from struct_sdk.core import _current_session_id
+            session_id = _current_session_id.get(None)
+            if session_id:
+                span.set_attribute("gen_ai.conversation.id", session_id)
+
+            # Recommended request attributes
+            if kwargs.get("max_tokens"):
+                span.set_attribute("gen_ai.request.max_tokens", kwargs["max_tokens"])
+            if kwargs.get("temperature") is not None:
+                span.set_attribute("gen_ai.request.temperature", kwargs["temperature"])
+            if kwargs.get("top_p") is not None:
+                span.set_attribute("gen_ai.request.top_p", kwargs["top_p"])
+            if kwargs.get("top_k") is not None:
+                span.set_attribute("gen_ai.request.top_k", kwargs["top_k"])
+            if kwargs.get("stop_sequences"):
+                span.set_attribute("gen_ai.request.stop_sequences", kwargs["stop_sequences"])
+
+            # Always: message count and user prompt propagation
+            if "messages" in kwargs:
+                span.set_attribute("struct.input.message_count", len(kwargs["messages"]))
+                _propagate_user_prompt_to_parent(kwargs["messages"])
+
+            # Log events: per-message log records linked to this span
+            if sdk.emit_events and otel_logger and "messages" in kwargs:
+                _emit_message_events(otel_logger, kwargs["messages"], kwargs.get("system"), span)
+
+            # Span attributes: content on the span (legacy / SPAN_AND_EVENT)
+            if sdk.emit_span_content:
+                if "messages" in kwargs:
+                    span.set_attribute("gen_ai.input.messages", _to_input_messages(kwargs["messages"]))
+                if kwargs.get("system"):
+                    span.set_attribute("gen_ai.system_instructions", _to_system_instructions(kwargs["system"]))
+                if kwargs.get("tools"):
+                    span.set_attribute("gen_ai.tool.definitions", _safe_json(kwargs["tools"]))
+
+        _safe(set_pre_call_attrs, site="anthropic.create.pre_call_attrs")
+
+        try:
+            result = yield f, args, kwargs
+        except Exception as e:
+            _safe(lambda: span.set_attribute("error.type", type(e).__name__),
+                  site="anthropic.create.error_type")
+            _safe(lambda: span.set_status(StatusCode.ERROR, str(e)),
+                  site="anthropic.create.error_status")
+            _safe(lambda: span.record_exception(e),
+                  site="anthropic.create.record_exception")
+            raise
+        _safe(lambda: _set_response_attrs(span, sdk, model, result, otel_logger),
+              site="anthropic.create.set_response_attrs")
+        _safe(lambda: span.set_status(StatusCode.OK),
+              site="anthropic.create.set_ok_status")
+        return result  # noqa: B901
+
+
+def _wrap_create(original: Any, tracer: trace.Tracer, sdk: StructSDK, otel_logger: Any, is_async: bool) -> Any:
+    if is_async:
+        @functools.wraps(original)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            from struct_sdk.core import _safe
+
+            gen: Optional[Generator] = None
+            yielded: Any = None
+
+            def _enter() -> None:
+                nonlocal gen, yielded
+                gen = _create_common(original, args, kwargs, tracer, sdk, otel_logger)
+                yielded = next(gen)
+
+            _safe(_enter, site="anthropic.create.start_span_async")
+            if gen is None or yielded is None:
+                # Telemetry setup raised before the user's call. Bypass
+                # instrumentation entirely so the user's call always runs.
+                return await original(*args, **kwargs)
+
+            f, call_args, call_kwargs = yielded
+            try:
+                result = await f(*call_args, **call_kwargs)
+                return gen.send(result)
+            except StopIteration as e:
+                return e.value
+            except Exception:
+                try:
+                    gen.throw(*__import__("sys").exc_info())
+                except StopIteration as e:
+                    return e.value
+                raise
+    else:
+        @functools.wraps(original)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            from struct_sdk.core import _safe
+
+            gen: Optional[Generator] = None
+            yielded: Any = None
+
+            def _enter() -> None:
+                nonlocal gen, yielded
+                gen = _create_common(original, args, kwargs, tracer, sdk, otel_logger)
+                yielded = next(gen)
+
+            _safe(_enter, site="anthropic.create.start_span")
+            if gen is None or yielded is None:
+                # Telemetry setup raised before the user's call. Bypass
+                # instrumentation entirely so the user's call always runs.
+                return original(*args, **kwargs)
+
+            f, call_args, call_kwargs = yielded
+            try:
+                result = f(*call_args, **call_kwargs)
+                return gen.send(result)
+            except StopIteration as e:
+                return e.value
+            except Exception:
+                try:
+                    gen.throw(*__import__("sys").exc_info())
+                except StopIteration as e:
+                    return e.value
+                raise
+
+    wrapper.__struct_wrapped__ = True  # type: ignore[attr-defined]
+    wrapper.__struct_original__ = original  # type: ignore[attr-defined]
+    return wrapper
+
+
+# ---------------------------------------------------------------------------
+# messages.stream — context manager wrapping
+# ---------------------------------------------------------------------------
+
+def _wrap_stream(original: Any, tracer: trace.Tracer, sdk: StructSDK, otel_logger: Any, is_async: bool) -> Any:
+    """Wrap messages.stream() to trace the streaming context manager.
+
+    KNOWN GAP: this wrapper creates the chat span and stashes it on the
+    stream_manager for use by downstream code, but does NOT currently hook
+    the stream's finalization to call _set_response_attrs on the
+    accumulated final message.  As a result, streaming chat calls do not
+    populate the _pending_tool_calls contextvar, and ``@struct.tool()``
+    callers downstream of a ``messages.stream(...)`` call must pass
+    ``tool_call_id=`` explicitly until this is fixed.  Non-streaming
+    ``messages.create()`` is fully covered.
+    """
+    if is_async:
+        @functools.wraps(original)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            from struct_sdk.core import _safe, _current_session_id
+            model = kwargs.get("model", "unknown")
+
+            span: Optional[trace.Span] = None
+
+            def start() -> None:
+                nonlocal span
+                span = tracer.start_span(f"chat {model}", kind=trace.SpanKind.CLIENT)
+
+            _safe(start, site="anthropic.stream.start_span_async")
+
+            if span is not None:
+                def set_pre_call_attrs() -> None:
+                    assert span is not None
+                    span.set_attribute("gen_ai.operation.name", "chat")
+                    span.set_attribute("gen_ai.provider.name", "anthropic")
+                    span.set_attribute("gen_ai.request.model", model)
+                    session_id = _current_session_id.get(None)
+                    if session_id:
+                        span.set_attribute("gen_ai.conversation.id", session_id)
+                    if "messages" in kwargs:
+                        span.set_attribute("struct.input.message_count", len(kwargs["messages"]))
+                        _propagate_user_prompt_to_parent(kwargs["messages"])
+                    if sdk.emit_events and otel_logger and "messages" in kwargs:
+                        _emit_message_events(otel_logger, kwargs["messages"], kwargs.get("system"), span)
+                    if sdk.emit_span_content and "messages" in kwargs:
+                        span.set_attribute("gen_ai.input.messages", _to_input_messages(kwargs["messages"]))
+
+                _safe(set_pre_call_attrs, site="anthropic.stream.pre_call_attrs")
+
+            stream_manager = await original(*args, **kwargs) if _is_coroutine(original) else original(*args, **kwargs)
+
+            if span is not None:
+                def stash_attrs() -> None:
+                    stream_manager._struct_span = span  # type: ignore[attr-defined]
+                    stream_manager._struct_sdk = sdk  # type: ignore[attr-defined]
+                    stream_manager._struct_model = model  # type: ignore[attr-defined]
+                    stream_manager._struct_logger = otel_logger  # type: ignore[attr-defined]
+
+                _safe(stash_attrs, site="anthropic.stream.stash_attrs")
+
+            return stream_manager
+    else:
+        @functools.wraps(original)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            from struct_sdk.core import _safe, _current_session_id
+            model = kwargs.get("model", "unknown")
+
+            span: Optional[trace.Span] = None
+
+            def start() -> None:
+                nonlocal span
+                span = tracer.start_span(f"chat {model}", kind=trace.SpanKind.CLIENT)
+
+            _safe(start, site="anthropic.stream.start_span")
+
+            if span is not None:
+                def set_pre_call_attrs() -> None:
+                    assert span is not None
+                    span.set_attribute("gen_ai.operation.name", "chat")
+                    span.set_attribute("gen_ai.provider.name", "anthropic")
+                    span.set_attribute("gen_ai.request.model", model)
+                    session_id = _current_session_id.get(None)
+                    if session_id:
+                        span.set_attribute("gen_ai.conversation.id", session_id)
+                    if "messages" in kwargs:
+                        span.set_attribute("struct.input.message_count", len(kwargs["messages"]))
+                        _propagate_user_prompt_to_parent(kwargs["messages"])
+                    if sdk.emit_events and otel_logger and "messages" in kwargs:
+                        _emit_message_events(otel_logger, kwargs["messages"], kwargs.get("system"), span)
+                    if sdk.emit_span_content and "messages" in kwargs:
+                        span.set_attribute("gen_ai.input.messages", _to_input_messages(kwargs["messages"]))
+
+                _safe(set_pre_call_attrs, site="anthropic.stream.pre_call_attrs")
+
+            stream_manager = original(*args, **kwargs)
+
+            if span is not None:
+                def stash_attrs() -> None:
+                    stream_manager._struct_span = span  # type: ignore[attr-defined]
+                    stream_manager._struct_sdk = sdk  # type: ignore[attr-defined]
+                    stream_manager._struct_model = model  # type: ignore[attr-defined]
+                    stream_manager._struct_logger = otel_logger  # type: ignore[attr-defined]
+
+                _safe(stash_attrs, site="anthropic.stream.stash_attrs")
+
+            return stream_manager
+
+    wrapper.__struct_wrapped__ = True  # type: ignore[attr-defined]
+    wrapper.__struct_original__ = original  # type: ignore[attr-defined]
+    return wrapper
+
+
+# ---------------------------------------------------------------------------
+# Response attribute extraction
+# ---------------------------------------------------------------------------
+
+def _iter_tool_uses(content_blocks: Any) -> list[tuple[str, str]]:
+    """Walk response content blocks and yield (tool_name, tool_use_id) pairs.
+
+    Pure helper — no side effects. Used to (a) emit events and output messages,
+    and (b) populate the SDK-internal pending-tool-calls contextvar so that
+    ``@struct.tool()`` spans get auto-linked to the originating tool_use.
+    """
+    result: list[tuple[str, str]] = []
+    if not content_blocks:
+        return result
+    for block in content_blocks:
+        block_type = None
+        if hasattr(block, "type"):
+            block_type = getattr(block, "type", None)
+        elif isinstance(block, dict):
+            block_type = block.get("type")
+        if block_type != "tool_use":
+            continue
+        if hasattr(block, "name"):
+            name = getattr(block, "name", "") or ""
+            tool_id = getattr(block, "id", "") or ""
+        else:
+            name = (block.get("name") or "") if isinstance(block, dict) else ""
+            tool_id = (block.get("id") or "") if isinstance(block, dict) else ""
+        if name and tool_id:
+            result.append((name, tool_id))
+    return result
+
+
+def _record_pending_tool_calls(content_blocks: Any) -> None:
+    """Push every tool_use (name, id) from the response into the SDK contextvar.
+
+    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:
+        return
+    pending = _pending_tool_calls.get()
+    if pending is None:
+        # No active agent scope — initialise a transient dict in the current
+        # context so a @struct.tool() call outside of @struct.agent() still
+        # gets the linkage.  (Will not be reset automatically; that's fine.)
+        pending = {}
+        _pending_tool_calls.set(pending)
+    for name, tool_id in pairs:
+        pending.setdefault(name, []).append(tool_id)
+
+
+def _set_response_attrs(span: trace.Span, sdk: StructSDK, model: str, response: Any, otel_logger: Any = None) -> None:
+    if not hasattr(response, "usage"):
+        return
+
+    usage = response.usage
+    input_tokens = getattr(usage, "input_tokens", 0) or 0
+    output_tokens = getattr(usage, "output_tokens", 0) or 0
+    cache_read = getattr(usage, "cache_read_input_tokens", 0) or 0
+    cache_creation = getattr(usage, "cache_creation_input_tokens", 0) or 0
+
+    # Anthropic's input_tokens excludes cached tokens — add them back for true total
+    total_input = input_tokens + cache_read + cache_creation
+
+    span.set_attribute("gen_ai.usage.input_tokens", total_input)
+    span.set_attribute("gen_ai.usage.output_tokens", output_tokens)
+    if cache_read:
+        span.set_attribute("gen_ai.usage.cache_read.input_tokens", cache_read)
+    if cache_creation:
+        span.set_attribute("gen_ai.usage.cache_creation.input_tokens", cache_creation)
+
+    if hasattr(response, "model"):
+        span.set_attribute("gen_ai.response.model", response.model)
+    if hasattr(response, "stop_reason") and response.stop_reason:
+        span.set_attribute("gen_ai.response.finish_reasons", [response.stop_reason])
+    if hasattr(response, "id"):
+        span.set_attribute("gen_ai.response.id", response.id)
+
+    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)
+
+        finish_reason = getattr(response, "stop_reason", None)
+
+        # Log event: gen_ai.choice
+        if sdk.emit_events and otel_logger:
+            _emit_choice_event(otel_logger, response.content, finish_reason, span)
+
+        # Span attribute (legacy / SPAN_AND_EVENT)
+        if sdk.emit_span_content:
+            span.set_attribute("gen_ai.output.messages", _to_output_messages(response.content, finish_reason))
+
+
+# ---------------------------------------------------------------------------
+# Log event emission — per-message LogRecords (OTel GenAI spec)
+# ---------------------------------------------------------------------------
+
+_EVENT_NAME_MAP = {
+    "user": "gen_ai.user.message",
+    "assistant": "gen_ai.assistant.message",
+    "system": "gen_ai.system.message",
+}
+
+
+def _emit_message_events(
+    otel_logger: Any,
+    messages: list,
+    system: Any = None,
+    span: Optional[trace.Span] = None,
+) -> None:
+    """Emit one LogRecord per message, linked to the current span via context.
+
+    Follows the OTel logs data model convention:
+    - ``body`` (log record body): the event tag string (``gen_ai.user.message``
+      etc.) — human-readable signal.
+    - ``attributes['body']`` (log record attribute): the JSON-serialised
+      structured payload ``{"role": ..., "parts": [...]}``.
+    - Other attributes: ``event.name``, ``gen_ai.system``,
+      ``gen_ai.message.index``, ``gen_ai.conversation.id``.
+
+    ``span`` — if provided, its span context is used for the LogRecord's
+    TraceId/SpanId fields. Fall back to ``trace.get_current_span()`` only for
+    backward compatibility. Always prefer passing the span explicitly — the
+    generator-based ``messages.create`` wrapper spans multiple async awaits
+    and contextvars can drop the active span on some Python + asyncio
+    interactions.
+    """
+    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)
+
+        msg_index = 0
+
+        # System prompt first (if present)
+        if system:
+            if isinstance(system, str):
+                parts = [{"type": "text", "content": system}]
+            elif isinstance(system, list):
+                parts = _content_to_parts(system)
+            else:
+                parts = [{"type": "text", "content": str(system)}]
+
+            payload = json.dumps({"role": "system", "parts": _truncate_parts(parts)}, default=str)
+            event_name = "gen_ai.system.message"
+            attrs: dict[str, Any] = {
+                "event.name": event_name,
+                "body": payload,
+                "gen_ai.system": "anthropic",
+                "gen_ai.message.index": msg_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,
+            ))
+            msg_index += 1
+
+        # Input messages
+        for msg in messages:
+            if isinstance(msg, dict):
+                role = msg.get("role", "user")
+                content = msg.get("content")
+            else:
+                role = getattr(msg, "role", "user")
+                content = getattr(msg, "content", None)
+
+            parts = _content_to_parts(content)
+            event_name = _EVENT_NAME_MAP.get(role, f"gen_ai.{role}.message")
+            payload = json.dumps({"role": role, "parts": _truncate_parts(parts)}, default=str)
+
+            attrs = {
+                "event.name": event_name,
+                "body": payload,
+                "gen_ai.system": "anthropic",
+                "gen_ai.message.index": msg_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,
+            ))
+            msg_index += 1
+
+    except Exception:
+        logger.debug("Failed to emit message events", exc_info=True)
+
+
+def _emit_choice_event(
+    otel_logger: Any,
+    content_blocks: list,
+    finish_reason: str | None,
+    span: Optional[trace.Span] = None,
+) -> None:
+    """Emit a gen_ai.choice LogRecord for the assistant's response.
+
+    ``span`` — same rationale as ``_emit_message_events``: prefer the
+    explicit span over the ambient ``trace.get_current_span()`` lookup.
+    """
+    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)
+
+        parts = []
+        for block in content_blocks:
+            block_type = getattr(block, "type", None)
+            if block_type == "text":
+                parts.append({"type": "text", "content": getattr(block, "text", "")})
+            elif block_type == "tool_use":
+                part: dict[str, Any] = {"type": "tool_call", "name": getattr(block, "name", "")}
+                tool_id = getattr(block, "id", None)
+                if tool_id:
+                    part["id"] = tool_id
+                tool_input = getattr(block, "input", None)
+                if tool_input is not None:
+                    part["arguments"] = tool_input
+                parts.append(part)
+            elif block_type == "thinking":
+                parts.append({"type": "reasoning", "content": getattr(block, "thinking", "")})
+            else:
+                parts.append({"type": block_type or "unknown"})
+
+        # Map Anthropic stop reasons to spec finish reasons
+        reason_map = {
+            "end_turn": "stop",
+            "stop_sequence": "stop",
+            "max_tokens": "length",
+            "tool_use": "tool_call",
+        }
+        mapped_reason = reason_map.get(finish_reason, finish_reason) if finish_reason else None
+
+        choice_body = {
+            "index": 0,
+            "finish_reason": mapped_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.system": "anthropic",
+        }
+        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)
+
+
+# ---------------------------------------------------------------------------
+# Message serialization — Anthropic format → OTel GenAI spec format
+# ---------------------------------------------------------------------------
+
+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."""
+    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
+    progressively more aggressive truncation.
+    """
+    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:
+        # Find the last complete message boundary
+        cut = result[:max_size - 50]  # leave room for closing
+        last_brace = cut.rfind("}")
+        if last_brace > 0:
+            # Try to close at a message boundary
+            result = cut[:last_brace + 1] + "]"
+        else:
+            result = "[]"
+
+    return result
+
+
+def _to_input_messages(messages: list) -> str:
+    """Convert Anthropic messages list to GenAI spec input messages format.
+
+    Spec format: [{"role": "user", "parts": [{"type": "text", "content": "..."}]}, ...]
+    """
+    try:
+        result = []
+        for msg in messages:
+            if isinstance(msg, dict):
+                role = msg.get("role", "user")
+                content = msg.get("content")
+            else:
+                role = getattr(msg, "role", "user")
+                content = getattr(msg, "content", None)
+
+            parts = _content_to_parts(content)
+            result.append({"role": role, "parts": parts})
+
+        return _truncate_and_serialize(result)
+    except Exception:
+        return json.dumps([], default=str)
+
+
+def _to_output_messages(content_blocks: list, finish_reason: str | None) -> str:
+    """Convert Anthropic response content blocks to GenAI spec output messages format.
+
+    Spec format: [{"role": "assistant", "parts": [...], "finish_reason": "stop"}]
+    """
+    try:
+        parts = []
+        for block in content_blocks:
+            block_type = getattr(block, "type", None)
+            if block_type == "text":
+                parts.append({"type": "text", "content": getattr(block, "text", "")})
+            elif block_type == "tool_use":
+                part: dict[str, Any] = {
+                    "type": "tool_call",
+                    "name": getattr(block, "name", ""),
+                }
+                tool_id = getattr(block, "id", None)
+                if tool_id:
+                    part["id"] = tool_id
+                tool_input = getattr(block, "input", None)
+                if tool_input is not None:
+                    part["arguments"] = tool_input
+                parts.append(part)
+            elif block_type == "thinking":
+                parts.append({"type": "reasoning", "content": getattr(block, "thinking", "")})
+            else:
+                parts.append({"type": block_type or "unknown"})
+
+        msg: dict[str, Any] = {"role": "assistant", "parts": parts}
+        if finish_reason:
+            # Map Anthropic stop reasons to spec finish reasons
+            reason_map = {
+                "end_turn": "stop",
+                "stop_sequence": "stop",
+                "max_tokens": "length",
+                "tool_use": "tool_call",
+            }
+            msg["finish_reason"] = reason_map.get(finish_reason, finish_reason)
+
+        return _truncate_and_serialize([msg])
+    except Exception:
+        return json.dumps([], default=str)
+
+
+def _to_system_instructions(system: Any) -> str:
+    """Convert Anthropic system prompt to GenAI spec system_instructions format.
+
+    Spec format: [{"type": "text", "content": "..."}]
+    """
+    try:
+        if isinstance(system, str):
+            return _truncate_and_serialize([{"type": "text", "content": system}])
+        elif isinstance(system, list):
+            parts = _content_to_parts(system)
+            return _truncate_and_serialize(parts)
+        return json.dumps([], default=str)
+    except Exception:
+        return json.dumps([], default=str)
+
+
+def _content_to_parts(content: Any) -> list[dict[str, Any]]:
+    """Convert Anthropic content (string, list of blocks, or tool_result) to spec parts."""
+    if content is None:
+        return []
+    if isinstance(content, str):
+        return [{"type": "text", "content": content}]
+    if isinstance(content, list):
+        parts = []
+        for item in content:
+            if isinstance(item, dict):
+                item_type = item.get("type")
+                if item_type == "text":
+                    parts.append({"type": "text", "content": item.get("text", "")})
+                elif item_type == "tool_use":
+                    part: dict[str, Any] = {"type": "tool_call", "name": item.get("name", "")}
+                    if item.get("id"):
+                        part["id"] = item["id"]
+                    if item.get("input") is not None:
+                        part["arguments"] = item["input"]
+                    parts.append(part)
+                elif item_type == "tool_result":
+                    part2: dict[str, Any] = {"type": "tool_call_response"}
+                    if item.get("tool_use_id"):
+                        part2["id"] = item["tool_use_id"]
+                    part2["response"] = item.get("content", "")
+                    parts.append(part2)
+                elif item_type == "image":
+                    source = item.get("source", {})
+                    if source.get("type") == "base64":
+                        parts.append({
+                            "type": "blob",
+                            "modality": "image",
+                            "content": source.get("data", "")[:256] + "...",
+                            "mime_type": source.get("media_type"),
+                        })
+                    elif source.get("type") == "url":
+                        parts.append({
+                            "type": "uri",
+                            "modality": "image",
+                            "uri": source.get("url", ""),
+                        })
+                else:
+                    parts.append({"type": item_type or "unknown"})
+            elif hasattr(item, "type"):
+                # Anthropic SDK objects
+                item_type = item.type
+                if item_type == "text":
+                    parts.append({"type": "text", "content": getattr(item, "text", "")})
+                elif item_type == "tool_use":
+                    part3: dict[str, Any] = {"type": "tool_call", "name": getattr(item, "name", "")}
+                    if getattr(item, "id", None):
+                        part3["id"] = item.id
+                    if getattr(item, "input", None) is not None:
+                        part3["arguments"] = item.input
+                    parts.append(part3)
+                elif item_type == "tool_result":
+                    part4: dict[str, Any] = {"type": "tool_call_response"}
+                    if getattr(item, "tool_use_id", None):
+                        part4["id"] = item.tool_use_id
+                    part4["response"] = getattr(item, "content", "")
+                    parts.append(part4)
+                else:
+                    parts.append({"type": item_type})
+            elif isinstance(item, str):
+                parts.append({"type": "text", "content": item})
+        return parts
+    return [{"type": "text", "content": str(content)}]
+
+
+def _propagate_user_prompt_to_parent(messages: list) -> None:
+    """Set the last user message on the parent invoke_agent span if present.
+
+    This allows the waterfall UI to show what the user asked without
+    needing to drill into the child chat span.  Only sets the attribute
+    once — the first chat call within an invoke_agent scope wins.
+    """
+    try:
+        # Walk up — the current span is the chat span we just created;
+        # its parent context holds the invoke_agent span.  However OTel
+        # Python flattens context, so get_current_span() returns the
+        # innermost (our chat span).  We need the parent, which is the
+        # span that was current *before* start_as_current_span.
+        # Since we're inside start_as_current_span, the parent is not
+        # directly accessible.  Instead, we stash the attribute on any
+        # ancestor invoke_agent span via the context var approach.
+        from struct_sdk.core import _current_agent_span
+        agent_span = _current_agent_span.get(None)
+        if agent_span is None:
+            return
+        # Only set once — don't overwrite if already captured
+        # (ReadableSpan check — attributes is a dict on SDK spans)
+        existing = None
+        if hasattr(agent_span, "attributes"):
+            existing = agent_span.attributes.get("gen_ai.input.messages")  # type: ignore[union-attr]
+        if existing:
+            return
+
+        # Extract just the last user message for a clean prompt preview
+        last_user_msg = None
+        for msg in reversed(messages):
+            role = msg.get("role") if isinstance(msg, dict) else getattr(msg, "role", None)
+            if role == "user":
+                content = msg.get("content") if isinstance(msg, dict) else getattr(msg, "content", None)
+                parts = _content_to_parts(content)
+                last_user_msg = [{"role": "user", "parts": parts}]
+                break
+
+        if last_user_msg:
+            agent_span.set_attribute(
+                "gen_ai.input.messages",
+                _truncate_and_serialize(last_user_msg),
+            )
+    except Exception:
+        pass  # Never break the application for telemetry
+
+
+def _safe_json(obj: Any) -> str:
+    """Safely serialize to JSON string with field-level truncation."""
+    try:
+        return _truncate_and_serialize(obj)
+    except Exception:
+        return "[]"
+
+
+def _is_coroutine(fn: Any) -> bool:
+    import asyncio
+    return asyncio.iscoroutinefunction(fn)