SDK リファレンス

oloproof パッケージと oloproof.evaluators パッケージがエクスポートするすべての名前を、そのシグネチャ、同期か非同期か、何を返すかとともに示します。ガイド付きの入門としては、まず Python API を読んでください。

公開されている面はこの 2 つのパッケージだけです。oloproof_core からインポートしたものはエンジンの内部であり、予告なく変わることがあります。以下のすべての関数はプロジェクトのストアに対してローカルで実行され、渡した評価器がモデルプロバイダーを呼び出さない限り、どこにもデータを送りません。

評価の実行

evaluate と aevaluate

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

evaluate は同期です。イベントループが動いていない状態で呼ぶと asyncio.run を使います。動作中のループの内側（ノートブック、非同期テスト）から呼ぶと、評価を別スレッドで実行し、終わるまでブロックするため、どちらの場所でも安全です。aevaluate はコルーチンです。非同期コードから await してください。

残りのキーワード引数（metrics、store、predictive、event_sink、retry_policy、traffic_draw_id）は oloproof_core のエンジンの型を受け取り、安定した面には含まれません。

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)

ポリシーなしで 2 ケースのスイートに対して実行すると、次のように出力されました。

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

状態、理由コード、件数の意味は結果と実行にあります。

evaluate_comparison と 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

両方のシステムを同じスイート上で 1 つのシード付き順序で実行し、ポリシーの比較ルールを判断します。policy は必須で、少なくとも 1 つの superiority、non_inferiority、equivalence ルールを含んでいなければならず、そうでなければ呼び出しは設定エラーを送出します。追加のキーワード引数は concurrency、replicates、そしてエンジンの型を取る metrics、store、retry_policy です。同期と非同期の挙動は evaluate と同じです。

ComparisonEvaluationResult は candidate と baseline（それぞれ EvaluationResult）、そして対応のある差とその判断を持つ comparison を持ちます。2 つのバージョンの比較を参照してください。

システムの宣言

@system

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

引数なし（@system）でも引数付き（@system(name=..., version=...)）でも使え、オブジェクトに対して呼び出すこともできます（system(model.answer, version="v2")）。関数はケース全体ではなくケースの input オブジェクトを受け取り、評価器が読む出力を返します。def でも async def でも構いません。同期関数はワーカースレッド上で実行されます。

関数自身のモジュールのソースはバージョンのダイジェストに含まれるため、それを編集するとキャッシュ済みの実行は無効になります。ほかに何が含まれ、何が含まれないかは設定リファレンスを参照してください。

current_case

def current_case() -> CaseRecorder

Oloproof があなたのシステムを呼び出している間だけ使えます。それ以外の場所では RuntimeError を送出します。レコーダーのメソッドは次のとおりです。

それぞれ ArtifactRef を返します（usage は何も返しません）。これらのレコードを組み立てるための型付きペイロードがエクスポートされています。Retrieval、Passage、Context、ContextItem、DroppedItem、Citations、StageTimings、AgentTrajectory、AgentStep、AgentCheckpoint、AgentConstraintCheck、そして種類名 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")

クラスデコレーターです。クラスは retrieve(input, depth) と generate(input, context) を提供し、token_budget を設定する場合は count_tokens(passage) も提供します。context は、top_k と予算を通過した Passage オブジェクトのリストで、順位の順に並びます。Oloproof は retrieval/v1、context/v1、citations/v1、stage_timings/v1 を自ら記録し、各段階を別々にキャッシュします。citations_path は、回答が引用する id を保持する出力フィールドを指定します。RAG を参照してください。

評価器

すべてのクラスは oloproof.evaluators にあります。それぞれの criterion が、それが生成するメトリクスの名前になります。各評価器がどのアーティファクトを読むか、および YAML での等価物は、設定リファレンスの評価器の表にあります。

provider は "anthropic"、"openai"、"openai_compatible" のいずれかです。ジャッジは api_key_env が指定する環境変数（デフォルトは ANTHROPIC_API_KEY または OPENAI_API_KEY）からキーを読み、そのプロバイダーから請求されます。Groundedness と CitationSupport は、RubricJudge の残りの設定を **options で受け取ります。確率ジャッジ、モデル分類器、カスケードには SDK のクラスがなく、YAML にのみ存在します。

ConversationCompleted と ConversationJudge は、あなたのシステムが記録する conversation/v1 アーティファクトを読みます。Oloproof は会話を駆動しません。あなたのアプリケーションがすべてのターンを実行し、トランスクリプトを記録します。エージェントを参照してください。

@evaluator

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

1 つの引数（ケース）を取る関数を CustomEvaluator に包みます。ケースは output、expected、scenario を持ち、artifacts(name) は記録された種類のペイロードを返します。関数は def でも async def でも構いません。二値の評価器は True または False を返します。スコアの評価器は value_type="score" と score_range=(low, high) を宣言し、数値を返します。関数が送出した例外は、そのケースをその基準について欠測として記録し、決して失敗とはしません。

reads には関数が読むすべてのフィールド（input、output、expected、metadata、metadata.<key>、artifacts.<name>）を列挙しなければなりません。キャッシュされた判定はまさにそれらをキーとするためです。判定は cacheable=True のときにだけ実行をまたいで再利用されます。定義しているモジュールのソースはバージョンに含まれるため、それを編集すると判定は無効になります。YAML ではカスタム評価器を指定できません。

診断

diagnose と 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

保存された実行の失敗ケースを、1 つの介入の下で再実行します。"gold-context"、"top-k"（top_k とともに）、"reranker"（reranker とともに）です。system と evaluators は実行が使ったバージョンでなければならず、異なるバージョンは何かが実行される前に拒否されます。control=True では新しい対照サンプルが介入と並んで実行されるため、変化を実行ごとのばらつきと区別できます。diagnose は同期版で、動作中のループの内側では evaluate と同じように振る舞います。ワークフローは RAG を参照してください。

InterventionResult は、親の実行 id、介入、それがサポートされたかどうか、介入と対照の実行、ケースごとの結果、そして生成された場合は CaseDiagnosis エントリからなる DiagnosisReport を保持します。

エージェントのリプレイ

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, ...]

リプレイはあなたのシステムが行うものであり、Oloproof がシミュレートするものではありません。システムがリプレイをサポートするのは、async def replay(self, trajectory, *, checkpoint, change) -> AgentTrajectory を実装し、チェックポイント以降にエージェントが行ったことを返す場合だけです。Oloproof は記録された前半部分をつなぎ合わせて比較します。状態、セッション、ツールの副作用は、リプレイ前のリセットも含めてあなたのアプリケーションが持ちます。supports_replay は、システムがそのメソッドを宣言しているかどうかを報告します。

replay_case はコルーチンです。await するか、asyncio.run を通して呼び出してください。リプレイの前に対照（同じチェックポイントで ReplayChange(kind="resume")）を実行し、対照が記録を再現しない場合はリプレイを試みません。change は ReplayChange(kind="drop_step", step_index=...) または ReplayChange(kind="resume") です。checkpoint_for はあるステップより厳密に前の、最新の記録されたチェックポイントを選びます。なければ None で、その場合の結果はシステムに触れずに no_checkpoint_recorded として破棄されます。

ReplayOutcome は scenario_id、change、リプレイと対照の終了ステータス、そしてケースがエビデンスを生まないときの理由付きの discarded を持ちます。破棄されたケースは失敗したケースではありません。label_case は結果を、FailureLabel とその LabelReason を持つ CaseDiagnosis に変えます。unnecessary_steps は、取り除いても結果が変わらなかったステップを列挙します。エージェントを参照してください。

人間のラベルと評価器の信頼

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

保存された実行の 1 つのケースについて、1 人の合格・不合格の判定を保存します。ラベルは oloproof evaluators validate に使われ、それはジャッジのラベルとの一致度を測定し（AgreementResult）、その状態を記録します（RegistryEntry）。さらに measurement_sample_* 引数はラベルを測定サンプルに結びつけます。CLI の oloproof labels export と oloproof labels import がそれらを埋めてくれます。ジャッジを参照してください。

コードでのポリシー

ReleasePolicy、IntervalThresholdRule、ObservedCountRule、DecisionRule（後の 2 つの合併型）を使うと、ファイルなしでポリシーを組み立てられます。それらのフィールドは設定リファレンスの release.yaml のフィールドです。区間ルールは min: や max: の代わりに direction（min または max）と threshold を取ります。比較ルールにはエクスポートされたクラスがありません。release.yaml に書き、そのパスを渡してください。

from oloproof import IntervalThresholdRule, ReleasePolicy

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

その他のエクスポート