OCS NER/NLP — API de Mascaramento de Dados Sensíveis Brasileiros

API de processamento de textos que detecta e mascara dados sensíveis brasileiros (CPF, RG, telefone, dados bancários, nome, endereço, etc.) combinando:

Regex — dados estruturados (CPF/CNPJ com validação de dígito, RG, telefone, CEP, cartão, conta bancária, e-mail, datas).
NER (GLiNER urchade/gliner_multi-v2.1) — dados de texto livre (nome, endereço, organização...).

Sem banco de dados: a API só processa texto. O armazenamento é responsabilidade de outro microsserviço consumidor.

Arquitetura

Arquitetura limpa (Clean Architecture) + padrões de projeto:

app/
├── core/            # config (Settings singleton)
├── domain/          # entidades + portas (interfaces)   <- regra de negócio
│   ├── entities.py  # Entity, MaskingResult
│   └── ports.py     # EntityDetector (Strategy/Port)
├── application/     # casos de uso
│   └── masking_service.py   # orquestra detectores + mascaramento
├── infrastructure/  # adaptadores concretos
│   ├── regex_detector.py    # Strategy: regex BR
│   ├── gliner_detector.py   # Strategy: NER
│   └── model_loader.py      # Singleton de modelo (cache)
└── presentation/    # FastAPI (rotas, schemas, DI)

Padrões usados:

Strategy / Port-Adapter: cada detector implementa EntityDetector; o serviço combina quantos existirem.
Dependency Injection: MaskingService injetado via app.state + Depends.
Singleton: modelo GLiNER carregado uma única vez no startup (model_loader).

Cache de modelo

O modelo é baixado uma vez para MODEL_CACHE_DIR (padrão .model_cache/) e carregado em memória no startup do servidor (lifespan em app/main.py). Requisições nunca disparam download/reload — usam a instância em cache.

Setup

python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate

pip install -r requirements.txt
cp .env.example .env   # ajuste se quiser

Rodar

python -m app.main
# ou
uvicorn app.main:app --host 0.0.0.0 --port 8000

Docs interativas: http://localhost:8000/docs

Endpoints

Ver docs/API.md.

GET /health — status.
GET /api/v1/labels — lista todas as labels detectáveis.
POST /api/v1/mask — mascara tudo que for sensível.
POST /api/v1/mask/custom — mascara só as labels escolhidas.