SDK-referentie

Elke naam die de pakketten oloproof en oloproof.evaluators exporteren, met zijn signatuur, of hij synchroon of asynchroon is, en wat hij teruggeeft. Lees voor een begeleide inleiding eerst De Python-API.

Alleen deze twee pakketten vormen het publieke oppervlak. Alles wat uit oloproof_core wordt geïmporteerd is interne engine en kan zonder aankondiging veranderen. Elke functie hieronder draait lokaal tegen de store van het project; geen ervan stuurt ergens gegevens heen, tenzij een evaluator die je meegeeft een modelprovider aanroept.

Een evaluatie draaien

evaluate en aevaluate

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

evaluate is synchroon. Aangeroepen zonder lopende event loop gebruikt het asyncio.run; aangeroepen binnen een lopende loop (een notebook, een asynchrone test) draait het de evaluatie op een aparte thread en blokkeert tot die klaar is, dus het is op beide plekken veilig. aevaluate is de coroutine; await die vanuit asynchrone code.

De overige keyword-argumenten (metrics, store, predictive, event_sink, retry_policy, traffic_draw_id) nemen enginetypen uit oloproof_core en horen niet bij het stabiele oppervlak.

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)

Gedraaid op een suite van twee cases zonder beleid, printte dit:

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

Wat de toestanden, redencodes en aantallen betekenen staat in Resultaten en uitvoering.

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

Draait beide systemen op dezelfde suite in één geseede volgorde en beslist de vergelijkingsregels van het beleid. policy is verplicht en moet minstens één superiority-, non_inferiority- of equivalence-regel bevatten, anders geeft de aanroep een configuratiefout. Extra keyword-argumenten: concurrency, replicates, en de engine-getypeerde metrics, store en retry_policy. Synchroon en asynchroon gedrag zijn als bij evaluate.

ComparisonEvaluationResult heeft candidate en baseline (elk een EvaluationResult) en comparison, dat de gepaarde verschillen en hun beslissingen draagt. Zie Twee versies vergelijken.

Een systeem declareren

@system

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

Bruikbaar zonder argumenten (@system) of met (@system(name=..., version=...)), of aangeroepen op een object (system(model.answer, version="v2")). De functie krijgt het input-object van de case, niet de hele case, en geeft de output terug die evaluators lezen. Ze mag def of async def zijn; een synchrone functie draait op een workerthread.

De broncode van de eigen module van de functie gaat mee in de versiedigest, dus wie die bewerkt maakt gecachete uitvoeringen ongeldig. Zie de Configuratiereferentie voor wat dat verder wel en niet doet.

current_case

def current_case() -> CaseRecorder

Alleen beschikbaar terwijl Oloproof je systeem aanroept; overal elders geeft het RuntimeError. De methoden van de recorder:

Elk geeft een ArtifactRef terug (behalve usage, dat niets teruggeeft). De getypeerde payloads worden geëxporteerd om deze records te bouwen: Retrieval, Passage, Context, ContextItem, DroppedItem, Citations, StageTimings, AgentTrajectory, AgentStep, AgentCheckpoint, AgentConstraintCheck, en de soortnaam 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")

Een klassedecorator. De klasse levert retrieve(input, depth) en generate(input, context), plus count_tokens(passage) als ze een token_budget zet. context is de lijst van Passage-objecten die top_k en het budget overleefden, in rangvolgorde. Oloproof legt zelf retrieval/v1, context/v1, citations/v1 en stage_timings/v1 vast, en cachet elke fase apart. citations_path noemt het outputveld met de ids die het antwoord citeert. Zie RAG.

Evaluators

Alle klassen staan in oloproof.evaluators. Het criterion van elk noemt de metriek die het produceert. Welke artefacten elk leest, en het YAML-equivalent, staan in de evaluatortabel van de Configuratiereferentie.

provider is "anthropic", "openai" of "openai_compatible". Een judge leest zijn sleutel uit de omgevingsvariabele die api_key_env noemt (standaard ANTHROPIC_API_KEY of OPENAI_API_KEY) en wordt door die provider gefactureerd. Groundedness en CitationSupport nemen de overige instellingen van RubricJudge via **options. De kansjudge, de modelclassifier en de cascade hebben geen SDK-klasse; ze bestaan alleen in YAML.

