FlightOps AI

An airline-operations intelligence API that turns live flight events into explainable delay-risk signals.

FlightOps AI is a tested vertical slice of an operations platform: it accepts retry-safe flight events, persists them, scores operational risk, explains every score, and exposes summaries and service metrics. It is intentionally small enough to understand in minutes while demonstrating the engineering decisions needed to evolve it into a cloud data and ML system.

Live demo: Open the interactive API documentation or check the health endpoint. The serverless demo uses ephemeral storage; see the documented limitations below.

What it demonstrates

Area	Evidence in this repository
Backend engineering	Typed FastAPI routes, validation, layered service/repository design, OpenAPI docs
Data engineering	Normalized UTC events, indexed SQLite persistence, latest-event queries, aggregate summaries
Reliability	Idempotent writes, bounded inputs, typed 404s, health endpoint, retry-safe behavior
Applied ML	Evaluated T-24h delay model trained on 90,000 official BTS records, portable JSON inference, calibration, model card, and error slices
Observability	Prometheus-compatible request and ingestion counters
Cloud delivery	Non-root Docker image, Compose setup, Vercel entrypoint, automated GitHub Actions tests

At a glance

• 7 operational endpoints for ingestion, risk, trained prediction, model evidence, summaries, health, and metrics
• 4 scored risk signals plus an explicit cancellation adjustment
• Idempotency by event ID, so producer retries do not duplicate records
• 8 automated tests covering API behavior, validation, rules, trained inference, summaries, and metrics
• 90,000 official BTS records in a checksum-tracked, reproducible chronological evaluation
• One-command local start with Docker Compose

Two-minute recruiter tour

1. Read the model card for the chronological evaluation, calibration, operating threshold, error slices, and limitations.
2. Read the portable inference code to see how inspectable JSON coefficients serve predictions without unsafe pickle loading.
3. Read the API tests to see idempotency, validation, rules, trained inference, summaries, and metrics working together.
4. Open the live API explorer to exercise every endpoint without local setup.

Architecture

flowchart LR
    C["Client or event producer"] --> A["FastAPI + Pydantic validation"]
    A --> S["Operations service"]
    S --> R["SQLite event repository"]
    S --> E["Explainable risk engine"]
    A --> P["T-24h schedule model"]
    A --> M["Service metrics"]
    R --> Q["Operational summary"]
    E --> O["Risk score + factor explanations"]
    P --> O2["Delay probability + model version"]

Loading

The repository boundary keeps persistence replaceable. SQLite makes the demo reproducible with zero infrastructure; PostgreSQL is the planned durable production store. See docs/architecture.md and ADR 0001.

Run it locally

Requirements: Python 3.11+

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
uvicorn app.main:app --reload

Then open http://127.0.0.1:8000/docs. The base URL redirects there automatically.

Docker alternative:

docker compose up --build

Try the end-to-end flow

Ingest a delayed flight event:

curl -X POST http://127.0.0.1:8000/v1/events \
  -H 'content-type: application/json' \
  -d @data/sample_event.json

Request its explainable risk score:

curl http://127.0.0.1:8000/v1/flights/DL123/risk

{
  "flight_id": "DL123",
  "score": 0.836,
  "level": "high",
  "factors": [
    {"name": "departure_delay", "contribution": 0.4, "explanation": "120 recorded delay minutes"},
    {"name": "weather", "contribution": 0.24, "explanation": "Weather severity is 0.80 on a 0–1 scale"},
    {"name": "airport_congestion", "contribution": 0.14, "explanation": "Airport congestion is 0.70 on a 0–1 scale"},
    {"name": "turnaround_pressure", "contribution": 0.056, "explanation": "Aircraft turnaround is 20 minutes"}
  ],
  "model_version": "baseline-rules-v1"
}

Inspect the operations view and service counters:

curl http://127.0.0.1:8000/v1/operations/summary
curl http://127.0.0.1:8000/metrics

Request a schedule-only trained-model prediction:

curl -X POST http://127.0.0.1:8000/v1/predictions/delay \
  -H 'content-type: application/json' \
  -d '{"flight_date":"2026-08-10","reporting_airline":"DL","origin":"IAD","destination":"ATL","crs_departure_time":815,"crs_elapsed_time":115,"distance":534,"distance_group":3}'
curl http://127.0.0.1:8000/v1/models/delay/metadata

Posting the same event_id again returns 200 with "created": false; the database keeps one event. That makes upstream retries safe.

API surface

Method	Path	Purpose
GET	/health	Service readiness and version
POST	/v1/events	Validate and idempotently store a flight event
GET	/v1/flights/{flight_id}/risk	Score the latest event and explain each contribution
GET	/v1/operations/summary	Return fleet-level event and high-risk counts
POST	/v1/predictions/delay	Predict T-24h arrival-delay probability from schedule-only fields
GET	/v1/models/delay/metadata	Expose model version, threshold, evaluation metrics, lineage, and limitations
GET	/metrics	Export Prometheus-compatible counters

Trained-model evidence

The deployed bts-schedule-logistic-v1 model was trained on a deterministic 90,000-row sample from official BTS monthly files. Training uses Jan-Dec 2024, threshold selection uses Jan-Mar 2025, and the untouched test period is Apr-Jun 2025.

Test metric	Result
ROC-AUC	0.640
PR-AUC	0.335
Precision	0.304
Recall	0.748
F1	0.432
Brier score	0.176

These are retrospective public-data results, not production accuracy claims. Reproduce the download and training with the ML runbook, then inspect the model card, data manifest, and error slices.

Quality checks

python -m pytest

GitHub Actions installs the project in a clean Python 3.12 runner and executes the same suite on every push and pull request.

Decisions and honest limitations

• The event-risk endpoint remains a deterministic rules fallback; the separate schedule-prediction endpoint uses the evaluated trained model and never mixes post-departure fields into T-24h inference.
• SQLite is appropriate for a local demonstration. On Vercel it uses ephemeral /tmp storage, so the public demo is not a durable system of record.
• Metrics are process-local. A production deployment would export them to managed observability infrastructure.
• Authentication, rate limiting, a durable event queue, and infrastructure-as-code belong in a later production milestone.

Roadmap

• Idempotent event ingestion
• Explainable baseline risk scoring
• Operational summary endpoint
• Health and service metrics
• Automated API and domain tests
• Docker packaging and CI
• PostgreSQL migrations and query-performance evidence
• React + TypeScript operations dashboard
• Versioned delay-prediction model with an evaluation report
• Queue, retries, caching, and failure-injection tests
• Evaluated incident/runbook assistant with citations
• AWS deployment with Terraform and a cost estimate
• Load-test report, SLO, and incident write-up

The trained-model milestone is specified in Issue #2 and governed by a leakage-resistant data contract.

Project integrity

This is original work. External datasets and libraries will be documented with their sources and licenses. Future capabilities are listed as roadmap items instead of being presented as finished work.

License

MIT License. See LICENSE.