Servidor RAG Personal con MCP

Um servidor para Geração Aumentada por Recuperação (RAG), fornecendo a clientes de IA acesso a uma base de conhecimento privada construída a partir de documentos do usuário.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor RAG Personal con MCP

Este projeto implementa um servidor compatível com o Protocolo de Contexto de Modelo (MCP) que fornece aos clientes de IA (como Cursor, Claude for Desktop, etc.) uma capacidade de Recuperação Aumentada por Geração (RAG). Permite ao modelo de linguagem acessar uma base de conhecimento privada e local, alimentada pelos seus próprios textos e documentos.

✨ Características

Memória Persistente para sua IA: "Ensina" à sua IA novas informações que ela lembrará entre sessões.
🆕 Interface Gráfica de Usuário (GUI): Um aplicativo de desktop intuitivo com sistema de scripts organizados para facilitar a instalação e execução.
🚀 Processamento Avançado de Documentos: Alimenta a base de conhecimento com mais de 25 formatos de arquivo incluindo PDF, DOCX, PPTX, XLSX, imagens (com OCR), e-mails, e mais.
🧠 Processamento Inteligente com Unstructured: Sistema de processamento de documentos de nível empresarial que preserva a estrutura semântica, elimina ruído automaticamente e lida com formatos complexos.
🔄 Sistema de Fallbacks Robusto: Múltiplas estratégias de processamento garantem que qualquer documento seja processado com sucesso.
📊 Metadados Estruturais: Informação detalhada sobre a estrutura do documento (títulos, tabelas, listas) para melhor rastreabilidade.
🔍 Buscas Avançadas com Filtros: Sistema de filtragem por metadados para buscas mais precisas e relevantes.
📈 Estatísticas da Base de Conhecimento: Informação detalhada sobre o conteúdo armazenado e sua estrutura.
LLM Local e Privado: Utiliza modelos de linguagem locais através de Ollama (ex. Llama 3, Mistral), garantindo que seus dados e perguntas nunca saiam da sua máquina.
100% Local e Offline: Tanto o modelo de linguagem quanto os embeddings são executados na sua máquina. Nenhum dado sai para a internet. Uma vez baixados os modelos, funciona sem conexão.
Ingestão Massiva: Scripts dedicados para processar diretórios inteiros de documentos e construir a base de conhecimento de maneira eficiente.
Arquitetura Modular: A lógica do RAG está separada dos scripts de servidor e de ingestão, facilitando a manutenção e a expansão.
Cópias em Markdown: Cada documento processado é salvo automaticamente em formato Markdown para verificação e reutilização.
🆕 Metadados de Fonte: Rastreabilidade completa da informação com atribuição de fontes em cada resposta.
🆕 Otimizado para Agentes de IA: Descrições detalhadas e tratamento inteligente de erros para uso efetivo por agentes de IA.
🆕 Sistema de Scripts Organizado: Estrutura modular de scripts que separa instalação, execução e diagnóstico.

🏗️ Arquitetura

O projeto está organizado em uma estrutura modular que separa claramente os componentes do servidor MCP e a interface gráfica de usuário (GUI). Essa organização facilita a manutenção, o desenvolvimento e o uso independente de cada componente.

Estrutura do Projeto:

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 Principais:

1. Servidor MCP (`mcp_server_organized/`)

server.py: Servidor MCP principal que expõe as ferramentas RAG
src/rag_core.py: O coração do sistema RAG com toda a lógica de processamento
src/tools/: Ferramentas MCP (learn_text, learn_document, ask_rag, etc.)
src/services/: Serviços do servidor (configuração, logging, etc.)
src/models/: Modelos de dados para o servidor
src/utils/: Utilitários compartilhados

2. Interface Gráfica (`bulk_ingest_GUI/`)

main.py: Ponto de entrada principal do aplicativo GUI
views/main_view.py: Interface de usuário principal com abas
controllers/main_controller.py: Lógica de controle da interface
services/document_service.py: Serviço para processamento de documentos
services/configuration_service.py: Gerenciamento de configuração
widgets/: Componentes personalizados da interface
gui_utils/: Utilitários específicos da GUI

3. Scripts de Sistema

start.bat: Script principal que guia o usuário
run_gui.bat: Executa diretamente o aplicativo GUI
install_requirements.bat: Instalação completa de dependências
check_system.bat: Diagnóstico do sistema
fix_dependencies.bat: Reparação de dependências

