Iris

Iris — pare de lançar agentes no achismo

O Iris pontua cada execução de agente por qualidade, segurança e custo — na sua máquina, sem SDK e sem conta. A maioria dos projetos de agentes verifica qualidade rodando alguns prompts memorizados e avaliando a saída visualmente. O Iris substitui isso por números que você pode auditar: as execuções dos seus agentes caem em um banco de dados SQLite no seu disco, 25 regras integradas pontuam deterministicamente — PII, injeção de prompt, marcadores de alucinação, limites de custo e as próprias chamadas de ferramenta do agente — grátis, sem chamadas de LLM, e um juiz LLM opcional com limite rígido de custo por avaliação cuida das questões semânticas. Toda regra é inspecionável e editável, porque um juiz que você não pode auditar é só achismo com um número em cima. Licença MIT, sem telemetria. Nada sai da sua máquina a menos que você ative uma destas opções: um endpoint OpenTelemetry (IRIS_OTEL_ENDPOINT), que exporta traces para o coletor que você nomear; o juiz LLM com sua própria chave, que envia o texto julgado para esse provedor, e cuja verificação de citação busca as páginas que uma saída cita; ou um webhook, que envia ids, o veredito e nomes de regras, nunca o texto, para o endereço que você definir.

Requer Node.js 22.13 ou posterior. Verifique com node --version.

_{O banco de dados de demonstração, gravado por scripts/demo-media.mts; a fonte é demo.mp4. Uma imagem estática: dashboard-overview.png.}

Uma falha na tela em 60 segundos

Sem configuração de agente, sem config — um comando:

npx @iris-eval/mcp-server --demo

Isso popula um banco de dados de demonstração — cinco agentes pequenos, duas semanas de execuções, todo veredito vindo do próprio mecanismo — e serve o dashboard contra ele em http://localhost:6920 (seu navegador abre automaticamente na primeira execução). O dashboard cai em Failures: o que falhou, do pior ao mais recente, cada cartão nomeando a regra e sua evidência. Vale clicar — um vazamento de PII pego pelas regras de segurança, uma diretiva oculta em um post de fórum que o resumidor obedeceu, um número que o documento-fonte nunca disse, duas execuções nas mesmas doze perguntas comparadas com um intervalo (Runs), uma regra customizada implantada e uma pausada com suas linhas de auditoria, e uma pontuação de juiz LLM reprovada com sua justificativa.

Os dados de demonstração vivem em seu próprio banco (demo.db no seu diretório home do Iris — ~/.iris no macOS/Linux, %USERPROFILE%\.iris no Windows) e nunca se misturam com seus traces reais. Remova tudo com um comando:

npx @iris-eval/mcp-server --demo-clear

Conecte seu próprio agente

Primeiro, prove que a instalação funciona nesta máquina — roda offline e não abre nada seu:

npx @iris-eval/mcp-server --self-test   # exit 0 = healthy

Depois adicione o Iris ao seu cliente MCP. Um comando grava o arquivo de configuração do próprio cliente, mantém todos os outros servidores nele e fixa a versão que você executou:

npx -y @iris-eval/mcp-server install claude-code

Os clientes: claude-code, claude-desktop, cursor, windsurf, continue, vscode, cline, zed, codex, gemini. install --list mostra os encontrados nesta máquina, o Iris que cada um executa e o arquivo que ele lê; install <client> --uninstall remove o Iris novamente. Todos os clientes compartilham um banco de dados, então após uma atualização mova todos de uma vez com install --upgrade (Atualizando). Reinicie o cliente para carregá-lo.

Claude Desktop: um clique. Cada release a partir de 0.20.0 anexa iris-eval.mcpb, um MCP Bundle: baixe o mais recente, abra-o, e o Claude Desktop mostra um diálogo de instalação. Nada nele é obrigatório — uma chave Anthropic ou OpenAI para o juiz LLM é opcional, e o dashboard é um interruptor que começa desligado. O bundle contém o pacote npm e suas dependências, então nada mais precisa ser instalado: o Claude Desktop o executa sob o Node que ele acompanha quando esse Node é 22.13 ou mais novo (Claude Desktop 1.1.6679 acompanha 24.13), e o Iris armazena traces com o SQLite embutido do Node, no mesmo ~/.iris que toda outra instalação usa. As notas de release mostram como verificar sua assinatura e atestado de build.

