diff --git a/.gitignore b/.gitignore index 25e1e10..3ca49e9 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,4 @@ dist/ build/ *.egg-info/ .DS_Store +.vercel diff --git a/README.md b/README.md index 858ef11..110452b 100644 --- a/README.md +++ b/README.md @@ -1,71 +1,141 @@ # FlightOps AI -FlightOps AI is an original airline-operations intelligence project designed to demonstrate production-minded backend, data, cloud, and AI/ML engineering skills. +[![CI](https://github.com/mitulpatel123/flightops-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/mitulpatel123/flightops-ai/actions/workflows/ci.yml) +[![Live API](https://img.shields.io/badge/Live_API-Open_Docs-000000?logo=vercel&logoColor=white)](https://flightops-ai-mu.vercel.app/docs) +![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white) +![FastAPI](https://img.shields.io/badge/FastAPI-0.133-009688?logo=fastapi&logoColor=white) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -The current milestone is a tested API that: +**An airline-operations intelligence API that turns live flight events into explainable delay-risk signals.** -- ingests flight-operation events idempotently; -- stores events in SQLite for a zero-setup local demo; -- calculates an explainable delay-risk score; -- returns an operational summary; -- exposes lightweight service metrics; -- runs locally or in Docker; and -- passes automated tests in CI. +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. -This repository intentionally starts with a small, working vertical slice. PostgreSQL, the React dashboard, model training, evaluated retrieval, AWS/Terraform deployment, load tests, and observability integrations are tracked as later milestones—not claimed as completed work. +**Live demo:** [Open the interactive API documentation](https://flightops-ai-mu.vercel.app/docs) or check the [health endpoint](https://flightops-ai-mu.vercel.app/health). The serverless demo uses ephemeral storage; see the documented limitations below. -## Why this project +## What it demonstrates -Current internship postings repeatedly ask for shipped projects, Python, APIs, SQL, distributed/cloud concepts, testing, reliability, TypeScript, and disciplined AI use. FlightOps AI connects those requirements to a real operational domain instead of presenting another tutorial clone. +| 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 | +| Explainable AI | Versioned baseline risk score with per-factor contributions—clearly identified as rules, not a trained model | +| Observability | Prometheus-compatible request and ingestion counters | +| Cloud delivery | Non-root Docker image, Compose setup, Vercel entrypoint, automated GitHub Actions tests | -## Quick start +### At a glance + +- **5 operational endpoints** for ingestion, risk, summaries, health, and metrics +- **4 scored risk signals** plus an explicit cancellation adjustment +- **Idempotency by event ID**, so producer retries do not duplicate records +- **6 automated tests** covering API behavior, validation, scoring, summaries, and metrics +- **One-command local start** with Docker Compose + +## Two-minute recruiter tour + +1. Read the [risk engine](app/risk.py) to see transparent feature contributions and model versioning. +2. Read the [API test](tests/test_api.py) to see idempotency, validation, risk, summaries, and metrics working together. +3. Read the [architecture notes](docs/architecture.md) for current tradeoffs and the production evolution path. +4. Open the [live API explorer](https://flightops-ai-mu.vercel.app/docs) to exercise every endpoint without local setup. + +## Architecture + +```mermaid +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 --> M["Service metrics"] + R --> Q["Operational summary"] + E --> O["Risk score + factor explanations"] +``` + +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](docs/architecture.md) and [ADR 0001](docs/adr/0001-start-with-a-tested-vertical-slice.md). + +## Run it locally Requirements: Python 3.11+ ```bash python -m venv .venv source .venv/bin/activate -pip install -r requirements.txt +pip install -e ".[dev]" uvicorn app.main:app --reload ``` -Open `http://127.0.0.1:8000/docs` for the API explorer. +Then open [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs). The base URL redirects there automatically. -Run tests: - -```bash -pip install -r requirements-dev.txt -pytest -``` - -Docker: +Docker alternative: ```bash docker compose up --build ``` -## Example +## Try the end-to-end flow + +Ingest a delayed flight event: ```bash 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: + +```bash curl http://127.0.0.1:8000/v1/flights/DL123/risk +``` + +```json +{ + "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: + +```bash curl http://127.0.0.1:8000/v1/operations/summary +curl http://127.0.0.1:8000/metrics ``` -Posting the same `event_id` again is safe: the API returns the existing event instead of inserting a duplicate. +Posting the same `event_id` again returns `200` with `"created": false`; the database keeps one event. That makes upstream retries safe. -## Architecture +## 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 | +| `GET` | `/metrics` | Export Prometheus-compatible counters | + +## Quality checks -```text -Client -> FastAPI routes -> Operations service -> SQLite repository - -> Explainable risk engine - -> In-memory service metrics +```bash +python -m pytest ``` -See [docs/architecture.md](docs/architecture.md) and [docs/adr/0001-start-with-a-tested-vertical-slice.md](docs/adr/0001-start-with-a-tested-vertical-slice.md). +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 current score is a deterministic, versioned baseline—not a trained ML model. This makes the behavior testable and gives a future model a measurable benchmark. +- 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 @@ -73,19 +143,19 @@ See [docs/architecture.md](docs/architecture.md) and [docs/adr/0001-start-with-a - [x] Explainable baseline risk scoring - [x] Operational summary endpoint - [x] Health and service metrics -- [x] Unit and API tests -- [x] Docker and CI +- [x] Automated API and domain tests +- [x] Docker packaging and CI - [ ] PostgreSQL migrations and query-performance evidence - [ ] React + TypeScript operations dashboard -- [ ] Versioned delay-prediction model with evaluation report -- [ ] Queue, retry, caching, and failure-injection tests +- [ ] 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 cost estimate +- [ ] AWS deployment with Terraform and a cost estimate - [ ] Load-test report, SLO, and incident write-up -## Integrity +## Project integrity -This project is original work. External datasets and libraries will be documented with their licenses and sources. No third-party repository is being copied and cosmetically rebranded. +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 diff --git a/app/main.py b/app/main.py index ec1cc91..ef8842e 100644 --- a/app/main.py +++ b/app/main.py @@ -4,6 +4,7 @@ from threading import Lock from fastapi import FastAPI, HTTPException, Response, status +from fastapi.responses import RedirectResponse from app.db import EventRepository from app.models import DelayRisk, FlightEvent, IngestResponse, OperationsSummary @@ -26,7 +27,8 @@ def render(self) -> str: def create_app(database_path: str | None = None) -> FastAPI: - resolved_path = database_path or os.getenv("FLIGHTOPS_DB_PATH", "flightops.db") + default_path = "/tmp/flightops.db" if os.getenv("VERCEL") else "flightops.db" + resolved_path = database_path or os.getenv("FLIGHTOPS_DB_PATH", default_path) threshold = float(os.getenv("FLIGHTOPS_HIGH_RISK_THRESHOLD", "0.70")) repository = EventRepository(resolved_path) service = OperationsService(repository, threshold) @@ -44,6 +46,10 @@ async def lifespan(_: FastAPI): lifespan=lifespan, ) + @api.get("/", include_in_schema=False) + def index() -> RedirectResponse: + return RedirectResponse(url="/docs") + @api.get("/health") def health() -> dict[str, str]: return {"status": "ok", "version": "0.1.0"} diff --git a/docs/architecture.md b/docs/architecture.md index ad4554f..824f6fc 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -4,6 +4,17 @@ The API uses a deliberately small layered design: +```mermaid +flowchart TB + P["Flight event producer"] -->|"POST /v1/events"| API["FastAPI boundary"] + API -->|"validated FlightEvent"| SVC["OperationsService"] + SVC --> REPO["EventRepository"] + REPO --> DB[("SQLite")] + SVC --> RISK["Risk engine"] + RISK -->|"score + factors + version"| API + API --> METRICS["Prometheus-compatible counters"] +``` + 1. FastAPI validates requests and exposes OpenAPI documentation. 2. `OperationsService` holds application behavior. 3. `EventRepository` isolates persistence and enforces event idempotency with a unique key. @@ -12,6 +23,8 @@ The API uses a deliberately small layered design: SQLite keeps the first milestone reproducible. The repository boundary allows a later PostgreSQL implementation without rewriting the API or domain logic. +For the serverless demo, SQLite is created under `/tmp`, which is writable but ephemeral. This is deliberate demo infrastructure, not a claim of durable cloud persistence. + ## Reliability decisions - Event identifiers are unique, so producer retries do not duplicate data. @@ -23,18 +36,21 @@ SQLite keeps the first milestone reproducible. The repository boundary allows a ## Planned production evolution -```text -Public data sources - | -Ingestion worker -> Queue / retry / dead-letter handling - | -PostgreSQL + object storage -> Feature pipeline -> Versioned model - | | -FastAPI + cache ----------------------------> Evaluation store - | -React operations dashboard + incident assistant - | -Metrics, traces, logs, SLOs, load tests +```mermaid +flowchart TB + D["Public aviation + weather data"] --> W["Ingestion workers"] + W --> Q["Queue + retries + dead-letter handling"] + Q --> PG[("PostgreSQL")] + Q --> OBJ[("Object storage")] + PG --> F["Feature pipeline"] + OBJ --> F + F --> MODEL["Versioned delay model"] + MODEL --> EVAL["Evaluation store"] + PG --> API["FastAPI + cache"] + MODEL --> API + API --> UI["React operations dashboard"] + API --> ASSIST["Cited incident assistant"] + API --> OBS["Metrics + traces + logs + SLOs"] ``` Each future component must include an acceptance test and evidence report before it is listed as a completed skill. diff --git a/pyproject.toml b/pyproject.toml index b62c85e..51775f1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,6 +19,9 @@ dev = ["httpx==0.28.1", "pytest==7.4.4"] [tool.setuptools.packages.find] include = ["app*"] +[tool.vercel] +entrypoint = "app.main:app" + [tool.pytest.ini_options] testpaths = ["tests"] addopts = "-q" diff --git a/tests/test_api.py b/tests/test_api.py index 5dd7211..41c9e22 100644 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -21,6 +21,15 @@ def sample_event(event_id: str = "evt-001") -> dict: } +def test_root_redirects_to_api_docs(tmp_path: Path) -> None: + app = create_app(str(tmp_path / "test.db")) + with TestClient(app, follow_redirects=False) as client: + response = client.get("/") + + assert response.status_code == 307 + assert response.headers["location"] == "/docs" + + def test_ingestion_is_idempotent_and_drives_summary(tmp_path: Path) -> None: app = create_app(str(tmp_path / "test.db")) with TestClient(app) as client: