Iris

Iris — deja de lanzar agentes a ciegas

Iris puntúa cada ejecución de agente en calidad, seguridad y costo, en tu máquina, sin SDK y sin cuenta. La mayoría de los proyectos de agentes verifican calidad ejecutando algunos prompts recordados y revisando la salida a ojo. Iris reemplaza eso con números que puedes auditar: las ejecuciones de tu agente se guardan en una base de datos SQLite en tu disco, 25 reglas integradas las puntúan de forma determinista — PII, inyección de prompts, marcadores de alucinación, umbrales de costo y las propias llamadas a herramientas del agente — gratis, sin llamadas a LLM, y un juez LLM opcional con un límite de costo por evaluación maneja las preguntas semánticas. Cada regla es inspeccionable y editable, porque un juez que no puedes auditar es solo una corazonada con un número encima. Licencia MIT, sin telemetría. Nada sale de tu máquina a menos que actives una de estas opciones: un endpoint de OpenTelemetry (IRIS_OTEL_ENDPOINT), que exporta trazas al colector que nombres; el juez LLM con tu propia clave, que envía el texto que juzga a ese proveedor, y cuya verificación de citas obtiene las páginas que una salida cita; o un webhook, que publica ids, el veredicto y los nombres de reglas, nunca el texto, a la dirección que configures.

Requiere Node.js 22.13 o posterior. Verifica con node --version.

_{La base de datos de demostración, grabada por scripts/demo-media.mts; la fuente es demo.mp4. Una imagen fija: dashboard-overview.png.}

Un fallo en pantalla en 60 segundos

Sin cableado de agente, sin configuración — un comando:

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

Esto siembra una base de datos de demostración — cinco agentes pequeños, dos semanas de ejecuciones, cada veredicto del propio motor — y sirve el panel contra ella en http://localhost:6920 (tu navegador se abre automáticamente en la primera ejecución). El panel aterriza en Fallos: qué falló, peor y más reciente primero, cada tarjeta nombra la regla y su evidencia. Vale la pena hacer clic — una fuga de PII detectada por las reglas de seguridad, una directiva oculta en una publicación de foro que el resumidor cumplió, un número que el documento fuente nunca dijo, dos ejecuciones sobre las mismas doce preguntas comparadas con un intervalo (Ejecuciones), una regla personalizada desplegada y una pausada con sus filas de auditoría, y una puntuación fallida del juez LLM con su justificación.

Los datos de demostración viven en su propia base de datos (demo.db en tu directorio de inicio de Iris — ~/.iris en macOS/Linux, %USERPROFILE%\.iris en Windows) y nunca se mezclan con tus trazas reales. Elimina todo con un comando:

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

Conecta tu propio agente

Primero, comprueba que la instalación funciona en esta máquina — se ejecuta sin conexión y no abre nada tuyo:

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

Luego añade Iris a tu cliente MCP. Un comando escribe el archivo de configuración del propio cliente, conserva todos los demás servidores y fija la versión que ejecutaste:

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

Los clientes: claude-code, claude-desktop, cursor, windsurf, continue, vscode, cline, zed, codex, gemini. install --list muestra los encontrados en esta máquina, el Iris que ejecuta cada uno y el archivo que lee; install <client> --uninstall saca a Iris de nuevo. Cada cliente comparte una base de datos, así que tras una actualización muévelos todos a la vez con install --upgrade (Actualización). Reinicia el cliente para cargarlo.

Claude Desktop: un clic. Cada versión desde la 0.20.0 adjunta iris-eval.mcpb, un MCP Bundle: descarga la más reciente, ábrela y Claude Desktop muestra un diálogo de instalación. Nada en él es obligatorio — una clave de Anthropic u OpenAI para el juez LLM es opcional, y el panel es un interruptor que comienza apagado. El bundle contiene el paquete npm y sus dependencias, así que no necesita instalar nada más: Claude Desktop lo ejecuta bajo el Node que incluye cuando ese Node es 22.13 o más reciente (Claude Desktop 1.1.6679 incluye 24.13), e Iris almacena trazas con el SQLite integrado de Node, en el mismo ~/.iris que usa cualquier otra instalación. Las notas de versión muestran cómo verificar su firma y atestación de compilación.

Se ejecuta en cualquier cliente MCP, y cada cliente que nombra tiene una fila con lo que realmente se verificó. Verificado en cada ejecución de CI: Claude Code, Gemini CLI — el cliente real inicia Iris desde la configuración que escribió el instalador e informa que se conectó (claude mcp list, gemini mcp list), en Linux, macOS y Windows; los hooks del plugin de captura de Claude Code también se manejan a través de los scripts reales. Afirmado desde la propia documentación MCP de cada cliente — el instalador escribe la forma de configuración que el cliente documenta, y ese escritor se prueba en esa forma; nadie del lado de Iris lo ha visto conectarse: Claude Desktop, Cursor, Devin Desktop (Windsurf), Continue, VS Code, Cline, Zed, OpenAI Codex CLI. Cada fila con su fuente y la fecha en que se leyó: https://iris-eval.com/clients. A mano en su lugar, un bloque, panel incluido:

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

Tu cliente lista las doce herramientas de Iris al conectarse, y el panel sirve en http://localhost:6920. Ahora pega esto a tu agente:

Registra esa última tarea en Iris y evalúa la salida.

La traza aterriza en el panel con sus puntuaciones. ¿Prefieres el servidor MCP sin interfaz? Elimina --dashboard de los argumentos — puedes abrir el mismo panel en cualquier momento con npx @iris-eval/mcp-server --dashboard.

Una cosa que vale la pena saber de antemano: las herramientas MCP se llaman cuando el modelo decide llamarlas. Iris no intercepta tu agente, así que las trazas se registran cuando tu agente pide registrarlas — ya sea porque se lo dijiste, o porque tu código llama a las herramientas directamente. Pide a tu agente que "registre esto en Iris y lo evalúe" y lo hará. Si quieres una captura que no dependa de la elección del modelo, POST /api/v1/traces hace exactamente eso — tu código envía la traza por HTTP simple, sin modelo en el bucle (ver docs/http-ingest.md). La CLI y los hooks de host en el roadmap serán clientes ligeros sobre el mismo endpoint.

Captura por HTTP (sin modelo en el bucle)

El endpoint de ingesta vive en el puerto del panel — 6920 por defecto, no el puerto de transporte MCP — y existe solo mientras el panel está en ejecución. Pasa --dashboard (o establece IRIS_DASHBOARD=true); --transport http por sí solo no lo inicia, y una solicitud al puerto de transporte devuelve 404. Con el panel activo, cualquier cosa que pueda enviar una solicitud HTTP puede registrar una traza — y opcionalmente ejecutar las evaluaciones deterministas en la misma solicitud. GET /api/v1/capabilities en el mismo puerto dice qué puede juzgar este servidor, qué necesita cada regla, el estado del juez con los pasos que lo habilitan y los límites — el mismo objeto que sirve el recurso MCP iris://capabilities — para que un llamador HTTP tenga el marco que un cliente MCP obtiene al inicializar:

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"
  }'

Devuelve 201 con el trace_id almacenado y el resultado de la evaluación (en modo --demo el endpoint rechaza escrituras con 403, para que los datos de demostración nunca se mezclen con los tuyos). El endpoint acepta el mismo cuerpo que la herramienta log_trace y está detrás de la misma pila de middleware que el resto del panel: enlace de loopback y la protección contra rebinding de DNS por defecto, más autenticación Bearer cuando estableces una. Dos hechos simples al respecto: acepta escrituras no autenticadas a menos que Iris se haya iniciado con --api-key (o IRIS_API_KEY) — el enlace de loopback es lo que lo mantiene en tu máquina por defecto, así que establece una clave antes de vincular más allá del loopback; y lo que almacena es textual — input y output llegan a iris.db exactamente como se enviaron, incluido cualquier texto que no_pii luego marque. Contrato completo, referencia de campos y semántica de errores: docs/http-ingest.md.

Captura cada turno de Claude Code (opcional)

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

Un segundo plugin, instalado por separado: tres hooks registran el prompt de cada turno, las llamadas a herramientas y la respuesta final y los entregan a iris-eval ingest, de forma separada, con los tramos críticos redactados en el texto de evaluación almacenado — captura que no depende de que el modelo decida llamar a una herramienta. Nunca registra un turno que el modelo ya registró, nunca imprime, nunca bloquea, nunca envía nada a ningún lado. Instalar iris-eval solo no cambia nada en tu bucle de turnos. Límites y eliminación: 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": []}

Un cliente ligero sobre la API HTTP del servidor 0.16.0 y posterior, versionado por separado — iris_eval.__version__ y la página de PyPI llevan su número, que no es el del servidor: log_trace(), evaluate_output(), get_traces(), get_trace(), health(), capabilities(), síncrono y asíncrono, respuestas tipadas, la propia frase del servidor ante un rechazo — y un plugin de pytest: un fixture iris y assert_iris(output, expect="pass") que afirma sobre el estado del veredicto. packages/python/README.md.

Registra cada llamada de OpenAI y 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' });

Envuelve el cliente del proveedor una vez y cada llamada de modelo se convierte en un span GenAI de OpenTelemetry enviado a la puerta OTLP, almacenado con su entrada, salida, uso de tokens y llamadas a herramientas, y puntuado: captura que no depende de que el modelo llame a una herramienta. wrap_openai / wrap_anthropic en el cliente Python; wrapOpenAI, wrapAnthropic y irisMiddleware para el Vercel AI SDK en @iris-eval/sdk. Ambos aún no están publicados (la próxima versión iris-eval en PyPI; @iris-eval/sdk se compila desde la fuente hasta su primer lanzamiento npm). Los streams, los helpers de stream de los SDK y las llamadas a herramientas están cubiertos, el cliente original no se modifica, y que Iris esté caído nunca rompe una llamada — packages/sdk/README.md, packages/python/README.md.

Puntúa cada ejecución de LangChain y LangGraph

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

Cada ejecución de nivel superior se convierte en una traza (la ejecución, sus llamadas de modelo, sus llamadas a herramientas y sus nodos de grafo como spans GenAI) con su entrada, salida, llamadas a herramientas, uso de tokens y un veredicto. Python en el cliente (próxima versión, aún no publicada en PyPI), JavaScript como @iris-eval/langchain (aún no publicado en npm). Ambos están probados en CI contra una aplicación LangGraph real con un modelo con guion; la exportación OpenTelemetry de LangSmith está probada de la misma manera — docs/otel-recipes.md.

Una puerta de CI, sin necesidad de servidor

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

O la GitHub Action (0.16.0), que falla el trabajo en los veredictos que nombres, escribe el recibo en el resumen del trabajo y lo publica como un comentario de pull request actualizado en su lugar: uses: iris-eval/mcp-server/.github/actions/gate@v0.19.0 con traces: traces.ndjson — docs/ci-gate.md. Una cuarta puerta (0.15.0): POST /v1/traces en el puerto del panel toma el OTLP/HTTP JSON o protobuf que tu instrumentación de OpenTelemetry ya emite (el exportador del SDK de Python solo habla protobuf, así que esta también es la puerta de Python), y cada traza OTLP se convierte en una traza de Iris con sus spans — docs/otel-integration.md; una receta por framework (Pydantic AI, Google ADK, LangGraph vía LangSmith, CrewAI, el SDK de OpenAI Agents en Python y JavaScript, LlamaIndex, AutoGen, Microsoft Agent Framework, Semantic Kernel, el SDK de Vercel AI y Mastra), cada una probada por un fixture, en docs/otel-recipes.md. ingest lee una traza JSON (o NDJSON, una por línea) desde stdin o un archivo, la almacena, la evalúa bajo exactamente las reglas que ejecuta evaluate_output, imprime una línea JSON por traza con el veredicto y su base, y sale con 1 cuando un veredicto coincide con --fail-on. --dataset <id|label> restringe esa puerta a las claves de caso en un dataset (POST /api/v1/datasets promueve las claves de caso de una ejecución a uno), de modo que un trabajo falla solo en los casos que elegiste. La receta completa, los códigos de salida y las ocho bases están en docs/ci-gate.md.

Escribe una regla como código

eval.plugins en config.json carga reglas que escribiste — un módulo ES cuya exportación por defecto es { name, kind, mechanism, version, needs, evaluate(ctx) } — fijado por el sha256 del archivo, de modo que un archivo que cambió desde que lo fijaste rechaza el arranque en lugar de ejecutarse. Un plugin cargado se dispara como uno integrado y se muestra en list_rules bajo plugins. El contrato, la receta de hash y lo que un plugin puede devolver: docs/plugins.md.

Usa el motor en tu propio proceso

El motor de evaluación es importable — sin servidor, sin base de datos, sin 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

El mismo motor, las mismas reglas y el mismo compositor que ejecuta el servidor; builtInRules(), createCustomRule(), compose() y los lectores de precisión publicada se exportan junto a él.

Un cliente tipado para la ruta 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

Un solo cuerpo en cada puerta: es lo que aceptan log_trace y iris-eval ingest. Una negativa lanza IrisClientError con la propia frase y estado del servidor. Ambos subcaminos se verifican desde un tarball empaquetado en cada compilación.

Verifica tu instalación

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 primero crea tu hogar de Iris si falta y verifica que sea escribible (salida 1, nombrando la ruta, si no lo es), informa dónde está el índice de búsqueda de tu base de datos (completo, cuántas trazas ha indexado una compilación en segundo plano hasta ahora, o sin FTS5 en este SQLite), lee el esquema de tu base de datos (salida 1, con la solución, cuando esta versión o un cliente MCP fijado a una versión anterior no puede abrirla), luego ejecuta sus verificaciones — ida y vuelta de almacenamiento, un SSN plantado y una inyección plantada detectados por las reglas de seguridad, arranque del panel, la protección contra rebinding de DNS — dentro de un hogar temporal aislado. Tu base de datos real solo se lee, nunca se cambia. Todo lo que Iris escribe vive bajo un directorio, tu hogar de Iris: ~/.iris por defecto (%USERPROFILE%\.iris en Windows), o donde apunte IRIS_HOME. Ahí es donde viven iris.db, config.json, custom-rules.json, audit.log, preferences.json y los archivos de demostración; apunta IRIS_HOME a un directorio de prueba para probar Iris sin tocar tus datos reales.

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"]

Otros Métodos de Instalación

# 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

Consejo: La instalación global (npm install -g) almacena trazas de forma persistente en ~/.iris/iris.db. Con npx, las trazas persisten en la misma ubicación, pero el arranque es más lento debido a la resolución de paquetes.

Lo Que Obtienes

Hacia dónde va esto a continuación: el mapa de capacidades — cada pregunta que se le puede hacer a Iris sobre cada tema, con lo que tiene y lo que le falta — y las tres pistas.

Medido, no afirmado

Toda regla integrada tiene una precisión, recuperación y F1 publicadas con intervalos de confianza del 95%, medidas sobre un corpus etiquetado que vive en este repositorio (proof/corpus/) y se regenera con un solo comando — npm run proof — sin conexión, sin clave y sin modelo en el bucle. Esos números son de dos tipos distintos, y la página nunca los suma: algunas reglas se miden contra etiquetas que un modelo dio al leer la falla en sí, lo que mide la detección; el resto se comprueban contra su propia definición documentada, aplicada de forma independiente, lo que muestra que el código implementa su fórmula y no dice nada sobre si la fórmula detecta la falla. proof/RESULTS.md y la página de pruebas marcan cada regla. CI vuelve a ejecutar la medición en cada pull request y falla si los números confirmados difieren de lo que produce el código, por lo que una regla no puede cambiar sin que sus números cambien con ella. Los números están en iris-eval.com/proof y en proof/RESULTS.md; cómo se creó el corpus, qué no es y cómo leer un intervalo están en docs/proof.md. El corpus es sintético y etiquetado por modelo — una etiqueta humana ciega está pendiente, y la página lo dice; node proof/blind-sample.mjs extrae la muestra reproducible que lo resolverá.

Herramientas MCP

Iris registra doce herramientas que cualquier agente compatible con MCP puede invocar — ciclo de vida de trazas y reglas, comparación entre ejecuciones, LLM como juez y verificación de citas semánticas:

• log_trace — Registra una ejecución de agente con tramos, llamadas a herramientas, uso de tokens y costo; pasa evaluate: true para puntuarla en la misma llamada
• evaluate_output — Puntúa la calidad de la salida según reglas de completitud, relevancia, seguridad y costo (heurísticas, deterministas, gratuitas)
• get_traces — Consulta trazas almacenadas con filtrado, paginación y soporte de rango temporal, y encuentra la ejecución donde el agente dijo algo con q: búsqueda de texto completo sobre entrada, salida, valores de llamadas a herramientas y metadatos, clasificada, con las palabras coincidentes marcadas
• list_rules — Enumera las reglas de evaluación personalizadas desplegadas (solo lectura)
• deploy_rule — Registra una nueva regla de evaluación personalizada para que se active en cada evaluate_output de esa categoría
• delete_rule — Elimina una regla personalizada desplegada (destructiva, idempotente)
• delete_trace — Elimina una sola traza almacenada por ID (destructiva, limitada al inquilino)
• evaluate_with_llm_judge — Evaluación semántica mediante LLM (Anthropic u OpenAI). Siete plantillas: precisión, utilidad, seguridad, corrección, fidelidad, tarea_completada, relevancia. Con límite de costo, precio por evaluación divulgado. Trae tu propia clave API (IRIS_ANTHROPIC_API_KEY o IRIS_OPENAI_API_KEY) — Iris no hace proxy ni retransmite llamadas LLM.
• verify_citations — Extrae citas de la salida (numeradas, autor-año, URLs, DOIs), obtiene las fuentes detrás de un resolvedor protegido contra SSRF y con lista de dominios permitidos, y usa un juez LLM para comprobar si cada fuente respalda realmente la afirmación citada. HTTP saliente opcional. Mismo requisito de traer tu propia clave que evaluate_with_llm_judge.
• compare_runs — ¿Un cambio empeoró al agente? Compara dos ejecuciones de evaluaciones almacenadas: una prueba exacta pareada cuando las ejecuciones comparten claves de caso, un intervalo sobre la diferencia en caso contrario, un honesto "no se puede determinar" con el número de casos que haría falta, o "equivalente dentro de un margen". Cada regla lleva su propia prueba unilateral, corregida en conjunto (Benjamini–Hochberg) para que veinte reglas no puedan fabricar una regresión
• compare_traces — ¿Con qué fiabilidad responde el agente la misma pregunta? Tasas de aprobación por caso con intervalos, casos inestables primero, y una tasa general que respeta las repeticiones
• evaluate_runs — Vuelve a puntuar cada traza de una ejecución bajo las reglas actuales en una nueva ejecución, para que un cambio de reglas nunca se lea como un cambio del agente

Habilita el juez LLM (opcional; las reglas deterministas nunca lo necesitan)

1. Obtén una clave API de Anthropic u OpenAI.
2. Ponla en el entorno del proceso que ejecuta Iris, no solo en tu shell. Claude Code, Claude Desktop, Cursor y la mayoría de clientes MCP: el bloque "env" de la entrada iris-eval en tu configuración MCP — "iris-eval": { "command": "npx", "args": ["-y", "@iris-eval/mcp-server"], "env": { "IRIS_ANTHROPIC_API_KEY": "sk-ant-..." } } (IRIS_OPENAI_API_KEY para una clave de OpenAI). Docker: -e IRIS_ANTHROPIC_API_KEY=... en el comando run. HTTP o CI: expórtala antes de iniciar iris-eval.
3. Reinicia la sesión MCP. Un proceso en ejecución nunca ve una variable establecida después de que comenzó.
4. Confirma desde tu cliente: lee iris://capabilities — judge.enabled debe ser true allí. Una clave exportada en tu shell no se pasa al proceso que tu cliente inicia a menos que su configuración la liste. En una máquina, npx @iris-eval/mcp-server --self-test imprime la línea del juez para ese shell, y GET /api/v1/health informa judge.enabled en un panel en ejecución.
5. Protección de gasto: cada llamada está limitada por IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL (predeterminado 0.25 USD) y se rechaza antes de cualquier gasto si el peor caso lo excediera. Iris llama al proveedor directamente con tu clave y nunca la hace proxy.
6. Opcional: establece IRIS_RELEVANCE_JUDGE_MODEL a un ID de modelo con precio (claude-haiku-4-5, por ejemplo) para que answers_the_ask pida al juez si cada respuesta aborda su pregunta, y falle una fuera de tema. Eso es una llamada al juez por cada evaluación que lleva una entrada, con tu clave y bajo el límite anterior; la clave sola nunca lo activa. Cada llamada envía esa entrada y salida al proveedor del modelo, con los indicadores de datos personales y credenciales no_pii reemplazados primero (IRIS_RELEVANCE_JUDGE_REDACT=off los envía tal cual). Gasta como máximo IRIS_RELEVANCE_JUDGE_DAILY_BUDGET_USD por día UTC (predeterminado 1 USD) y hace como máximo IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST llamadas por solicitud (predeterminado 20); superado cualquiera de los dos, answers_the_ask lee la pregunta léxicamente y dice por qué.

Cuando IRIS_OTEL_ENDPOINT está configurado, las llamadas a log_trace también emiten una exportación JSON OTLP/HTTP de mejor esfuerzo a cualquier colector OpenTelemetry (Jaeger, Grafana Tempo, Datadog OTLP, Honeycomb, etc.). Consulta docs/otel-integration.md.

Cómo se decide passed

evaluate_output devuelve tanto un score como un indicador passed — responden preguntas diferentes:

• score (0..1) es el promedio ponderado entre las reglas que se ejecutaron — un gradiente de calidad.
• passed es el veredicto de lanzar/no lanzar, y la puntuación nunca se consulta para él. Un compositor lee cada regla según el tipo de afirmación que hace: una política que configuraste actúa como compuerta; un detector crítico veta; una comprobación crítica que se pidió y no pudo responder hace que el veredicto sea desconocido (passed: false) en lugar de limpio; cada detector restante se combina en una probabilidad de que la salida sea mala, ponderada contra la relación de pérdida que indicas en eval.falsePassCost (predeterminado 1, por lo que el corte es 0.5). verdict.basis nombra la capa que decidió y verdict.by las reglas, y verdict.also enumera cada capa posterior que también lo habría decidido; interpretations[] dice por qué una regla que falló no decidió y qué ajuste lo cambiaría, y nombra cualquier pregunta que no se juzgó y la entrada que permitiría hacerlo.

Las violaciones de seguridad genuinas fallan de forma dura. Por defecto, no_pii, no_injection_patterns y no_blocklist_words son reglas críticas: si una falla, la evaluación informa passed: false sin importar cuán bien puntuaron las demás reglas, y la respuesta nombra a los culpables en critical_failures. Un SSN filtrado no se puede promediar. Qué reglas integradas son críticas es un ajuste de despliegue (eval.criticalRules / eval.nonCriticalRules); cada resultado de regla lleva el indicador critical efectivo y criticalSource, y list_rules informa el roster que aplica este servidor. Las reglas personalizadas desplegadas con severity: "high" o "critical" fallan de forma dura igual; las severidades low/medium solo afectan la puntuación. Un límite a conocer, expresado igual en todas las superficies: una regla crítica que se omitió (contexto faltante, una definición rota o un regex eliminado por el presupuesto del sandbox) no ha juzgado la salida y no veta — cada una de esas reglas se nombra en critical_skipped. Una compuerta que debe fallar cerrada trata un critical_skipped no vacío como desconocido, no limpio, y puede tratar cualquier omisión budgetExceeded en rule_results de la misma manera.

Para compuertas de CI: si omites eval_type, se ejecuta cada paquete — completitud, relevancia, seguridad, costo y cualquier regla personalizada — y la respuesta dice eval_type: "all" con un note de que se ejecutó el predeterminado, más un mapa categories por paquete. Un paquete sin nada que juzgar (costo sin cost_usd, relevancia sin input) informa passed: null allí — no evaluado, no fallando — y nunca cuenta para el veredicto. La respuesta siempre repite el eval_type que se ejecutó, para que tu compuerta pueda verificar la cobertura; clave en passed para el veredicto y nombra un paquete solo cuando quieras una ejecución más limitada.

Creación de una regla personalizada

Dos formas de añadir una regla. Las reglas en línea viajan en una sola llamada a evaluate_output (custom_rules, hasta 10 por llamada); se activan junto con el paquete eval_type que elijas, o solas con eval_type: "custom". Las reglas desplegadas se registran una vez con deploy_rule, persisten en custom-rules.json bajo tu hogar de Iris y se activan en cada futuro evaluate_output de su evalType. La definición tiene la misma forma en ambos casos:

deploy_rule envuelve la definición con name, un description opcional, evalType (completeness · relevance · safety · cost · custom) y severity. La severidad dice qué significa un fallo: low/medium solo bajan la puntuación; high/critical fallan la evaluación de forma dura — passed: false, la regla nombrada en critical_failures — diga lo que diga la puntuación ponderada. Una regla que se omite (una regla cost_threshold sin cost_usd, o un regex eliminado por el presupuesto del sandbox de 100 ms) no ha juzgado la salida y se lista en critical_skipped en su lugar. Despliega una regla crítica que prohíba nombres de host internos en cualquier cosa que diga el agente:

{
  "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" }
  }
}

La respuesta es la regla persistida — guarda el id para delete_rule:

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

Desde el siguiente evaluate_output con eval_type: "safety", una salida que mencione db-primary.internal.example vuelve passed: false con critical_failures: ["no_internal_hostnames"] — incluso aunque las cinco reglas de seguridad integradas hayan pasado y la puntuación ponderada sea 0.895. Los patrones de regex deben pasar una comprobación de ReDoS en el despliegue y siempre se ejecutan en un trabajador sandbox bajo un plazo duro de 100 ms. list_rules muestra lo que está desplegado; el compositor de reglas del panel construye la misma forma desde un fallo en el que hiciste clic. Referencia completa, puntuación por tipo y ejemplos trabajados: docs/custom-rules.md.

Esquemas completos de herramientas y configuración: iris-eval.com

Funciones alojadas

Iris se ejecuta completamente en tu máquina hoy, y todo lo que hace es gratuito y con licencia MIT, sin límites y sin cuenta. Almacenamiento alojado, historial de equipo compartido y alertas están en consideración, no en construcción. No hay precios ni nada que comprar. Si el historial compartido te resultara útil, la lista de espera es cómo descubrimos si vale la pena construirlo; no te compromete a nada.

Dos compromisos se mantienen en cualquier caso: nada que hoy sea gratuito pasará detrás de un muro de pago, y no se reclamará ninguna certificación de cumplimiento antes de obtenerla.

Ejemplos

• Configuración de Claude Desktop — Configuración de MCP para modos stdio y HTTP
• TypeScript — Cliente del SDK de MCP — Conectar e invocar herramientas
• Transporte HTTP (TS + Python) — Código de cliente completo para integración estilo REST
• Un agente LangGraph, evaluado ejecución por ejecución (Python) — IrisCallbackHandler en los callbacks del grafo; CI ejecuta el mismo grafo con un modelo con guion
• Un equipo CrewAI sobre OpenTelemetry (Python) — El instrumentador OpenInference directo a la puerta OTLP de Iris, la receta CrewAI como script
• Un agente del SDK de OpenAI Agents sobre OpenTelemetry (Python) y (JavaScript), y un agente LlamaIndex — cada receta como el script que CI ejecuta contra un servidor Iris real

Comunidad

• Problemas de GitHub — Informes de errores y solicitudes de funciones
• Discusiones de GitHub — Preguntas e ideas
• Guía de contribución — Cómo contribuir
• Ingesta HTTP — Captura determinista de trazas mediante POST /api/v1/traces
• Mapa de capacidades — Cada pregunta que se le puede hacer a Iris y lo que le falta
• Política de versionado — Qué promete cada número de versión y qué debe ser cierto antes de 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"

Si Iris te resulta útil, considera darle una estrella al repositorio — ayuda a que otros lo encuentren.

Licencia MIT.