Spaces:

caarleexx
/

para.AI_ASSUNTOS_CNJ

Paused

App Files Files Community

para.AI_ASSUNTOS_CNJ / docs /MODELCARD.md

caarleexx

Update docs/MODELCARD.md

d9eb15e verified 3 months ago

preview code

raw

history blame contribute delete

11.7 kB

🤖 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

{
  "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

{
  "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:

Assuntos do mesmo nível hierárquico do ancestor
Pastas/categorias filhas diretas (profundidade + 1)

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

Exemplo de Requisição

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

Schema da Resposta (modo padrão)

{
  "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)

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

{
  "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.

// 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

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

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

{"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

{"campos": [{"campo": "ramo", "valor": "DIREITO ASSISTENCIAL"}],
 "q": "benefício pessoa deficiência",
 "retornar": ["titulo", "normas", "artigos"]}

3. Definição técnica para RAG

{"q": "dano moral extrapatrimonial",
 "topk": 1, "retornar": ["titulo", "definicao", "introducao"]}

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

Listar pastas filhas diretas:

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):

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

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

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

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

Fuzzy Match

{"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