MCP RAG Server
by caagudelo
README.md
# Servidor RAG Personal con MCP
Este proyecto implementa un servidor compatible con el Protocolo de Contexto de Modelo (MCP) que dota a los clientes de IA (como Cursor, Claude for Desktop, etc.) de una capacidad de Recuperación Aumentada por Generación (RAG). Permite al modelo de lenguaje acceder a una base de conocimiento privada y local, alimentada por tus propios textos y documentos.
## ✨ Características
- **Memoria Persistente para tu IA:** "Enseña" a tu IA nueva información que recordará entre sesiones.
- **🆕 Interfaz Gráfica de Usuario (GUI):** Una aplicación de escritorio intuitiva con sistema de scripts organizados para facilitar la instalación y ejecución.
- **🚀 Procesamiento Avanzado de Documentos:** Alimenta la base de conocimiento con **más de 25 formatos de archivo** incluyendo PDF, DOCX, PPTX, XLSX, imágenes (con OCR), correos electrónicos, y más.
- **🧠 Procesamiento Inteligente con Unstructured:** Sistema de procesamiento de documentos de nivel empresarial que preserva la estructura semántica, elimina ruido automáticamente y maneja formatos complejos.
- **🔄 Sistema de Fallbacks Robusto:** Múltiples estrategias de procesamiento garantizan que cualquier documento sea procesado exitosamente.
- **📊 Metadatos Estructurales:** Información detallada sobre la estructura del documento (títulos, tablas, listas) para mejor rastreabilidad.
- **🔍 Búsquedas Avanzadas con Filtros:** Sistema de filtrado por metadatos para búsquedas más precisas y relevantes.
- **📈 Estadísticas de Base de Conocimientos:** Información detallada sobre el contenido almacenado y su estructura.
- **LLM Local y Privado:** Utiliza modelos de lenguaje locales a través de [Ollama](https://ollama.com/) (ej. Llama 3, Mistral), asegurando que tus datos y preguntas nunca salgan de tu máquina.
- **100% Local y Offline:** Tanto el modelo de lenguaje como los embeddings se ejecutan en tu máquina. Ningún dato sale a internet. Una vez descargados los modelos, funciona sin conexión.
- **Ingesta Masiva:** Scripts dedicados para procesar directorios enteros de documentos y construir la base de conocimiento de manera eficiente.
- **Arquitectura Modular:** La lógica del RAG está separada de los scripts de servidor y de ingesta, facilitando el mantenimiento y la expansión.
- **Copias en Markdown:** Cada documento procesado se guarda automáticamente en formato Markdown para verificación y reutilización.
- **🆕 Metadatos de Fuente:** Rastreabilidad completa de información con atribución de fuentes en cada respuesta.
- **🆕 Optimizado para Agentes de IA:** Descripciones detalladas y manejo de errores inteligente para uso efectivo por agentes de IA.
- **🆕 Sistema de Scripts Organizado:** Estructura modular de scripts que separa instalación, ejecución y diagnóstico.
---
## 🏗️ Arquitectura
El proyecto está organizado en una estructura modular que separa claramente los componentes del servidor MCP y la interfaz gráfica de usuario (GUI). Esta organización facilita el mantenimiento, desarrollo y uso independiente de cada componente.
### **Estructura del Proyecto:**
```
MCP_RAG/
├── 📁 mcp_server_organized/ # Servidor MCP principal
│ ├── 📄 server.py # Servidor MCP con herramientas RAG
│ ├── 📄 run_server_organized.bat # Script para ejecutar el servidor
│ ├── 📁 src/ # Código fuente del servidor
│ │ ├── 📄 rag_core.py # Lógica principal del RAG
│ │ ├── 📄 rag_server_bk.py # Servidor MCP (backup)
│ │ ├── 📁 models/ # Modelos de datos
│ │ ├── 📁 services/ # Servicios del servidor
│ │ ├── 📁 tools/ # Herramientas MCP
│ │ └── 📁 utils/ # Utilidades
│ ├── 📁 tests/ # Pruebas del servidor
│ ├── 📁 data/ # Datos del servidor
│ │ ├── 📁 documents/ # Documentos procesados
│ │ └── 📁 vector_store/ # Base de datos vectorial
│ └── 📁 embedding_cache/ # Cache de embeddings
│
├── 📁 bulk_ingest_GUI/ # Interfaz gráfica de usuario
│ ├── 📄 main.py # Punto de entrada principal
│ ├── 📄 launch.py # Lanzador de la aplicación
│ ├── 📄 start_app.py # Inicialización de la app
│ ├── 📄 rag_core_wrapper.py # Wrapper para rag_core
│ ├── 📁 views/ # Vistas de la interfaz
│ │ └── 📄 main_view.py # Vista principal
│ ├── 📁 controllers/ # Controladores
│ │ └── 📄 main_controller.py # Controlador principal
│ ├── 📁 services/ # Servicios de la GUI
│ │ ├── 📄 document_service.py # Servicio de documentos
│ │ └── 📄 configuration_service.py # Servicio de configuración
│ ├── 📁 models/ # Modelos de la GUI
│ ├── 📁 widgets/ # Widgets personalizados
│ ├── 📁 gui_utils/ # Utilidades de la GUI
│ ├── 📁 data/ # Datos de la GUI
│ │ ├── 📁 documents/ # Documentos procesados
│ │ └── 📁 vector_store/ # Base de datos vectorial
│ └── 📁 embedding_cache/ # Cache de embeddings
│
├── 📄 start.bat # Script principal de arranque
├── 📄 run_gui.bat # Script para ejecutar la GUI
├── 📄 install_requirements.bat # Instalación de dependencias
├── 📄 requirements.txt # Dependencias del proyecto
├── 📄 README.md # Documentación principal
├── 📄 SCRIPTS_README.md # Guía de scripts
├── 📄 GUI_ADVANCED_README.md # Guía de la GUI para ingesta de documentos masivo
└── 📄 AGENT_INSTRUCTIONS.md # Instrucciones para agentes IA
```
### **Componentes Principales:**
#### **1. Servidor MCP (`mcp_server_organized/`)**
- **`server.py`**: Servidor MCP principal que expone las herramientas RAG
- **`src/rag_core.py`**: El corazón del sistema RAG con toda la lógica de procesamiento
- **`src/tools/`**: Herramientas MCP (`learn_text`, `learn_document`, `ask_rag`, etc.)
- **`src/services/`**: Servicios del servidor (configuración, logging, etc.)
- **`src/models/`**: Modelos de datos para el servidor
- **`src/utils/`**: Utilidades compartidas
#### **2. Interfaz Gráfica (`bulk_ingest_GUI/`)**
- **`main.py`**: Punto de entrada principal de la aplicación GUI
- **`views/main_view.py`**: Interfaz de usuario principal con pestañas
- **`controllers/main_controller.py`**: Lógica de control de la interfaz
- **`services/document_service.py`**: Servicio para procesamiento de documentos
- **`services/configuration_service.py`**: Gestión de configuración
- **`widgets/`**: Componentes personalizados de la interfaz
- **`gui_utils/`**: Utilidades específicas de la GUI
#### **3. Scripts de Sistema**
- **`start.bat`**: Script principal que guía al usuario
- **`run_gui.bat`**: Ejecuta directamente la aplicación GUI
- **`install_requirements.bat`**: Instalación completa de dependencias
- **`check_system.bat`**: Diagnóstico del sistema
- **`fix_dependencies.bat`**: Reparación de dependencias
### **Flujo de Datos:**
1. **Ingesta de Documentos**: La GUI procesa documentos usando `rag_core_wrapper.py`
2. **Almacenamiento**: Los documentos se guardan en la base de datos vectorial
3. **Consulta**: El servidor MCP accede a la misma base de datos para responder consultas
4. **Respuesta**: Las herramientas MCP devuelven respuestas con fuentes
### **Separación de Responsabilidades:**
- **Servidor MCP**: Se enfoca en exponer herramientas para clientes de IA
- **GUI**: Se enfoca en la experiencia de usuario para ingesta de documentos
- **RAG Core**: Lógica compartida entre ambos componentes
- **Scripts**: Automatización y gestión del entorno
Esta arquitectura modular permite:
- ✅ Desarrollo independiente de cada componente
- ✅ Reutilización de código entre servidor y GUI
- ✅ Fácil mantenimiento y debugging
- ✅ Escalabilidad para nuevas características
- ✅ Uso independiente del servidor o la GUI
### **Archivos de Documentación:**
- [`AGENT_INSTRUCTIONS.md`](./AGENT_INSTRUCTIONS.md): Guía completa para agentes de IA sobre cómo usar el sistema
- [`GUI_ADVANCED_README.md`](./GUI_ADVANCED_README.md): Guía detallada para la interfaz gráfica para ingesta de documentos masivo
- [`SCRIPTS_README.md`](./SCRIPTS_README.md): Guía completa del sistema de scripts organizados
- [`STORAGE_PROGRESS_README.md`](./STORAGE_PROGRESS_README.md): Documentación del sistema de progreso de almacenamiento
- `test_enhanced_rag.py`: Script de prueba para verificar el funcionamiento del sistema
---
## 🚀 Guía de Instalación y Configuración
Sigue estos pasos para poner en marcha el sistema.
### Prerrequisitos
- **Python 3.10+**
- **Ollama:** Asegúrate de que [Ollama esté instalado](https://ollama.com/) y en ejecución en tu sistema.
- **Tesseract OCR (Opcional):** Para procesar imágenes con texto. Descarga desde [GitHub](https://github.com/UB-Mannheim/tesseract/wiki) o usa `choco install tesseract`.
### 1. Instalación (¡Automática!)
Gracias al sistema de scripts organizados, la instalación es increíblemente sencilla.
#### **Para Usuarios (Recomendado):**
1. **Ejecuta el script principal:** `start.bat`
2. **Selecciona "1"** para instalar dependencias
3. **Espera** a que termine la instalación automática
4. **La aplicación se iniciará** automáticamente
#### **Para Desarrolladores:**
- **Instalación completa:** `install_requirements.bat`
- **Ejecución:** `run_gui.bat`
- **Diagnóstico:** `check_system.bat`
El sistema de scripts hace todo por ti:
- ✅ Crea un entorno virtual de Python en una carpeta `.venv`
- ✅ Activa el entorno automáticamente
- ✅ Instala todas las dependencias necesarias desde `requirements.txt`
- ✅ Detecta automáticamente si tienes GPU NVIDIA y instala PyTorch apropiadamente
- ✅ Instala Unstructured con capacidades avanzadas
- ✅ Lanza la aplicación
En ejecuciones posteriores, el script simplemente activará el entorno y lanzará la aplicación directamente.
### 2. Instalación Manual de Dependencias (Opcional)
Si prefieres instalar las dependencias manualmente o necesitas capacidades específicas:
```bash
# Activar entorno virtual
.\.venv\Scripts\activate
# Instalación completa de Unstructured con todas las capacidades
pip install "unstructured[local-inference,all-docs]"
# Dependencias adicionales para mejor rendimiento
pip install python-docx openpyxl beautifulsoup4 pytesseract
```
### 3. Configuración de Ollama (Paso Crítico)
Ollama es necesario para que el sistema RAG funcione, ya que proporciona el modelo de lenguaje local que genera las respuestas.
#### Instalación de Ollama
**Windows:**
1. Descarga Ollama desde [ollama.com](https://ollama.com/)
2. Ejecuta el instalador y sigue las instrucciones
3. Ollama se ejecutará automáticamente como servicio
**macOS/Linux:**
```bash
curl -fsSL https://ollama.ai/install.sh | sh
```
#### Verificar Instalación
```bash
# Verificar que Ollama está funcionando
ollama --version
# Verificar que el servicio está ejecutándose
ollama list
```
#### Descargar Modelos de Lenguaje
El sistema RAG necesita un modelo de lenguaje para generar respuestas. Se utiliza Ollama por ser gratis:
```bash
# Modelo recomendado (equilibrio entre velocidad y calidad)
ollama pull llama3
# Alternativas más rápidas
ollama pull phi3
ollama pull mistral
# Alternativa más potente (requiere más recursos)
ollama pull llama3.1:8b
```
#### Configurar el Modelo en el Sistema
Una vez descargado el modelo, asegúrate de que `rag_core.py` use el modelo correcto:
```python
# En rag_core.py, línea ~100, verifica que use tu modelo:
llm = ChatOllama(model="llama3", temperature=0)
```
**Nota:** Si descargaste un modelo diferente, cambia `"llama3"` por el nombre de tu modelo.
#### Probar Ollama
```bash
# Probar que el modelo funciona
ollama run llama3 "Hola, ¿cómo estás?"
```
Si ves una respuesta generada, Ollama está funcionando correctamente.
#### Solución de Problemas Comunes
**Error: "Ollama is not running"**
```bash
# Iniciar Ollama manualmente
ollama serve
```
**Error: "Model not found"**
```bash
# Verificar modelos disponibles
ollama list
# Descargar el modelo si no está
ollama pull llama3
```
**Error: "Out of memory"**
- Usa un modelo más pequeño: `ollama pull phi3`
- Cierra otras aplicaciones que consuman mucha RAM
- Considera aumentar la memoria virtual en Windows
### 4. Verificación Completa del Sistema
Antes de continuar, vamos a verificar que todo esté funcionando correctamente:
#### Paso 1: Verificar Ollama
```bash
# Verificar que Ollama está ejecutándose
ollama list
# Probar el modelo
ollama run llama3 "Test de funcionamiento"
```
#### Paso 2: Verificar Dependencias de Python
```bash
# Verificar que todas las dependencias están instaladas
python -c "import mcp; print('✅ MCP instalado correctamente')"
python -c "import langchain; print('✅ LangChain instalado correctamente')"
python -c "import chromadb; print('✅ ChromaDB instalado correctamente')"
python -c "import unstructured; print('✅ Unstructured instalado correctamente')"
```
#### Paso 3: Probar el Sistema RAG
```bash
# Ejecutar el script de prueba mejorado
python test_enhanced_rag.py
```
Si todo funciona correctamente, verás:
- ✅ Ollama respondiendo a comandos
- ✅ Todas las dependencias importándose sin errores
- ✅ El sistema RAG procesando preguntas y mostrando fuentes
**¡Tu sistema RAG está listo para usar!** 🚀
---
## 📋 Formatos de Archivo Soportados
El sistema soporta **más de 25 formatos de archivo** con procesamiento optimizado:
### 📄 **Documentos de Office:**
- **PDF** (.pdf) - Con procesamiento de alta resolución
- **Word** (.docx, .doc) - Documentos de Microsoft Word
- **PowerPoint** (.pptx, .ppt) - Presentaciones
- **Excel** (.xlsx, .xls) - Hojas de cálculo
- **RTF** (.rtf) - Formato de texto enriquecido
### 📁 **Documentos OpenDocument:**
- **ODT** (.odt) - Documentos de texto (LibreOffice/OpenOffice)
- **ODP** (.odp) - Presentaciones (LibreOffice/OpenOffice)
- **ODS** (.ods) - Hojas de cálculo (LibreOffice/OpenOffice)
### 🌐 **Formatos Web y Markup:**
- **HTML** (.html, .htm) - Páginas web
- **XML** (.xml) - Datos estructurados
- **Markdown** (.md) - Documentación técnica
### 📝 **Formatos de Texto Plano:**
- **TXT** (.txt) - Texto simple
- **CSV** (.csv) - Datos tabulares
- **TSV** (.tsv) - Datos tabulares separados por tabulaciones
### 📊 **Formatos de Datos:**
- **JSON** (.json) - Datos estructurados
- **YAML** (.yaml, .yml) - Configuraciones y datos
### 🖼️ **Imágenes (con OCR):**
- **PNG** (.png) - Imágenes con texto
- **JPG/JPEG** (.jpg, .jpeg) - Fotografías con texto
- **TIFF** (.tiff) - Imágenes de alta calidad
- **BMP** (.bmp) - Imágenes de mapa de bits
### 📧 **Correos Electrónicos:**
- **EML** (.eml) - Archivos de correo
- **MSG** (.msg) - Mensajes de Outlook
---
## 🛠️ Guía de Uso
### Uso 1: Poblar la Base de Conocimiento con la GUI (Recomendado)
La forma más fácil e intuitiva de añadir documentos es usando la interfaz gráfica.
1. **Ejecuta el script principal:** `start.bat`
2. **Selecciona "1"** para ejecutar la aplicación
3. **La aplicación se iniciará** (la primera vez puede tardar mientras instala las dependencias)
4. **Usa el botón "Explorar..."** para seleccionar la carpeta con tus documentos
5. **Haz clic en "Iniciar Procesamiento"**. Los archivos se procesarán con el sistema avanzado de Unstructured
6. **Ve a la pestaña "Revisión"**, selecciona los archivos que quieres guardar y previsualiza su contenido
7. **Ve a la pestaña "Almacenamiento"** y haz clic en "Iniciar Almacenamiento" para guardar los documentos seleccionados en la base de datos
#### ✨ **GUI para ingesta de documentos masivo con Previsualización y Selección**
Para un control total sobre el proceso de ingesta, hemos añadido una **GUI**. Esta versión te permite **previsualizar** el contenido de cada documento procesado y **seleccionar manualmente** cuáles quieres incluir en la base de conocimiento.
**Características de la GUI:**
- **Procesamiento Inteligente:** Usa Unstructured para limpiar ruido y preservar estructura
- **Previsualización en Tiempo Real:** Ve el contenido procesado antes de almacenar
- **Selección Granular:** Marca/desmarca documentos individualmente
- **Metadatos Estructurales:** Información sobre títulos, tablas, listas en cada documento
- **Sistema de Fallbacks:** Múltiples estrategias garantizan que todo documento se procese
- **Sistema de Progreso:** Seguimiento detallado del proceso de almacenamiento
➡️ **Para una guía completa sobre cómo usarla, consulta el [Guia de Carga Masiva](./GUI_ADVANCED_README.md).**
### Uso 2: Poblar la Base de Conocimiento desde la Línea de Comandos
Si prefieres usar la línea de comandos o necesitas automatizar la ingesta.
1. **Abre una terminal**
2. **Activa el entorno virtual:** `.\.venv\Scripts\activate`
3. **Ejecuta el script `bulk_ingest.py`** apuntando a tu carpeta de documentos:
```bash
python bulk_ingest.py --directory "C:\Ruta\A\Tus\Documentos"
```
**Características del Procesamiento Mejorado:**
- **Detección Automática de Formato:** El sistema identifica y optimiza el procesamiento según el tipo de archivo
- **Limpieza Inteligente:** Elimina automáticamente cabeceras, pies de página y contenido irrelevante
- **Preservación de Estructura:** Mantiene títulos, listas y tablas organizadas
- **Metadatos Enriquecidos:** Información detallada sobre la estructura de cada documento
- **Logs Detallados:** Información completa sobre el proceso de cada archivo
### Uso 3: Configuración del Cliente MCP (Ej. Cursor)
Para que tu editor de IA pueda usar el servidor, debes configurarlo.
1. **Encuentra el archivo de configuración de servidores MCP de tu editor.** Para Cursor, busca un archivo como `mcp_servers.json` en su directorio de configuración (`%APPDATA%\cursor` en Windows). Si no existe, puedes crearlo.
2. **Añade la siguiente configuración al archivo JSON.**
Este método utiliza el script del servidor MCP (`run_server_organized.bat`) para ejecutar el servidor RAG.
**¡IMPORTANTE!** Debes reemplazar `"D:\\ruta\\completa\\a\\tu\\proyecto\\MCP_RAG"` con la ruta absoluta real a la carpeta de este proyecto en tu máquina.
```json
{
"mcpServers": {
"rag": {
"command": "D:\\ruta\\completa\\a\\tu\\proyecto\\MCP_RAG\\mcp_server_organized\\run_server_organized.bat",
"args": [],
"workingDirectory": "D:\\ruta\\completa\\a\\tu\\proyecto\\MCP_RAG"
}
}
}
```
3. **Reinicia tu editor.** Al arrancar, debería detectar y lanzar el servidor MCP, que expondrá las herramientas RAG para uso en el chat.
### Uso 4: Interactuando con las Herramientas
Una vez configurado, puedes usar las herramientas directamente en el chat de tu editor.
#### Herramientas Disponibles:
**1. `learn_text(text, source_name)` - Añadir información textual**
```
@rag learn_text("El punto de fusión del titanio es 1,668 °C.", "material_properties")
```
- **Cuándo usar**: Para añadir hechos, definiciones, notas de conversación, etc.
- **Parámetros**:
- `text`: El contenido a almacenar
- `source_name`: Nombre descriptivo de la fuente (opcional, por defecto "manual_input")
**2. `learn_document(file_path)` - Procesar documentos**
```
@rag learn_document("C:\\Reportes\\informe_q3.pdf")
```
- **Cuándo usar**: Para procesar archivos PDF, DOCX, PPTX, XLSX, TXT, HTML, CSV, JSON, XML, imágenes, correos electrónicos y más de 25 formatos
- **Características Mejoradas**:
- **Procesamiento Inteligente**: Usa Unstructured para limpiar ruido y preservar estructura
- **Sistema de Fallbacks**: Múltiples estrategias garantizan procesamiento exitoso
- **Metadatos Estructurales**: Información detallada sobre títulos, tablas, listas
- **Conversión Automática**: Procesamiento optimizado según el tipo de archivo
- **Copias Guardadas**: Documentos procesados guardados en `./converted_docs/`
**3. `ask_rag(query)` - Consultar información**
```
@rag ask_rag("¿Cuál es el punto de fusión del titanio?")
```
- **Cuándo usar**: Para buscar información previamente almacenada
- **Respuesta incluye**:
- Respuesta generada por IA con contexto mejorado
- 📚 Lista de fuentes utilizadas con metadatos estructurales
- Información sobre la relevancia de cada fuente
**4. `ask_rag_filtered(query, file_type, min_tables, min_titles, processing_method)` - Búsquedas con filtros**
```
@rag ask_rag_filtered("¿Qué tablas de datos tenemos?", file_type=".pdf", min_tables=1)
```
- **Cuándo usar**: Para búsquedas más precisas usando filtros de metadatos
- **Filtros disponibles**:
- `file_type`: Tipo de archivo (ej. ".pdf", ".docx", ".xlsx")
- `min_tables`: Mínimo número de tablas en el documento
- `min_titles`: Mínimo número de títulos en el documento
- `processing_method`: Método de procesamiento usado
- **Ventajas**: Búsquedas más relevantes y específicas
**5. `get_knowledge_base_stats()` - Estadísticas de la base de conocimientos**
```
@rag get_knowledge_base_stats()
```
- **Cuándo usar**: Para obtener información sobre el contenido almacenado
- **Información proporcionada**:
- Número total de documentos
- Distribución por tipo de archivo
- Estadísticas de estructura (tablas, títulos, listas)
- Métodos de procesamiento utilizados
#### Ejemplo de Flujo Completo:
```bash
# 1. Añadir información
@rag learn_text("La temperatura de fusión del titanio es 1,668°C.", "material_properties")
# 2. Procesar un documento complejo (ahora con procesamiento mejorado)
@rag learn_document("C:\\Documents\\manual_titanio.pdf")
# 3. Hacer preguntas (con respuestas mejoradas)
@rag ask_rag("¿Cuál es la temperatura de fusión del titanio?")
# 4. Búsqueda filtrada por documentos con tablas
@rag ask_rag_filtered("¿Qué datos tabulares tenemos?", min_tables=1)
# 5. Ver estadísticas de la base de conocimientos
@rag get_knowledge_base_stats()
```
**Respuesta esperada:**
```
La temperatura de fusión del titanio es 1,668°C.
📚 Fuentes de información:
1. material_properties (manual_input)
2. manual_titanio.pdf (página 3, sección "Propiedades Físicas")
📊 Estadísticas de búsqueda filtrada:
• Documentos con tablas encontrados: 3
• Tipos de archivo: PDF (2), DOCX (1)
• Total de tablas: 7
```
---
## 🧪 Pruebas y Verificación
### Probar el Sistema
Para verificar que todo funciona correctamente:
```bash
# Probar el sistema RAG mejorado con todas las características
python test_enhanced_rag.py
```
#### **Script de Pruebas Mejorado (`test_enhanced_rag.py`)**
El script de pruebas verifica todas las mejoras implementadas:
**🧪 Pruebas Incluidas:**
- **Procesamiento Mejorado de Documentos**: Verifica el sistema Unstructured con metadatos estructurales
- **Base de Conocimientos Mejorada**: Prueba el chunking mejorado y metadatos enriquecidos
- **Integración del Servidor MCP**: Verifica las herramientas mejoradas del servidor
- **Soporte de Formatos**: Confirma la configuración para más de 25 formatos
**📊 Información de Salida:**
- Estado de cada prueba (✅ PASÓ / ❌ FALLÓ)
- Metadatos estructurales extraídos
- Método de procesamiento utilizado
- Información de fuentes y chunks
- Resumen completo del sistema
### Verificar la Base de Datos
Los documentos procesados se almacenan en:
- **Base de datos vectorial**: `./rag_mcp_db/`
- **Copias procesadas**: `./converted_docs/` (con información del método de procesamiento)
---
## 🤖 Uso por Agentes de IA
El sistema está optimizado para ser utilizado por agentes de IA. Consulta [`AGENT_INSTRUCTIONS.md`](./AGENT_INSTRUCTIONS.md) para:
- Guías detalladas de uso
- Ejemplos de casos de uso
- Mejores prácticas
- Manejo de errores
- Consideraciones importantes
### Características para Agentes:
- **Descripciones detalladas** de cada herramienta
- **Ejemplos de uso** claros y específicos
- **Manejo de errores inteligente** con sugerencias útiles
- **Metadatos de fuente** para rastreabilidad completa
- **Respuestas estructuradas** con información de fuentes
---
## 🔧 Mejoras Técnicas Implementadas
Esta sección explica las mejoras técnicas avanzadas que han transformado el sistema en una solución de nivel empresarial.
### **A. Procesamiento Inteligente con Unstructured**
#### **¿Qué es Unstructured?**
Unstructured es una librería de procesamiento de documentos que va más allá de la simple extracción de texto. Analiza la **estructura semántica** de los documentos para:
- **Identificar elementos**: Títulos, párrafos, listas, tablas
- **Limpiar ruido**: Eliminar cabeceras, pies de página, elementos irrelevantes
- **Preservar contexto**: Mantener la jerarquía y estructura del documento
- **Manejar formatos complejos**: PDFs escaneados, documentos con tablas, etc.
#### **Configuración Optimizada por Tipo de Archivo:**
```python
UNSTRUCTURED_CONFIGS = {
'.pdf': {
'strategy': 'hi_res', # Alta resolución para PDFs complejos
'include_metadata': True, # Incluir metadatos estructurales
'include_page_breaks': True, # Preservar saltos de página
'max_partition': 2000, # Tamaño máximo de partición
'new_after_n_chars': 1500 # Nuevo elemento después de N caracteres
},
'.docx': {
'strategy': 'fast', # Procesamiento rápido para documentos de Office
'include_metadata': True,
'max_partition': 2000,
'new_after_n_chars': 1500
},
# ... configuraciones para más de 25 formatos
}
```
#### **Procesamiento Inteligente de Elementos:**
```python
def process_unstructured_elements(elements: List[Any]) -> str:
"""Procesa elementos de Unstructured preservando estructura semántica."""
for element in elements:
element_type = type(element).__name__
if element_type == 'Title':
# Los títulos van con formato especial
processed_parts.append(f"\n## {element.text.strip()}\n")
elif element_type == 'ListItem':
# Las listas mantienen su estructura
processed_parts.append(f"• {element.text.strip()}")
elif element_type == 'Table':
# Las tablas se convierten a texto legible
table_text = convert_table_to_text(element)
processed_parts.append(f"\n{table_text}\n")
elif element_type == 'NarrativeText':
# El texto narrativo va tal como está
processed_parts.append(element.text.strip())
```
### **B. Sistema de Fallbacks Robusto**
#### **Estrategia de Fallbacks en Cascada:**
El sistema intenta múltiples estrategias en orden de preferencia:
1. **Unstructured con Configuración Óptima**
- Usa la configuración específica para el tipo de archivo
- Máxima calidad de procesamiento
2. **Unstructured con Configuración Básica**
- Estrategia "fast" para compatibilidad
- Procesamiento más simple pero funcional
3. **Cargadores Específicos de LangChain**
- Cargadores especializados por tipo de archivo
- Último recurso para formatos problemáticos
#### **Ejemplo de Fallback en Acción:**
```python
def load_document_with_fallbacks(file_path: str) -> tuple[str, dict]:
file_extension = os.path.splitext(file_path)[1].lower()
# Estrategia 1: Unstructured óptimo
try:
config = UNSTRUCTURED_CONFIGS.get(file_extension, DEFAULT_CONFIG)
elements = partition(filename=file_path, **config)
processed_text = process_unstructured_elements(elements)
metadata = extract_structural_metadata(elements, file_path)
return processed_text, metadata
except Exception as e:
log(f"Core Warning: Unstructured óptimo falló: {e}")
# Estrategia 2: Unstructured básico
try:
elements = partition(filename=file_path, strategy="fast")
# ... procesamiento
except Exception as e:
log(f"Core Warning: Unstructured básico falló: {e}")
# Estrategia 3: LangChain fallbacks
try:
fallback_text = load_with_langchain_fallbacks(file_path)
# ... procesamiento
except Exception as e:
log(f"Core Warning: LangChain fallbacks fallaron: {e}")
return "", {} # Solo si todas las estrategias fallan
```
### **C. Metadatos Estructurales Enriquecidos**
#### **Información Estructural Capturada:**
```python
def extract_structural_metadata(elements: List[Any], file_path: str) -> Dict[str, Any]:
structural_info = {
"total_elements": len(elements),
"titles_count": sum(1 for e in elements if type(e).__name__ == 'Title'),
"tables_count": sum(1 for e in elements if type(e).__name__ == 'Table'),
"lists_count": sum(1 for e in elements if type(e).__name__ == 'ListItem'),
"narrative_blocks": sum(1 for e in elements if type(e).__name__ == 'NarrativeText'),
"total_text_length": total_text_length,
"avg_element_length": total_text_length / len(elements) if elements else 0
}
metadata = {
"source": os.path.basename(file_path),
"file_path": file_path,
"file_type": os.path.splitext(file_path)[1].lower(),
"processed_date": datetime.now().isoformat(),
"processing_method": "unstructured_enhanced",
"structural_info": structural_info
}
```
#### **Beneficios de los Metadatos Estructurales:**
- **Rastreabilidad**: Sabes exactamente qué parte del documento se usó
- **Calidad**: Información sobre la estructura del contenido
- **Optimización**: Datos para mejorar el procesamiento futuro
- **Debugging**: Información detallada para resolver problemas
### **D. División Inteligente de Texto Mejorada**
#### **Configuración Optimizada:**
```python
text_splitter = RecursiveCharacterTextSplitter(
chunk_size=1000, # Tamaño máximo de cada fragmento
chunk_overlap=200, # Caracteres que se comparten entre fragmentos
length_function=len, # Función para medir longitud
separators=["\n\n", "\n", ". ", "! ", "? ", " ", ""] # Separadores inteligentes
)
```
#### **Separadores Inteligentes:**
El sistema busca los mejores puntos de división en este orden:
1. **`\n\n`** - Párrafos (mejor opción)
2. **`\n`** - Saltos de línea
3. **`. `** - Final de oraciones
4. **`! `** - Final de exclamaciones
5. **`? `** - Final de preguntas
6. **` `** - Espacios (último recurso)
### **E. Motor de Búsqueda Optimizado**
#### **Configuración Actual:**
```python
retriever = vector_store.as_retriever(
search_type="similarity_score_threshold", # Búsqueda con umbral de similitud
search_kwargs={
"k": 5, # Recupera 5 fragmentos más relevantes
"score_threshold": 0.3, # Umbral de distancia (similitud > 0.7)
}
)
```
#### **Parámetros Optimizados:**
- **`k=5`**: Obtienes información de 5 fuentes diferentes para respuestas más completas
- **`score_threshold=0.3`**: Garantiza que solo se use información muy relevante (similitud > 70%)
- **Búsqueda por similitud**: Encuentra el contenido más semánticamente similar
### **F. Limpieza Automática de Texto**
#### **Proceso de Limpieza:**
```python
def clean_text_for_rag(text: str) -> str:
"""Limpia y prepara el texto para mejorar la calidad de las búsquedas RAG."""
if not text:
return ""
# Eliminar espacios múltiples y saltos de línea excesivos
text = re.sub(r'\s+', ' ', text)
# Eliminar caracteres especiales problemáticos pero mantener puntuación importante
text = re.sub(r'[^\w\s\.\,\!\?\;\:\-\(\)\[\]\{\}\"\']', '', text)
# Normalizar espacios alrededor de puntuación
text = re.sub(r'\s+([\.\,\!\?\;\:])', r'\1', text)
# Eliminar líneas vacías múltiples
text = re.sub(r'\n\s*\n', '\n\n', text)
# Limpiar espacios al inicio y final
text = text.strip()
return text
```
### **G. Sistema de Filtrado de Metadatos Avanzado**
#### **Funcionalidades de Filtrado:**
El sistema ahora incluye capacidades avanzadas de filtrado que permiten búsquedas más precisas y relevantes:
```python
def create_metadata_filter(file_type: str = None, processing_method: str = None,
min_tables: int = None, min_titles: int = None,
source_contains: str = None) -> dict:
"""Crea filtros de metadatos para búsquedas más precisas."""
filters = []
if file_type:
filters.append({"file_type": file_type})
if processing_method:
filters.append({"processing_method": processing_method})
if min_tables:
filters.append({"structural_info_tables_count": {"$gte": min_tables}})
if min_titles:
filters.append({"structural_info_titles_count": {"$gte": min_titles}})
if source_contains:
filters.append({"source": {"$contains": source_contains}})
return {"$and": filters} if len(filters) > 1 else filters[0] if filters else None
```
#### **Búsquedas con Filtros:**
```python
def search_with_metadata_filters(vector_store: Chroma, query: str,
metadata_filter: dict = None, k: int = 5) -> List[Any]:
"""Realiza búsquedas con filtros de metadatos para mayor precisión."""
if metadata_filter:
# Búsqueda con filtros específicos
results = vector_store.similarity_search_with_relevance_scores(
query, k=k, filter=metadata_filter
)
else:
# Búsqueda normal sin filtros
results = vector_store.similarity_search_with_relevance_scores(query, k=k)
return results
```
#### **Estadísticas de Base de Conocimientos:**
```python
def get_document_statistics(vector_store: Chroma) -> dict:
"""Obtiene estadísticas detalladas sobre la base de conocimientos."""
all_docs = vector_store.get()
if not all_docs or not all_docs.get('metadatas'):
return {"total_documents": 0}
metadatas = all_docs['metadatas']
# Análisis por tipo de archivo
file_types = {}
processing_methods = {}
total_tables = 0
total_titles = 0
for metadata in metadatas:
file_type = metadata.get("file_type", "unknown")
processing_method = metadata.get("processing_method", "unknown")
tables_count = metadata.get("structural_info_tables_count", 0)
titles_count = metadata.get("structural_info_titles_count", 0)
file_types[file_type] = file_types.get(file_type, 0) + 1
processing_methods[processing_method] = processing_methods.get(processing_method, 0) + 1
total_tables += tables_count
total_titles += titles_count
return {
"total_documents": len(metadatas),
"file_types": file_types,
"processing_methods": processing_methods,
"total_tables": total_tables,
"total_titles": total_titles,
"avg_tables_per_doc": total_tables / len(metadatas) if metadatas else 0,
"avg_titles_per_doc": total_titles / len(metadatas) if metadatas else 0
}
```
#### **Casos de Uso de Filtrado:**
1. **Búsqueda por Tipo de Archivo:**
```python
# Solo buscar en PDFs
pdf_filter = create_metadata_filter(file_type=".pdf")
results = search_with_metadata_filters(vector_store, "datos", pdf_filter)
```
2. **Búsqueda por Estructura:**
```python
# Solo documentos con tablas
tables_filter = create_metadata_filter(min_tables=1)
results = search_with_metadata_filters(vector_store, "datos tabulares", tables_filter)
```
3. **Búsqueda por Método de Procesamiento:**
```python
# Solo documentos procesados con Unstructured
unstructured_filter = create_metadata_filter(processing_method="unstructured_enhanced")
results = search_with_metadata_filters(vector_store, "contenido", unstructured_filter)
```
4. **Filtros Combinados:**
```python
# PDFs con tablas procesados con Unstructured
complex_filter = create_metadata_filter(
file_type=".pdf",
min_tables=1,
processing_method="unstructured_enhanced"
)
results = search_with_metadata_filters(vector_store, "datos", complex_filter)
```
### **H. Herramientas MCP Mejoradas**
#### **Nuevas Herramientas Disponibles:**
1. **`ask_rag_filtered`**: Búsquedas con filtros de metadatos
2. **`get_knowledge_base_stats`**: Estadísticas detalladas de la base de conocimientos
#### **Integración con Agentes de IA:**
Las nuevas herramientas están optimizadas para uso por agentes de IA con:
- **Descripciones detalladas** de parámetros y casos de uso
- **Ejemplos específicos** de cada herramienta
- **Manejo de errores inteligente** con sugerencias útiles
- **Respuestas estructuradas** con información de metadatos
---
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo issues