struct-sdk 0.1.0__py3-none-any.whl

struct_sdk/core.py

@@ -0,0 +1,755 @@
+"""Core SDK — wraps OpenTelemetry with Struct-specific defaults.
+
+Users call struct.init() once at startup. The SDK auto-instruments any
+supported libraries that are installed (anthropic, claude_agent_sdk).
+
+OTel GenAI Semantic Conventions v1.37+ compliant.
+"""
+
+import asyncio
+import atexit
+import contextvars
+import functools
+import json
+import logging
+import threading
+import uuid
+from enum import Enum
+from typing import Any, Callable, Optional
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+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.export import BatchSpanProcessor
+from opentelemetry.trace import StatusCode
+
+logger = logging.getLogger("struct_sdk")
+
+DEFAULT_ENDPOINT = "https://ingest.struct.ai"
+
+
+class ContentCaptureMode(str, Enum):
+    """Controls how LLM message content is captured in telemetry.
+
+    Follows the OTel GenAI spec content capture modes.
+    """
+    NONE = "none"                # No message content captured
+    EVENT_ONLY = "event_only"    # Content in log events only (default)
+    SPAN_ONLY = "span_only"      # Content in span attributes only (legacy)
+    SPAN_AND_EVENT = "span_and_event"  # Both log events and span attributes
+
+# Context vars for propagating session context to child spans
+_current_session_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar("_current_session_id", default=None)
+_current_conversation_id: contextvars.ContextVar[Optional[str]] = contextvars.ContextVar("_current_conversation_id", default=None)
+_current_agent_span: contextvars.ContextVar[Optional[trace.Span]] = contextvars.ContextVar("_current_agent_span", default=None)
+
+# 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
+# decorated function/context manager starts its span.  Lets us auto-link
+# execute_tool spans to the originating tool_use.id without forcing callers
+# to pass tool_call_id= explicitly.  Customers who already pass it keep
+# working unchanged (explicit override wins).
+_pending_tool_calls: contextvars.ContextVar[Optional[dict[str, list[str]]]] = contextvars.ContextVar("_pending_tool_calls", default=None)
+
+# Registry of patched integrations — prevents double-patching
+_patched_integrations: set[str] = set()
+
+# Sites that have already logged a first-failure WARN; subsequent failures log at DEBUG.
+_first_failure_logged: set[str] = set()
+
+
+def _safe(fn: Callable[[], None], *, site: str) -> None:
+    """Run fn(); swallow any exception. First failure per site logs at WARN with stack; subsequent at DEBUG."""
+    try:
+        fn()
+    except Exception:
+        if site in _first_failure_logged:
+            logger.debug("Struct SDK suppressed exception at %s", site, exc_info=True)
+        else:
+            _first_failure_logged.add(site)
+            logger.warning("Struct SDK suppressed exception at %s", site, exc_info=True)
+
+
+class StructSDK:
+    """Global SDK instance. Call init() once at startup."""
+
+    def __init__(self):
+        self._initialized = False
+        self._tracer_provider: Optional[TracerProvider] = None
+        self._logger_provider: Optional[LoggerProvider] = None
+        self._ingest_key: str = ""
+        self._endpoint: str = DEFAULT_ENDPOINT
+        self._content_capture: ContentCaptureMode = ContentCaptureMode.EVENT_ONLY
+        # Atexit/_shutdown reads this even when init() was never called or
+        # failed before reaching the assignment in init() — keep it set here.
+        self._shutdown_timeout_seconds: float = 5.0
+        # Serializes init() so concurrent callers cannot both pass the
+        # early-return check and double-run the init body. A second concurrent
+        # init blocks on this lock instead of racing.
+        self._init_lock: threading.Lock = threading.Lock()
+
+    def init(
+        self,
+        ingest_key: str,
+        *,
+        service_name: str = "default-agent",
+        service_version: str = "0.0.0",
+        environment: str = "development",
+        endpoint: str = DEFAULT_ENDPOINT,
+        shutdown_timeout_seconds: float = 5.0,
+        capture_content: bool = True,
+        content_capture: Optional[ContentCaptureMode] = None,
+    ):
+        """Initialize the Struct SDK and auto-instrument installed libraries.
+
+        After calling this, any installed supported library is automatically
+        instrumented — no additional setup required.
+
+        Auto-detected integrations:
+            - ``anthropic`` — patches messages.create() and messages.stream()
+            - ``claude_agent_sdk`` — patches ClaudeAgentOptions to inject OTel env vars
+
+        Args:
+            ingest_key: Your Struct ingest key (pk-...). Write-only, safe to expose.
+            service_name: Name of your agent/service (e.g., "checkout-agent").
+            service_version: Version string for your agent.
+            environment: Deployment environment (development, staging, production).
+            endpoint: Struct ingestion endpoint. Override for self-hosted or local dev.
+            shutdown_timeout_seconds: Maximum time the SDK's atexit shutdown is
+                allowed to spend flushing telemetry providers. If the ingest
+                endpoint is dead or slow, shutdown returns within this budget
+                rather than hanging the user's process exit. Defaults to 5.0.
+            capture_content: Whether to capture LLM prompts/completions. Disable for privacy.
+                Deprecated — use ``content_capture`` instead.
+            content_capture: Controls how LLM message content is captured.
+                Takes precedence over ``capture_content``. Defaults to EVENT_ONLY.
+        """
+        # Serialize init() so concurrent callers cannot both pass the early-return
+        # check and double-run the body (which would leak the first provider — the
+        # second assignment to self._tracer_provider would orphan the first without
+        # ever shutting it down). The single-threaded healthy path is unaffected:
+        # the lock is uncontended and acquired once.
+        with self._init_lock:
+            if self._initialized:
+                logger.warning("struct.init() called multiple times — ignoring")
+                return
+
+            self._ingest_key = ingest_key
+            self._endpoint = endpoint
+
+            # Resolve content capture mode: explicit content_capture > capture_content bool
+            if content_capture is not None:
+                self._content_capture = content_capture
+            elif not capture_content:
+                self._content_capture = ContentCaptureMode.NONE
+            else:
+                self._content_capture = ContentCaptureMode.EVENT_ONLY
+
+            try:
+                # Stored before atexit registers _shutdown so the hook always sees
+                # the user-configured timeout (or the default).
+                self._shutdown_timeout_seconds = shutdown_timeout_seconds
+
+                headers = {"x-struct-ingest-key": ingest_key}
+
+                # --- TracerProvider ---
+                span_exporter = OTLPSpanExporter(
+                    endpoint=f"{endpoint.rstrip('/')}/v1/traces",
+                    headers=headers,
+                )
+
+                span_processor = BatchSpanProcessor(
+                    span_exporter,
+                    max_queue_size=10000,
+                    max_export_batch_size=100,
+                    schedule_delay_millis=1000,
+                )
+
+                # Isolated TracerProvider — NOT set as the global.
+                resource = Resource.create(
+                    {
+                        "service.name": service_name,
+                        "service.version": service_version,
+                        "deployment.environment": environment,
+                    }
+                )
+                self._tracer_provider = TracerProvider(resource=resource)
+                self._tracer_provider.add_span_processor(span_processor)
+
+                # --- LoggerProvider (for gen_ai message events) ---
+                log_exporter = OTLPLogExporter(
+                    endpoint=f"{endpoint.rstrip('/')}/v1/logs",
+                    headers=headers,
+                )
+
+                log_processor = BatchLogRecordProcessor(
+                    log_exporter,
+                    max_queue_size=10000,
+                    max_export_batch_size=100,
+                    schedule_delay_millis=1000,
+                )
+
+                self._logger_provider = LoggerProvider(resource=resource)
+                self._logger_provider.add_log_record_processor(log_processor)
+
+                self._initialized = True
+
+                self._auto_instrument()
+            except Exception:
+                logger.warning(
+                    "Struct SDK init failed; SDK disabled: service=%s endpoint=%s",
+                    service_name, endpoint, exc_info=True,
+                )
+                self._initialized = False
+                self._tracer_provider = None
+                self._logger_provider = None
+                return
+
+            atexit.register(self._shutdown)
+
+            logger.info(
+                "Struct SDK initialized: service=%s endpoint=%s content_capture=%s",
+                service_name, endpoint, self._content_capture.value,
+            )
+
+    def _auto_instrument(self):
+        """Detect and patch installed libraries."""
+        integrations = [
+            ("anthropic", "struct_sdk.anthropic"),
+            ("claude_agent_sdk", "struct_sdk.claude_agent"),
+            ("langchain_core", "struct_sdk.langchain"),
+        ]
+
+        for lib_name, module_path in integrations:
+            if lib_name in _patched_integrations:
+                continue
+            try:
+                import importlib
+                mod = importlib.import_module(module_path)
+                mod.patch(self)  # type: ignore[attr-defined]
+                _patched_integrations.add(lib_name)
+                logger.info("Auto-instrumented: %s", lib_name)
+            except ImportError:
+                pass
+            except Exception:
+                logger.debug("Failed to instrument %s", lib_name, exc_info=True)
+
+    def get_tracer(self, name: str = "struct-sdk") -> trace.Tracer:
+        """Get an OTel tracer from our isolated provider."""
+        if self._tracer_provider is None:
+            raise RuntimeError("Call struct.init() before using the SDK")
+        return self._tracer_provider.get_tracer(name)
+
+    def get_logger(self, name: str = "struct-sdk") -> Any:
+        """Get an OTel logger from our isolated provider (for gen_ai log events)."""
+        if self._logger_provider is None:
+            raise RuntimeError("Call struct.init() before using the SDK")
+        return self._logger_provider.get_logger(name)
+
+    @property
+    def capture_content(self) -> bool:
+        """Backward-compatible property. True if any content capture is enabled."""
+        return self._content_capture != ContentCaptureMode.NONE
+
+    @property
+    def content_capture(self) -> ContentCaptureMode:
+        """The active content capture mode."""
+        return self._content_capture
+
+    @property
+    def emit_events(self) -> bool:
+        """True if content should be emitted as log events."""
+        return self._content_capture in (ContentCaptureMode.EVENT_ONLY, ContentCaptureMode.SPAN_AND_EVENT)
+
+    @property
+    def emit_span_content(self) -> bool:
+        """True if content should be set as span attributes."""
+        return self._content_capture in (ContentCaptureMode.SPAN_ONLY, ContentCaptureMode.SPAN_AND_EVENT)
+
+    # ── Decorators / Context Managers ──
+
+    def agent(
+        self,
+        fn: Any = None,
+        *,
+        name: Optional[str] = None,
+        session_id: Optional[str] = None,
+        agent_id: Optional[str] = None,
+        version: Optional[str] = None,
+        metadata: Optional[dict[str, str]] = None,
+    ) -> Any:
+        """Mark a function or block as an agent session.
+
+        Creates an ``invoke_agent`` span per the OTel GenAI spec that groups
+        all LLM and tool calls within the scope.
+
+        Usage::
+
+            @struct.agent()
+            async def my_agent():
+                response = await client.messages.create(...)
+
+            async with struct.agent(session_id=agent_id, name="checkout"):
+                ...
+        """
+        if not self._initialized:
+            return fn if fn is not None else _NoOpContext()
+
+        ctx = _AgentContext(self, name=name, session_id=session_id, agent_id=agent_id, version=version, metadata=metadata)
+        if fn is None:
+            return ctx
+        if callable(fn):
+            return ctx(fn)
+        raise TypeError("agent() argument must be callable or used as context manager")
+
+    def tool(
+        self,
+        fn: Any = None,
+        *,
+        name: Optional[str] = None,
+        tool_call_id: Optional[str] = None,
+    ) -> Any:
+        """Mark a function or block as a tool execution.
+
+        Creates an ``execute_tool`` span per the OTel GenAI spec.
+
+        ``gen_ai.tool.call.id`` is populated automatically when this is invoked
+        after a patched Anthropic call flow — the SDK stashes each ``tool_use.id``
+        from the assistant response and pops the first matching tool name when
+        this span starts. Pass ``tool_call_id=`` explicitly to override.
+
+        Usage::
+
+            @struct.tool()
+            async def search_investigations(query: str, limit: int):
+                return await repo.search(query, limit)
+
+            async with struct.tool(name="search"):
+                result = await do_search()
+        """
+        if not self._initialized:
+            return fn if fn is not None else _NoOpContext()
+
+        ctx = _ToolContext(self, name=name, tool_call_id=tool_call_id)
+        if fn is None:
+            return ctx
+        if callable(fn):
+            return ctx(fn)
+        raise TypeError("tool() argument must be callable or used as context manager")
+
+    def _shutdown(self) -> None:
+        """Best-effort shutdown bounded by ``shutdown_timeout_seconds``.
+
+        Runs ``provider.shutdown()`` in a daemon worker thread and waits up
+        to the configured timeout for it to finish. On timeout, the daemon
+        is abandoned (it dies with the process). On any failure — thread
+        creation, provider faults, attribute errors — we swallow the
+        exception: this runs in atexit context where propagating to the
+        interpreter would mean the user's process exits with a confusing
+        traceback for telemetry the SDK was supposed to hide.
+        """
+        try:
+            worker = threading.Thread(
+                target=self._do_shutdown,
+                name="struct-sdk-shutdown",
+                daemon=True,
+            )
+            worker.start()
+            worker.join(timeout=self._shutdown_timeout_seconds)
+            if worker.is_alive():
+                # Thread keeps running; daemon=True so it dies with the
+                # process. We log at DEBUG: stderr WARNs at atexit time
+                # clutter user output for a fault we already handled.
+                logger.debug(
+                    "Struct SDK shutdown timed out after %.1fs (ingest may be unreachable)",
+                    self._shutdown_timeout_seconds,
+                )
+        except Exception:
+            logger.debug("Struct SDK shutdown failed", exc_info=True)
+
+    def _do_shutdown(self) -> None:
+        """Worker that calls each provider's shutdown(); each call is isolated.
+
+        Order matches the previous behavior (logger first, tracer second) so
+        any consumer that depended on relative ordering keeps working.
+        """
+        if self._logger_provider is not None:
+            try:
+                self._logger_provider.shutdown()
+            except Exception:
+                logger.debug("LoggerProvider shutdown failed", exc_info=True)
+        if self._tracer_provider is not None:
+            try:
+                self._tracer_provider.shutdown()
+            except Exception:
+                logger.debug("TracerProvider shutdown failed", exc_info=True)
+
+
+# ---------------------------------------------------------------------------
+# No-op context (when SDK not initialized)
+# ---------------------------------------------------------------------------
+
+class _NoOpContext:
+    """No-op context manager / decorator when SDK is not initialized."""
+    def __call__(self, fn: Any) -> Any:
+        return fn
+    def __enter__(self) -> "_NoOpContext":
+        return self
+    def __exit__(self, *args: Any) -> None:
+        pass
+    async def __aenter__(self) -> "_NoOpContext":
+        return self
+    async def __aexit__(self, *args: Any) -> None:
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Agent context — invoke_agent span (GenAI spec)
+# ---------------------------------------------------------------------------
+
+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):
+        self._sdk = sdk
+        self._name = name
+        self._session_id = session_id or str(uuid.uuid4())
+        self._agent_id = agent_id
+        self._version = version
+        self._metadata = metadata
+        self._span: Optional[trace.Span] = None
+        self._ctx_manager: Optional[Any] = None
+        self._session_token: Optional[contextvars.Token[Optional[str]]] = None
+        self._conversation_token: Optional[contextvars.Token[Optional[str]]] = None
+        self._agent_span_token: Optional[contextvars.Token[Optional[trace.Span]]] = None
+        self._pending_tool_token: Optional[contextvars.Token[Optional[dict[str, list[str]]]]] = None
+
+    def __call__(self, fn: Any) -> Any:
+        """Use as decorator."""
+        span_name = self._name or fn.__name__
+        sdk = self._sdk
+        session_id = self._session_id
+        agent_id = self._agent_id
+        version = self._version
+        metadata = self._metadata
+
+        if asyncio.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def wrapper(*args: Any, **kwargs: Any) -> Any:
+                async with _AgentContext(sdk, name=span_name, session_id=session_id, agent_id=agent_id, version=version, metadata=metadata):
+                    return await fn(*args, **kwargs)
+            return wrapper
+        else:
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                with _AgentContext(sdk, name=span_name, session_id=session_id, agent_id=agent_id, version=version, metadata=metadata):
+                    return fn(*args, **kwargs)
+            return wrapper
+
+    def _start_span(self) -> None:
+        started = False
+        entered = False
+
+        def body() -> None:
+            nonlocal started, entered
+            agent_name = self._name or "agent"
+            tracer = self._sdk.get_tracer("struct-sdk")
+
+            # Capture the outer session id BEFORE overwriting the contextvar so we
+            # can link nested agents (subagents) back to the agent that spawned them.
+            # Subagent pattern: an outer @struct.agent() wraps a function; that function
+            # calls a tool that itself enters another @struct.agent() scope. The inner
+            # scope's struct.agent.parent_session_id points to the outer session_id.
+            parent_session_id = _current_session_id.get(None)
+
+            self._span = tracer.start_span(
+                f"invoke_agent {agent_name}",
+                kind=trace.SpanKind.INTERNAL,
+            )
+            # Required
+            self._span.set_attribute("gen_ai.operation.name", "invoke_agent")
+            self._span.set_attribute("gen_ai.provider.name", "struct")
+            # Conditionally required
+            self._span.set_attribute("gen_ai.agent.name", agent_name)
+            # gen_ai.agent.id is the stable agent-definition identifier per the
+            # OTel GenAI spec — not a per-invocation value. Only set it when the
+            # caller supplies one.
+            if self._agent_id:
+                self._span.set_attribute("gen_ai.agent.id", self._agent_id)
+            if self._version:
+                self._span.set_attribute("gen_ai.agent.version", self._version)
+            # gen_ai.conversation.id is the spec-blessed name; we drop the
+            # redundant session.id.
+            self._span.set_attribute("gen_ai.conversation.id", self._session_id)
+            # Link to the outer agent's session, if we're nested under one.
+            if parent_session_id and parent_session_id != self._session_id:
+                self._span.set_attribute("struct.agent.parent_session_id", parent_session_id)
+            # Custom metadata
+            if self._metadata:
+                for key, value in self._metadata.items():
+                    self._span.set_attribute(f"struct.metadata.{key}", value)
+
+            self._ctx_manager = trace.use_span(self._span, end_on_exit=False)
+            self._ctx_manager.__enter__()
+            # Tracks whether the OTel context stack was actually pushed; only
+            # then is it correct to call __exit__ on rollback. If body raised
+            # between assigning self._ctx_manager and __enter__ returning,
+            # nothing was pushed and __exit__ would corrupt the stack.
+            entered = True
+            # Set context vars so child spans inherit session context
+            self._session_token = _current_session_id.set(self._session_id)
+            self._conversation_token = _current_conversation_id.set(self._session_id)
+            self._agent_span_token = _current_agent_span.set(self._span)
+            # Fresh pending-tool-calls dict scoped to this agent run, so tool_use
+            # ids from an outer agent cannot leak in or out.
+            self._pending_tool_token = _pending_tool_calls.set({})
+            started = True
+
+        _safe(body, site="agent.start_span")
+        if not started:
+            # body() raised partway. Roll back any partial state so __exit__ /
+            # _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.
+            pending_tok = self._pending_tool_token
+            if pending_tok is not None:
+                _safe(lambda: _pending_tool_calls.reset(pending_tok),
+                      site="agent.start_span.reset_pending_tool")
+                self._pending_tool_token = None
+            agent_tok = self._agent_span_token
+            if agent_tok is not None:
+                _safe(lambda: _current_agent_span.reset(agent_tok),
+                      site="agent.start_span.reset_agent_span")
+                self._agent_span_token = None
+            conv_tok = self._conversation_token
+            if conv_tok is not None:
+                _safe(lambda: _current_conversation_id.reset(conv_tok),
+                      site="agent.start_span.reset_conversation")
+                self._conversation_token = None
+            session_tok = self._session_token
+            if session_tok is not None:
+                _safe(lambda: _current_session_id.reset(session_tok),
+                      site="agent.start_span.reset_session")
+                self._session_token = None
+            # Pop the OTel context stack first — use_span's __exit__ depends on
+            # the span still being current. Only call it if __enter__ ran.
+            ctx = self._ctx_manager
+            if entered and ctx is not None:
+                _safe(lambda: ctx.__exit__(None, None, None),
+                      site="agent.start_span.rollback_ctx_exit")
+            self._ctx_manager = None
+            # Then end the span so it isn't leaked unended.
+            span = self._span
+            if span is not None:
+                _safe(span.end, site="agent.start_span.rollback_span_end")
+            self._span = None
+
+    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.
+        pending_tok = self._pending_tool_token
+        if pending_tok is not None:
+            _safe(lambda: _pending_tool_calls.reset(pending_tok),
+                  site="agent.end_span.reset_pending_tool")
+        agent_tok = self._agent_span_token
+        if agent_tok is not None:
+            _safe(lambda: _current_agent_span.reset(agent_tok),
+                  site="agent.end_span.reset_agent_span")
+        session_tok = self._session_token
+        if session_tok is not None:
+            _safe(lambda: _current_session_id.reset(session_tok),
+                  site="agent.end_span.reset_session")
+        conv_tok = self._conversation_token
+        if conv_tok is not None:
+            _safe(lambda: _current_conversation_id.reset(conv_tok),
+                  site="agent.end_span.reset_conversation")
+        span = self._span
+        if span is not None:
+            if exc_val:
+                _safe(lambda: span.set_attribute("error.type", type(exc_val).__name__),
+                      site="agent.end_span.error_type")
+                _safe(lambda: span.set_status(StatusCode.ERROR, str(exc_val)),
+                      site="agent.end_span.error_status")
+                _safe(lambda: span.record_exception(exc_val),
+                      site="agent.end_span.record_exception")
+            else:
+                _safe(lambda: span.set_status(StatusCode.OK),
+                      site="agent.end_span.set_ok")
+            _safe(span.end, site="agent.end_span.end")
+        ctx = self._ctx_manager
+        if ctx is not None:
+            _safe(lambda: ctx.__exit__(None, None, None), site="agent.end_span.ctx_exit")
+
+    def __enter__(self) -> "_AgentContext":
+        self._start_span()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self._end_span(exc_val)
+
+    async def __aenter__(self) -> "_AgentContext":
+        self._start_span()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self._end_span(exc_val)
+
+    @property
+    def session_id(self) -> str:
+        return self._session_id
+
+
+# ---------------------------------------------------------------------------
+# Tool context — execute_tool span (GenAI spec)
+# ---------------------------------------------------------------------------
+
+class _ToolContext:
+    """Creates an ``execute_tool {name}`` span per the OTel GenAI spec."""
+
+    def __init__(self, sdk: StructSDK, *, name: Optional[str] = None, tool_call_id: Optional[str] = None):
+        self._sdk = sdk
+        self._name = name
+        self._tool_call_id = tool_call_id
+        self._span: Optional[trace.Span] = None
+        self._ctx_manager: Optional[Any] = None
+        self._result: Any = None
+
+    def __call__(self, fn: Any) -> Any:
+        """Use as decorator. Captures function args and return value."""
+        tool_name = self._name or fn.__name__
+        sdk = self._sdk
+        tool_call_id = self._tool_call_id
+
+        if asyncio.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def wrapper(*args: Any, **kwargs: Any) -> Any:
+                async with _ToolContext(sdk, name=tool_name, tool_call_id=tool_call_id) as ctx:
+                    # Capture arguments (opt-in)
+                    if sdk.capture_content and kwargs:
+                        ctx._set_arguments(kwargs)
+                    result = await fn(*args, **kwargs)
+                    # Capture result (opt-in)
+                    if sdk.capture_content and result is not None:
+                        ctx._set_result(result)
+                    return result
+            return wrapper
+        else:
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                with _ToolContext(sdk, name=tool_name, tool_call_id=tool_call_id) as ctx:
+                    if sdk.capture_content and kwargs:
+                        ctx._set_arguments(kwargs)
+                    result = fn(*args, **kwargs)
+                    if sdk.capture_content and result is not None:
+                        ctx._set_result(result)
+                    return result
+            return wrapper
+
+    def _start_span(self) -> None:
+        started = False
+        entered = False
+
+        def body() -> None:
+            nonlocal started, entered
+            tool_name = self._name or "tool"
+            tracer = self._sdk.get_tracer("struct-sdk")
+            self._span = tracer.start_span(
+                f"execute_tool {tool_name}",
+                kind=trace.SpanKind.INTERNAL,
+            )
+            # Required
+            self._span.set_attribute("gen_ai.operation.name", "execute_tool")
+            self._span.set_attribute("gen_ai.provider.name", "struct")
+            # Recommended
+            self._span.set_attribute("gen_ai.tool.name", tool_name)
+            # Auto-link to the originating tool_use.id from the preceding chat
+            # response if the caller didn't pass one explicitly.  Explicit
+            # tool_call_id= always wins — pop from the pending queue only when
+            # the caller left it unset.
+            if self._tool_call_id is None:
+                pending = _pending_tool_calls.get()
+                if pending:
+                    ids = pending.get(tool_name)
+                    if ids:
+                        self._tool_call_id = ids.pop(0)
+            if self._tool_call_id:
+                self._span.set_attribute("gen_ai.tool.call.id", self._tool_call_id)
+            # Propagate session context
+            session_id = _current_session_id.get(None)
+            if session_id:
+                self._span.set_attribute("gen_ai.conversation.id", session_id)
+
+            self._ctx_manager = trace.use_span(self._span, end_on_exit=False)
+            self._ctx_manager.__enter__()
+            # Tracks whether the OTel context stack was actually pushed; only
+            # then is it correct to call __exit__ on rollback.
+            entered = True
+            started = True
+
+        _safe(body, site="tool.start_span")
+        if not started:
+            # Body raised partway. Pop the OTel context stack if it was pushed,
+            # end the span if it was started, then drop references so
+            # _end_span sees a clean "no telemetry" view.
+            ctx = self._ctx_manager
+            if entered and ctx is not None:
+                _safe(lambda: ctx.__exit__(None, None, None),
+                      site="tool.start_span.rollback_ctx_exit")
+            self._ctx_manager = None
+            span = self._span
+            if span is not None:
+                _safe(span.end, site="tool.start_span.rollback_span_end")
+            self._span = None
+
+    def _end_span(self, exc_val: Any = None) -> None:
+        span = self._span
+        if span is not None:
+            if exc_val:
+                _safe(lambda: span.set_attribute("error.type", type(exc_val).__name__),
+                      site="tool.end_span.error_type")
+                _safe(lambda: span.set_status(StatusCode.ERROR, str(exc_val)),
+                      site="tool.end_span.error_status")
+                _safe(lambda: span.record_exception(exc_val),
+                      site="tool.end_span.record_exception")
+            else:
+                _safe(lambda: span.set_status(StatusCode.OK),
+                      site="tool.end_span.set_ok")
+            _safe(span.end, site="tool.end_span.end")
+        ctx = self._ctx_manager
+        if ctx is not None:
+            _safe(lambda: ctx.__exit__(None, None, None), site="tool.end_span.ctx_exit")
+
+    def _set_arguments(self, kwargs: dict) -> None:
+        """Set tool call arguments (opt-in)."""
+        if self._span:
+            try:
+                self._span.set_attribute("gen_ai.tool.call.arguments", json.dumps(kwargs, default=str)[:8192])
+            except Exception:
+                pass
+
+    def _set_result(self, result: Any) -> None:
+        """Set tool call result (opt-in)."""
+        if self._span:
+            try:
+                self._span.set_attribute("gen_ai.tool.call.result", json.dumps(result, default=str)[:8192])
+            except Exception:
+                pass
+
+    def __enter__(self) -> "_ToolContext":
+        self._start_span()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self._end_span(exc_val)
+
+    async def __aenter__(self) -> "_ToolContext":
+        self._start_span()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self._end_span(exc_val)