Documentação · Metodologia
Como uma resposta de IA vira uma classe — o ADR-031 resumido
Cinco classes de citação, um classificador que se recusa a rodar sem verdade fundamentada, heurística antes de juiz e um histórico que nunca é sobrescrito. Esta é a versão técnica; as métricas publicadas e o score estão em /metodologia.
As 5 classes de citação
"A IA mencionou a marca" é um booleano que mistura três situações muito diferentes: a IA conhece a marca e diz algo verificável; a IA só repete o nome que estava na pergunta; a IA inventa uma descrição plausível a partir do nome. O ADR-031 separa isso em cinco classes — e só STRONG e DESCRIPTIVE contam para a taxa de citação publicada. As outras três existem porque a diferença entre elas é a informação: muito ECHO é problema de conteúdo; muito CONFABULATED é problema de reputação.
| Classe | Decisão | Critério |
|---|---|---|
| STRONG | máquina | A resposta cita a URL do domínio da marca. Verificável por máquina, sem julgamento. |
| DESCRIPTIVE | juiz | Descreve corretamente o que a marca faz, sem link — conferido contra a verdade conhecida. |
| ECHO | heurística/juiz | Só repete o nome. Típico de prompts que trazem a marca no enunciado. |
| CONFABULATED | juiz | Afirma fato específico que contradiz ou não consta da verdade conhecida. |
| ABSENT | máquina | Sem menção nenhuma à marca. |
Sem verdade fundamentada, o classificador não roda
Um LLM classificador sem contexto tem exatamente o problema que tenta detectar: perguntar a um modelo "esta descrição da marca está correta?" produz um palpite confiante sobre um site que ele talvez nunca tenha visto — uma alucinação com aparência de auditoria, que é pior que a invisível, porque essa a gente publicaria. Por isso a regra estrutural: o classificador exige ground truth não-vazio e falha explicitamente sem ele. Não existe modo "melhor esforço".
A verdade fundamentada é registrada como GroundTruthFact: cada fato guarda o tipo e a URL da fonte, a data de coleta (fetchedAt), a atribuição e o hash SHA-256 do conteúdo. A coleta pode ser disparada por POST /v1/brands/:id/ground-truth/refresh, e os fatos ativos são consultáveis em GET /v1/brands/:id/ground-truth.
Heurística antes de juiz
Duas das cinco classes são decidíveis sem julgamento nenhum — STRONG (a URL do domínio está na resposta) e ABSENT (a marca não aparece) — e são a maioria dos casos. A heurística determinística resolve esses primeiro; só o meio ambíguo vai para o juiz LLM (hoje openai/gpt-4o-mini, via OpenRouter), que julga a resposta contra a verdade fundamentada, nunca contra a própria memória. Cada classificação registra se foi determinística ou de juiz, e qual modelo julgou.
Evidência verificável por qualquer pessoa
Toda resposta classificada aponta para a evidência bruta com hash SHA-256 — e o hash é conferível publicamente, sem conta, pela interface em /verify ou pelos dois endpoints públicos:
# O hash existe? (público, sem conta)
curl -s https://api.genopt.ai/v1/public/evidence/<hash-sha256>
# Conferência byte a byte do conteúdo em mãos:
curl -X POST https://api.genopt.ai/v1/public/evidence/<hash-sha256>/check \
-H 'Content-Type: application/json' \
-d '{"content":"<texto exato da resposta>"}'Reclassificar nunca sobrescreve
A classificação vigente de um run fica nas colunas do próprio run; todas as que já foram feitas ficam no histórico (CitationClassification). Reclassificar — por reverificação, backfill ou ferramenta manual — acrescenta uma linha, nunca apaga a anterior. Cada linha registra também o groundTruthHash: o SHA-256 do texto de verdade usado naquele julgamento. É o que permite responder "o que sabíamos e quando" — a mesma resposta julgada contra uma verdade diferente pode mudar de classe, e sem o hash essa diferença seria indistinguível de inconsistência.
O que esta página não cobre
As métricas agregadas — GenOpt Score, share of voice, taxa de confabulação, quais engines medimos e com que cadência, e o rigor experimental dos nossos próprios experimentos — estão em /metodologia, com as fórmulas publicadas. As duas páginas descrevem o mesmo sistema; esta é a de quem integra, aquela é a de quem interpreta os números.