docs/MODELCARD.md

# 🤖 MODELCARD.md — Para.AI Assuntos Jurídicos API
**Referência para LLMs e Tool Calling**

---

## Identidade

| Campo | Valor |
|-------|-------|
| Nome | Para.AI Assuntos Jurídicos API |
| Versão | 1.0.1 |
| Base URL | `https://api.para-ai.com` / `http://localhost:8000` |
| Protocolo | REST / JSON |
| Latência típica | 74ms (`/busca-q`) · 800ms (`/busca`) · 120ms (`/grafo/filhos`) |
| Licença dados | CNJ — domínio público |
| Licença código | MIT |

---

## Quando Usar Este Tool

Use este tool quando o usuário perguntar sobre:
- Classificação de processos judiciais
- Nome ou código oficial de assuntos jurídicos
- Legislação aplicável a um tema do Direito
- Hierarquia de ramos/categorias do Direito brasileiro
- Definição técnica de um instituto jurídico
- Navegação pela árvore de assuntos (drill-down hierárquico)

---

## Endpoint Recomendado: POST /busca-q

### Schema da Requisição

```json
{
  "q": "string (opcional) — texto livre, multi_match em todos os campos",
  "campos": [
    {"campo": "ramo",              "valor": "DIREITO PENAL"},
    {"campo": "dispositivos_legais","valor": "Lei 8.742"},
    {"campo": "classes_nivel2",    "valor": "Responsabilidade Civil"},
    {"campo": "nome_assunto",      "valor": "aposentadoria"}
  ],
  "modo": "fuzzy",
  "topk": 5,
  "operador": "or",
  "retornar": ["titulo", "introducao", "normas", "caminho"],
  "incluir_texto_completo": false,
  "com_facets": false
}
```

### Campos disponíveis em `campos[].campo`

`nome_assunto` · `titulo_curto` · `breve_sintese` · `glossario` ·
`texto_completo` · `classes_path` · `ramo` · `classes_nivel1` ·
`classes_nivel2` · `classes_nivel3` · `dispositivos_legais` ·
`artigos` · `cod_assunto`

### Campos disponíveis em `retornar[]`

| Token | Descrição |
|-------|-----------|
| `titulo` | Nome principal do assunto |
| `titulo_curto` | Título abreviado |
| `introducao` | Síntese (1–2 parágrafos) |
| `definicao` | Glossário técnico completo |
| `normas` | Lista de leis/decretos |
| `artigos` | Artigos específicos |
| `caminho` | Hierarquia ("RAMO > Cat > Sub") |
| `ramo` | Ramo do Direito |
| `nivel1/2/3` | Categorias hierárquicas |
| `texto` | Texto completo consolidado |
| `cod_assunto` | Código numérico CNJ |

### Ramos do Direito disponíveis (filtro `ramo`)

`DIREITO PENAL` · `DIREITO CIVIL` · `DIREITO PROCESSUAL CIVIL` ·
`DIREITO PREVIDENCIÁRIO` · `DIREITO TRIBUTÁRIO` · `DIREITO ADMINISTRATIVO` ·
`DIREITO DO CONSUMIDOR` · `DIREITO DO TRABALHO` · `DIREITO CONSTITUCIONAL` ·
`DIREITO AMBIENTAL` · `DIREITO EMPRESARIAL` · `DIREITO DE FAMÍLIA` ·
`DIREITO ASSISTENCIAL` · `DIREITO ELEITORAL` · `DIREITO IMOBILIÁRIO` …

---

## Schema da Resposta

```json
{
  "total": 18,
  "retornados": 5,
  "took_ms": 74,
  "modo": "fuzzy",
  "operador": "or",
  "resultados": [
    {
      "score": 24.5,
      "campos_matched": ["ramo", "dispositivos_legais"],
      "ficha": {
        "id": "d2fb81f5...",
        "titulo": "Benefício de Prestação Continuada (BPC)",
        "introducao": "Benefício assistencial garantido a idosos e pessoas com deficiência...",
        "normas": ["Lei 8.742/1993 (LOAS)", "Art. 20", "Decreto 6.214/2007"],
        "caminho": "DIREITO ASSISTENCIAL > Assistência Social > BPC"
      }
    }
  ]
}
```

---

## Endpoint de Navegação: GET /grafo/filhos

**Retorna assuntos do mesmo nível e pastas filhas diretas de um nó da hierarquia.**

### Parâmetros

