Referensi SDK

Setiap nama yang diekspor paket oloproof dan oloproof.evaluators, beserta signature-nya, apakah sinkron atau asinkron, dan apa yang dikembalikannya. Untuk pengantar terpandu baca API Python terlebih dahulu.

Hanya kedua paket ini yang merupakan permukaan publik. Apa pun yang diimpor dari oloproof_core adalah internal mesin dan dapat berubah tanpa pemberitahuan. Setiap fungsi di bawah berjalan secara lokal terhadap store proyek; tidak satu pun mengirim data ke mana pun kecuali evaluator yang Anda berikan memanggil penyedia model.

Menjalankan evaluasi

evaluate dan aevaluate

def evaluate(*, system, dataset, evaluators, policy=None, **kwargs) -> EvaluationResult
async def aevaluate(*, system, dataset, evaluators, policy=None, **kwargs) -> EvaluationResult

evaluate bersifat sinkron. Jika dipanggil tanpa event loop yang berjalan, fungsi ini memakai asyncio.run; jika dipanggil dari dalam loop yang sedang berjalan (notebook, pengujian async), fungsi ini menjalankan evaluasi di thread terpisah dan memblokir sampai selesai, sehingga aman di kedua tempat. aevaluate adalah coroutine-nya; await dari kode async.

Argumen kata kunci lainnya (metrics, store, predictive, event_sink, retry_policy, traffic_draw_id) menerima tipe mesin dari oloproof_core dan bukan bagian dari permukaan yang stabil.

from oloproof import evaluate, system, current_case
from oloproof.evaluators import ExactMatch, evaluator

@system(name="support-bot", version="1")
def answer(case):
    current_case().usage(input_tokens=12, output_tokens=3)
    return {"label": "refund" if "refund" in case["question"].lower() else "other"}

@evaluator(criterion="short_label")
def short_label(case):
    return len(case.output["label"]) <= 6

result = evaluate(
    system=answer,
    dataset="cases.jsonl",
    evaluators=[ExactMatch(criterion="correct_label", field="label"), short_label],
)
for metric in result.metrics:
    print(metric.metric, metric.estimate, metric.interval, metric.n_observed, metric.n_missing)

Dijalankan pada suite dua kasus tanpa kebijakan, ini mencetak:

correct_label 1.0 lower=0.15811388300841903 upper=1.0 2 0
short_label 1.0 lower=0.15811388300841903 upper=1.0 2 0

EvaluationResult

Arti status, kode alasan, dan hitungan ada di Hasil dan eksekusi.

evaluate_comparison dan aevaluate_comparison

def evaluate_comparison(*, candidate_system, baseline_system, dataset, evaluators, policy, **kwargs) -> ComparisonEvaluationResult
async def aevaluate_comparison(*, candidate_system, baseline_system, dataset, evaluators, policy, **kwargs) -> ComparisonEvaluationResult

Menjalankan kedua sistem pada suite yang sama dalam satu urutan ber-seed dan memutuskan aturan perbandingan kebijakan. policy wajib dan harus memuat setidaknya satu aturan superiority, non_inferiority, atau equivalence, atau panggilan memunculkan error konfigurasi. Argumen kata kunci tambahan: concurrency, replicates, serta metrics, store, dan retry_policy yang bertipe mesin. Perilaku sinkron dan asinkron sama seperti evaluate.

ComparisonEvaluationResult memiliki candidate dan baseline (masing-masing EvaluationResult) serta comparison, yang membawa selisih berpasangan dan keputusannya. Lihat Membandingkan dua versi.

Mendeklarasikan sistem

@system

def system(func=None, *, name=None, version=None, config=None, timeout_s=None, records=())

Dapat dipakai tanpa argumen (@system) atau dengan argumen (@system(name=..., version=...)), atau dipanggil pada sebuah objek (system(model.answer, version="v2")). Fungsi menerima objek input kasus, bukan seluruh kasus, dan mengembalikan keluaran yang dibaca evaluator. Fungsi boleh berupa def atau async def; fungsi sinkron berjalan di thread worker.

