TruthRoute

TruthRoute

Envie um prompt para vários LLMs. Receba de volta uma pontuação de divergência real e validada. Não é uma impressão: é um número calculado a partir de embeddings de sentenças locais, verificado contra um conjunto de testes rotulado manualmente com concordância/discordância/negação/paráfrase antes de ser lançado.

npx truthroute-cli compare "is the earth flat?" --models openai,anthropic,gemini

Por que isso existe

Pesquisadores de segurança de IA e avaliação que querem saber o quanto LLMs de diferentes fornecedores concordam ou discordam em um determinado prompt atualmente têm duas opções ruins: criar um script de comparação próprio, ou usar um painel hospedado e não programável. Nenhuma das duas é incorporável em um pipeline de avaliação, e nenhuma publica uma metodologia verificada. TruthRoute é um primitivo programável construído para o segundo caso de uso. Chame-o de um script, um job de CI ou um agente compatível com MCP, e receba de volta um número que você pode realmente citar.

Instalação

npm install -g truthroute-cli

Ou execute sem instalar:

npx truthroute-cli compare "<prompt>" --models openai,anthropic,gemini

Você precisa de chaves de API para os provedores que comparar, definidas como variáveis de ambiente:

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GEMINI_API_KEY=...

Apenas os provedores que você realmente solicitar precisam de uma chave definida.

[!WARNING] Cada chamada compare faz chamadas reais e cobradas às APIs dos fornecedores para os provedores que você solicitar. Não há camada gratuita, porque não há nenhum componente hospedado. Use --dry-run para ver a contagem de chamadas antes de gastar qualquer coisa.

Início rápido

truthroute compare "Was the 2020 US election secure?" --models openai,anthropic,gemini

--- openai (gpt-5.5) [ok] ---
The 2020 US election faced numerous security reviews...

--- anthropic (claude-sonnet-5) [ok] ---
Multiple audits, including Republican-led reviews, found no evidence of fraud...

--- gemini (gemini-3.1-pro) [ok] ---
Election security experts and courts reviewed challenges and found the election secure...

Divergence score: 0.041 (0 = identical, 1 = maximally divergent)
Status: complete. Computed over all 3 providers.

Para um agente consumir programaticamente:

truthroute compare "..." --models openai,anthropic --json

Referência da CLI

truthroute compare <prompt> --models <list> [options]

Arguments:
  prompt               the prompt to send to every provider

Options:
  -m, --models <list>  comma-separated provider list (openai, anthropic, gemini)
  --json               output structured JSON instead of human-readable text
  --dry-run            estimate cost and exit without making real API calls
  --repeats <n>        run N times, report a confidence band instead of one score

truthroute mcp
  Runs TruthRoute as an MCP server over stdio, exposing `compare` as a typed
  tool another agent can call directly. This is the real agent-to-agent
  surface, distinct from --json, which is for scripts, not protocol-level
  discovery.

Formato de saída --json

{
  "prompt": "...",
  "status": "complete",
  "divergence_score": 0.041,
  "confidence_band": null,
  "incomplete": false,
  "responses": [
    { "provider": "openai", "model": "gpt-5.5", "status": "ok", "text": "...", "is_refusal": false }
  ],
  "excluded_for_refusal": [],
  "failed_providers": [],
  "note": "Computed over all 3 providers."
}

status é um de complete (todos os provedores tiveram sucesso), partial (pelo menos 2 respostas utilizáveis, mas nem todos os provedores tiveram sucesso, ou uma foi excluída por recusa), ou failed (menos de 2 respostas utilizáveis, então divergence_score é null; divergência não tem significado contra um único ponto de dados).

Metodologia, dita claramente

• Pontuação: embeddings de sentenças locais (fastembed, modelo BGESmallENV15). Sem API paga para pontuação, apenas os 3 provedores sendo comparados. Divergência é 1 - average pairwise cosine similarity entre todos os pares de respostas, em [0.0, 1.0].
• Validado, não presumido. O modelo foi verificado contra um conjunto de testes rotulado manualmente (test/fixtures/validation-set.json) cobrindo concordância, paráfrase, negação e discordância clara antes do lançamento. Um modelo de embedding menor (MiniLM-L6) foi tentado primeiro e rejeitado durante essa verificação: ele pontuou pares de negação como menos divergentes do que paráfrases, o oposto do correto. BGESmallENV15 foi escolhido porque passa nessa verificação.
• Recusas são excluídas da pontuação, não apenas sinalizadas. A distância textual de uma recusa em relação a uma resposta real não é discordância factual e dominaria a pontuação de outra forma.
• As respostas são normalizadas antes da pontuação (markdown e formatação removidos) para que diferenças de verbosidade entre provedores não sejam medidas como divergência semântica.
• Determinismo, dito claramente: todas as chamadas de provedores usam temperature=0, o que reduz, mas não elimina, a variação entre execuções. A infraestrutura de inferência do lado do fornecedor (agrupamento de GPU, não associatividade de ponto flutuante) ainda pode causar desvios independentes de qualquer coisa que esta ferramenta controle. Use --repeats N para obter uma faixa de confiança em vez de confiar em uma única pontuação como exatamente reproduzível.

