# Psyche Error Handling

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

```
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