0victorr0/graph-rag-api

graph-rag-api

API multi-tenant de Graph-RAG sobre LightRAG + Gemini + FastAPI. Cada cliente (tenant) tiene su propio grafo de conocimiento construido desde un MDFile, y un agente de WhatsApp consulta esa base por HTTP.

Hermano de demo-ia (text-to-SQL). Este es el sistema bound-to-production: una sola API sirve N clientes.

Cómo funciona — vista de pájaro

┌─────────────┐
│ Cliente     │
│ WhatsApp    │
└──────┬──────┘
       │ mensaje
       ▼
┌─────────────────────┐      ┌────────────────────────┐
│ n8n (orquestador)   │      │ Gemini 2.5 Flash       │
│                     │◄────►│ (razonamiento agente)  │
│ • Memoria 10 msgs   │      └────────────────────────┘
│ • Reglas de prompt  │
│ • Tool: kb_tvs      │
└──────┬──────────────┘
       │ HTTPS + Bearer
       ▼
┌──────────────────────────────────────────────┐
│ HF Spaces: graph-rag-api (FastAPI)           │
│                                              │
│  ┌────────────────────────────────────────┐  │
│  │ LightRAG engine (por tenant)           │  │
│  │  • Grafo (entidades + relaciones)      │  │
│  │  • Vector store (embeddings)           │  │
│  │  • KV store (chunks originales)        │  │
│  └────────────────┬───────────────────────┘  │
│                   │ retrieve_only            │
│                   ▼                          │
│  ┌────────────────────────────────────────┐  │
│  │ Gemini 2.0 Flash                       │  │
│  │ Extracción de facts atómicos del KB    │  │
│  └────────────────┬───────────────────────┘  │
└───────────────────┼──────────────────────────┘
                    │ facts[] + entities[]
                    ▼ JSON
              de vuelta a n8n
                    │
                    ▼
              respuesta al cliente

Flujo paso a paso

1. 1.Cliente manda mensaje WhatsApp → llega a n8n.
2. 2.n8n consulta memoria conversacional (últimos 10 mensajes con mismo sessionId).
3. 3.n8n llama al agente Gemini 2.5 Flash con sistema-prompt + memoria.
4. 4.El agente decide: ¿llamo a la herramienta consultar_kb_tvs? Regla #1 dice siempre sí (excepto saludo).
5. 5.Tool HTTP → POST a HF Spaces /agent/run con la pregunta literal del cliente + Bearer token.
6. 6.API localiza el tenant, carga su LightRAG (o usa el cache).
7. 7.LightRAG consulta el grafo: trae entidades + relaciones + chunks relevantes.
8. 8.Gemini 2.0 Flash extrae los facts atómicos pertinentes del contexto crudo.
9. 9.Devuelve JSON: { facts: [...], entities: [...], no_match: false, raw_context: "..." }.
10. 10.Agente Gemini en n8n recibe los facts y formula la respuesta al cliente con tono natural.
11. 11.Cliente recibe el mensaje en su WhatsApp.

Stack

Tope práctico free tier: ~330 mensajes de cliente/día (limita la cuota diaria de Gemini 2.5 Flash: 1,000 RPD ÷ 3 calls/msg).

Quickstart (desarrollo local)

# 1. Instalar
uv venv && uv pip install -e .

# 2. Configurar .env (copiar de .env.example y poner GEMINI_API_KEY)
cp .env.example .env

# 3. Soltar MDFile del tenant
mkdir -p kb_sources/tvs
cp /path/to/tvs_master_kb.md kb_sources/tvs/

# 4. Construir el grafo
uv run graph-rag-index --tenant tvs

# 5. Levantar la API
uv run graph-rag-api
# → http://127.0.0.1:8002/docs (Swagger UI)

Agregar un nuevo tenant

1. 1.mkdir -p kb_sources/<tenant_id>/
2. 2.Soltar *.md adentro
3. 3.uv run graph-rag-index --tenant <tenant_id> (local) o curl POST /admin/reindex (en la nube)
4. 4.Llamar POST /agent/run con {"prompt": "...", "tenant": "<tenant_id>"}

Los tenant_id deben matchear ^[a-z0-9][a-z0-9_-]{0,63}$ (anti path-traversal).

Endpoints

Auth: bearer tokens en Authorization: Bearer <token>.

Despliegue en HF Spaces

Ver DEPLOY.md para guía completa (HTTPS, secrets, dataset privado).

Comandos rápidos:

# Re-indexar tenant en producción
curl -X POST https://USER-graph-rag-api.hf.space/admin/reindex \
  -H "Authorization: Bearer $REINDEX_TOKEN" \
  -d '{"tenant": "tvs"}'

# Verificar estado
curl https://USER-graph-rag-api.hf.space/health

# Consulta de prueba
curl -X POST https://USER-graph-rag-api.hf.space/agent/run \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "horario sucursales", "tenant": "tvs"}'

Privacidad y seguridad

• —El KB nunca vive en el repo público. Está en HF Dataset privado.
• —El container lo baja al arrancar (_hydrate_from_hf_dataset) usando HF_TOKEN como secret.
• —kb_sources/*/ está en .gitignore para evitar commits accidentales.
• —Bearer tokens son secrets cifrados en HF Spaces (no en el código).
• —Endpoints /admin/* requieren token separado (REINDEX_TOKEN).
• —Logs redactan automáticamente Bearer xxx para no filtrar tokens.
• —Rate limit slowapi a 60 req/min por IP.

Costo

Tier gratuito cubre hasta ~330 mensajes de cliente/día. Más allá:

• —Gemini billing activado: ~$0.001-0.003 USD/mensaje → ~$30-90/mes para 1,000 msg/día
• —HF Persistent Storage: $5/mes (evita re-hidratar al despertar)
• —HF CPU Upgrade: $36/mes (4 vCPU, sin sleep)

Documentación adicional

• —`docs/PRUEBAS.md` — Historial de todas las pruebas con error encontrado y corrección aplicada.
• —`CLAUDE.md` — Contexto para Claude Code (memoria de proyecto).
• —`DEPLOY.md` — Guía paso a paso para deploy en HF Spaces.

License

Proprietary — AInnovation.