Referencia del SDK

Cada nombre que exportan los paquetes oloproof y oloproof.evaluators, con su firma, si es síncrono o asíncrono, y lo que devuelve. Para una introducción guiada, lea primero La API de Python.

Solo estos dos paquetes son la superficie pública. Cualquier cosa importada de oloproof_core son internos del motor y puede cambiar sin aviso. Cada función de abajo se ejecuta en local contra el almacén del proyecto; ninguna envía datos a ningún sitio salvo que un evaluador que usted le pase llame a un proveedor de modelos.

Ejecutar una evaluación

evaluate y aevaluate

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

evaluate es síncrono. Llamado sin ningún bucle de eventos en marcha usa asyncio.run; llamado desde dentro de un bucle en marcha (un notebook, una prueba asíncrona) ejecuta la evaluación en un hilo aparte y se bloquea hasta que termina, así que es seguro en ambos sitios. aevaluate es la corrutina; espérela con await desde código asíncrono.

Los demás argumentos con nombre (metrics, store, predictive, event_sink, retry_policy, traffic_draw_id) toman tipos del motor de oloproof_core y no forman parte de la superficie estable.

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)

Ejecutado sobre una suite de dos casos sin política, imprimió:

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

Lo que significan los estados, los códigos de motivo y los conteos está en Resultados y ejecución.

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

Ejecuta ambos sistemas sobre la misma suite en un único orden con semilla y decide las reglas de comparación de la política. policy es obligatorio y debe contener al menos una regla superiority, non_inferiority o equivalence, o la llamada lanza un error de configuración. Argumentos con nombre adicionales: concurrency, replicates, y los de tipos del motor metrics, store y retry_policy. El comportamiento síncrono y asíncrono es como en evaluate.

ComparisonEvaluationResult tiene candidate y baseline (cada uno un EvaluationResult) y comparison, que lleva las diferencias emparejadas y sus decisiones. Consulte Comparar dos versiones.

Declarar un sistema

@system

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

Se puede usar sin argumentos (@system) o con ellos (@system(name=..., version=...)), o llamarse sobre un objeto (system(model.answer, version="v2")). La función recibe el objeto input del caso, no el caso entero, y devuelve la salida que leen los evaluadores. Puede ser def o async def; una función síncrona se ejecuta en un hilo de trabajo.

El código fuente del propio módulo de la función entra en el digest de la versión, así que editarlo invalida las ejecuciones en caché. Consulte la Referencia de configuración para saber qué más lo hace y qué no.

current_case

def current_case() -> CaseRecorder

Solo está disponible mientras Oloproof llama a su sistema; en cualquier otro sitio lanza RuntimeError. Los métodos del registrador:

Cada uno devuelve un ArtifactRef (salvo usage, que no devuelve nada). Las cargas tipadas se exportan para construir estos registros: Retrieval, Passage, Context, ContextItem, DroppedItem, Citations, StageTimings, AgentTrajectory, AgentStep, AgentCheckpoint, AgentConstraintCheck, y el nombre de 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 decorador de clase. La clase proporciona retrieve(input, depth) y generate(input, context), más count_tokens(passage) cuando fija un token_budget. context es la lista de objetos Passage que sobrevivieron a top_k y al presupuesto, en orden de ranking. Oloproof registra por sí mismo retrieval/v1, context/v1, citations/v1 y stage_timings/v1, y guarda en caché cada etapa por separado. citations_path nombra el campo de salida que contiene los ids que cita la respuesta. Consulte RAG.

Evaluadores

Todas las clases están en oloproof.evaluators. El criterion de cada una nombra la métrica que produce. Qué artefactos lee cada una, y su equivalente en YAML, están en la tabla de evaluadores de la Referencia de configuración.

provider es "anthropic", "openai" o "openai_compatible". Un juez lee su clave de la variable de entorno que nombra api_key_env (ANTHROPIC_API_KEY u OPENAI_API_KEY por defecto) y ese proveedor se lo factura. Groundedness y CitationSupport toman el resto de los ajustes de RubricJudge mediante **options. El juez de probabilidad, el clasificador modelo y la cascada no tienen clase en el SDK; solo existen en YAML.

