pilot-training-rag
# pilot-training-rag
Corpus de instrucción de pilotos y simulación, indexado para que un agente pueda
responder **con cita exacta** («14 CFR § 60.15(b)(1)», «Doc 9995 › Chapter 3 ›
3.1 BACKGROUND», «p. 3-7»), y un servidor MCP que lo expone a cualquier cliente
(Claude Desktop, Cursor, Hermes…).
Sin vector DB, sin embeddings obligatorios, sin servicios en la nube: SQLite +
FTS5 y tres ficheros de Python. 9 documentos, 2.012 páginas, 6.179 fragmentos,
11 segundos de ingesta y 16 MB de índice.
```
raw/ 9 PDF/XML (descargables con scripts/fetch.py, no versionados)
src/pilot_rag/ ingesta, índice, búsqueda, árbol y servidor MCP
scripts/ CLI: fetch, ingest, build_tree, ask, eval, smoke_mcp
eval/ 21 preguntas con cita esperada + arnés de evaluación
data/ corpus.db + árboles (generados)
pageindex/ variante on-premise con PageIndex (opcional)
docs/ arquitectura, MCP, licencias, PageIndex
```
## Arranque rápido
Requisitos: Python ≥ 3.10, `pdftotext` y `qpdf` (poppler / qpdf).
```bash
git clone https://github.com/fmanso/pilot-training-rag && cd pilot-training-rag
python3 scripts/fetch.py # ~490 MB (o sin --all: solo los pequeños)
python3 scripts/ingest.py # 11 s -> data/corpus.db
python3 scripts/build_tree.py # árboles navegables por documento
python3 scripts/eval.py # métricas de recuperación
python3 scripts/ask.py "¿Quién firma la declaración inicial de un FSTD?"
```
`scripts/ask.py` no redacta respuestas: devuelve fragmentos con su cita. La
redacción es del agente. Es deliberado — así la capa de recuperación no puede
alucinar y el agente siempre tiene el texto fuente delante.
## Qué hay dentro
| Documento | Aporta | Jurisdicción |
|---|---|---|
| 14 CFR Part 60 + apéndices A–F | QPS: tareas vs nivel de dispositivo, tolerancias, tests objetivos | FAA |
| AC 120-54A Chg 1 | Diseño instruccional de programas de simulador (AQP, ISD, LOE) | FAA |
| Aviation Instructor's Handbook (8083-9B) | Pedagogía: aprendizaje, enseñanza, evaluación | FAA |
| Airplane Flying Handbook (8083-3C) | Maniobras y procedimientos | FAA |
| Pilot's Handbook of Aeronautical Knowledge (8083-25C) | Teoría y sistemas | FAA |
| Doc 9868 PANS-TRG | Formación por competencias y cualificación de instructores | ICAO |
| Doc 9995 EBT | Competencias EBT, escenarios, grading | ICAO |
| CS-FSTD(A) + AMC/GM | Niveles FFS A–D, FTD, FNPT, BITD | EASA |
| EASA EBT Manual | Implementación práctica de EBT en la UE | EASA |
Los PDFs **no se versionan** (licencias, ver `docs/LICENSING.md`); `sources.json`
tiene URL, tamaño, licencia y para qué sirve cada uno.
## Por qué recupera bien (y dónde no)
El corpus está en inglés y las preguntas llegan en castellano. BM25 no cruza
idiomas, así que el repo lleva un **léxico de dominio ES→EN** (`src/pilot_rag/text.py`)
que expande la consulta. Eso es lo que mueve la aguja:
| configuración | hit@1 | hit@5 | MRR@10 | documento correcto |
|---|---|---|---|---|
| BM25 puro | 0.33 | 0.38 | 0.363 | 0.47 |
| BM25 + expansión léxica | 0.57 | 0.90 | 0.737 | 1.00 |
| híbrido (expansión + rerank + atajo estructural) | 0.57 | 0.90 | 0.737 | 1.00 |
21 preguntas, `python3 scripts/eval.py --verbose` para ver cada fallo.
Dos cosas que sí aportan estructura:
* **Chunks con ruta de cita** en vez de ventanas ciegas: el XML del eCFR ya trae
la jerarquía (`§ 60.15` → `(b)` → `(1)`), y los PDFs se parten por sus
marcadores o por la numeración «capítulo-página» de la FAA.
* **Atajo estructural**: si la pregunta cita una sección o tabla («60.25»,
«Tabla A1B»), esa sección va primera aunque el texto no repita las palabras.
Y una que no: el rerank léxico empata con BM25 en este conjunto. Se mantiene
porque es donde se inyectan señales que FTS5 no expresa (cobertura ponderada por
IDF, frase exacta, coincidencia de cita) sin tocar la consulta.
**Limitaciones conocidas**: preguntas puramente semánticas («¿cada cuánto se
revisa?» cuando el texto dice «four evenly spaced inspections») siguen fallando;
el AC 120-54A trae algunos títulos de sección que vienen del índice embebido del
PDF y no del texto (la cita de página sigue siendo correcta). Para eso está
`docs/PAGEINDEX.md`: recuperación por razonamiento sobre el árbol, a cambio de un
LLM por consulta.
## MCP
```bash
python3 -m pilot_rag.mcp_server # stdio
PILOT_RAG_TRANSPORT=http python3 -m pilot_rag.mcp_server # streamable-http
```
Seis herramientas: `search_corpus`, `lookup_citation`, `get_chunk`,
`get_document_structure`, `get_page_content`, `list_documents`.
Claude Desktop / Cursor / Hermes: ver `docs/MCP.md` (configuración lista para
copiar, contratos de cada tool y el prompt de sistema recomendado).
Verificación real de que habla MCP:
```bash
$ python3 scripts/smoke_mcp.py
servidor: pilot-training-rag v1.0.0
tools (6): list_documents, search_corpus, get_chunk, lookup_citation, get_document_structure, get_page_content
search_corpus -> 3 resultados
lookup_citation('60.19') -> 16 chunks; primero: 14 CFR § 60.19
get_document_structure -> 109 nodos de nivel<=2
SMOKE: OK
```
## PageIndex on-premise
`pageindex/` monta el árbol con la librería real de PageIndex (MIT) contra un
endpoint compatible con OpenAI — Ollama, vLLM o cualquier API. Nuestro
`get_document_structure` devuelve **el mismo contrato** (title / start_index /
end_index / summary / nodes), así que un agente puede cambiar de motor sin tocar
el prompt. Detalles y veredicto en `docs/PAGEINDEX.md`.
## Licencia
Código MIT (`LICENSE`). Los documentos conservan la suya: FAA es dominio público,
EASA permite reutilización con atribución, ICAO está bajo copyright — por eso el
repo trae descargadores, no PDFs. `docs/LICENSING.md` lo detalla documento a documento.
TDQS
Scored across 6 tools
The tools are mostly clearly separated by purpose: corpus search, citation lookup, chunk retrieval, document listing, structure browsing, and page extraction. There is minor overlap between get_chunk and get_page_content as context-expansion tools, and between search_corpus and lookup_citation as retrieval paths, but descriptions make the intended use reasonably clear.
All tool names follow a consistent snake_case verb_noun pattern: list_documents, search_corpus, get_chunk, lookup_citation, get_document_structure, get_page_content. The verb choices vary appropriately by action while maintaining a predictable convention.
Six tools is well-scoped for a RAG retrieval server. Each tool has a distinct retrieval role: discovery, search, chunk context, citation lookup, structure navigation, and page extraction.
The surface covers the core RAG retrieval lifecycle: discovering documents, searching, expanding chunks, resolving citations, inspecting structure, and reading page ranges. Minor gaps exist, such as no explicit document-level metadata retrieval beyond list_documents, but these are not likely to block most agent workflows.