An offline flight-safety monitor for the Cessna 172S — it replays real training-flight telemetry, spots behaviour unlike normal flight, explains which signals drove that judgement, and opens a structured checklist.
Built for the HTCJ Aviation Futures Innovation Challenge. Everything runs on one laptop with no internet connection: the models, the rules, the dashboard, and the language model that writes the explanations.
git clone <this-repo> && cd guardian172
pip install -r requirements.txt
python run.py # → http://127.0.0.1:8000That is the whole quickstart. The trained models, the demo clips and the built dashboard are committed, so a judge needs neither the dataset nor npm.
General-aviation training flights are where most pilots learn, and where a disproportionate share of accidents happen. Aircraft like the C172 record detailed telemetry, but on a training aircraft that data is almost always looked at after something has gone wrong — if at all. There is no equivalent of the airline world's flight-data monitoring for a flight school with six aeroplanes and no data-science team.
The obstacles are practical rather than scientific: the data is sensitive, connectivity in a hangar is poor, and nobody trusts a black box that says "anomaly 0.94" without saying why.
Guardian 172 is a demonstration of what the other shape looks like — monitoring that runs entirely on local hardware, states its evidence in the units a pilot already reads, and hands off to a checklist rather than to a probability.
Replay a flight, second by second, and watch four things happen together:
- Score it. 54 causal rolling features feed a supervised model
(
1 − P(normal)) and an Isolation Forest trained only on normal flights. - Corroborate it. Eight deterministic rules, with thresholds calibrated from normal training flights, name the specific condition in plain language.
- Decide. Arbitration turns scores and rules into an alert only when the evidence is sustained or a trusted rule fires — with a cooldown so one developing condition does not produce a stream of duplicates.
- Explain and act. A local Gemma model turns the already-decided alert into readable text, and the matching demonstration checklist opens.
The dashboard shows instruments, synchronised plots, the live anomaly score, which rules are holding, the ranked contributing signals with their normal-flight reference ranges, an event timeline, and a post-flight report. Ground truth stays hidden until you ask for it.
CAFUC2 telemetry ─► replay ─► 54 rolling features
│
┌──────────────────────┼──────────────────────┐
▼ ▼ ▼
Isolation Forest Supervised forest 8 deterministic
(normal only) 1 − P(normal) rules
→ novelty → anomaly score → named conditions
└──────────────────────┼──────────────────────┘
▼
alert arbitration (three paths)
▼
┌────────────────┴────────────────┐
▼ ▼
local Gemma explanation checklist state machine
└────────────────┬────────────────┘
▼
React dashboard over a WebSocket
Full detail, including why there are two detection models, is in
docs/ARCHITECTURE.md.
This is the part that took the most work, and it is where the honest engineering lives. A sustained high score is the obvious path, but it cannot catch everything: a throttle surge in this dataset is a single-second RPM step that never drives the supervised score to threshold at all, so any persistence requirement rules it out by construction.
So an alert can come from a sustained score above threshold; from several rules
agreeing at once; or from one rule that was measured to be trustworthy enough
to act alone. That last path is not a hand-wave — each rule is replayed across
the validation split and scored on how often its own firings land inside a real
event, and only the top-ranked rule is admitted. On this dataset that is
rpm_step_discontinuity, and it is the only reason throttle surges are visible
at all.
The operating point is chosen on validation by maximising the mean detection rate per anomaly category, subject to at most one false alert per normal flight. Averaging per category matters: pitch excursions supply over half of all significant events, so maximising the pooled rate quietly buys a few extra pitch detections by giving up two entire failure families — which is exactly what an earlier version of this system did.
Measured on a held-out test split of 30 flights that was never used for training, rule calibration, threshold selection or demo curation. Splits are grouped by source flight, because each abnormal file is a byte-identical copy of a normal flight with an injection applied.
| Metric | Result |
|---|---|
| Significant events detected | 72 / 176 (40.9%) |
| Precision | 0.787 |
| False alerts | 0.67 per normal flight (1 of 6 flights affected) |
| Median detection delay | 1.0 s |
| Classification accuracy | 0.986 over 74 detected events |
| Category | Significant events detected | Classification |
|---|---|---|
| Engine power loss | 12 / 17 = 0.71 | 1.00 |
| Flight-path deviation | 24 / 39 = 0.62 | 1.00 |
| Throttle surge | 9 / 15 = 0.60 | 0.89 |
| Pitch excursion | 27 / 105 = 0.26 | 1.00 |
An earlier operating point scored a similar headline number while detecting zero engine-power-loss and zero throttle-surge events — it was quietly blind to half the failure families. Fixing that cost precision (0.93 → 0.79) and some detection on the two easy categories. That trade is deliberate: a monitor that cannot see two of the four things it is meant to see is not a safer monitor for being quiet about them.
| Injection magnitude | Detected |
|---|---|
| negligible (<0.25) | 1 / 357 = 0.003 |
| small (0.25–0.5) | 1 / 65 = 0.015 |
| moderate (0.5–1) | 5 / 50 = 0.100 |
| large (1–2) | 25 / 56 = 0.446 |
| very large (>2) | 42 / 70 = 0.600 |
This clean monotonic curve is the most honest result in the project, and it
explains the headline number. Most CAFUC2 injections are too small to detect by
any means. The median throttle-surge injection moves engine RPM by about
15 rpm — smaller than the second-to-second noise of ordinary flight. Because
every abnormal file differs from its source flight only inside the injected
segments, each event has an exact measured relative_magnitude, so this is
measured rather than asserted. Results are always reported both over all events
and over the events at or above half strength.
Five clips, all cut from test-split flights:
| Clip | Peak score | Alert | Classified |
|---|---|---|---|
| Normal | 0.79 | none — stays quiet | — |
| Engine power loss | 0.98 | 1 | correct |
| Pitch excursion | 0.99 | 1 | correct |
| Flight-path deviation | 1.00 | 1 | correct |
| Throttle surge | 0.77 | 1 | correct |
The throttle-surge clip is worth watching closely: it alerts at a peak score of 0.77, below the 0.95 threshold, because it was caught by the standalone rule path rather than the model.
python run.py # dashboard + API on :8000
python -m pytest tests/ -q # 65 testsThe local explanation model is optional. Point Guardian at any OpenAI-compatible local server:
export GUARDIAN172_LLM_URL=http://127.0.0.1:5000/v1
export GUARDIAN172_LLM_MODEL=gemma-4-E4B-it-IQ4_XSVerified end to end against a local llama-server running Gemma 4 E4B (IQ4_XS)
on a single RTX 4070: explanations return in ~1.1–1.6 s. If the server is
absent, slow, or returns anything failing schema validation, a deterministic
template is used instead and the UI labels which one produced the text — the demo
never depends on the model being up.
Rebuilding everything from the raw dataset (~15 min) is documented in
data/README.md.
The claim is deliberately narrow, and the UI is worded to match:
Guardian 172 demonstrates how an offline software monitor can replay Cessna 172 telemetry, identify unusual multivariate behaviour, explain the contributing signals, and initiate a structured checklist workflow.
- Classifier confidence is similarity to a dataset category, never a probability that a real failure is occurring.
- The checklists are project-authored demonstration content. They are not Cessna procedures and are not approved for operational use.
- Rule thresholds are learned from this dataset's normal flights, not operating limits, and carry no airworthiness meaning.
- The language model never decides whether something is wrong, never sees raw telemetry, and cannot author or edit a checklist step. It receives the finished alert object and nothing else, and its output is schema-validated before display.
The addressable problem is real and unserved. The FAA counts over 200,000 active general aviation aircraft in the United States alone, flying out of thousands of flight schools and clubs, almost none of which run flight-data monitoring — the airline-grade FDM vendors price and scope for fleets of hundreds.
Guardian 172's architecture is what makes that market reachable:
- No cloud, no per-aircraft connectivity. The whole system runs on a laptop in the ops room. That removes the recurring cost that makes existing FDM uneconomic below fleet scale, and it removes the data-governance conversation that stalls adoption — student telemetry never leaves the building.
- Explanations, not scores. A flight school's safety officer is a chief instructor, not an analyst. Alerts that name signals in the units on the panel, with normal ranges beside them, are actionable by the person who already exists.
- Checklist hand-off. The output is a procedure to work through and a record that it was worked through — which is the artefact an audit or insurer wants.
The near-term commercial wedges are debrief tooling for flight schools (per-aircraft subscription), maintenance triage — the engine-power-loss family is exactly the slow-onset trend that gets missed between scheduled inspections — and insurer-facing evidence that a school runs a monitoring programme.
Near term. Per-category arbitration, so persistence can be 1 s for a one-second throttle step and 5 s for a 40-second engine trend instead of one compromise value. Broadening the rule set for pitch excursions, the weakest category at 0.26. Ingesting real Garmin/JPI log formats so the tool reads what an actual C172 records rather than a prepared parquet file.
Medium term. Extending beyond the four injected families to the C172R, SR20 and SR20G6 airframes also present in CAFUC2, which tests whether the Isolation Forest earns its place by flagging behaviour the supervised model was never shown. Fleet-level views across many flights, where slow-onset trends actually live. On-device deployment to a panel tablet.
Longer term. The same offline, explain-then-hand-off pattern is what uncrewed and advanced-air-mobility platforms will need for onboard health monitoring, where there is no crew to interpret a score and no guarantee of a link to the ground.
backend/ features, detection, classification, rules, alerts, checklist,
assistant, replay, reporting, FastAPI app
frontend/ React + Vite dashboard (built bundle committed)
scripts/ prepare_dataset · train_models · calibrate_rules ·
select_threshold · evaluate · build_demo_files
rules/ calibrated demonstration rules (YAML)
checklists/ project-authored demonstration checklists (YAML)
models/ trained artifacts + the selected alert configuration
evaluations/ metrics.json and per-event results on the test split
data/demo/ the five replay clips
docs/ ARCHITECTURE.md
Built on CAFUC2 (Civil Aviation Flight University of China), real C172S
training telemetry with physics-based injections —
DOI 10.21227/sp2s-7r16. The dataset
requires an IEEE DataPort subscription and is not redistributed here; it is
not needed to run the demo. See data/README.md.
Code released under the licence in LICENSE. Citation metadata in
CITATION.cff.