OpenGATE

Open Grounded AI Testing & Evaluation

Verificação determinística e ancorada em ouro para IA fundamentada em evidências — sem juiz LLM.

Início rápido · Arquitetura · Superfícies · Exemplos · Roteiro · Contribuição · Changelog

Evidência acima de plausibilidade. O OpenGATE verifica sistemas de IA que precisam justificar cada resposta a partir do material de origem — pipelines de RAG, ferramentas de QA documental, assistentes jurídicos e científicos. Ele responde a uma pergunta acima de tudo: o sistema consegue provar sua resposta a partir das evidências que recebeu?

A verificação é determinística — sem LLM-como-juiz, sem modelo avaliador, sem escala de veredito de seis pontos. Fatos obrigatórios devem estar presentes, cada número deve rastrear até a fonte, e quando o contexto não pode responder, o sistema deve se abster em vez de fabricar. Como é lógica pura, é reproduzível, gratuito e rápido o suficiente para rodar em cada resposta ou servir de portão em cada commit.

À medida que a IA avança para domínios de alto risco, a avaliação está se tornando tão fundamental quanto o teste automatizado no software tradicional. O OpenGATE transforma falhas de fundamentação em números que você pode acompanhar, e aplica um portão a cada mudança de prompt, modelo ou fluxo de trabalho contra uma linha de base — para que a confiabilidade não regrida silenciosamente.

Início rápido (60 segundos)

Nenhuma chave de API necessária — o pacote offline executa avaliadores determinísticos contra o conjunto de ouro incluído:

npx @pharmatools/opengate           # run the offline evaluation suite
npx @pharmatools/opengate init      # scaffold gold cases + HTTP config + a GitHub Action

OpenGATE — 39 case(s), online=false, adapter=refcheckr

  ✓ citation-detection   PASS
      perClaim_exactSetRate      100.0%
      perClaim_jaccardMean       100.0%
      supportedStyle_accuracy    100.0%
  ⊘ grounding            SKIPPED — online scorer (pass --online)

Aponte opengate.http.json para seu endpoint e adicione --online --ci para aplicar o portão ao seu próprio sistema. Passo a passo completo: Começando.

Uma verificação, muitas superfícies

A mesma lógica determinística de fundamentação está disponível onde quer que sua stack esteja:

Arquitetura

Os avaliadores nunca falam diretamente com um sistema — eles o alcançam por meio de um pequeno adaptador, para que a metodologia viaje e apenas o conjunto de ouro mude. No ciclo de desenvolvimento, ele fica onde o CI fica: mude um prompt, modelo ou pipeline; o portão de regressão compara o novo scorecard com a linha de base — melhorado ou mantido faz deploy, regredido falha o build.

Por que não DeepEval?

Use ambos — evals medem, OpenGATE verifica. Frameworks de propósito geral como DeepEval e OpenAI Evals avaliam sistemas de IA amplamente, geralmente com um LLM julgando a saída. O OpenGATE verifica a promessa mais restrita e difícil: que cada resposta é fundamentada em evidências:

• Proveniência é primeira classe — a passagem citada realmente existe, verbatim, na fonte?
• Sem juiz LLM — as pontuações são verificações determinísticas contra ouro rotulado manualmente, então são reproduzíveis e gratuitas para rodar no CI; seu julgamento vive no conjunto de ouro, não em um modelo avaliador.
• Detecção de regressão é primeira classe — cada execução é comparada com uma linha de base por adaptador; uma queda falha o build.

Combine um framework geral para métricas de qualidade amplas com o OpenGATE para aplicar o portão na fundamentação.

Conceitos principais

Casos de ouro — casos de benchmark rotulados manualmente (datasets/cases/): texto-fonte, as afirmações que devem ser extraídas, as frases que não devem ser, e trechos de referência com vereditos conhecidamente corretos. Copie _template.json para adicionar um; formato em datasets/SCHEMA.md, regras de rotulagem em datasets/LABELING-GUIDE.md.

Avaliadores — um módulo por família de métrica (src/scorers/):

Avaliadores offline rodam sem chave de API — rápidos o suficiente para cada commit. Avaliadores online exercitam um sistema ao vivo por meio de um adaptador.

Scorecards — cada execução grava results/<timestamp>.json carimbado com o SHA do git, para que qualquer resultado seja reproduzível e auditável. Execuções por modelo carregam um rótulo run_model, transformando o diretório de resultados em uma comparação medida (precisão × alucinação × latência × custo).

