import { ReadableSpan, SpanProcessor } from "@opentelemetry/sdk-trace-base"; import { Context, Span as Span$1 } from "@opentelemetry/api"; //#region src/evals/Evaluator.d.ts /** * Base class for evaluators. * * Subclasses should: * - Set a `static evaluatorName` if they want a stable, minification-proof * registry key (otherwise the class's runtime `name` is used). * - Implement `evaluate(ctx)` returning a boolean (assertion) / number (score) * / string (label) / `EvaluationReason` / map of any of those. * - Optionally implement `toJSON()` returning the constructor args used for * serialization to YAML / JSON dataset files. */ declare abstract class Evaluator { static evaluatorName?: string; /** Optional override for the result name in the report (defaults to class name). */ evaluationName?: string; /** Optional version string propagated to `gen_ai.evaluation.evaluator.version`. */ evaluatorVersion?: string; abstract evaluate(ctx: EvaluatorContext): EvaluatorOutput | Promise; /** Resolved name used as the dictionary key in `case.scores | labels | assertions`. */ getResultName(): string; /** Wire-format spec used in the `source` field of `EvaluationResult` and in YAML. */ getSpec(): EvaluatorSpec; /** * Optional. Implement to return the constructor arguments used to recreate * this instance from a YAML / JSON dataset file. Should exclude fields equal * to their declared default. * * Default returns `null` (no arguments) — appropriate for parameterless evaluators. */ toJSON(): null | Record | unknown[]; } //#endregion //#region src/evals/Case.d.ts interface CaseOptions { evaluators?: readonly Evaluator[]; expectedOutput?: Output; inputs: Inputs; metadata?: Metadata; name?: string; } /** * One example for a `Dataset` to evaluate. Holds inputs, an optional * expected output, free-form metadata, and any case-specific evaluators. */ declare class Case { readonly evaluators: readonly Evaluator[]; readonly expectedOutput?: Output; readonly inputs: Inputs; readonly metadata?: Metadata; readonly name?: string; constructor(opts: CaseOptions); } //#endregion //#region src/evals/ReportEvaluator.d.ts /** Discriminated union of analysis outputs report evaluators may emit. */ type ReportAnalysis = ConfusionMatrixAnalysis | LinePlotAnalysis | PrecisionRecallAnalysis | ScalarAnalysis | TableAnalysis; interface ConfusionMatrixAnalysis { class_labels: string[]; description?: string; matrix: number[][]; title: string; type: "confusion_matrix"; } interface PrecisionRecallAnalysis { curves: { auc?: number; name: string; points: { precision: number; recall: number; threshold: number; }[]; }[]; description?: string; title: string; type: "precision_recall"; } type ROCAnalysis = LinePlotAnalysis; type KSAnalysis = LinePlotAnalysis; interface ScalarAnalysis { description?: string; title: string; type: "scalar"; unit?: string; value: number; } interface TableAnalysis { columns: string[]; rows: (number | string)[][]; title: string; type: "table"; } interface LinePlotAnalysis { curves: { name: string; points: { x: number; y: number; }[]; step?: "end" | "middle" | "start"; style?: "dashed" | "solid"; }[]; description?: string; title: string; type: "line_plot"; x_label: string; x_range?: [number, number]; y_label: string; y_range?: [number, number]; } interface ReportEvaluatorContext { cases: readonly (ReportCase | ReportCaseFailure)[]; experimentMetadata?: Record; name: string; report: EvaluationReport; } declare abstract class ReportEvaluator { static evaluatorName?: string; evaluatorVersion?: string; abstract evaluate(ctx: ReportEvaluatorContext): Promise | ReportAnalysis | ReportAnalysis[]; getSpec(): EvaluatorSpec; toJSON(): null | Record | unknown[]; } //#endregion //#region src/evals/reporting.d.ts interface ReportCase { assertions: Record; attributes: Record; evaluator_failures: EvaluatorFailureRecord[]; expected_output?: Output; inputs: Inputs; labels: Record; metadata?: Metadata; metrics: Record; name: string; output: Output; scores: Record; source_case_name?: string; span_id: null | string; task_duration: number; total_duration: number; trace_id: null | string; } interface ReportCaseFailure { error_message: string; error_stacktrace?: string; error_type: string; expected_output?: Output; inputs: Inputs; metadata?: Metadata; name: string; source_case_name?: string; span_id: null | string; trace_id: null | string; } interface EvaluationReport { analyses: ReportAnalysis[]; cases: ReportCase[]; experiment_metadata?: Record; failures: ReportCaseFailure[]; name: string; report_evaluator_failures: EvaluatorFailureRecord[]; span_id: null | string; trace_id: null | string; } interface ReportCaseAggregate { assertions: null | number; labels: Record>; metrics: Record; name: string; scores: Record; task_duration: number; total_duration: number; } /** * A group of runs that share a `source_case_name`. Computed view returned by * `caseGroups()` for multi-run experiments (mirrors Python's `ReportCaseGroup`). */ interface ReportCaseGroup { expected_output?: Output; failures: ReportCaseFailure[]; inputs: Inputs; metadata?: Metadata; name: string; runs: ReportCase[]; summary: ReportCaseAggregate; } /** * Compute `assertion_pass_rate` across the cases. Returns `null` if there are * no assertions. */ declare function computeAssertionPassRate(cases: readonly ReportCase[]): null | number; /** * Compute the `averages` block stored under `logfire.experiment.metadata.averages`. * Required by the platform's sort-by-pass-rate UI. */ declare function computeAverages(name: string, cases: readonly ReportCase[]): ReportCaseAggregate; /** * Group runs by `source_case_name` and compute per-group aggregates. Returns * `undefined` when no case or failure has a `source_case_name` set (i.e., a * single-run experiment). Mirrors Python's `EvaluationReport.case_groups()`. */ declare function caseGroups(report: EvaluationReport): ReportCaseGroup[] | undefined; /** * Average across already-aggregated cases. Used to roll multi-run group * summaries up into a single experiment-wide aggregate. Mirrors Python's * `ReportCaseAggregate.average_from_aggregates`. * * For each key, only aggregates that contain the key contribute (so a key * present in 2/3 aggregates averages over 2 entries). Counts are summed. */ declare function averageFromAggregates(name: string, aggregates: readonly ReportCaseAggregate[]): ReportCaseAggregate; /** * Compute the experiment-wide aggregate for a report. For multi-run reports * (any case has `source_case_name`), uses two-level aggregation: average each * source-case group, then average the group summaries. For single-run reports, * averages the cases directly. Returns `undefined` if there are no cases. * * Mirrors Python's `EvaluationReport.averages()`. */ declare function averages(report: EvaluationReport): ReportCaseAggregate | undefined; //#endregion //#region src/evals/CaseLifecycle.d.ts /** * Per-case lifecycle hook. Pass the **class** (not an instance) to * `Dataset.evaluate({ lifecycle: MyLifecycle })` and the driver will * instantiate one per case. * * Mirrors pydantic-evals' `CaseLifecycle`. */ declare abstract class CaseLifecycle { protected case: Case; constructor(c: Case); /** * Runs between the task and the evaluators. Return a (potentially modified) * `EvaluatorContext` to be passed to the evaluators. */ prepareContext?(ctx: EvaluatorContext): EvaluatorContext | Promise>; /** Runs before the task. Useful for setting up per-case state. */ setup?(): Promise | void; /** Always runs, even when the task or an evaluator throws. */ teardown?(result: ReportCase | ReportCaseFailure): Promise | void; } type CaseLifecycleClass = new (c: Case) => CaseLifecycle; //#endregion //#region src/evals/spanTree/SpanTree.d.ts declare class SpanTreeRecordingError extends Error { constructor(message?: string); } declare class SpanNode { attributes: Record; children: SpanNode[]; durationMs: number; endTimeNs: number; name: string; parent: null | SpanNode; parentSpanId?: string; spanId: string; startTimeNs: number; traceId: string; constructor(span: ReadableSpan); ancestors(): Generator; descendants(): Generator; matches(query: SpanQuery): boolean; } interface SpanQuery { all_ancestors_have?: SpanQuery; all_children_have?: SpanQuery; all_descendants_have?: SpanQuery; allAncestorsHave?: SpanQuery; allChildrenHave?: SpanQuery; allDescendantsHave?: SpanQuery; and_?: SpanQuery[]; has_attribute_keys?: string[]; has_attributes?: Record; hasAttributeKeys?: string[]; hasAttributes?: Record; max_child_count?: number; max_depth?: number; max_descendant_count?: number; /** Max duration in seconds. */ max_duration?: number; maxChildCount?: number; maxDescendantCount?: number; /** @deprecated Use max_duration. Values are interpreted as seconds for Python parity. */ maxDuration?: number; min_child_count?: number; min_depth?: number; min_descendant_count?: number; /** Min duration in seconds. */ min_duration?: number; minChildCount?: number; minDescendantCount?: number; /** @deprecated Use min_duration. Values are interpreted as seconds for Python parity. */ minDuration?: number; name_contains?: string; name_equals?: string; name_matches_regex?: string; nameContains?: string; nameEquals?: string; nameMatchesRegex?: string; no_ancestor_has?: SpanQuery; no_child_has?: SpanQuery; no_descendant_has?: SpanQuery; noAncestorHas?: SpanQuery; noChildHas?: SpanQuery; noDescendantHas?: SpanQuery; not_?: SpanQuery; or_?: SpanQuery[]; some_ancestor_has?: SpanQuery; some_child_has?: SpanQuery; some_descendant_has?: SpanQuery; someAncestorHas?: SpanQuery; someChildHas?: SpanQuery; someDescendantHas?: SpanQuery; stop_recursing_when?: SpanQuery; stopRecursingWhen?: SpanQuery; } declare function spanQueryToSnakeCase(query: SpanQuery): SpanQuery; declare class SpanTree { readonly roots: SpanNode[]; /** Set when the user-provided custom OTel provider didn't allow processor installation. */ private readonly recordingError; constructor(roots?: SpanNode[], recordingError?: null | SpanTreeRecordingError); static fromError(err: SpanTreeRecordingError): SpanTree; static fromSpans(spans: ReadableSpan[]): SpanTree; all(): Generator; any(query: SpanQuery): boolean; /** Throws if span-tree recording wasn't available. Mirrors Python's `span_tree` property. */ ensureAvailable(): void; find(query: SpanQuery): SpanNode[]; first(query: SpanQuery): null | SpanNode; } //#endregion //#region src/evals/types.d.ts /** * The serialized identity of an evaluator instance, used for the wire-format * `source` field on EvaluationResult and for round-tripping YAML / JSON. * * Mirrors pydantic-evals' `EvaluatorSpec`. */ interface EvaluatorSpec { arguments: null | Record | unknown[]; name: string; } /** Reason explanation paired with a scalar evaluator output. */ interface EvaluationReason { reason?: string; value: boolean | number | string; } /** * The raw shape an evaluator's `evaluate()` may return. The driver * post-processes this into `EvaluationResult[]`. */ type EvaluatorOutput = boolean | EvaluationReason | number | Record | string; /** * The wire-format JSON shape the platform frontend strict-parses with Zod. * Anything we put in `case.scores | labels | assertions` must look like this. */ interface EvaluationResultJson { evaluator_version?: string; name: string; reason: null | string; source: EvaluatorSpec; value: boolean | number | string; } interface EvaluatorContext { readonly attributes: Record; readonly duration: number; readonly expectedOutput?: Output; readonly inputs: Inputs; readonly metadata?: Metadata; readonly metrics: Record; readonly name?: string; readonly output: Output; /** * Captured tree of spans emitted under `execute {task}`. Throws * `SpanTreeRecordingError` on access if span-tree capture wasn't installed. */ readonly spanTree: SpanTree; } interface EvaluatorClass { evaluatorName?: string; new (...args: never[]): Evaluator; } interface ReportEvaluatorClass { evaluatorName?: string; new (...args: never[]): ReportEvaluator; } /** * Mutable per-case execution state. Lives in an `AsyncLocalStorage`-managed * context for the duration of a case run. Used by `setEvalAttribute` / * `incrementEvalMetric`. */ interface TaskRunState { attributes: Record; /** Stable random ID used by the span-tree exporter to scope captured spans. */ exporterContextId: string; metrics: Record; } /** Internal — failure record produced when an evaluator throws. */ interface EvaluatorFailureRecord { error_message: string; error_stacktrace?: string; error_type: string; evaluator_version?: string; name: string; source: EvaluatorSpec; } /** * Retry config — passed to `p-retry`. See https://github.com/sindresorhus/p-retry * for the full option set; only the most common options are documented here. */ interface RetryConfig { factor?: number; maxTimeout?: number; minTimeout?: number; retries?: number; } /** * Options accepted by `Dataset.evaluate`. Mirrors pydantic-evals' * `Dataset.evaluate(...)` kwargs but with TS-idiomatic naming. */ interface EvaluateOptions { _phantomInputs?: Inputs; _phantomMetadata?: Metadata; _phantomOutput?: Output; /** Per-case lifecycle hooks — pass the class, not an instance. */ lifecycle?: CaseLifecycleClass; /** Bound concurrent case execution with a semaphore. Undefined = unbounded. */ maxConcurrency?: number; /** User-provided experiment metadata — surfaces as a top-level `metadata` attribute. */ metadata?: Record; /** Override the experiment name (defaults to dataset.name). */ name?: string; /** Progress reporter. `true` = default stderr reporter, callback = custom, `false`/undefined = silent. */ progress?: ((event: { caseName: string; done: number; total: number; }) => void) | boolean; /** Number of times to repeat each case (default 1). */ repeat?: number; /** Retry config for evaluator runs. */ retryEvaluators?: RetryConfig; /** Retry config for the user's task. Powered by `p-retry`. */ retryTask?: RetryConfig; /** Cancel an evaluation. Cases not yet started are skipped; in-flight tasks are not interrupted automatically. */ signal?: AbortSignal; /** Override the task display name (defaults to function.name). */ taskName?: string; } //#endregion //#region src/evals/builtins/Contains.d.ts /** * True iff `output` contains `value`. Supports strings (substring), arrays * (element membership), and objects (key membership / value match). * * Mirrors pydantic-evals' `Contains` evaluator behaviour at * `evaluators/common.py:64–141`. */ declare class Contains extends Evaluator { static override evaluatorName: string; readonly asStrings: boolean; readonly caseSensitive: boolean; readonly value: unknown; constructor(opts: { as_strings?: boolean; asStrings?: boolean; case_sensitive?: boolean; caseSensitive?: boolean; evaluation_name?: string; evaluationName?: string; value: unknown; }); static jsonSchema(): Record; evaluate(ctx: EvaluatorContext): EvaluationReason; override toJSON(): Record; private check; } //#endregion //#region src/evals/builtins/Equals.d.ts /** True iff `output` is structurally equal to a fixed `value`. */ declare class Equals extends Evaluator { static override evaluatorName: string; readonly value: unknown; constructor(opts: { evaluation_name?: string; evaluationName?: string; value: unknown; }); static jsonSchema(): Record; evaluate(ctx: EvaluatorContext): boolean; override toJSON(): Record; } declare function deepEqual(a: unknown, b: unknown): boolean; //#endregion //#region src/evals/builtins/EqualsExpected.d.ts /** * True iff `output === expectedOutput`. If the case has no expected output, * returns an empty mapping (no result emitted) — same as Python pydantic-evals. */ declare class EqualsExpected extends Evaluator { static override evaluatorName: string; constructor(opts?: { evaluation_name?: string; evaluationName?: string; }); static jsonSchema(): Record; evaluate(ctx: EvaluatorContext): EvaluatorOutput; override toJSON(): null | Record; } //#endregion //#region src/evals/spanTree/exporter.d.ts /** * `SpanProcessor` that snapshots ended spans into per-context-id buckets. * Each `Dataset.evaluate` case allocates a bucket, runs the user's task with * the bucket's ID set on the active OTel context, then drains the bucket and * builds a `SpanTree`. */ declare class EvalsSpanProcessor implements SpanProcessor { private readonly buckets; /** Pop and return the spans captured for a bucket. */ drainBucket(id: string): ReadableSpan[]; forceFlush(): Promise; onEnd(span: ReadableSpan): void; onStart(span: ReadableSpan, parentContext: Context): void; /** Allocate a fresh bucket and return its ID. */ openBucket(id: string): void; /** Wrap `fn` in a context that carries `bucketId`, so any spans started inside are captured. */ runWithBucket(bucketId: string, fn: () => Promise | R): Promise | R; shutdown(): Promise; } /** * Get the singleton evals span processor. Pass it to a custom `TracerProvider` * via `addSpanProcessor(getEvalsSpanProcessor())` if you're not using `logfire.configure()`. */ declare function getEvalsSpanProcessor(): EvalsSpanProcessor; //#endregion //#region src/evals/builtins/HasMatchingSpan.d.ts /** True iff a span matching `query` was emitted under the user's task. */ declare class HasMatchingSpan extends Evaluator { static override evaluatorName: string; readonly query: SpanQuery; constructor(opts: { evaluation_name?: string; evaluationName?: string; query: SpanQuery; }); static jsonSchema(): Record; evaluate(ctx: EvaluatorContext): boolean; override toJSON(): Record; } //#endregion //#region src/evals/builtins/IsInstance.d.ts /** * True iff the runtime constructor name (or one of its prototype-chain ancestors) * matches `typeName`. This is the closest TS analogue of Python's MRO walk on * class names. */ declare class IsInstance extends Evaluator { static override evaluatorName: string; readonly typeName: string; constructor(opts: { evaluation_name?: string; evaluationName?: string; type_name?: string; typeName?: string; }); static jsonSchema(): Record; evaluate(ctx: EvaluatorContext): EvaluationReason; override toJSON(): Record; } //#endregion //#region src/evals/builtins/LLMJudge.d.ts /** * Per-output-channel config for `LLMJudge`. `false` disables the channel. */ interface LLMJudgeOutputConfig { evaluation_name?: string; evaluationName?: string; include_reason?: boolean; includeReason?: boolean; } /** * The result of a judge invocation. Mirrors pydantic-evals' * `GradingOutput`-shaped dict. */ interface JudgeResult { pass: boolean; reason?: string; score: number; } type JudgeFn = (args: { expectedOutput?: unknown; inputs: unknown; output: unknown; rubric: string; }) => JudgeResult | Promise; /** * Set a process-wide default judge for `LLMJudge` instances that don't pass * their own callback. Useful for shipping a single model client across all * evaluations. */ declare function setDefaultJudge(fn: JudgeFn): void; declare function getDefaultJudge(): JudgeFn | null; /** * LLM-as-judge evaluator. Takes a `rubric`, hands it (plus the case output and * optionally inputs / expected output) to a user-provided judge function, and * emits a score and/or assertion based on the judge's verdict. * * BYO judge (no model client is bundled with logfire-js). Either pass a * `judge` callback per instance or call `setDefaultJudge(fn)` once at startup. */ declare class LLMJudge extends Evaluator { static override evaluatorName: string; readonly assertion: false | LLMJudgeOutputConfig; readonly includeExpectedOutput: boolean; readonly includeInput: boolean; readonly judge?: JudgeFn; readonly rubric: string; readonly score: false | LLMJudgeOutputConfig; private readonly assertionWasProvided; private readonly scoreWasProvided; constructor(opts: { assertion?: false | LLMJudgeOutputConfig; include_expected_output?: boolean; include_input?: boolean; includeExpectedOutput?: boolean; includeInput?: boolean; judge?: JudgeFn; rubric: string; score?: false | LLMJudgeOutputConfig; }); static jsonSchema(): Record; evaluate(ctx: EvaluatorContext): Promise; override toJSON(): Record; } //#endregion //#region src/evals/builtins/MaxDuration.d.ts /** True iff the task ran in at most `seconds` seconds. */ declare class MaxDuration extends Evaluator { static override evaluatorName: string; readonly seconds: number; constructor(opts: { seconds: number; }); static jsonSchema(): Record; evaluate(ctx: EvaluatorContext): boolean; override toJSON(): Record; } //#endregion //#region src/evals/constants.d.ts /** OTel scope used by every evals span and log emission. */ declare const EVALS_OTEL_SCOPE = "pydantic-evals"; declare const GEN_AI_OPERATION_NAME = "gen_ai.operation.name"; declare const GEN_AI_EVAL_NAME = "gen_ai.evaluation.name"; declare const GEN_AI_SCORE_VALUE = "gen_ai.evaluation.score.value"; declare const GEN_AI_SCORE_LABEL = "gen_ai.evaluation.score.label"; declare const GEN_AI_EXPLANATION = "gen_ai.evaluation.explanation"; declare const ERROR_TYPE = "error.type"; declare const GEN_AI_EVAL_TARGET = "gen_ai.evaluation.target"; declare const GEN_AI_EVALUATOR_SOURCE = "gen_ai.evaluation.evaluator.source"; declare const GEN_AI_EVALUATOR_VERSION = "gen_ai.evaluation.evaluator.version"; declare const EVAL_RESULT_EVENT_NAME = "gen_ai.evaluation.result"; declare const EXPERIMENT_REPEAT_KEY = "logfire.experiment.repeat"; declare const EXPERIMENT_METADATA_KEY = "logfire.experiment.metadata"; declare const EXPERIMENT_ANALYSES_KEY = "logfire.experiment.analyses"; declare const EXPERIMENT_REPORT_EVALUATOR_FAILURES_KEY = "logfire.experiment.report_evaluator_failures"; declare const EXPERIMENT_SOURCE_CASE_NAME_KEY = "logfire.experiment.source_case_name"; declare const ATTR_NAME = "name"; declare const ATTR_TASK_NAME = "task_name"; declare const ATTR_DATASET_NAME = "dataset_name"; declare const ATTR_N_CASES = "n_cases"; declare const ATTR_CASE_NAME = "case_name"; declare const ATTR_INPUTS = "inputs"; declare const ATTR_METADATA = "metadata"; declare const ATTR_EXPECTED_OUTPUT = "expected_output"; declare const ATTR_OUTPUT = "output"; declare const ATTR_TASK_DURATION = "task_duration"; declare const ATTR_METRICS = "metrics"; declare const ATTR_ATTRIBUTES = "attributes"; declare const ATTR_ASSERTIONS = "assertions"; declare const ATTR_SCORES = "scores"; declare const ATTR_LABELS = "labels"; declare const ATTR_ASSERTION_PASS_RATE = "assertion_pass_rate"; declare const ATTR_EVALUATOR_NAME = "evaluator_name"; declare const SPAN_NAME_EXPERIMENT = "evaluate {name}"; declare const SPAN_NAME_CASE = "case: {case_name}"; declare const SPAN_NAME_EXECUTE = "execute {task}"; /** Stable span name for evaluator runs — kept literal across versions. */ declare const SPAN_NAME_EVALUATOR_LITERAL = "evaluator: {evaluator_name}"; /** Friendly message template for evaluator runs (the user-visible form in the UI). */ declare const SPAN_MSG_TEMPLATE_EVALUATOR = "Calling evaluator: {evaluator_name}"; declare const SPAN_NAME_REPORT_EVALUATOR_LITERAL = "report_evaluator: {evaluator_name}"; declare const SPAN_MSG_TEMPLATE_REPORT_EVALUATOR = "Running report evaluator: {evaluator_name}"; declare const OPERATION_EXPERIMENT = "experiment"; //#endregion //#region src/evals/currentTaskRun.d.ts /** Run `fn` with `state` set as the current task-run context. */ declare function runWithTaskRun(state: TaskRunState, fn: () => Promise | R): Promise; declare function getCurrentTaskRun(): TaskRunState | undefined; /** * Record an attribute on the current case's span. No-op outside a `Dataset.evaluate` * task. Mirrors pydantic-evals' `set_eval_attribute`. */ declare function setEvalAttribute(name: string, value: unknown): void; /** * Increment a metric on the current case. No-op outside a `Dataset.evaluate` * task. Mirrors pydantic-evals' `increment_eval_metric`. */ declare function incrementEvalMetric(name: string, amount: number): void; //#endregion //#region src/evals/serialization/spec.d.ts type EncodedEvaluator = Record | string; interface EvaluatorRegistry { get(name: string): T | undefined; keys(): Iterable; } type RegistryInput = EvaluatorRegistry | Map | Record; declare function encodeEvaluatorSpec(evaluator: Evaluator | ReportEvaluator): EncodedEvaluator; declare function decodeEvaluator(encoded: unknown, registry: RegistryInput>, primaryArgKeys: Map): Evaluator; declare function decodeReportEvaluator(encoded: unknown, registry: RegistryInput>, primaryArgKeys: Map): ReportEvaluator; declare function decodeSpec(encoded: unknown): EvaluatorSpec; //#endregion //#region src/evals/serialization/dataset.d.ts interface FromOptions { customEvaluators?: readonly EvaluatorClass[]; customReportEvaluators?: readonly ReportEvaluatorClass[]; /** Default dataset name when the YAML / JSON omits `name`. Falls back to `'dataset'`. */ defaultName?: string; /** Map of evaluator-name → primary-arg-key for constructing single-positional short forms. */ primaryArgKeys?: Record; } interface ToOptions { /** Path to the JSON Schema sidecar file referenced from the dataset's first line / `$schema` key. */ schemaPath?: string; } interface SerializedCase { evaluators?: EncodedEvaluator[]; expected_output?: unknown; inputs: unknown; metadata?: unknown; name?: string; } interface SerializedDataset { $schema?: string; cases: SerializedCase[]; evaluators?: EncodedEvaluator[]; name: string; report_evaluators?: EncodedEvaluator[]; } declare function datasetToObject(dataset: Dataset, options?: ToOptions): SerializedDataset; declare function datasetFromObject(data: unknown, options?: FromOptions): Dataset; //#endregion //#region src/evals/serialization/jsonSchema.d.ts interface JsonSchemaOptions { customEvaluators?: readonly EvaluatorClass[]; customReportEvaluators?: readonly ReportEvaluatorClass[]; } interface JsonSchema { $schema?: string; [key: string]: unknown; } declare function buildDatasetJsonSchema(opts?: JsonSchemaOptions): JsonSchema; //#endregion //#region src/evals/serialization/yaml.d.ts declare function parseYaml(text: string): unknown; declare function stringifyYaml(value: unknown, opts?: { sortKeys?: boolean; }): string; //#endregion //#region src/evals/Dataset.d.ts interface DatasetOptions { cases?: readonly Case[]; evaluators?: readonly Evaluator[]; name: string; reportEvaluators?: readonly ReportEvaluator[]; } declare class Dataset { cases: Case[]; evaluators: Evaluator[]; name: string; reportEvaluators: ReportEvaluator[]; constructor(opts: DatasetOptions); static fromFile(filePath: string, options?: FromOptions): Promise>; static fromObject(data: unknown, options?: FromOptions): Dataset; static fromText(text: string, options: FromOptions & { format: "json" | "yaml"; }): Dataset; addCase(opts: CaseOptions): void; addEvaluator(evaluator: Evaluator, options?: { specificCase?: string; }): void; evaluate(task: (inputs: Inputs) => Output | Promise, options?: EvaluateOptions): Promise>; /** JSON-schema description of the dataset file format, suitable for IDE auto-complete. */ jsonSchema(opts?: { customEvaluators?: readonly EvaluatorClass[]; customReportEvaluators?: readonly ReportEvaluatorClass[]; }): JsonSchema; toFile(filePath: string, opts?: ToOptions): Promise; toObject(opts?: ToOptions): Record; toText(format: "json" | "yaml", opts?: ToOptions): string; } //#endregion //#region src/evals/evaluatorResults.d.ts declare function buildEvaluationResultJson(name: string, value: boolean | EvaluationReason | number | string, source: EvaluatorSpec, evaluatorVersion?: string): EvaluationResultJson; //#endregion //#region src/evals/otelEmit.d.ts interface SpanReference { spanId: string; traceId: string; } declare function spanReferenceFromSpan(span: Span$1): SpanReference; interface EmitOptions { baggageAttrs?: Record; parentSpanRef?: SpanReference; target: string; } declare function emitEvaluationResult(result: EvaluationResultJson, opts: EmitOptions): void; declare function emitEvaluatorFailure(failure: EvaluatorFailureRecord, opts: EmitOptions): void; //#endregion //#region src/evals/online.d.ts type SamplingMode = "correlated" | "independent"; interface SamplingContext { args: unknown[]; target: string; } interface SinkPayload { context: EvaluatorContext; failures: EvaluatorFailureRecord[]; results: EvaluationResultJson[]; spanReference: null | SpanReference; target: string; } type EvaluationSink = (payload: SinkPayload) => Promise | void; type OnErrorLocation = "on_max_concurrency" | "sink"; type OnErrorCallback = (e: unknown, context: EvaluatorContext, evaluator: Evaluator, location: OnErrorLocation) => Promise | void; type OnMaxConcurrencyCallback = (context: EvaluatorContext) => Promise | void; interface OnlineEvalConfig { emitOtelEvents: boolean; enabled: boolean; includeBaggage: boolean; metadata?: Record; onError?: OnErrorCallback; onMaxConcurrency?: OnMaxConcurrencyCallback; onSamplingError?: (e: unknown) => void; sampleRate: ((ctx: SamplingContext) => boolean | number) | number; samplingMode: SamplingMode; sink?: EvaluationSink; } interface OnlineEvalConfigOptions { emitOtelEvents?: boolean; enabled?: boolean; includeBaggage?: boolean; metadata?: Record | undefined; onError?: OnErrorCallback | undefined; onMaxConcurrency?: OnMaxConcurrencyCallback | undefined; onSamplingError?: ((e: unknown) => void) | undefined; sampleRate?: ((ctx: SamplingContext) => boolean | number) | number; samplingMode?: SamplingMode; sink?: EvaluationSink | undefined; } /** Mutate the process-wide online-eval defaults. */ declare function configureOnlineEvals(opts: OnlineEvalConfigOptions): void; declare function getOnlineEvalConfig(): Readonly; interface OnlineEvaluatorOptions { evaluator: Evaluator; maxConcurrency?: number; onError?: OnErrorCallback; onMaxConcurrency?: OnMaxConcurrencyCallback; sampleRate?: number; sink?: EvaluationSink; } declare class OnlineEvaluator { readonly onError?: OnErrorCallback; readonly sampleRate?: number; readonly sink?: EvaluationSink; get evaluator(): Evaluator; get name(): string; private readonly inner; private readonly maxConcurrencySem; private readonly onMaxConcurrency?; constructor(opts: OnlineEvaluatorOptions); tryRun(ctx: EvaluatorContext, parentSpanRef: null | SpanReference, hooks?: { onError?: OnErrorCallback; onMaxConcurrency?: OnMaxConcurrencyCallback; }): Promise<{ failures: EvaluatorFailureRecord[]; results: EvaluationResultJson[]; }>; } interface WithOnlineOptions { emitOtelEvents?: boolean; evaluators: readonly (Evaluator | OnlineEvaluator)[]; extractArgs?: boolean | readonly string[]; includeBaggage?: boolean; msgTemplate?: string; onError?: OnErrorCallback; onMaxConcurrency?: OnMaxConcurrencyCallback; onSamplingError?: (e: unknown) => void; recordReturn?: boolean; sampleRate?: ((ctx: SamplingContext) => boolean | number) | number; samplingMode?: SamplingMode; sink?: EvaluationSink; spanName?: string; target?: string; } declare function disableEvaluation(): { dispose(): void; }; /** Wait for any in-flight online-eval dispatches to settle. Test-only utility. */ declare function waitForEvaluations(opts?: { timeoutMs?: number; }): Promise; /** * Wrap an async function with online evaluation. Each call opens a span; after * the span closes, configured evaluators run in the background. * * Online evals only support **async-returning** functions. Python pydantic-evals * has a sync→thread fallback; we type-restrict away from it because JS * concurrency doesn't model that path cleanly. */ declare function withOnlineEvaluation Promise>(fn: F, opts: WithOnlineOptions): F; //#endregion //#region src/evals/registry.d.ts /** Resolve the registry key for an evaluator class. */ declare function evaluatorRegistryKey(cls: { evaluatorName?: string; name: string; }): string; declare function registerEvaluator(cls: EvaluatorClass): void; declare function registerReportEvaluator(cls: ReportEvaluatorClass): void; declare function getEvaluatorClass(name: string): EvaluatorClass | undefined; declare function getReportEvaluatorClass(name: string): ReportEvaluatorClass | undefined; declare function listRegisteredEvaluators(): readonly EvaluatorClass[]; declare function listRegisteredReportEvaluators(): readonly ReportEvaluatorClass[]; //#endregion //#region src/evals/render.d.ts interface RenderOptions { includeFailures?: boolean; includeInput?: boolean; includeOutput?: boolean; } declare function renderReport(report: EvaluationReport, opts?: RenderOptions): string; //#endregion //#region src/evals/reportEvaluators/ConfusionMatrixEvaluator.d.ts type ExtractFrom = "expected_output" | "labels" | "metadata" | "output"; interface ExtractOpts { from: ExtractFrom; key?: string; } interface ConfusionMatrixOptions { expected?: ExtractOpts; expected_from?: ExtractFrom; expected_key?: string; expectedFrom?: ExtractFrom; expectedKey?: string; predicted?: ExtractOpts; predicted_from?: ExtractFrom; predicted_key?: string; predictedFrom?: ExtractFrom; predictedKey?: string; title?: string; } /** * Builds a confusion matrix from the report cases. Counts each (expected, predicted) * label pair. Mirrors pydantic-evals' `ConfusionMatrixEvaluator`. */ declare class ConfusionMatrixEvaluator extends ReportEvaluator { static override evaluatorName: string; readonly expected: ExtractOpts; readonly predicted: ExtractOpts; readonly title: string; constructor(opts?: ConfusionMatrixOptions); static jsonSchema(): Record; evaluate(ctx: ReportEvaluatorContext): ConfusionMatrixAnalysis; override toJSON(): null | Record; } //#endregion //#region src/evals/reportEvaluators/scoreCommon.d.ts type ScoreFrom = "metrics" | "scores"; type PositiveFrom = "assertions" | "expected_output" | "labels"; //#endregion //#region src/evals/reportEvaluators/KolmogorovSmirnovEvaluator.d.ts interface KSOptions { n_thresholds?: number; nThresholds?: number; positive_from?: PositiveFrom; positive_key?: string; positiveFrom?: PositiveFrom; positiveKey?: string; score_from?: ScoreFrom; score_key?: string; scoreFrom?: ScoreFrom; scoreKey?: string; title?: string; } declare class KolmogorovSmirnovEvaluator extends ReportEvaluator { static override evaluatorName: string; readonly nThresholds: number; readonly positiveFrom: PositiveFrom; readonly positiveKey?: string; readonly scoreFrom: ScoreFrom; readonly scoreKey: string; readonly title: string; constructor(opts: KSOptions); static jsonSchema(): Record; evaluate(ctx: ReportEvaluatorContext): [KSAnalysis, ScalarAnalysis]; override toJSON(): Record; } //#endregion //#region src/evals/reportEvaluators/PrecisionRecallEvaluator.d.ts interface PrecisionRecallOptions { n_thresholds?: number; nThresholds?: number; positive_from?: PositiveFrom; positive_key?: string; positiveFrom?: PositiveFrom; positiveKey?: string; score_from?: ScoreFrom; score_key?: string; scoreFrom?: ScoreFrom; scoreKey?: string; title?: string; } declare class PrecisionRecallEvaluator extends ReportEvaluator { static override evaluatorName: string; readonly nThresholds: number; readonly positiveFrom: PositiveFrom; readonly positiveKey?: string; readonly scoreFrom: ScoreFrom; readonly scoreKey: string; readonly title: string; constructor(opts: PrecisionRecallOptions); static jsonSchema(): Record; evaluate(ctx: ReportEvaluatorContext): [PrecisionRecallAnalysis, ScalarAnalysis]; override toJSON(): Record; } //#endregion //#region src/evals/reportEvaluators/ROCAUCEvaluator.d.ts interface ROCAUCOptions { n_thresholds?: number; nThresholds?: number; positive_from?: PositiveFrom; positive_key?: string; positiveFrom?: PositiveFrom; positiveKey?: string; score_from?: ScoreFrom; score_key?: string; scoreFrom?: ScoreFrom; scoreKey?: string; title?: string; } declare class ROCAUCEvaluator extends ReportEvaluator { static override evaluatorName: string; readonly nThresholds: number; readonly positiveFrom: PositiveFrom; readonly positiveKey?: string; readonly scoreFrom: ScoreFrom; readonly scoreKey: string; readonly title: string; constructor(opts: ROCAUCOptions); static jsonSchema(): Record; evaluate(ctx: ReportEvaluatorContext): [ROCAnalysis, ScalarAnalysis]; override toJSON(): Record; } //#endregion //#region src/evals/runtime.d.ts /** * Runtime detection. Used to pick a strategy for ALS, file IO, and other * runtime-specific affordances. */ type RuntimeName = "browser" | "bun" | "deno" | "node" | "workers"; declare function detectRuntime(): RuntimeName; /** True for runtimes where `node:async_hooks` (and thus `AsyncLocalStorage`) is available. */ declare function hasAsyncLocalStorage(): boolean; /** True for runtimes where `node:fs/promises` is usable. */ declare function hasNodeFs(): boolean; //#endregion export { datasetFromObject as $, JudgeResult as $t, SamplingContext as A, ReportCase as An, EXPERIMENT_ANALYSES_KEY as At, emitEvaluatorFailure as B, KSAnalysis as Bn, GEN_AI_OPERATION_NAME as Bt, registerReportEvaluator as C, SpanQuery as Cn, ATTR_OUTPUT as Ct, OnMaxConcurrencyCallback as D, CaseLifecycle as Dn, ERROR_TYPE as Dt, OnErrorLocation as E, spanQueryToSnakeCase as En, ATTR_TASK_NAME as Et, getOnlineEvalConfig as F, averages as Fn, GEN_AI_EVALUATOR_SOURCE as Ft, parseYaml as G, ReportEvaluator as Gn, SPAN_MSG_TEMPLATE_REPORT_EVALUATOR as Gt, buildEvaluationResultJson as H, PrecisionRecallAnalysis as Hn, GEN_AI_SCORE_VALUE as Ht, waitForEvaluations as I, caseGroups as In, GEN_AI_EVALUATOR_VERSION as It, buildDatasetJsonSchema as J, TableAnalysis as Jn, SPAN_NAME_EXECUTE as Jt, stringifyYaml as K, ReportEvaluatorContext as Kn, SPAN_NAME_CASE as Kt, withOnlineEvaluation as L, computeAssertionPassRate as Ln, GEN_AI_EVAL_NAME as Lt, SinkPayload as M, ReportCaseFailure as Mn, EXPERIMENT_REPEAT_KEY as Mt, configureOnlineEvals as N, ReportCaseGroup as Nn, EXPERIMENT_REPORT_EVALUATOR_FAILURES_KEY as Nt, OnlineEvalConfig as O, CaseLifecycleClass as On, EVALS_OTEL_SCOPE as Ot, disableEvaluation as P, averageFromAggregates as Pn, EXPERIMENT_SOURCE_CASE_NAME_KEY as Pt, ToOptions as Q, JudgeFn as Qt, SpanReference as R, computeAverages as Rn, GEN_AI_EVAL_TARGET as Rt, registerEvaluator as S, SpanNode as Sn, ATTR_N_CASES as St, OnErrorCallback as T, SpanTreeRecordingError as Tn, ATTR_TASK_DURATION as Tt, Dataset as U, ROCAnalysis as Un, OPERATION_EXPERIMENT as Ut, spanReferenceFromSpan as V, LinePlotAnalysis as Vn, GEN_AI_SCORE_LABEL as Vt, DatasetOptions as W, ReportAnalysis as Wn, SPAN_MSG_TEMPLATE_EVALUATOR as Wt, SerializedCase as X, CaseOptions as Xn, SPAN_NAME_REPORT_EVALUATOR_LITERAL as Xt, FromOptions as Y, Case as Yn, SPAN_NAME_EXPERIMENT as Yt, SerializedDataset as Z, Evaluator as Zn, MaxDuration as Zt, evaluatorRegistryKey as _, EvaluatorFailureRecord as _n, ATTR_INPUTS as _t, ROCAUCEvaluator as a, HasMatchingSpan as an, encodeEvaluatorSpec as at, listRegisteredEvaluators as b, ReportEvaluatorClass as bn, ATTR_METRICS as bt, PrecisionRecallOptions as c, EqualsExpected as cn, runWithTaskRun as ct, PositiveFrom as d, Contains as dn, ATTR_ASSERTION_PASS_RATE as dt, LLMJudge as en, datasetToObject as et, ScoreFrom as f, EvaluateOptions as fn, ATTR_ATTRIBUTES as ft, renderReport as g, EvaluatorContext as gn, ATTR_EXPECTED_OUTPUT as gt, RenderOptions as h, EvaluatorClass as hn, ATTR_EVALUATOR_NAME as ht, hasNodeFs as i, IsInstance as in, decodeSpec as it, SamplingMode as j, ReportCaseAggregate as jn, EXPERIMENT_METADATA_KEY as jt, OnlineEvaluator as k, EvaluationReport as kn, EVAL_RESULT_EVENT_NAME as kt, KSOptions as l, Equals as ln, setEvalAttribute as lt, ConfusionMatrixOptions as m, EvaluationResultJson as mn, ATTR_DATASET_NAME as mt, detectRuntime as n, getDefaultJudge as nn, decodeEvaluator as nt, ROCAUCOptions as o, EvalsSpanProcessor as on, getCurrentTaskRun as ot, ConfusionMatrixEvaluator as p, EvaluationReason as pn, ATTR_CASE_NAME as pt, JsonSchema as q, ScalarAnalysis as qn, SPAN_NAME_EVALUATOR_LITERAL as qt, hasAsyncLocalStorage as r, setDefaultJudge as rn, decodeReportEvaluator as rt, PrecisionRecallEvaluator as s, getEvalsSpanProcessor as sn, incrementEvalMetric as st, RuntimeName as t, LLMJudgeOutputConfig as tn, EncodedEvaluator as tt, KolmogorovSmirnovEvaluator as u, deepEqual as un, ATTR_ASSERTIONS as ut, getEvaluatorClass as v, EvaluatorOutput as vn, ATTR_LABELS as vt, EvaluationSink as w, SpanTree as wn, ATTR_SCORES as wt, listRegisteredReportEvaluators as x, TaskRunState as xn, ATTR_NAME as xt, getReportEvaluatorClass as y, EvaluatorSpec as yn, ATTR_METADATA as yt, emitEvaluationResult as z, ConfusionMatrixAnalysis as zn, GEN_AI_EXPLANATION as zt };