Projeto de RAG com Arquitetura MCP

Aplicação de Busca Aumentada por Geração (RAG) para consulta de documentos, reestruturada com a arquitetura Memory, Controller, Policy (MCP) para maior clareza, manutenibilidade e escalabilidade.

Relatório de Melhorias: Da Arquitetura Inicial para MCP

1. Estado Inicial do Projeto

O projeto inicial já era funcional e implementava um fluxo RAG básico. No entanto, a arquitetura apresentava os seguintes desafios:

Alto Acoplamento: A lógica de negócio, as chamadas à API do Pinecone e a formatação de prompts para o LLM estavam misturadas nos mesmos arquivos de rota da API (ex: llm_router.py).
Dificuldade de Manutenção: Qualquer alteração, como a troca do modelo de embedding ou a adição de uma nova regra de negócio, exigiria modificar múltiplos arquivos e funções interligadas.
Baixa Escalabilidade: Adicionar novos fluxos, como um histórico de conversas ou regras de acesso mais complexas, seria complicado e tornaria o código progressivamente mais confuso.

2. Solução Implementada (Arquitetura MCP)

Para resolver esses desafios, o projeto foi refatorado para adotar o padrão de arquitetura Memory, Controller, Policy (MCP), que separa claramente as responsabilidades do sistema.

Componentes da Arquitetura MCP:

Memory
- Responsabilidade: Gerenciar o estado e o conhecimento de longo prazo do sistema.
- Implementação: A pasta memory/ e o arquivo pinecone_memory.py agora centralizam toda a interação com o banco de dados vetorial (Pinecone). Qualquer operação de busca ou salvamento de documentos passa por esta camada.
Policy
- Responsabilidade: Aplicar regras de negócio, validações e restrições.
- Implementação: A pasta policy/ e o arquivo policy.py contêm a lógica para validar perguntas, filtrar resultados com base em score de relevância, ou aplicar quaisquer outras regras de negócio (ex: anonimização de dados, controle de acesso).
Controller
- Responsabilidade: Orquestrar todo o fluxo de uma requisição. Ele atua como o "cérebro" da operação.
- Implementação: A pasta controller/ e o arquivo controller.py recebem a requisição, utilizam a Memory para buscar o contexto, aplicam as regras da Policy e, finalmente, montam o prompt e chamam o LLM (Gemini) para gerar a resposta.

3. Principais Vantagens da Nova Arquitetura

Separação de Responsabilidades: Cada componente tem um único trabalho, tornando o código mais limpo e fácil de entender.
Facilidade de Manutenção: Precisa trocar o Pinecone por outro banco vetorial? Modifique apenas a camada de Memory. Quer adicionar novas regras de negócio? Trabalhe apenas na camada de Policy.
Escalabilidade: É simples adicionar novas funcionalidades. Por exemplo, para implementar um histórico de conversas, basta expandir a camada de Memory e ajustar o Controller para usá-lo.
Testabilidade: Cada camada (Memory, Controller, Policy) pode ser testada de forma isolada, garantindo maior qualidade e confiabilidade do código.

Related MCP server: RAG_MCP

Diagrama da Nova Arquitetura

graph TD subgraph "API Layer" A[FastAPI: /mcp/ask] end subgraph "Application Core (MCP)" B[Controller] C[Policy] D[Memory] end subgraph "External Services" E[Pinecone DB] F[Gemini LLM] end A -- Requisição --> B B -- Aplica Regras --> C B -- Busca Contexto --> D D <--> E B -- Gera Resposta --> F F -- Resposta --> B B -- Resposta Final --> A

Como Configurar e Rodar o Projeto

Pré-requisitos

Python 3.9+
Conta no Pinecone
Chave de API da Google (Gemini)

1. Crie o Ambiente Virtual

python -m venv venv

2. Ative o Ambiente Virtual

Windows (PowerShell):
.\venv\Scripts\activate
Linux/macOS:
source venv/bin/activate

3. Instale as Dependências

pip install -r requirements.txt

4. Configure as Variáveis de Ambiente

Renomeie o arquivo .env.example para .env.
Abra o arquivo .env e preencha com suas chaves de API:
PINECONE_API_KEY="SUA_CHAVE_PINECONE" PINECONE_HOST="SEU_HOST_PINECONE" PINECONE_INDEX_NAME="brito-ai" GEMINI_API_KEY="SUA_CHAVE_GEMINI"

5. Rodar o Back-End

uvicorn api_mcp:app --reload --host 0.0.0.0 --port 8000

6. Rodar o Front-End

cd frontend npm run dev

7. Rode o Servidor da API

uvicorn api_mcp:app --reload

O servidor estará disponível em http://127.0.0.1:8000/docs.

Como Usar a API

Acesse a documentação interativa no seu navegador: http://127.0.0.1:8000/docs.
Encontre o endpoint POST /mcp/ask.
Clique em "Try it out".
Preencha o corpo da requisição com sua pergunta. Exemplo:
{ "pergunta": "Quais são as principais cláusulas do contrato de aluguel?", "max_results": 3 }
Clique em "Execute" para ver a resposta gerada pelo sistema.