Riferimento dell'SDK

Ogni nome che i pacchetti oloproof e oloproof.evaluators esportano, con la sua firma, se è sincrono o asincrono, e che cosa restituisce. Per un'introduzione guidata leggi prima L'API Python.

Solo questi due pacchetti costituiscono la superficie pubblica. Qualsiasi cosa importata da oloproof_core è parte interna del motore e può cambiare senza preavviso. Ogni funzione qui sotto gira in locale sullo store del progetto; nessuna invia dati da qualche parte, a meno che un valutatore che passi non chiami un provider di modelli.

Eseguire una valutazione

evaluate e aevaluate

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

evaluate è sincrona. Chiamata senza un event loop in esecuzione usa asyncio.run; chiamata dall'interno di un loop in esecuzione (un notebook, un test asincrono) esegue la valutazione su un thread separato e blocca finché non termina, quindi è sicura in entrambi i contesti. aevaluate è la coroutine; attendila con await dal codice asincrono.

Gli argomenti nominali rimanenti (metrics, store, predictive, event_sink, retry_policy, traffic_draw_id) accettano tipi del motore da oloproof_core e non fanno parte della superficie stabile.

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)

Eseguito su una suite di due casi senza policy, ha stampato:

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

Che cosa significano gli stati, i codici di motivo e i conteggi è spiegato in Risultati ed esecuzione.

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

Esegue entrambi i sistemi sulla stessa suite in un unico ordine con seed e decide le regole di confronto della policy. policy è obbligatoria e deve contenere almeno una regola superiority, non_inferiority o equivalence, altrimenti la chiamata solleva un errore di configurazione. Argomenti nominali aggiuntivi: concurrency, replicates, e metrics, store e retry_policy con tipi del motore. Il comportamento sincrono e asincrono è come per evaluate.

ComparisonEvaluationResult ha candidate e baseline (ciascuno un EvaluationResult) e comparison, che porta le differenze appaiate e le loro decisioni. Vedi Confrontare due versioni.

Dichiarare un sistema

@system

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

Utilizzabile senza argomenti (@system) o con argomenti (@system(name=..., version=...)), oppure chiamato su un oggetto (system(model.answer, version="v2")). La funzione riceve l'oggetto input del caso, non l'intero caso, e restituisce l'output che i valutatori leggono. Può essere def o async def; una funzione sincrona gira su un thread di lavoro.

Il sorgente del modulo della funzione entra nel digest della versione, quindi modificarlo invalida le esecuzioni in cache. Vedi il Riferimento della configurazione per che cos'altro lo fa e che cosa no.

current_case

def current_case() -> CaseRecorder

Disponibile solo mentre Oloproof sta chiamando il tuo sistema; altrove solleva RuntimeError. I metodi del registratore:

Ciascuno restituisce un ArtifactRef (tranne usage, che non restituisce nulla). I payload tipizzati sono esportati per costruire questi record: Retrieval, Passage, Context, ContextItem, DroppedItem, Citations, StageTimings, AgentTrajectory, AgentStep, AgentCheckpoint, AgentConstraintCheck, e il nome di tipo 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")

Un decoratore di classe. La classe fornisce retrieve(input, depth) e generate(input, context), più count_tokens(passage) quando imposta un token_budget. context è la lista degli oggetti Passage sopravvissuti a top_k e al budget, in ordine di rango. Oloproof registra da sé retrieval/v1, context/v1, citations/v1 e stage_timings/v1, e mette in cache ogni stadio separatamente. citations_path indica il campo dell'output che contiene gli id citati dalla risposta. Vedi RAG.

Valutatori

Tutte le classi sono in oloproof.evaluators. Il criterion di ciascuna nomina la metrica che produce. Quali artefatti legge ciascuna, e il suo equivalente YAML, sono nella tabella dei valutatori del Riferimento della configurazione.

provider è "anthropic", "openai" o "openai_compatible". Un giudice legge la sua chiave dalla variabile d'ambiente indicata da api_key_env (ANTHROPIC_API_KEY o OPENAI_API_KEY per impostazione predefinita) e viene fatturato da quel provider. Groundedness e CitationSupport accettano le altre impostazioni di RubricJudge tramite **options. Il giudice di probabilità, il classificatore basato su modello e la cascata non hanno una classe nell'SDK; esistono solo in YAML.

