src/README_RESILIENT_API.md

# MorphGuard Resilient API System

The MorphGuard Resilient API System provides a comprehensive solution for making API calls with intelligent fallbacks, context-aware routing, and adaptive behavior. This system is designed to enhance application reliability and user experience by gracefully handling API failures and degraded conditions.

## Key Features

### 1. Intelligent Fallbacks
- **Tiered Fallback Selection**: Prioritize fallbacks by importance
- **Context-Aware Fallbacks**: Select fallbacks based on request context
- **Dynamic Fallback Generation**: Generate fallback data at runtime
- **Fallback Registry**: Centralized management of fallbacks

### 2. Context-Aware Request Handling
- **Request Context**: Route requests based on context information
- **Endpoint Configuration**: Fine-tune behavior for specific endpoints
- **Adaptive Timeouts**: Adjust timeouts based on historical performance
- **Priority-Based Handling**: Prioritize critical requests

### 3. Circuit Breaker Pattern
- **Automatic Circuit Breaking**: Prevent cascading failures
- **Health-Aware Recovery**: Intelligently attempt recovery
- **Per-Endpoint Configuration**: Configure circuit breakers for each endpoint
- **Manual Reset**: Reset circuit breakers when needed

### 4. Resource-Aware Request Throttling
- **Resource Monitoring**: Track CPU and memory usage
- **Automatic Throttling**: Reduce load during high resource utilization
- **Priority-Based Dropping**: Drop low-priority requests first
- **Adaptive Behavior**: Adjust behavior based on system conditions

### 5. Degraded Mode Operations
- **Degraded Mode Detection**: Automatically detect system degradation
- **Fallback to Cached Data**: Use cached data during degradation
- **Reduced Functionality**: Provide essential functionality during degradation
- **Graceful Recovery**: Smoothly transition back to normal operation

### 6. Comprehensive Metrics and Telemetry
- **Request Statistics**: Track success rates, timing, and more
- **Circuit Breaker Status**: Monitor circuit breaker states
- **Resource Usage**: Track resource utilization
- **Fallback Usage**: Monitor fallback utilization

## Architecture

The system is built on a modular architecture with the following components:

1. **API Fallback Registry**: Manages fallbacks for API endpoints
2. **Context-Aware API Adapter**: Enhances requests with context awareness
3. **API Resilience Client**: Integrates all components for a unified interface
4. **API Utilities**: Core request handling and circuit breaking
5. **Telemetry Integration**: Comprehensive logging and metrics

## Usage

### Basic Usage

```python
from src.api_resilience import get_resilient_api

# Get the resilient API client
api = get_resilient_api()

# Make a request
try:
    response = api.get("/users")
    print(f"Response: {response}")
except Exception as e:
    print(f"Error: {e}")
```

### Context-Aware Requests

```python
# Make a request with context
response = api.get(
    "/users/profile",
    context={"role": "admin", "user_id": "123"}
)
```

### Registering Fallbacks

```python
from src.api_resilience import get_resilient_api, FallbackTier

# Register a fallback
api.register_fallback(
    endpoint="/users/profile",
    key="default_profile",
    fallback={"id": None, "name": "Guest", "email": None, "role": "guest"},
    tier=FallbackTier.PRIMARY,
    tags={"type": "static", "category": "user"}
)
```

### Configuring Endpoints

```python
from src.api_resilience import get_resilient_api
from src.context_aware_api import EndpointPriority, ResourceConsumption

# Configure an endpoint
api.configure_endpoint(
    "/users",
    priority=EndpointPriority.HIGH,
    resource_consumption=ResourceConsumption.MODERATE,
    timeout=5.0,
    retries=2,
    circuit_breaker_enabled=True,
    cache_enabled=True,
    tags={"category": "user", "importance": "high"}
)
```

### Managing Circuit Breakers

```python
# Reset a circuit breaker
api.reset_circuit_breaker("/users")

# Reset all circuit breakers
api.reset_all_circuit_breakers()
```

### Monitoring

```python
# Get request statistics
stats = api.get_request_stats("/users")

# Check if system is in degraded mode
is_degraded = api.is_in_degraded_mode()

# Get fallbacks for an endpoint
fallbacks = api.get_fallbacks("/users")
```

## Configuration

The resilient API system can be configured with various options:

```python
options = {
    "base_url": "http://localhost:5000/api",
    "cache_dir": ".mg_api_cache",
    "fallbacks_dir": ".mg_fallbacks",
    "timeout": 30.0,
    "retries": 3,
    "enable_telemetry": True,
    "enable_fallbacks": True,
    "enable_circuit_breaker": True,
    "enable_context_aware": True,
    "enable_resource_monitoring": True,
    "register_default_fallbacks": True
}

api = get_resilient_api(options)
```

## Running the Demo

A demo script is provided to showcase the features of the resilient API system:

```bash
python demo_resilient_api.py
```

For verbose logging:

```bash
python demo_resilient_api.py --verbose
```

## Integration with MorphGuard

The resilient API system is fully integrated with the MorphGuard telemetry and error handling systems, providing comprehensive monitoring and diagnostics. It uses the existing caching and circuit breaker implementations while adding new capabilities for context-aware routing and intelligent fallbacks.