struct-sdk 0.2.0__tar.gz → 0.2.2__tar.gz

{struct_sdk-0.2.0 → struct_sdk-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: struct-sdk
-Version: 0.2.0
+Version: 0.2.2
 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
@@ -108,7 +108,7 @@ async with struct.agent(name="checkout"):
 | `langchain_core` `BaseChatModel` | `chat {model}` | Skipped when an underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic` → a single span). |
 | `langchain_core` `BaseTool` | `execute_tool {name}` | `tool_call_id` extracted from the LangChain ToolCall when present. |
 | `langchain_core` `BaseRetriever` | `retrieval {name}` | |
-| `langgraph` `Pregel` | `invoke_agent {name}` | Covers `create_react_agent` and custom graphs. `thread_id` → `gen_ai.conversation.id`. |
+| `langgraph` `Pregel` | `invoke_agent {name}` | Covers `create_react_agent`, `langchain.agents.create_agent`, and custom graphs. Reads conversation id from any of: `configurable.thread_id` (LangGraph canonical), or `metadata.{thread_id, session_id, conversation_id}` (LangSmith conventions). For multi-turn HTTP-style threading, wrap your entry point in [`struct.agent(session_id=conv_id)`](#recommended-pattern-wrap-langchain-entry-points-in-structagent) — that's the struct-native replacement for `ls.tracing_context(parent=run_tree)`. |
 
 ## Framework integration
 
@@ -156,6 +156,40 @@ from langgraph.prebuilt import create_react_agent
 # execute_tool spans. BaseRetriever.invoke gets retrieval spans.
 ```
 
+##### Recommended pattern: wrap LangChain entry points in `struct.agent`
+
+For multi-turn HTTP-style usage (every request continues the same
+conversation), wrap your request handler in
+`struct.agent(session_id=conversation_id)`. This is the struct-native
+replacement for `with ls.tracing_context(parent=run_tree):` and gives
+you two things you can't get from `configurable.thread_id` alone:
+
+1. **Threading without per-call config plumbing.** Every nested
+   LangChain call inherits the conversation id via the SDK's ambient
+   contextvar — you don't have to ensure each `compiled_graph.ainvoke`
+   gets `thread_id` on its config.
+2. **One trace per request.** `struct.agent` creates a parent OTel span
+   so all the LangChain work for the request nests under one trace
+   (clean tree, "Subagents" / "Spawned by" UI links work). Without it,
+   each `.invoke()` becomes its own root trace, and the UI's session
+   list shows a non-deterministic agent name (`omni_agent`,
+   `LangGraph`, the first sub-agent it sees…).
+
+Migrating from LangSmith:
+
+```python
+# Before — LangSmith convention, fragments under struct-sdk
+with ls.tracing_context(parent=run_tree):
+    await orchestrator.ainvoke(inputs, config=config)
+
+# After — struct-native, threads correctly, no langsmith dep
+async with struct.agent(session_id=conversation_id):
+    await orchestrator.ainvoke(inputs, config=config)
+```
+
+Also works as a sync context manager (`with struct.agent(...)`) for
+non-async handlers.
+
 ### LLM SDKs used directly — manual agent + tool scopes required
 
 When you call an LLM SDK directly (no agent framework wrapping it), only
@@ -269,8 +303,19 @@ async def run_checkout(order_id: str):
     return await charge()
 ```
 
-Nested agents are linked to their parent via the
-`struct.agent.parent_session_id` attribute on the inner span.
+Sub-agents (e.g. a `create_agent` graph invoked from inside another
+agent's tool body) record their parent via the
+`struct.agent.parent_session_id` attribute on the inner `invoke_agent`
+span. This powers the UI's "Spawned by" backlink, which works for any
+nested invocation.
+
+The parent's "Subagents" forward list — the inverse direction —
+additionally requires that the nested invoke shares the outer agent's
+trace. This works automatically when the outer tool is built with the
+`@tool` decorator (or any callback-aware wrapping) since the nested
+invoke inherits the parent's run state. Bare `Tool(...)` constructors
+that bypass the callback chain can break the forward link; the
+backlink still renders.
 
 ## Semantic conventions
 

{struct_sdk-0.2.0 → struct_sdk-0.2.2}/README.md

@@ -62,7 +62,7 @@ async with struct.agent(name="checkout"):
 | `langchain_core` `BaseChatModel` | `chat {model}` | Skipped when an underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic` → a single span). |
 | `langchain_core` `BaseTool` | `execute_tool {name}` | `tool_call_id` extracted from the LangChain ToolCall when present. |
 | `langchain_core` `BaseRetriever` | `retrieval {name}` | |
