agentfootprint/dist/esm/memory/retrieval/topK.js

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * Build the top-K strategy.
 *
 * @example
 * ```ts
 * import { defineRAG } from 'agentfootprint';
 * import { topK } from 'agentfootprint/memory';
 *
 * const docs = defineRAG({
 *   id: 'product-docs',
 *   store, embedder,
 *   retrieval: topK({ k: 5, threshold: 0.55 }),
 * });
 * ```
 */
export function topK(options = {}) {
    const k = options.k ?? 3;
    if (!Number.isInteger(k) || k < 1) {
        throw new Error(`topK: \`k\` must be a positive integer — received ${String(options.k)}.`);
    }
    const rejectWindow = options.rejectWindow ?? 10;
    if (!Number.isInteger(rejectWindow) || rejectWindow < 0) {
        throw new Error(`topK: \`rejectWindow\` must be a non-negative integer — received ${String(options.rejectWindow)}.`);
    }
    const threshold = options.threshold === null ? undefined : options.threshold ?? 0.7;
    if (threshold !== undefined && !Number.isFinite(threshold)) {
        throw new Error(`topK: \`threshold\` must be a finite number or null — received ${String(options.threshold)}.`);
    }
    return {
        name: 'topK',
        k,
        ...(threshold !== undefined && { threshold }),
        rejectWindow,
        select(pool) {
            const verdicts = [];
            let admitted = 0;
            for (const candidate of pool) {
                if (threshold !== undefined && candidate.score < threshold) {
                    verdicts.push({ admitted: false, reason: 'below-threshold' });
                    continue;
                }
                if (admitted >= k) {
                    verdicts.push({ admitted: false, reason: 'over-max-entries' });
                    continue;
                }
                admitted += 1;
                verdicts.push({ admitted: true });
            }
            return verdicts;
        },
    };
}
//# sourceMappingURL=topK.js.map