Fluxo de Dados:

Ingestão de Documentos: A GUI processa documentos usando rag_core_wrapper.py
Armazenamento: Os documentos são salvos no banco de dados vetorial
Consulta: O servidor MCP acessa o mesmo banco de dados para responder consultas
Resposta: As ferramentas MCP retornam respostas com fontes

Separação de Responsabilidades:

Servidor MCP: Foca em expor ferramentas para clientes de IA
GUI: Foca na experiência do usuário para ingestão de documentos
RAG Core: Lógica compartilhada entre ambos os componentes
Scripts: Automação e gerenciamento do ambiente

Esta arquitetura modular permite:

✅ Desenvolvimento independente de cada componente
✅ Reutilização de código entre servidor e GUI
✅ Fácil manutenção e debugging
✅ Escalabilidade para novos recursos
✅ Uso independente do servidor ou da GUI

Arquivos de Documentação:

AGENT_INSTRUCTIONS.md: Guia completo para agentes de IA sobre como usar o sistema
GUI_ADVANCED_README.md: Guia detalhado para a interface gráfica para ingestão massiva de documentos
SCRIPTS_README.md: Guia completo do sistema de scripts organizados
STORAGE_PROGRESS_README.md: Documentação do sistema de progresso de armazenamento
test_enhanced_rag.py: Script de teste para verificar o funcionamento do sistema

🚀 Guia de Instalação e Configuração

Siga estes passos para colocar o sistema em funcionamento.

Pré-requisitos

Python 3.10+
Ollama: Certifique-se de que o Ollama esteja instalado e em execução no seu sistema.
Tesseract OCR (Opcional): Para processar imagens com texto. Baixe do GitHub ou use choco install tesseract.

1. Instalação (Automática!)

Graças ao sistema de scripts organizados, a instalação é incrivelmente simples.

Para Usuários (Recomendado):

Execute o script principal: start.bat
Selecione "1" para instalar dependências
Aguarde a instalação automática terminar
O aplicativo será iniciado automaticamente

Para Desenvolvedores:

Instalação completa: install_requirements.bat
Execução: run_gui.bat
Diagnóstico: check_system.bat

O sistema de scripts faz tudo por você:

✅ Cria um ambiente virtual Python em uma pasta .venv
✅ Ativa o ambiente automaticamente
✅ Instala todas as dependências necessárias a partir de requirements.txt
✅ Detecta automaticamente se você tem GPU NVIDIA e instala PyTorch adequadamente
✅ Instala Unstructured com capacidades avançadas
✅ Inicia o aplicativo

Em execuções posteriores, o script simplesmente ativará o ambiente e iniciará o aplicativo diretamente.

2. Instalação Manual de Dependências (Opcional)

Se preferir instalar as dependências manualmente ou precisar de capacidades específicas:

# 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. Configuração do Ollama (Passo Crítico)

O Ollama é necessário para que o sistema RAG funcione, pois fornece o modelo de linguagem local que gera as respostas.

Instalação do Ollama

Windows:

Baixe o Ollama de ollama.com
Execute o instalador e siga as instruções
O Ollama será executado automaticamente como serviço

macOS/Linux:

curl -fsSL https://ollama.ai/install.sh | sh

Verificar Instalação

# Verificar que Ollama está funcionando
ollama --version

# Verificar que el servicio está ejecutándose
ollama list

Baixar Modelos de Linguagem

O sistema RAG precisa de um modelo de linguagem para gerar respostas. O Ollama é utilizado por ser gratuito:

# 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 o Modelo no Sistema

Depois de baixar o modelo, certifique-se de que rag_core.py use o modelo correto:

# En rag_core.py, línea ~100, verifica que use tu modelo:
llm = ChatOllama(model="llama3", temperature=0)

Nota: Se você baixou um modelo diferente, altere "llama3" para o nome do seu modelo.

Testar o Ollama

# Probar que el modelo funciona
ollama run llama3 "Hola, ¿cómo estás?"

Se você vir uma resposta gerada, o Ollama está funcionando corretamente.

Solução de Problemas Comuns

Error: "Ollama is not running"

# Iniciar Ollama manualmente
ollama serve

Error: "Model not found"

# Verificar modelos disponibles
ollama list

# Descargar el modelo si no está
ollama pull llama3

Error: "Out of memory"

