Iris

Iris — berhenti mengirim agen berdasarkan firasat

Iris menilai setiap eksekusi agen untuk kualitas, keamanan, dan biaya — di mesin Anda, tanpa SDK dan tanpa akun. Sebagian besar proyek agen memeriksa kualitas dengan menjalankan beberapa prompt yang diingat dan melihat sekilas keluarannya. Iris menggantinya dengan angka yang dapat Anda audit: eksekusi agen Anda tersimpan dalam database SQLite di disk Anda, 25 aturan bawaan menilainya secara deterministik — PII, injeksi prompt, penanda halusinasi, ambang biaya, dan panggilan alat agen itu sendiri — gratis, tanpa panggilan LLM, dan hakim LLM opsional dengan batas biaya keras per evaluasi menangani pertanyaan semantik. Setiap aturan dapat diperiksa dan diedit, karena hakim yang tidak dapat Anda audit hanyalah firasat dengan angka di atasnya. Lisensi MIT, tanpa telemetri. Tidak ada yang meninggalkan mesin Anda kecuali Anda mengaktifkan salah satu dari ini: endpoint OpenTelemetry (IRIS_OTEL_ENDPOINT), yang mengekspor jejak ke kolektor yang Anda sebutkan; hakim LLM dengan kunci Anda sendiri, yang mengirim teks yang dinilainya ke penyedia tersebut, dan pemeriksaan kutipannya mengambil halaman yang dikutip oleh keluaran; atau webhook, yang mengirim id, vonis, dan nama aturan, tidak pernah teksnya, ke alamat yang Anda tetapkan.

Membutuhkan Node.js 22.13 atau lebih baru. Periksa dengan node --version.

_{Database demo, direkam oleh scripts/demo-media.mts; sumbernya adalah demo.mp4. Gambar diam: dashboard-overview.png.}

Kegagalan di layar dalam 60 detik

Tanpa pengkabelan agen, tanpa konfigurasi — satu perintah:

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

Ini mengisi database demo — lima agen kecil, dua minggu eksekusi, setiap vonis dari mesin itu sendiri — dan menyajikan dasbor terhadapnya di http://localhost:6920 (browser Anda terbuka otomatis pada eksekusi pertama). Dasbor mendarat di Kegagalan: apa yang gagal, terburuk dan terbaru lebih dulu, setiap kartu menyebutkan aturan dan buktinya. Layak diklik — kebocoran PII yang tertangkap oleh aturan keamanan, arahan tersembunyi di posting forum yang dipatuhi perangkum, angka yang tidak pernah disebutkan dokumen sumber, dua eksekusi pada dua belas pertanyaan yang sama dibandingkan dengan interval (Eksekusi), aturan kustom yang diterapkan dan yang dijeda dengan baris auditnya, dan skor hakim LLM yang gagal dengan alasannya.

Data demo hidup di database sendiri (demo.db di direktori rumah Iris Anda — ~/.iris di macOS/Linux, %USERPROFILE%\.iris di Windows) dan tidak pernah bercampur dengan jejak asli Anda. Hapus semuanya dengan satu perintah:

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

Hubungkan agen Anda sendiri

Pertama, buktikan instalasi berfungsi di mesin ini — berjalan offline dan tidak membuka apa pun milik Anda:

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

Lalu tambahkan Iris ke klien MCP Anda. Satu perintah menulis file konfigurasi klien itu sendiri, menjaga setiap server lain di dalamnya, dan mengunci versi yang Anda jalankan:

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

Kliennya: claude-code, claude-desktop, cursor, windsurf, continue, vscode, cline, zed, codex, gemini. install --list menampilkan yang ditemukan di mesin ini, Iris yang dijalankan masing-masing dan file yang dibacanya; install <client> --uninstall menghapus Iris lagi. Setiap klien berbagi satu database, jadi setelah peningkatan, pindahkan semuanya sekaligus dengan install --upgrade (Memperbarui). Mulai ulang klien untuk memuatnya.

