SDK 참조

oloproof와 oloproof.evaluators 패키지가 내보내는 모든 이름을, 시그니처, 동기인지 비동기인지, 그리고 반환하는 것과 함께 정리합니다. 안내형 소개를 원하면 먼저 Python API를 읽으세요.

공개 인터페이스는 이 두 패키지뿐입니다. oloproof_core에서 가져오는 것은 모두 엔진 내부이며 예고 없이 바뀔 수 있습니다. 아래의 모든 함수는 프로젝트의 저장소에 대해 로컬에서 실행됩니다. 여러분이 넘긴 평가기가 모델 제공자를 호출하지 않는 한, 어느 함수도 데이터를 어디로도 보내지 않습니다.

평가 실행하기

evaluate와 aevaluate

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

evaluate는 동기입니다. 실행 중인 이벤트 루프가 없을 때 호출하면 asyncio.run을 쓰고, 실행 중인 루프 안(노트북, 비동기 테스트)에서 호출하면 별도 스레드에서 평가를 실행하고 끝날 때까지 블록하므로, 두 곳 모두에서 안전합니다. aevaluate는 코루틴이므로 비동기 코드에서 await하세요.

나머지 키워드 인수(metrics, store, predictive, event_sink, retry_policy, traffic_draw_id)는 oloproof_core의 엔진 타입을 받으며 안정적인 인터페이스에 속하지 않습니다.

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)

케이스 두 개짜리 스위트에서 정책 없이 실행하면 다음을 출력했습니다.

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

상태, 이유 코드, 개수의 의미는 결과와 실행에 있습니다.

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

같은 스위트에서 두 시스템을 시드가 고정된 하나의 순서로 실행하고, 정책의 비교 규칙을 결정합니다. policy는 필수이며 superiority, non_inferiority 또는 equivalence 규칙을 하나 이상 담아야 하고, 그렇지 않으면 호출이 구성 오류를 일으킵니다. 추가 키워드 인수는 concurrency, replicates, 그리고 엔진 타입인 metrics, store, retry_policy입니다. 동기와 비동기 동작은 evaluate와 같습니다.

ComparisonEvaluationResult에는 candidate와 baseline(각각 EvaluationResult), 그리고 짝지은 차이와 그 결정을 담은 comparison이 있습니다. 두 버전 비교하기를 보세요.

시스템 선언하기

@system

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

인수 없이(@system) 또는 인수와 함께(@system(name=..., version=...)) 쓰거나, 객체에 대해 호출할 수 있습니다(system(model.answer, version="v2")). 함수는 케이스 전체가 아니라 케이스의 input 객체를 받고, 평가기가 읽는 출력을 반환합니다. def나 async def 모두 가능하며, 동기 함수는 워커 스레드에서 실행됩니다.

함수가 속한 모듈의 소스가 버전 다이제스트에 들어가므로, 수정하면 캐시된 실행이 무효화됩니다. 그 밖에 무엇이 영향을 주고 무엇이 주지 않는지는 구성 참조를 보세요.

current_case

def current_case() -> CaseRecorder

Oloproof가 시스템을 호출하는 동안에만 사용할 수 있으며, 다른 곳에서는 RuntimeError를 일으킵니다. 기록기의 메서드는 다음과 같습니다.

각 메서드는 ArtifactRef를 반환합니다(usage는 아무것도 반환하지 않습니다). 이 레코드를 만들기 위한 타입 페이로드도 내보냅니다. Retrieval, Passage, Context, ContextItem, DroppedItem, Citations, StageTimings, AgentTrajectory, AgentStep, AgentCheckpoint, AgentConstraintCheck, 그리고 종류 이름 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")

클래스 데코레이터입니다. 클래스는 retrieve(input, depth)와 generate(input, context)를 제공하고, token_budget을 설정하면 count_tokens(passage)도 제공합니다. context는 top_k와 예산을 통과한 Passage 객체의 리스트로, 순위 순서입니다. Oloproof는 retrieval/v1, context/v1, citations/v1, stage_timings/v1을 스스로 기록하고, 각 단계를 따로 캐시합니다. citations_path는 답변이 인용하는 id를 담은 출력 필드를 가리킵니다. RAG를 보세요.

평가기

모든 클래스는 oloproof.evaluators에 있습니다. 각각의 criterion은 그것이 만드는 지표의 이름입니다. 각 평가기가 어떤 아티팩트를 읽는지와 YAML 대응은 구성 참조의 평가기 표에 있습니다.

provider는 "anthropic", "openai" 또는 "openai_compatible"입니다. 심사 모델은 api_key_env가 가리키는 환경 변수(기본값은 ANTHROPIC_API_KEY 또는 OPENAI_API_KEY)에서 키를 읽으며, 요금은 그 제공자가 청구합니다. Groundedness와 CitationSupport는 RubricJudge의 나머지 설정을 **options로 받습니다. 확률 심사 모델, 모델 분류기, 캐스케이드에는 SDK 클래스가 없으며 YAML에만 있습니다.

