Référence du SDK

Chaque nom qu’exportent les paquets oloproof et oloproof.evaluators, avec sa signature, son caractère synchrone ou asynchrone, et ce qu’il renvoie. Pour une introduction guidée, lisez d’abord L’API Python.

Seuls ces deux paquets constituent la surface publique. Tout ce qui est importé de oloproof_core relève des rouages internes du moteur et peut changer sans préavis. Chaque fonction ci-dessous s’exécute en local sur le magasin du projet ; aucune n’envoie de données où que ce soit, sauf si un évaluateur que vous passez appelle un fournisseur de modèles.

Lancer une évaluation

evaluate et aevaluate

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

evaluate est synchrone. Appelée sans boucle d’événements active, elle utilise asyncio.run ; appelée depuis une boucle active (un notebook, un test asynchrone), elle exécute l’évaluation sur un fil séparé et bloque jusqu’à la fin, si bien qu’elle est sûre dans les deux cas. aevaluate est la coroutine ; attendez-la avec await depuis du code asynchrone.

Les arguments nommés restants (metrics, store, predictive, event_sink, retry_policy, traffic_draw_id) prennent des types du moteur issus de oloproof_core et ne font pas partie de la surface stable.

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)

Exécuté sur une suite de deux cas sans politique, cela a affiché :

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

Ce que signifient les états, les codes de raison et les effectifs se trouve dans Résultats et exécution.

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

Exécute les deux systèmes sur la même suite dans un même ordre fixé par une graine et décide les règles de comparaison de la politique. policy est obligatoire et doit contenir au moins une règle superiority, non_inferiority ou equivalence, sinon l’appel lève une erreur de configuration. Arguments nommés supplémentaires : concurrency, replicates, et metrics, store et retry_policy, typés par le moteur. Les comportements synchrone et asynchrone sont ceux de evaluate.

ComparisonEvaluationResult a candidate et baseline (chacun un EvaluationResult) et comparison, qui porte les différences appariées et leurs décisions. Voyez Comparer deux versions.

Déclarer un système

@system

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

Utilisable nu (@system) ou avec des arguments (@system(name=..., version=...)), ou appelé sur un objet (system(model.answer, version="v2")). La fonction reçoit l’objet input du cas, et non le cas entier, et renvoie la sortie que lisent les évaluateurs. Elle peut être def ou async def ; une fonction synchrone s’exécute sur un fil de travail.

Le source du module de la fonction entre dans l’empreinte de la version, si bien que le modifier invalide les exécutions en cache. Voyez la Référence de configuration pour ce qui l’invalide aussi et ce qui ne l’invalide pas.

current_case

def current_case() -> CaseRecorder

Disponible seulement pendant qu’Oloproof appelle votre système ; ailleurs, elle lève RuntimeError. Les méthodes de l’enregistreur :

Chacune renvoie un ArtifactRef (sauf usage, qui ne renvoie rien). Les charges typées sont exportées pour construire ces enregistrements : Retrieval, Passage, Context, ContextItem, DroppedItem, Citations, StageTimings, AgentTrajectory, AgentStep, AgentCheckpoint, AgentConstraintCheck, et le nom de sorte 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 décorateur de classe. La classe fournit retrieve(input, depth) et generate(input, context), plus count_tokens(passage) quand elle fixe un token_budget. context est la liste des objets Passage qui ont survécu à top_k et au budget, dans l’ordre du classement. Oloproof enregistre lui-même retrieval/v1, context/v1, citations/v1 et stage_timings/v1, et met chaque étape en cache séparément. citations_path nomme le champ de sortie qui contient les identifiants que cite la réponse. Voyez Évaluation RAG.

Évaluateurs

Toutes les classes sont dans oloproof.evaluators. Le criterion de chacune nomme la métrique qu’elle produit. Les artefacts que lit chacune, et son équivalent YAML, sont dans le tableau des évaluateurs de la Référence de configuration.

provider vaut "anthropic", "openai" ou "openai_compatible". Un juge lit sa clé dans la variable d’environnement que nomme api_key_env (ANTHROPIC_API_KEY ou OPENAI_API_KEY par défaut) et est facturé par ce fournisseur. Groundedness et CitationSupport prennent le reste des réglages de RubricJudge via **options. Le juge probabiliste, le classifieur modèle et la cascade n’ont pas de classe dans le SDK ; ils n’existent qu’en YAML.

