Eve library

Psyche Error Handling

Other

Revision 1

On this page

Error handling and recovery framework for the Psyche AI Virtual Assistant Platform.

Part of the Oshun Platform.

Overview#

This library provides comprehensive error handling, graceful degradation, and recovery mechanisms for AI virtual assistants. It ensures the system remains responsive and provides meaningful feedback even when components fail.

Modules#

Error Classification#

  • Typed exception hierarchy (Network, Service, AI, Media, etc.)
  • Error severity and category classification
  • Automatic exception classification
  • Error context and metadata

Graceful Degradation#

  • Multi-level degradation (0-4 levels)
  • Component-specific degraders (Avatar, TTS, LLM, Network)
  • Feature management (enable/disable based on health)
  • Smooth transitions between degradation levels

Recovery Mechanisms#

  • Retry policies with exponential backoff
  • Circuit breaker pattern
  • Provider failover (multi-provider resilience)
  • Checkpoint and restore for long operations
  • Connection pool management

User Communication#

  • User-friendly error messages
  • Status updates during recovery
  • Recovery time estimation
  • Progressive disclosure of details

Degradation Levels#

Level Name Description
0 Normal All features operational
1 Reduced AI Simplified AI processing
2 Basic Features Core features only
3 Minimal Emergency mode
4 Offline Fully degraded

Project Structure#

text
src/error_handling/
├── __init__.py           # Package exports
├── errors/               # Error Classification
│   ├── types.py          # Error types and enums
│   └── detection.py      # Error detection services
├── degradation/          # Graceful Degradation
│   ├── levels.py         # Degradation levels
│   ├── degraders.py      # Component degraders
│   └── manager.py        # Degradation manager
├── recovery/             # Recovery Mechanisms
│   ├── retry.py          # Retry policies
│   ├── circuit_breaker.py
│   ├── failover.py       # Provider failover
│   └── checkpoint.py     # Checkpoint/restore
└── communication/        # User Communication
    ├── messages.py       # Message generation
    ├── status.py         # Status updates
    └── estimates.py      # Recovery estimates

Development#

Using Nx#

bash
# Install dependencies
nx install psyche-error-handling

# Build
nx build psyche-error-handling

# Linting
nx lint psyche-error-handling
nx lint-fix psyche-error-handling

# Formatting
nx format psyche-error-handling
nx format-check psyche-error-handling

# Type checking
nx typecheck psyche-error-handling

# Testing
nx test psyche-error-handling
nx test-cov psyche-error-handling

Direct Commands#

bash
cd apps/psyche/error-handling

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Lint
poetry run ruff check src tests

Usage Examples#

Error Handling#

python
from error_handling import (
    NetworkError,
    ServiceError,
    classify_exception,
    get_communication_service,
)

try:
    result = await external_api_call()
except Exception as e:
    # Classify the error
    error_info = classify_exception(e)

    # Get user-friendly message
    comm = get_communication_service()
    message = comm.communicate_error(error_info)

    # Handle based on severity
    if error_info.severity == ErrorSeverity.CRITICAL:
        await escalate_to_support(error_info)

Retry Policy#

python
from error_handling import RetryPolicy

# Create a retry policy
policy = RetryPolicy(
    max_retries=3,
    initial_delay=1.0,
    exponential_base=2.0,
    max_delay=30.0,
)

# Execute with automatic retries
result = await policy.execute(unreliable_operation)

Circuit Breaker#

python
from error_handling import CircuitBreaker, CircuitOpenError

# Create circuit breaker
breaker = CircuitBreaker(
    name="external_api",
    failure_threshold=5,
    recovery_timeout=30.0,
)

try:
    result = await breaker.execute(api_call)
except CircuitOpenError:
    # Service is failing, use fallback
    result = await get_cached_response()

Graceful Degradation#

python
from error_handling import get_degradation_manager, DegradationLevel

manager = get_degradation_manager()

# Check current level
if manager.current_level >= DegradationLevel.LEVEL_1_REDUCED_AI:
    # Use simplified AI processing
    response = await simplified_ai_response(prompt)
else:
    # Use full AI processing
    response = await full_ai_response(prompt)

# Trigger degradation
await manager.trigger_degradation(
    level=DegradationLevel.LEVEL_1_REDUCED_AI,
    reason="High latency detected",
)

Failover#

python
from error_handling import FailoverManager, ProviderConfig

# Configure providers
providers = [
    ProviderConfig(name="primary", endpoint="...", priority=1),
    ProviderConfig(name="secondary", endpoint="...", priority=2),
    ProviderConfig(name="backup", endpoint="...", priority=3),
]

failover = FailoverManager(providers)

# Execute with automatic failover
result = await failover.execute(lambda p: call_provider(p))

Error Types#

Error Description
NetworkError Network connectivity issues
ServiceError External service failures
AuthenticationError Auth failures
AuthorizationError Permission denied
ValidationError Input validation failures
ResourceError Resource not found/exhausted
TimeoutError Operation timeouts
RateLimitError Rate limit exceeded
AIModelError AI model failures
MediaError Audio/video processing errors
DatabaseError Database operations
ConfigurationError Configuration issues

License#

Proprietary - Oshun Platform