Metadata-Version: 2.4
Name: rag-context-indexer
Version: 1.9.0
Summary: Indexador de contexto enriquecido para optimización de RAG en LLMs con soporte Agentic Scaffolding, Auto-Sync y Sistema de Trazabilidad
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: pathspec
Requires-Dist: python-dotenv
Dynamic: license-file

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

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