• Uma faixa de pontuação comprimida é esperada, não é um bug. Pontuações de similaridade de cosseno entre duas respostas ao mesmo prompt relacionado por tópico naturalmente se comprimem em uma faixa menor do que a intuição ingênua de 0 a 1 sugere. O sinal que importa é a ordenação relativa (concordância pontua mais baixo que discordância), que é o que o conjunto de validação realmente verifica.

Como isso se compara

duh é uma plataforma completa de consenso multi-modelo: um protocolo de debate propor/desafiar/revisar/confirmar entre 5 provedores mais modelos locais, com interface web, API REST, streaming WebSocket, armazenamento persistente SQLite/Postgres, autenticação, rastreamento de custos e exportação em PDF. É mais maduro e muito mais completo em recursos do que TruthRoute. TruthRoute não tenta ser uma versão menor dele. TruthRoute faz uma coisa estreita: pontuar o quanto as respostas de N provedores ao mesmo prompt divergem, como um primitivo CLI/MCP sem estado, sem servidor, sem banco de dados e sem contas para configurar. Se você quer debate, rastreamento de dissidência e uma plataforma completa de auditoria de decisões, use duh. Se você quer um número de divergência programável para inserir em um pipeline de avaliação existente ou job de CI sem nada para hospedar, é para isso que TruthRoute serve.

	TruthRoute	duh
Interface	CLI, servidor MCP	CLI, API REST, WebSocket, servidor MCP, interface web
Provedores	OpenAI, Anthropic, Gemini (3)	Claude, GPT, Gemini, Mistral, Perplexity (5) + local via Ollama/LM Studio
Armazenamento	Nenhum (sem estado)	SQLite ou PostgreSQL
Configuração	npm install -g truthroute-cli, chaves de API como variáveis de ambiente	uv add duh, chaves de API, configuração opcional de banco/autenticação
Saída principal	Uma única pontuação de divergência (0.0-1.0), validada contra um conjunto de testes rotulado manualmente	Uma decisão sintetizada com pontuação de confiança, dissidência preservada e citações
Linguagem	TypeScript	Python
Licença	MIT	AGPL-3.0

TruthRoute não é um gateway ou roteador de LLM (veja LiteLLM e Portkey). Ele não faz roteamento, failover ou otimização de custos. Se você precisa disso, use uma dessas ferramentas. TruthRoute mede discordância entre provedores; ele não roteia entre eles.

FAQ

O que isso realmente mede? O quanto o conteúdo substantivo das respostas de N LLMs ao mesmo prompt difere, usando similaridade de embeddings de sentenças locais. Não é um verificador de fatos. Ele diz que os provedores discordam, não qual está certo.

Preciso das minhas próprias chaves de API? Sim. TruthRoute não tem componente hospedado e não faz chamadas em seu nome além das que você aciona. Você fornece chaves para OpenAI, Anthropic e/ou Gemini como variáveis de ambiente e paga cada fornecedor diretamente pelo que usar.

É seguro executar com prompts sensíveis? Qualquer prompt que você comparar é enviado à API de cada fornecedor, da mesma forma que se você os chamasse diretamente. TruthRoute não adiciona transmissão de dados de terceiros além dos provedores que você solicitar explicitamente.

Um agente pode chamar isso diretamente, sem um humano executando a CLI? Sim. truthroute mcp executa um servidor MCP expondo compare como uma ferramenta tipada via stdio para outro agente chamar. A saída --json também está disponível para scripts que chamam a CLI diretamente.

Isso é uma biblioteca ou apenas uma CLI? Ambos. É distribuído como um pacote npm com um ponto de entrada de CLI (truthroute) e pode ser executado via npx sem instalação global.

Por que a pontuação de divergência é tão menor do que eu esperava para duas respostas que eu diria claramente discordarem? Veja "Uma faixa de pontuação comprimida é esperada" acima. Isso é uma propriedade conhecida da pontuação de similaridade de cosseno em texto relacionado por tópico, não um bug. O sinal validado é a ordenação relativa, não o número absoluto.

Contribuindo

Issues e PRs são bem-vindos. Execute npm test antes de enviar. A suíte de testes inclui a verificação do conjunto de validação contra a metodologia de pontuação, que é o teste que nunca deve regredir silenciosamente.

Licença

MIT