Claude Desktop: satu klik. Setiap rilis dari 0.20.0 ke atas melampirkan iris-eval.mcpb, sebuah MCP Bundle: unduh yang terbaru, buka, dan Claude Desktop menampilkan dialog instalasi. Tidak ada yang wajib di dalamnya — kunci Anthropic atau OpenAI untuk hakim LLM bersifat opsional, dan dasbor adalah sakelar yang mulai mati. Bundel tersebut berisi paket npm dan dependensinya, jadi tidak ada yang perlu diinstal lagi: Claude Desktop menjalankannya di bawah Node yang disertakannya saat Node tersebut 22.13 atau lebih baru (Claude Desktop 1.1.6679 menyertakan 24.13), dan Iris menyimpan jejak dengan SQLite bawaan Node, di ~/.iris yang sama yang digunakan instalasi lain. Catatan rilis menunjukkan cara memverifikasi tanda tangan dan bukti pembangunannya.

Ini berjalan di klien MCP mana pun, dan setiap klien yang disebutnya memiliki baris dengan apa yang sebenarnya diperiksa. Terverifikasi di setiap eksekusi CI: Claude Code, Gemini CLI — klien asli memulai Iris dari konfigurasi yang ditulis penginstal dan melaporkan bahwa ia terhubung (claude mcp list, gemini mcp list), di Linux, macOS, dan Windows; plugin hook penangkap Claude Code juga digerakkan melalui skrip asli. Diklaim dari dokumentasi MCP masing-masing klien — penginstal menulis bentuk konfigurasi yang didokumentasikan klien, dan penulis itu diuji pada bentuknya; tidak ada seorang pun di sisi Iris yang melihatnya terhubung: Claude Desktop, Cursor, Devin Desktop (Windsurf), Continue, VS Code, Cline, Zed, OpenAI Codex CLI. Setiap baris dengan sumbernya dan tanggal dibacanya: https://iris-eval.com/clients. Secara manual sebagai gantinya, satu blok, termasuk dasbor:

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

Klien Anda mencantumkan dua belas alat Iris saat terhubung, dan dasbor melayani di http://localhost:6920. Sekarang tempel ini ke agen Anda:

Catat tugas terakhir itu ke Iris dan evaluasi keluarannya.

Jejak mendarat di dasbor dengan skornya. Lebih suka server MCP tanpa kepala? Hapus --dashboard dari argumen — Anda dapat membuka dasbor yang sama kapan saja dengan npx @iris-eval/mcp-server --dashboard.

Satu hal yang perlu diketahui di awal: alat MCP dipanggil saat model memutuskan untuk memanggilnya. Iris tidak mencegat agen Anda, jadi jejak dicatat saat agen Anda memintanya untuk mencatatnya — baik karena Anda menyuruhnya, atau karena kode Anda memanggil alat secara langsung. Minta agen Anda untuk "catat ini ke Iris dan evaluasi" dan ia akan melakukannya. Jika Anda ingin penangkapan yang tidak bergantung pada pilihan model, POST /api/v1/traces melakukan persis itu — kode Anda mengirim jejak melalui HTTP biasa, tanpa model dalam loop (lihat docs/http-ingest.md). CLI dan hook host di peta jalan akan menjadi klien tipis di atas endpoint yang sama.

Penangkapan melalui HTTP (tanpa model dalam loop)

Endpoint ingest hidup di port dasbor — 6920 secara default, bukan port transport MCP — dan hanya ada saat dasbor berjalan. Berikan --dashboard (atau atur IRIS_DASHBOARD=true); --transport http saja tidak memulainya, dan permintaan ke port transport mengembalikan 404. Dengan dasbor aktif, apa pun yang dapat mengirim permintaan HTTP dapat mencatat jejak — dan secara opsional menjalankan evaluasi deterministik dalam permintaan yang sama. GET /api/v1/capabilities di port yang sama mengatakan apa yang dapat dinilai server ini, apa yang dibutuhkan setiap aturan, status hakim dengan langkah-langkah yang mengaktifkannya, dan batasannya — objek yang sama yang dilayani sumber daya MCP iris://capabilities — sehingga pemanggil HTTP memiliki bingkai yang didapat klien MCP saat inisialisasi:

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

