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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: struct-sdk
-Version: 0.2.8
+Version: 0.2.10
 Summary: Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry
 Project-URL: Homepage, https://struct.ai
 Project-URL: Documentation, https://struct.ai/docs
@@ -29,10 +29,10 @@ Requires-Dist: anthropic>=0.30.0; extra == 'anthropic'
 Provides-Extra: claude-agent-sdk
 Requires-Dist: claude-agent-sdk>=0.1.59; extra == 'claude-agent-sdk'
 Provides-Extra: demo
-Requires-Dist: langchain-anthropic>=0.3.0; extra == 'demo'
+Requires-Dist: langchain-anthropic>=1.4.6; extra == 'demo'
 Requires-Dist: langchain-core>=1.3.3; extra == 'demo'
 Requires-Dist: langchain-openai>=0.2.0; extra == 'demo'
-Requires-Dist: langchain>=1.3.0; extra == 'demo'
+Requires-Dist: langchain>=1.3.9; extra == 'demo'
 Requires-Dist: langgraph>=0.2.0; extra == 'demo'
 Requires-Dist: python-dotenv>=1.0.0; extra == 'demo'
 Provides-Extra: dev

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.2.8"
+version = "0.2.10"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -40,10 +40,10 @@ anthropic = ["anthropic>=0.30.0"]
 claude-agent-sdk = ["claude-agent-sdk>=0.1.59"]
 langchain = ["langchain-core>=1.3.3"]
 demo = [
-    "langchain>=1.3.0",
+    "langchain>=1.3.9",
     "langchain-core>=1.3.3",
     "langchain-openai>=0.2.0",
-    "langchain-anthropic>=0.3.0",
+    "langchain-anthropic>=1.4.6",
     "langgraph>=0.2.0",
     "python-dotenv>=1.0.0",
 ]
@@ -70,6 +70,8 @@ override-dependencies = [
     "langchain-text-splitters>=1.1.2",
     "python-multipart>=0.0.30",
     "starlette>=1.3.1",
+    "langsmith>=0.8.18",
+    "pydantic-settings>=2.14.2",
 ]
 
 [tool.pytest.ini_options]

{struct_sdk-0.2.8 → struct_sdk-0.2.10}/src/struct_sdk/anthropic.py

