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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: struct-sdk
-Version: 0.2.22
+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
@@ -389,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.22 → struct_sdk-0.2.23}/README.md

@@ -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.22 → struct_sdk-0.2.23}/pyproject.toml

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