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