Portão de regressão — --baseline salva uma referência; execuções posteriores imprimem deltas por métrica (▲/▼ em pontos percentuais) e --ci falha o build em qualquer queda. As linhas de base são por adaptador, para que o scorecard de um sistema não possa sobrescrever o de outro.

Relatório HTML — adicione --report (ou opengate report) para um dashboard autônomo: passou/falhou por avaliador, deltas vs linha de base, cada falha nomeada. Um arquivo, sem servidor, sem dependências.

Avaliando seu próprio sistema

Um adaptador é um arquivo: duas exportações base — onlineAvailable(), onlineConfigHint() — mais pelo menos uma capacidade completa (ex.: grounding → answer()). Os avaliadores verificam adapter.capabilities e pulam limpo através da fronteira; adaptadores são validados no carregamento com mensagens nomeando cada exportação ausente.

OPENGATE_ADAPTER=./adapters/my-system.mjs npm run eval:online

Para sistemas com backend REST, há um caminho sem código: o adaptador HTTP genérico incluído lê caminhos de endpoint e cabeçalhos de opengate.http.json (interpolação ${ENV}, captura integrada de latência/tokens). Contrato completo e um esqueleto mínimo: ADAPTERS.md.

Exemplos

• Avaliando um agente RAG com NIM — constrói um agente RAG em um modelo NVIDIA NIM e aplica o portão na fundamentação das respostas com OpenGATE, deterministicamente e sem juiz LLM. Inclui um notebook Python executável (opengate-grounding) e um adaptador Node para o portão de CI.

Comprovado em produção

Quatro produtos PharmaTools rodam no OpenGATE no CI — quatro formatos de capacidade diferentes, um padrão de avaliação. Executado contra o conjunto de ouro do RefCheckr, o OpenGATE:

• revelou um modo de falha silenciosa de parsing afetando ~50% dos vereditos de múltiplas afirmações, eliminado com saída estruturada forçada (→ 0);
• reduziu pela metade a alucinação de passagem (5,8% → 2,4%) ao conduzir uma mudança medida no modelo de produção — uma decisão tomada com base em números, não em reputação;
• mantém a extração de afirmações em 0,91 F1 com 0,93 de recall na linha de base commitada (variação entre execuções 0,86–0,94 — o divisor é um LLM), e atualmente está falhando seu próprio portão: 2 não-afirmações conhecidas vazam para a extração na maioria das execuções, um problema aberto do divisor que o portão relata em vez de arredondar.

npm install --no-save @pharmatools/redacta
node src/runner.mjs --online --adapter ./src/adapters/redacta.mjs

node src/runner.mjs --online --adapter ./src/adapters/patiently.mjs

node src/runner.mjs --online --adapter ./src/adapters/pubcrawl.mjs

Metodologia completa e comparação de modelos: como o RefCheckr é avaliado.

Estrutura do projeto

opengate/
├── src/
│   ├── lib/          metrics + shared grounding core (single source of truth)
│   ├── scorers/      one file per metric family (7 scorers)
│   ├── adapters/     system-under-test boundary (refcheckr.mjs is the reference)
│   └── runner.mjs    CLI: discover cases → score → report → snapshot → gate
├── datasets/         gold-labelled cases (39) + fixtures + schema
├── examples/         worked examples (NVIDIA NIM RAG)
├── mcp/              MCP server (@pharmatools/opengate-mcp)
├── python/           opengate-grounding (PyPI) + DeepEval metric
├── Dockerfile        CPU-only image (pharmatools/opengate)
└── action.yml        GitHub Action

Documentação

Contribuição

Contribuições são bem-vindas — especialmente casos de ouro (novos domínios, estilos de citação), adaptadores (conecte seu sistema) e avaliadores (novas famílias de métricas). Veja CONTRIBUTING.md — incluindo suas expectativas de suporte e governança e divulgação de desenvolvimento assistido por IA; abra uma issue para discutir mudanças grandes. Interfaces podem ainda mudar antes da 1.0, e o semver sinalizará mudanças que quebram.

Citando o OpenGATE

Se você usar o OpenGATE em pesquisa, por favor cite-o — os metadados de citação estão em CITATION.cff (o botão "Cite this repository" do GitHub os usa).

Licença

MIT — porque frameworks de avaliação não deveriam ser caixas-pretas. Se uma avaliação influencia decisões de deploy, engenheiros deveriam poder inspecionar cada avaliador, métrica e benchmark.