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