Ele roda em qualquer cliente MCP, e cada cliente que ele nomeia tem uma linha com o que foi realmente verificado. Verificado em toda execução de CI: Claude Code, Gemini CLI — o cliente real inicia o Iris a partir da configuração que o instalador escreveu e reporta que conectou (claude mcp list, gemini mcp list), em Linux, macOS e Windows; os hooks do plugin de captura do Claude Code também são acionados pelos scripts reais. Afirmado a partir da documentação MCP de cada cliente — o instalador escreve o formato de configuração que o cliente documenta, e esse escritor é testado no formato; ninguém do lado do Iris viu a conexão: Claude Desktop, Cursor, Devin Desktop (Windsurf), Continue, VS Code, Cline, Zed, OpenAI Codex CLI. Cada linha com sua fonte e a data em que foi lida: https://iris-eval.com/clients. Manualmente, um bloco, dashboard incluído:

{
  "mcpServers": {
    "iris-eval": {
      "command": "npx",
      "args": ["-y", "@iris-eval/mcp-server", "--dashboard"]
    }
  }
}

Seu cliente lista as doze ferramentas do Iris na conexão, e o dashboard serve em http://localhost:6920. Agora cole isto no seu agente:

Registre essa última tarefa no Iris e avalie a saída.

O trace cai no dashboard com suas pontuações. Prefere o servidor MCP sem interface? Remova --dashboard dos argumentos — você pode abrir o mesmo dashboard a qualquer momento com npx @iris-eval/mcp-server --dashboard.

Uma coisa que vale saber de antemão: ferramentas MCP são chamadas quando o modelo decide chamá-las. O Iris não intercepta seu agente, então traces são registrados quando seu agente pede para registrá-los — seja porque você mandou, seja porque seu código chama as ferramentas diretamente. Peça ao seu agente para "registrar isso no Iris e avaliar" e ele fará. Se você quer captura que não dependa da escolha do modelo, POST /api/v1/traces faz exatamente isso — seu código envia o trace por HTTP puro, sem modelo no meio (veja docs/http-ingest.md). A CLI e os hooks de host no roadmap serão clientes leves sobre o mesmo endpoint.

Captura por HTTP (sem modelo no meio)

O endpoint de ingestão vive na porta do dashboard — 6920 por padrão, não a porta do transporte MCP — e existe apenas enquanto o dashboard está rodando. Passe --dashboard (ou defina IRIS_DASHBOARD=true); --transport http sozinho não o inicia, e uma requisição à porta de transporte retorna 404. Com o dashboard de pé, qualquer coisa que possa enviar uma requisição HTTP pode registrar um trace — e opcionalmente rodar as avaliações determinísticas na mesma requisição. GET /api/v1/capabilities na mesma porta diz o que este servidor pode julgar, o que cada regra precisa, o estado do juiz com os passos que o habilitam e os limites — o mesmo objeto que o recurso MCP iris://capabilities serve — então um chamador HTTP tem o enquadramento que um cliente MCP recebe no initialize:

curl -s -X POST "http://127.0.0.1:6920/api/v1/traces" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "support-bot",
    "input": "What is the refund policy?",
    "output": "Refunds are available within 30 days of purchase.",
    "evaluate": true,
    "eval_type": "safety"
  }'

Retorna 201 com o trace_id armazenado e o resultado da avaliação (no modo --demo o endpoint recusa escritas com 403, então dados de demonstração nunca se misturam com os seus). O endpoint aceita o mesmo corpo que a ferramenta log_trace e fica atrás da mesma pilha de middleware que o resto do dashboard: bind de loopback e a proteção contra DNS-rebinding por padrão, mais autenticação Bearer quando você define uma. Dois fatos simples sobre ele: aceita escritas não autenticadas a menos que o Iris tenha sido iniciado com --api-key (ou IRIS_API_KEY) — o bind de loopback é o que o mantém na sua máquina por padrão, então defina uma chave antes de vincular além do loopback; e o que ele armazena é verbatim — input e output caem em iris.db exatamente como enviados, incluindo qualquer texto que no_pii venha a sinalizar. Contrato completo, referência de campos e semântica de erros: docs/http-ingest.md.

