SDK-Referenz

Jeder Name, den die Pakete oloproof und oloproof.evaluators exportieren, mit seiner Signatur, ob er synchron oder asynchron ist und was er zurückgibt. Für eine geführte Einführung lesen Sie zuerst Die Python-API.

Nur diese beiden Pakete sind die öffentliche Oberfläche. Alles, was aus oloproof_core importiert wird, sind Interna der Engine und kann sich ohne Ankündigung ändern. Jede Funktion unten läuft lokal gegen den Store des Projekts; keine sendet Daten irgendwohin, es sei denn, ein übergebener Evaluator ruft einen Modell-Provider auf.

Eine Evaluation ausführen

evaluate und aevaluate

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

evaluate ist synchron. Ohne laufende Event-Loop aufgerufen, verwendet es asyncio.run; aus einer laufenden Loop heraus (ein Notebook, ein asynchroner Test) führt es die Evaluation in einem eigenen Thread aus und blockiert, bis sie fertig ist, sodass es an beiden Orten sicher ist. aevaluate ist die Coroutine; warten Sie in asynchronem Code mit await darauf.

Die übrigen Schlüsselwortargumente (metrics, store, predictive, event_sink, retry_policy, traffic_draw_id) nehmen Engine-Typen aus oloproof_core und gehören nicht zur stabilen Oberfläche.

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)

Auf einer Suite mit zwei Fällen ohne Policy ausgeführt, gab dies aus:

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

Was die Zustände, Begründungscodes und Zählungen bedeuten, steht in Ergebnisse und Ausführung.

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

Führt beide Systeme auf derselben Suite in einer geseedeten Reihenfolge aus und entscheidet die Vergleichsregeln der Policy. policy ist erforderlich und muss mindestens eine superiority-, non_inferiority- oder equivalence-Regel enthalten, sonst wirft der Aufruf einen Konfigurationsfehler. Weitere Schlüsselwortargumente: concurrency, replicates und die Engine-typisierten metrics, store und retry_policy. Synchrones und asynchrones Verhalten sind wie bei evaluate.

ComparisonEvaluationResult hat candidate und baseline (jeweils ein EvaluationResult) und comparison, das die gepaarten Differenzen und ihre Entscheidungen trägt. Siehe Zwei Versionen vergleichen.

Ein System deklarieren

@system

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

Verwendbar ohne Argumente (@system) oder mit (@system(name=..., version=...)) oder auf ein Objekt angewendet (system(model.answer, version="v2")). Die Funktion erhält das input-Objekt des Falls, nicht den ganzen Fall, und gibt die Ausgabe zurück, die Evaluatoren lesen. Sie darf def oder async def sein; eine synchrone Funktion läuft in einem Worker-Thread.

Der Quelltext des eigenen Moduls der Funktion geht in den Versions-Digest ein, sodass eine Änderung daran gecachte Ausführungen ungültig macht. Was sonst dazu führt und was nicht, steht in der Konfigurationsreferenz.

current_case

def current_case() -> CaseRecorder

Nur verfügbar, während Oloproof Ihr System aufruft; anderswo wirft es RuntimeError. Die Methoden des Recorders:

Jede gibt eine ArtifactRef zurück (außer usage, das nichts zurückgibt). Die typisierten Payloads zum Aufbau dieser Datensätze werden exportiert: Retrieval, Passage, Context, ContextItem, DroppedItem, Citations, StageTimings, AgentTrajectory, AgentStep, AgentCheckpoint, AgentConstraintCheck und der Artname 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")

Ein Klassendekorator. Die Klasse stellt retrieve(input, depth) und generate(input, context) bereit, dazu count_tokens(passage), wenn sie ein token_budget setzt. context ist die Liste der Passage-Objekte, die top_k und das Budget überstanden haben, in Rangfolge. Oloproof zeichnet retrieval/v1, context/v1, citations/v1 und stage_timings/v1 selbst auf und cacht jede Stufe getrennt. citations_path benennt das Ausgabefeld mit den IDs, die die Antwort zitiert. Siehe RAG.

Evaluatoren

Alle Klassen liegen in oloproof.evaluators. Das criterion jeder Klasse benennt die Metrik, die sie erzeugt. Welche Artefakte jede liest und ihr YAML-Gegenstück stehen in der Evaluator-Tabelle der Konfigurationsreferenz.

provider ist "anthropic", "openai" oder "openai_compatible". Ein Judge liest seinen Schlüssel aus der Umgebungsvariable, die api_key_env benennt (standardmäßig ANTHROPIC_API_KEY oder OPENAI_API_KEY), und wird von diesem Provider abgerechnet. Groundedness und CitationSupport nehmen die übrigen Einstellungen von RubricJudge über **options. Der Wahrscheinlichkeits-Judge, der Modell-Klassifikator und die Kaskade haben keine SDK-Klasse; es gibt sie nur in YAML.

