# Manual RAG — Auditoria de Faturamento SIH/SUS
Sistema RAG (Retrieval-Augmented Generation) para auditoria de faturamento hospitalar SIH/SUS com consulta de manuais, portarias, SIGTAP e CNES em linguagem natural.
Funciona como **MCP Server** para o Claude Code, expondo **43 tools** organizadas em 8 módulos: RAG, SIGTAP, CNES, auditoria, auditoria de AIH, inteligência, legacy e health.
**v2.1.0** — Busca híbrida (semântica + BM25), DuckDB/DATASUS client, Docker Compose, parent-child chunking.
## Instalação rápida
```bash
cd scripts/manual-rag
bash setup.sh
```
O script cria o venv, instala dependências, indexa os documentos (se existirem em `ragData/`) e registra o MCP server no Claude Code.
## Instalação manual
### 1. Ambiente e dependências
```bash
cd scripts/manual-rag
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```
### 2. Alimentar o banco vetorial
Coloque PDFs em `ragData/manuais/` e portarias em `ragData/portarias/`, depois:
```bash
python extrair_manual.py --ragdata ragData/
python scripts/indexar_manual.py
```
### 3. Registrar MCP no Claude Code
```bash
# Local (este repo)
claude mcp add manual-sih -- .venv/bin/python mcp_server.py
# Global (qualquer repo)
pip install -e .
claude mcp add --scope user manual-sih -- manual-sih-mcp
```
Abra uma nova sessão do Claude Code — as 43 tools ficam disponíveis automaticamente.
### 4. SIGTAP e CNES via DATASUS
As tools de SIGTAP e CNES usam DuckDB sobre Parquet armazenado no MinIO. Precisa do container do `modulo-processos` rodando:
```bash
cd modulo-processos && docker compose up -d minio
```
Copie `.env.example` para `.env` e ajuste se necessário:
```bash
cp .env.example .env
```
Variáveis relevantes:
| Variável | Default | Descrição |
|----------|---------|-----------|
| `S3_ENDPOINT` | `http://localhost:9000` | Endpoint MinIO/S3 |
| `AWS_ACCESS_KEY_ID` | `minioadmin` | Credencial S3 |
| `AWS_SECRET_ACCESS_KEY` | `minioadmin` | Credencial S3 |
| `DATASUS_BUCKET` | `bucket-datasus` | Bucket com Parquets SIGTAP/CNES |
| `CHROMA_HOST` | `localhost` | Host ChromaDB (para modo Docker) |
| `CHROMA_PORT` | `8000` | Porta ChromaDB |
| `MCP_HOST` | `0.0.0.0` | Host do MCP Server (modo SSE) |
| `MCP_PORT` | `8200` | Porta do MCP Server (modo SSE) |
| `LOG_LEVEL` | `WARNING` | Nível de log |
### 5. Docker Compose (opcional)
Para rodar o MCP Server e ChromaDB em containers:
```bash
docker compose up -d
```
Expõe o MCP Server na porta `8200` e ChromaDB na `8201`.
### API Key (para `/explicar` e `analisar_critica.py`)
```bash
export GEMINI_API_KEY="sua-chave"
```
Ou salve em arquivo:
```bash
mkdir -p ~/.config/google
echo "sua-chave" > ~/.config/google/api_key
chmod 600 ~/.config/google/api_key
```
## Alimentar o banco
### Opção 1: Processar todo o ragData (recomendado)
Processa recursivamente todos os arquivos em `ragData/` (PDFs, HTMLs, DOCs, ZIPs):
```bash
source .venv/bin/activate
python extrair_manual.py --ragdata ragData/
python scripts/indexar_manual.py
```
### Opção 2: PDFs individuais
```bash
# Múltiplos PDFs
python extrair_manual.py manual1.pdf manual2.pdf
# Adicionar sem apagar existentes
python extrair_manual.py --adicionar novo.pdf
```
### Opção 3: Auto-detecção
Se nenhum argumento for passado, procura `*.pdf` no diretório raiz do projeto:
```bash
python extrair_manual.py
```
Após qualquer extração, sempre indexar:
```bash
python scripts/indexar_manual.py
```
A indexação gera embeddings (paraphrase-multilingual-MiniLM-L12-v2) no ChromaDB e um índice BM25 para busca híbrida.
## Uso
### `consulta_manual.py` — Consulta interativa
Busca semântica no manual em linguagem natural.
```bash
# Modo interativo
python consulta_manual.py
# Consulta direta (uma pergunta)
python consulta_manual.py 'como registrar politraumatizado na AIH'
```
**Comandos no modo interativo:**
| Comando | Ação |
|---------|------|
| `<pergunta>` | Busca semântica no manual |
| `/explicar N` | Explica como a crítica N é validada (usa IA + RAG + código) |
| `/critica` | Modo validação de críticas (busca semântica simples) |
| `/fontes` | Lista todas as fontes indexadas com tipo e ano |
| `/secoes` | Lista todas as seções do manual |
| `/buscar N` | Altera quantidade de resultados (padrão: 5) |
| `sair` | Encerra |
#### `/explicar N` — Como funciona a validação de uma crítica
Combina o código TypeScript da crítica + trechos relevantes do manual + Claude para gerar uma explicação didática:
1. O que a crítica verifica
2. Passo a passo da validação
3. Campos envolvidos
4. Exceções (quando NÃO gera crítica)
5. Fundamentação no manual (com seção e página)
Após a explicação, abre modo interativo para perguntas de follow-up.
```
Manual SIH> /explicar 92
```
### `analisar_critica.py` — Agente de Análise Crítica (IA)
Envia o código + trechos do manual para o Claude e recebe um parecer estruturado de conformidade.
```bash
# Analisar uma crítica
python analisar_critica.py 92
# Analisar e salvar resultado em data/analises/
python analisar_critica.py 92 --salvar
# Analisar TODAS as críticas
python analisar_critica.py --todas --salvar
```
**O parecer inclui:**
- Resumo da regra
- O que o código faz (passo a passo)
- O que o manual diz (com seção e página)
- **Veredicto: CONFORME / PARCIALMENTE CONFORME / NÃO CONFORME**
- Pontos conformes, lacunas, excessos e riscos
- Recomendações concretas
Após a análise, abre modo interativo para perguntas de follow-up com contexto mantido.
**Com `--salvar`**, gera em `data/analises/`:
- `analise_critica_92.json` — dados estruturados
- `analise_critica_92.md` — parecer em markdown
### `validar_critica.py` — Código vs Manual (sem IA)
Mostra o código de uma crítica lado a lado com as seções do manual que a fundamentam.
```bash
python validar_critica.py 129
```
**Comandos internos:** `/codigo` (ver código completo), `/full` (ver todas as seções encontradas)
### `mapear_criticas.py` — Referência cruzada em lote
Mapeia automaticamente todas as críticas de `processos-criticas` para as seções do manual.
```bash
python scripts/mapear_criticas.py
```
Gera tabela no terminal e salva `data/mapeamento_criticas_manual.json`.
### `extrair_manual.py` — Extração de texto
```bash
# Processar todo ragData (PDFs, HTMLs, DOCs, ZIPs)
python extrair_manual.py --ragdata ragData/
# PDFs individuais
python extrair_manual.py manual1.pdf manual2.pdf
# Adicionar sem apagar existentes
python extrair_manual.py --adicionar novo.pdf
```
Formatos suportados:
- **PDF**: Manuais SIH/SUS (extração por seções numeradas) ou genérico (por página/parágrafo)
- **HTML/HTM**: Portarias em HTML (encoding windows-1252/latin-1/utf-8)
- **DOC**: Documentos legados (via libreoffice --headless)
- **ZIP**: Extrai e processa recursivamente o conteúdo
Anexos SIGTAP (tabelas de procedimentos) são detectados automaticamente e limitados a 10 páginas.
Gera parent-child chunks em `data/chunks.json`.
### `indexar_manual.py` — Indexação vetorial + BM25
Gera embeddings e indexa no ChromaDB. Constrói índice BM25 para busca híbrida. Deve ser executado após cada `extrair_manual.py`.
```bash
python scripts/indexar_manual.py
```
## MCP Tools (43)
### RAG — Busca no manual (10 tools)
| Tool | Descrição |
|------|-----------|
| `buscar_manual` | Busca semântica no manual SIH/SUS |
| `buscar_critica` | Busca crítica por número |
| `listar_criticas` | Lista críticas com filtro |
| `buscar_por_secao` | Busca seção por número |
| `verificar_citacao` | Verifica se seção existe antes de citá-la |
| `extrair_dados_aih` | Extrai dados de espelho de AIH (texto livre) |
| `ler_codigo_critica` | Lê código TypeScript da crítica |
| `contexto_critica` | Contexto completo: código + manual + mapeamento |
| `listar_fontes` | Fontes indexadas no banco com tipo e ano |
| `listar_secoes` | Seções do manual |
### SIGTAP — Procedimentos SUS (13 tools)
| Tool | Descrição |
|------|-----------|
| `consultar_procedimento` | Procedimento SIGTAP por código (legacy) |
| `buscar_procedimento` | Busca SIGTAP por nome (legacy) |
| `info_sigtap` | Metadata do SIGTAP carregado |
| `consultar_procedimento_completo` | Procedimento com todas as tabelas relacionadas |
| `buscar_cid` | Busca CID por nome |
| `consultar_cid` | CID por código |
| `listar_cids_procedimento` | CIDs compatíveis com um procedimento |
| `listar_compatibilidades` | Compatibilidades de um procedimento |
| `consultar_habilitacoes_procedimento` | Habilitações exigidas por procedimento |
| `consultar_servicos_procedimento` | Serviços/classificações exigidos |
| `consultar_ocupacoes_procedimento` | Ocupações (CBO) permitidas |
| `consultar_leitos_procedimento` | Tipos de leito compatíveis |
| `consultar_incrementos` | Incrementos financeiros aplicáveis |
### SIGTAP — Hierarquia e regras (3 tools)
| Tool | Descrição |
|------|-----------|
| `consultar_hierarquia_sigtap` | Grupo/subgrupo/forma de organização |
| `consultar_descricao_procedimento` | Descrição detalhada do procedimento |
| `consultar_regras_condicionadas` | Regras condicionadas do procedimento |
### CNES — Estabelecimentos (8 tools)
| Tool | Descrição |
|------|-----------|
| `consultar_cnes` | Dados operacionais de um CNES (legacy) |
| `buscar_profissionais_cnes` | Profissionais de um CNES (legacy) |
| `info_cnes` | Metadata do CNES carregado |
| `consultar_cnes_completo` | CNES com leitos, serviços, habilitações e equipes |
| `consultar_leitos_cnes_detalhado` | Leitos de um CNES com SUS/não-SUS |
| `consultar_servicos_cnes_detalhado` | Serviços/classificações de um CNES |
| `consultar_habilitacoes_cnes_detalhado` | Habilitações de um CNES |
| `buscar_profissionais_detalhado` | Profissionais com CBO, carga horária, vínculos |
### CNES — Profissionais (1 tool)
| Tool | Descrição |
|------|-----------|
| `consultar_dados_profissional` | Dados de profissional por CNS/CPF |
### Auditoria (3 tools)
| Tool | Descrição |
|------|-----------|
| `validar_procedimento_cnes` | Valida procedimento vs capacidade do CNES |
| `validar_cid_procedimento` | Valida compatibilidade CID x procedimento |
| `perfil_auditoria` | Perfil completo do CNES para auditoria |
### Auditoria de AIH (2 tools)
| Tool | Descrição |
|------|-----------|
| `auditar_aih` | Auditoria completa: procedimento + CID + CNES + profissional |
| `calcular_valor_aih` | Calcula valor da AIH com incrementos |
### Inteligência (2 tools)
| Tool | Descrição |
|------|-----------|
| `sugerir_procedimentos_por_cid` | Sugere procedimentos a partir de um CID |
| `comparar_procedimento_competencias` | Compara procedimento entre competências SIGTAP |
### Health (2 tools)
| Tool | Descrição |
|------|-----------|
| `health_check` | Status de todos os subsistemas (RAG, DATASUS, etc.) |
| `info_servidor` | Versão, tools registradas e configuração |
## Entry points
| Comando | Descrição |
|---------|-----------|
| `manual-sih` | Consulta interativa (CLI) |
| `manual-sih-mcp` | MCP Server modo stdio (para Claude Code) |
| `manual-sih-server` | MCP Server modo SSE (servidor compartilhado) |
## Estrutura
```
scripts/manual-rag/
src/manual_sih_rag/ # Pacote principal
config.py # Configuração centralizada (env vars)
rag/ # Motor RAG
engine.py # Carregar sistema (model + collection)
hybrid_search.py # Busca híbrida semântica + BM25
search_primitives.py # Tokenização e primitivas de busca
aih_parser.py # Parser de espelhos de AIH
hints.py # Hints de busca por tipo
paths.py # Caminhos do projeto
datasus/ # Client DATASUS (DuckDB + S3/MinIO)
client.py # Client principal com connection pool
connection.py # Gerenciamento de conexões DuckDB
cache.py # Cache de queries
metrics.py # Métricas de uso
schemas.py # Schemas de dados
sigtap/ # Namespace SIGTAP (resources + types)
cnes/ # Namespace CNES (resources + types)
tools/ # MCP Tools (43 tools em 8 módulos)
rag_tools.py # 10 tools de busca no manual
sigtap_tools.py # 13 tools SIGTAP completo
cnes_tools.py # 6 tools CNES detalhado
auditoria_tools.py # 3 tools de auditoria
auditoria_aih_tools.py # 2 tools de auditoria de AIH
inteligencia_tools.py # 2 tools de inteligência
legacy_tools.py # 6 tools legacy (SIGTAP/CNES básico)
health_tools.py # 2 tools de health check
criticas/ # Leitura e análise de críticas
extraction/ # Extração multi-formato (PDF, HTML, DOC, ZIP)
validation/ # Validação de respostas
shared/ # Utilitários (log, erros, normalização)
legacy/ # Clients legados (s3, sigtap, cnes)
scripts/
indexar_manual.py # Indexação vetorial + BM25
mapear_criticas.py # Referência cruzada em lote
agente.py # Agente de análise
avaliar_rag.py # Avaliação de qualidade do RAG
ragData/
manuais/ # PDFs dos manuais SIH/SUS e SIA/SUS
portarias/ # Portarias (PDF, HTML, DOC, ZIP)
data/
chunks.json # Chunks extraídos (parent + child)
bm25_index.pkl # Índice BM25 para busca híbrida
secoes.json # Seções detectadas
analises/ # Pareceres do agente
db/ # Banco vetorial ChromaDB
mcp_server.py # MCP Server (43 tools, 8 módulos)
consulta_manual.py # Consulta interativa + /explicar
extrair_manual.py # Extração multi-formato
validar_critica.py # Código vs manual (sem IA)
analisar_critica.py # Agente de análise crítica (com IA)
busca_hibrida.py # Busca híbrida standalone
validar_resposta.py # Validação de respostas
docker-compose.yml # MCP Server + ChromaDB containerizados
Dockerfile # Build do MCP Server
pyproject.toml # Dependências e entry points
setup.sh # Setup automatizado
```
