```
# 🚀 API Reference - Aviation Safety AI Framework
## Overview
Complete API documentation for the Limit Cycle Flight Dynamics framework. This hybrid physics-AI system predicts crew cognitive state with 89.3% accuracy using Van der Pol oscillator models and Lyapunov stability analysis.
## Quick Start
```python
from aviation_safety import AviationSafetyAI
# Initialize the framework
ai = AviationSafetyAI(
model_type='hybrid',
certification_level='DO-178C'
)
# Load and analyze flight data
results = ai.analyze_flight(
flight_data='data/flight_001.csv',
horizon=300, # 5-minute prediction
return_detailed=True
)
```
Core Modules
1. Modeling Module
```python
from src.modeling import (
VanDerPolModel,
LyapunovAnalyzer,
LimitCycleDetector
)
# Van der Pol Oscillator for cognitive dynamics
model = VanDerPolModel(
mu=0.47, # Nonlinearity (0.1-1.0), 0.83 in emergencies
omega=1.23, # Natural frequency rad/s (0.41 in emergencies)
k_B=0.12, # Bank coupling coefficient
k_P=0.09, # Pitch coupling coefficient
lambda_memory=0.031 # Memory decay rate (0.008 in QF32)
)
# Lyapunov stability analysis
analyzer = LyapunovAnalyzer(
window_size=60, # 1-minute window for λ calculation
method='wolf', # Wolf's method for Lyapunov exponents
embedding_dim=3 # P, B, W dimensions
)
# Limit cycle detection
detector = LimitCycleDetector(
min_period=2.0, # Minimum cycle period (seconds)
max_period=15.0, # Maximum cycle period
stability_threshold=0.01
)
```
2. Prediction Functions
```python
def predict_crew_state(flight_data, horizon=300, confidence_threshold=0.8):
"""
Predict crew cognitive state 3-5 minutes ahead
Parameters:
-----------
flight_data : pandas.DataFrame or str
Flight data or path to file
horizon : int
Prediction horizon in seconds (60-600)
confidence_threshold : float
Minimum confidence for predictions (0.0-1.0)
Returns:
--------
dict:
{
'timestamp': '2023-10-15T14:30:00Z',
'prediction': {
'lambda_current': 0.234,
'lambda_predicted': 0.189,
'state': 'Creative Chaos Zone',
'state_code': 'CCZ',
'risk_level': 'MEDIUM',
'risk_score': 0.42,
'confidence': 0.893,
'time_to_ccz': 182, # seconds
'time_to_chaos': 420,
'stability_index': 0.76
},
'recommendations': [
{
'priority': 'HIGH',
'action': 'Simplify interface',
'reason': 'λ approaching chaos threshold',
'parameters': ['display_complexity', 'alert_frequency']
},
{
'priority': 'MEDIUM',
'action': 'Enhance documentation',
'reason': 'Memory decay rate increasing',
'parameters': ['logging_rate', 'checklist_frequency']
}
],
'metadata': {
'model_version': '1.2.0',
'inference_time_ms': 87,
'parameters_used': 127,
'training_date': '2025-12-01'
}
}
"""
```
3. CCZ Detection
```python
def detect_creative_chaos_zones(flight_data, custom_threshold=None):
"""
Detect Creative Chaos Zones (0.01 < λ < 0.5)
Parameters:
-----------
flight_data : pandas.DataFrame
Must contain 'pitch', 'bank', 'power' columns
custom_threshold : dict, optional
Custom CCZ thresholds
Returns:
--------
list of dict:
[
{
'zone_id': 'ccz_001',
'start_index': 1250,
'end_index': 1320,
'start_time': 1250.0, # seconds from start
'end_time': 1320.0,
'duration': 70.0, # seconds
'avg_lambda': 0.31,
'max_lambda': 0.42,
'min_lambda': 0.18,
'flight_phase': 'APPROACH',
'crew_actions': 47, # Number of distinct actions
'decisions_made': 12,
'innovation_score': 0.76,
'performance_metrics': {
'decision_speed': 8.2,
'error_rate': 0.008,
'coordination_score': 9.5
}
}
]
"""
```
4. Data Processing
```python
class FlightDataProcessor:
"""
Process and validate flight data
"""
def __init__(self, sampling_rate=8, airline='ANY'):
self.sampling_rate = sampling_rate # Hz
self.airline = airline
self.required_params = 127
def validate_format(self, data):
"""
Validate FDR data format
Returns validation report
"""
def preprocess(self, data, impute=True, normalize=True):
"""
Preprocess flight data
"""
def extract_features(self, data, phase_detection=True):
"""
Extract features for model input
"""
```
5. Visualization
```python
class SafetyVisualizer:
"""
Generate safety visualization
"""
def plot_cognitive_timeline(self, timeline_data, save_path=None):
"""
Plot cognitive state timeline with λ values
"""
def plot_phase_portrait(self, P, B, W, lambda_values):
"""
3D phase portrait colored by stability
"""
def plot_ccz_analysis(self, flight_data, ccz_segments):
"""
Visualize CCZ segments with crew actions
"""
def generate_safety_report(self, analysis_results, format='pdf'):
"""
Generate comprehensive safety report
"""
```
Response Formats
Success Response
```json
{
"status": "SUCCESS",
"timestamp": "2025-12-28T10:30:00Z",
"request_id": "req_7f8e9d0a",
"data": {
"prediction": { ... },
"ccz_segments": [ ... ],
"warnings": [],
"metadata": { ... }
}
}
```
Error Response
```json
{
"status": "ERROR",
"timestamp": "2025-12-28T10:30:00Z",
"request_id": "req_7f8e9d0a",
"error": {
"code": "API_1002",
"message": "Missing required parameter: pitch",
"details": {
"missing_params": ["pitch"],
"available_params": ["bank", "power", ...],
"suggestion": "Check data column names"
}
}
}
```
Error Codes
Code Message Resolution
API_1001 Invalid data format Ensure CSV/HDF5 format with correct columns
API_1002 Missing required parameters Check data includes pitch, bank, power
API_1003 Model prediction failed Check input data range and quality
API_1004 CCZ detection error Adjust thresholds or window size
API_1005 Memory allocation error Reduce data size or increase resources
API_1006 Certification validation failed Ensure DO-178C compliance settings
Rate Limits
· Free Tier: 100 requests/day
· Professional: 10,000 requests/day
· Enterprise: Unlimited
· Aircraft Deployment: Real-time, no limits
Authentication
```python
# API Key authentication
headers = {
'X-API-Key': 'your_api_key_here',
'X-Aircraft-ID': 'A380_VH-OQA',
'X-Certification': 'DO-178C'
}
```
Versioning
· v1.0: Initial release (2025-12)
· v1.1: Added CCZ detection (2026-01)
· v1.2: Enhanced visualization (2026-02)
Support
· Email: support@emeraldcompass.aero
· Documentation: https://docs.emeraldcompass.aero
· GitHub Issues: https://github.com/emerladcompass/Aviation/issues
```