RAG · Expert chatbot on NTC CDMX (2004 / 2017 / 2023)

Retrieval-Augmented Generation system over the Complementary Technical Standards of the Mexico City Building Regulations, with hybrid search (BM25 + multilingual embeddings + RRF) and citations by edition and clause.

Structure

RAG/
├── src/
│   ├── config.py        # rutas y mapeo PDF → (edición, norma)
│   ├── extract.py       # PDF → páginas de texto por norma (temp/extracted_text/)
│   ├── structure.py     # páginas → secciones X.Y.Z (data/corpus/*.json)
│   ├── index_build.py   # secciones → catálogo + BM25 + embeddings (data/index/)
│   ├── retrieve.py      # retriever híbrido (BM25 + embeddings + RRF + numeral)
│   ├── answer.py        # generador de respuestas con LLM (DeepSeek V4 Flash)
│   ├── calc.py          # cálculos validados (viento, sismo, combinaciones)
│   ├── evaluate.py      # evaluación recall@k con el dataset de 21k Q&A
│   └── finetune_gen.py  # genera dataset RAG-formateado para fine-tune del generador
├── app/app.py           # interfaz web (Streamlit)
└── scripts/run_all.py   # orquesta el pipeline completo

MCP Server (for opencode, codex, Claude Desktop, etc.)

The project is exposed as an MCP server with three tools:

Automatic installation (registers the server in opencode and/or codex):

.venv\Scripts\python.exe scripts\install_mcp.py            # opencode + codex
.venv\Scripts\python.exe scripts\install_mcp.py --opencode # solo opencode
.venv\Scripts\python.exe scripts\install_mcp.py --codex    # solo codex

Restart opencode/codex and the RAG will be available as tools (answer_ntc, etc.). The server reads the provider API key from RAG/.env, the corresponding environment variable, or ~/.config/ntc-cdmx/.env.

One-command installation (GitHub + uv)

uvx --from git+https://github.com/Sobrio25/ntc-cdmx-mcp ntc-cdmx-install

That command installs and registers the MCP in opencode, Codex, Command Code, and Kilo Code. Restart the clients and answer_ntc, search_ntc and get_section will be available. The index (BM25 + embeddings) travels inside the package; the provider API key is configured in ~/.config/ntc-cdmx/.env.

To install only the executable:

uv tool install git+https://github.com/Sobrio25/ntc-cdmx-mcp

Test the server manually:

ntc-cdmx                                     # stdio (modo instalado)
.venv\Scripts\python.exe src\mcp_server.py   # stdio (modo desarrollo)

Pipeline

# 1) Extraer y estructurar e indexar
.venv/Scripts/python.exe scripts/run_all.py --steps extract structure index

# 2) Evaluar recall del retriever (muestra 400 preguntas del dataset de 21k)
.venv/Scripts/python.exe scripts/run_all.py --steps eval

# 3) Interfaz web
.venv/Scripts/python.exe -m streamlit run app/app.py

Configure the LLM

Responses use DeepSeek V4 Flash. Configure the provider/API key in src/answer.py (LLM_MODEL, LLM_BASE_URL). Without a key, the chatbot responds with the retrieved sections (no LLM), useful for debugging.

Validated calculations (src/calc.py)

If the question asks for a calculation (e.g., "calculate the wind pressure for Vz=35 m/s"), the engine detects it and uses a formula verified against the text of the standard, without going through the LLM. Included calculators:

If data is missing, the chatbot explicitly asks for it.

Generator fine-tuning (src/finetune_gen.py)

Generates a dataset in chat format where each example includes the retrieved context (so that the generator learns to answer from the context, rather than memorizing the standards):

.venv/Scripts/python.exe src/finetune_gen.py --max 2000 --top_k 8 --require_all

Automatically filters out examples whose "gold" answer is NOT supported by the retrieved context (missing cited clauses → discarded).

Evaluation

The evaluate.py module uses your dataset from Documents\Fine_Tunning\NTC_CDMX\dataset.jsonl: for each question with clauses cited in the "gold" answer, it checks that the clause appears among the retrieved sections.

Reference result (sample of 164 questions with citations, top-6): recall@q ≈ 0.58. Approximately 18% of the clauses cited by the dataset do not exist in the corpus of their edition (possible erroneous citations in the dataset or extraction gaps).

Technical notes

• The 2004 and 2017 editions come in official gazettes (several documents per PDF); the boundaries of each standard are mapped in src/config.py.

• The chunking is by numbered section (never by paragraph), preserving formulas/tables.

• Each section carries metadata {edición, norma, numeral, página} for precise citation.

• The 2023 PDFs have names with corrupt characters on disk; the extractor resolves them by numeric prefix.