RAGMeUp Local

Chat RAG local con Ollama, servidor MCP, API FastAPI, UI web ligera y carga diferida de componentes pesados.

El objetivo del paquete es permitir consultar documentos locales con un modelo Ollama, manteniendo una operación simple desde CLI o navegador. La arquitectura expone tres superficies de uso: CLI ragmeup, interfaz web en /ui y herramientas MCP para clientes compatibles.

Qué incluye

| Componente | Descripción | |---|---| | ragmeup | CLI principal para instalar, diagnosticar, servir, indexar y preguntar. | | start.sh | Script de compatibilidad con los comandos originales. | | server/api_server.py | API FastAPI con healthcheck, endpoints Ollama RAG y UI web. | | server/mcp_server.py | Servidor MCP con tools RAG y tools Ollama RAG. | | server/ollama_rag.py | Motor RAG local simple usando documentos del directorio configurado. | | server/deferred_loader.py | Carga diferida del backend RAG clásico. | | README-USABILITY.md | Detalle de la capa UX. | | README-DEFERRED-TOOL-LOADING.md | Detalle técnico de deferred tool loading. |

Requisitos

| Requisito | Versión recomendada | |---|---| | Python | 3.12 o superior | | Ollama | Instalado y ejecutándose localmente | | Sistema operativo | macOS, Linux o Windows con WSL/Git Bash recomendado |

Comprueba que Ollama responde:

ollama serve

En otra terminal, descarga el modelo configurado por defecto:

ollama pull gemma4:latest

También puedes usar otro modelo exportando OLLAMA_MODEL.

export OLLAMA_MODEL=llama3.1:8b

Inicio rápido

Desde la raíz del proyecto:

chmod +x ragmeup start.sh
./ragmeup setup
./ragmeup pull-model
./ragmeup serve

Abre la UI:

http://127.0.0.1:8000/ui

Desde la UI puedes ver estado, subir documentos .txt, .md, .csv o .json, reindexar, preguntar y revisar fuentes.

Uso por CLI

| Comando | Uso | |---|---| | ./ragmeup setup | Prepara el entorno local mínimo. | | ./ragmeup doctor | Ejecuta diagnóstico accionable. | | ./ragmeup status | Muestra estado de API, modelo, corpus y deferred loading. | | ./ragmeup pull-model | Descarga el modelo Ollama configurado. | | ./ragmeup serve | Levanta API + UI. | | ./ragmeup index | Reindexa el corpus actual. | | ./ragmeup index ./docs | Reindexa usando una ruta concreta como corpus. | | ./ragmeup ask "pregunta" | Ejecuta pregunta RAG completa. | | ./ragmeup retrieve "consulta" | Recupera chunks sin llamar al LLM. | | ./ragmeup mcp-config | Imprime configuración MCP lista para pegar. |

Ejemplo:

./ragmeup status
./ragmeup index ./server/data/ollama-demo
./ragmeup ask "¿Qué recomienda el documento sobre churn enterprise?"
./ragmeup retrieve "seguridad despliegues locales"

Uso por API

Arranca el servidor:

./ragmeup serve

Consulta estado:

curl http://127.0.0.1:8000/health

Reindexa documentos:

curl -X POST http://127.0.0.1:8000/ollama/reindex

Pregunta al RAG:

curl -X POST http://127.0.0.1:8000/ollama/chat \
  -H "Content-Type: application/json" \
  -d '{"question":"¿Qué dice el documento sobre seguridad?","top_k":4}'

Recupera fuentes sin generar respuesta:

curl -X POST http://127.0.0.1:8000/ollama/retrieve \
  -H "Content-Type: application/json" \
  -d '{"question":"seguridad despliegues locales","top_k":4}'

Uso como servidor MCP

Para MCP por stdio:

./ragmeup mcp-config

Pega la configuración resultante en tu cliente MCP. La entrada usa start.sh mcp-stdio por compatibilidad.

Tools MCP principales:

| Tool | Función | |---|---| | mcp_runtime_status | Muestra si los motores están cargados sin forzar inicialización. | | ollama_rag_status | Estado del motor Ollama RAG. | | ollama_rag_reindex | Reindexa documentos locales. | | ollama_rag_retrieve | Recupera chunks relevantes. | | ollama_rag_chat | Pregunta RAG completa con fuentes. | | rag_chat | Chat contra el backend RAG clásico. | | retrieve_documents | Recuperación clásica de documentos. | | add_document | Añade documento al backend clásico. | | corpus_summary | Resume el corpus clásico. |

Deferred tool loading

La carga diferida evita importar o inicializar componentes pesados al arrancar. En el arranque, la API y el servidor MCP registran rutas y tools, pero el backend RAG clásico y el motor Ollama RAG solo se inicializan cuando una operación real los necesita.

Puedes comprobarlo con:

./ragmeup status
curl http://127.0.0.1:8000/health

Campos relevantes:

| Campo | Significado | |---|---| | deferred_tool_loading | Indica si la carga diferida está habilitada. | | rag_backend_loaded | Indica si el backend RAG clásico ya fue cargado. | | ollama_engine_loaded | Indica si el motor Ollama RAG ya fue inicializado. |

Configuración

Variables principales:

| Variable | Valor por defecto | Descripción | |---|---|---| | OLLAMA_MODEL | gemma4:latest | Modelo usado para generación. | | OLLAMA_HOST | http://127.0.0.1:11434 | URL del servidor Ollama. | | OLLAMA_RAG_DATA_DIR | server/data/ollama-demo | Directorio del corpus local. | | OLLAMA_RAG_TOP_K | 4 | Número de chunks recuperados por defecto. | | OLLAMA_RAG_CHUNK_WORDS | 260 | Tamaño aproximado de chunk en palabras. | | OLLAMA_RAG_CHUNK_OVERLAP | 40 | Solapamiento entre chunks. | | DEFERRED_TOOL_LOADING | True | Activa carga diferida. | | API_PORT | 8000 | Puerto de la API FastAPI. |

Ejemplo:

export OLLAMA_MODEL=llama3.1:8b
export OLLAMA_RAG_DATA_DIR="$PWD/docs"
./ragmeup serve

Windows

En Windows, el shebang de ragmeup no se ejecuta igual que en macOS/Linux desde PowerShell o CMD. Opciones recomendadas:

| Entorno | Comando | |---|---| | WSL | ./ragmeup status | | Git Bash | ./ragmeup status | | PowerShell/CMD | py -3 ragmeup status |

Si quieres una experiencia nativa en PowerShell, crea un archivo ragmeup.cmd junto a ragmeup con este contenido:

@echo off
py -3 "%~dp0ragmeup" %*

Luego ejecuta:

.\ragmeup.cmd status

Seguridad

Por defecto, los servicios deben ejecutarse en 127.0.0.1. No expongas Ollama, la API FastAPI ni el endpoint MCP directamente a internet sin autenticación, TLS, rate limiting y segmentación de red.

No guardes claves API, tokens o secretos dentro del corpus de prueba. Los documentos subidos pueden aparecer como fuentes recuperadas en respuestas RAG.

Solución de problemas

| Síntoma | Causa probable | Acción | |---|---|---| | API no responde | El servidor no está levantado | Ejecuta ./ragmeup serve. | | Connection refused contra Ollama | Ollama no está corriendo | Ejecuta ollama serve. | | Modelo no encontrado | El modelo no fue descargado | Ejecuta ./ragmeup pull-model o ollama pull <modelo>. | | 0 chunks | No hay documentos válidos en el corpus | Sube documentos desde /ui o usa ./ragmeup index ./docs. | | Respuestas pobres | Corpus insuficiente o chunks no relevantes | Usa ./ragmeup retrieve "consulta" para auditar fuentes. | | MCP HTTP devuelve 406 con curl | El endpoint MCP usa streamable HTTP | Usa un cliente MCP compatible, no curl simple. |

Flujo recomendado de validación

./ragmeup doctor
./ragmeup status
./ragmeup index ./server/data/ollama-demo
./ragmeup ask "¿Qué documentos están indexados?"

La validación correcta debe mostrar API operativa, modelo configurado, chunks indexados y respuestas con fuentes visibles.

MCP Servers