Verificação de citações

Três rotas, todas POST, todas com chave:

Status

Cada resolução tem um status. Os valores são estáveis: trate-os como enum.

Só verificado confirma a citação. verificado_inferido e ambiguo indicam que o diploma não estava explícito no texto e exigem conferência. nao_suportado e diploma_desconhecido indicam que a citação está fora do corpus, não que ela está errada.

Resumo do topo

POST /v1/resolver-texto (e a ferramenta MCP verificar_texto) devolvem um resumo no topo da resposta:

{
  "resumo": {
    "total": 7,
    "por_status": { "verificado": 3, "ambiguo": 1, "diploma_desconhecido": 2, "nao_suportado": 1 },
    "todas_confirmadas": false
  },
  "citacoes": []
}

todas_confirmadas só é true quando todas as citações têm status verificado (e a lista não está vazia).

Exemplos reais

Inciso inexistente (verificado_parcial):

{
  "status": "verificado_parcial",
  "ref_key": "CF.5",
  "texto": "Todos são iguais perante a lei, sem distinção de qualquer natureza, …",
  "hierarquia": "Título II – Dos Direitos e Garantias Fundamentais > Capítulo I – Dos Direitos e Deveres Individuais e Coletivos",
  "revogado": false,
  "anotacoes": [],
  "alterado_por": null,
  "revogado_por": null,
  "parcial": { "nivel": "inciso", "valor": "XCIX", "encontrado": "CF.5" }
}

Artigo revogado citado como vigente (revogado). Quando o Planalto publica só a nota de revogação, texto vem vazio e a informação útil está em revogado_por:

{
  "status": "revogado",
  "ref_key": "CPP.594",
  "texto": "",
  "hierarquia": "Livro III – Das Nulidades e dos Recursos em Geral > Título II – Dos Recursos em Geral > Capítulo III – Da Apelação",
  "revogado": true,
  "anotacoes": ["Revogado pela Lei nº 11.719, de 2008"],
  "alterado_por": null,
  "revogado_por": "Lei nº 11.719, de 2008"
}

Quando o Planalto mantém a redação antiga tachada, texto é essa redação, revogada, não vigente; revogado: true é o que manda:

{
  "status": "revogado",
  "ref_key": "LIMPROBIDADE.5",
  "texto": "Ocorrendo lesão ao patrimônio público por ação ou omissão, dolosa ou culposa, do agente ou de terceiro, dar-se-á o integral ressarcimento do dano.",
  "hierarquia": "Capítulo I – Das Disposições Gerais",
  "revogado": true,
  "anotacoes": ["Revogado pela Lei nº 14.230, de 2021"],
  "alterado_por": null,
  "revogado_por": "Lei nº 14.230, de 2021"
}

Artigo que não existe (nao_encontrado). Entrada { "sigla": "CC", "artigo": "9999", "rotulo": "obriga a reparar o dano causado por ato ilícito" }:

{
  "status": "nao_encontrado",
  "mensagem": "CC: art. 9999 não existe no corpus.",
  "sugestao": [
    { "ref_key": "CC.927", "artigo": "927", "trecho": "Aquele que, por <b>ato</b> <b>ilícito</b> (arts. 186 e 187), <b>causar</b> <b>dano</b> a outrem, fica <b>obrigado</b> a repará-lo.\nParágrafo único ... Haverá <b>obrigação</b> de <b>reparar</b> o <b>dano</b>, independentemente de culpa, nos casos especificados em lei, ou quando a atividade normalmente desenvolvida" }
  ]
}

Sugestões

sugestao está sempre presente em nao_encontrado e traz até 3 dispositivos do diploma citado, em ordem de relevância, nunca revogados. A lista vem vazia ([]) sempre que o contexto não determina um dispositivo, e isso é a resposta certa, não uma falha: um cliente vai exibir "você quis dizer o art. 927?" e o usuário vai acreditar, então uma sugestão plausível mas errada é pior que nenhuma.

Quando não há diploma explícito nem inferência segura, o status é ambiguo e o campo é candidatos, não sugestao: a lista traz até max_candidatos (padrão 10, parâmetro de 0 a 25; 0 devolve só total_candidatos) diplomas do corpus que têm aquele artigo, ordenados por cobertura lexical do contexto, pista de área (pista_area) e prior do diploma (constituição > código > lei > decreto > emenda). candidatos_truncados diz se a lista foi cortada. Quem escolhe entre os candidatos é o cliente; o Lei Vigente não decide sozinho.

Quando a citação resolve para um dispositivo alterador (uma emenda ou lei que muda outro diploma), a resolução traz alterador: true e altera: [ref_keys]; o status não muda — citar art. 1º da EC 45/2004 continua verificado.

O critério é de cobertura, não de semelhança: o dispositivo precisa conter (quase) todos os termos do contexto, e os termos raros no diploma pesam mais que os comuns. Na prática:

trecho vem com <b>…</b> marcando os termos encontrados; escape antes de exibir como texto puro.

POST /v1/resolver

Duas formas de citação, distinguidas pelos campos presentes (ou três, contando tema/OJ/enunciado):