ConversationCompleted et ConversationJudge lisent un artefact conversation/v1 que votre système enregistre. Oloproof ne pilote pas la conversation : votre application exécute chaque tour et enregistre la transcription. Voyez Agents et outils.

@evaluator

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

Enveloppe une fonction d’un argument, le cas, dans un CustomEvaluator. Le cas a output, expected et scenario, et artifacts(name) renvoie les charges d’une sorte enregistrée. La fonction peut être def ou async def. Un évaluateur binaire renvoie True ou False ; un évaluateur de score déclare value_type="score" et score_range=(low, high) et renvoie un nombre. Une exception levée par la fonction enregistre le cas comme manquant pour ce critère, jamais comme un échec.

reads doit lister chaque champ que lit la fonction (input, output, expected, metadata, metadata.<key> ou artifacts.<name>), parce que le jugement en cache est indexé exactement sur ceux-là. Les jugements ne sont réutilisés d’une exécution à l’autre qu’avec cacheable=True. Le source du module qui la définit entre dans la version, si bien que le modifier les invalide. Le YAML ne peut pas nommer un évaluateur personnalisé.

Diagnostic

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

Réexécute les cas en échec d’une exécution stockée sous une intervention : "gold-context", "top-k" (avec top_k) ou "reranker" (avec reranker). system et evaluators doivent être les versions qu’a utilisées l’exécution ; une version différente est refusée avant toute exécution. Avec control=True, un échantillon de contrôle frais s’exécute à côté de l’intervention, si bien qu’on peut distinguer un changement de la variation d’une exécution à l’autre. diagnose est la forme synchrone et se comporte dans une boucle active comme evaluate. Voyez Évaluation RAG pour la démarche.

InterventionResult contient l’identifiant de l’exécution parente, l’intervention, si elle était prise en charge, les exécutions d’intervention et de contrôle, un résultat par cas, et un DiagnosisReport d’entrées CaseDiagnosis quand il en a été produit un.

Rejeu d’agent

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

Le rejeu est quelque chose que fait votre système, pas quelque chose qu’Oloproof simule. Un système ne le prend en charge qu’en implémentant async def replay(self, trajectory, *, checkpoint, change) -> AgentTrajectory, qui renvoie ce que l’agent a fait à partir du point de contrôle ; Oloproof y raccorde le préfixe enregistré et compare. Votre application possède son état, ses sessions et les effets de bord de ses outils, y compris leur réinitialisation avant un rejeu. supports_replay indique si un système déclare la méthode.

replay_case est une coroutine : attendez-la avec await, ou appelez-la via asyncio.run. Elle exécute un contrôle (le même point de contrôle avec ReplayChange(kind="resume")) avant le rejeu, et ne tente pas le rejeu quand le contrôle ne reproduit pas l’enregistrement. change vaut ReplayChange(kind="drop_step", step_index=...) ou ReplayChange(kind="resume"). checkpoint_for choisit le dernier point de contrôle enregistré strictement avant une étape, ou None, auquel cas le résultat est écarté comme no_checkpoint_recorded sans toucher au système.

ReplayOutcome porte scenario_id, change, les statuts terminaux du rejeu et du contrôle, et discarded avec une raison quand le cas ne produit aucune preuve. Un cas écarté n’est pas un cas en échec. label_case transforme un résultat en CaseDiagnosis avec un FailureLabel et son LabelReason ; unnecessary_steps liste les étapes dont la suppression a laissé le résultat intact. Voyez Agents et outils.

Étiquettes humaines et confiance dans les évaluateurs

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

Stocke le verdict réussite/échec d’une personne sur un cas d’une exécution stockée. Les étiquettes alimentent oloproof evaluators validate, qui mesure l’accord d’un juge avec elles (AgreementResult) et enregistre son statut (RegistryEntry). Les arguments supplémentaires measurement_sample_* lient une étiquette à un échantillon de mesure ; oloproof labels export et oloproof labels import de l’outil en ligne de commande les remplissent pour vous. Voyez Juges.

Les politiques dans le code

ReleasePolicy, IntervalThresholdRule, ObservedCountRule et DecisionRule (l’union des deux) construisent une politique sans fichier. Leurs champs sont les champs de release.yaml de la Référence de configuration ; une règle d’intervalle prend direction (min ou max) et threshold au lieu de min: ou max:. Les règles de comparaison n’ont pas de classe exportée ; écrivez-les dans release.yaml et passez son chemin.

from oloproof import IntervalThresholdRule, ReleasePolicy

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

Autres exports