struct-sdk 0.2.5__tar.gz → 0.2.9__tar.gz

{struct_sdk-0.2.5 → struct_sdk-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: struct-sdk
-Version: 0.2.5
+Version: 0.2.9
 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
@@ -87,16 +87,18 @@ struct.init(
 import anthropic
 client = anthropic.AsyncAnthropic()
 
+# Decorate each tool — auto-captures arguments + result + tool_call_id.
+@struct.tool()
+async def search(query: str):
+    ...
+
 async with struct.agent(name="checkout"):
     msg = await client.messages.create(
         model="claude-3-5-sonnet-20241022",
         max_tokens=1024,
         messages=[{"role": "user", "content": "plan my checkout flow"}],
     )
-
-    # tool_call_id is auto-filled from the preceding Anthropic response
-    async with struct.tool(name="search"):
-        result = await search(msg)
+    result = await search(query="...")
 ```
 
 ## What gets traced
@@ -207,6 +209,14 @@ struct.init(ingest_key="pk-...", service_name="checkout-agent")
 import anthropic
 client = anthropic.AsyncAnthropic()
 
+# Recommended: define each tool as a function and DECORATE it. The decorator
+# auto-captures the tool's arguments + result on the execute_tool span and
+# auto-fills tool_call_id from the preceding Anthropic response — no manual
+# bookkeeping.
+@struct.tool()
+async def search(query: str):
+    ...
+
 # Required: wrap the agent loop yourself.
 async with struct.agent(name="checkout"):
     msg = await client.messages.create(
@@ -214,16 +224,60 @@ async with struct.agent(name="checkout"):
         max_tokens=1024,
         messages=[...],
     )
+    # Dispatching a decorated tool inside the agent emits a fully-populated
+    # execute_tool span (name, id, arguments, result):
+    result = await search(query="...")
+```
 
-    # Required: wrap each tool execution.
-    # tool_call_id is auto-filled from the preceding Anthropic response.
-    async with struct.tool(name="search"):
-        result = await search(...)
+For **dynamic dispatch** (the LLM picks a tool from a registry at runtime),
+apply the decorator at runtime — still automatic, just bind the name when you
+wrap the callable:
+
+```python
+registry = {t.name: struct.tool(name=t.name)(t.execute) for t in tools}
+result = await registry[block.name](**block.input)   # arguments + result captured
 ```
 
+> `struct.tool()` can also be used as a context manager
+> (`async with struct.tool(name=...): ...`) to instrument an arbitrary block of
+> code as a tool span. That form is a **manual escape hatch** — it does NOT
+> auto-capture arguments/result (a `with` block can't see the body's return
+> value), so prefer the decorator for actual tool calls. See
+> [Parallel tool calls](#parallel-tool-calls--pass-tool_call_id-explicitly) for
+> the one runtime value (`tool_call_id`) you must supply under concurrency.
+
 `anthropic.Anthropic`, `anthropic.AsyncAnthropic`, and the bedrock/vertex
 clients are all auto-instrumented for chat spans.
 
+#### Parallel tool calls — pass `tool_call_id` explicitly
+
+When you execute an assistant turn's tool calls **sequentially** — one
+`await` at a time, in the order the `tool_use` blocks appear — `struct.tool()`
+auto-fills `gen_ai.tool.call.id` by matching each span to the next pending
+`tool_use` of the same tool name. Nothing extra to do.
+
+When you execute them **concurrently** (e.g. `asyncio.gather`), that
+name-and-order matching is ambiguous: two `struct.tool(name="search")` spans
+can start in any order, so the auto-fill may attach the wrong id (and thus the
+wrong arguments/result) to a call. In that case **pass `tool_call_id`
+explicitly** from the originating `tool_use` block — an explicit id always
+overrides the auto-linkage:
+
+```python
+async def run_one(block):
+    # The id from THIS block overrides the name/order auto-fill.
+    async with struct.tool(name=block.name, tool_call_id=block.id):
+        return await dispatch(block.name, **block.input)
+
+# Concurrent execution — each tool span still carries the correct id.
+results = await asyncio.gather(*[run_one(b) for b in tool_use_blocks])
+```
+
+Rule of thumb: **serial tool execution → automatic; concurrent tool execution
+→ provide `tool_call_id=` yourself.** (Auto-instrumented frameworks such as
+LangChain read the id from the framework's `ToolCall`, so this only applies
+when you drive the tool loop directly against an LLM SDK.)
+
 #### LangChain `BaseChatModel` (no agent/graph)
 
 If you call `ChatAnthropic.invoke(...)` (or any other `BaseChatModel`)

{struct_sdk-0.2.5 → struct_sdk-0.2.9}/README.md

@@ -41,16 +41,18 @@ struct.init(
 import anthropic
 client = anthropic.AsyncAnthropic()
 
+# Decorate each tool — auto-captures arguments + result + tool_call_id.
+@struct.tool()
+async def search(query: str):
+    ...
+
 async with struct.agent(name="checkout"):
     msg = await client.messages.create(
         model="claude-3-5-sonnet-20241022",
         max_tokens=1024,
         messages=[{"role": "user", "content": "plan my checkout flow"}],
     )
-
-    # tool_call_id is auto-filled from the preceding Anthropic response
-    async with struct.tool(name="search"):
-        result = await search(msg)
+    result = await search(query="...")
 ```
 
 ## What gets traced
@@ -161,6 +163,14 @@ struct.init(ingest_key="pk-...", service_name="checkout-agent")
 import anthropic
 client = anthropic.AsyncAnthropic()
 
+# Recommended: define each tool as a function and DECORATE it. The decorator
+# auto-captures the tool's arguments + result on the execute_tool span and
+# auto-fills tool_call_id from the preceding Anthropic response — no manual
+# bookkeeping.
+@struct.tool()
+async def search(query: str):
+    ...
+
 # Required: wrap the agent loop yourself.
 async with struct.agent(name="checkout"):
     msg = await client.messages.create(
@@ -168,16 +178,60 @@ async with struct.agent(name="checkout"):
         max_tokens=1024,
         messages=[...],
     )
+    # Dispatching a decorated tool inside the agent emits a fully-populated
+    # execute_tool span (name, id, arguments, result):
+    result = await search(query="...")
+```
 
-    # Required: wrap each tool execution.
-    # tool_call_id is auto-filled from the preceding Anthropic response.
-    async with struct.tool(name="search"):
-        result = await search(...)
+For **dynamic dispatch** (the LLM picks a tool from a registry at runtime),
+apply the decorator at runtime — still automatic, just bind the name when you
+wrap the callable:
+
+```python
+registry = {t.name: struct.tool(name=t.name)(t.execute) for t in tools}
+result = await registry[block.name](**block.input)   # arguments + result captured
 ```
 
+> `struct.tool()` can also be used as a context manager
+> (`async with struct.tool(name=...): ...`) to instrument an arbitrary block of
+> code as a tool span. That form is a **manual escape hatch** — it does NOT
+> auto-capture arguments/result (a `with` block can't see the body's return
+> value), so prefer the decorator for actual tool calls. See
+> [Parallel tool calls](#parallel-tool-calls--pass-tool_call_id-explicitly) for
+> the one runtime value (`tool_call_id`) you must supply under concurrency.
+
 `anthropic.Anthropic`, `anthropic.AsyncAnthropic`, and the bedrock/vertex
 clients are all auto-instrumented for chat spans.
 
+#### Parallel tool calls — pass `tool_call_id` explicitly
+
+When you execute an assistant turn's tool calls **sequentially** — one
+`await` at a time, in the order the `tool_use` blocks appear — `struct.tool()`
+auto-fills `gen_ai.tool.call.id` by matching each span to the next pending
+`tool_use` of the same tool name. Nothing extra to do.
+
+When you execute them **concurrently** (e.g. `asyncio.gather`), that
+name-and-order matching is ambiguous: two `struct.tool(name="search")` spans
+can start in any order, so the auto-fill may attach the wrong id (and thus the
+wrong arguments/result) to a call. In that case **pass `tool_call_id`
+explicitly** from the originating `tool_use` block — an explicit id always
+overrides the auto-linkage:
+
+```python
+async def run_one(block):
+    # The id from THIS block overrides the name/order auto-fill.
+    async with struct.tool(name=block.name, tool_call_id=block.id):
+        return await dispatch(block.name, **block.input)
+
+# Concurrent execution — each tool span still carries the correct id.
+results = await asyncio.gather(*[run_one(b) for b in tool_use_blocks])
+```
+
+Rule of thumb: **serial tool execution → automatic; concurrent tool execution
+→ provide `tool_call_id=` yourself.** (Auto-instrumented frameworks such as
+LangChain read the id from the framework's `ToolCall`, so this only applies
+when you drive the tool loop directly against an LLM SDK.)
+
 #### LangChain `BaseChatModel` (no agent/graph)
 
 If you call `ChatAnthropic.invoke(...)` (or any other `BaseChatModel`)

{struct_sdk-0.2.5 → struct_sdk-0.2.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.2.5"
+version = "0.2.9"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -72,6 +72,11 @@ override-dependencies = [
     "starlette>=1.3.1",
 ]
 
+[tool.pytest.ini_options]
+markers = [
+    "integration: real-model integration tests (requires ANTHROPIC_API_KEY / OPENAI_API_KEY; skipped in default CI)",
+]
+
 [tool.mypy]
 [[tool.mypy.overrides]]
 module = ["anthropic", "anthropic.*", "claude_agent_sdk", "claude_agent_sdk.*", "langchain_core", "langchain_core.*", "langchain", "langchain.*", "langgraph", "langgraph.*"]

{struct_sdk-0.2.5 → struct_sdk-0.2.9}/src/struct_sdk/anthropic.py

@@ -119,44 +119,23 @@ def _create_common(
 
     Two paths:
 
-    1. **Enrich** — when ``_current_langchain_chat_span`` is set, this call
-       is happening underneath a LangChain handler that's already created
-       a ``chat <model>`` span. We do NOT create our own span (that's the
-       duplicate-Anthropic-spans issue). Instead we attach HTTP-layer
-       attrs (the real provider msg_id, exact response_model, usage,
-       finish_reasons, error info on failure) onto the langchain span.
-       Pre-call attrs are skipped — LangChain already set them.
-
-    2. **Standalone** — no LangChain in the picture. Create our own span
-       and set the full attribute set as before.
+    1. **Suppressed** — when ``is_genai_suppressed()`` is True, a framework
+       layer (e.g. the LangChain callback handler) already owns a ``chat
+       <model>`` span for this call. We run the original call to completion
+       and emit NO span — avoiding the duplicate-Anthropic-spans problem.
+
+    2. **Standalone** — no framework suppression in the picture. Create our
+       own span and set the full attribute set as before.
     """
-    from struct_sdk.core import _safe, _current_langchain_chat_span
+    from struct_sdk.core import _safe, is_genai_suppressed
 
     model = kwargs.get("model", "unknown")
 
-    # Enrich path: a LangChain handler upstream already created a ``chat
-    # <model>`` span for this call. Attach Anthropic HTTP-layer detail to it
-    # without creating a duplicate span.
-    host_span = _current_langchain_chat_span.get(None)
-    if host_span is not None:
-        try:
-            result = yield f, args, kwargs
-        except Exception as e:
-            # Capture the type name OUTSIDE the lambda — ``except X as e``
-            # binds ``e`` only for the duration of the except block, but
-            # ``_safe`` is opaque to static analysis (ruff flags F841 +
-            # F821 thinking the lambda outlives the binding). Snapshotting
-            # to a local makes the closure capture trivially correct.
-            err_type = type(e).__name__
-            _safe(
-                lambda: host_span.set_attribute("error.type", err_type),
-                site="anthropic.create.enrich.error_type",
-            )
-            raise
-        _safe(
-            lambda: _set_response_attrs(host_span, sdk, model, result, otel_logger),
-            site="anthropic.create.enrich.set_response_attrs",
-        )
+    # Suppression path: a framework layer (LangChain handler) already owns the
+    # ``chat <model>`` span for this call. Run the original call to completion
+    # and emit NO span — the framework's span covers this invocation.
+    if is_genai_suppressed():
+        result = yield f, args, kwargs
         return result  # noqa: B901
 
     with tracer.start_as_current_span(
@@ -311,30 +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:
-            from struct_sdk.core import _safe, _current_session_id, _current_langchain_chat_span
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            from struct_sdk.core import _safe, _current_session_id, is_genai_suppressed
             model = kwargs.get("model", "unknown")
 
-            # Enrich path: a LangChain handler upstream already owns a chat
-            # span for this call. Don't create a duplicate; just pass through.
-            # (Stream end-handling will set response attrs on the host span
-            # when the LangChain handler's on_llm_end fires.)
-            if _current_langchain_chat_span.get(None) is not None:
-                return await original(*args, **kwargs) if _is_coroutine(original) else original(*args, **kwargs)
+            # Suppression path: a framework layer (LangChain handler) already
+            # owns the chat span. Don't create a duplicate; pass through.
+            if is_genai_suppressed():
+                return original(*args, **kwargs)
 
             span: Optional[trace.Span] = None
 
@@ -363,27 +461,28 @@ 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:
-            from struct_sdk.core import _safe, _current_session_id, _current_langchain_chat_span
+            from struct_sdk.core import _safe, _current_session_id, is_genai_suppressed
             model = kwargs.get("model", "unknown")
 
-            # Enrich path: a LangChain handler upstream already owns a chat
-            # span for this call. Don't create a duplicate; just pass through.
-            if _current_langchain_chat_span.get(None) is not None:
+            # Suppression path: a framework layer (LangChain handler) already
+            # owns the chat span. Don't create a duplicate; pass through.
+            if is_genai_suppressed():
                 return original(*args, **kwargs)
 
             span: Optional[trace.Span] = None
@@ -415,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]
@@ -552,7 +652,7 @@ def _emit_message_events(
       etc.) — human-readable signal.
     - ``attributes['body']`` (log record attribute): the JSON-serialised
       structured payload ``{"role": ..., "parts": [...]}``.
-    - Other attributes: ``event.name``, ``gen_ai.system``,
+    - Other attributes: ``event.name``, ``gen_ai.provider.name``,
       ``gen_ai.message.index``, ``gen_ai.conversation.id``.
 
     ``span`` — if provided, its span context is used for the LogRecord's
@@ -585,7 +685,7 @@ def _emit_message_events(
             attrs: dict[str, Any] = {
                 "event.name": event_name,
                 "body": payload,
-                "gen_ai.system": "anthropic",
+                "gen_ai.provider.name": "anthropic",
                 "gen_ai.message.index": msg_index,
             }
             if session_id:
@@ -618,7 +718,7 @@ def _emit_message_events(
             attrs = {
                 "event.name": event_name,
                 "body": payload,
-                "gen_ai.system": "anthropic",
+                "gen_ai.provider.name": "anthropic",
                 "gen_ai.message.index": msg_index,
             }
             if session_id:
@@ -696,7 +796,7 @@ def _emit_choice_event(
         attrs: dict[str, Any] = {
             "event.name": event_name,
             "body": payload,
-            "gen_ai.system": "anthropic",
+            "gen_ai.provider.name": "anthropic",
         }
         if session_id:
             attrs["gen_ai.conversation.id"] = session_id
@@ -996,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)