Capture cada turno do Claude Code (opcional)

/plugin marketplace add iris-eval/mcp-server
/plugin install iris-eval-capture@iris-eval

Um segundo plugin, instalado separadamente: três hooks registram o prompt de cada turno, chamadas de ferramenta e resposta final e os entregam a iris-eval ingest, em modo destacado, com spans críticos redigidos no texto de avaliação armazenado — captura que não depende do modelo decidir chamar uma ferramenta. Nunca registra um turno que o modelo já registrou, nunca imprime, nunca bloqueia, nunca envia nada para lugar nenhum. Instalar iris-eval sozinho não muda nada no seu loop de turnos. Limites e remoção: claude-plugin-capture/README.md.

Python

pip install iris-eval

from iris_eval import IrisClient
iris = IrisClient()                       # IRIS_URL, or the running dashboard's runtime.json
iris.evaluate_output("…", input="…", agent_name="support-bot")["verdict"]   # {"state": "pass", "basis": "clean", "by": []}

Um cliente leve sobre a API HTTP do servidor 0.16.0 e posterior, versionado separadamente — iris_eval.__version__ e a página do PyPI carregam seu número, que não é o do servidor: log_trace(), evaluate_output(), get_traces(), get_trace(), health(), capabilities(), síncrono e assíncrono, respostas tipadas, a própria frase do servidor sobre uma recusa — e um plugin pytest: uma fixture iris e assert_iris(output, expect="pass") que afirma o estado do veredito. packages/python/README.md.

Registre toda chamada OpenAI e Anthropic

from iris_eval import wrap_openai
client = wrap_openai(OpenAI(), agent_name="support-bot")   # every call: a GenAI span to POST /v1/traces, scored

import { wrapOpenAI } from '@iris-eval/sdk';
const openai = wrapOpenAI(new OpenAI(), { agentName: 'support-bot' });

Envolva o cliente do provedor uma vez e cada chamada de modelo vira um span GenAI OpenTelemetry enviado à porta OTLP, armazenado com sua entrada, saída, uso de tokens e chamadas de ferramenta, e pontuado: captura que não depende do modelo chamar uma ferramenta. wrap_openai / wrap_anthropic no cliente Python; wrapOpenAI, wrapAnthropic e irisMiddleware para o Vercel AI SDK em @iris-eval/sdk. Ambos ainda não publicados (o próximo release iris-eval no PyPI; @iris-eval/sdk é construído da fonte até seu primeiro release npm). Streams, os helpers de stream dos SDKs e chamadas de ferramenta são cobertos, o cliente original não é alterado, e o Iris fora do ar nunca quebra uma chamada — packages/sdk/README.md, packages/python/README.md.

Pontue toda execução LangChain e LangGraph

from iris_eval.langchain import IrisCallbackHandler
graph.invoke(inputs, config={"callbacks": [IrisCallbackHandler(agent_name="support-bot")]})

Cada execução de nível superior vira um trace (a execução, suas chamadas de modelo, suas chamadas de ferramenta e seus nós de grafo como spans GenAI) com sua entrada, saída, chamadas de ferramenta, uso de tokens e um veredito. Python no cliente (próximo release, ainda não publicado no PyPI), JavaScript como @iris-eval/langchain (ainda não publicado no npm). Ambos são comprovados em CI contra um app LangGraph real com um modelo roteirizado; a exportação OpenTelemetry do próprio LangSmith é comprovada da mesma forma — docs/otel-recipes.md.

Um portão de CI, sem servidor necessário

npx -y @iris-eval/mcp-server ingest --file traces.ndjson --evaluate --fail-on detector_veto

