agentfootprint
Version:
The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.
73 lines (72 loc) • 3.87 kB
TypeScript
/**
* rankingConfidence — honesty marker for an influence ranking (RFC-003 honesty
* marker; influence-core block D6). Internal concept: "attributability".
*
* Pattern: pure, embedder-free function over a `scoreInfluence` result.
* Deterministic; no I/O.
* Role: `src/influence-core/` leaf. The honesty companion to the
* four-signal scorer: it says when the ranking is a SHORTLIST,
* not a verdict.
*
* ## Why this exists (the measured blind spot)
*
* Output-similarity influence ranks sources by how much they resemble the
* final answer. That is structurally blind to ABSENCE / CROWDING bugs: a
* culprit that caused the error by *displacing* context (history truncation,
* context dilution) need not resemble the answer — so it ranks low, or below
* an innocent that the answer happens to talk about. The tell is not a low
* absolute score; it is a FLAT top — no source clearly dominates. This
* function reports that flatness honestly so consumers escalate to ablation
* (the causal tier) instead of trusting a confident-but-wrong rank-1.
*
* Honest claim (RFC-002 §2 discipline): `clearWinner` is a proxy for "the
* ranking has a clear lead", never "the lead is the cause". A clear lead can
* still be an innocent the answer rationalizes over — only ablation makes
* causal claims.
*/
import type { ConfidenceStrategy, InfluenceScore, RankingConfidence } from './types.js';
/**
* Default strategy: ABSOLUTE top-2 gap `s0 − s1 >= threshold`. Simple and
* interpretable, but embedder-relative (the gap scale depends on the embedding
* geometry). Use `ratioStrategy` for cross-embedder transfer.
*/
export declare function marginStrategy(threshold?: number): ConfidenceStrategy;
/**
* Scale-invariant strategy: top-2 gap as a FRACTION of the top score,
* `(s0 − s1) / |s0| >= threshold`. Transfers across embedders / answer lengths
* where the absolute margin does not. A zero (or all-equal) top is never a
* clear winner.
*/
export declare function ratioStrategy(threshold?: number): ConfidenceStrategy;
export interface RankingConfidenceOptions {
/**
* The decisiveness rule. Default: `marginStrategy(clearWinnerMargin)`.
* When set, it WINS — `clearWinnerMargin` is ignored. Bring your own
* (e.g. entropy / dispersion) or use the shipped `ratioStrategy`.
*/
readonly strategy?: ConfidenceStrategy;
/** Threshold for the DEFAULT margin strategy (ignored when `strategy` is
* set). Default: `DEFAULT_CLEAR_WINNER_MARGIN` (0.05). */
readonly clearWinnerMargin?: number;
/** Score band below the top defining the shortlist to double-check.
* Default: `DEFAULT_SHORTLIST_BAND` (0.1). Recommended >=
* `clearWinnerMargin` so the shortlist is at least as wide as the
* winning gap (the function also guarantees the runner-up is shortlisted
* when there is no clear winner, so a smaller value is safe). */
readonly shortlistBand?: number;
}
/**
* Assess whether an influence ranking has a clear winner to trust as a lead,
* or is too close to call and should be confirmed by ablation.
*
* Guarantees (relied on by the localizer): the returned `shortlist` always
* contains `lead` when there is one, and — when there is NO clear winner and
* there are ≥2 suspects — always contains the runner-up too (so ablation over
* the shortlist covers the real culprit even if it ranked below an innocent).
*
* @param scores `scoreInfluence` output (any order — re-sorted defensively).
* Ids are assumed unique (as `scoreInfluence` enforces); the
* shortlist is de-duplicated defensively regardless.
* @throws Error on negative or NaN options.
*/
export declare function rankingConfidence(scores: readonly InfluenceScore[], options?: RankingConfidenceOptions): RankingConfidence;