AIRMAN is a highly specialized, hallucination-resistant Retrieval-Augmented Generation (RAG) web application tailored for aviation manuals and documentation. It employs a Hybrid RAG approach—combining semantic vector search with exact-match keyword search (BM25)—and utilizes a custom prompt safeguard to ensure the LLM strictly grounds its answers in the provided aviation manuals without injecting external, potentially fatal, unverified knowledge.
The UI is built with a custom Risograph-inspired aesthetic, combining sharp typography, misregistration accents, and a distinct tactical feel suitable for flight documentation.
- Hybrid Search Pipeline: Merges Local Vector Similarity (Transformers.js) with BM25 Keyword Search for ultra-precise retrieval, excelling at both conceptual queries and exact part number/acronym lookups.
- 100% Local Embeddings: Uses
Xenova/all-MiniLM-L6-v2via ONNX Runtime to generate 384-dimensional embeddings directly in Node.js. No rate limits, no API costs, and instant ingestion. - Hallucination Safeguards:
- Prompt Enforcement: The LLM is explicitly forbidden from employing pre-existing weights outside the retrieved chunks.
- Refusal Filtering: Enforces strict "I don't know" protocols when information is absent from the manuals.
- Blazing Fast Generation: Uses the Groq API (Llama 3 8B / 70B) for instant LLM synthesis and reranking.
- Live Ingestion Dashboard: Visual tracking of the 4-phase ingestion process (Parsing → Chunking → Local Embedding → Writing Indexes).
=======================================================================
PHASE 1: DATA INGESTION & INDEXING
=======================================================================
[ PDF Manuals ]
│
▼ (pdfjs-dist)
[ Text Extraction ]
│
▼ (Recursive Character Split)
[ Text Chunks ]
│
┌───┴────────────────────────────┐
│ │
▼ (Transformers.js) ▼ (wink-bm25)
[ Local Embeddings ] [ Keyword Tokens ]
[ (384-dim Vector) ] │
│ │
▼ (batchInsertItems) ▼
[( Vectra Vector DB )] [( BM25 Keyword DB )]
=======================================================================
PHASE 2: QUERY & HYBRID RETRIEVAL
=======================================================================
[ User Query ]
│
┌──────────────┴──────────────┐
│ │
▼ (Transformers.js) ▼ (Tokenization)
[ Query Embedding ] [ Query Keywords ]
│ │
▼ ▼
[( Vectra Vector DB )] [( BM25 Keyword DB )]
│ │
▼ ▼
[ Semantic Results ] [ Exact Match Results ]
│ │
└──────────────┬──────────────┘
│
▼
[ Combine & Deduplicate ]
│
▼ (Groq API)
[ LLM Reranker (Top N) ]
=======================================================================
PHASE 3: GENERATION & SAFEGUARDS
=======================================================================
│
▼
[ Prompt Builder ]
(Injects context + Strict Rules)
│
▼
[ Groq LLM ]
│
▼
[ Refusal Filter ]
(Forces "I don't know" if not in text)
│
▼
[ Final Answer ]
(User UI)
| Layer | Technology | Purpose |
|---|---|---|
| Framework | Next.js 15 (App Router) | Full stack application (frontend + backend APIs) |
| Language | TypeScript | End-to-end type safety |
| Styling | Tailwind CSS v4 | Rapid UI development with custom Risograph theme |
| PDF Parsing | pdfjs-dist |
Extracting raw text and maintaining page numbers |
| Embeddings | Transformers.js (all-MiniLM) |
Converting text to 384-dimensional semantic vectors (100% local) |
| Vector Database | Vectra | Storing and performing semantic cosine similarity searches on disk |
| Keyword Database | wink-bm25-text-search |
Storing and performing exact-match keyword retrieval |
| LLM Provider | Groq API (llama-3.3-70b) |
Ultra-fast semantic reranking and grounded answer generation |
| Icons | Lucide React | Clean, consistent SVG iconography |
- Node.js 18+ installed.
- A Groq API Key. You can get one for free at console.groq.com.
Clone the repository and install dependencies:
# Navigate to the project directory
cd "Aviation Rag"
# Install all required packages
npm installCreate a .env.local file in the root of your project and add your Groq API Key:
GROQ_API_KEY=your_groq_api_key_here
NEXT_PUBLIC_GROQ_API_KEY=your_groq_api_key_here(Note: Gemini was previously used for embeddings but was replaced with local Transformers.js. You no longer need a Gemini API key.)
Start the Next.js server:
npm run devOpen http://localhost:3000 in your browser.
To teach the AI about your specific aircraft manuals:
- Add PDFs: Drop your aviation PDF manuals (e.g.,
Instruments.pdf,POH.pdf) into thedata/pdfs/folder. - Ingest: Open the app in your browser and click the "INGEST PDF DOCUMENTS" button in the System Status Panel.
- Wait for processing: The system will parse the text, split it into chunks, generate local embeddings (at roughly ~500 chunks per minute), and write the vector and BM25 indexes to disk.
- Ready: Once the status badge turns green (
INDEX READY), you can start asking questions!
The vector indexes are stored locally in data/index/.
The project includes an automated evaluation script to test the accuracy and refusal capabilities of the RAG pipeline against a set of predetermined questions.
To run the benchmark:
npm run evaluateThis will run through a matrix of queries and generate a detailed Markdown report at evaluation/report.md detailing the system's Precision, Recall, and Strictness.
The UI utilizes a bespoke "Risograph" design system configured directly in app/globals.css. It features:
bg-riso-paper: Off-white textured background.text-riso-ink: Off-black deep text for stark contrast.riso-pink,riso-blue,riso-yellow,riso-teal: CMYK-inspired accent colors used for status badges, progress bars, and hover states.
This software is for demonstration and educational purposes only. Do not use AI-generated outputs as a substitute for official aircraft flight manuals (AFM), Pilot's Operating Handbooks (POH), or certified flight instruction. Always consult official documentation for flight operations.