Mengembalikan 201 dengan trace_id yang tersimpan dan hasil evaluasi (dalam mode --demo endpoint menolak penulisan dengan 403, sehingga data demo tidak pernah bercampur dengan milik Anda). Endpoint menerima badan yang sama dengan alat log_trace dan berada di belakang tumpukan middleware yang sama dengan dasbor lainnya: ikatan loopback dan penjaga pengikatan ulang DNS secara default, plus autentikasi Bearer saat Anda menetapkannya. Dua fakta sederhana tentangnya: ia menerima penulisan tanpa autentikasi kecuali Iris dimulai dengan --api-key (atau IRIS_API_KEY) — ikatan loopback adalah yang menjaganya tetap di mesin Anda secara default, jadi tetapkan kunci sebelum mengikat di luar loopback; dan apa yang disimpannya adalah kata demi kata — input dan output mendarat di iris.db persis seperti yang dikirim, termasuk teks apa pun yang kemudian ditandai no_pii. Kontrak lengkap, referensi bidang, dan semantik kesalahan: docs/http-ingest.md.

Tangkap setiap giliran Claude Code (opsional)

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

Plugin kedua yang diinstal terpisah: tiga hook mencatat prompt setiap giliran, panggilan alat, dan jawaban akhir dan menyerahkannya ke iris-eval ingest, terlepas, dengan rentang kritis disunting dalam teks evaluasi yang disimpan — penangkapan yang tidak bergantung pada model yang memutuskan untuk memanggil alat. Ia tidak pernah mencatat giliran yang sudah dicatat model, tidak pernah mencetak, tidak pernah memblokir, tidak pernah mengirim apa pun ke mana pun. Menginstal iris-eval saja tidak mengubah apa pun tentang loop giliran Anda. Batasan dan penghapusan: 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": []}

Klien tipis di atas API HTTP server 0.16.0 dan yang lebih baru, diberi versi sendiri — iris_eval.__version__ dan halaman PyPI membawa nomornya, yang bukan nomor server: log_trace(), evaluate_output(), get_traces(), get_trace(), health(), capabilities(), sinkron dan asinkron, jawaban bertipe, kalimat server sendiri tentang penolakan — dan plugin pytest: perlengkapan iris dan assert_iris(output, expect="pass") yang menegaskan status vonis. packages/python/README.md.

Rekam setiap panggilan OpenAI dan 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' });

Bungkus klien penyedia sekali dan setiap panggilan model menjadi satu span OpenTelemetry GenAI yang dikirim ke pintu OTLP, disimpan dengan input, output, penggunaan token, dan panggilan alatnya, dan dinilai: penangkapan yang tidak bergantung pada model yang memanggil alat. wrap_openai / wrap_anthropic di klien Python; wrapOpenAI, wrapAnthropic dan irisMiddleware untuk Vercel AI SDK di @iris-eval/sdk. Keduanya belum diterbitkan (rilis iris-eval berikutnya di PyPI; @iris-eval/sdk dibangun dari sumber hingga rilis npm pertamanya). Streaming, pembantu streaming SDK, dan panggilan alat tercakup, klien asli tidak diubah, dan Iris yang mati tidak pernah merusak panggilan — packages/sdk/README.md, packages/python/README.md.

Nilai setiap eksekusi LangChain dan LangGraph

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

Setiap eksekusi tingkat atas menjadi satu jejak (eksekusi, panggilan modelnya, panggilan alatnya, dan node grafnya sebagai span GenAI) dengan input, output, panggilan alat, penggunaan token, dan vonis. Python di klien (rilis berikutnya, belum diterbitkan ke PyPI), JavaScript sebagai @iris-eval/langchain (belum diterbitkan ke npm). Keduanya terbukti di CI terhadap aplikasi LangGraph nyata dengan model berskrip; ekspor OpenTelemetry LangSmith sendiri terbukti dengan cara yang sama — docs/otel-recipes.md.

Gerbang CI, tanpa server yang diperlukan

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

Atau GitHub Action (0.16.0), yang menggagalkan pekerjaan pada vonis yang Anda sebutkan, menulis tanda terima ke ringkasan pekerjaan dan mempostingnya sebagai satu komentar permintaan tarik yang diperbarui di tempat: uses: iris-eval/mcp-server/.github/actions/gate@v0.19.0 dengan traces: traces.ndjson — docs/ci-gate.md. Pintu keempat (0.15.0): POST /v1/traces pada port dasbor menerima OTLP/HTTP JSON atau protobuf yang sudah dihasilkan oleh instrumentasi OpenTelemetry Anda (eksportir Python SDK hanya berbicara protobuf, jadi ini juga pintu untuk Python), dan setiap trace OTLP menjadi trace Iris dengan span-span-nya — docs/otel-integration.md; satu resep per kerangka kerja (Pydantic AI, Google ADK, LangGraph via LangSmith, CrewAI, OpenAI Agents SDK dalam Python dan JavaScript, LlamaIndex, AutoGen, Microsoft Agent Framework, Semantic Kernel, Vercel AI SDK dan Mastra), masing-masing dibuktikan oleh fixture, di docs/otel-recipes.md. ingest membaca satu trace JSON (atau NDJSON, satu per baris) dari stdin atau file, menyimpannya, mengevaluasinya dengan aturan yang persis sama seperti yang dijalankan evaluate_output, mencetak satu baris JSON per trace dengan vonis dan dasarnya, dan keluar dengan kode 1 ketika vonis cocok dengan --fail-on. --dataset <id|label> membatasi gerbang tersebut hanya pada kunci kasus dalam sebuah dataset (POST /api/v1/datasets mempromosikan kunci kasus dari sebuah run menjadi satu), sehingga sebuah pekerjaan hanya gagal pada kasus yang Anda pilih. Resep lengkap, kode keluar, dan delapan dasar tersebut ada di docs/ci-gate.md.

Menulis aturan sebagai kode

eval.plugins di config.json memuat aturan yang Anda tulis — sebuah modul ES yang ekspor default-nya adalah { name, kind, mechanism, version, needs, evaluate(ctx) } — yang dipatok oleh sha256 dari file tersebut, sehingga file yang berubah sejak Anda mematoknya akan menolak untuk memulai daripada dijalankan. Plugin yang dimuat akan menyala seperti bawaan dan tampil di list_rules di bawah plugins. Kontrak, resep hash, dan apa yang boleh dikembalikan oleh plugin: docs/plugins.md.

Menggunakan mesin di proses Anda sendiri

Mesin evaluasi dapat diimpor — tanpa server, tanpa database, tanpa model:

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

Mesin yang sama, aturan yang sama, dan komposer yang sama yang dijalankan server; builtInRules(), createCustomRule(), compose() dan pembaca akurasi yang dipublikasikan diekspor di sampingnya.

Klien bertipe untuk rute 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

Satu body di setiap pintu: itulah yang diterima oleh log_trace dan iris-eval ingest. Penolakan melempar IrisClientError dengan kalimat dan status dari server itu sendiri. Kedua subpath diperiksa dari tarball yang dikemas pada setiap build.

Verifikasi instalasi Anda

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 pertama-tama membuat home Iris Anda jika belum ada dan memeriksa apakah dapat ditulis (keluar dengan kode 1, menyebutkan jalurnya, jika tidak), melaporkan di mana indeks pencarian database Anda berada (utuh, berapa banyak trace yang telah diindeks oleh build latar belakang sejauh ini, atau tanpa FTS5 pada SQLite ini), membaca skema database Anda (keluar dengan kode 1, beserta perbaikannya, ketika versi ini atau klien MCP yang dipatok ke rilis lama tidak dapat membukanya), lalu menjalankan pemeriksaannya — penyimpanan bolak-balik, SSN yang ditanam dan injeksi yang ditanam yang tertangkap oleh aturan keamanan, boot dasbor, penjaga anti-DNS-rebinding — di dalam home sementara yang terisolasi. Database asli Anda hanya dibaca, tidak pernah diubah. Semua yang ditulis Iris berada di satu direktori, home Iris Anda: ~/.iris secara default (%USERPROFILE%\.iris di Windows), atau di mana pun IRIS_HOME menunjuk. Di situlah iris.db, config.json, custom-rules.json, audit.log, preferences.json dan file demo berada; arahkan IRIS_HOME ke direktori sementara untuk mencoba Iris tanpa menyentuh data asli Anda.

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

Metode Instalasi Lainnya

# 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

Tip: Instalasi global (npm install -g) menyimpan trace secara persisten di ~/.iris/iris.db. Dengan npx, trace bertahan di lokasi yang sama, tetapi startup lebih lambat karena resolusi paket.

Apa yang Anda Dapatkan

Ke mana ini berlanjut: peta kemampuan — setiap pertanyaan yang dapat diajukan ke Iris tentang setiap subjek, dengan apa yang dimilikinya dan apa yang kurang — dan tiga jalur.

Terukur, bukan diklaim

Setiap aturan bawaan memiliki presisi, recall, dan F1 yang dipublikasikan dengan interval kepercayaan 95%, diukur pada korpus berlabel yang berada di repositori ini (proof/corpus/) dan dibuat ulang dengan satu perintah — npm run proof — secara offline, tanpa kunci dan tanpa model dalam prosesnya. Angka-angka tersebut terdiri dari dua jenis yang berbeda, dan halaman tidak pernah menjumlahkannya: beberapa aturan diukur terhadap label yang diberikan model dengan membaca kegagalan itu sendiri, yang mengukur deteksi; sisanya diperiksa terhadap definisi terdokumentasi mereka sendiri, yang diterapkan secara independen, yang menunjukkan kode mengimplementasikan formulanya dan tidak mengatakan apa pun tentang apakah formula tersebut menangkap kegagalan. proof/RESULTS.md dan halaman bukti menandai setiap aturan. CI menjalankan ulang pengukuran pada setiap pull request dan gagal jika angka yang dikomit berbeda dari yang dihasilkan kode, sehingga sebuah aturan tidak dapat berubah tanpa angka-angkanya ikut berubah. Angka-angka tersebut ada di iris-eval.com/proof dan di proof/RESULTS.md; bagaimana korpus dibuat, apa yang bukan, dan cara membaca interval ada di docs/proof.md. Korpus bersifat sintetis dan berlabel model — label buta manusia masih tertunda, dan halaman menyatakannya; node proof/blind-sample.mjs menarik sampel yang dapat direproduksi yang akan menyelesaikannya.

Alat MCP

Iris mendaftarkan dua belas alat yang dapat dipanggil oleh agen yang kompatibel dengan MCP — siklus hidup jejak dan aturan, perbandingan antar proses, LLM-sebagai-juri, dan verifikasi kutipan semantik:

• log_trace — Mencatat eksekusi agen dengan span, panggilan alat, penggunaan token, dan biaya; berikan evaluate: true untuk menilainya dalam panggilan yang sama
• evaluate_output — Menilai kualitas keluaran terhadap aturan kelengkapan, relevansi, keamanan, dan biaya (heuristik, deterministik, gratis)
• get_traces — Mengkueri jejak tersimpan dengan dukungan pemfilteran, paginasi, dan rentang waktu, serta menemukan proses di mana agen mengatakan sesuatu dengan q: pencarian teks lengkap atas input, output, nilai panggilan alat, dan metadata, diperingkat, dengan kata yang cocok ditandai
• list_rules — Mendaftarkan aturan evaluasi kustom yang diterapkan (hanya baca)
• deploy_rule — Mendaftarkan aturan evaluasi kustom baru sehingga aturan tersebut aktif pada setiap evaluate_output dari kategori tersebut
• delete_rule — Menghapus aturan kustom yang diterapkan (destruktif, idempoten)
• delete_trace — Menghapus satu jejak tersimpan berdasarkan ID (destruktif, terbatas pada penyewa)
• evaluate_with_llm_judge — Evaluasi semantik melalui LLM (Anthropic atau OpenAI). Tujuh templat: akurasi, kebermanfaatan, keamanan, kebenaran, kesetiaan, tugas_selesai, relevansi. Berbatas biaya, harga per evaluasi diungkapkan. Bawa kunci API Anda sendiri (IRIS_ANTHROPIC_API_KEY atau IRIS_OPENAI_API_KEY) — Iris tidak memproksi atau meneruskan panggilan LLM.
• verify_citations — Mengekstrak kutipan dari keluaran (bernomor, penulis-tahun, URL, DOI), mengambil sumber di balik resolver yang dilindungi SSRF + daftar izin domain, dan menggunakan juri LLM untuk memeriksa apakah setiap sumber benar-benar mendukung klaim yang dikutip. HTTP keluar opsional. Persyaratan BYOK yang sama dengan evaluate_with_llm_judge.
• compare_runs — Apakah perubahan membuat agen lebih buruk? Membandingkan dua proses evaluasi tersimpan: uji eksak berpasangan ketika proses berbagi kunci kasus, interval pada selisih jika tidak, "tidak dapat mengatakan" yang jujur dengan jumlah kasus yang diperlukan, atau "setara dalam margin". Setiap aturan membawa uji satu sisi sendiri, dikoreksi bersama (Benjamini–Hochberg) sehingga dua puluh aturan tidak dapat memproduksi regresi
• compare_traces — Seberapa andal agen menjawab pertanyaan yang sama? Tingkat kelulusan per kasus dengan interval, kasus flaky terlebih dahulu, dan tingkat keseluruhan yang menghormati pengulangan
• evaluate_runs — Menilai ulang setiap jejak dalam proses di bawah aturan hari ini ke dalam proses baru, sehingga perubahan aturan tidak pernah dibaca sebagai perubahan agen

Aktifkan juri LLM (opsional; aturan deterministik tidak pernah membutuhkannya)

1. Dapatkan kunci API dari Anthropic atau OpenAI.
2. Letakkan di lingkungan proses yang menjalankan Iris, bukan hanya shell Anda. Claude Code, Claude Desktop, Cursor, dan sebagian besar klien MCP: blok "env" dari entri iris-eval di konfigurasi MCP Anda — "iris-eval": { "command": "npx", "args": ["-y", "@iris-eval/mcp-server"], "env": { "IRIS_ANTHROPIC_API_KEY": "sk-ant-..." } } (IRIS_OPENAI_API_KEY untuk kunci OpenAI). Docker: -e IRIS_ANTHROPIC_API_KEY=... pada perintah run. HTTP atau CI: ekspor sebelum memulai iris-eval.
3. Mulai ulang sesi MCP. Proses yang berjalan tidak pernah melihat variabel yang diatur setelah dimulai.
4. Konfirmasi dari dalam klien Anda: baca iris://capabilities — judge.enabled harus true di sana. Kunci yang diekspor di shell Anda tidak diteruskan ke proses yang dihasilkan klien Anda kecuali konfigurasinya mencantumkannya. Di mesin, npx @iris-eval/mcp-server --self-test mencetak baris juri untuk shell tersebut, dan GET /api/v1/health melaporkan judge.enabled pada dasbor yang berjalan.
5. Pengaman pengeluaran: setiap panggilan dibatasi oleh IRIS_LLM_JUDGE_MAX_COST_USD_PER_EVAL (default 0,25 USD) dan ditolak sebelum pengeluaran apa pun jika kasus terburuk akan melebihi batas. Iris memanggil penyedia secara langsung dengan kunci Anda dan tidak pernah memproksinya.
6. Opsional: atur IRIS_RELEVANCE_JUDGE_MODEL ke id model berharga (claude-haiku-4-5, misalnya) agar answers_the_ask meminta juri memeriksa apakah setiap jawaban menangani pertanyaannya, dan gagalkan yang di luar topik. Itu satu panggilan juri per evaluasi yang membawa input, pada kunci Anda dan di bawah batas di atas; kunci saja tidak pernah mengaktifkannya. Setiap panggilan mengirim input dan output tersebut ke penyedia model, dengan flag no_pii untuk data pribadi dan kredensial diganti terlebih dahulu (IRIS_RELEVANCE_JUDGE_REDACT=off mengirimnya apa adanya). Ini menghabiskan paling banyak IRIS_RELEVANCE_JUDGE_DAILY_BUDGET_USD per hari UTC (default 1 USD) dan membuat paling banyak IRIS_RELEVANCE_JUDGE_MAX_CALLS_PER_REQUEST panggilan per permintaan (default 20); melewati salah satunya, answers_the_ask membaca pertanyaan secara leksikal dan menjelaskan alasannya.