-| `langgraph` `Pregel` | `invoke_agent {name}` | Covers `create_react_agent` and custom graphs. `thread_id` → `gen_ai.conversation.id`. |
+| `langgraph` `Pregel` | `invoke_agent {name}` | Covers `create_react_agent`, `langchain.agents.create_agent`, and custom graphs. Reads conversation id from any of: `configurable.thread_id` (LangGraph canonical), or `metadata.{thread_id, session_id, conversation_id}` (LangSmith conventions). For multi-turn HTTP-style threading, wrap your entry point in [`struct.agent(session_id=conv_id)`](#recommended-pattern-wrap-langchain-entry-points-in-structagent) — that's the struct-native replacement for `ls.tracing_context(parent=run_tree)`. |
 
 ## Framework integration
 
@@ -110,6 +110,40 @@ from langgraph.prebuilt import create_react_agent
 # execute_tool spans. BaseRetriever.invoke gets retrieval spans.
 ```
 
+##### Recommended pattern: wrap LangChain entry points in `struct.agent`
+
+For multi-turn HTTP-style usage (every request continues the same
+conversation), wrap your request handler in
+`struct.agent(session_id=conversation_id)`. This is the struct-native
+replacement for `with ls.tracing_context(parent=run_tree):` and gives
+you two things you can't get from `configurable.thread_id` alone:
+
+1. **Threading without per-call config plumbing.** Every nested
+   LangChain call inherits the conversation id via the SDK's ambient
+   contextvar — you don't have to ensure each `compiled_graph.ainvoke`
+   gets `thread_id` on its config.
+2. **One trace per request.** `struct.agent` creates a parent OTel span
+   so all the LangChain work for the request nests under one trace
+   (clean tree, "Subagents" / "Spawned by" UI links work). Without it,
+   each `.invoke()` becomes its own root trace, and the UI's session
+   list shows a non-deterministic agent name (`omni_agent`,
+   `LangGraph`, the first sub-agent it sees…).
+
+Migrating from LangSmith:
+
+```python
+# Before — LangSmith convention, fragments under struct-sdk
+with ls.tracing_context(parent=run_tree):
+    await orchestrator.ainvoke(inputs, config=config)
+
+# After — struct-native, threads correctly, no langsmith dep
+async with struct.agent(session_id=conversation_id):
+    await orchestrator.ainvoke(inputs, config=config)
+```
+
+Also works as a sync context manager (`with struct.agent(...)`) for
+non-async handlers.
+
 ### LLM SDKs used directly — manual agent + tool scopes required
 
 When you call an LLM SDK directly (no agent framework wrapping it), only
@@ -223,8 +257,19 @@ async def run_checkout(order_id: str):
     return await charge()
 ```
 
-Nested agents are linked to their parent via the
-`struct.agent.parent_session_id` attribute on the inner span.
+Sub-agents (e.g. a `create_agent` graph invoked from inside another
+agent's tool body) record their parent via the
+`struct.agent.parent_session_id` attribute on the inner `invoke_agent`
+span. This powers the UI's "Spawned by" backlink, which works for any
+nested invocation.
+
+The parent's "Subagents" forward list — the inverse direction —
+additionally requires that the nested invoke shares the outer agent's
+trace. This works automatically when the outer tool is built with the
+`@tool` decorator (or any callback-aware wrapping) since the nested
+invoke inherits the parent's run state. Bare `Tool(...)` constructors
+that bypass the callback chain can break the forward link; the
+backlink still renders.
 
 ## Semantic conventions
 

{struct_sdk-0.2.0 → struct_sdk-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.2.0"
+version = "0.2.2"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"

{struct_sdk-0.2.0 → struct_sdk-0.2.2}/src/struct_sdk/anthropic.py

@@ -142,8 +142,16 @@ def _create_common(
         try:
             result = yield f, args, kwargs
         except Exception as e:
-            _safe(lambda: host_span.set_attribute("error.type", type(e).__name__),
-                  site="anthropic.create.enrich.error_type")
+            # 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),
@@ -201,12 +209,27 @@ def _create_common(
         try:
             result = yield f, args, kwargs
         except Exception as e:
-            _safe(lambda: span.set_attribute("error.type", type(e).__name__),
-                  site="anthropic.create.error_type")
-            _safe(lambda: span.set_status(StatusCode.ERROR, str(e)),
-                  site="anthropic.create.error_status")
-            _safe(lambda: span.record_exception(e),
-                  site="anthropic.create.record_exception")
+            # Snapshot ``e`` outside the lambdas — ``except X as e`` unbinds
+            # ``e`` at end-of-block, and ruff (correctly) flags closures that
+            # reference it. The lambdas run synchronously inside the except
+            # via ``_safe``, so this is mechanically equivalent — just legible
+            # to static analysis. ``type(exc).__name__`` is cheap and won't
+            # raise; ``str(exc)`` runs inside ``_safe`` so a broken
+            # ``__str__`` can't mask the original exception we're re-raising.
+            exc = e
+            err_type = type(exc).__name__
+            _safe(
+                lambda: span.set_attribute("error.type", err_type),
+                site="anthropic.create.error_type",
+            )
+            _safe(
+                lambda: span.set_status(StatusCode.ERROR, str(exc)),
+                site="anthropic.create.error_status",
+            )
+            _safe(
+                lambda: span.record_exception(exc),
+                site="anthropic.create.record_exception",
+            )
             raise
         _safe(lambda: _set_response_attrs(span, sdk, model, result, otel_logger),
               site="anthropic.create.set_response_attrs")