# ℹ️ 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)