ConversationCompleted en ConversationJudge lezen een conversation/v1-artefact dat je systeem vastlegt. Oloproof stuurt het gesprek niet aan: je applicatie draait elke beurt en legt het transcript vast. Zie Agents.

@evaluator

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

Verpakt een functie met één argument, de case, tot een CustomEvaluator. De case heeft output, expected en scenario, en artifacts(name) geeft de payloads van een vastgelegde soort terug. De functie mag def of async def zijn. Een binaire evaluator geeft True of False terug; een score-evaluator declareert value_type="score" en score_range=(low, high) en geeft een getal terug. Een exceptie die de functie opwerpt legt de case voor dat criterium vast als ontbrekend, nooit als mislukking.

reads moet elk veld noemen dat de functie leest (input, output, expected, metadata, metadata.<key> of artifacts.<name>), omdat het gecachete oordeel precies op die velden is gesleuteld. Oordelen worden alleen met cacheable=True tussen runs hergebruikt. De broncode van de definiërende module gaat mee in de versie, dus wie die bewerkt maakt ze ongeldig. YAML kan geen eigen evaluator noemen.

Diagnose

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

Voert de mislukte cases van een opgeslagen run opnieuw uit onder één interventie: "gold-context", "top-k" (met top_k) of "reranker" (met reranker). system en evaluators moeten de versies zijn die de run gebruikte; een andere versie wordt geweigerd voordat er iets wordt uitgevoerd. Met control=True draait er naast de interventie een verse controlesteekproef, zodat een verandering te onderscheiden is van variatie tussen runs. diagnose is de synchrone vorm en gedraagt zich binnen een lopende loop zoals evaluate. Zie RAG voor de werkwijze.

InterventionResult bevat het id van de ouderrun, de interventie, of die ondersteund werd, de interventie- en controleruns, een uitkomst per case, en een DiagnosisReport met CaseDiagnosis-items als er een is gemaakt.

Agent-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 is iets wat je systeem doet, niet iets wat Oloproof simuleert. Een systeem ondersteunt het alleen door async def replay(self, trajectory, *, checkpoint, change) -> AgentTrajectory te implementeren, dat teruggeeft wat de agent vanaf het checkpoint deed; Oloproof plakt het vastgelegde begin ervoor en vergelijkt. Je applicatie beheert haar eigen toestand, sessies en neveneffecten van tools, inclusief het terugzetten ervan vóór een replay. supports_replay meldt of een systeem de methode declareert.

replay_case is een coroutine: await hem, of roep hem aan via asyncio.run. Hij draait vóór de replay een controle (hetzelfde checkpoint met ReplayChange(kind="resume")), en probeert de replay niet als de controle de opname niet reproduceert. change is ReplayChange(kind="drop_step", step_index=...) of ReplayChange(kind="resume"). checkpoint_for kiest het laatste vastgelegde checkpoint strikt vóór een stap, of None, waarna de uitkomst wordt verworpen als no_checkpoint_recorded zonder het systeem aan te raken.

ReplayOutcome draagt scenario_id, change, de eindstatussen van de replay en de controle, en discarded met een reden als de case geen bewijs oplevert. Een verworpen case is geen mislukte case. label_case maakt van een uitkomst een CaseDiagnosis met een FailureLabel en zijn LabelReason; unnecessary_steps noemt de stappen waarvan het weglaten de uitkomst intact liet. Zie Agents.

Menselijke labels en vertrouwen in evaluators

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

Slaat het geslaagd/mislukt-oordeel van één persoon over één case van een opgeslagen run op. Labels voeden oloproof evaluators validate, dat de overeenstemming van een judge ermee meet (AgreementResult) en zijn status vastlegt (RegistryEntry). De verdere measurement_sample_*-argumenten binden een label aan een meetsteekproef; oloproof labels export en oloproof labels import in de CLI vullen ze voor je in. Zie Judges.

Beleid in code

ReleasePolicy, IntervalThresholdRule, ObservedCountRule en DecisionRule (de vereniging van die twee) bouwen een beleid zonder bestand. Hun velden zijn de release.yaml-velden uit de Configuratiereferentie; een intervalregel neemt direction (min of max) en threshold in plaats van min: of max:. Vergelijkingsregels hebben geen geëxporteerde klasse; schrijf ze in release.yaml en geef het pad mee.

from oloproof import IntervalThresholdRule, ReleasePolicy

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

Andere exports