Source modul fungsi itu sendiri masuk ke digest versi, sehingga mengeditnya membatalkan eksekusi yang di-cache. Lihat Referensi konfigurasi untuk apa lagi yang membatalkan dan yang tidak.

current_case

def current_case() -> CaseRecorder

Hanya tersedia selama Oloproof memanggil sistem Anda; di tempat lain fungsi ini memunculkan RuntimeError. Metode recorder:

Masing-masing mengembalikan ArtifactRef (kecuali usage, yang tidak mengembalikan apa pun). Payload bertipe diekspor untuk membangun rekaman ini: Retrieval, Passage, Context, ContextItem, DroppedItem, Citations, StageTimings, AgentTrajectory, AgentStep, AgentCheckpoint, AgentConstraintCheck, dan nama jenis CONVERSATION (conversation/v1).

@rag_system

def rag_system(*, name, depth, top_k, token_budget=None, index_version=None, version=None, config=None, citations_path="citations")

Dekorator kelas. Kelas menyediakan retrieve(input, depth) dan generate(input, context), ditambah count_tokens(passage) jika menetapkan token_budget. context adalah list objek Passage yang lolos top_k dan anggaran, dalam urutan peringkat. Oloproof merekam sendiri retrieval/v1, context/v1, citations/v1, dan stage_timings/v1, dan meng-cache setiap tahap secara terpisah. citations_path menyebut field keluaran yang berisi id yang dikutip jawaban. Lihat RAG.

Evaluator

Semua kelas ada di oloproof.evaluators. criterion masing-masing menyebut metrik yang dihasilkannya. Artefak mana yang dibaca masing-masing, dan padanan YAML-nya, ada di tabel evaluator dalam Referensi konfigurasi.

provider adalah "anthropic", "openai", atau "openai_compatible". Juri membaca kuncinya dari variabel lingkungan yang disebut api_key_env (ANTHROPIC_API_KEY atau OPENAI_API_KEY secara bawaan) dan ditagih oleh penyedia itu. Groundedness dan CitationSupport menerima pengaturan RubricJudge lainnya melalui **options. Juri probabilitas, classifier model, dan cascade tidak memiliki kelas SDK; ketiganya hanya ada di YAML.

ConversationCompleted dan ConversationJudge membaca artefak conversation/v1 yang direkam sistem Anda. Oloproof tidak menjalankan percakapan: aplikasi Anda menjalankan setiap giliran dan merekam transkripnya. Lihat Agen.

@evaluator

def evaluator(*, criterion, reads=("output", "expected"), cacheable=False, version=None, value_type="binary", score_range=None)

Membungkus fungsi satu argumen, yaitu kasus, menjadi CustomEvaluator. Kasus memiliki output, expected, dan scenario, dan artifacts(name) mengembalikan payload dari jenis yang direkam. Fungsi boleh berupa def atau async def. Evaluator biner mengembalikan True atau False; evaluator skor mendeklarasikan value_type="score" dan score_range=(low, high) lalu mengembalikan angka. Exception yang dimunculkan fungsi merekam kasus sebagai hilang untuk kriteria itu, tidak pernah sebagai kegagalan.

reads harus mencantumkan setiap field yang dibaca fungsi (input, output, expected, metadata, metadata.<key>, atau artifacts.<name>), karena penilaian yang di-cache dikunci tepat pada field-field itu. Penilaian dipakai ulang antar-eksekusi hanya dengan cacheable=True. Source modul yang mendefinisikannya masuk ke versi, sehingga mengeditnya membatalkan penilaian itu. YAML tidak dapat menyebut evaluator kustom.

Diagnosis

diagnose dan adiagnose

def diagnose(run_id, **kwargs) -> InterventionResult
async def adiagnose(run_id, *, system, evaluators, intervention, criterion, control=True, top_k=None, reranker=None, reranker_root=None, store=None, concurrency=None) -> InterventionResult

Mengeksekusi ulang kasus gagal dari eksekusi tersimpan di bawah satu intervensi: "gold-context", "top-k" (dengan top_k), atau "reranker" (dengan reranker). system dan evaluators harus versi yang dipakai eksekusi; versi yang berbeda ditolak sebelum apa pun dieksekusi. Dengan control=True sampel kontrol baru dijalankan di samping intervensi, sehingga perubahan dapat dibedakan dari variasi antar-eksekusi. diagnose adalah bentuk sinkronnya dan berperilaku di dalam loop yang berjalan seperti evaluate. Lihat RAG untuk alur kerjanya.

