Agent Factory

Assistente corporativo para consulta de documentos internos via RAG (Retrieval-Augmented Generation). Faça upload de PDFs e obtenha respostas objetivas com rastreabilidade de fontes.

Stack

Camada	Tecnologia
Backend	FastAPI + Python 3.12
LLM	Groq API (llama3-70b-8192)
Embeddings	SentenceTransformers (paraphrase-multilingual-mpnet-base-v2)
Busca	FAISS (semântico) + BM25 (keyword) — busca híbrida
OCR	Tesseract + pdfplumber
Frontend	React 18 + TypeScript + Vite 5
Estilização	Tailwind CSS v4
Testes (FE)	Vitest + Testing Library

---

Estrutura do projeto

agent_factory_unimedpoa/
├── backend/
│   ├── app/
│   │   ├── main.py        # Rotas FastAPI
│   │   ├── store.py       # Vector store (FAISS + BM25)
│   │   ├── rag.py         # Chunking e processamento de PDFs
│   │   └── config.py      # Configurações via variáveis de ambiente
│   ├── data/
│   │   ├── projects/      # Índices por projeto (gerado em runtime)
│   │   └── uploads/       # PDFs enviados (gerado em runtime)
│   ├── tests/
│   │   └── test_api.py
│   ├── requirements.txt
│   └── .env.example
└── frontend/
    ├── src/
    │   ├── App.tsx
    │   ├── index.css
    │   ├── main.tsx
    │   ├── types/          # Interfaces TypeScript
    │   ├── services/       # Camada de API (axios)
    │   ├── context/        # Estado global (useReducer + Context)
    │   ├── hooks/          # useProjects, useDocuments, useChat
    │   └── components/
    │       ├── common/     # ErrorBoundary, Notice
    │       ├── layout/     # Sidebar, Topbar, Drawer
    │       ├── chat/       # ChatArea, MessageBubble, SourcesList, Composer
    │       └── documents/  # UploadForm, DocumentList
    ├── package.json
    ├── vite.config.ts
    └── .env.example

---

Configuração e execução

Pré-requisitos

• Python 3.12+
• Node.js 18+
• Tesseract OCR instalado no sistema (para OCR de PDFs)
• Conta na Groq com chave de API

Backend

# 1. Criar e ativar virtualenv
cd backend
python -m venv .venv

# Windows
.\.venv\Scripts\Activate.ps1
# Linux / macOS
source .venv/bin/activate

# 2. Instalar dependências
pip install -r requirements.txt

# 3. Configurar variáveis de ambiente
cp .env.example .env
# Edite .env e preencha GROQ_API_KEY

# 4. Iniciar o servidor
uvicorn app.main:app --reload --port 8000

Variáveis disponíveis em backend/.env:

Variável	Padrão	Descrição
GROQ_API_KEY	—	Chave da API Groq (obrigatória)
GROQ_MODEL	llama3-70b-8192	Modelo LLM utilizado
EMBED_MODEL	paraphrase-multilingual-mpnet-base-v2	Modelo de embeddings
CHUNK_SIZE	400	Tamanho dos chunks de texto
CHUNK_OVERLAP	80	Sobreposição entre chunks
TOP_K	6	Quantidade de trechos retornados na busca
ALPHA	0.65	Peso semântico vs BM25 (0 = só BM25, 1 = só FAISS)
API_KEY	—	Chave opcional para proteger a API (X-API-Key)
MAX_UPLOAD_MB	25	Tamanho máximo de upload em MB
OCR_ENABLED	true	Ativar OCR em PDFs sem texto extraível
OCR_LANG	por	Idioma do Tesseract OCR
OCR_MAX_PAGES	10	Limite de páginas processadas via OCR

API disponível em http://localhost:8000. Documentação interativa em http://localhost:8000/docs.

Frontend

# 1. Instalar dependências
cd frontend
npm install

# 2. Configurar variáveis de ambiente
cp .env.example .env

# 3. Iniciar em desenvolvimento
npm run dev

Variáveis disponíveis em frontend/.env:

Variável	Padrão	Descrição
VITE_API_BASE	http://localhost:8000	URL base do backend
VITE_API_KEY	—	Chave de API (se API_KEY estiver configurada no backend)

Acesse http://localhost:5173.

---

Scripts do frontend

Comando	Descrição
npm run dev	Servidor de desenvolvimento
npm run build	Build de produção (TypeScript + Vite)
npm run preview	Preview do build gerado
npm run lint	ESLint nos arquivos .ts/.tsx
npm run format	Prettier em src/
npm run test	Vitest em modo watch
npm run coverage	Cobertura de testes

---

API

Todos os endpoints aceitam o header opcional X-API-Key quando API_KEY está configurado no backend.

Método	Endpoint	Descrição
POST	/api/upload	Upload de PDF (multipart/form-data: file, project_id)
POST	/api/ask	Pergunta ao documento ({ question, project_id })
GET	/api/projects	Lista todos os projetos
POST	/api/projects	Cria projeto (form-data: project_id)
DELETE	/api/projects/{project_id}	Exclui projeto e seus índices
GET	/api/projects/{project_id}/documents	Lista documentos com paginação e filtro
DELETE	/api/projects/{project_id}/documents/{doc_id}	Exclui documento específico

---

Como usar

1. Crie um projeto — clique em "Novo projeto" na sidebar e dê um nome
2. Envie um PDF — use o formulário de upload na área inferior
3. Faça sua pergunta — digite na caixa de texto e pressione Enter ou clique em "Perguntar"
4. Consulte as fontes — clique em "Fontes utilizadas" abaixo de cada resposta, ou abra o Painel lateral

---

Testes do backend

cd backend
pytest tests/ -v

---

Multi-tenant

Cada project_id mantém um índice FAISS e BM25 independente. Múltiplos usuários podem trabalhar em projetos diferentes simultaneamente sem interferência.