ConversationCompleted e ConversationJudge leggono un artefatto conversation/v1 che il tuo sistema registra. Oloproof non conduce la conversazione: la tua applicazione esegue ogni turno e registra la trascrizione. Vedi Agenti.

@evaluator

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

Avvolge una funzione di un argomento, il caso, in un CustomEvaluator. Il caso ha output, expected e scenario, e artifacts(name) restituisce i payload di un tipo registrato. La funzione può essere def o async def. Un valutatore binario restituisce True o False; un valutatore di punteggio dichiara value_type="score" e score_range=(low, high) e restituisce un numero. Un'eccezione sollevata dalla funzione registra il caso come mancante per quel criterio, mai come fallimento.

reads deve elencare ogni campo che la funzione legge (input, output, expected, metadata, metadata.<key> o artifacts.<name>), perché il giudizio in cache ha come chiave esattamente quelli. I giudizi vengono riutilizzati tra le esecuzioni solo con cacheable=True. Il sorgente del modulo che la definisce entra nella versione, quindi modificarlo li invalida. YAML non può indicare un valutatore personalizzato.

Diagnosi

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

Riesegue i casi falliti di un'esecuzione memorizzata sotto un intervento: "gold-context", "top-k" (con top_k) o "reranker" (con reranker). system e evaluators devono essere le versioni usate dall'esecuzione; una versione diversa viene rifiutata prima che qualcosa venga eseguito. Con control=True un nuovo campione di controllo gira accanto all'intervento, così che un cambiamento possa essere distinto dalla variazione tra un'esecuzione e l'altra. diagnose è la forma sincrona e dentro un loop in esecuzione si comporta come evaluate. Vedi RAG per il flusso di lavoro.

InterventionResult contiene l'id dell'esecuzione padre, l'intervento, se era supportato, le esecuzioni di intervento e di controllo, un esito per caso, e un DiagnosisReport di voci CaseDiagnosis quando ne è stato prodotto uno.

Replay degli agenti

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

Il replay è qualcosa che fa il tuo sistema, non qualcosa che Oloproof simula. Un sistema lo supporta solo implementando async def replay(self, trajectory, *, checkpoint, change) -> AgentTrajectory, che restituisce ciò che l'agente ha fatto dal checkpoint in poi; Oloproof vi innesta il prefisso registrato e confronta. La tua applicazione gestisce il proprio stato, le sessioni e gli effetti collaterali degli strumenti, compreso il loro ripristino prima di un replay. supports_replay riporta se un sistema dichiara il metodo.

replay_case è una coroutine: attendila con await, o chiamala tramite asyncio.run. Esegue un controllo (lo stesso checkpoint con ReplayChange(kind="resume")) prima del replay, e non tenta il replay quando il controllo non riproduce la registrazione. change è ReplayChange(kind="drop_step", step_index=...) o ReplayChange(kind="resume"). checkpoint_for sceglie l'ultimo checkpoint registrato strettamente prima di un passo, oppure None, nel qual caso l'esito viene scartato come no_checkpoint_recorded senza toccare il sistema.

ReplayOutcome porta scenario_id, change, gli stati terminali del replay e del controllo, e discarded con un motivo quando il caso non produce evidenze. Un caso scartato non è un caso fallito. label_case trasforma un esito in un CaseDiagnosis con una FailureLabel e la sua LabelReason; unnecessary_steps elenca i passi la cui rimozione ha lasciato intatto l'esito. Vedi Agenti.

Etichette umane e fiducia nei valutatori

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

Memorizza il verdetto di successo o fallimento di una persona su un caso di un'esecuzione memorizzata. Le etichette alimentano oloproof evaluators validate, che misura l'accordo di un giudice con esse (AgreementResult) e ne registra lo stato (RegistryEntry). Gli ulteriori argomenti measurement_sample_* legano un'etichetta a un campione di misura; oloproof labels export e oloproof labels import della CLI li compilano per te. Vedi Giudici.

Policy nel codice

ReleasePolicy, IntervalThresholdRule, ObservedCountRule e DecisionRule (l'unione delle due) costruiscono una policy senza un file. I loro campi sono i campi di release.yaml del Riferimento della configurazione; una regola su intervallo accetta direction (min o max) e threshold invece di min: o max:. Le regole di confronto non hanno una classe esportata; scrivile in release.yaml e passane il percorso.

from oloproof import IntervalThresholdRule, ReleasePolicy

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

Altre esportazioni