Ketika IRIS_OTEL_ENDPOINT dikonfigurasi, panggilan log_trace juga mengeluarkan ekspor JSON OTLP/HTTP upaya terbaik ke kolektor OpenTelemetry apa pun (Jaeger, Grafana Tempo, Datadog OTLP, Honeycomb, dll.). Lihat docs/otel-integration.md.

Bagaimana passed diputuskan

evaluate_output mengembalikan baik score dan flag passed — keduanya menjawab pertanyaan yang berbeda:

• score (0..1) adalah rata-rata tertimbang di seluruh aturan yang berjalan — gradien kualitas.
• passed adalah vonis kirim/jangan-kirim, dan skor tidak pernah dikonsultasikan untuk itu. Seorang komposer membaca setiap aturan berdasarkan jenis klaim yang dibuatnya: kebijakan yang Anda konfigurasi menjadi gerbang; detektor kritis memveto; pemeriksaan kritis yang diminta dan tidak dapat dijawab membuat vonis tidak diketahui (passed: false) daripada bersih; setiap detektor yang tersisa bergabung menjadi satu probabilitas bahwa keluaran buruk, ditimbang terhadap rasio kerugian yang Anda nyatakan di eval.falsePassCost (default 1, sehingga batasnya 0,5). verdict.basis menamai lapisan yang memutuskan dan verdict.by aturannya, dan verdict.also mencantumkan setiap lapisan berikutnya yang juga akan memutuskannya; interpretations[] menjelaskan mengapa aturan yang gagal tidak memutuskan dan pengaturan mana yang akan mengubahnya, serta menamai pertanyaan apa pun yang tidak dinilai dan input yang memungkinkannya dinilai.

Pelanggaran keamanan yang nyata gagal-keras. Secara default no_pii, no_injection_patterns, dan no_blocklist_words adalah aturan kritis: jika satu gagal, evaluasi melaporkan passed: false tidak peduli seberapa baik aturan lain dinilai, dan respons menamai pelakunya di critical_failures. SSN yang bocor tidak dapat dirata-ratakan. Aturan bawaan mana yang kritis adalah pengaturan penerapan (eval.criticalRules / eval.nonCriticalRules); setiap hasil aturan membawa flag critical efektif dan criticalSource, dan list_rules melaporkan daftar yang diterapkan server ini. Aturan kustom yang diterapkan dengan severity: "high" atau "critical" gagal-keras dengan cara yang sama; tingkat keparahan low/medium hanya memengaruhi skor. Satu batas yang perlu diketahui, dinyatakan dengan cara yang sama di setiap permukaan: aturan kritis yang dilewati (konteks hilang, definisi rusak, atau regex dihentikan pada anggaran sandbox) belum menilai keluaran dan tidak memveto — setiap aturan tersebut dinamai di critical_skipped. Gerbang yang harus gagal-tertutup memperlakukan critical_skipped yang tidak kosong sebagai tidak diketahui, bukan bersih, dan dapat memperlakukan setiap lompatan budgetExceeded di rule_results dengan cara yang sama.

Untuk gerbang CI: jika Anda menghilangkan eval_type, setiap bundel berjalan — kelengkapan, relevansi, keamanan, biaya, dan aturan kustom apa pun — dan respons mengatakan eval_type: "all" dengan note bahwa default berjalan, plus peta categories per bundel. Bundel tanpa apa pun untuk dinilai (biaya tanpa cost_usd, relevansi tanpa input) melaporkan passed: null di sana — tidak dievaluasi, tidak gagal — dan tidak pernah dihitung menuju vonis. Respons selalu menggema eval_type yang berjalan, sehingga gerbang Anda dapat memverifikasi cakupan; kunci pada passed untuk vonis dan sebutkan bundel hanya ketika Anda menginginkan proses yang lebih sempit.

Menulis aturan kustom

Dua cara untuk menambahkan aturan. Aturan inline ikut serta dalam satu panggilan evaluate_output (custom_rules, hingga 10 per panggilan); aturan tersebut aktif di samping bundel eval_type yang Anda pilih, atau sendiri dengan eval_type: "custom". Aturan diterapkan didaftarkan sekali dengan deploy_rule, bertahan di custom-rules.json di bawah rumah Iris Anda, dan aktif pada setiap evaluate_output masa depan dari evalType mereka. Definisi memiliki bentuk yang sama dalam kedua kasus:

deploy_rule membungkus definisi dengan name, opsional description, evalType (completeness · relevance · safety · cost · custom) dan severity. Tingkat keparahan mengatakan apa arti kegagalan: low/medium hanya menurunkan skor; high/critical gagal-keras evaluasi — passed: false, aturan yang dinamai di critical_failures — apa pun skor tertimbangnya. Aturan yang dilewati (aturan cost_threshold tanpa cost_usd, atau regex yang dihentikan pada anggaran sandbox 100 ms) belum menilai keluaran dan dicantumkan di critical_skipped sebagai gantinya. Terapkan aturan kritis yang melarang nama host internal dalam apa pun yang dikatakan agen:

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

Responsnya adalah aturan yang dipertahankan — simpan id untuk delete_rule:

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

Dari evaluate_output berikutnya dengan eval_type: "safety", keluaran yang menyebutkan db-primary.internal.example kembali passed: false dengan critical_failures: ["no_internal_hostnames"] — bahkan meskipun kelima aturan keamanan bawaan lulus dan skor tertimbangnya 0,895. Pola regex harus lulus pemeriksaan ReDoS pada saat penerapan dan selalu berjalan di pekerja sandbox di bawah tenggat keras 100 ms. list_rules menunjukkan apa yang diterapkan; komposer aturan dasbor membangun bentuk yang sama dari kegagalan yang Anda klik. Referensi lengkap, penilaian per jenis, dan contoh kerja: docs/custom-rules.md.

Skema dan konfigurasi alat lengkap: iris-eval.com

Fitur yang dihosting

Iris berjalan sepenuhnya di mesin Anda hari ini, dan semua yang dilakukannya gratis dan berlisensi MIT tanpa batasan dan tanpa akun. Penyimpanan ter-hosting, riwayat tim bersama, dan alerting sedang dipertimbangkan, bukan sedang dibangun. Belum ada harga, dan tidak ada yang perlu dibeli. Jika riwayat bersama berguna bagi Anda, daftar tunggu adalah cara kami mengetahui apakah itu layak dibangun — itu tidak mengikat Anda pada apa pun.

Dua komitmen tetap berlaku apa pun yang terjadi: tidak ada yang gratis hari ini yang akan dipindahkan ke balik paywall, dan tidak ada sertifikasi kepatuhan yang akan diklaim sebelum sertifikasi tersebut dimiliki.

Contoh

• Pengaturan Claude Desktop — Konfigurasi MCP untuk mode stdio dan HTTP
• TypeScript — klien MCP SDK — hubungkan dan panggil alat
• Transport HTTP (TS + Python) — kode klien lengkap untuk integrasi gaya REST
• Agen LangGraph, dinilai jalankan demi jalankan (Python) — IrisCallbackHandler dalam callback grafik; CI menjalankan grafik yang sama dengan model berskrip
• Crew CrewAI melalui OpenTelemetry (Python) — instrumentor OpenInference langsung ke pintu OTLP Iris, resep CrewAI sebagai skrip
• Agen OpenAI Agents SDK melalui OpenTelemetry (Python) dan (JavaScript), dan agen LlamaIndex — setiap resep sebagai skrip yang dijalankan CI terhadap server Iris nyata

Komunitas

• Masalah GitHub — Laporan bug dan permintaan fitur
• Diskusi GitHub — Pertanyaan dan ide
• Panduan Kontribusi — Cara berkontribusi
• Ingest HTTP — Penangkapan jejak deterministik melalui POST /api/v1/traces
• Peta kemampuan — Setiap pertanyaan yang dapat diajukan ke Iris, dan apa yang kurang
• Kebijakan versi — Apa yang dijanjikan setiap nomor versi, dan apa yang harus benar sebelum 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"

Jika Iris berguna bagi Anda, pertimbangkan untuk memberi bintang pada repo — ini membantu orang lain menemukannya.

Dilisensikan di bawah MIT.