ConversationCompleted und ConversationJudge lesen ein conversation/v1-Artefakt, das Ihr System aufzeichnet. Oloproof steuert die Konversation nicht: Ihre Anwendung führt jeden Turn aus und zeichnet das Transkript auf. Siehe Agenten.

@evaluator

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

Verpackt eine Funktion mit einem Argument, dem Fall, in einen CustomEvaluator. Der Fall hat output, expected und scenario, und artifacts(name) gibt die Payloads einer aufgezeichneten Art zurück. Die Funktion darf def oder async def sein. Ein binärer Evaluator gibt True oder False zurück; ein Score-Evaluator deklariert value_type="score" und score_range=(low, high) und gibt eine Zahl zurück. Eine Ausnahme der Funktion zeichnet den Fall für dieses Kriterium als fehlend auf, nie als Fehlschlag.

reads muss jedes Feld aufführen, das die Funktion liest (input, output, expected, metadata, metadata.<key> oder artifacts.<name>), weil das gecachte Urteil genau auf diese verschlüsselt ist. Urteile werden nur mit cacheable=True über Läufe hinweg wiederverwendet. Der Quelltext des definierenden Moduls geht in die Version ein, sodass eine Änderung daran sie ungültig macht. YAML kann keinen eigenen Evaluator benennen.

Diagnose

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

Führt die fehlgeschlagenen Fälle eines gespeicherten Laufs unter einer Intervention erneut aus: "gold-context", "top-k" (mit top_k) oder "reranker" (mit reranker). system und evaluators müssen die Versionen sein, die der Lauf verwendet hat; eine andere Version wird abgewiesen, bevor irgendetwas ausgeführt wird. Mit control=True läuft neben der Intervention eine frische Kontrollstichprobe, sodass sich eine Änderung von der Variation zwischen Läufen unterscheiden lässt. diagnose ist die synchrone Form und verhält sich in einer laufenden Loop wie evaluate. Den Ablauf beschreibt RAG.

InterventionResult enthält die ID des Elternlaufs, die Intervention, ob sie unterstützt wurde, die Interventions- und Kontrollläufe, ein Ergebnis pro Fall und einen DiagnosisReport aus CaseDiagnosis-Einträgen, wenn einer erzeugt wurde.

Agenten-Replay

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 ist etwas, das Ihr System tut, nicht etwas, das Oloproof simuliert. Ein System unterstützt es nur, indem es async def replay(self, trajectory, *, checkpoint, change) -> AgentTrajectory implementiert und zurückgibt, was der Agent ab dem Checkpoint tat; Oloproof fügt das aufgezeichnete Präfix an und vergleicht. Ihre Anwendung besitzt ihren Zustand, ihre Sitzungen und die Nebeneffekte ihrer Tools und setzt sie auch vor einem Replay zurück. supports_replay meldet, ob ein System die Methode deklariert.

replay_case ist eine Coroutine: Warten Sie mit await darauf oder rufen Sie sie über asyncio.run auf. Sie führt vor dem Replay eine Kontrolle aus (derselbe Checkpoint mit ReplayChange(kind="resume")) und versucht das Replay nicht, wenn die Kontrolle die Aufzeichnung nicht reproduziert. change ist ReplayChange(kind="drop_step", step_index=...) oder ReplayChange(kind="resume"). checkpoint_for wählt den letzten aufgezeichneten Checkpoint strikt vor einem Schritt, oder None; dann wird das Ergebnis als no_checkpoint_recorded verworfen, ohne das System zu berühren.

ReplayOutcome trägt scenario_id, change, die Endzustände von Replay und Kontrolle und discarded mit einem Grund, wenn der Fall keine Evidenz liefert. Ein verworfener Fall ist kein fehlgeschlagener Fall. label_case macht aus einem Ergebnis eine CaseDiagnosis mit einem FailureLabel und seinem LabelReason; unnecessary_steps listet die Schritte auf, deren Entfernen das Ergebnis unverändert ließ. Siehe Agenten.

Menschliche Labels und Vertrauen in Evaluatoren

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

Speichert das Bestanden/Nicht-bestanden-Urteil einer Person über einen Fall eines gespeicherten Laufs. Labels speisen oloproof evaluators validate, das die Übereinstimmung eines Judges mit ihnen misst (AgreementResult) und seinen Status aufzeichnet (RegistryEntry). Die weiteren measurement_sample_*-Argumente binden ein Label an eine Messstichprobe; oloproof labels export und oloproof labels import in der CLI füllen sie für Sie aus. Siehe Judges.

Policies im Code

ReleasePolicy, IntervalThresholdRule, ObservedCountRule und DecisionRule (die Vereinigung der beiden) bauen eine Policy ohne Datei. Ihre Felder sind die release.yaml-Felder der Konfigurationsreferenz; eine Intervallregel nimmt direction (min oder max) und threshold statt min: oder max:. Vergleichsregeln haben keine exportierte Klasse; schreiben Sie sie in release.yaml und übergeben Sie deren Pfad.

from oloproof import IntervalThresholdRule, ReleasePolicy

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

Weitere Exporte