Update docs/MODELCARD.md

docs/MODELCARD.md

@@ -8,10 +8,10 @@
 | Campo | Valor |
 |-------|-------|
 | Nome | Para.AI Assuntos Jurídicos API |
-| Versão | 1.0.0 |
+| 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`) |
+| 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 |
 
@@ -25,6 +25,7 @@ Use este tool quando o usuário perguntar sobre:
 - 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)
 
 ---
 
@@ -110,6 +111,129 @@ Use este tool quando o usuário perguntar sobre:
 
 ---
 
+## 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
@@ -208,11 +332,91 @@ TOOL_ANTHROPIC = {
  "topk": 1, "retornar": ["titulo", "definicao", "introducao"]}
 ```
 
-### 4. Drill-down hierárquico
+### 4. Navegação hierárquica (drill-down)
+
+**Listar pastas filhas diretas:**
+```bash
+GET /grafo/filhos?ancestor=Crimes contra o Patrimônio&size=20
 ```
-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.0 · 24/02/2026 · Para.AI*
+*v1.0.1 · 28/02/2026 · Para.AI*