RAG Context Indexer

Indexador de contexto enriquecido para optimización de RAG en LLMs. Motor agnóstico que inyecta metadatos semánticos en el código fuente y genera un rag-indexer.json para que los LLMs entiendan arquitecturas complejas ahorrando millones de tokens.

Instalación

pip install rag-context-indexer

Uso

# En la raíz de tu proyecto:

# 1. Scaffold: inyecta bloques @RAG_CONTEXT vacíos + genera .ai/prompts/
rag-indexer prepare

# 2. Instalar el pre-commit hook (una sola vez)
rag-indexer init

# 3. Ejecutar indexación manual (requiere API key)
rag-indexer run

Configuración

Crea un archivo .env en la raíz de tu proyecto:

# LLM activo: openai | anthropic | gemini | deepseek
ACTIVE_LLM=openai

# API Keys (solo la del LLM activo es necesaria)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
DEEPSEEK_API_KEY=sk-...

# Opcional: usar modelos de razonamiento pesados
USE_CODE_MODEL=false

Modelos soportados

Plantilla JSON inyectada por archivo

{
  "archivo": "ruta/relativa/al/archivo.ext",
  "lineas": 0,
  "tokens_estimados": 0,
  "hash_contenido": "sha256_del_codigo_limpio",
  "creacion": "YYYY-MM-DD",
  "modificacion": "YYYY-MM-DD",
  "tags": ["dependencia1", "exportacion_principal"],
  "descripcion_corta": "Máx 50 chars.",
  "descripcion_larga": "100-500 chars, técnico."
}

Plantillas generadas por rag-indexer prepare

Además de los bloques @RAG_CONTEXT en cada archivo, prepare genera en .ai/prompts/:

• 01_buenas_practicas.md — Constitución de ingeniería: Conventional Commits, Clean Code, seguridad, planificación, protocolo de confirmación con 3 banderas (RESUMEN / TECNICA / RESUMDA)
• 02_menu_sesion.md — Menú de 15 opciones para gestionar sesiones con la IA (solo se crea si no existe, para que puedas personalizarlo)

Convención de commits enriquecida

Para máxima trazabilidad, los commits pueden incluir un JSON body con campos opcionales:

git commit -m "$(cat <<'EOF'
fix(modulo): descripción del fix

{
  "resuelve": "Descripción del bug cerrado",
  "antes": "Comportamiento anterior (síntoma visible)",
  "deuda_tecnica": "Limitación pendiente (si aplica)"
}
EOF
)"

Estos campos son parseados automáticamente por rag-indexer trace (v2.0.0, próximamente).

Sistema de Trazabilidad (rag-indexer trace)

Vincula cada commit con la decisión técnica original que lo causó. Ideal para debugging: dado un bug en la línea N de un archivo, encuentra exactamente qué interacción con la IA generó ese cambio y por qué.

# 1. Inicializar (una sola vez por proyecto)
rag-indexer trace-init

# 2. A partir de aquí, cada `git commit` actualiza el contexto automáticamente

# 3. Procesar historial existente
rag-indexer trace-backfill

# 4. Query de trazabilidad manual
git log -L 42,42:src/mi_archivo.py --pretty="%h %s"
grep -r "HASH_ENCONTRADO" .ai/contexto/

Genera en .ai/contexto/:

• contexto_activo.json — últimas 25 interacciones con commits y decisiones técnicas
• contexto_resumen.json — índice de bloques históricos
• archivo/contexto_NNN.json — bloques archivados (25 interacciones c/u)

Auto-detección de sesiones: detecta automáticamente el directorio de sesiones de Claude Code (~/.claude/projects/{slug}/). Para otras IAs, establece RAG_TRACE_SESSIONS_DIR=/ruta/manual en .env.

Persistencia de sesión (rag-indexer tmux-*)

Mantiene la sesión de tu AI CLI activa aunque se caiga la terminal o se corte la conexión SSH. Ahorra tokens al no tener que re-explicar el contexto a la IA en cada reconexión.

# 1. Configurar e inicializar (detecta/instala tmux automáticamente)
rag-indexer tmux-init

# 2. Conectar o reconectar a la sesión del proyecto
rag-indexer tmux-attach

# 3. Ver estado de la sesión actual
rag-indexer tmux-status

# 4. Listar todas las sesiones rag-indexer activas
rag-indexer tmux-list

# 5. Eliminar la sesión del proyecto
rag-indexer tmux-del-session

Las sesiones se nombran {directorio}___rag-indexer (ej. mi-proyecto___rag-indexer) y tienen dos ventanas predefinidas:

• [AI] — lanza tu AI CLI automáticamente (RAG_AI_CMD=claude por defecto)
• [Shell] — terminal bash limpia para git, logs y comandos

Variables .env:

RAG_TMUX_ENABLED=true
RAG_AI_CMD=claude          # claude | cursor | aider | cualquier CLI
RAG_TMUX_SESSION=mi-proyecto___rag-indexer   # auto-generado, sobreescribible

⚠️ Las sesiones tmux no persisten reboots. Tras reiniciar el servidor, ejecuta rag-indexer tmux-attach para recrear la sesión.

Gestores de paquetes soportados para instalación automática: apt, apt-get, dnf, yum, pacman, brew.

Principios de diseño

• Idempotencia: el hash SHA256 del código limpio evita llamadas innecesarias a la API
• Anti vendor lock-in: sin SDKs de terceros, solo requests vía REST
• Control de costos: variable USE_CODE_MODEL alterna entre tiers de modelos
• Contexto de ejecución: siempre escanea os.getcwd(), no la ubicación del script

Licencia

MIT