| Parâmetro | Tipo | Obrigatório | Descrição |
|-----------|------|-------------|-----------|
| `ancestor` | string | ✓ | Nome do nó ancestral (ex: "Crimes contra o Patrimônio") |
| `size` | integer | ✗ | Máximo de resultados (padrão: 50, max: 500) |
| `estruturado` | boolean | ✗ | Retornar resposta separada por tipo (padrão: false) |

### Comportamento

O endpoint retorna **APENAS**:
1. Assuntos do **mesmo nível hierárquico** do ancestor
2. **Pastas/categorias filhas diretas** (profundidade + 1)

**NÃO retorna** os assuntos dentro das pastas dos filhos (netos, bisnetos, etc.).

### Exemplo de Requisição

```bash
GET /grafo/filhos?ancestor=DIREITO DO CONSUMIDOR&size=50
```

### Schema da Resposta (modo padrão)

```json
{
  "ancestor": "DIREITO DO CONSUMIDOR",
  "total": 13,
  "filhos": [
    {
      "id": "fb36b9c7...",
      "nome_assunto": "DIREITO DO CONSUMIDOR",
      "classes_profundidade": 1,
      "classes_path": "DIREITO DO CONSUMIDOR",
      "titulo_curto": "Direito do Consumidor",
      "breve_sintese": "Assunto que abrange questões relativas à proteção...",
      "dispositivos_legais": ["Lei nº 8.078/1990"]
    },
    {
      "id": "0039f247...",
      "nome_assunto": "Responsabilidade do Fornecedor",
      "classes_profundidade": 2,
      "classes_path": "DIREITO DO CONSUMIDOR > Responsabilidade do Fornecedor",
      "titulo_curto": "Responsabilidade do Fornecedor",
      "breve_sintese": "Trata da responsabilidade civil do fornecedor..."
    },
    {
      "id": "0bcbb6ab...",
      "nome_assunto": "Dever de Informação",
      "classes_profundidade": 2,
      "classes_path": "DIREITO DO CONSUMIDOR > Dever de Informação"
    }
    // ... mais 10 pastas de profundidade 2
  ]
}
```

### Schema da Resposta (modo estruturado)

```bash
GET /grafo/filhos?ancestor=DIREITO DO CONSUMIDOR&estruturado=true
```

```json
{
  "ancestor": "DIREITO DO CONSUMIDOR",
  "ancestor_profundidade": 1,
  "total": 13,
  "assuntos_mesmo_nivel": {
    "total": 1,
    "assuntos": [
      {
        "id": "fb36b9c7...",
        "nome_assunto": "DIREITO DO CONSUMIDOR",
        "classes_profundidade": 1,
        "classes_path": "DIREITO DO CONSUMIDOR"
      }
    ]
  },
  "pastas_com_filhos": {
    "total": 12,
    "pastas": [
      {
        "id": "0039f247...",
        "nome_assunto": "Responsabilidade do Fornecedor",
        "classes_profundidade": 2,
        "classes_path": "DIREITO DO CONSUMIDOR > Responsabilidade do Fornecedor"
      },
      {
        "id": "0bcbb6ab...",
        "nome_assunto": "Dever de Informação",
        "classes_profundidade": 2,
        "classes_path": "DIREITO DO CONSUMIDOR > Dever de Informação"
      }
      // ... mais 10 pastas
    ]
  }
}
```

### Caso de Uso

Ideal para construir interfaces de navegação em árvore, onde o usuário clica em uma pasta e vê apenas as subpastas diretas, não todos os conteúdos recursivamente.

```javascript
// Frontend - Navegação em árvore
async function loadChildren(nodeName) {
  const response = await fetch(
    `/grafo/filhos?ancestor=${nodeName}&estruturado=true`
  );
  const data = await response.json();
  
  // Mostrar apenas as pastas clicáveis
  return data.pastas_com_filhos.pastas;
}
```

---

## Exemplo — OpenAI Function Calling

