struct-sdk 0.1.0__py3-none-any.whl

struct_sdk/langchain.py

@@ -0,0 +1,1450 @@
+"""LangChain auto-instrumentation via the official BaseCallbackHandler API.
+
+This is the same integration pattern used by LangSmith, Arize OpenInference,
+Traceloop, and Langfuse. LangChain fires ``on_*_start`` / ``on_*_end``
+callbacks for every chain / LLM / tool / retriever run, each carrying a
+``run_id`` and ``parent_run_id``. We build OTel spans from those events —
+parentage comes from LangChain's own run tree rather than from Python's
+contextvars, so it works correctly with every Runnable the framework knows
+about (including LangGraph's Pregel, custom chains, and future Runnable
+types).
+
+Why we switched from monkey-patching:
+- The previous implementation patched ``Pregel.invoke``, ``BaseTool.invoke``,
+  etc. That bets on LangChain's internal class surface, which churns across
+  releases, and misses custom Runnables entirely.
+- Double-tracing with LangSmith was unavoidable: both approaches install
+  overlapping hooks with no de-dup story.
+- The callback API is LangChain's public contract — stable across versions,
+  automatically covers every Runnable type, and is the pattern every other
+  tracing SDK in the ecosystem uses.
+
+Auto-applied by ``struct.init()`` when ``langchain-core`` is installed.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+import uuid
+from typing import TYPE_CHECKING, Any, Optional
+from uuid import UUID
+
+from opentelemetry import trace
+from opentelemetry.trace import StatusCode
+
+if TYPE_CHECKING:
+    from struct_sdk.core import StructSDK
+
+logger = logging.getLogger("struct_sdk.langchain")
+
+_MAX_CONTENT_SIZE = 128 * 1024
+_TRUNCATION_MARKER = "… [truncated]"
+_MAX_FIELD_SIZE = 16384
+
+
+# ---------------------------------------------------------------------------
+# Module state — handler + configure-wrapper bookkeeping
+# ---------------------------------------------------------------------------
+
+_STRUCT_WRAPPED = "_struct_wrapped_configure"
+_active_handler: Optional["StructCallbackHandler"] = None
+# (cls, original_classmethod) tuples so we can restore on unpatch.
+_patched_configures: list[tuple[type, Any]] = []
+
+
+def get_langchain_handler() -> Optional["StructCallbackHandler"]:
+    """The currently-registered callback handler, or None if not initialized.
+
+    Exported so callers can attach it explicitly via
+    ``runnable.invoke(x, config={"callbacks": [struct_sdk.get_langchain_handler()]})``
+    if global injection isn't in play for some reason.
+    """
+    return _active_handler
+
+
+def patch(sdk: StructSDK) -> None:
+    """Install a StructCallbackHandler as a global LangChain callback.
+
+    Wraps ``CallbackManager.configure`` (and its async counterpart) so every
+    invoke/stream/batch call picks up our handler as an inheritable
+    callback. This is exactly how OpenInference and Traceloop's LangChain
+    instrumentations hook in.
+    """
+    global _active_handler
+
+    import langchain_core  # type: ignore
+    from langchain_core.callbacks.manager import (  # type: ignore
+        AsyncCallbackManager,
+        CallbackManager,
+    )
+
+    if getattr(langchain_core, "__struct_patched", False):
+        _active_handler = _build_handler(sdk)
+        return
+
+    _active_handler = _build_handler(sdk)
+
+    for target in (CallbackManager, AsyncCallbackManager):
+        original_cm = target.__dict__.get("configure")
+        if original_cm is None:
+            continue
+        # Marker lives on the underlying function so the classmethod wrapper
+        # is transparent to the idempotency check.
+        original_func = getattr(original_cm, "__func__", original_cm)
+        if getattr(original_func, _STRUCT_WRAPPED, False):
+            continue
+
+        def _make_wrapper(orig_func: Any) -> Any:
+            def wrapped(
+                cls: Any,
+                inheritable_callbacks: Any = None,
+                local_callbacks: Any = None,
+                *args: Any,
+                **kwargs: Any,
+            ) -> Any:
+                inheritable_callbacks = _inject_handler(
+                    inheritable_callbacks, _active_handler
+                )
+                return orig_func(
+                    cls,
+                    inheritable_callbacks,
+                    local_callbacks,
+                    *args,
+                    **kwargs,
+                )
+
+            setattr(wrapped, _STRUCT_WRAPPED, True)
+            return classmethod(wrapped)
+
+        _patched_configures.append((target, original_cm))
+        setattr(target, "configure", _make_wrapper(original_func))
+
+    langchain_core.__struct_patched = True  # type: ignore[attr-defined]
+
+
+def unpatch() -> None:
+    """Restore the original CallbackManager.configure. Primarily for tests."""
+    global _active_handler
+
+    while _patched_configures:
+        cls, original_cm = _patched_configures.pop()
+        try:
+            setattr(cls, "configure", original_cm)
+        except Exception:  # noqa: BLE001
+            pass
+
+    try:
+        import langchain_core  # type: ignore
+    except ImportError:
+        _active_handler = None
+        return
+
+    _active_handler = None
+    langchain_core.__struct_patched = False  # type: ignore[attr-defined]
+
+
+def _build_handler(sdk: StructSDK) -> "StructCallbackHandler":
+    return StructCallbackHandler(
+        sdk,
+        sdk.get_tracer("struct-sdk-langchain"),
+        sdk.get_logger("struct-sdk-langchain") if sdk.emit_events else None,
+    )
+
+
+def _inject_handler(existing: Any, handler: Optional["StructCallbackHandler"]) -> Any:
+    """Merge our handler into the inheritable_handlers argument, with de-dup."""
+    if handler is None:
+        return existing
+    if existing is None:
+        return [handler]
+    if isinstance(existing, list):
+        if any(getattr(h, "name", None) == "struct" for h in existing):
+            return existing
+        return [*existing, handler]
+    add = getattr(existing, "add_handler", None)
+    handlers = getattr(existing, "handlers", []) or []
+    if callable(add) and not any(
+        getattr(h, "name", None) == "struct" for h in handlers
+    ):
+        try:
+            add(handler, True)
+        except Exception:  # noqa: BLE001
+            pass
+    return existing
+
+
+# ---------------------------------------------------------------------------
+# Provider / model detection
+# ---------------------------------------------------------------------------
+
+_PROVIDER_MAP: dict[str, str] = {
+    "ChatOpenAI": "openai",
+    "AzureChatOpenAI": "azure.openai",
+    "ChatAnthropic": "anthropic",
+    "ChatGoogleGenerativeAI": "gcp.generative_ai",
+    "ChatVertexAI": "gcp.vertex_ai",
+    "ChatCohere": "cohere",
+    "ChatMistralAI": "mistral",
+    "ChatGroq": "groq",
+    "ChatBedrock": "aws.bedrock",
+    "ChatBedrockConverse": "aws.bedrock",
+    "BedrockChat": "aws.bedrock",
+    "ChatFireworks": "fireworks",
+    "ChatTogether": "together",
+    "ChatOllama": "ollama",
+    "ChatDeepSeek": "deepseek",
+}
+
+_MODULE_PROVIDER_MAP: dict[str, str] = {
+    "openai": "openai",
+    "anthropic": "anthropic",
+    "google": "gcp.generative_ai",
+    "cohere": "cohere",
+    "mistral": "mistral",
+    "groq": "groq",
+    "bedrock": "aws.bedrock",
+    "fireworks": "fireworks",
+    "together": "together",
+    "ollama": "ollama",
+    "deepseek": "deepseek",
+}
+
+
+def _detect_provider_from_serialized(serialized: Optional[dict[str, Any]]) -> str:
+    if not isinstance(serialized, dict):
+        return "langchain"
+    cls_name = _extract_class_name(serialized)
+    if cls_name in _PROVIDER_MAP:
+        return _PROVIDER_MAP[cls_name]
+    ids = serialized.get("id")
+    module_path = ids[0] if isinstance(ids, list) and ids else ""
+    for key, provider in _MODULE_PROVIDER_MAP.items():
+        if key in module_path:
+            return provider
+    return "langchain"
+
+
+def _extract_class_name(serialized: Optional[dict[str, Any]]) -> str:
+    """Last segment of ``serialized['id']`` is the class name. Handles None."""
+    if not isinstance(serialized, dict):
+        return ""
+    ids = serialized.get("id")
+    if isinstance(ids, list) and ids:
+        last = ids[-1]
+        if isinstance(last, str):
+            return last
+    name = serialized.get("name")
+    return name if isinstance(name, str) else ""
+
+
+_AGENT_CLASSES = {
+    "AgentExecutor",
+    "CompiledStateGraph",
+    "CompiledGraph",
+    "Pregel",
+    "LangGraph",
+}
+
+# LangChain/LangGraph fires chain-start for every internal Runnable. In Python,
+# ``serialized`` is usually ``None`` for these, so we filter on run_name via a
+# denylist. Matches LangSmith's promotion heuristic.
+_INTERNAL_RUN_NAMES = {
+    "RunnableSequence",
+    "RunnableLambda",
+    "RunnablePassthrough",
+    "RunnableParallel",
+    "RunnableBinding",
+    "RunnableMap",
+    "RunnableAssign",
+    "RunnableBranch",
+    "RunnableWithFallbacks",
+    "RunnableEach",
+    "RunnablePick",
+    "RunnableGenerator",
+    "Prompt",
+    "ChatPromptTemplate",
+    "PromptTemplate",
+    "agent",
+    "tools",
+    "call_model",
+    "should_continue",
+    "__start__",
+    "__end__",
+}
+
+_INTERNAL_RUN_NAME_PREFIXES = (
+    "ChannelWrite<",
+    "Branch<",
+    "RunnableSequence<",
+)
+
+
+def _is_agent_chain(
+    serialized: Optional[dict[str, Any]],
+    run_type: Optional[str],
+    run_name: Optional[str],
+) -> bool:
+    """Only promote user-meaningful chains to ``invoke_agent`` spans."""
+    if run_type == "agent":
+        return True
+    cls = _extract_class_name(serialized)
+    if cls in _AGENT_CLASSES:
+        return True
+    if run_name:
+        if run_name in _INTERNAL_RUN_NAMES:
+            return False
+        if any(run_name.startswith(p) for p in _INTERNAL_RUN_NAME_PREFIXES):
+            return False
+        return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Message conversion helpers — LangChain message → OTel GenAI parts
+# ---------------------------------------------------------------------------
+
+_LANGCHAIN_FINISH_REASON_MAP = {
+    "end_turn": "stop",
+    "stop_sequence": "stop",
+    "max_tokens": "length",
+    "tool_use": "tool_calls",
+    "tool_calls": "tool_calls",
+    "function_call": "tool_calls",
+}
+
+
+def _message_to_role_and_parts(msg: Any) -> tuple[str, list[dict[str, Any]]]:
+    if isinstance(msg, dict):
+        role = msg.get("role", "user")
+        parts: list[dict[str, Any]] = []
+        content = msg.get("content")
+        if content:
+            parts.append({"type": "text", "content": str(content)})
+        return role, parts
+
+    cls_name = type(msg).__name__
+    parts = []
+
+    if cls_name == "ToolMessage":
+        tool_call_id = getattr(msg, "tool_call_id", "") or ""
+        content = getattr(msg, "content", "") or ""
+        parts.append({
+            "type": "tool_call_response",
+            "id": tool_call_id,
+            "response": content if isinstance(content, str) else str(content),
+        })
+        return "tool", parts
+
+    if cls_name == "SystemMessage":
+        role = "system"
+    elif cls_name == "HumanMessage":
+        role = "user"
+    elif cls_name in ("AIMessage", "AIMessageChunk"):
+        role = "assistant"
+    else:
+        role = getattr(msg, "role", None) or "user"
+
+    content = getattr(msg, "content", None)
+    if isinstance(content, str) and content:
+        parts.append({"type": "text", "content": content})
+    elif isinstance(content, list):
+        for block in content:
+            if isinstance(block, str):
+                parts.append({"type": "text", "content": block})
+            elif isinstance(block, dict):
+                bt = block.get("type")
+                if bt == "text":
+                    parts.append({"type": "text", "content": block.get("text", "")})
+                elif bt == "image_url":
+                    url = block.get("image_url", {})
+                    if isinstance(url, dict):
+                        u = url.get("url")
+                        if isinstance(u, str):
+                            parts.append({"type": "uri", "modality": "image", "uri": u})
+                    elif isinstance(url, str):
+                        parts.append({"type": "uri", "modality": "image", "uri": url})
+
+    if role == "assistant":
+        tool_calls = getattr(msg, "tool_calls", None) or []
+        for tc in tool_calls:
+            part: dict[str, Any] = {"type": "tool_call", "name": tc.get("name", "")}
+            if tc.get("id"):
+                part["id"] = tc["id"]
+            if tc.get("args") is not None:
+                part["arguments"] = tc["args"]
+            parts.append(part)
+
+    return role, parts
+
+
+def _truncate_field(value: Any, max_len: int = _MAX_FIELD_SIZE) -> Any:
+    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]]:
+    out = []
+    for part in parts:
+        part = dict(part)
+        if "content" in part and isinstance(part["content"], str):
+            part["content"] = _truncate_field(part["content"])
+        for key in ("arguments", "response"):
+            if key in part:
+                val = part[key]
+                if isinstance(val, str):
+                    part[key] = _truncate_field(val)
+                elif isinstance(val, (dict, list)):
+                    ser = json.dumps(val, default=str)
+                    if len(ser) > _MAX_FIELD_SIZE:
+                        part[key] = ser[:_MAX_FIELD_SIZE] + _TRUNCATION_MARKER
+        out.append(part)
+    return out
+
+
+def _truncate_and_serialize(obj: Any, max_size: int = _MAX_CONTENT_SIZE) -> str:
+    if isinstance(obj, list):
+        truncated: list[Any] = []
+        for item in obj:
+            if isinstance(item, dict):
+                item = dict(item)
+                if isinstance(item.get("parts"), list):
+                    item["parts"] = _truncate_parts(item["parts"])
+                elif isinstance(item.get("content"), str):
+                    item["content"] = _truncate_field(item["content"])
+            truncated.append(item)
+        result = json.dumps(truncated, default=str)
+    else:
+        result = json.dumps(obj, default=str)
+
+    if len(result) > max_size:
+        cut = result[: max_size - 50]
+        last_brace = cut.rfind("}")
+        result = cut[: last_brace + 1] + "]" if last_brace > 0 else "[]"
+    return result
+
+
+def _last_user_parts(messages: list[Any]) -> Optional[list[dict[str, Any]]]:
+    for msg in reversed(messages):
+        role, parts = _message_to_role_and_parts(msg)
+        if role == "user":
+            return parts
+    return None
+
+
+# ---------------------------------------------------------------------------
+# StructCallbackHandler
+# ---------------------------------------------------------------------------
+
+try:
+    from langchain_core.callbacks.base import BaseCallbackHandler  # type: ignore
+except ImportError:  # pragma: no cover
+    class BaseCallbackHandler:  # type: ignore[no-redef]
+        """Placeholder so struct_sdk imports cleanly when langchain-core is absent."""
+
+
+class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
+    """LangChain callback handler that emits OTel spans + log events.
+
+    Parent-child span linkage is built from LangChain's ``run_id`` /
+    ``parent_run_id`` — NOT from OTel's active context. That makes us robust
+    to LangGraph's internal task scheduling (which drops the active context
+    across microtasks) and matches LangSmith/OpenInference/Traceloop/Langfuse.
+
+    thread_id vs gen_ai.conversation.id
+    -----------------------------------
+
+    * ``config.configurable.thread_id`` (LangGraph) — checkpoint identifier.
+      Keys a conversation's state in the checkpointer (MemorySaver,
+      PostgresSaver). Multiple turns of the SAME conversation reuse one
+      thread_id so history accumulates.
+    * ``gen_ai.conversation.id`` (OTel GenAI spec) — the spec-blessed name
+      for the conversation/thread identifier. We emit this on every span as
+      the canonical session identifier.
+
+    We used to also emit ``session.id`` (generic OTel); that's been dropped
+    in favour of the GenAI-spec name.
+
+    For SUBAGENTS (an agent invoked from inside another's tool body) we
+    deliberately assign a DIFFERENT ``conversation.id`` — either the
+    subagent's own ``thread_id`` if supplied, or a fresh UUID. The resulting
+    subagent span is linked to the outer agent via our
+    ``struct.agent.parent_session_id`` attribute (what powers "Spawned by"
+    navigation in the UI). Without this split, subagent spans would collapse
+    into the outer session and hide delegation.
+
+    LangChain quirk (handled automatically): when ``agent.invoke(...)`` runs
+    nested inside a parent call, LangChain's config-merge inherits the
+    parent's ``metadata.thread_id`` onto the child — even if the child
+    config supplied its own. We detect that by comparing against the
+    nearest agent ancestor's session; if they match, treat as "inherited,
+    not user-intended" and assign a fresh UUID.
+
+    End-user guidance:
+      * Use thread_id per conversation; multi-turn chats reuse it.
+      * For a subagent call, pass a DIFFERENT thread_id (or omit it and let
+        LangGraph generate one). Subagents then surface as their own
+        sessions in the UI, linked back via parent_session_id.
+    """
+
+    name = "struct"
+    ignore_llm = False
+    ignore_chain = False
+    ignore_agent = False
+    ignore_retriever = False
+    ignore_chat_model = False
+    ignore_custom_event = True
+    raise_error = False
+    run_inline = True
+
+    def __init__(self, sdk: StructSDK, tracer: trace.Tracer, otel_logger: Any) -> None:
+        super().__init__()
+        self._sdk = sdk
+        self._tracer = tracer
+        self._logger = otel_logger
+        self._runs: dict[str, _RunState] = {}
+
+    # ── Chain / Agent ───────────────────────────────────────────────────────
+
+    def on_chain_start(
+        self,
+        serialized: dict[str, Any],
+        inputs: dict[str, Any],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        from struct_sdk.core import _safe
+
+        run_type = kwargs.get("run_type")
+        run_name = kwargs.get("name")
+        key = str(run_id)
+        parent_key = str(parent_run_id) if parent_run_id else None
+
+        if not _is_agent_chain(serialized or {}, run_type, run_name):
+            # Skipped chain — record entry so descendants can walk the parent
+            # chain and find the nearest agent ancestor's session id.
+            effective_parent = self._resolve_parent(parent_key).span
+            session_id = self._resolve_session_id(parent_key, metadata)
+            self._runs[key] = _RunState(
+                span=None,
+                effective_parent_span=effective_parent,
+                session_id=session_id,
+                nearest_agent_session_id=self._inherited_agent_session_id(parent_key),
+                nearest_agent_span=self._inherited_agent_span(parent_key),
+                kind="skipped-chain",
+            )
+            return
+
+        # For the parent_session_id linkage we need the NEAREST AGENT ancestor,
+        # not just the immediate parent (which might be a tool / llm / skipped
+        # chain). Use the cached nearest_agent_session_id field.
+        parent_agent_session_id = self._inherited_agent_session_id(parent_key)
+        session_id = self._resolve_agent_session_id(metadata, parent_agent_session_id)
+        parent = self._resolve_parent(parent_key)
+
+        agent_name: str = "agent"
+        span: Optional[trace.Span] = None
+
+        def create_span() -> None:
+            nonlocal span, agent_name
+            agent_name = (
+                run_name
+                or _extract_class_name(serialized or {})
+                or (inputs.get("name") if isinstance(inputs, dict) else None)
+                or "agent"
+            )
+            parent_ctx = trace.set_span_in_context(parent.span) if parent.span else None
+            span = self._tracer.start_span(
+                f"invoke_agent {agent_name}",
+                kind=trace.SpanKind.INTERNAL,
+                context=parent_ctx,
+            )
+
+        _safe(create_span, site="langchain.on_chain_start.create_span")
+
+        if span is None:
+            # No telemetry; record run_state without a span so end/error callbacks
+            # can find it and cleanly skip span operations. Descendants still
+            # get the inherited nearest-agent ancestry from the parent.
+            self._runs[key] = _RunState(
+                span=None,
+                effective_parent_span=parent.span,
+                session_id=session_id,
+                nearest_agent_session_id=self._inherited_agent_session_id(parent_key),
+                nearest_agent_span=self._inherited_agent_span(parent_key),
+                kind="chain",
+            )
+            return
+
+        def set_attrs() -> None:
+            assert span is not None
+            span.set_attribute("gen_ai.operation.name", "invoke_agent")
+            span.set_attribute("gen_ai.provider.name", "langchain")
+            span.set_attribute("gen_ai.agent.name", str(agent_name))
+            # Don't set gen_ai.agent.id from session_id — the spec uses agent.id
+            # for a stable agent-definition identifier, not per-invocation.
+            span.set_attribute("gen_ai.conversation.id", session_id)
+            if (
+                parent_agent_session_id
+                and parent_agent_session_id != session_id
+            ):
+                span.set_attribute("struct.agent.parent_session_id", parent_agent_session_id)
+
+        _safe(set_attrs, site="langchain.on_chain_start.start_attrs")
+
+        self._runs[key] = _RunState(
+            span=span,
+            effective_parent_span=span,
+            session_id=session_id,
+            nearest_agent_session_id=session_id,  # self is the nearest agent for descendants
+            nearest_agent_span=span,              # same — this span IS the agent
+            kind="chain",
+        )
+
+    def on_chain_end(
+        self,
+        outputs: Any,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        from struct_sdk.core import _safe
+
+        r = self._runs.pop(str(run_id), None)
+        if not r or not r.span:
+            return
+        span = r.span
+        _safe(lambda: span.set_status(StatusCode.OK),
+              site="langchain.on_chain_end.set_status")
+        _safe(span.end, site="langchain.on_chain_end.span_end")
+
+    def on_chain_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        from struct_sdk.core import _safe
+
+        r = self._runs.pop(str(run_id), None)
+        if not r or not r.span:
+            return
+        span = r.span
+        _safe(lambda: _record_error(span, error),
+              site="langchain.on_chain_error.record_error")
+        _safe(span.end, site="langchain.on_chain_error.span_end")
+
+    # ── LLM / Chat model ────────────────────────────────────────────────────
+
+    def on_chat_model_start(
+        self,
+        serialized: dict[str, Any],
+        messages: list[list[Any]],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        from struct_sdk.core import _safe
+
+        key = str(run_id)
+        parent_key = str(parent_run_id) if parent_run_id else None
+        provider = _detect_provider_from_serialized(serialized or {})
+
+        invocation = kwargs.get("invocation_params") or {}
+        model = (
+            invocation.get("model")
+            or invocation.get("model_name")
+            or kwargs.get("name")
+            or "unknown"
+        )
+
+        parent = self._resolve_parent(parent_key)
+        session_id = self._resolve_session_id(parent_key, metadata)
+
+        span: Optional[trace.Span] = None
+
+        def create_span() -> None:
+            nonlocal span
+            parent_ctx = trace.set_span_in_context(parent.span) if parent.span else None
+            span = self._tracer.start_span(
+                f"chat {model}",
+                kind=trace.SpanKind.CLIENT,
+                context=parent_ctx,
+            )
+
+        _safe(create_span, site="langchain.on_chat_model_start.create_span")
+
+        if span is None:
+            self._runs[key] = _RunState(
+                span=None,
+                effective_parent_span=parent.span,
+                session_id=session_id,
+                nearest_agent_session_id=self._inherited_agent_session_id(parent_key),
+                nearest_agent_span=self._inherited_agent_span(parent_key),
+                kind="llm",
+            )
+            return
+
+        def set_attrs() -> None:
+            assert span is not None
+            span.set_attribute("gen_ai.operation.name", "chat")
+            span.set_attribute("gen_ai.provider.name", provider)
+            span.set_attribute("gen_ai.request.model", str(model))
+            span.set_attribute("gen_ai.conversation.id", session_id)
+
+            _set_request_attrs(span, invocation)
+
+            flat = [m for seq in messages for m in seq]
+            if flat:
+                span.set_attribute("struct.input.message_count", len(flat))
+                if self._sdk.emit_events and self._logger:
+                    _emit_message_events(self._logger, flat, provider, session_id, span)
+                if self._sdk.emit_span_content:
+                    span.set_attribute(
+                        "gen_ai.input.messages",
+                        _to_input_messages(flat),
+                    )
+                ancestor_agent = parent.span if parent.is_agent else self._find_agent_ancestor(parent_key)
+                if ancestor_agent is not None:
+                    _propagate_user_prompt(ancestor_agent, flat)
+
+        _safe(set_attrs, site="langchain.on_chat_model_start.start_attrs")
+
+        self._runs[key] = _RunState(
+            span=span,
+            effective_parent_span=span,
+            session_id=session_id,
+            nearest_agent_session_id=self._inherited_agent_session_id(parent_key),
+            nearest_agent_span=self._inherited_agent_span(parent_key),
+            kind="llm",
+        )
+
+    def on_llm_start(
+        self,
+        serialized: dict[str, Any],
+        prompts: list[str],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        messages = [[{"role": "user", "content": p}] for p in prompts]
+        self.on_chat_model_start(
+            serialized,
+            messages,
+            run_id=run_id,
+            parent_run_id=parent_run_id,
+            tags=tags,
+            metadata=metadata,
+            **kwargs,
+        )
+
+    def on_llm_end(
+        self,
+        response: Any,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        from struct_sdk.core import _safe
+
+        r = self._runs.pop(str(run_id), None)
+        if not r or not r.span:
+            return
+        span = r.span
+
+        def set_response_attrs() -> None:
+            generations = getattr(response, "generations", None) or []
+            first = generations[0][0] if generations and generations[0] else None
+            message = getattr(first, "message", None) if first is not None else None
+            if message is None:
+                return
+            provider = span.attributes.get("gen_ai.provider.name") if hasattr(span, "attributes") else None  # type: ignore[union-attr]
+            _set_llm_response_attrs(
+                span, self._sdk, self._logger, message, provider, r.session_id
+            )
+
+        def push_pending_tool_calls() -> None:
+            generations = getattr(response, "generations", None) or []
+            first = generations[0][0] if generations and generations[0] else None
+            message = getattr(first, "message", None) if first is not None else None
+            if message is None:
+                return
+            tool_calls = getattr(message, "tool_calls", None) or []
+            if not tool_calls:
+                return
+            pairs = [
+                (tc.get("name", ""), tc.get("id", ""))
+                for tc in tool_calls
+                if tc.get("name") and tc.get("id")
+            ]
+            if pairs:
+                _push_pending_tool_calls(pairs)
+
+        _safe(set_response_attrs, site="langchain.on_llm_end.set_response_attrs")
+        _safe(push_pending_tool_calls,
+              site="langchain.on_llm_end.record_pending_tool_calls")
+        _safe(lambda: span.set_status(StatusCode.OK),
+              site="langchain.on_llm_end.set_status")
+        _safe(span.end, site="langchain.on_llm_end.span_end")
+
+    def on_llm_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        from struct_sdk.core import _safe
+
+        r = self._runs.pop(str(run_id), None)
+        if not r or not r.span:
+            return
+        span = r.span
+        _safe(lambda: _record_error(span, error),
+              site="langchain.on_llm_error.record_error")
+        _safe(span.end, site="langchain.on_llm_error.span_end")
+
+    # ── Tool ────────────────────────────────────────────────────────────────
+
+    def on_tool_start(
+        self,
+        serialized: dict[str, Any],
+        input_str: str,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        inputs: Optional[dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        from struct_sdk.core import _safe
+
+        key = str(run_id)
+        parent_key = str(parent_run_id) if parent_run_id else None
+
+        tool_name = (
+            kwargs.get("name")
+            or (serialized.get("name") if isinstance(serialized, dict) else None)
+            or _extract_class_name(serialized or {})
+            or "tool"
+        )
+
+        parent = self._resolve_parent(parent_key)
+        session_id = self._resolve_session_id(parent_key, metadata)
+
+        span: Optional[trace.Span] = None
+
+        def create_span() -> None:
+            nonlocal span
+            parent_ctx = trace.set_span_in_context(parent.span) if parent.span else None
+            span = self._tracer.start_span(
+                f"execute_tool {tool_name}",
+                kind=trace.SpanKind.INTERNAL,
+                context=parent_ctx,
+            )
+
+        _safe(create_span, site="langchain.on_tool_start.create_span")
+
+        if span is None:
+            self._runs[key] = _RunState(
+                span=None,
+                effective_parent_span=parent.span,
+                session_id=session_id,
+                nearest_agent_session_id=self._inherited_agent_session_id(parent_key),
+                nearest_agent_span=self._inherited_agent_span(parent_key),
+                kind="tool",
+            )
+            return
+
+        def set_attrs() -> None:
+            assert span is not None
+            span.set_attribute("gen_ai.operation.name", "execute_tool")
+            span.set_attribute("gen_ai.provider.name", "langchain")
+            span.set_attribute("gen_ai.tool.name", str(tool_name))
+
+            tool_call_id = _extract_tool_call_id_from_inputs(inputs) or _pop_pending_tool_call_id(str(tool_name))
+            if tool_call_id:
+                span.set_attribute("gen_ai.tool.call.id", tool_call_id)
+
+            span.set_attribute("gen_ai.conversation.id", session_id)
+
+            if self._sdk.capture_content and input_str:
+                span.set_attribute(
+                    "gen_ai.tool.call.arguments",
+                    json.dumps(input_str, default=str)[:8192],
+                )
+
+        _safe(set_attrs, site="langchain.on_tool_start.start_attrs")
+
+        self._runs[key] = _RunState(
+            span=span,
+            effective_parent_span=span,
+            session_id=session_id,
+            nearest_agent_session_id=self._inherited_agent_session_id(parent_key),
+            nearest_agent_span=self._inherited_agent_span(parent_key),
+            kind="tool",
+        )
+
+    def on_tool_end(
+        self,
+        output: Any,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        from struct_sdk.core import _safe
+
+        r = self._runs.pop(str(run_id), None)
+        if not r or not r.span:
+            return
+        span = r.span
+
+        def set_result_attr() -> None:
+            if self._sdk.capture_content and output is not None:
+                span.set_attribute(
+                    "gen_ai.tool.call.result",
+                    json.dumps(output, default=str)[:8192],
+                )
+
+        _safe(set_result_attr, site="langchain.on_tool_end.set_result")
+        _safe(lambda: span.set_status(StatusCode.OK),
+              site="langchain.on_tool_end.set_status")
+        _safe(span.end, site="langchain.on_tool_end.span_end")
+
+    def on_tool_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        from struct_sdk.core import _safe
+
+        r = self._runs.pop(str(run_id), None)
+        if not r or not r.span:
+            return
+        span = r.span
+        _safe(lambda: _record_error(span, error),
+              site="langchain.on_tool_error.record_error")
+        _safe(span.end, site="langchain.on_tool_error.span_end")
+
+    # ── Retriever ───────────────────────────────────────────────────────────
+
+    def on_retriever_start(
+        self,
+        serialized: dict[str, Any],
+        query: str,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        tags: Optional[list[str]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> None:
+        from struct_sdk.core import _safe
+
+        key = str(run_id)
+        parent_key = str(parent_run_id) if parent_run_id else None
+
+        name = (
+            kwargs.get("name")
+            or (serialized.get("name") if isinstance(serialized, dict) else None)
+            or _extract_class_name(serialized or {})
+            or "retriever"
+        )
+
+        parent = self._resolve_parent(parent_key)
+        session_id = self._resolve_session_id(parent_key, metadata)
+
+        span: Optional[trace.Span] = None
+
+        def create_span() -> None:
+            nonlocal span
+            parent_ctx = trace.set_span_in_context(parent.span) if parent.span else None
+            span = self._tracer.start_span(
+                f"retrieval {name}",
+                kind=trace.SpanKind.INTERNAL,
+                context=parent_ctx,
+            )
+
+        _safe(create_span, site="langchain.on_retriever_start.create_span")
+
+        if span is None:
+            self._runs[key] = _RunState(
+                span=None,
+                effective_parent_span=parent.span,
+                session_id=session_id,
+                nearest_agent_session_id=self._inherited_agent_session_id(parent_key),
+                nearest_agent_span=self._inherited_agent_span(parent_key),
+                kind="retriever",
+            )
+            return
+
+        def set_attrs() -> None:
+            assert span is not None
+            span.set_attribute("gen_ai.operation.name", "retrieval")
+            span.set_attribute("gen_ai.provider.name", "langchain")
+            span.set_attribute("gen_ai.data_source.id", str(name))
+            span.set_attribute("gen_ai.conversation.id", session_id)
+            if self._sdk.capture_content and query:
+                span.set_attribute("gen_ai.retrieval.query.text", str(query)[:4096])
+
+        _safe(set_attrs, site="langchain.on_retriever_start.start_attrs")
+
+        self._runs[key] = _RunState(
+            span=span,
+            effective_parent_span=span,
+            session_id=session_id,
+            nearest_agent_session_id=self._inherited_agent_session_id(parent_key),
+            nearest_agent_span=self._inherited_agent_span(parent_key),
+            kind="retriever",
+        )
+
+    def on_retriever_end(
+        self,
+        documents: Any,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        from struct_sdk.core import _safe
+
+        r = self._runs.pop(str(run_id), None)
+        if not r or not r.span:
+            return
+        span = r.span
+
+        def set_doc_count() -> None:
+            if isinstance(documents, list):
+                span.set_attribute("gen_ai.retrieval.documents", len(documents))
+
+        _safe(set_doc_count, site="langchain.on_retriever_end.set_doc_count")
+        _safe(lambda: span.set_status(StatusCode.OK),
+              site="langchain.on_retriever_end.set_status")
+        _safe(span.end, site="langchain.on_retriever_end.span_end")
+
+    def on_retriever_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any,
+    ) -> None:
+        from struct_sdk.core import _safe
+
+        r = self._runs.pop(str(run_id), None)
+        if not r or not r.span:
+            return
+        span = r.span
+        _safe(lambda: _record_error(span, error),
+              site="langchain.on_retriever_error.record_error")
+        _safe(span.end, site="langchain.on_retriever_error.span_end")
+
+    # ── Internals ───────────────────────────────────────────────────────────
+
+    def _resolve_parent(self, parent_run_id: Optional[str]) -> "_ParentInfo":
+        if parent_run_id:
+            p = self._runs.get(parent_run_id)
+            if p is not None:
+                return _ParentInfo(
+                    span=p.effective_parent_span,
+                    is_agent=p.kind == "chain",
+                    span_session_id=p.session_id,
+                )
+        from struct_sdk.core import _current_agent_span, _current_session_id
+
+        span = _current_agent_span.get(None)
+        return _ParentInfo(
+            span=span,
+            is_agent=span is not None,
+            span_session_id=_current_session_id.get(None),
+        )
+
+    def _find_agent_ancestor(self, parent_run_id: Optional[str]) -> Optional[trace.Span]:
+        """Nearest ``invoke_agent`` ancestor span.
+
+        Used by the chat/LLM handler to propagate the user's most-recent
+        message onto the enclosing agent span's ``gen_ai.input.messages`` so
+        the waterfall UI can show the prompt at the agent level. Reads from
+        the cached ``nearest_agent_span`` populated at RunState creation — the
+        same pattern as ``_inherited_agent_session_id``, O(1) per lookup.
+        """
+        if parent_run_id:
+            r = self._runs.get(parent_run_id)
+            if r is not None and r.nearest_agent_span is not None:
+                return r.nearest_agent_span
+        from struct_sdk.core import _current_agent_span
+        return _current_agent_span.get(None)
+
+    def _inherited_agent_span(self, parent_run_id: Optional[str]) -> Optional[trace.Span]:
+        """Nearest ``invoke_agent`` ancestor span — O(1) lookup.
+
+        Mirrors ``_inherited_agent_session_id`` for the span pointer. Cached
+        at every RunState creation so descendants can reach the ancestor
+        without walking a parent chain (which we don't retain).
+        """
+        if not parent_run_id:
+            return None
+        p = self._runs.get(parent_run_id)
+        return p.nearest_agent_span if p else None
+
+    def _inherited_agent_session_id(self, parent_run_id: Optional[str]) -> Optional[str]:
+        """Nearest ``invoke_agent`` ancestor's gen_ai.conversation.id — O(1) lookup.
+
+        Every run records ``nearest_agent_session_id`` at creation (its own
+        session if it IS an agent, else inherited from parent). A subagent's
+        chain-start uses this to set ``struct.agent.parent_session_id`` on
+        the new agent span even when the immediate parent is a tool / LLM /
+        filtered chain.
+        """
+        if not parent_run_id:
+            return None
+        p = self._runs.get(parent_run_id)
+        return p.nearest_agent_session_id if p else None
+
+    def _resolve_session_id(
+        self,
+        parent_run_id: Optional[str],
+        metadata: Optional[dict[str, Any]],
+    ) -> str:
+        """For chat/tool/retriever spans — inherit from parent so everything rolls up."""
+        if parent_run_id:
+            p = self._runs.get(parent_run_id)
+            if p and p.session_id:
+                return p.session_id
+        if metadata and isinstance(metadata.get("thread_id"), str) and metadata["thread_id"]:
+            return metadata["thread_id"]
+        from struct_sdk.core import _current_session_id
+        ambient = _current_session_id.get(None)
+        if ambient:
+            return ambient
+        return str(uuid.uuid4())
+
+    def _resolve_agent_session_id(
+        self,
+        metadata: Optional[dict[str, Any]],
+        parent_agent_session_id: Optional[str] = None,
+    ) -> str:
+        """For AGENT spans — each invocation gets its own conversation id.
+
+        Prefer config-supplied thread_id for multi-turn continuity, fall
+        back to a fresh UUID. Never inherit from the parent run —
+        subagents should surface as separate sessions in the UI.
+
+        LangChain quirk: when a nested invoke runs inside a parent call,
+        LangChain inherits the parent's metadata.thread_id onto the child
+        even if the child supplied its own. Detect that by comparing
+        against the nearest-agent-ancestor's session and assign a fresh
+        UUID if they match.
+        """
+        thread_id = metadata.get("thread_id") if metadata else None
+        if isinstance(thread_id, str) and thread_id:
+            if parent_agent_session_id and thread_id == parent_agent_session_id:
+                return str(uuid.uuid4())
+            return thread_id
+        from struct_sdk.core import _current_session_id
+        ambient = _current_session_id.get(None)
+        if ambient:
+            return ambient
+        return str(uuid.uuid4())
+
+
+# ---------------------------------------------------------------------------
+# Internal dataclasses + shared helpers
+# ---------------------------------------------------------------------------
+
+
+class _RunState:
+    """Per-runId bookkeeping used by StructCallbackHandler."""
+
+    __slots__ = (
+        "span",
+        "effective_parent_span",
+        "session_id",
+        "nearest_agent_session_id",
+        "nearest_agent_span",
+        "kind",
+    )
+
+    def __init__(
+        self,
+        *,
+        span: Optional[trace.Span],
+        effective_parent_span: Optional[trace.Span],
+        session_id: str,
+        nearest_agent_session_id: Optional[str],
+        nearest_agent_span: Optional[trace.Span],
+        kind: str,
+    ) -> None:
+        self.span = span
+        self.effective_parent_span = effective_parent_span
+        self.session_id = session_id
+        self.nearest_agent_session_id = nearest_agent_session_id
+        self.nearest_agent_span = nearest_agent_span
+        self.kind = kind
+
+
+class _ParentInfo:
+    __slots__ = ("span", "is_agent", "span_session_id")
+
+    def __init__(
+        self,
+        *,
+        span: Optional[trace.Span],
+        is_agent: bool,
+        span_session_id: Optional[str],
+    ) -> None:
+        self.span = span
+        self.is_agent = is_agent
+        self.span_session_id = span_session_id
+
+
+def _record_error(span: trace.Span, err: BaseException) -> None:
+    span.set_attribute("error.type", type(err).__name__)
+    span.set_status(StatusCode.ERROR, str(err))
+    span.record_exception(err)
+
+
+def _set_request_attrs(span: trace.Span, invocation: dict[str, Any]) -> None:
+    mapping = [
+        ("temperature", "gen_ai.request.temperature"),
+        ("max_tokens", "gen_ai.request.max_tokens"),
+        ("maxTokens", "gen_ai.request.max_tokens"),
+        ("top_p", "gen_ai.request.top_p"),
+        ("topP", "gen_ai.request.top_p"),
+        ("top_k", "gen_ai.request.top_k"),
+        ("topK", "gen_ai.request.top_k"),
+        ("frequency_penalty", "gen_ai.request.frequency_penalty"),
+        ("presence_penalty", "gen_ai.request.presence_penalty"),
+    ]
+    for src, dst in mapping:
+        val = invocation.get(src)
+        if isinstance(val, (int, float)):
+            span.set_attribute(dst, val)
+    stop = invocation.get("stop") or invocation.get("stop_sequences")
+    if isinstance(stop, list) and stop:
+        span.set_attribute("gen_ai.request.stop_sequences", stop)
+
+
+def _set_llm_response_attrs(
+    span: trace.Span,
+    sdk: StructSDK,
+    otel_logger: Any,
+    message: Any,
+    provider: Optional[str],
+    session_id: str,
+) -> None:
+    usage = getattr(message, "usage_metadata", None) or {}
+    if isinstance(usage, dict):
+        if isinstance(usage.get("input_tokens"), int):
+            span.set_attribute("gen_ai.usage.input_tokens", usage["input_tokens"])
+        if isinstance(usage.get("output_tokens"), int):
+            span.set_attribute("gen_ai.usage.output_tokens", usage["output_tokens"])
+        details = usage.get("input_token_details") or {}
+        cr = details.get("cache_read")
+        cc = details.get("cache_creation")
+        if isinstance(cr, int) and cr > 0:
+            span.set_attribute("gen_ai.usage.cache_read.input_tokens", cr)
+        if isinstance(cc, int) and cc > 0:
+            span.set_attribute("gen_ai.usage.cache_creation.input_tokens", cc)
+
+    resp_meta = getattr(message, "response_metadata", None) or {}
+    resp_model = resp_meta.get("model_name") or resp_meta.get("model")
+    if isinstance(resp_model, str):
+        span.set_attribute("gen_ai.response.model", resp_model)
+
+    finish = resp_meta.get("finish_reason") or resp_meta.get("stop_reason")
+    if isinstance(finish, str):
+        mapped = _LANGCHAIN_FINISH_REASON_MAP.get(finish, finish)
+        span.set_attribute("gen_ai.response.finish_reasons", [mapped])
+
+    resp_id = getattr(message, "id", None) or resp_meta.get("id")
+    if isinstance(resp_id, str):
+        span.set_attribute("gen_ai.response.id", resp_id)
+
+    if sdk.emit_events and otel_logger:
+        _emit_choice_event(otel_logger, message, provider or "langchain", session_id, span)
+    if sdk.emit_span_content:
+        span.set_attribute("gen_ai.output.messages", _to_output_messages(message))
+
+
+def _extract_tool_call_id_from_inputs(inputs: Optional[dict[str, Any]]) -> Optional[str]:
+    if not isinstance(inputs, dict):
+        return None
+    id_val = inputs.get("id")
+    if isinstance(id_val, str) and id_val:
+        return id_val
+    return None
+
+
+def _push_pending_tool_calls(pairs: list[tuple[str, str]]) -> None:
+    from struct_sdk.core import _pending_tool_calls
+    pending = _pending_tool_calls.get()
+    if pending is None:
+        pending = {}
+        _pending_tool_calls.set(pending)
+    for name, call_id in pairs:
+        pending.setdefault(name, []).append(call_id)
+
+
+def _pop_pending_tool_call_id(name: str) -> Optional[str]:
+    from struct_sdk.core import _pending_tool_calls
+    pending = _pending_tool_calls.get(None)
+    if not pending:
+        return None
+    ids = pending.get(name)
+    if not ids:
+        return None
+    return ids.pop(0)
+
+
+def _propagate_user_prompt(agent_span: trace.Span, messages: list[Any]) -> None:
+    try:
+        existing = None
+        if hasattr(agent_span, "attributes"):
+            existing = agent_span.attributes.get("gen_ai.input.messages")  # type: ignore[union-attr]
+        if existing:
+            return
+        parts = _last_user_parts(messages)
+        if parts is None:
+            return
+        agent_span.set_attribute(
+            "gen_ai.input.messages",
+            _truncate_and_serialize([{"role": "user", "parts": parts}]),
+        )
+    except Exception:  # noqa: BLE001
+        pass
+
+
+def _to_input_messages(messages: list[Any]) -> str:
+    try:
+        out = [{"role": role, "parts": parts} for role, parts in (_message_to_role_and_parts(m) for m in messages)]
+        return _truncate_and_serialize(out)
+    except Exception:  # noqa: BLE001
+        return "[]"
+
+
+def _to_output_messages(message: Any) -> str:
+    try:
+        _role, parts = _message_to_role_and_parts(message)
+        resp_meta = getattr(message, "response_metadata", None) or {}
+        finish = resp_meta.get("finish_reason") or resp_meta.get("stop_reason")
+        msg: dict[str, Any] = {"role": "assistant", "parts": parts}
+        if isinstance(finish, str):
+            msg["finish_reason"] = _LANGCHAIN_FINISH_REASON_MAP.get(finish, finish)
+        return _truncate_and_serialize([msg])
+    except Exception:  # noqa: BLE001
+        return "[]"
+
+
+_EVENT_NAME_MAP = {
+    "user": "gen_ai.user.message",
+    "assistant": "gen_ai.assistant.message",
+    "system": "gen_ai.system.message",
+    "tool": "gen_ai.tool.message",
+}
+
+
+def _emit_message_events(
+    otel_logger: Any,
+    messages: list[Any],
+    provider: str,
+    session_id: str,
+    span: Optional[trace.Span] = None,
+) -> None:
+    try:
+        from opentelemetry._logs import LogRecord, SeverityNumber
+
+        # The callback handler doesn't run inside a `with
+        # use_span(...)` block, so `trace.get_current_span()` is NOT
+        # guaranteed to return the span we just created. Always prefer the
+        # explicitly-passed span; fall back to the ambient lookup only for
+        # backward compatibility with any out-of-tree callers.
+        span_ctx = (span or trace.get_current_span()).get_span_context()
+        for idx, msg in enumerate(messages):
+            role, parts = _message_to_role_and_parts(msg)
+            event_name = _EVENT_NAME_MAP.get(role, f"gen_ai.{role}.message")
+            payload = json.dumps({"role": role, "parts": _truncate_parts(parts)}, default=str)
+            # OTel logs convention: Body holds the event tag (human-readable
+            # signal), the structured JSON payload lives on `attributes.body`.
+            attrs: dict[str, Any] = {
+                "event.name": event_name,
+                "body": payload,
+                "gen_ai.system": provider,
+                "gen_ai.message.index": idx,
+                "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:  # noqa: BLE001
+        logger.debug("failed to emit message events", exc_info=True)
+
+
+def _emit_choice_event(
+    otel_logger: Any,
+    message: Any,
+    provider: str,
+    session_id: str,
+    span: Optional[trace.Span] = None,
+) -> None:
+    try:
+        from opentelemetry._logs import LogRecord, SeverityNumber
+
+        span_ctx = (span or trace.get_current_span()).get_span_context()
+        _role, parts = _message_to_role_and_parts(message)
+        resp_meta = getattr(message, "response_metadata", None) or {}
+        finish = resp_meta.get("finish_reason") or resp_meta.get("stop_reason") or "stop"
+        mapped = _LANGCHAIN_FINISH_REASON_MAP.get(finish, finish)
+        payload = json.dumps({
+            "index": 0,
+            "finish_reason": mapped,
+            "message": {"role": "assistant", "parts": _truncate_parts(parts)},
+        }, default=str)
+        event_name = "gen_ai.choice"
+        # OTel logs convention: tag on Body, JSON payload on attributes.body.
+        attrs: dict[str, Any] = {
+            "event.name": event_name,
+            "body": payload,
+            "gen_ai.system": provider,
+            "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:  # noqa: BLE001
+        logger.debug("failed to emit choice event", exc_info=True)