agentfootprint/dist/esm/memory/store/staticVectorStore.d.ts

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

import type { MemoryEntry } from '../entry/index.js';
import type { MemoryStore } from './types.js';
/** The bundle format marker. Version the FORMAT, not the library. */
export declare const CORPUS_BUNDLE_FORMAT: "agentfootprint-corpus-v1";
/** One exported corpus entry: the passage, its vector, and its coordinates. */
export interface CorpusBundleEntry {
    /** The chunk id, e.g. `'refunds.md#3'` — what the model cites. */
    readonly id: string;
    /** The passage text. */
    readonly text: string;
    /** The embedding vector, in the bundle embedder's space. */
    readonly vector: readonly number[];
    /**
     * Everything else the stored value carried — provenance (`docUri`,
     * `heading`, `page`, offsets, hashes) and any consumer metadata, flattened
     * into one record the retrieval formatter's provenance reader understands.
     */
    readonly metadata?: Readonly<Record<string, unknown>>;
}
/**
 * A corpus as a plain-JSON build artifact. Produced by `exportCorpus`
 * (`agentfootprint/rag`), served by {@link staticVectorStore}, loadable into a
 * writable store by `importCorpus`. Survives `JSON.stringify` → `JSON.parse`
 * byte-for-byte, which is the whole point.
 */
export interface CorpusBundle {
    readonly format: typeof CORPUS_BUNDLE_FORMAT;
    /** The embedding space every vector in `entries` lives in. */
    readonly embedder: {
        /** The embedder id recorded at index time (`'default-embedder'` when the index never named one). */
        readonly id: string;
        /** Vector length. Every entry's vector has exactly this many numbers. */
        readonly dimensions: number;
    };
    /** The namespace the corpus was exported from (`identityNamespace` form). */
    readonly namespace: string;
    /** Unix ms at export time. */
    readonly exportedAt: number;
    readonly entries: readonly CorpusBundleEntry[];
}
/** The embedder-shaped slice the load-time fingerprint check needs. */
export interface EmbedderFingerprint {
    readonly id?: string;
    readonly dimensions: number;
}
/**
 * Validate a value as a `CorpusBundle`, teachingly. Shared by
 * `staticVectorStore` and `importCorpus`, so a truncated file or a
 * hand-edited bundle fails the same way at every door.
 */
export declare function assertCorpusBundle(bundle: unknown, caller: string): asserts bundle is CorpusBundle;
/**
 * The `MemoryEntry` a bundle entry seeds — in the exact shape the retrieval
 * formatter reads: passage on `value.content`, provenance under
 * `value.metadata`. Shared with `importCorpus` so a static corpus and an
 * imported one render identically.
 */
export declare function bundleEntryToMemoryEntry(entry: CorpusBundleEntry, bundle: CorpusBundle): MemoryEntry<{
    id: string;
    content: string;
    metadata?: Record<string, unknown>;
}>;
/**
 * Serve an exported corpus bundle as a read-only, vector-capable
 * `MemoryStore`.
 *
 * @param bundle   a `CorpusBundle` from `exportCorpus` (usually
 *                 `JSON.parse` of the shipped file).
 * @param embedder optional — the embedder the RUNTIME will query with (or
 *                 just `{ id, dimensions }`). When given, a fingerprint
 *                 mismatch is refused HERE, at load, instead of surfacing as
 *                 an empty retrieval at the first question. Recommended.
 *
 * @example
 * ```ts
 * import { staticVectorStore } from 'agentfootprint/memory';
 * import corpus from './corpus.json';
 *
 * const store = staticVectorStore(corpus, embedder);
 * const docs = defineRAG({ id: 'docs', store, embedder });
 * ```
 */
export declare function staticVectorStore(bundle: CorpusBundle, embedder?: EmbedderFingerprint): MemoryStore;