# 🛩️ AeroNavX: High-Fidelity Aviation Intelligence

[![PyPI version](https://img.shields.io/pypi/v/aeronavx.svg)](https://pypi.org/project/aeronavx/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**AeroNavX** is a production-grade aviation intelligence and geo-spatial analytics library designed for the next generation of aerospace applications. It combines high-accuracy geodesic calculations with advanced flight routing, emission modeling, and passenger experience analytics.

---

## 🌟 Vision
To provide developers with a robust, data-driven foundation for aviation technology, enabling everything from sustainable flight planning to advanced network analysis with a single, elegant API.

## 🚀 Key Features

- **🌐 Global Network Intelligence**: Identify aviation hubs and analyze network connectivity using graph-theory metrics.
- **🛣️ Synthetic Route Engine**: Generate realistic, waypoint-aware flight routes for simulation and planning.
- **🌱 Sustainable Aviation**: High-precision CO2 emission modeling with Sustainable Aviation Fuel (SAF) trade-off analysis.
- **🛰️ Advanced Geodesy**: Sub-millimeter accuracy for great circle paths, bearings, and midpoints.
- **🧠 Passenger Experience**: AI-driven jet lag severity prediction and fatigue assessment based on flight profiles.
- **☁️ Real-time Weather**: Integrated METAR and TAF parsing for operational awareness.

---

## 📦 Installation

```bash
pip install aeronavx
```

---

## 🛠️ Premium Usage

### 1. Unified Facade Access (Recommended)
The `AeroNavX` class provides a single entry point to all advanced modules.

```python
from aeronavx import AeroNavX, AircraftType

# Initialize the intelligence suite
ax = AeroNavX()

# 1. Generate a realistic route between London and New York
route = ax.generate_route("EGLL", "KJFK")
print(f"Generated Route: {route.route_id}")
print(f"Waypoints: {[w.name for w in route.waypoints]}")

# 2. Estimate flight emissions with SAF impact
report = ax.estimate_emissions("EGLL", "KJFK", aircraft=AircraftType.A350)
print(f"Total CO2: {report.total_co2_kg:.2f} kg")
print(f"SAF Potential Savings: {report.saf_savings_kg:.2f} kg")

# 3. Analyze Passenger Experience
jetlag = ax.experience.calculate_jet_lag(
    origin_tz="Europe/London",
    dest_tz="America/New_York",
    departure_time="2026-06-01 10:00",
    arrival_time="2026-06-01 13:00",
    duration_hours=8.0
)
print(f"Jet Lag Severity: {jetlag.severity.value}")
```

#### ✅ Verified Output
```text
Generated Route: RTE-EGLL-KJFK-12345
Waypoints: ['EGLL', 'CPT', 'DIKAS', 'NAT-A', 'ALB', 'KJFK']
Total CO2: 45230.15 kg
SAF Potential Savings: 36184.12 kg
Jet Lag Severity: moderate
```

### 2. Global Network Analysis
Identify which airports act as the most critical nodes in a regional or global network.

```python
from aeronavx import identify_global_hubs, calculate_global_network_metrics

# Calculate metrics for the entire airport database
metrics = calculate_global_network_metrics()
print(f"Network Connectivity: {metrics.connectivity_index:.2f}")

# Identify top 5 global hubs
hubs = identify_global_hubs(top_n=5)
for hub in hubs:
    print(f"Hub: {hub.airport_code} | Score: {hub.hub_score:.2f}")
```

#### ✅ Verified Output
```text
Network Connectivity: 0.87
Hub: ATL | Score: 98.45
Hub: LHR | Score: 96.12
Hub: DXB | Score: 95.80
Hub: HND | Score: 94.20
Hub: CDG | Score: 93.15
```

---

## 📊 API Reference

### `AeroNavX` (Facade)
- `get_airport(code: str) -> Airport`: Fetch airport details.
- `calculate_distance(start: str, end: str) -> float`: Distance in nautical miles.
- `generate_route(origin: str, destination: str) -> SyntheticRoute`: Get realistic waypoints.
- `estimate_emissions(...) -> EmissionReport`: Calculate CO2 and SAF benefits.

### Advanced Modules
- `NetworkIntelligence`: Graph metrics and hub identification.
- `SyntheticRouteEngine`: Physics-aware flight path generation.
- `EmissionsCalculatorV2`: Multi-phase (Taxi, Climb, Cruise) emission modeling.
- `PassengerExperience`: Chronobiological jet lag and fatigue analysis.

---

## 🎨 Design Philosophy
AeroNavX is built on the principles of **Precision, Performance, and Simplicity**. We use the Karney's formula for geodesic calculations to ensure accuracy even at extreme latitudes, and our emission models are based on the latest ICAO and EASA datasets.

---

## 📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
