Error Handling Philosophy

Deconvolute distinguishes between content policy violations, expected security states, and fundamental infrastructure compromises. This distinction dictates how the SDK communicates a threat back to your application or your AI agent.

There are three distinct error handling patterns used across the SDK:

1. Protocol Errors (Graceful Agent Degradation)

When acting as an intermediary proxy, such as the MCP Firewall intercepting a call_tool operation, Deconvolute returns an in-band protocol error (e.g. an MCP CallToolResult with isError=True).

This is intentional. The session connection itself is still verified, but the specific action is forbidden. Returning an error object stays within the boundaries of the underlying protocol. This allows the AI agent to read the error context and gracefully adjust its approach, such as trying a different tool or asking the user for clarification.

2. Security Results (Explicit Developer Control)

When using the content scanners directly (e.g. via scan() or standard .check() methods), Deconvolute does not raise exceptions for malicious content. Instead, it returns a structured SecurityResult object.

The philosophy here is that detecting an adversarial payload is an expected outcome of scanning untrusted data, not a runtime application crash. Returning an object requires the developer to explicitly evaluate the safe property and intentionally route the execution flow, whether that means quarantining the payload, redacting the text, or logging an audit trail.

3. Hard Exceptions (Fail-Closed Posture)

Deconvolute raises hard Python exceptions only when execution must be immediately halted to prevent a critical failure. This occurs in two primary scenarios:

• Infrastructure Compromise: If a server fails origin validation, it represents a fundamental infrastructure compromise. The SDK raises a hard exception before ever yielding the session context. You do not want to negotiate with a compromised server or allow the agent to connect to it.
• Wrapper Type Safety: When using transparent client wrappers like llm_guard(), returning a custom SecurityResult object would break the type signature expected from the underlying client (like the OpenAI SDK). To maintain type safety and prevent unsafe generations from silently propagating, the wrapper raises a hard exception to halt the execution thread.