Ou a GitHub Action (0.16.0), que reprova o job nos vereditos que você nomear, escreve o recibo no resumo do job e o publica como um comentário de pull request atualizado no lugar: uses: iris-eval/mcp-server/.github/actions/gate@v0.19.0 com traces: traces.ndjson — docs/ci-gate.md. Uma quarta porta (0.15.0): POST /v1/traces na porta do dashboard recebe o JSON ou protobuf OTLP/HTTP que sua instrumentação OpenTelemetry já emite (o exportador do SDK Python fala apenas protobuf, então esta também é a porta para Python), e cada trace OTLP se torna um trace Iris com seus spans — docs/otel-integration.md; uma receita por framework (Pydantic AI, Google ADK, LangGraph via LangSmith, CrewAI, o OpenAI Agents SDK em Python e JavaScript, LlamaIndex, AutoGen, Microsoft Agent Framework, Semantic Kernel, o Vercel AI SDK e Mastra), cada uma comprovada por um fixture, em docs/otel-recipes.md. ingest lê um trace JSON (ou NDJSON, um por linha) de stdin ou de um arquivo, armazena-o, avalia-o exatamente sob as regras que evaluate_output executa, imprime uma linha JSON por trace com o veredito e sua base, e sai com código 1 quando um veredito corresponde a --fail-on. --dataset <id|label> restringe esse portão às chaves de caso em um dataset (POST /api/v1/datasets promove as chaves de caso de uma execução em um), para que um job falhe apenas nos casos que você escolheu. A receita completa, os códigos de saída e as oito bases estão em docs/ci-gate.md.

Escreva uma regra como código

eval.plugins em config.json carrega regras que você escreveu — um módulo ES cuja exportação padrão é { name, kind, mechanism, version, needs, evaluate(ctx) } — fixado pelo sha256 do arquivo, de modo que um arquivo alterado desde a fixação recusa a inicialização em vez de executar. Um plugin carregado dispara como um integrado e aparece em list_rules sob plugins. O contrato, a receita de hash e o que um plugin pode retornar: docs/plugins.md.

Use o motor no seu próprio processo

O motor de avaliação é importável — sem servidor, sem banco de dados, sem modelo:

import { EvalEngine, defaultConfig } from '@iris-eval/mcp-server/engine';

const engine = new EvalEngine(defaultConfig.eval.defaultThreshold, defaultConfig.eval.ruleThresholds, defaultConfig.eval);
const result = await engine.evaluateAll({ output: answer, input: prompt, toolCalls, costUsd });
result.verdict.state;       // 'pass' | 'fail' | 'unknown', with result.verdict.basis and result.interpretations

O mesmo motor, as mesmas regras e o mesmo compositor que o servidor executa; builtInRules(), createCustomRule(), compose() e os leitores de precisão publicada são exportados ao lado dele.

Um cliente tipado para a rota HTTP

import { createClient } from '@iris-eval/mcp-server/client';

const iris = createClient({ baseUrl: 'http://127.0.0.1:6920', apiKey: process.env.IRIS_API_KEY });
const { trace_id, evaluation } = await iris.logTrace({ agent_name: 'support-bot', input, output, tool_calls, evaluate: true });
evaluation?.verdict?.state;  // the same object evaluate_output returns

Um corpo em cada porta: é o que log_trace e iris-eval ingest aceitam. Uma recusa lança IrisClientError com a própria frase e status do servidor. Ambos os subcaminhos são verificados a partir de um tarball empacotado em cada build.

Verifique sua instalação

npx @iris-eval/mcp-server --self-test   # offline diagnostic; exit 0 = healthy, 1 = a check failed
npx @iris-eval/mcp-server --version     # prints the bare version, e.g. 1.2.3

--self-test primeiro cria seu home Iris se estiver ausente e verifica se é gravável (saída 1, nomeando o caminho, se não for), relata onde está o índice de busca do seu banco de dados (inteiro, quantos traces um build em segundo plano indexou até agora, ou sem FTS5 neste SQLite), lê o schema do seu banco de dados (saída 1, com a correção, quando esta versão ou um cliente MCP fixado em uma versão mais antiga não puder abri-lo), então executa suas verificações — round-trip de armazenamento, um SSN plantado e uma injeção plantada capturados pelas regras de segurança, inicialização do dashboard, a proteção contra DNS-rebinding — dentro de um home temporário isolado. Seu banco de dados real é apenas lido, nunca alterado. Tudo o que Iris escreve vive sob um diretório, seu home Iris: ~/.iris por padrão (%USERPROFILE%\.iris no Windows), ou onde IRIS_HOME apontar. É onde iris.db, config.json, custom-rules.json, audit.log, preferences.json e os arquivos de demonstração vivem; aponte IRIS_HOME para um diretório temporário para experimentar Iris sem tocar em seus dados reais.