Use um modelo menor: ollama pull phi3
Feche outros aplicativos que consumam muita RAM
Considere aumentar a memória virtual no Windows

4. Verificação Completa do Sistema

Antes de continuar, vamos verificar se tudo está funcionando corretamente:

Passo 1: Verificar o Ollama

# Verificar que Ollama está ejecutándose
ollama list

# Probar el modelo
ollama run llama3 "Test de funcionamiento"

Passo 2: Verificar Dependências do Python

# 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')"

Passo 3: Testar o Sistema RAG

# Ejecutar el script de prueba mejorado
python test_enhanced_rag.py

Se tudo funcionar corretamente, você verá:

✅ Ollama respondendo a comandos
✅ Todas as dependências sendo importadas sem erros
✅ O sistema RAG processando perguntas e mostrando fontes

Seu sistema RAG está pronto para usar! 🚀

📋 Formatos de Arquivo Suportados

O sistema suporta mais de 25 formatos de arquivo com processamento otimizado:

📄 Documentos do Office:

PDF (.pdf) - Com processamento de alta resolução
Word (.docx, .doc) - Documentos do Microsoft Word
PowerPoint (.pptx, .ppt) - Apresentações
Excel (.xlsx, .xls) - Planilhas
RTF (.rtf) - Formato de texto rico

📁 Documentos OpenDocument:

ODT (.odt) - Documentos de texto (LibreOffice/OpenOffice)
ODP (.odp) - Apresentações (LibreOffice/OpenOffice)
ODS (.ods) - Planilhas (LibreOffice/OpenOffice)

🌐 Formatos Web e Markup:

HTML (.html, .htm) - Páginas web
XML (.xml) - Dados estruturados
Markdown (.md) - Documentação técnica

📝 Formatos de Texto Simples:

TXT (.txt) - Texto simples
CSV (.csv) - Dados tabulares
TSV (.tsv) - Dados tabulares separados por tabulações

📊 Formatos de Dados:

JSON (.json) - Dados estruturados
YAML (.yaml, .yml) - Configurações e dados

🖼️ Imagens (com OCR):

PNG (.png) - Imagens com texto
JPG/JPEG (.jpg, .jpeg) - Fotografias com texto
TIFF (.tiff) - Imagens de alta qualidade
BMP (.bmp) - Imagens bitmap

📧 E-mails:

EML (.eml) - Arquivos de e-mail
MSG (.msg) - Mensagens do Outlook

🛠️ Guia de Uso

Uso 1: Popular a Base de Conhecimento com a GUI (Recomendado)

A forma mais fácil e intuitiva de adicionar documentos é usando a interface gráfica.

Execute o script principal: start.bat
Selecione "1" para executar o aplicativo
O aplicativo será iniciado (na primeira vez pode demorar enquanto instala as dependências)
Use o botão "Explorar..." para selecionar a pasta com seus documentos
Clique em "Iniciar Processamento". Os arquivos serão processados com o sistema avançado do Unstructured
Vá para a aba "Revisão", selecione os arquivos que deseja salvar e visualize o conteúdo
Vá para a aba "Armazenamento" e clique em "Iniciar Armazenamento" para salvar os documentos selecionados no banco de dados

✨ GUI para ingestão massiva de documentos com Visualização e Seleção

Para um controle total sobre o processo de ingestão, adicionamos uma GUI. Esta versão permite visualizar o conteúdo de cada documento processado e selecionar manualmente quais deseja incluir na base de conhecimento. Características da GUI:

Processamento Inteligente: Usa Unstructured para limpar ruído e preservar estrutura
Pré-visualização em Tempo Real: Veja o conteúdo processado antes de armazenar
Seleção Granular: Marque/desmarque documentos individualmente
Metadados Estruturais: Informações sobre títulos, tabelas, listas em cada documento
Sistema de Fallbacks: Múltiplas estratégias garantem que todo documento seja processado
Sistema de Progresso: Acompanhamento detalhado do processo de armazenamento

Pestaña de Procesamiento de la GUI

➡️ Para um guia completo sobre como usá-la, consulte o Guia de Carga em Massa.

Uso 2: Popular a Base de Conhecimento pela Linha de Comando

Se você prefere usar a linha de comando ou precisa automatizar a ingestão.