```python
import requests

# Definição da tool
TOOL = {
    "type": "function",
    "function": {
        "name": "buscar_assunto_juridico",
        "description": (
            "Busca assuntos jurídicos na base oficial do CNJ (5.184 assuntos). "
            "Use para classificar processos, identificar legislação aplicável "
            "ou obter a definição técnica de um instituto jurídico."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "q": {
                    "type": "string",
                    "description": "Termo jurídico ou descrição do caso"
                },
                "ramo": {
                    "type": "string",
                    "description": "Ramo do Direito (ex: DIREITO PENAL)"
                },
                "topk": {
                    "type": "integer",
                    "default": 3,
                    "description": "Número de resultados"
                },
                "retornar": {
                    "type": "array",
                    "items": {"type": "string"},
                    "default": ["titulo", "introducao", "normas"],
                    "description": "Campos a retornar"
                }
            },
            "required": ["q"]
        }
    }
}

def buscar_assunto_juridico(q, ramo=None, topk=3, retornar=None):
    campos = [{"campo": "ramo", "valor": ramo}] if ramo else []
    r = requests.post("https://api.para-ai.com/busca-q", json={
        "q": q,
        "campos": campos,
        "topk": topk,
        "retornar": retornar or ["titulo", "introducao", "normas"],
    })
    return r.json()
```

---

## Exemplo — Anthropic Tool Use

```python
TOOL_ANTHROPIC = {
    "name": "buscar_assunto_juridico",
    "description": "Busca assuntos jurídicos na base CNJ.",
    "input_schema": {
        "type": "object",
        "properties": {
            "q":       {"type": "string"},
            "ramo":    {"type": "string"},
            "topk":    {"type": "integer"},
            "retornar":{"type": "array", "items": {"type": "string"}}
        },
        "required": ["q"]
    }
}
```

---

## Casos de Uso Documentados

### 1. Classificar processo por texto da petição
```json
{"q": "ação de usucapião extraordinária imóvel rural posse 15 anos",
 "topk": 3, "retornar": ["titulo", "caminho", "cod_assunto"]}
```

### 2. Buscar legislação de um tema
```json
{"campos": [{"campo": "ramo", "valor": "DIREITO ASSISTENCIAL"}],
 "q": "benefício pessoa deficiência",
 "retornar": ["titulo", "normas", "artigos"]}
```

### 3. Definição técnica para RAG
```json
{"q": "dano moral extrapatrimonial",
 "topk": 1, "retornar": ["titulo", "definicao", "introducao"]}
```

### 4. Navegação hierárquica (drill-down)

**Listar pastas filhas diretas:**
```bash
GET /grafo/filhos?ancestor=Crimes contra o Patrimônio&size=20
```

**Resposta:**
- Assuntos do mesmo nível (irmãos)
- Pastas/categorias filhas diretas
- **NÃO** inclui assuntos dentro das pastas

**Navegação estruturada (para UIs):**
```bash
GET /grafo/filhos?ancestor=DIREITO PENAL&estruturado=true
```

**Casos de uso:**
- Construir árvores de navegação
- Breadcrumbs dinâmicos
- Interfaces de seleção hierárquica
- Sugestões de assuntos relacionados

### 5. Obter hierarquia completa
```bash
GET /hierarquia
```

Retorna a árvore completa de ramos → categorias → subcategorias em formato agregado.

---

## Comparação entre Endpoints de Navegação

| Endpoint | Retorna | Caso de Uso |
|----------|---------|-------------|
| `/hierarquia` | Árvore completa agregada | Visão geral, estatísticas |
| `/grafo/filhos` | Apenas nível atual + filhos diretos | Navegação incremental, UI |
| `/busca` | Busca full-text | Busca livre por palavras |
| `/busca-q` | Busca estruturada | Tool calling, RAG |

---

## Notas de Implementação

### Performance

- **Cache recomendado:** `/hierarquia` (raramente muda)
- **Taxa de limite:** 100 req/min por IP (ajustável)
- **Timeout:** 10s (aumentar para `/busca` com `texto_completo`)

### Paginação

```json
{
  "page": 2,
  "size": 20
}
```

Apenas em `/busca` (GET/POST). Outros endpoints usam `size` ou `topk`.

### Fuzzy Match

```json
{"modo": "fuzzy"}  // Tolera erros de digitação (fuzziness AUTO)
{"modo": "exact"}  // Match exato em campos keyword
```

---

## Changelog

### v1.0.1 (28/02/2026)
- ✨ Correção do endpoint `/grafo/filhos`: agora retorna apenas mesmo nível + filhos diretos
- ✨ Novo parâmetro `estruturado=true` para resposta separada por tipo
- 📝 Documentação expandida sobre navegação hierárquica
- 🐛 Fix: `/grafo/filhos` não retorna mais descendentes recursivos (netos, bisnetos)

### v1.0.0 (24/02/2026)
- 🚀 Release inicial
- Suporte a busca full-text e estruturada
- 5.184 assuntos jurídicos CNJ
- Endpoints REST completos

---

*v1.0.1 · 28/02/2026 · Para.AI*