claude mcp add --transport stdio iris-eval -- npx -y @iris-eval/mcp-server

{
  "servers": {
    "iris-eval": {
      "command": "npx",
      "args": ["-y", "@iris-eval/mcp-server"]
    }
  }
}

{
  "context_servers": {
    "iris-eval": {
      "command": "npx",
      "args": ["-y", "@iris-eval/mcp-server"],
      "env": {}
    }
  }
}

[mcp_servers.iris-eval]
command = "npx"
args = ["-y", "@iris-eval/mcp-server"]

Outros Métodos de Instalação

# Global install (recommended for persistent data and faster startup)
npm install -g @iris-eval/mcp-server
iris-eval --dashboard

# Docker — two servers, two ports: 3000 = MCP HTTP transport,
# 6920 = dashboard (which also serves the POST /api/v1/traces ingest endpoint).
# The image binds 0.0.0.0 inside the container, so a key is required (see Production).
# The volume is the Iris home: the database, deployed rules and audit log persist in it.
docker run -p 3000:3000 -p 6920:6920 -v iris-data:/data \
  -e IRIS_API_KEY="$(openssl rand -hex 32)" ghcr.io/iris-eval/mcp-server

Dica: Instalação global (npm install -g) armazena traces persistentemente em ~/.iris/iris.db. Com npx, os traces persistem no mesmo local, mas a inicialização é mais lenta devido à resolução de pacotes.

O Que Você Obtém

Para onde isso vai a seguir: o mapa de capacidades — toda pergunta que Iris pode receber sobre cada assunto, com o que tem e o que falta — e as três trilhas.

Medido, não reivindicado

Toda regra integrada tem precisão, recall e F1 publicados com intervalos de confiança de 95%, medidos em um corpus rotulado que vive neste repositório (proof/corpus/) e é regenerado com um único comando — npm run proof — offline, sem chave e sem modelo no processo. Esses números são de dois tipos diferentes, e a página nunca os soma: algumas regras são medidas contra rótulos que um modelo deu ao ler a própria falha, o que mede a detecção; as demais são verificadas contra sua própria definição documentada, aplicada de forma independente, o que mostra que o código implementa sua fórmula e não diz nada sobre se a fórmula captura a falha. proof/RESULTS.md e a página de prova marcam cada regra. A CI reexecuta a medição em cada pull request e falha se os números confirmados diferirem do que o código produz, então uma regra não pode mudar sem que seus números mudem junto. Os números estão em iris-eval.com/proof e em proof/RESULTS.md; como o corpus foi criado, o que ele não é e como ler um intervalo estão em docs/proof.md. O corpus é sintético e rotulado por modelo — uma rotulação humana cega está pendente, e a página diz isso; node proof/blind-sample.mjs gera a amostra reproduzível que resolverá isso.

Ferramentas MCP

O Iris registra doze ferramentas que qualquer agente compatível com MCP pode invocar — ciclo de vida de traces e regras, comparação entre execuções, LLM-como-juiz e verificação semântica de citações:

• log_trace — Registra uma execução de agente com spans, chamadas de ferramenta, uso de tokens e custo; passe evaluate: true para pontuar na mesma chamada
• evaluate_output — Pontua a qualidade da saída contra regras de completude, relevância, segurança e custo (heurísticas, determinísticas, gratuitas)
• get_traces — Consulta traces armazenados com filtragem, paginação e suporte a intervalo de tempo, e encontra a execução em que o agente disse algo com q: busca de texto completo sobre entrada, saída, valores de chamadas de ferramenta e metadados, ranqueada, com as palavras correspondentes marcadas
• list_rules — Enumera regras de avaliação personalizadas implantadas (somente leitura)
• deploy_rule — Registra uma nova regra de avaliação personalizada para que ela seja acionada em todo evaluate_output dessa categoria
• delete_rule — Remove uma regra personalizada implantada (destrutiva, idempotente)
• delete_trace — Remove um único trace armazenado por ID (destrutivo, com escopo por locatário)
• evaluate_with_llm_judge — Avaliação semântica via LLM (Anthropic ou OpenAI). Sete modelos: precisão, utilidade, segurança, correção, fidelidade, tarefa_concluída, relevância. Com limite de custo, preço por avaliação divulgado. Traga sua própria chave de API (IRIS_ANTHROPIC_API_KEY ou IRIS_OPENAI_API_KEY) — o Iris não faz proxy nem retransmite chamadas de LLM.
• verify_citations — Extrai citações da saída (numeradas, autor-ano, URLs, DOIs), busca as fontes por trás de um resolvedor protegido contra SSRF e com lista de domínios permitidos, e usa um juiz LLM para verificar se cada fonte realmente sustenta a afirmação citada. HTTP de saída opcional. Mesmo requisito de BYOK que evaluate_with_llm_judge.
• compare_runs — Uma mudança piorou o agente? Compara duas execuções de avaliações armazenadas: um teste exato pareado quando as execuções compartilham chaves de caso, um intervalo sobre a diferença caso contrário, um honesto "não é possível dizer" com o número de casos que seriam necessários, ou "equivalente dentro de uma margem". Cada regra carrega seu próprio teste unilateral, corrigido em conjunto (Benjamini–Hochberg) para que vinte regras não possam fabricar uma regressão
• compare_traces — Com que confiabilidade o agente responde à mesma pergunta? Taxas de aprovação por caso com intervalos, casos instáveis primeiro, e uma taxa geral que respeita repetições
• evaluate_runs — Reavalia cada trace de uma execução sob as regras atuais em uma nova execução, para que uma mudança de regras nunca seja lida como uma mudança do agente

Ative o juiz LLM (opcional; as regras determinísticas nunca precisam dele)

1. Obtenha uma chave de API da Anthropic ou da OpenAI.
2. Coloque-a no ambiente do processo que executa o Iris, não apenas no seu shell. Claude Code, Claude Desktop, Cursor e a maioria dos clientes MCP: o bloco "env" da entrada iris-eval na sua configuração MCP — "iris-eval": { "command": "npx", "args": ["-y", "@iris-eval/mcp-server"], "env": { "IRIS_ANTHROPIC_API_KEY": "sk-ant-..." } } (IRIS_OPENAI_API_KEY para uma chave da OpenAI). Docker: -e IRIS_ANTHROPIC_API_KEY=... no comando run. HTTP ou CI: exporte antes de iniciar o iris-eval.
3. Reinicie a sessão MCP. Um processo em execução nunca vê uma variável definida depois que ele iniciou.
4. Confirme de dentro do seu cliente: leia iris://capabilities — judge.enabled deve ser true lá. Uma chave exportada no seu shell não é passada para o processo que seu cliente inicia, a menos que a configuração dele a liste. Em uma máquina, npx @iris-eval/mcp-server --self-test imprime a linha do juiz para aquele shell, e GET /api/v1/health informa judge.enabled em um dashboard em execução.
5. Proteção de gastos: cada chamada é limitada por IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL (padrão 0,25 USD) e recusada antes de qualquer gasto se o pior caso exceder esse valor. O Iris chama o provedor diretamente com sua chave e nunca a usa como proxy.
6. Opcional: defina IRIS_RELEVANCE_JUDGE_MODEL para um ID de modelo com preço (claude-haiku-4-5, por exemplo) para que answers_the_ask peça ao juiz se cada resposta aborda sua pergunta, e reprove uma fora do assunto. Isso é uma chamada de juiz por avaliação que carrega uma entrada, na sua chave e sob o limite acima; a chave sozinha nunca ativa isso. Cada chamada envia essa entrada e saída ao provedor do modelo, com os dados pessoais e credenciais dos flags no_pii substituídos primeiro (IRIS_RELEVANCE_JUDGE_REDACT=off os envia como estão). Isso gasta no máximo IRIS_RELEVANCE_JUDGE_DAILY_BUDGET_USD por dia UTC (padrão 1 USD) e faz no máximo IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST chamadas por requisição (padrão 20); além de qualquer um desses limites, answers_the_ask lê a pergunta lexicalmente e diz o porquê.

Quando IRIS_OTEL_ENDPOINT está configurado, chamadas de log_trace também emitem uma exportação OTLP/HTTP JSON de melhor esforço para qualquer coletor OpenTelemetry (Jaeger, Grafana Tempo, Datadog OTLP, Honeycomb, etc). Veja docs/otel-integration.md.

Como passed é decidido

