pjecalc-processamento

Files (3)

• SKILL.md
• regras-validacao.md · references/
• schema-contrato.md · references/

SKILL.md (first lines)

# pjecalc-processamento — Extração, Validação e HITL

> **Autoridade arquitetural:** `pjecalc-transformacao`. Esta skill documenta a implementação
> real das Fases 1–3 do pipeline. Em caso de conflito com `pjecalc-transformacao`, ela prevalece.

## Por que esta skill existe

O pipeline do pjecalc-agente começa com um documento (PDF/DOCX/texto ou relatório
estruturado) e deve terminar com um JSON válido, revisado e confirmado pelo usuário —
pronto para instruir a automação Playwright.

Esta skill consolida em um único lugar:
- As regras reais de extração (o que o LLM deve capturar e como)
- O schema JSON completo com todos os campos atualizados
- As regras de validação implementadas em `ValidadorSentenca`
- Os triggers de HITL que pausam para revisão humana
- Os pontos críticos onde a extração costuma falhar

O código-fonte de referência está em:
- `modules/extraction.py` — ingestão, extração, validação
- `modules/classification.py` — mapeamento de verbas
- `webapp.py` — orquestração do fluxo, HITL, confirmação

---

## Regra inviolável — IA obrigatória

> **A prévia do cálculo NÃO pode ser gerada sem extração via IA.**
>
> Quando a IA falha (sem créditos, timeout, erro 400/500), o processamento é BLOQUEADO
> com `status="erro_ia"`. Nunca contornar esse bloqueio. A confiabilidade da liquidação
> trabalhista depende da extração por IA.

---

## Fluxo completo — Fases 1 a 3

```
Entrada do usuário (PDF / DOCX / TXT / relatório estruturado)
    │
    ▼ FASE 1 — Ingestão (modules/ingestion.py)
    │
    │  PDF nativo    → pdfplumber (extrai texto com layout preservado)
    │  PDF escaneado → pytesseract OCR como fallback automático
    │  DOCX/TXT      → extração direta de texto
    │  Relatório     → flag is_relatorio=True (CalcMACHINE ou similar)
    │
    │  Normalização: encoding UTF-8, datas BR → ISO, valores monetários
    │
    ▼ FASE 2 — Extração com IA (modules/extraction.py)
    │
    │  Roteamento de modelo:
    │    PDF nativo    → Claude Sonnet 4.6 via base64 (visão multimodal)
    │    Texto/DOCX    → Claude ou Gemini conforme USE_GEMINI env
    │    Relatório     → Claude/Gemini conforme seleção do usuário + streaming
    │
    │  Gemini: timeout 30s (texto) / 60s (relatório) → fallback Claude se falhar
    │  Claude: timeout 90s (texto/PDF) / 120s+streaming (relatório)
    │
    │  Output: JSON com todos os campos do schema (ver references/schema-contrato.md)
    │  Falha de IA: _erro_ia=True → BLOQUEAR (regra inviolável acima)
    │
    ▼ FASE 3 — Validação + HITL
    │
    │  1. ValidadorSentenca(dados).validar()
    │     → ResultadoValidacao(valido: bool, erros: list, avisos: list)
    │
    │  2. Erros bloqueantes impedem confirmação
    │     Avisos mostram alertas mas não bloqueiam
    │
    │  3. Interface prévia: todos os campos editáveis
    │     PATCH /previa/{sessao_id}/campo → salvarCampo() inline
    │
    │  4. Usuário revisa, corrige, confirma
    │     POST /previa/{sessao_id}/confirmar
    │     → calculo.confirmado_em = now()
    │
    ▼ JSON válido e confirmado → pjecalc-automacao (Fases 4-6)
```

---

## Roteamento de modelos IA

| Tipo de entrada | Modelo primário | Fallback | Timeout | Streaming |
|---|---|---|---|---|
| PDF nativo | Claude Sonnet 4.6 (base64) | Gemini (converte para texto) | 90s | Não |
| Texto / DOCX | Claude ou Gemini (USE_GEMINI) | Claude | 90s | Não |
| Relatório estruturado | Claude ou Gemini (usa `usar_gemini`) | Claude | 120s | Sim |

**Por que streaming no relatório?**
Relatórios têm prompt muito longo (guia de mapeamento + texto do relatório = 30k+ tokens).
Sem streaming, a API Anthropic derruba a conexão antes da resposta completa. `messages.stream()`
mantém a conexão viva durante toda a geração.

**Controle pelo usuário:** seletor "Modelo de IA" no formulário define `usar_gemini=True/False`.
Se não selecionado, usa `USE_GEMINI` do `.env`.

---

## Schema JSON — Campos principais

> Schema completo em `references/schema-contrato.md`.

### processo
```json
{
  "numero": "0000153-87.2026.5.07.0002",  // CNJ completo — copiar EXATO do documento
  "numero_seq": "0000153",                 // 7 dígitos (desmembrado por _desmembrar_cnj)
  "digito_verificador": "87",              // 2 dígitos
  "ano": "2026",
  "segmento": "5",                         // 5 = Justiça do Trabalho
  "regiao": "07",                          // tribunal (07 = TRT7)
  "vara": "0002",                          // 4 dígitos
  "reclamante": "João da Silva",
  "reclamado": "Empresa ABC Ltda",
  "estado": "CE",                          // sigla UF (2 letras)
  "municipio": "FORTALEZA",               // APENAS nome da cidade, sem UF/sufixo
  "vara_nome": "3ª Vara do Trabalho de Fortaleza"
}

From bragabarreto/pjecalc-agente, MIT.

More from bragabarreto/pjecalc-agente