actionable-errors

actionable-errors

Three-audience error framework for Python.

Every ActionableError speaks to three audiences simultaneously:

Install

pip install actionable-errors

Zero runtime dependencies — stdlib only. Sits at the bottom of every dependency tree.

Quick Start

from actionable_errors import (
    ActionableError,
    AIGuidance,
    ToolResult,
    from_exception,
    sanitize,
)

# Domain-specific factory with built-in defaults
error = ActionableError.authentication(
    service="Azure DevOps",
    raw_error="401 Unauthorized",
)
print(error.suggestion)    # "Check your credentials and try again."
print(error.ai_guidance)   # AIGuidance(action_required="Re-authenticate", command="az login")

# Auto-classify any exception
try:
    raise ConnectionError("Connection refused")
except Exception as exc:
    ae = from_exception(exc, service="Kusto", operation="query")
    print(ae.error_type)   # "connection"

# Typed result envelope for MCP tool responses
result = ToolResult.ok(data={"items": 42})
result = ToolResult.fail(error=error)     # extracts error_type + suggestion

# Credential sanitization
clean = sanitize('password="hunter2" token=abc123')
# → 'password="***" token=***'

Extending ErrorType

Python StrEnum can't be subclassed once it has members, so extend via composition:

from enum import StrEnum
from actionable_errors import ActionableError

class RAGErrorType(StrEnum):
    EMBEDDING = "embedding"
    INDEX = "index"

error = ActionableError(
    error="Vector store unavailable",
    error_type=RAGErrorType.INDEX,
    service="pinecone",
    suggestion="Check Pinecone cluster status.",
)

Factories

Eight domain-specific factories with sensible defaults:

All factories accept optional suggestion, ai_guidance, and troubleshooting kwargs.

Development

# Install dev dependencies
uv sync --extra dev

# Run all checks
task check  # lint → type → test (90 tests, 100% coverage)

License

MIT