evaluate_output retorna tanto um flag score quanto um flag passed — eles respondem a perguntas diferentes:

• score (0..1) é a média ponderada entre as regras que foram executadas — um gradiente de qualidade.
• passed é o veredito de liberar/não liberar, e a pontuação nunca é consultada para ele. Um compositor lê cada regra pelo tipo de afirmação que ela faz: uma política que você configurou bloqueia; um detector crítico veta; uma verificação crítica que foi solicitada e não pôde responder torna o veredito desconhecido (passed: false) em vez de limpo; cada detector restante se combina em uma probabilidade de que a saída seja ruim, ponderada contra a razão de perda que você declara em eval.falsePassCost (padrão 1, então o corte é 0,5). verdict.basis nomeia a camada que decidiu e verdict.by as regras, e verdict.also lista toda camada posterior que também teria decidido; interpretations[] diz por que uma regra que falhou não decidiu e qual configuração mudaria isso, e nomeia qualquer pergunta que não foi julgada e a entrada que permitiria que fosse.

Violaçõs genuínas de segurança falham de forma rígida. Por padrão, no_pii, no_injection_patterns e no_blocklist_words são regras críticas: se uma falhar, a avaliação reporta passed: false não importa quão bem as outras regras pontuaram, e a resposta nomeia os culpados em critical_failures. Um SSN vazado não pode ser diluído por média. Quais regras integradas são críticas é uma configuração de implantação (eval.criticalRules / eval.nonCriticalRules); cada resultado de regra carrega o flag critical efetivo e criticalSource, e list_rules reporta o quadro que este servidor aplica. Regras personalizadas implantadas com severity: "high" ou "critical" falham de forma rígida da mesma maneira; severidades low/medium afetam apenas a pontuação. Um limite para conhecer, declarado da mesma forma em todas as superfícies: uma regra crítica que pulou (contexto ausente, definição quebrada ou um regex morto no orçamento do sandbox) não julgou a saída e não veta — cada uma dessas regras é nomeada em critical_skipped. Um portão que deve falhar fechado trata um critical_skipped não vazio como desconhecido, não limpo, e pode tratar qualquer pulo de budgetExceeded em rule_results da mesma forma.

Para portões de CI: se você omitir eval_type, todo pacote é executado — completude, relevância, segurança, custo e quaisquer regras personalizadas — e a resposta diz eval_type: "all" com um note de que o padrão foi executado, além de um mapa categories por pacote. Um pacote sem nada para julgar (custo sem cost_usd, relevância sem input) reporta passed: null lá — não avaliado, não falhando — e nunca conta para o veredito. A resposta sempre ecoa o eval_type que foi executado, para que seu portão possa verificar a cobertura; use passed para o veredito e nomeie um pacote apenas quando quiser uma execução mais restrita.

Criando uma regra personalizada

Duas maneiras de adicionar uma regra. Regras inline acompanham uma única chamada de evaluate_output (custom_rules, até 10 por chamada); elas são acionadas junto com o pacote eval_type que você escolheu, ou sozinhas com eval_type: "custom". Regras implantadas são registradas uma vez com deploy_rule, persistem em custom-rules.json sob seu home do Iris e são acionadas em todo evaluate_output futuro de seu evalType. A definição tem a mesma forma de qualquer maneira:

deploy_rule envolve a definição com name, um description opcional, evalType (completeness · relevance · safety · cost · custom) e severity. A severidade diz o que uma falha significa: low/medium apenas reduzem a pontuação; high/critical falham a avaliação de forma rígida — passed: false, a regra nomeada em critical_failures — independentemente da pontuação ponderada. Uma regra que pula (uma regra de cost_threshold sem cost_usd, ou um regex morto no orçamento de 100 ms do sandbox) não julgou a saída e é listada em critical_skipped em vez disso. Implante uma regra crítica que proíbe hostnames internos em qualquer coisa que o agente diga:

{
  "name": "no_internal_hostnames",
  "description": "Output must not mention internal hostnames.",
  "evalType": "safety",
  "severity": "critical",
  "definition": {
    "name": "no_internal_hostnames",
    "type": "regex_no_match",
    "config": { "pattern": "\\b[a-z0-9-]+\\.internal\\.example\\b", "flags": "i" }
  }
}

