struct-sdk 0.2.15__tar.gz → 0.2.23__tar.gz

{struct_sdk-0.2.15 → struct_sdk-0.2.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: struct-sdk
-Version: 0.2.15
+Version: 0.2.23
 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
@@ -28,6 +28,7 @@ Provides-Extra: anthropic
 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'
+Requires-Dist: mcp>=1.28.1; extra == 'claude-agent-sdk'
 Provides-Extra: demo
 Requires-Dist: langchain-anthropic>=1.4.6; extra == 'demo'
 Requires-Dist: langchain-core>=1.3.3; extra == 'demo'
@@ -380,7 +381,7 @@ backlink still renders.
 Emits attributes per the OTel GenAI semantic conventions:
 
 - `gen_ai.operation.name` — `chat`, `execute_tool`, `invoke_agent`, `retrieval`
-- `gen_ai.provider.name` — `anthropic`, `openai`, `langchain`, `struct`, …
+- `gen_ai.provider.name` — the GenAI provider on inference spans (`anthropic`, `openai`, …); platform-routed calls report the platform value (`aws.bedrock`, `gcp.vertex_ai`, `azure.ai.openai`) when detectable from the client. `invoke_agent` spans inherit the provider from their first child inference call (omitted when no model is reached); `execute_tool`/`retrieval` spans carry no provider.
 - `gen_ai.request.{model, max_tokens, temperature, top_p, top_k, stop_sequences}`
 - `gen_ai.response.{model, id, finish_reasons}`
 - `gen_ai.usage.{input_tokens, output_tokens, cache_read.input_tokens, cache_creation.input_tokens}`
@@ -388,6 +389,29 @@ Emits attributes per the OTel GenAI semantic conventions:
 - `gen_ai.tool.{name, call.id, call.arguments, call.result}`
 - `error.type` + `StatusCode.ERROR` on failures
 
+### `error.type` values emitted
+
+The OTel conventions ask instrumentations to document the error values
+they report ("Instrumentations SHOULD document the list of errors they
+report"). This SDK emits exactly two kinds of value, both alongside
+span `StatusCode.ERROR`:
+
+| Value | When | Meaning |
+| --- | --- | --- |
+| exception class name (e.g. `RuntimeError`, `httpx.ConnectError`) | the instrumented call raised | We failed to execute the request. Also records an OTel exception event. |
+| `tool_error` | an `execute_tool` span whose result signalled failure **in band** — Anthropic `tool_result` blocks with `is_error: true`, MCP `CallToolResult.isError`, or a LangChain `ToolMessage` with `status="error"` | The tool ran and reported a failure back to the model (bad arguments, a domain "no"), so the model can self-correct. No exception object exists, so no class name is available. |
+
+`tool_error` is a deliberate low-cardinality sentinel, which the
+`error.type` convention explicitly permits ("another low-cardinality
+error identifier"; a custom value MAY be used where no well-known one
+applies). The same split is used by OpenTelemetry's MCP instrumentation
+in OpenLLMetry, which likewise reports `error.type="tool_error"` for the
+`isError` path and the exception class name otherwise.
+
+The distinction is what lets a monitor page on genuine execution
+failures while excluding failures the model already saw and can recover
+from.
+
 Note: `gen_ai.usage.input_tokens` for Anthropic is the true total — the
 SDK adds back `cache_read_input_tokens` and
 `cache_creation_input_tokens`, which Anthropic's raw response excludes

{struct_sdk-0.2.15 → struct_sdk-0.2.23}/README.md

@@ -332,7 +332,7 @@ backlink still renders.
 Emits attributes per the OTel GenAI semantic conventions:
 
 - `gen_ai.operation.name` — `chat`, `execute_tool`, `invoke_agent`, `retrieval`
-- `gen_ai.provider.name` — `anthropic`, `openai`, `langchain`, `struct`, …
+- `gen_ai.provider.name` — the GenAI provider on inference spans (`anthropic`, `openai`, …); platform-routed calls report the platform value (`aws.bedrock`, `gcp.vertex_ai`, `azure.ai.openai`) when detectable from the client. `invoke_agent` spans inherit the provider from their first child inference call (omitted when no model is reached); `execute_tool`/`retrieval` spans carry no provider.
 - `gen_ai.request.{model, max_tokens, temperature, top_p, top_k, stop_sequences}`
 - `gen_ai.response.{model, id, finish_reasons}`
 - `gen_ai.usage.{input_tokens, output_tokens, cache_read.input_tokens, cache_creation.input_tokens}`
@@ -340,6 +340,29 @@ Emits attributes per the OTel GenAI semantic conventions:
 - `gen_ai.tool.{name, call.id, call.arguments, call.result}`
 - `error.type` + `StatusCode.ERROR` on failures
 
+### `error.type` values emitted
+
+The OTel conventions ask instrumentations to document the error values
+they report ("Instrumentations SHOULD document the list of errors they
+report"). This SDK emits exactly two kinds of value, both alongside
+span `StatusCode.ERROR`:
+
+| Value | When | Meaning |
+| --- | --- | --- |
+| exception class name (e.g. `RuntimeError`, `httpx.ConnectError`) | the instrumented call raised | We failed to execute the request. Also records an OTel exception event. |
+| `tool_error` | an `execute_tool` span whose result signalled failure **in band** — Anthropic `tool_result` blocks with `is_error: true`, MCP `CallToolResult.isError`, or a LangChain `ToolMessage` with `status="error"` | The tool ran and reported a failure back to the model (bad arguments, a domain "no"), so the model can self-correct. No exception object exists, so no class name is available. |
+
+`tool_error` is a deliberate low-cardinality sentinel, which the
+`error.type` convention explicitly permits ("another low-cardinality
+error identifier"; a custom value MAY be used where no well-known one
+applies). The same split is used by OpenTelemetry's MCP instrumentation
+in OpenLLMetry, which likewise reports `error.type="tool_error"` for the
+`isError` path and the exception class name otherwise.
+
+The distinction is what lets a monitor page on genuine execution
+failures while excluding failures the model already saw and can recover
+from.
+
 Note: `gen_ai.usage.input_tokens` for Anthropic is the true total — the
 SDK adds back `cache_read_input_tokens` and
 `cache_creation_input_tokens`, which Anthropic's raw response excludes

{struct_sdk-0.2.15 → struct_sdk-0.2.23}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.2.15"
+version = "0.2.23"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -37,7 +37,11 @@ Issues = "https://struct.ai/support"
 
 [project.optional-dependencies]
 anthropic = ["anthropic>=0.30.0"]
-claude-agent-sdk = ["claude-agent-sdk>=0.1.59"]
+# mcp>=1.28.1 pinned directly (not just in override-dependencies below) so it
+# ships in this extra's published wheel metadata — CVE-2026-52870,
+# CVE-2026-52869, CVE-2026-59950 (GHSA-hvrp-rf83-w775, GHSA-jpw9-pfvf-9f58,
+# GHSA-vj7q-gjh5-988w).
+claude-agent-sdk = ["claude-agent-sdk>=0.1.59", "mcp>=1.28.1"]
 langchain = ["langchain-core>=1.3.3"]
 # Responses API (openai.resources.responses) exists from 1.66.0 onward.
 openai = ["openai>=1.66.0"]
@@ -80,6 +84,8 @@ override-dependencies = [
     "starlette>=1.3.1",
     "langsmith>=0.8.18",
     "pydantic-settings>=2.14.2",
+    # CVE-2026-52870, CVE-2026-52869, CVE-2026-59950 (GHSA-hvrp-rf83-w775, GHSA-jpw9-pfvf-9f58, GHSA-vj7q-gjh5-988w)
+    "mcp>=1.28.1",
 ]
 
 [tool.pytest.ini_options]