@@ -290,28 +290,149 @@ def _wrap_create(original: Any, tracer: trace.Tracer, sdk: StructSDK, otel_logge
 # messages.stream — context manager wrapping
 # ---------------------------------------------------------------------------
 
+def _finish_stream_span(
+    span: trace.Span, stream: Any, sdk: "StructSDK", model: str, otel_logger: Any, exc: tuple
+) -> None:
+    """End the streaming ``chat`` span EXACTLY ONCE on block exit: populate
+    response attributes from the accumulated final message (best-effort — the
+    stream may have been left partially consumed), set status, and end. All
+    _safe-wrapped so a broken stream can never fault the host's ``with`` block."""
+    from struct_sdk.core import _safe
+
+    def body() -> None:
+        final_msg = None
+        if stream is not None:
+            try:
+                getter = getattr(stream, "get_final_message", None)
+                final_msg = getter() if getter is not None else None
+            except Exception:  # noqa: BLE001 — partial/aborted streams have no final message
+                final_msg = None
+        if final_msg is not None:
+            _set_response_attrs(span, sdk, model, final_msg, otel_logger)
+        if exc and exc[0] is not None:
+            span.set_attribute("error.type", exc[0].__name__)
+            span.set_status(StatusCode.ERROR, str(exc[1]))
+            span.record_exception(exc[1])
+        else:
+            span.set_status(StatusCode.OK)
+
+    _safe(body, site="anthropic.stream.finish")
+    _safe(span.end, site="anthropic.stream.end")
+
+
+class _TracedStreamManager:
+    """Wraps a sync Anthropic ``MessageStreamManager`` so the chat span ends
+    exactly once when the customer's ``with`` block exits (the only guaranteed
+    single termination point), without making the span the ambient current
+    context across iteration."""
+
+    def __init__(self, inner: Any, span: trace.Span, sdk: "StructSDK", model: str, otel_logger: Any) -> None:
+        self._inner = inner
+        self._stream: Any = None
+        self._ended = False
+        # Back-compat: downstream code may read these stashed attrs.
+        self._struct_span = span
+        self._struct_sdk = sdk
+        self._struct_model = model
+        self._struct_logger = otel_logger
+
+    def __enter__(self) -> Any:
+        # Anthropic does request setup on enter, so __enter__ can raise
+        # (auth/connection). If it does, __exit__ never runs — end the span here
+        # or it leaks unexported. Re-raise so the customer still sees their error.
+        try:
+            self._stream = self._inner.__enter__()
+        except BaseException as e:
+            self._finish_once((type(e), e, e.__traceback__))
+            raise
+        return self._stream
+
+    def __exit__(self, *exc: Any) -> Any:
+        try:
+            return self._inner.__exit__(*exc)
+        finally:
+            self._finish_once(exc)
+
+    def _finish_once(self, exc: Any) -> None:
+        if not self._ended:
+            self._ended = True
+            _finish_stream_span(
+                self._struct_span, self._stream, self._struct_sdk,
+                self._struct_model, self._struct_logger, exc,
+            )
+
+    def __getattr__(self, name: str) -> Any:
+        # Delegate unknown attributes to the wrapped manager (e.g. .text_stream).
+        return getattr(object.__getattribute__(self, "_inner"), name)
+
+
+class _TracedAsyncStreamManager:
+    """Async twin of ``_TracedStreamManager``."""
+
+    def __init__(self, inner: Any, span: trace.Span, sdk: "StructSDK", model: str, otel_logger: Any) -> None:
+        self._inner = inner
+        self._stream: Any = None
+        self._ended = False
+        self._struct_span = span
+        self._struct_sdk = sdk
+        self._struct_model = model
+        self._struct_logger = otel_logger
+
+    async def __aenter__(self) -> Any:
+        # See _TracedStreamManager.__enter__: a failed enter must still end the
+        # span (it would otherwise leak unexported), then re-raise.
+        try:
+            self._stream = await self._inner.__aenter__()
+        except BaseException as e:
+            self._finish_once((type(e), e, e.__traceback__))
+            raise
+        return self._stream
+
+    async def __aexit__(self, *exc: Any) -> Any:
+        try:
+            return await self._inner.__aexit__(*exc)
+        finally:
+            self._finish_once(exc)
+
+    def _finish_once(self, exc: Any) -> None:
+        if not self._ended:
+            self._ended = True
+            _finish_stream_span(
+                self._struct_span, self._stream, self._struct_sdk,
+                self._struct_model, self._struct_logger, exc,
+            )
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(object.__getattribute__(self, "_inner"), name)
+
+
 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.
+    The returned manager is wrapped in ``_TracedStreamManager`` /
+    ``_TracedAsyncStreamManager`` so the ``chat`` span ENDS exactly once when the
+    customer's ``with``/``async with`` block exits, with response attributes
+    populated from the accumulated final message (best-effort). The span is never
+    made the ambient current context across iteration — there is no token to
+    detach on a foreign task. (Pre-fix this wrapper only stashed the span and
+    never ended it, dropping every streaming chat from telemetry.)
     """
     if is_async:
+        # NOTE: Anthropic's async ``messages.stream()`` is a SYNC method that
+        # returns an ``AsyncMessageStreamManager`` — customers write
+        # ``async with client.messages.stream(...) as s:`` WITHOUT awaiting the
+        # call. So this wrapper must be SYNC and return the manager directly
+        # (the async work lives in the manager's __aenter__/__aexit__). Making it
+        # ``async def`` would return a coroutine and break ``async with``.
         @functools.wraps(original)
-        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
             from struct_sdk.core import _safe, _current_session_id, is_genai_suppressed
             model = kwargs.get("model", "unknown")
 
             # Suppression path: a framework layer (LangChain handler) already
             # owns the chat span. Don't create a duplicate; pass through.
             if is_genai_suppressed():
-                return await original(*args, **kwargs) if _is_coroutine(original) else original(*args, **kwargs)
+                return original(*args, **kwargs)
 
             span: Optional[trace.Span] = None
 
@@ -340,18 +461,19 @@ def _wrap_stream(original: Any, tracer: trace.Tracer, sdk: StructSDK, otel_logge
 
                 _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)
+            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]
+            if span is None:
+                return stream_manager
+            # Wrap so the chat span ENDS exactly once on block exit (was leaked).
+            result: Any = stream_manager
 
-                _safe(stash_attrs, site="anthropic.stream.stash_attrs")
+            def wrap_mgr() -> None:
+                nonlocal result
+                result = _TracedAsyncStreamManager(stream_manager, span, sdk, model, otel_logger)
 
-            return stream_manager
+            _safe(wrap_mgr, site="anthropic.stream.wrap_async")
+            return result
     else:
         @functools.wraps(original)
         def wrapper(*args: Any, **kwargs: Any) -> Any:
@@ -392,16 +514,17 @@ def _wrap_stream(original: Any, tracer: trace.Tracer, sdk: StructSDK, otel_logge
 
             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]
+            if span is None:
+                return stream_manager
+            # Wrap so the chat span ENDS exactly once on block exit (was leaked).
+            result: Any = stream_manager
 
-                _safe(stash_attrs, site="anthropic.stream.stash_attrs")
+            def wrap_mgr() -> None:
+                nonlocal result
+                result = _TracedStreamManager(stream_manager, span, sdk, model, otel_logger)
 
-            return stream_manager
+            _safe(wrap_mgr, site="anthropic.stream.wrap_sync")
+            return result
 
     wrapper.__struct_wrapped__ = True  # type: ignore[attr-defined]
     wrapper.__struct_original__ = original  # type: ignore[attr-defined]
@@ -973,8 +1096,3 @@ def _safe_json(obj: Any) -> str:
         return _truncate_and_serialize(obj)
     except Exception:
         return "[]"
-
-
-def _is_coroutine(fn: Any) -> bool:
-    import asyncio
-    return asyncio.iscoroutinefunction(fn)

{struct_sdk-0.2.8 → struct_sdk-0.2.10}/src/struct_sdk/core.py

@@ -14,7 +14,6 @@ import functools
 import json
 import logging
 import threading
-import uuid
 from enum import Enum
 from typing import Any, Callable, Optional
 from importlib.metadata import version as _pkg_version
@@ -33,6 +32,12 @@ from opentelemetry.sdk.trace.export import BatchSpanProcessor
 from opentelemetry.trace import StatusCode
 
 logger = logging.getLogger("struct_sdk")
+# A library must not configure logging on the host's behalf. Attach a NullHandler
+# to the top-level ``struct_sdk`` logger so that, absent host configuration, the
+# SDK's own records are dropped instead of triggering the "No handlers could be
+# found" fallback. Child loggers (struct_sdk.anthropic, .langchain, ...) propagate
+# here, so one handler covers them all. (Python logging library guidance.)
+logger.addHandler(logging.NullHandler())
 
 try:
     _SDK_VERSION = _pkg_version("struct-sdk")
@@ -96,27 +101,100 @@ def is_genai_suppressed() -> bool:
     return bool(_otel_context.get_value(_GENAI_SUPPRESS_KEY))
 
 
-def suppress_genai_token() -> Token[_OtelContext]:
+def suppress_genai_token() -> "tuple[Token[_OtelContext], Optional[asyncio.Task[Any]]]":
     """Attach the suppression key to the current OTel context.
 
-    Returns an opaque token that MUST be passed to ``reset_genai()`` when the
-    suppression window ends.  Follows the same attach/detach contract as
-    ``opentelemetry.context.attach`` / ``detach``.
+    Returns ``(token, enter_task)`` that MUST be passed to ``reset_genai()`` when
+    the suppression window ends. The suppression window spans TWO LangChain
+    callbacks (``on_chat_model_start`` -> ``on_llm_end``) that LangGraph can
+    schedule on DIFFERENT asyncio tasks, so the enter-task travels with the token
+    for a task-affinity-safe detach.
     """
-    return _otel_context.attach(_otel_context.set_value(_GENAI_SUPPRESS_KEY, True))
+    token = _otel_context.attach(_otel_context.set_value(_GENAI_SUPPRESS_KEY, True))
+    return token, _current_task_or_none()
 
 
-def reset_genai(token: Token[_OtelContext]) -> None:
-    """Detach the suppression key token.
+def reset_genai(pair: "Optional[tuple[Token[_OtelContext], Optional[asyncio.Task[Any]]]]") -> None:
+    """Detach the suppression key — ONLY on the asyncio task it was attached on.
 
-    Tolerant of cross-context detach (e.g. async tasks that detach from a
-    different context than the one that attached): the exception is swallowed
-    so instrumentation never fails the host call.
+    Detaching a token from a foreign task's ``contextvars.Context`` makes
+    ``opentelemetry.context.detach`` raise AND log ``Failed to detach context`` at
+    ERROR *internally, before our try/except runs* — the same spam that bit Fermat
+    via the LangChain suppression path. Skipping the detach cross-task is correct:
+    the foreign context is being torn down anyway. Sync code (no loop) always
+    detaches — it can't hop tasks.
     """
+    if pair is None:
+        return
+    token, enter_task = pair
+    if token is None:
+        return
+    # KNOWN LIMITATION (deliberate — do NOT "fix" by forcing the detach below):
+    # on a cross-task reset we skip the detach, so the task that ATTACHED the key
+    # keeps ``struct.suppress_genai=True`` in its own context. contextvars are
+    # task-isolated, so a foreign task literally cannot reset the entering task's
+    # var — attempting it IS the cross-context detach that raises and re-spams
+    # "Failed to detach context" (the 0.2.8 production breakage). A surviving
+    # entering task that later makes a RAW (non-LangChain) provider call could be
+    # silently suppressed. Accepted: cross-task reset only happens on abnormal
+    # teardown (client disconnect) where that context is abandoned anyway, and the
+    # real SSE shape attaches on an ephemeral pump task that dies. A clean restore
+    # would require abandoning the context-key suppression model — tracked follow-up.
+    if _current_task_or_none() is enter_task:
+        try:
+            _otel_context.detach(token)
+        except Exception:  # noqa: BLE001 — never fail the host
+            pass
+
+
+def _current_task_or_none() -> Optional["asyncio.Task[Any]"]:
     try:
+        return asyncio.current_task()
+    except RuntimeError:  # no running event loop (sync code)
+        return None
+
+
+def _attach_current_span(
+    span: trace.Span,
+) -> tuple[Token[_OtelContext], Optional["asyncio.Task[Any]"]]:
+    """Make ``span`` the current OTel span so children — customer-created raw spans
+    AND nested SDK spans — nest under it (ambient-context honoring, good-citizen
+    behavior). Returns ``(token, enter_task)`` for a later task-safe detach."""
+    token = _otel_context.attach(trace.set_span_in_context(span))
+    return token, _current_task_or_none()
+
+
+def _detach_current_span(
+    token: Optional[Token[_OtelContext]], enter_task: Optional["asyncio.Task[Any]"]
+) -> None:
+    """Detach the OTel context token ONLY when we're on the SAME asyncio task it was
+    attached on.
+
+    A different task has a different ``contextvars.Context``, so
+    ``opentelemetry.context.detach`` would raise AND log ``Failed to detach context``
+    at ERROR *internally, before any guard of ours runs* — exactly the
+    streaming/SSE bug (a generator's ``aclose()`` driven from a foreign task on
+    client disconnect). Skipping the detach there is correct: the foreign context is
+    being torn down anyway and our token belongs to the original context, which is no
+    longer active here. Sync code (no running loop) always detaches — it can't hop
+    tasks. This is what makes ``struct.agent()``/``struct.tool()`` teardown
+    task-affinity-safe while still participating in the ambient OTel stack."""
+    if token is None:
+        return
+    # KNOWN LIMITATION (deliberate — do NOT "fix" by forcing the detach or dropping
+    # the ambient attach): a cross-task exit leaves the ENTERING task with this
+    # (now-ended) span as its ambient current span. contextvars are task-isolated,
+    # so a foreign task cannot reset the entering task's var without the
+    # cross-context detach error ("Failed to detach context" — the 0.2.8 breakage).
+    # If that task survives and creates more spans they parent under the ended span
+    # (a slightly-wrong parent, not corruption). The two "fixes" both regress:
+    # forcing the detach re-spams the ERROR; dropping the ambient attach orphans
+    # customer-created raw OTel spans out of the agent's trace (loses nesting).
+    # Cross-task exit only happens on abnormal teardown (disconnect) where the
+    # entering context is abandoned. Tracked as an architectural follow-up.
+    if _current_task_or_none() is enter_task:
         _otel_context.detach(token)
-    except Exception:  # noqa: BLE001 — cross-context detach is a no-op, never fail the host
-        pass
+
 
 # Registry of patched integrations — prevents double-patching
 _patched_integrations: set[str] = set()
@@ -126,15 +204,21 @@ _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."""
+    """Run fn(); swallow any exception so an SDK fault never reaches the host call.
+
+    Self-faults are logged at DEBUG ONLY — a telemetry SDK must stay silent at
+    WARN+; the whole point of fault isolation is invisibility, and a WARN with a
+    traceback for an error we deliberately swallow is alarming noise. The first
+    failure per site carries the traceback; repeats are terse to avoid DEBUG spam.
+    """
     try:
         fn()
     except Exception:
         if site in _first_failure_logged:
-            logger.debug("Struct SDK suppressed exception at %s", site, exc_info=True)
+            logger.debug("Struct SDK suppressed exception at %s", site)
         else:
             _first_failure_logged.add(site)
-            logger.warning("Struct SDK suppressed exception at %s", site, exc_info=True)
+            logger.debug("Struct SDK suppressed exception at %s", site, exc_info=True)
 
 
 class StructSDK:
@@ -308,7 +392,7 @@ class StructSDK:
         return self._tracer_provider.get_tracer(name, _SDK_VERSION)
 
     def get_logger(self, name: str = "struct-sdk") -> Any:
-        """Get an OTel logger from our isolated provider (for gen_ai log events)."""
+        """Get an OTel logger from our isolated provider."""
         if self._logger_provider is None:
             raise RuntimeError("Call struct.init() before using the SDK")
         return self._logger_provider.get_logger(name)
@@ -491,7 +575,8 @@ class _AgentContext:
         self._version = version
         self._metadata = metadata
         self._span: Optional[trace.Span] = None
-        self._ctx_manager: Optional[Any] = None
+        self._otel_token: Optional[Token[_OtelContext]] = None
+        self._enter_task: Optional["asyncio.Task[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
@@ -551,8 +636,12 @@ class _AgentContext:
                 # No explicit id → inherit the enclosing agent's session (inline).
                 self._session_id = enclosing_session_id
             else:
-                # No ambient context → mint a fresh id for this root agent.
-                self._session_id = str(uuid.uuid4())
+                # No explicit id AND no ambient session → leave the run
+                # SESSION-LESS (do NOT fabricate a uuid). The backend groups
+                # session-less spans by trace; a per-run uuid would render each as
+                # its own degenerate "session". (Spec: never fabricate
+                # gen_ai.conversation.id.)
+                self._session_id = ""
 
             # ── Break-out detection ──────────────────────────────────────────
             # Condition: caller supplied an EXPLICIT id AND it differs from the
@@ -631,8 +720,9 @@ class _AgentContext:
             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)
+            # redundant session.id. Omitted when session-less (never fabricated).
+            if self._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.
             # For break-out agents: the parent is the enclosing agent.
             # For inline nested agents: parent is the same session (same id).
@@ -658,16 +748,17 @@ class _AgentContext:
                 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.
+            # Make this the current OTel span so children (incl. customer raw
+            # spans) nest under it. Detach is TASK-SAFE on exit (see
+            # _detach_current_span) — never the foreign-task detach that logged
+            # "Failed to detach context".
+            self._otel_token, self._enter_task = _attach_current_span(self._span)
             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)
+            # Set context vars so child spans inherit session context. A
+            # session-less run propagates None (not ""), so descendants stay
+            # session-less rather than inheriting an empty string.
+            self._session_token = _current_session_id.set(self._session_id or None)
+            self._conversation_token = _current_conversation_id.set(self._session_id or None)
             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.
@@ -710,13 +801,11 @@ class _AgentContext:
                 _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
+            # Detach the OTel context (task-safe) if we attached.
+            if entered and self._otel_token is not None:
+                _safe(lambda: _detach_current_span(self._otel_token, self._enter_task),
+                      site="agent.start_span.rollback_detach")
+            self._otel_token = None
             # Then end the span so it isn't leaked unended.
             span = self._span
             if span is not None:
@@ -759,9 +848,10 @@ class _AgentContext:
                 _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")
+        if self._otel_token is not None:
+            _safe(lambda: _detach_current_span(self._otel_token, self._enter_task),
+                  site="agent.end_span.detach")
+            self._otel_token = None
 
     def __enter__(self) -> "_AgentContext":
         self._start_span()
@@ -794,7 +884,8 @@ class _ToolContext:
         self._name = name
         self._tool_call_id = tool_call_id
         self._span: Optional[trace.Span] = None
-        self._ctx_manager: Optional[Any] = None
+        self._otel_token: Optional[Token[_OtelContext]] = None
+        self._enter_task: Optional["asyncio.Task[Any]"] = None
         self._result: Any = None
 
     def __call__(self, fn: Any) -> Any:
@@ -862,23 +953,19 @@ class _ToolContext:
             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.
+            # Current OTel span for children; task-safe detach on exit.
+            self._otel_token, self._enter_task = _attach_current_span(self._span)
             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
+            # Body raised partway. Detach (task-safe) if attached, end the span if
+            # started, then drop references so _end_span sees a clean view.
+            if entered and self._otel_token is not None:
+                _safe(lambda: _detach_current_span(self._otel_token, self._enter_task),
+                      site="tool.start_span.rollback_detach")
+            self._otel_token = None
             span = self._span
             if span is not None:
                 _safe(span.end, site="tool.start_span.rollback_span_end")
@@ -898,9 +985,10 @@ class _ToolContext:
                 _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")
+        if self._otel_token is not None:
+            _safe(lambda: _detach_current_span(self._otel_token, self._enter_task),
+                  site="tool.end_span.detach")
+            self._otel_token = None
 
     def _set_arguments(self, kwargs: dict) -> None:
         """Set tool call arguments (opt-in)."""

{struct_sdk-0.2.8 → struct_sdk-0.2.10}/src/struct_sdk/langchain.py

@@ -393,7 +393,13 @@ def _is_agent_chain(
         if isinstance(lg_node, str) and lg_node and lg_node == run_name:
             return False
     if run_name:
-        if run_name in _INTERNAL_RUN_NAMES:
+        # LangChain names parametrized runnables ``Base<...>`` — e.g.
+        # ``RunnableParallel<raw>`` and ``RunnableAssign<parsed,parsing_error>``
+        # from ``with_structured_output(include_raw=True)``. Strip the ``<...>``
+        # so the base class matches the denylist instead of falling through to
+        # the user-named-chain promotion below (the Fermat phantom-agent bug).
+        base_name = run_name.split("<", 1)[0]
+        if base_name in _INTERNAL_RUN_NAMES:
             return False
         if any(run_name.startswith(p) for p in _INTERNAL_RUN_NAME_PREFIXES):
             return False
@@ -401,6 +407,31 @@ def _is_agent_chain(
     return False
 
 
+def _forced_tool_name(invocation: Optional[dict[str, Any]]) -> Optional[str]:
+    """Return the tool name a forced ``tool_choice`` pins, else None.
+
+    ``with_structured_output`` forces the model to call a single schema-tool, so
+    a tool_call matching this name is structured output (a forced extraction
+    LangChain parses into the Pydantic object) — never executed, so it must not
+    be treated as an agentic tool call. Grounded in a real
+    ``ChatAnthropic.with_structured_output`` probe:
+      Anthropic: ``tool_choice = {"type": "tool", "name": X}``
+      OpenAI:    ``tool_choice = {"type": "function", "function": {"name": X}}``
+    """
+    if not isinstance(invocation, dict):
+        return None
+    tc = invocation.get("tool_choice")
+    if not isinstance(tc, dict):
+        return None
+    if tc.get("type") == "tool" and isinstance(tc.get("name"), str):
+        return tc["name"]
+    if tc.get("type") == "function":
+        fn = tc.get("function")
+        if isinstance(fn, dict) and isinstance(fn.get("name"), str):
+            return fn["name"]
+    return None
+
+
 # ---------------------------------------------------------------------------
 # Message conversion helpers — LangChain message → OTel GenAI parts
 # ---------------------------------------------------------------------------
@@ -718,7 +749,8 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
             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 session_id:
+                span.set_attribute("gen_ai.conversation.id", session_id)
             # Always set parent_session_id when there's a parent agent — even
             # if it matches our own session_id (which happens when the SDK's
             # ambient ``_current_session_id`` propagates through nested
@@ -855,7 +887,8 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
             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)
+            if session_id:
+                span.set_attribute("gen_ai.conversation.id", session_id)
 
             _set_request_attrs(span, invocation)
 
@@ -895,6 +928,7 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
             nearest_agent_span=self._inherited_agent_span(parent_key),
             kind="llm",
             enrich_token=enrich_token,
+            forced_tool_name=_forced_tool_name(invocation),
         )
 
     def on_llm_start(
@@ -970,9 +1004,23 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
             tool_calls = getattr(message, "tool_calls", None) or []
             if not tool_calls:
                 return
+            # A tool_call matching a forced tool_choice is structured output
+            # (with_structured_output) — never executed, so it must NOT become a
+            # pending tool-call (that would dangle in the waterfall as a tool with
+            # no execution). Mark the chat output as structured (json) instead.
+            forced = r.forced_tool_name
+            real = []
+            structured_seen = False
+            for tc in tool_calls:
+                if forced and tc.get("name") == forced:
+                    structured_seen = True
+                    continue
+                real.append(tc)
+            if structured_seen:
+                span.set_attribute("gen_ai.output.type", "json")
             pairs = [
                 (tc.get("name", ""), tc.get("id", ""))
-                for tc in tool_calls
+                for tc in real
                 if tc.get("name") and tc.get("id")
             ]
             if pairs:
@@ -1080,7 +1128,8 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
             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 session_id:
+                span.set_attribute("gen_ai.conversation.id", session_id)
 
             if self._sdk.capture_content and input_str:
                 span.set_attribute(
@@ -1214,7 +1263,8 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
             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 session_id:
+                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])
 
@@ -1337,8 +1387,14 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
         self,
         parent_run_id: Optional[str],
         metadata: Optional[dict[str, Any]],
-    ) -> str:
-        """For chat/tool/retriever spans — inherit from parent so everything rolls up."""
+    ) -> Optional[str]:
+        """For chat/tool/retriever spans — inherit from parent so everything rolls up.
+
+        Returns None when there is no session signal (no parent, no thread_id, no
+        ambient struct.agent) — the span is left session-less so the backend groups
+        it by trace, rather than fabricating a per-run uuid that renders as its own
+        degenerate session (Fermat prefetch-.ainvoke() orphan bug; spec: never
+        fabricate gen_ai.conversation.id)."""
         if parent_run_id:
             p = self._runs.get(parent_run_id)
             if p and p.session_id:
@@ -1350,13 +1406,13 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
         ambient = _current_session_id.get(None)
         if ambient:
             return ambient
-        return str(uuid.uuid4())
+        return None
 
     def _resolve_agent_session_id(
         self,
         metadata: Optional[dict[str, Any]],
         parent_agent_session_id: Optional[str] = None,
-    ) -> str:
+    ) -> Optional[str]:
         """Agent spans INHERIT the nearest-agent ancestor's conversation id so a
         whole run shares one id. A locally-supplied thread_id is preserved by the
         caller as ``struct.agent.thread_id`` (non-grouping) — it never splits the run.
@@ -1370,6 +1426,9 @@ class StructCallbackHandler(BaseCallbackHandler):  # type: ignore[misc]
         ambient = _current_session_id.get(None)
         if ambient:
             return ambient
+        # A standalone agent run with no session signal is still a coherent
+        # session; mint a per-run id so its sub-spans group. (Orphan leaf
+        # tool/chat spans stay session-less — see _resolve_session_id.)
         return str(uuid.uuid4())
 
 
@@ -1394,6 +1453,10 @@ class _RunState:
         # provider-SDK instrumentations (anthropic, openai, etc.)
         # "a framework layer owns the chat span — skip creating a duplicate."
         "enrich_token",
+        # On chat runs: the tool name a forced ``tool_choice`` pins (i.e.
+        # ``with_structured_output``). A tool_call matching it is structured
+        # output, not an agentic tool call. See _forced_tool_name.
+        "forced_tool_name",
     )
 
     def __init__(
@@ -1401,11 +1464,12 @@ class _RunState:
         *,
         span: Optional[trace.Span],
         effective_parent_span: Optional[trace.Span],
-        session_id: str,
+        session_id: Optional[str],
         nearest_agent_session_id: Optional[str],
         nearest_agent_span: Optional[trace.Span],
         kind: str,
         enrich_token: Any = None,
+        forced_tool_name: Optional[str] = None,
     ) -> None:
         self.span = span
         self.effective_parent_span = effective_parent_span