ConversationCompleted y ConversationJudge leen un artefacto conversation/v1 que registra su sistema. Oloproof no conduce la conversación: su aplicación ejecuta cada turno y registra la transcripción. Consulte Agentes.

@evaluator

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

Envuelve una función de un argumento, el caso, en un CustomEvaluator. El caso tiene output, expected y scenario, y artifacts(name) devuelve las cargas de un tipo registrado. La función puede ser def o async def. Un evaluador binario devuelve True o False; un evaluador de puntuación declara value_type="score" y score_range=(low, high) y devuelve un número. Una excepción lanzada por la función registra el caso como faltante para ese criterio, nunca como un fallo.

reads debe enumerar cada campo que lee la función (input, output, expected, metadata, metadata.<key> o artifacts.<name>), porque el juicio en caché se indexa exactamente por ellos. Los juicios solo se reutilizan entre ejecuciones con cacheable=True. El código fuente del módulo que la define entra en la versión, así que editarlo los invalida. YAML no puede nombrar un evaluador personalizado.

Diagnóstico

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

Vuelve a ejecutar los casos fallidos de una ejecución almacenada bajo una intervención: "gold-context", "top-k" (con top_k) o "reranker" (con reranker). system y evaluators deben ser las versiones que usó la ejecución; una versión distinta se rechaza antes de que se ejecute nada. Con control=True se ejecuta una muestra de control nueva junto a la intervención, para poder distinguir un cambio de la variación entre ejecuciones. diagnose es la forma síncrona y se comporta dentro de un bucle en marcha como evaluate. Consulte RAG para el flujo de trabajo.

InterventionResult contiene el id de la ejecución de origen, la intervención, si estaba soportada, las ejecuciones de intervención y de control, un resultado por caso, y un DiagnosisReport de entradas CaseDiagnosis cuando se produjo uno.

Reproducción de agentes

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

La reproducción es algo que hace su sistema, no algo que Oloproof simule. Un sistema la admite solo implementando async def replay(self, trajectory, *, checkpoint, change) -> AgentTrajectory, que devuelve lo que hizo el agente desde el checkpoint en adelante; Oloproof empalma el prefijo registrado y compara. Su aplicación es dueña de su estado, sus sesiones y los efectos secundarios de sus herramientas, incluido restablecerlos antes de una reproducción. supports_replay indica si un sistema declara el método.

replay_case es una corrutina: espérela con await, o llámela mediante asyncio.run. Ejecuta un control (el mismo checkpoint con ReplayChange(kind="resume")) antes de la reproducción, y no intenta la reproducción cuando el control no reproduce lo registrado. change es ReplayChange(kind="drop_step", step_index=...) o ReplayChange(kind="resume"). checkpoint_for elige el último checkpoint registrado estrictamente anterior a un paso, o None, en cuyo caso el resultado se descarta como no_checkpoint_recorded sin tocar el sistema.

ReplayOutcome lleva scenario_id, change, los estados terminales de la reproducción y del control, y discarded con un motivo cuando el caso no aporta evidencia. Un caso descartado no es un caso fallido. label_case convierte un resultado en un CaseDiagnosis con un FailureLabel y su LabelReason; unnecessary_steps enumera los pasos cuya eliminación dejó intacto el resultado. Consulte Agentes.

Etiquetas humanas y confianza en los evaluadores

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

Almacena el veredicto de aprobado o fallo de una persona sobre un caso de una ejecución almacenada. Las etiquetas alimentan oloproof evaluators validate, que mide el acuerdo de un juez con ellas (AgreementResult) y registra su estado (RegistryEntry). Los argumentos adicionales measurement_sample_* vinculan una etiqueta a una muestra de medición; oloproof labels export y oloproof labels import de la CLI los rellenan por usted. Consulte Jueces.

Políticas en código

ReleasePolicy, IntervalThresholdRule, ObservedCountRule y DecisionRule (la unión de las dos) construyen una política sin archivo. Sus campos son los campos de release.yaml de la Referencia de configuración; una regla de intervalo toma direction (min o max) y threshold en lugar de min: o max:. Las reglas de comparación no tienen clase exportada; escríbalas en release.yaml y pase su ruta.

from oloproof import IntervalThresholdRule, ReleasePolicy

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

Otras exportaciones