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 (Memória):
- 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 (Política):
- 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 (Controlador):
- 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.

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.

RAG MCP Server

README Documentation