| # ℹ️ INFO.md — Para.AI Assuntos Jurídicos API |
| **Para potenciais clientes e usuários** |
|
|
| --- |
|
|
| ## O que é? |
|
|
| API REST pública que provê acesso estruturado aos **5.184 assuntos jurídicos** |
| catalogados oficialmente pelo **Conselho Nacional de Justiça (CNJ)**. |
|
|
| Projetada para advogados, legaltechs, sistemas de gestão processual e |
| desenvolvedores que integram LLMs com contexto jurídico confiável. |
|
|
| --- |
|
|
| ## Propósito e Objetivo |
|
|
| ### Problema |
|
|
| Profissionais do Direito perdem horas navegando manualmente a taxonomia do CNJ |
| para classificar processos. Chatbots jurídicos carecem de fonte estruturada e |
| confiável. Sistemas de triagem automática erram por falta de contexto oficial. |
|
|
| ### Solução |
|
|
| A Para.AI API entrega em milissegundos: |
|
|
| - **Busca fuzzy** tolerante a erros (`"aposen"` → `"Aposentadoria"`) |
| - **Filtros por ramo**, legislação e hierarquia |
| - **Autocomplete** em tempo real |
| - **Ficha unificada** para tool calling de LLMs (GPT-4, Claude, Gemini) |
| - **Árvore hierárquica** completa (22 ramos, até 5 níveis) |
|
|
| --- |
|
|
| ## Arquitetura |
|
|
| ``` |
| Cliente / LLM |
| │ HTTP/JSON |
| ▼ |
| FastAPI 0.115 ←── Pydantic 2 (validação + serialização ORJSON) |
| │ |
| ▼ |
| Elasticsearch 8.12 |
| • Índice: assuntos_juridicos (5.184 docs, ~18 MB) |
| • Analyzer: juridico_pt (lowercase + ASCII fold + stemmer PT + stopwords) |
| • Edge n-gram tokenizer para autocomplete |
| • BM25 com pesos: nome_assunto^4, titulo_curto^3, breve_sintese^2 … |
| │ |
| ▼ |
| Base CNJ (dados públicos, bulk_assuntos.ndjson) |
| ``` |
|
|
| --- |
|
|
| ## Endpoints Disponíveis |
|
|
| | Endpoint | Método | Latência p50 | Descrição | |
| |----------|--------|-------------|-----------| |
| | `/busca` | GET/POST | ~800ms | Full-text + filtros + facets | |
| | `/busca-q` | GET/POST | ~74ms | Estruturada para LLMs | |
| | `/autocomplete` | GET | ~45ms | Sugestões por prefixo | |
| | `/hierarquia` | GET | ~250ms | Árvore 22 ramos | |
| | `/assuntos/{id}` | GET | ~20ms | Documento completo | |
| | `/grafo/filhos` | GET | ~100ms | Drill-down por ancestral | |
| | `/health` | GET | ~10ms | Status e métricas | |
|
|
| Documentação interativa: `http://localhost:8000/docs` |
|
|
| --- |
|
|
| ## Desafios e Soluções |
|
|
| | Desafio | Solução | |
| |---------|---------| |
| | Soft hyphens `\xad` nos textos CNJ | Strip no pipeline de indexação | |
| | Termos jurídicos longos com acentos | ASCII folding + stemmer português | |
| | LLMs precisam de payload compacto | `/busca-q` com `retornar=[]` seletivo | |
| | Hierarquia de 5 níveis aninhados | Agregações ES nested + `classes_path` | |
| | Autocompletar prefixos rápido | Edge n-gram (min 2, max 20 chars) | |
|
|
| --- |
|
|
| ## Próximos Passos |
|
|
| **Q2 2026 — Otimização** |
| - Cache Redis (p95 < 200ms) |
| - Rate limiting e API keys |
| - Métricas Prometheus + Grafana |
|
|
| **Q3 2026 — Inteligência** |
| - Busca semântica (embeddings) |
| - Dicionário de sinônimos jurídicos |
| - `/classificar` — inferência de assunto por texto livre |
|
|
| **Q4 2026 — Escala** |
| - Cluster ES 3 nós |
| - Integração com jurisprudência (acórdãos TJPR) |
| - Webhooks de atualização CNJ |
|
|
| --- |
|
|
| ## Open Source |
|
|
| Código: https://github.com/para-ai/assuntos-juridicos |
| Licença: MIT |
| Dados: CNJ (domínio público) |
|
|
