Black Box AI
Natural-language aviation safety analytics over NTSB final reports, built around guarded SQL for exact statistics, cited retrieval for narrative questions, validated charts, BYOK model controls, and visible audit trails.
Evidence
Screenshots from the live app: the key-free Findings report of live-SQL charts, and the natural-language Ask-the-record console with bring-your-own-key model controls.




Problem
Aviation safety questions split into two very different types. Counting questions need exact structured data, while causal or explanatory questions need retrieval over accident narratives.
A single chat-style interface can hide that distinction and make answers feel more certain than they are. The project needed to route questions to the right engine, show the evidence, and keep generated prose from inventing numbers.
Users and decisions
Aviation-safety analysts and researchers are the intended users. They can use exact SQL-backed counts for structured questions and cited report retrieval for narrative questions, then decide which patterns or records merit deeper investigation.
The app is a portfolio analytics system over a public NTSB final-report dataset. It is not an official NTSB tool, aviation investigation system, or safety determination source.
One router, two accountable paths
Black Box AI routes plain-English questions to SQL, retrieval, charting, or a combined path. Structured questions use deterministic plans or guarded model-planned SQL, then return the SQL, table, chart, and audit trail. Narrative questions retrieve cited accident reports and show the source records directly.
The live app includes FastAPI, React, provider adapters, in-memory BYOK handling, query planning, SQL validation, chart validation, retrieval, answer composition, limitations, and an audit trail for each answer.
Architecture
Data flow
The ingestion pipeline parses the NTSB source data into structured accident fields and narrative records. Structured questions run through approved SQL plans or a guarded SQL generation path. Narrative questions query retrieval indexes and return cited accident records.
Every answer returns supporting artifacts: route decision, confidence, SQL when used, result table, chart spec when used, citations when used, limitations, and audit events describing how the answer was produced.
Tools used
Key features
- Question router that separates exact statistics from narrative retrieval.
- SQL-backed answers where numbers come from executed queries, not model text.
- SELECT-only SQL guard, approved schema catalog, row limits, and read-only execution pattern.
- Validated chart specs tied to the real result table.
- Cited retrieval results with official NTSB record links and probable-cause text.
- BYOK provider panel with session-scoped key handling and error redaction utilities.
- Audit trail and limitations shown with each answer.
BM25 matched semantic retrieval, against my hypothesis
The retrieval layer was scored at the accident level across semantic, BM25 keyword, and reciprocal-rank-fusion hybrid retrieval, on 17 hand-labeled questions. The result contradicted the starting hypothesis, which is the reason it is reported.
| Retriever | Recall@5 | MRR | Hit@5 |
|---|---|---|---|
| Semantic | 0.335 | 0.853 | 1.000 |
| Keyword (BM25) | 0.339 | 0.897 | 1.000 |
| Hybrid (RRF) | 0.327 | 0.902 | 1.000 |
Hybrid lost on recall. Reciprocal rank fusion is a consensus mechanism, not a best-of-both. It helps when two engines are each partially right and complementary, and it actively hurts when one is decisively right and the other decisively wrong, because the confident wrong results push the correct ones down. On the bird-strike query semantic scored 0.80 and keyword 0.40; hybrid returned 0.20. Fusion had little to resolve here because on this corpus the search term usually appears in the report text, so the two engines mostly already agreed.
Two of the three metrics carried no signal, and Hit@5 was the worst offender. It saturated at 1.000 for every engine, because the corpus is dense enough that finding something relevant in the top five is trivial. Recall@5 was also capped: three topic-saturated queries (hard landing, carburetor icing, gear collapse) each have twenty-plus relevant reports, which holds Recall@5 near 0.25 for any retriever. MRR is the only metric here that discriminates, and it separates the engines by 4.9 MRR points across a 17-question set, which is not enough to call decisively.
Conclusion, and the design decision that followed. Hybrid retrieval is insurance against query types you cannot anticipate, not a universal upgrade. On a corpus where the answer term reliably appears in the text, a single retriever is competitive, so the demo defaults to semantic and exposes all three for comparison. That was a decision driven by measurement rather than by assumption, and the measurement said the opposite of what I expected.
What would strengthen it. Seventeen queries cannot separate methods whose real differences are a few percentage points, and the set is too easy: it was written by someone who knew the corpus. A stronger set would target each engine's known failure mode deliberately, with paraphrase queries that share no vocabulary with the report, rare-identifier queries such as tail numbers and exact dates, and multi-hop questions requiring two documents. It would also report bootstrap intervals rather than point estimates. That is the next piece of work on this project.
Methodology
Appropriate use: portfolio demonstration of AI-assisted analytics, cited retrieval, SQL safety, chart validation, data-product design, and evidence-first answer presentation.
Inappropriate use: official accident investigation, regulatory decision-making, legal conclusions, aircraft safety certification, or claims beyond the loaded NTSB final-report dataset.
Exact counts and cited narrative, kept on separate paths
The finished platform shows how an AI analytics interface can stay accountable by separating exact counts from narrative evidence and exposing the machinery behind each answer.
No separation
0.902 vs 0.853MRR for hybrid retrieval against semantic on 17 hand-labeled questions. Hybrid wins on MRR and loses on Recall@5, at 0.327 against BM25's 0.339. Hit@5 saturates at 1.000 for all three and is reported only to show it carries no signal.Limitations
The loaded dataset covers NTSB final reports from 2016-2023 and notes that 2020 and 2021 are absent in this source snapshot. Recent years may lag because final reports take time to publish.
Entity resolution is partial, the labeled retrieval evaluation set is small, and the router remains an engineered routing layer that should continue to be measured as new question types appear.
What I would improve next
I would expand the labeled evaluation sets, add deeper entity resolution for aircraft manufacturers, broaden deterministic SQL plans, add more chart templates, and continue hardening the Postgres deployment with query fingerprints and validation reporting.