Skip to main content
Glama
pilot-training-rag

pilot-training-rag

by fmanso

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).

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.

Related MCP server: PDF-RAG

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

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:

$ 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.

Available Tools

6 tools
get_chunkC

Devuelve un fragmento y sus contiguos (más contexto).

Inputs: chunk_id (required), neighbours.

get_document_structureC

Árbol de secciones del documento, con páginas y resumen de cada nodo.

Inputs: doc_id (required), max_level.

get_page_contentC

Texto de un rango de páginas, p. ej. pages='12-14'.

Inputs: pages (required), doc_id (required). Returns: result

list_documentsC

Documentos disponibles, jurisdicción y número de fragmentos.

Inputs: no named parameters. Returns: result

lookup_citationC

Acceso estructural: '60.15', '§ 60.25(b)', 'App. A', 'Table A1B'.

Inputs: citation (required). Returns: result

search_corpusA

Busca en el corpus (castellano o inglés) y devuelve fragmentos citables.

Args: query: pregunta o palabras clave, en cualquier idioma. k: número de fragmentos (1-20). doc_ids: opcional, limita a esos documentos.

Inputs: query (required), k, doc_ids. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables semantic retrieval over locally indexed PDF manuals and books, exposing tools to list available sources and search excerpts by query with page, chapter, source, and relevance metadata.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to search local component-manual corpora via hybrid semantic, full-text, and substring retrieval with table recognition and OCR fallback for scanned pages. Provides tools for literal/regex grepping, reading single or multiple pages, navigating bookmarks and outlines, listing categories and indexed files, and checking index and dependency status.
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to search a curated catalog of practical AI books and retrieve book records, topics, reading paths, free chapters, glossary definitions, and verified claim citations. It also supports checking claims and generating citations from the catalog’s published free material.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Exposes seven read-only tools that let an existing chat model search a private, incrementally ingested PDF library, fetch full parent sections with provenance and hash validation, check evidence completeness, audit literal quote anchors, view original PDF pages, and explore a frozen citation snapshot. It provides source-first retrieval and provenance without invoking another model or certifying scientific conclusions.
      7
      1
      MIT