A resposta é a regra persistida — guarde o id para delete_rule:

{ "rule": { "id": "rule-588823d0", "name": "no_internal_hostnames", "evalType": "safety", "severity": "critical", "enabled": true, "version": 1, "definition": { "…": "…" } } }

A partir do próximo evaluate_output com eval_type: "safety", uma saída que mencione db-primary.internal.example retorna passed: false com critical_failures: ["no_internal_hostnames"] — mesmo que todas as cinco regras de segurança integradas tenham passado e a pontuação ponderada seja 0,895. Padrões de regex devem passar por uma verificação de ReDoS no momento da implantação e sempre são executados em um worker de sandbox sob um prazo rígido de 100 ms. list_rules mostra o que está implantado; o compositor de regras do dashboard constrói a mesma forma a partir de uma falha em que você clicou. Referência completa, pontuação por tipo e exemplos práticos: docs/custom-rules.md.

Esquemas completos de ferramentas e configuração: iris-eval.com

Recursos hospedados

O Iris é executado inteiramente na sua máquina hoje, e tudo o que ele faz é gratuito e licenciado sob MIT, sem limites e sem conta. Armazenamento hospedado, histórico compartilhado de equipe e alertas estão em consideração, não em construção. Não há preços e nada para comprar. Se o histórico compartilhado fosse útil para você, a lista de espera é como descobrimos se vale a pena construir — isso não compromete você com nada.

Dois compromissos permanecem independentemente: nada que é gratuito hoje será colocado atrás de um paywall e nenhuma certificação de conformidade será reivindicada antes de ser obtida.

Exemplos

• Configuração do Claude Desktop — configuração MCP para modos stdio e HTTP
• TypeScript — cliente MCP SDK — conectar e invocar ferramentas
• Transporte HTTP (TS + Python) — código completo de cliente para integração no estilo REST
• Um agente LangGraph, avaliado execução por execução (Python) — IrisCallbackHandler nos callbacks do grafo; CI executa o mesmo grafo com um modelo roteirizado
• Uma equipe CrewAI sobre OpenTelemetry (Python) — o instrumentador OpenInference direto para a porta OTLP do Iris, a receita CrewAI como script
• Um agente OpenAI Agents SDK sobre OpenTelemetry (Python) e (JavaScript), e um agente LlamaIndex — cada receita como o script que a CI executa contra um servidor Iris real

Comunidade

• GitHub Issues — Relatórios de bugs e solicitações de recursos
• GitHub Discussions — Perguntas e ideias
• Guia de Contribuição — Como contribuir
• Ingestão HTTP — Captura determinística de traces via POST /api/v1/traces
• Mapa de capacidades — Cada pergunta que o Iris pode receber e o que ele não tem
• Política de versionamento — O que cada número de versão promete e o que precisa ser verdadeiro antes da 1.0

# Production deployment
iris-eval --transport http --port 3000 --api-key "$(openssl rand -hex 32)" --dashboard

# The image: pass a key
docker run -p 3000:3000 -p 6920:6920 -v iris-data:/data \
  -e IRIS_API_KEY="$(openssl rand -hex 32)" ghcr.io/iris-eval/mcp-server

# Compose: the file requires the variable and refuses before the container starts
IRIS_API_KEY="$(openssl rand -hex 32)" docker compose up

# A network you have already fenced some other way: run open, on purpose
IRIS_ALLOW_UNAUTHENTICATED=1 iris-eval --transport http --dashboard

npx @iris-eval/mcp-server --self-test

npx --yes @iris-eval/mcp-server@latest

npm install -g @iris-eval/mcp-server@latest

npm rebuild better-sqlite3
# for a global install:
npm rebuild -g better-sqlite3

npx @iris-eval/mcp-server --version

npx -y @iris-eval/mcp-server@latest install --upgrade

node --version  # Must be v22.13.0 or newer

# Correct
claude mcp add --transport stdio iris-eval -- npx -y @iris-eval/mcp-server

# Wrong (causes /c to be parsed as a path)
claude mcp add --transport stdio iris-eval -- cmd /c "npx -y @iris-eval/mcp-server"

Se o Iris for útil para você, considere dar uma estrela no repositório — isso ajuda outras pessoas a encontrá-lo.

Licenciado sob MIT.