cpf-validador: Instructions file for Claude Code

CLAUDE.md

Guia para o Claude Code ao trabalhar neste repositório.

Comandos

# Instalar dependências (requirements-trt3.txt inclui o PyTorch da CRNN)
pip install -r requirements-trt3.txt

# Rodar localmente (FastAPI + FastMCP na porta 8000)
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Docker (porta 8002 conforme docker-compose.yaml)
docker compose up --build -d
docker compose down

Testes automatizados (mockam o TRT3, rodam no CI):

pip install -r requirements-dev.txt
ruff check app/
pytest tests/ -v

Testes manuais via:

• Interface web: http://localhost:8000/
• FastAPI docs (apenas ENV=development): http://localhost:8000/docs
• MCP transport: http://localhost:8000/mcp (streamable-http)

Arquitetura

FastAPI (app/main.py) com routers REST + FastMCP 3.0 montado em /mcp. A camada services/ não tem dependência de framework.

app/
├── main.py           # FastAPI — routers + rate limiter + mcp.http_app() em /mcp
├── config.py         # Lê todas as variáveis de ambiente com defaults
├── mcp_server.py     # FastMCP("cpf-validador") — 6 tools wrapping services
├── auth.py           # TokenMiddleware — autenticação via API_TOKEN + controle prod/dev via ENV
├── rate_limit.py     # Limiter compartilhado — main.py e routers/consulta.py precisam do mesmo objeto
├── services/
│   ├── cpf.py        # Lógica pura de CPF (zero deps de framework)
│   └── sources/      # Fontes de consulta — a fonte ativa vem de SOURCE no .env
│       ├── base.py     # ABC Fonte + contrato do retorno + mascarar_cpf (log)
│       ├── __init__.py # Registro preguiçoso + busca em lote (agnóstica de fonte)
│       ├── trt3.py     # TRT3: curl_cffi + CAPTCHA CRNN + pypdf
│       ├── tcu.py      # TCU: API JSON + Altcha (PoW PBKDF2), sem pypdf
│       └── exemplo.py  # Modelo para novas fontes — fictícia, sem rede e sem CAPTCHA
├── routers/
│   ├── cpf.py        # POST /cpf/validate, POST /cpf/variations
│   ├── consulta.py   # POST /consulta/cpf, /cpfs, /buscar-por-mascara, /buscar-por-variacoes
│   └── ui.py         # GET / — interface web com gate de autenticação
└── captcha/
    ├── model.py       # Arquitetura CRNN (CNN + BiLSTM + CTC Loss)
    ├── predictor.py   # Inferência — carrega captcha_model.pt
    ├── dataset.py     # CaptchaDataset com data augmentation
    ├── train.py       # Loop de treino com early stopping + AMP + registry
    ├── collector.py   # Coleta amostras rotuladas do TRT3 (--workers N)
    ├── registry.py    # Versionamento de modelos (models/vN/model.pt + meta.json)
    └── models/        # Histórico de versões treinadas