@arizeai/phoenix-evals/dist/src/code/classificationMetrics.d.ts

A library for running evaluations for AI use cases

/**
 * A label produced by a classifier. Must be a primitive so it can be compared
 * for equality and used as a lookup key.
 */
export type ClassificationLabel = string | number;
/**
 * The strategy used to aggregate per-class precision/recall/F-score into a
 * single number when there are more than two classes (or no `positiveLabel`
 * is configured).
 *
 * - `"macro"`: unweighted mean across classes.
 * - `"micro"`: pool true/false positives and false negatives across classes
 *   before computing the metric.
 * - `"weighted"`: mean across classes, weighted by each class's support
 *   (number of true instances).
 */
export type AverageType = "macro" | "micro" | "weighted";
/**
 * The example shape expected by the classification-metric evaluators.
 */
export interface ClassificationExample {
    /** The ground-truth sequence of labels. */
    expected: ClassificationLabel[];
    /** The predicted sequence of labels, aligned by index with `expected`. */
    output: ClassificationLabel[];
    [key: string]: unknown;
}
/**
 * Options shared by precision, recall, and F-score computations.
 */
export interface PrecisionRecallFScoreOptions {
    /**
     * Weight of recall relative to precision in the F-score. Must be > 0.
     * @defaultValue 1
     */
    beta?: number;
    /**
     * Aggregation strategy across classes. Ignored when `positiveLabel` is set
     * (or auto-detected).
     * @defaultValue "macro"
     */
    average?: AverageType;
    /**
     * Value substituted for a metric when it is undefined (e.g. 0/0).
     * @defaultValue 0
     */
    zeroDivision?: number;
    /**
     * When set, compute binary precision/recall/F exclusively for this label
     * (one-vs-rest). If not set, `average` is at its default `"macro"`, and
     * the labels are the numeric set `{0, 1}`, the positive label defaults to
     * `1`. Otherwise, multi-class averaging is used. The auto-detection is
     * skipped whenever a non-default `average` is configured, so an explicit
     * `average` is never silently overridden by the shape of the data.
     */
    positiveLabel?: ClassificationLabel;
}
/**
 * The result of computing precision, recall, and F-score for a batch of
 * predictions.
 */
export interface PrecisionRecallFScoreResult {
    precision: number;
    recall: number;
    fScore: number;
    beta: number;
    average: AverageType;
    /** All labels observed in `expected` and `output`, in first-seen order. */
    labels: ClassificationLabel[];
    /** The label treated as positive in one-vs-rest mode, or `null` if multi-class averaging was used. */
    positiveLabel: ClassificationLabel | null;
}
/**
 * Computes precision, recall, and F-beta score for a batch of expected vs.
 * predicted labels.
 *
 * `expected`/`output` are the full sequence of labels across an entire
 * dataset, not a single row — this and the evaluators built on it are
 * dataset-level, unlike the package's per-row LLM evaluators. Call it once
 * over every row's collected labels rather than wiring it into a per-row
 * pipeline (e.g. `runExperiment`'s per-row evaluators).
 *
 * Supports both binary classification (via `positiveLabel`, or
 * auto-detected when `average` is at its default `"macro"` and the labels
 * are the numeric set `{0, 1}`) and multi-class classification (via the
 * `average` strategy).
 *
 * @example Multi-class (macro average)
 * ```typescript
 * computePrecisionRecallFScore({
 *   expected: ["cat", "dog", "cat", "bird"],
 *   output: ["cat", "cat", "cat", "bird"],
 * });
 * // { precision: 5/9, recall: 2/3, fScore: 0.6, beta: 1, average: "macro", ... }
 * ```
 *
 * @example Binary with an explicit positive label
 * ```typescript
 * computePrecisionRecallFScore(
 *   { expected: ["spam", "ham", "spam"], output: ["spam", "spam", "ham"] },
 *   { beta: 0.5, positiveLabel: "spam" }
 * );
 * ```
 */
export declare function computePrecisionRecallFScore({ expected, output }: Pick<ClassificationExample, "expected" | "output">, options?: PrecisionRecallFScoreOptions): PrecisionRecallFScoreResult;
/**
 * Formats a beta value for use in metric names, e.g. `1` -> `"f1"`,
 * `0.5` -> `"f0_5"`.
 */
export declare function formatBetaForMetricName(beta: number): string;
/**
 * The suffix appended to a metric name to reflect the aggregation strategy,
 * e.g. `"precision"` vs. `"precision_micro"`. No suffix is used when
 * `positiveLabel` is explicitly configured, since `average` is not
 * applicable in that one-vs-rest binary mode. This mirrors
 * `resolvePositiveLabel`'s auto-detection rule (only under the default
 * `"macro"` average) so a constructed evaluator's static name always
 * matches what `computePrecisionRecallFScore` actually computes.
 */
export declare function getAverageMetricNameSuffix({ average, positiveLabel, }: PrecisionRecallFScoreOptions): string;
//# sourceMappingURL=classificationMetrics.d.ts.map