zhichao1208/reduce-hallucination

O que reduce-hallucination faz?

Transforme as técnicas verificadas que a ciência de interrogatório usa para obter que uma testemunha experiente diga a verdade em uma auditoria padrão para agentes LLM. Cada nó LLM é uma testemunha. A transferência entre nós é a transcrição do testemunho. Correções do usuário e registros de tarefas são evidências físicas.

A teoria e as evidências estão em references/. Leia references/research-map.md para as citações por trás de cada afirmação.

Três regras de ouro

1. Nenhuma acusação sem evidência (regra de Wellman). Toda descoberta deve citar o prompt, esquema ou saída real a que se refere. Uma suspeita sem citação vai para uma lista "a verificar", não para as descobertas.
2. Sinais superficiais não provam a verdade. Texto fluente, confiante e detalhado não é mais correto do que texto conciso. As pessoas leem engano a partir do comportamento aproximadamente por acaso. Julgue apenas o conteúdo: fundamentação, consistência, se o trecho citado existe.
3. A autocorreção precisa de um novo sinal externo. "Tem certeza? Verifique novamente" sem novas evidências degrada a precisão. Cada nova verificação deve injetar resultados recuperados ou saída de validador.

Os três pilares de uma boa citação

A qualidade da citação se decompõe em três verificações, em ordem crescente de dificuldade e valor:

Pilar	Pergunta	Status atual
Fiel	A citação é literalmente real e a afirmação não é fabricada?	Amplamente solucionável: correspondência de string literal + abstenção.
Relevante	A fonte está no tópico da pergunta?	Amplamente solucionável: qualidade da recuperação + sondagem de consistência.
Solidário	A fonte apoia a afirmação, vs contradiz ela, vs permanece neutra?	A fronteira. Difícil, e a rara classe "contradiz" é onde os sistemas são mais fracos.

Uma citação que resolve para uma passagem real e no tópico, mas que na verdade não apoia a afirmação ("desfundamentação") é pior do que nenhuma citação, porque fabrica confiança sobre uma afirmação errada e desarma a única defesa funcional do revisor (verificar o conteúdo). Mostrar uma citação sem verificá-la no backend torna a alucinação mais perigosa, não menos.

Protocolo de auditoria

Fase 1 — Interrogar cada testemunha (sinais de alerta de prompt + esquema)

Para cada nó LLM, execute a lista de sinais de alerta. Cada sinal é uma violação de interrogatório.

#	Sinal de alerta (o que procurar)	Por que é importante	Dano
R1	Um campo enum sem opção null / unknown; uma instrução unidirecional "produza uma confirmação de X".	Forçar uma resposta produz conformidade (análogo a falsa confissão).	Adivinhação forçada, fabricação confiante.
R2	A prosa concede uma abstenção ("use null se ausente") mas o esquema não tem null.	O esquema vence, a abstenção é nula.	Fabricação silenciosa.
R3	O prompt pede evidência/citação, mas nada downstream verifica.	Dizer sem verificar ensina o modelo a fabricar citações mais convincentes.	Âncoras falsas.
R4	Instruções direcionais: "seja conservador", "presuma", "infira de", "padrão para".	Presunção unidirecional; combinado com R1 produz viés sistemático.	Saída distorcida em uma direção.
R5	Um campo agregado sem unidade definida ("total de anos", "pontuação geral").	Uma medida precisa de sua unidade declarada antes de ser fixada.	Incompatibilidade de definição lida como erro de extração.
R6	Exemplos de few-shot que estão fora da tarefa ou que modelam raciocínio sem citação.	Exemplos definem a expectativa para uma resposta "boa".	Ensina o estilo de saída errado.
R7	O prompt afirma que o nó pode fazer algo para o qual não tem ferramenta.	Premissa falsa.	Narração de processo fabricada.
R8	Um "fato" apresentado pelo usuário ou nó upstream, usado como verdade sem marca de fonte.	Só confrontar com evidências verificadas.	Poluição de premissa.
R9	Um template com um slot obrigatório e nenhum ramo vazio.	A versão de template de forçar uma resposta.	Um espaço em branco é preenchido com o valor mais próximo.
R10	Nova verificação / retentativa escrita agressivamente ("você estava errado, corrija") sem novas evidências.	Bajulação inverte respostas corretas.	Respostas corretas derrubadas.

Registre cada uma como: node | R# | texto citado | consequência de uma linha.

Fase 2 — Auditar a transcrição (fronteiras de nó / fluxo de dados)

É aqui que a maioria das alucinações de pipeline acontece. Desenhe o fluxo de dados e verifique cada aresta:

1. A incerteza atravessa a fronteira? confiança / missing_fields / null / notas upstream — algo downstream consome eles, ou um template os achata em uma afirmação? Procure por incerteza "carta morta": produzida mas nunca lida.
2. A proveniência é perdida? Um valor que o raciocínio upstream admite ser "assumido/inferido" torna-se um fato não marcado downstream. O esquema deve carregar stated | inferred | absent.
3. Categorias de fato se cruzam? Dados de configuração ou requisito renderizados como se o usuário/documento os tivesse afirmado.
4. Um agregado muda de unidade? "total de anos médicos" upstream torna-se "anos como título X" downstream.
5. O LLM está fazendo computação determinística? Cálculos de data, somas, contagens em um prompt devem ser movidos para uma etapa de código.

Fase 3 — Corresponder com evidências físicas (quando registros de tarefas existem)

1. Extraia saídas de nó intermediárias para uma amostra de tarefas (prefira aquelas com correções ou falhas de usuário).
2. Compare a saída final vs a saída intermediária de cada nó vs a entrada bruta, campo por campo; localize qual fronteira perdeu a verdade primeiro.
3. Encontre declarações inconsistentes anteriores: o mesmo campo se contradizendo entre nós.
4. Se as correções são direcionais (sistematicamente em uma direção), verifique novamente as instruções direcionais R4 da Fase 1; erro aleatório aponta mais para a qualidade da entrada.
5. Classifique honestamente: "informação que nunca esteve na fonte" (uma lacuna de processo, não uma alucinação) vs "informação que estava na entrada mas foi dita errada" (uma alucinação real).

Fase 4 — Correções classificadas (por ROI)

Camada 1 — prompt / esquema (nenhuma mudança estrutural)

• Cada R1/R2 → adicione um enum null/unknown + uma linha desestigmatizante ("X é uma resposta correta e esperada").
• Cada R9 → adicione um ramo vazio ao template (afirmação torna-se uma pergunta aberta).
• Cada R5 → divida a unidade, ou produza um intervalo {piso, teto}.
• Cada R3 → adicione uma tríplice {valor, fonte, evidence_quote} a campos de suporte de carga.

Camada 2 — um validador de código determinístico (custo LLM zero)

Validador	Verificações
Whitelist de enum	O valor do campo está no conjunto permitido.
Correspondência de string de citação	evidence_quote existe literalmente na fonte citada; se não, rejeite ou rebaixe.
Consistência entre campos	Totais reconciliam; missing_fields não contradiz valores preenchidos.
Computação de unidade	Diferenças de data / somas feitas em código; o LLM só faz extração semântica.
Contrato de saída	Todo slot de fato visível ao usuário não está vazio e vem de um campo de fonte permitido.

Coloque-o antes de qualquer nó que produza conteúdo visível ao usuário. Em caso de falha, escreva uma bandeira de fallback e encaminhe para uma pergunta aberta ou um humano.

Camada 3 — um nó de contra-examinador LLM (LM-vs-LM)

• Um nó separado que recebe apenas a saída sob revisão mais o documento fonte (não o contexto poluidor).
• Formule a tarefa para refutar: "Tente refutar: toda afirmação nesta saída remonta ao documento fonte? Liste as afirmações que não remontam."
• Saída {veredito, offending_claims[]}; para fluxos de alto risco, pergunte novamente em ordem diferente e faça um voto de consistência.
• Custo: +1 chamada LLM por tarefa — limite a saídas visíveis ao usuário ou decisões de alto risco.

Fase 5 — O relatório

# Auditoria de alucinação — {agente}
## Veredito de uma linha
## Visão geral das evidências (nós / versão auditada / amostra de tarefa / amostra + direção de correção)
## Descobertas (cada uma: localização | R# | texto citado | consequência | correção #)
## Mapa de fluxo de dados e canais de carta morta
## Recomendações de correção (Camada 1/2/3, cada uma marcada com as descobertas que elimina)
## A verificar (suspeitas sem evidência suficiente + como obtê-las)
## Fronteira honesta (quais correções são lacunas de processo, não alucinações; o que esta auditoria não cobriu)

Solidariedade como a fronteira (extensão opcional)

Fiel + relevante são o piso. O problema em aberto é solidário: a fonte citada apoia, contradiz ou permanece neutra sobre a afirmação? Duas notas da pesquisa:

• Modele como posição mais grau. A posição de três vias (entail / contradiz / neutro) perde apoio parcial ou condicional, que é a maior parte do texto regulatório e legal. Adicione uma bandeira "parcial/condicional" que encaminha para revisão humana.
• A solidariedade é relativa à intenção. A mesma passagem apoia "nós cumprimos" e contradiz "nós temos uma lacuna", dependendo do que o usuário está argumentando. Quando a posição ou intenção é incerta, apresente tanto uma fonte de apoio quanto uma de contradição e deixe o usuário escolher. Apresente a direção como uma bandeira que convida à revisão, não como um veredito.

Lembretes

• Se um prompt é "chocantemente ruim", primeiro verifique se é um boilerplate gerado automaticamente (Role/Objective/Task repetidos é o sinal). "Um problema sistemático com este gerador" supera listar a mesma falha por agente.
• Contraste dentro de um agente: quais campos estão limpos e quais falham. A diferença geralmente é a resposta (campos com uma opção unknown tendem a estar limpos).
• Execute o relatório em uma passagem de edição em linguagem simples: uma descoberta deve ser legível para alguém que não leu a teoria.

---

Habilidades relacionadas

Parte de uma pequena família de habilidades de agente abertas para comunicação confiável e clara:

• reduce-hallucination — audite agentes LLM; fundamente, cite, abstenha-se.
• better-doc — Estilo Clássico + Brevidade Inteligente.
• numbers — torne os números significativos, e mostre-os limpos.