InterventionResult menyimpan id eksekusi induk, intervensinya, apakah intervensi itu didukung, eksekusi intervensi dan kontrol, hasil per kasus, serta DiagnosisReport berisi entri CaseDiagnosis jika dihasilkan.

Replay agen

def supports_replay(system) -> bool
def checkpoint_for(trajectory, step_index) -> AgentCheckpoint | None
async def replay_case(system, *, scenario_id, trajectory, checkpoint, change) -> ReplayOutcome
def label_case(outcome) -> CaseDiagnosis
def label_cases(outcomes) -> tuple[CaseDiagnosis, ...]
def unnecessary_steps(labels) -> tuple[UnnecessaryStep, ...]

Replay adalah sesuatu yang dilakukan sistem Anda, bukan sesuatu yang disimulasikan Oloproof. Sebuah sistem mendukungnya hanya dengan mengimplementasikan async def replay(self, trajectory, *, checkpoint, change) -> AgentTrajectory, yang mengembalikan apa yang dilakukan agen sejak checkpoint dan seterusnya; Oloproof menyambungkannya ke prefiks yang direkam lalu membandingkan. Aplikasi Anda memiliki sendiri state, sesi, dan efek samping alatnya, termasuk mengatur ulang semuanya sebelum replay. supports_replay melaporkan apakah sebuah sistem mendeklarasikan metode itu.

replay_case adalah coroutine: await atau panggil melalui asyncio.run. Fungsi ini menjalankan kontrol (checkpoint yang sama dengan ReplayChange(kind="resume")) sebelum replay, dan tidak mencoba replay ketika kontrol tidak mereproduksi rekaman. change adalah ReplayChange(kind="drop_step", step_index=...) atau ReplayChange(kind="resume"). checkpoint_for memilih checkpoint terekam terakhir yang benar-benar sebelum sebuah langkah, atau None, dalam hal ini hasilnya dibuang sebagai no_checkpoint_recorded tanpa menyentuh sistem.

ReplayOutcome membawa scenario_id, change, status akhir replay dan kontrol, serta discarded dengan alasan ketika kasus tidak menghasilkan bukti. Kasus yang dibuang bukanlah kasus yang gagal. label_case mengubah hasil menjadi CaseDiagnosis dengan FailureLabel dan LabelReason-nya; unnecessary_steps mencantumkan langkah-langkah yang penghapusannya membiarkan hasil tetap utuh. Lihat Agen.

Label manusia dan kepercayaan evaluator

def record_label(*, run_id, scenario_id, criterion, passed, labelled_by, note=None, purpose="measurement", sample_index=0, config="oloproof.yaml", store=None, ...) -> HumanLabel

Menyimpan putusan lolos/gagal satu orang atas satu kasus dari eksekusi tersimpan. Label menjadi masukan bagi oloproof evaluators validate, yang mengukur kesepakatan juri terhadapnya (AgreementResult) dan merekam statusnya (RegistryEntry). Argumen measurement_sample_* lainnya mengikat label ke sampel pengukuran; oloproof labels export dan oloproof labels import di CLI mengisinya untuk Anda. Lihat Juri.

Kebijakan dalam kode

ReleasePolicy, IntervalThresholdRule, ObservedCountRule, dan DecisionRule (gabungan keduanya) membangun kebijakan tanpa file. Field-field mereka adalah field release.yaml dalam Referensi konfigurasi; aturan interval menerima direction (min atau max) dan threshold alih-alih min: atau max:. Aturan perbandingan tidak memiliki kelas yang diekspor; tulis di release.yaml dan berikan path-nya.

from oloproof import IntervalThresholdRule, ReleasePolicy

policy = ReleasePolicy(
    rules=(IntervalThresholdRule(id="accuracy", metric="correct_label", direction="min", threshold=0.8),),
)

Ekspor lainnya