Abra um terminal
Ative o ambiente virtual: .\.venv\Scripts\activate
Execute o script bulk_ingest.py apontando para sua pasta de documentos:
```
python bulk_ingest.py --directory "C:\Ruta\A\Tus\Documentos"
```

Características do Processamento Aprimorado:

Detecção Automática de Formato: O sistema identifica e otimiza o processamento conforme o tipo de arquivo
Limpeza Inteligente: Remove automaticamente cabeçalhos, rodapés e conteúdo irrelevante
Preservação de Estrutura: Mantém títulos, listas e tabelas organizadas
Metadados Enriquecedores: Informações detalhadas sobre a estrutura de cada documento
Logs Detalhados: Informações completas sobre o processo de cada arquivo

Uso 3: Configuração do Cliente MCP (Ex.: Cursor)

Para que seu editor de IA possa usar o servidor, você deve configurá-lo.

Encontre o arquivo de configuração de servidores MCP do seu editor. Para o Cursor, procure um arquivo como mcp_servers.json em seu diretório de configuração (%APPDATA%\cursor no Windows). Se não existir, você pode criá-lo.
Adicione a seguinte configuração ao arquivo JSON.

Este método utiliza o script do servidor MCP (run_server_organized.bat) para executar o servidor RAG.

IMPORTANTE! Você deve substituir "D:\\ruta\\completa\\a\\tu\\proyecto\\MCP_RAG" pelo caminho absoluto real para a pasta deste projeto em sua máquina.
```
{
  "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"
    }
  }
}
```
Reinicie seu editor. Ao iniciar, ele deve detectar e lançar o servidor MCP, que exporá as ferramentas RAG para uso no chat.

Uso 4: Interagindo com as Ferramentas

Uma vez configurado, você pode usar as ferramentas diretamente no chat do seu editor.

Ferramentas Disponíveis:

1. learn_text(text, source_name) - Adicionar informação textual

@rag learn_text("El punto de fusión del titanio es 1,668 °C.", "material_properties")

Quando usar: Para adicionar fatos, definições, notas de conversa, etc.
Parâmetros:
- text: O conteúdo a ser armazenado
- source_name: Nome descritivo da fonte (opcional, padrão "manual_input")

2. learn_document(file_path) - Processar documentos

@rag learn_document("C:\\Reportes\\informe_q3.pdf")

Quando usar: Para processar arquivos PDF, DOCX, PPTX, XLSX, TXT, HTML, CSV, JSON, XML, imagens, e-mails e mais de 25 formatos
Características Aprimoradas:
- Processamento Inteligente: Usa Unstructured para limpar ruído e preservar estrutura
- Sistema de Fallbacks: Múltiplas estratégias garantem processamento bem-sucedido
- Metadados Estruturais: Informações detalhadas sobre títulos, tabelas, listas
- Conversão Automática: Processamento otimizado conforme o tipo de arquivo
- Cópias Salvas: Documentos processados salvos em ./converted_docs/

3. ask_rag(query) - Consultar informações

@rag ask_rag("¿Cuál es el punto de fusión del titanio?")

Quando usar: Para buscar informações previamente armazenadas
A resposta inclui:
- Resposta gerada por IA com contexto aprimorado
- 📚 Lista de fontes utilizadas com metadados estruturais
- Informações sobre a relevância de cada fonte

4. ask_rag_filtered(query, file_type, min_tables, min_titles, processing_method) - Buscas com filtros

@rag ask_rag_filtered("¿Qué tablas de datos tenemos?", file_type=".pdf", min_tables=1)

Quando usar: Para buscas mais precisas usando filtros de metadados
Filtros disponíveis:
- file_type: Tipo de arquivo (ex.: ".pdf", ".docx", ".xlsx")
- min_tables: Número mínimo de tabelas no documento
- min_titles: Número mínimo de títulos no documento
- processing_method: Método de processamento usado
Vantagens: Buscas mais relevantes e específicas

5. get_knowledge_base_stats() - Estatísticas da base de conhecimentos

@rag get_knowledge_base_stats()

Quando usar: Para obter informações sobre o conteúdo armazenado
Informações fornecidas:
- Número total de documentos
- Distribuição por tipo de arquivo
- Estatísticas de estrutura (tabelas, títulos, listas)
- Métodos de processamento utilizados

Exemplo de Fluxo Completo:

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

Resposta 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

🧪 Testes e Verificação

Testar o Sistema

Para verificar se tudo funciona corretamente:

# Probar el sistema RAG mejorado con todas las características
python test_enhanced_rag.py

Script de Testes Aprimorado (`test_enhanced_rag.py`)

O script de testes verifica todas as melhorias implementadas:

🧪 Testes Incluídos:

Processamento Aprimorado de Documentos: Verifica o sistema Unstructured com metadados estruturais
Base de Conhecimentos Aprimorada: Testa o chunking aprimorado e metadados enriquecidos
Integração do Servidor MCP: Verifica as ferramentas aprimoradas do servidor
Suporte de Formatos: Confirma a configuração para mais de 25 formatos

📊 Informações de Saída:

Status de cada teste (✅ PASSOU / ❌ FALHOU)
Metadados estruturais extraídos
Método de processamento utilizado
Informações de fontes e chunks
Resumo completo do sistema

Verificar a Base de Dados

Os documentos processados são armazenados em:

Base de dados vetorial: ./rag_mcp_db/
Cópias processadas: ./converted_docs/ (com informações do método de processamento)

🤖 Uso por Agentes de IA

O sistema é otimizado para uso por agentes de IA. Consulte AGENT_INSTRUCTIONS.md para:

Guias detalhados de uso
Exemplos de casos de uso
Melhores práticas
Tratamento de erros
Considerações importantes

Características para Agentes:

Descrições detalhadas de cada ferramenta
Exemplos de uso claros e específicos
Tratamento de erros inteligente com sugestões úteis
Metadados de fonte para rastreabilidade completa
Respostas estruturadas com informações de fontes

🔧 Melhorias Técnicas Implementadas

Esta seção explica as melhorias técnicas avançadas que transformaram o sistema em uma solução de nível empresarial.

A. Processamento Inteligente com Unstructured

O que é Unstructured?

Unstructured é uma biblioteca de processamento de documentos que vai além da simples extração de texto. Ela analisa a estrutura semântica dos documentos para:

Identificar elementos: Títulos, parágrafos, listas, tabelas
Limpar ruído: Remover cabeçalhos, rodapés, elementos irrelevantes
Preservar contexto: Manter a hierarquia e estrutura do documento
Lidar com formatos complexos: PDFs escaneados, documentos com tabelas, etc.

Configuração Otimizada por Tipo de Arquivo:

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
}

Processamento Inteligente de Elementos:

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

Estratégia de Fallbacks em Cascata:

O sistema tenta múltiplas estratégias em ordem de preferência:

Unstructured com Configuração Ótima
- Usa a configuração específica para o tipo de arquivo
- Máxima qualidade de processamento
Unstructured com Configuração Básica
- Estratégia "fast" para compatibilidade
- Processamento mais simples, porém funcional
Carregadores Específicos do LangChain
- Carregadores especializados por tipo de arquivo
- Último recurso para formatos problemáticos

Exemplo de Fallback em Ação:

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. Metadados Estruturais Enriquecedores

Informações Estruturais Capturadas:

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
    }

Benefícios dos Metadados Estruturais:

Rastreabilidade: Você sabe exatamente qual parte do documento foi usada
Qualidade: Informações sobre a estrutura do conteúdo
Otimização: Dados para melhorar o processamento futuro
Debugging: Informações detalhadas para resolver problemas

D. Divisão Inteligente de Texto Aprimorada

Configuração Otimizada:

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:

O sistema busca os melhores pontos de divisão nesta ordem:

\n\n - Parágrafos (melhor opção)
\n - Quebras de linha
. - Final de frases
! - Final de exclamações
? - Final de perguntas
- Espaços (último recurso)

E. Motor de Busca Otimizado

Configuração Atual:

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 Otimizados:

k=5: Você obtém informações de 5 fontes diferentes para respostas mais completas
score_threshold=0.3: Garante que apenas informações muito relevantes sejam usadas (similaridade > 70%)
Busca por similaridade: Encontra o conteúdo mais semanticamente semelhante

F. Limpeza Automática de Texto

Processo de Limpeza:

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 Filtragem de Metadados Avançado

Funcionalidades de Filtragem:

O sistema agora inclui capacidades avançadas de filtragem que permitem buscas mais precisas e relevantes:

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

Buscas com Filtros:

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

Estatísticas da Base de Conhecimentos:

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 Filtragem:

Busca por Tipo de Arquivo:

# Solo buscar en PDFs
pdf_filter = create_metadata_filter(file_type=".pdf")
results = search_with_metadata_filters(vector_store, "datos", pdf_filter)

Busca por Estrutura:

# Solo documentos con tablas
tables_filter = create_metadata_filter(min_tables=1)
results = search_with_metadata_filters(vector_store, "datos tabulares", tables_filter)

Busca por Método de Processamento:

# Solo documentos procesados con Unstructured
unstructured_filter = create_metadata_filter(processing_method="unstructured_enhanced")
results = search_with_metadata_filters(vector_store, "contenido", unstructured_filter)

Filtros Combinados:

# 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. Ferramentas MCP Aprimoradas

Novas Ferramentas Disponíveis:

ask_rag_filtered: Buscas com filtros de metadados
get_knowledge_base_stats: Estatísticas detalhadas da base de conhecimentos

Integração com Agentes de IA:

As novas ferramentas são otimizadas para uso por agentes de IA com:

Descrições detalhadas de parâmetros e casos de uso
Exemplos específicos de cada ferramenta
Tratamento de erros inteligente com sugestões úteis
Respostas estruturadas com informações de metadados

Servidor RAG Personal con MCP

Documentação

Servidor RAG Personal con MCP

✨ Características

🏗️ Arquitetura

Estrutura do Projeto:

Componentes Principais:

1. Servidor MCP (mcp_server_organized/)

2. Interface Gráfica (bulk_ingest_GUI/)

3. Scripts de Sistema

Fluxo de Dados:

Separação de Responsabilidades:

Arquivos de Documentação:

🚀 Guia de Instalação e Configuração

Pré-requisitos

1. Instalação (Automática!)

Para Usuários (Recomendado):

Para Desenvolvedores:

2. Instalação Manual de Dependências (Opcional)

3. Configuração do Ollama (Passo Crítico)

Instalação do Ollama

Verificar Instalação

Baixar Modelos de Linguagem

Configurar o Modelo no Sistema

Testar o Ollama

Solução de Problemas Comuns

4. Verificação Completa do Sistema

Passo 1: Verificar o Ollama

Passo 2: Verificar Dependências do Python

Passo 3: Testar o Sistema RAG

📋 Formatos de Arquivo Suportados

📄 Documentos do Office:

📁 Documentos OpenDocument:

🌐 Formatos Web e Markup:

📝 Formatos de Texto Simples:

📊 Formatos de Dados:

🖼️ Imagens (com OCR):

📧 E-mails:

🛠️ Guia de Uso

Uso 1: Popular a Base de Conhecimento com a GUI (Recomendado)

✨ GUI para ingestão massiva de documentos com Visualização e Seleção

Uso 2: Popular a Base de Conhecimento pela Linha de Comando

Uso 3: Configuração do Cliente MCP (Ex.: Cursor)

Uso 4: Interagindo com as Ferramentas

Ferramentas Disponíveis:

Exemplo de Fluxo Completo:

🧪 Testes e Verificação

Testar o Sistema

Script de Testes Aprimorado (test_enhanced_rag.py)

Verificar a Base de Dados

🤖 Uso por Agentes de IA

Características para Agentes:

🔧 Melhorias Técnicas Implementadas

A. Processamento Inteligente com Unstructured

O que é Unstructured?

Configuração Otimizada por Tipo de Arquivo:

Processamento Inteligente de Elementos:

B. Sistema de Fallbacks Robusto

Estratégia de Fallbacks em Cascata:

Exemplo de Fallback em Ação:

C. Metadados Estruturais Enriquecedores

Informações Estruturais Capturadas:

Benefícios dos Metadados Estruturais:

D. Divisão Inteligente de Texto Aprimorada

Configuração Otimizada:

Separadores Inteligentes:

E. Motor de Busca Otimizado

Configuração Atual:

Parâmetros Otimizados:

F. Limpeza Automática de Texto

Processo de Limpeza:

G. Sistema de Filtragem de Metadados Avançado

Funcionalidades de Filtragem:

Buscas com Filtros:

Estatísticas da Base de Conhecimentos:

Casos de Uso de Filtragem:

H. Ferramentas MCP Aprimoradas

Novas Ferramentas Disponíveis:

Integração com Agentes de IA:

1. Servidor MCP (`mcp_server_organized/`)

2. Interface Gráfica (`bulk_ingest_GUI/`)

Script de Testes Aprimorado (`test_enhanced_rag.py`)