{
  "citacoes": [
    { "sigla": "CF", "artigo": "5", "inciso": "LXXVIII" },
    { "sigla": "CPC", "artigo": "1.003", "paragrafo": "5º" },
    { "sigla": "CLT", "artigo": "482", "alinea": "a" },
    { "sigla": "CC", "artigo": "12", "paragrafo": "unico" },
    { "sigla": "CC", "artigo": "9999", "rotulo": "obriga a reparar o dano causado por ato ilícito" },
    { "tribunal": "STJ", "numero": 7 },
    { "tribunal": "STF", "numero": 11, "vinculante": true }
  ]
}

Dispositivo: sigla (obrigatória; maiúsculas/minúsculas e apelidos aceitos), artigo (obrigatório; "1.003", "1003", "5º", "5-A" são equivalentes), paragrafo ("5º", "5", "único"/"unico"), inciso (romano), alinea (letra), item (número) e rotulo, a frase que descreve o que a citação afirma (não a citação em si), usada só para gerar sugestao quando o dispositivo não existe. Tokens de citação no rotulo (art., §, números, romanos, siglas) são ignorados na busca; mande o conteúdo ("prazo para interposição de recurso"), não a referência ("art. 1.003 do CPC").

Súmula: tribunal (qualquer tribunal; "STF" e "STJ" são verificados, os demais voltam como nao_suportado), numero e vinculante. Omitido, tenta a súmula comum e, no STF, a vinculante. No STF, Súmula 11 e Súmula Vinculante 11 são enunciados diferentes; seja explícito quando souber.

Tema / OJ / enunciado: aceitos na entrada estruturada e respondidos como nao_suportado (fora do corpus): { "tipo": "tema", "tribunal": "STJ", "numero": 1085 }, { "tipo": "oj", "orgao": "SDI-1", "numero": 394 }, { "tipo": "enunciado", "orgao": "FONAJE", "numero": 54 }.

A resposta é { "resultados": [...] } na mesma ordem da entrada.

POST /v1/parse

Extrai citações de texto com regex e uma tabela de apelidos: sem IA, determinístico, rápido. Reconhece, entre outros:

• art. 5º, LXXVIII, da CF · CF, art. 5º, LXXVIII · artigo 5º, inciso LXXVIII, da Constituição
• § 5º do art. 1.003 do CPC · CPC, art. 1.003, §5º · art. 1.003, § 5º, do Código de Processo Civil
• arts. 186 e 927 do CC (vira duas citações)
• art. 482, alínea a, da CLT
• Lei 8.078/90, art. 6º, VIII · Lei nº 13.709/2018, art. 7º (número da lei → sigla)
• Súmula 7 do STJ · Súmula Vinculante 11 · Súmula 11 do STF

Cada citação vem com offset/fim (posições no texto original), rotulo (o trecho como estava escrito) e, para dispositivos, diploma_inferido: true quando a lei veio do contexto ("O CPC prevê, no art. 1.003, …"). Sem diploma identificável, sigla é null; no /resolver-texto isso vira diploma_desconhecido.

{
  "citacoes": [
    { "tipo": "dispositivo", "sigla": "CF", "artigo": "5", "paragrafo": null, "inciso": "LXXVIII", "alinea": null, "item": null, "rotulo": "art. 5º, LXXVIII, da CF", "offset": 11, "fim": 34, "diploma_inferido": false },
    { "tipo": "sumula", "tribunal": "STJ", "numero": 7, "vinculante": false, "rotulo": "Súmula 7 do STJ", "offset": 78, "fim": 93 }
  ]
}

POST /v1/resolver-texto

/parse seguido de /resolver, em uma chamada. Resposta: { "citacoes": [ { "citacao": <CitacaoExtraida>, "resolucao": <Resolucao> } ] }. Só as 100 primeiras citações são verificadas.

Para as sugestões de nao_encontrado, o rotulo da busca não é a citação (citacao.rotulo continua sendo o trecho como escrito): é a frase ao redor dela, sem a própria citação, sem outras citações e sem nomes de leis. "O art. 9.999 do CC obriga a reparar o dano causado por ato ilícito." sugere o art. 927; "Ver também art. 9.999 do CC." devolve "sugestao": [].

Integrando com um assistente jurídico

Padrão recomendado, verificação pós-geração:

1. O LLM gera a resposta.
2. Envie o texto a /v1/resolver-texto.
3. Para cada item:
   • verificado → mantenha; opcionalmente anexe texto como fonte.
   • verificado_inferido → o diploma não estava explícito no texto; confira inferencia antes de manter. Trate como não confirmado.
   • ambiguo → escolha entre candidatos (ou remova a citação, se vier []); não confirme sozinho.
   • verificado_parcial → o artigo existe, o inciso não: peça ao modelo para corrigir usando o texto do artigo devolvido, ou remova o inciso.
   • revogado / cancelada → alerte ou reescreva. revogado_por diz qual lei revogou; se texto vier preenchido, é a redação revogada (útil para explicar o erro), nunca texto vigente.
   • nao_encontrado → se sugestao tiver itens, proponha o primeiro; se vier [], remova a citação; não há o que propor.
   • diploma_desconhecido → o corpus não cobre a lei (veja diploma_citado); sinalize como "não verificado"; não infira outro diploma.
   • nao_suportado → tema, OJ, enunciado ou súmula de outro tribunal; está fora do corpus, sinalize como "não verificado".
4. Use offset/fim para grifar cada citação na interface.

Para grounding antes da geração, busque o texto oficial com GET /v1/busca e GET /v1/diplomas/{sigla}/artigos/{artigo} e injete-o no prompt.