agentfootprint
Version:
The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.
34 lines (33 loc) • 1.55 kB
TypeScript
import type { Embedder, MarginCandidate, MarginResult } from './types.js';
export interface ScoreMarginArgs {
/** The offered candidates (e.g. the tool catalog on `llm_start`). */
readonly candidates: readonly MarginCandidate[];
/** The choice context — the text the chooser ranked against. */
readonly contextText: string;
/** Names of the chosen candidate(s). Must exist in `candidates`. */
readonly chosen: readonly string[];
/**
* Injected embedder. Wrap in an `EmbeddingCache` so descriptions
* embed once across calls (RFC-002 §3 — the same cache the catalog
* lint already filled).
*/
readonly embedder: Embedder;
/** Margins below this flag `narrow`. Default 0.05 (RFC-002 §4). */
readonly marginThreshold?: number;
/** Abort signal threaded to the embedder (network backends). */
readonly signal?: AbortSignal;
}
/**
* Rank candidates by cosine similarity to the choice context and
* measure how decisively the chosen one(s) won.
*
* Returns ranked `scores` (descending; ties keep candidate input
* order), the `topScored` name, the `margin` (undefined when every
* candidate was chosen — no competition to measure; `narrow` is false
* in that case), and the two flags.
*
* Fail-loud validation: empty candidates/chosen, duplicate candidate
* names, or a chosen name missing from the candidates throw — those
* are wiring bugs in the caller, not runtime conditions.
*/
export declare function scoreMargin(args: ScoreMarginArgs): Promise<MarginResult>;