agentfootprint/dist/esm/influence-core/snippets.d.ts

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

/**
 * snippetUnits — cut a tool result into citable AttributionUnits for the
 * `'data'` channel.
 *
 * `explainChoice` can only credit the data channel with units to point
 * at — a raw tool result (arbitrary JSON or prose) is not citable as one
 * blob. This helper cuts it at the natural citation grain so a pick like
 * "open dress d42" can be attributed to the exact search-result snippet
 * that returned d42:
 *
 *   • a string → one unit per sentence/line (non-empty, trimmed),
 *   • an array element that is an object → ONE unit summarizing it — its
 *     primitive fields joined as `key: value` pairs (a search hit, a row),
 *   • any other object → its primitive fields grouped into one unit,
 *     then the walk continues into nested objects/arrays,
 *   • null/undefined/booleans/empty strings/functions/symbols → skipped.
 *
 * Bounded and total: at most `max` units, each truncated to `maxLength`
 * characters; circular references are guarded (WeakSet) — weird input
 * yields fewer units, never a throw.
 *
 * Pattern: pure synchronous function, zero imports beyond the shared
 *          types — `src/influence-core/` leaf. No embedding happens
 *          here; the units feed `attributeChoice` / `explainChoice`.
 *
 * Honest claim: this is a CUTTER, not a ranker — it decides what is
 * quotable, not what mattered. Whether a snippet explains the pick is
 * the (proxy) verdict of the similarity scoring downstream.
 */
import type { AttributionUnit } from './types.js';
export interface SnippetUnitsOptions {
    /** Channel tag stamped on every unit. Default `'data'`. */
    readonly channel?: string;
    /** Unit id prefix — ids become `'<prefix>-1'`, `'<prefix>-2'`, … Default `'data'`. */
    readonly idPrefix?: string;
    /** Cap on units returned. Default 12. */
    readonly max?: number;
    /** Cap on characters per unit text (ellipsis included). Default 200. */
    readonly maxLength?: number;
}
/**
 * Cut `value` (a tool result — arbitrary JSON value or prose string)
 * into at most `max` citable units for the data channel.
 */
export declare function snippetUnits(value: unknown, options?: SnippetUnitsOptions): AttributionUnit[];