agentfootprint
Version:
The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.
121 lines • 5.16 kB
TypeScript
/**
* search/types — what a tool declares about its search (`Tool.search`).
*
* Pattern: declaration vocabulary, pure data. Validated once at `defineTool`
* (`declaration.ts` · `assertToolSearch`) and at the MCP ingest door
* with the same rule; read by the funnel's composer (`compose.ts`).
* Role: semantics/ layer. TYPE-only.
* Emits: N/A.
*/
import type { GapFacet } from '../composedCoverage.js';
/**
* What one input argument DOES to the ground a call covers — a closed set.
*
* • `population` — which rows: one facet per value sent (a list gives one per item);
* • `filter` — narrows the rows;
* • `period` — the time read (the argument `Tool.period` names);
* • `source` — picks the store: a sent value REPLACES the declared source;
* • `query` — free text: the population is what MATCHED it, by the
* tool's own rule — a `match` gap on every call;
* • `match` — a fuzzy value, read the same way as `query`;
* • `cap` — at most this many rows;
* • `page` — which page of the rows;
* • `inert` — changes the bytes, not the ground (a format, a sort).
*/
export type SearchRole = 'population' | 'filter' | 'period' | 'source' | 'query' | 'match' | 'cap' | 'page' | 'inert';
/** A value a declaration may name — a default, a fixed qualifier's value. */
export type SearchScalar = string | number | boolean;
/** `whenOmitted: { any: true }` — omission narrows nothing. */
export interface AnyValue {
readonly any: true;
}
/**
* What `execute` does when the call leaves the argument out — TWO typed forms,
* no third: the default VALUE `execute` applies (composed as if sent), or
* `{ any: true }`. With neither, an unsent argument is a bearing gap: its
* default may live inside `execute`.
*/
export type WhenOmitted = SearchScalar | readonly SearchScalar[] | AnyValue;
/** One input argument, classified. EVERY property of `inputSchema` needs one. */
export interface SearchArgument {
readonly name: string;
readonly role: SearchRole;
readonly whenOmitted?: WhenOmitted;
/**
* The words a claim may use for each VALUE of a `filter` or `source`
* argument — `{ critical: ['critical', 'sev1'] }`. Allowed on those two
* roles only.
*/
readonly said?: Readonly<Record<string, readonly string[]>>;
}
/** A thing the search is made of, and the words a claim may use for it. */
export interface SearchWords {
readonly what: string;
/** Non-empty. The ONLY vocabulary a prose claim's words are matched to. */
readonly said: readonly string[];
}
/** A qualifier the tool ALWAYS applies — part of the search's scope. */
export interface SearchFixed {
/** Not an input property; unique among the fixed qualifiers. */
readonly name: string;
readonly value: SearchScalar;
/** Required: a claim that does not name the qualifier is wider than the search. */
readonly said: readonly string[];
}
/** A ground the search NEVER reaches — a build-time constant. */
export interface SearchGap {
readonly what: string;
/** Required: a blind spot with no reason cannot be acted on or disproved. */
readonly why: string;
/** Required: the facet it bears on. */
readonly bears: GapFacet;
}
/** Limits no input property carries. */
export interface SearchLimits {
/** A server-side cap on the rows; `'unknown'` when the tool cannot say. */
readonly cap?: number | 'unknown';
/**
* The read sees only what the caller's credential may see — a
* `credential-limited` gap bearing on the population, every call.
*/
readonly byCredential?: true;
}
/**
* WHAT ONE CALL OF THIS TOOL SEARCHES — declared once; the library composes
* each call's coverage from it and the arguments the call ran with.
*
* @example
* ```ts
* search: {
* source: { what: 'the incident store', said: ['the incident store'] },
* subject: { what: 'incidents', said: ['incident', 'incidents'] },
* fixed: [{ name: 'status', value: 'open', said: ['open'] }],
* arguments: [
* { name: 'service', role: 'population' },
* { name: 'window', role: 'period', whenOmitted: '2h' },
* ],
* complete: 'within-arguments',
* }
* ```
*/
export interface ToolSearch {
readonly source: SearchWords;
readonly subject: SearchWords;
readonly fixed?: readonly SearchFixed[];
readonly arguments: readonly SearchArgument[];
/**
* The tool's statement that a call is complete for the population, filters
* and period in effect when no cap was reached and no page was open. Absent
* = never complete.
*/
readonly complete?: 'within-arguments';
readonly gaps?: readonly SearchGap[];
readonly limits?: SearchLimits;
/**
* `'approximate'` — a vector, top-k or fuzzy ranking: the rows are the ones
* ranked nearest, never every row that fits, so every call carries a
* `ranking` gap on completeness and `complete` is refused beside it.
*/
readonly ranking?: 'approximate';
}
//# sourceMappingURL=types.d.ts.map