@@ -1414,6 +1478,7 @@ class _RunState:
         self.nearest_agent_span = nearest_agent_span
         self.kind = kind
         self.enrich_token = enrich_token
+        self.forced_tool_name = forced_tool_name
 
 
 class _ParentInfo:
@@ -1464,7 +1529,7 @@ def _set_llm_response_attrs(
     otel_logger: Any,
     message: Any,
     provider: Optional[str],
-    session_id: str,
+    session_id: Optional[str],
 ) -> None:
     usage = getattr(message, "usage_metadata", None) or {}
     if isinstance(usage, dict):
@@ -1596,7 +1661,7 @@ def _emit_message_events(
     otel_logger: Any,
     messages: list[Any],
     provider: str,
-    session_id: str,
+    session_id: Optional[str],
     span: Optional[trace.Span] = None,
 ) -> None:
     try:
@@ -1619,8 +1684,11 @@ def _emit_message_events(
                 "body": payload,
                 "gen_ai.provider.name": provider,
                 "gen_ai.message.index": idx,
-                "gen_ai.conversation.id": session_id,
             }
+            # Omit when session-less — OTel attribute values must be non-null,
+            # and we never fabricate a conversation.id for orphan runs.
+            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,
@@ -1638,7 +1706,7 @@ def _emit_choice_event(
     otel_logger: Any,
     message: Any,
     provider: str,
-    session_id: str,
+    session_id: Optional[str],
     span: Optional[trace.Span] = None,
 ) -> None:
     try:
@@ -1660,8 +1728,11 @@ def _emit_choice_event(
             "event.name": event_name,
             "body": payload,
             "gen_ai.provider.name": provider,
-            "gen_ai.conversation.id": session_id,
         }
+        # Omit when session-less — OTel attribute values must be non-null, and we
+        # never fabricate a conversation.id for orphan runs.
+        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,