<!--
@RAG_CONTEXT
{
  "archivo": "README.md",
  "lineas": 75,
  "tokens_estimados": 520,
  "hash_contenido": "2a1924a921eaea602b23db0539d0ff8407901f4536f6512a0eea574f7631b865",
  "creacion": "2026-03-04",
  "modificacion": "2026-03-09",
  "tags": [],
  "descripcion_corta": "Documentación principal del CLI rag-context-indexer",
  "descripcion_larga": "README del proyecto RAG Context Indexer. Documenta instalación vía pip, uso de comandos CLI (init, run), configuración del .env para múltiples LLMs (OpenAI, Anthropic, Gemini, DeepSeek), tabla de modelos por tier (default/code), estructura JSON de la plantilla inyectada por archivo y principios de diseño: idempotencia por hash SHA256, anti vendor lock-in (solo requests), control de costos con USE_CODE_MODEL y contexto desde os.getcwd()."
}
-->
# 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

```bash
pip install rag-context-indexer
```

## Uso

```bash
# 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:

```env
# 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

| LLM       | Tier Default         | Tier Code                   |
|-----------|----------------------|-----------------------------|
| OpenAI    | gpt-4o-mini          | gpt-4o                      |
| Anthropic | claude-3-haiku       | claude-3-5-sonnet-latest    |
| Gemini    | gemini-2.5-flash     | gemini-2.5-pro              |
| DeepSeek  | deepseek-chat        | deepseek-coder              |

## Plantilla JSON inyectada por archivo

```json
{
  "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:

```bash
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é.

```bash
# 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.

```bash
# 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`:**
```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