ConversationCompleted와 ConversationJudge는 시스템이 기록한 conversation/v1 아티팩트를 읽습니다. Oloproof는 대화를 진행하지 않습니다. 애플리케이션이 모든 턴을 실행하고 대화 기록을 남깁니다. 에이전트를 보세요.

@evaluator

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

인수 하나(케이스)를 받는 함수를 CustomEvaluator로 감쌉니다. 케이스에는 output, expected, scenario가 있고, artifacts(name)은 기록된 종류의 페이로드를 반환합니다. 함수는 def나 async def 모두 가능합니다. 이진 평가기는 True 또는 False를 반환하고, 점수 평가기는 value_type="score"와 score_range=(low, high)를 선언하고 숫자를 반환합니다. 함수가 일으킨 예외는 그 기준에 대해 케이스를 누락으로 기록하며, 실패로 기록하는 일은 없습니다.

reads에는 함수가 읽는 모든 필드(input, output, expected, metadata, metadata.<key> 또는 artifacts.<name>)를 나열해야 합니다. 캐시된 판정이 정확히 그 필드들을 키로 삼기 때문입니다. 판정은 cacheable=True일 때만 실행 사이에 재사용됩니다. 정의한 모듈의 소스가 버전에 들어가므로, 수정하면 판정이 무효화됩니다. YAML에서는 사용자 정의 평가기를 지정할 수 없습니다.

진단

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

저장된 실행의 실패한 케이스를 하나의 개입 아래에서 다시 실행합니다. 개입은 "gold-context", "top-k"(top_k와 함께) 또는 "reranker"(reranker와 함께)입니다. system과 evaluators는 실행이 사용한 버전이어야 하며, 다른 버전은 무엇이든 실행되기 전에 거부됩니다. control=True이면 새 대조 표본이 개입과 나란히 실행되므로, 변화를 실행 간 변동과 구별할 수 있습니다. diagnose는 동기 형태이며, 실행 중인 루프 안에서 evaluate와 같이 동작합니다. 작업 흐름은 RAG를 보세요.

InterventionResult는 부모 실행 id, 개입, 그것이 지원되었는지 여부, 개입 실행과 대조 실행, 케이스별 결과, 그리고 생성된 경우 CaseDiagnosis 항목으로 이루어진 DiagnosisReport를 담습니다.

에이전트 재생

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

재생은 Oloproof가 시뮬레이션하는 것이 아니라 여러분의 시스템이 하는 일입니다. 시스템은 async def replay(self, trajectory, *, checkpoint, change) -> AgentTrajectory를 구현해야만 재생을 지원하며, 체크포인트 이후 에이전트가 한 일을 반환합니다. Oloproof는 기록된 앞부분을 이어 붙이고 비교합니다. 상태, 세션, 도구의 부수 효과는 애플리케이션이 소유하며, 재생 전에 그것을 초기화하는 일도 포함됩니다. supports_replay는 시스템이 그 메서드를 선언하는지 보고합니다.

replay_case는 코루틴입니다. await하거나 asyncio.run으로 호출하세요. 재생 전에 대조(같은 체크포인트에 ReplayChange(kind="resume"))를 실행하며, 대조가 기록을 재현하지 못하면 재생을 시도하지 않습니다. change는 ReplayChange(kind="drop_step", step_index=...) 또는 ReplayChange(kind="resume")입니다. checkpoint_for는 어떤 단계보다 엄격히 앞선 가장 최근의 기록된 체크포인트를 고르거나 None을 반환하며, 그 경우 결과는 시스템을 건드리지 않고 no_checkpoint_recorded로 폐기됩니다.

ReplayOutcome은 scenario_id, change, 재생과 대조의 최종 상태, 그리고 케이스가 증거를 내지 못할 때 이유와 함께 discarded를 담습니다. 폐기된 케이스는 실패한 케이스가 아닙니다. label_case는 결과를 FailureLabel과 그 LabelReason을 가진 CaseDiagnosis로 바꿉니다. unnecessary_steps는 제거해도 결과가 그대로인 단계를 나열합니다. 에이전트를 보세요.

사람 레이블과 평가기 신뢰

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

저장된 실행의 케이스 하나에 대한 한 사람의 통과/실패 판정을 저장합니다. 레이블은 oloproof evaluators validate에 쓰이며, 이 명령은 레이블에 대한 심사 모델의 일치도를 측정하고(AgreementResult) 그 상태를 기록합니다(RegistryEntry). 그 밖의 measurement_sample_* 인수는 레이블을 측정 표본에 묶으며, CLI의 oloproof labels export와 oloproof labels import가 이를 대신 채워 줍니다. 심사 모델을 보세요.

코드로 작성하는 정책

ReleasePolicy, IntervalThresholdRule, ObservedCountRule, DecisionRule(앞의 둘의 합집합)로 파일 없이 정책을 만듭니다. 필드는 구성 참조의 release.yaml 필드와 같습니다. 구간 규칙은 min:이나 max: 대신 direction(min 또는 max)과 threshold를 받습니다. 비교 규칙에는 내보낸 클래스가 없으니, release.yaml에 작성하고 그 경로를 넘기세요.

from oloproof import IntervalThresholdRule, ReleasePolicy

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

그 밖의 내보낸 이름