import { type EmbeddingProvider } from '../hallucination/retrieval.js';
import type { Run, RunQuery, RunTree, TraceStore } from '../types/tracing.js';
/** How runs are grouped: by what went wrong, by the path they took, or by what their text means. */
export type ClusterBy = 'error' | 'trajectory' | 'meaning';
/** Options for `clusterRuns()`. */
export interface ClusterOptions {
    /** What runs are grouped by. Defaults to `error`. */
    by?: ClusterBy;
    /**
     * A run's path, for `trajectory`: the steps it took, in order. Defaults to `trajectoryOf()` for a
     * run tree, or a `trajectory` list in the run's metadata.
     */
    trajectory?: (run: Run) => readonly string[] | undefined;
    /** A run's text, for `meaning`. Defaults to its error message, or else its outputs as JSON. */
    text?: (run: Run) => string;
    /** Embeds texts, for `meaning`. Use the embedding function retrieval uses. */
    embed?: EmbeddingProvider;
    /** How similar two texts must be to share a cluster, for `meaning`. Defaults to 0.85. */
    threshold?: number;
    /** Clusters smaller than this are left out. Defaults to 1. */
    minSize?: number;
}
/** Runs that failed, or behaved, the same way. */
export interface RunCluster {
    /** Stable id: the grouping and a hash of the signature, so the same problem keeps its id across runs. */
    id: string;
    /** What the runs were grouped by. */
    by: ClusterBy;
    /**
     * What the runs share: the run name and normalized error message, the path as `a > b > c`, or the
     * first run's text for a meaning cluster.
     */
    signature: string;
    /** The runs, as given. */
    runs: Run[];
    /** How many runs. */
    count: number;
    /** Distinct run names among them. */
    names: string[];
    /** Distinct models among them. */
    models: string[];
    /** ISO-8601 start of the earliest run. */
    firstSeen: string;
    /** ISO-8601 start of the latest run. */
    lastSeen: string;
}
/**
 * An error message with what varies between occurrences taken out — ids, numbers, quoted values,
 * addresses — so the same failure reads the same every time it happens.
 */
export declare function errorSignature(message: string): string;
/** The steps a run tree took, depth first in start order: each descendant as `kind:name`. */
export declare function trajectoryOf(tree: RunTree): string[];
/**
 * Groups runs that failed or behaved the same way. `error` groups by run name and normalized error
 * message; `trajectory` by the path taken; `meaning` by embedding each run's text and joining it to
 * the first cluster whose leader is at least `threshold` similar. Clusters come back largest first.
 */
export declare function clusterRuns(runs: readonly Run[], options?: ClusterOptions): Promise<RunCluster[]>;
/** Options for `findIssues()`. */
export interface FindIssuesOptions extends Omit<ClusterOptions, 'minSize'> {
    /** Where the runs are. */
    store: TraceStore;
    /** ISO-8601 start of the window. Defaults to the last 24 hours. */
    since?: string;
    /** ISO-8601 end of the window. */
    until?: string;
    /** Narrows the runs read, such as `{ name: 'support-agent' }`. */
    query?: RunQuery;
    /** Runs at least this slow, in milliseconds, are reported as slow issues. Slowness is not checked without it. */
    slowMs?: number;
    /** Only root runs — one per request — which is what an issue counts. On by default. */
    roots?: boolean;
    /** Runs read from the store. Defaults to 1,000. */
    limit?: number;
    /** Clusters smaller than this are not issues. Defaults to 2. */
    minCount?: number;
    /** Replaces the system clock, for tests. */
    now?: () => Date;
}
/** A problem found in recent runs: a cluster of failing or slow runs, and how common it is. */
export interface Issue {
    /** Stable id: the kind and the cluster's id. */
    id: string;
    /** Whether the runs failed or were slow. */
    kind: 'failing' | 'slow';
    /** The runs and what they share. */
    cluster: RunCluster;
    /** The share of the window's runs this issue covers, from 0 to 1. */
    rate: number;
    /** One readable line, such as `12 failing runs of support-agent: TypeError: …`. */
    summary: string;
}
/**
 * Finds the problems in a window of traces: failing runs, and slow runs when `slowMs` is set, each
 * clustered the way `by` asks, most common first. Trajectory clustering reads each run's trace tree.
 */
export declare function findIssues(options: FindIssuesOptions): Promise<Issue[]>;