reducto-graph 0.3.2

Universal knowledge graph for LLMs — reduce tokens, not intelligence.

Reducto 🧠

Reduce tokens, not intelligence.

Reducto convierte tu codebase en un knowledge graph local que cualquier LLM puede consultar sin leer archivos enteros. Menos tokens, mejores respuestas, mismo resultado.

Ahorro comprobado: reduce el consumo de contexto en un 85% al pasarle al LLM solo las firmas y resúmenes que necesita, resolviendo código completo on-demand.

Qué hace

• Indexa tu proyecto — extrae funciones, clases, imports y referencias.
• Guarda todo localmente — sin base de datos, sin cuenta, sin internet.
• Expone el grafo via MCP — cualquier LLM que soporte MCP (Claude Code, Antigravity, VS Code Copilot, Cursor) lo puede consultar.

Requisitos

• Python 3.10+ (probado hasta 3.13)
• uv (recomendado) o pip

Opcional (para parsing AST real)

pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript --user

Sin esto, Reducto usa un parser regex que funciona pero es menos preciso. Con tree-sitter se detectan CALLS reales (función→función).

Instalación

Opción 1: con pip (la más simple)

pip install reducto-graph --user

Opción 2: con uv (más rápido)

uv tool install reducto-graph

Opción 3: desde GitHub directo

pip install git+https://github.com/SudacaDev/reducto.git --user

Opcional: tree-sitter para parsing AST real

pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript --user

Sin esto, Reducto funciona con regex (menos preciso). Con tree-sitter detecta CALLS reales (función→función).

Verificar

reducto --help

Actualizar a la última versión

pip install reducto-graph --upgrade --user
# o con uv:
uv tool install reducto-graph --force

Primeros pasos

# 1. Ir a tu proyecto
cd mi-proyecto

# 2. Indexar el código (primera vez)
reducto ingest . --clean

# 3. Conectar con tu IDE
reducto install
#   → te pregunta qué IDEs querés configurar
#   → o directo: reducto install --target all

# 4. Listo — abrí tu IDE y preguntale algo sobre el proyecto

Uso diario

# Re-indexar después de cambios (solo procesa archivos modificados)
reducto ingest .

# Buscar en el grafo
reducto query "auth"
reducto query "getSession" --resolve

# Ver stats de ahorro de tokens
reducto context

# Ver el grafo visualmente
reducto visualize
# → abre reducto-out/graph.html en el navegador

# Imprimir el template SKILL.md (para pegarlo en la carpeta de skills de tu agente)
reducto skill

Comandos

Comando	Qué hace
reducto ingest . [--clean]	Indexa el proyecto (--clean = rebuild completo)
reducto install [--target X]	Configura tu IDE (claude-code, antigravity, vscode, cursor, all)
reducto query "término" [--resolve]	Busca en el grafo (--resolve = carga el código fuente)
reducto context	Muestra tokens usados y ahorrados
reducto visualize	Genera un HTML interactivo del grafo
reducto skill	Imprime el template SKILL.md para tu agente (stdout)
reducto serve	Levanta el MCP server (el IDE lo usa automáticamente)
reducto skills list	Lista los Autonomous Skills generados por el LLM que esperan revisión
reducto skills show <nombre>	Imprime el código de un skill pendiente
reducto skills approve <nombre>	Aprueba y carga un skill pendiente
reducto skills reject <nombre>	Descarta un skill pendiente sin cargarlo

Autonomous Skills (Experimental) — revisión humana obligatoria

Además de consultar el grafo, un LLM conectado por MCP puede proponer una Autonomous Skill: código Python que se convierte en una tool nueva del servidor (por ejemplo, detect_god_classes). Esto pasa por la tool MCP save_autonomous_skill.

Ese código nunca se ejecuta automáticamente. El flujo es:

LLM llama save_autonomous_skill
        ↓
se guarda en .reducto/skills/pending/<nombre>.py   (solo escritura, nada se carga)
        ↓
vos revisás el código:  reducto skills show <nombre>
        ↓
   ├─ reducto skills approve <nombre>   → se mueve a .reducto/skills/, se carga y queda disponible como tool
   └─ reducto skills reject <nombre>    → se borra, nunca se ejecuta

Antes de la versión 0.2.66, save_autonomous_skill escribía el código directamente en .reducto/skills/ y lo cargaba (load_skills()) en el mismo paso, sin revisión — cualquier Python generado por el LLM corría de inmediato con los mismos permisos que tu usuario (filesystem, red, git, lo que sea). Ahora esa ejecución automática está deshabilitada; la única forma de que un skill generado corra es que un humano lo lea y lo apruebe explícitamente desde la terminal.

IDEs soportados

IDE	Config generada
Claude Code	.mcp.json + CLAUDE.md + slash commands
Antigravity (Google)	AGENTS.md + ~/.gemini/antigravity/mcp_config.json
VS Code (Copilot)	.vscode/mcp.json
Cursor	.cursor/mcp.json + .cursorrules

Cómo funciona

reducto ingest .      ← parsea el código, extrae nodos y edges, detecta comunidades
                        todo queda en reducto-out/graph.json

Tu IDE pregunta algo → LLM consulta Reducto via MCP (search_context, get_callers, etc.)
                     → Reducto busca en el grafo (metadata, ~10 tokens)
                     → Si necesita el código: resuelve el nodo (lee solo esas líneas)
                     → Lo cachea con hash SHA256 (próxima vez = 0 tokens)
                     → Si el archivo cambió: invalida el cache automáticamente

Arquitectura y Detalles Técnicos

• Parsing Estructural: Parsea .ts, .tsx, .js, .py y .md extrayendo funciones, clases, imports y calls reales (AST via tree-sitter).
• Detección de Comunidades: Agrupa automáticamente archivos relacionados usando el algoritmo de Louvain (clustering).
• Cache Inteligente (Schrödinger): Los nodos se resuelven on-demand y se cachean con hash SHA256. Si el archivo cambia, el cache se invalida automáticamente (decoherencia).
• Vistas por Observador: El LLM puede pedir solo la firma (signature), un resumen (summary), el esqueleto estructural con los cuerpos colapsados (skeleton), o el código completo (full). Cada vista se cachea independientemente, maximizando el ahorro de tokens.

Archivos generados

tu-proyecto/
  reducto-out/          ← gitignored
    graph.json          ← el grafo completo
    graph.html          ← visualización interactiva
    session_stats.json  ← stats de tokens
  .mcp.json             ← config MCP para Claude Code
  CLAUDE.md             ← routing rules para Claude Code
  AGENTS.md             ← routing rules para Antigravity
  .reducto/
    skills/             ← skills aprobados (cargados y activos)
    skills/pending/     ← skills generados por el LLM, esperando `reducto skills approve`

Troubleshooting

"tree-sitter no disponible" — Reducto funciona sin tree-sitter (usa regex), pero para CALLS reales necesitás instalarlo: pip install tree-sitter tree-sitter-python tree-sitter-javascript tree-sitter-typescript --user

"error: Failed to install entrypoint" en Windows — Cerrá Antigravity/Claude Code (tienen reducto.exe bloqueado) y reintentá.

"UnicodeEncodeError" en Windows — Setear $env:PYTHONUTF8 = "1" antes de correr Reducto, o agregarlo permanente: [System.Environment]::SetEnvironmentVariable("PYTHONUTF8", "1", "User")

El MCP no conecta en Antigravity — Verificá que ~/.gemini/antigravity/mcp_config.json tenga la entrada de reducto. Corré reducto install --target antigravity para regenerarlo.

Licencia

MIT