# 🤖 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*