@aid-framework/runtime 0.0.0 → 0.1.39

package/dist/retrieval/rerank.js

@@ -0,0 +1,105 @@
+/**
+ * Reordering a retrieved set before it is returned.
+ *
+ * Exactly one reranker exists in Phase 1, and it is lexical. That is a deliberate
+ * limitation rather than an unfinished one: the seam is what this layer owes, and the
+ * deterministic implementation is what lets a gate assert on ranking behaviour
+ * without an API key or a floating cross-encoder.
+ *
+ * Why rerank at all when hybrid search already blends two rankings? Because fusion
+ * answers "which candidates are worth considering" and reranking answers "which of
+ * these best answers the question", and the second question can look at the query and
+ * one passage together instead of at ranks alone. The lexical reranker does that with
+ * query-term coverage, which is cheap, explainable, and stable.
+ *
+ * The reranker **replaces** each item's score instead of adding a second number. After
+ * reranking, the number that ranks the list is the reranker's, and keeping a fused RRF
+ * value in the same field would put two incomparable scales in one place. Ranks are
+ * renumbered from 1 so {@link RetrievalResult.context} stays resolvable.
+ */
+import { ConfigurationError, FeatureDeferredError } from '../errors.js';
+import { repr } from '../internal/json.js';
+import { cite, RetrievedItem } from './citations.js';
+import { tokenize } from './hybrid.js';
+const LEXICAL_MARKER = 'lexical';
+/**
+ * How much of `query` the passage actually covers, in `[0, 1]`.
+ *
+ * Query-term coverage, not term frequency: for "which passages answer this", a
+ * passage containing each distinct query term once is as good a candidate as one
+ * repeating a term, and rewarding repetition is how a keyword-stuffed chunk wins. An
+ * exact phrase match breaks ties toward the passage quoting the query.
+ */
+export function lexicalScore(query, text) {
+    const terms = new Set(tokenize(query));
+    if (terms.size === 0)
+        return 0.0;
+    const present = new Set(tokenize(text));
+    let coverage = 0;
+    for (const term of terms) {
+        if (present.has(term))
+            coverage += 1;
+    }
+    coverage /= terms.size;
+    const trimmed = query.trim();
+    if (trimmed.length > 0 && text.toLowerCase().includes(trimmed.toLowerCase())) {
+        // Small and bounded, so it can only order passages that already cover the query
+        // equally well; it can never promote an unrelated passage.
+        return Math.min(1.0, coverage + 0.1);
+    }
+    return coverage;
+}
+/** Coverage-based reranking, with ties broken on chunk id. */
+export class LexicalReranker {
+    _name;
+    constructor(init = {}) {
+        this._name = init.name ?? 'lexical';
+    }
+    get name() {
+        return this._name;
+    }
+    async rerank(query, items, init) {
+        if (init.topN < 1) {
+            throw new ConfigurationError('rerank top_n must be at least 1');
+        }
+        const scored = items.map((item) => ({
+            score: lexicalScore(query, item.chunk.text),
+            chunkId: item.chunk.chunkId,
+            item,
+        }));
+        // A reranker that cannot read the query leaves the incoming order alone rather
+        // than shuffling it: every score is 0.0, so the tie-break would be chunk-id
+        // order, which is an arbitrary order dressed up as a decision.
+        if (scored.every((entry) => entry.score === 0.0)) {
+            return items.slice(0, init.topN);
+        }
+        scored.sort((left, right) => left.score !== right.score ? right.score - left.score : left.chunkId < right.chunkId ? -1 : 1);
+        return scored.slice(0, init.topN).map((entry, offset) => new RetrievedItem({
+            chunk: entry.item.chunk,
+            score: entry.score,
+            rank: offset + 1,
+            citation: cite(entry.item.chunk),
+        }));
+    }
+}
+/**
+ * The reranker a retriever's `rerank` block asks for, if any.
+ *
+ * `rerank.model` is free-form in the IR, and Phase 1 ships exactly one
+ * implementation. A declared model outside the lexical family is refused rather than
+ * quietly served by {@link LexicalReranker}, for the same reason an unimplemented
+ * source kind or store kind is refused: a retriever that appears to rerank with a
+ * cross-encoder it never called is worse than one that says it cannot. The guard
+ * matches on the name because the name is the only signal the IR gives; the lexical
+ * family is what this runtime can honestly claim.
+ */
+export function rerankerFor(spec) {
+    if (spec === null)
+        return null;
+    if (!spec.model.toLowerCase().includes(LEXICAL_MARKER)) {
+        throw new FeatureDeferredError(`rerank model ${repr(spec.model)} is declared but not implemented: Phase 1 ships one ` +
+            'deterministic lexical reranker, and a hosted cross-encoder is a later layer');
+    }
+    return new LexicalReranker();
+}
+//# sourceMappingURL=rerank.js.map

package/dist/retrieval/rerank.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rerank.js","sourceRoot":"","sources":["../../src/retrieval/rerank.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/retriever.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Ingesting a corpus and retrieving from it.
+ *
+ * This is the module a later layer's generated code calls: `ingest` once per
+ * refresh, `retrieve` per query. It is deliberately not a command-line entry point --
+ * the generated module is the intended surface, and a runtime that also shipped a
+ * `main` would grow a second, competing one.
+ *
+ * Both halves are orchestration over injected seams. Nothing here chooses a model by
+ * name, because the binding already carries the resolved model id, the vector width
+ * and the store kind; resolving any of those at run time is exactly what the pinning
+ * rule forbids.
+ *
+ * Cost is charged to the existing ledger using the existing profile. The IR quotes
+ * embedding prices per MTok and `CostProfile` quotes per 1k tokens; that conversion
+ * happens once, in `pinnedEmbedding`, so no call site repeats it.
+ *
+ * Candidates: the retriever fetches more than `topK` candidates from each ranking
+ * before fusing, because fusion and reranking both reorder, and a fused list built
+ * from only `topK` inputs has nothing to reorder. `topK` is applied to the *result*,
+ * which is what the IR field means.
+ */
+import { type Budget, type CostLedger } from '../cost.js';
+import { RetrievalResult } from './citations.js';
+import { type Connector, type SourceDocument } from './connectors.js';
+import { type Embedder } from './embedding.js';
+import { type Reranker } from './rerank.js';
+import { type VectorStore } from './stores.js';
+import { type RetrieverBinding } from './types.js';
+/**
+ * How many candidates per ranking are fetched before fusion. Four is a round number
+ * with a defensible property: it lets a passage ranked 4th lexically and 1st by
+ * vector similarity reach the top of the fused list, which is the case fusion exists
+ * to fix.
+ */
+export declare const DEFAULT_CANDIDATE_FACTOR = 4;
+/**
+ * What one ingest wrote.
+ *
+ * `chunkIds` is the load-bearing field for idempotence: it is sorted, so two ingests
+ * of identical input compare equal without depending on the order the filesystem
+ * happened to yield. `costUsd` is what *this* ingest charged, not the ledger's
+ * running total, so ingesting twice reads as two separate spends.
+ */
+export declare class IngestReport {
+    readonly retriever: string;
+    readonly documents: number;
+    readonly chunks: number;
+    readonly written: number;
+    readonly tokens: number;
+    readonly costUsd: number;
+    readonly chunkIds: readonly string[];
+    constructor(init: {
+        readonly retriever: string;
+        readonly documents: number;
+        readonly chunks: number;
+        readonly written: number;
+        readonly tokens: number;
+        readonly costUsd: number;
+        readonly chunkIds: readonly string[];
+    });
+    get isEmpty(): boolean;
+}
+export interface RetrieverOptions {
+    readonly embedder?: Embedder;
+    readonly store?: VectorStore;
+    readonly reranker?: Reranker | null;
+    readonly connector?: Connector | null;
+    readonly ledger?: CostLedger;
+    readonly budget?: Budget;
+    readonly baseDir?: string | null;
+    readonly candidateFactor?: number;
+}
+/**
+ * A bound retriever: its source, its chunker, its embedder, its store.
+ *
+ * Seams are injectable and default from the binding. Tests inject the fake embedder
+ * and an in-memory store; generated code passes the real ones.
+ */
+export declare class Retriever {
+    private readonly _binding;
+    private readonly _embedder;
+    private readonly _store;
+    private readonly _reranker;
+    private _connector;
+    private readonly _baseDir;
+    private readonly _ledger;
+    private readonly _budget;
+    private readonly _candidateFactor;
+    private _closed;
+    constructor(binding: RetrieverBinding, options?: RetrieverOptions);
+    get binding(): RetrieverBinding;
+    get store(): VectorStore;
+    /**
+     * Chunk a source, embed it, and write it.
+     *
+     * Idempotent by construction: chunk ids are content hashes and the store upserts on
+     * them, so ingesting the same input twice replaces rather than duplicates.
+     * Re-ingesting is therefore a legitimate way to refresh a corpus.
+     */
+    ingest(documents?: readonly SourceDocument[] | null): Promise<IngestReport>;
+    /** Search the store for `query` and return ranked, cited passages. */
+    retrieve(query: string, options?: {
+        readonly topK?: number | null;
+    }): Promise<RetrievalResult>;
+    close(): Promise<void>;
+    private _readSource;
+    /**
+     * Embed a batch, charge it to the ledger, and report what it cost.
+     *
+     * The cost is returned as well as charged so a caller can report what one operation
+     * spent: the ledger's total is cumulative across every call the process made, and
+     * reporting that as this ingest's cost would double-count.
+     */
+    private _embed;
+    /**
+     * The candidate ranking: vector only, or fused with a lexical ranking.
+     *
+     * Fusion is skipped when `index.hybrid` is false, and that is the whole meaning of
+     * the flag -- not "use a different metric", but "do not consult the lexical ranking
+     * at all".
+     */
+    private _rank;
+}
+//# sourceMappingURL=retriever.d.ts.map

package/dist/retrieval/retriever.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retriever.d.ts","sourceRoot":"","sources":["../../src/retrieval/retriever.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/retriever.js

@@ -0,0 +1,281 @@
+/**
+ * Ingesting a corpus and retrieving from it.
+ *
+ * This is the module a later layer's generated code calls: `ingest` once per
+ * refresh, `retrieve` per query. It is deliberately not a command-line entry point --
+ * the generated module is the intended surface, and a runtime that also shipped a
+ * `main` would grow a second, competing one.
+ *
+ * Both halves are orchestration over injected seams. Nothing here chooses a model by
+ * name, because the binding already carries the resolved model id, the vector width
+ * and the store kind; resolving any of those at run time is exactly what the pinning
+ * rule forbids.
+ *
+ * Cost is charged to the existing ledger using the existing profile. The IR quotes
+ * embedding prices per MTok and `CostProfile` quotes per 1k tokens; that conversion
+ * happens once, in `pinnedEmbedding`, so no call site repeats it.
+ *
+ * Candidates: the retriever fetches more than `topK` candidates from each ranking
+ * before fusing, because fusion and reranking both reorder, and a fused list built
+ * from only `topK` inputs has nothing to reorder. `topK` is applied to the *result*,
+ * which is what the IR field means.
+ */
+import { LedgerEntry } from '../cost.js';
+import { ConfigurationError, FeatureDeferredError } from '../errors.js';
+import { repr } from '../internal/json.js';
+import { TokenUsage } from '../types.js';
+import { chunkerFor } from './chunking.js';
+import { cite, RetrievalResult, RetrievedItem } from './citations.js';
+import { openConnector } from './connectors.js';
+import { embedderFor } from './embedding.js';
+import { fuse, lexicalRanking } from './hybrid.js';
+import { rerankerFor } from './rerank.js';
+import { createStore, StoreRecord } from './stores.js';
+import { ScoredChunk } from './types.js';
+/**
+ * How many candidates per ranking are fetched before fusion. Four is a round number
+ * with a defensible property: it lets a passage ranked 4th lexically and 1st by
+ * vector similarity reach the top of the fused list, which is the case fusion exists
+ * to fix.
+ */
+export const DEFAULT_CANDIDATE_FACTOR = 4;
+/** Texts per embedding request. */
+const BATCH_SIZE = 64;
+/**
+ * What one ingest wrote.
+ *
+ * `chunkIds` is the load-bearing field for idempotence: it is sorted, so two ingests
+ * of identical input compare equal without depending on the order the filesystem
+ * happened to yield. `costUsd` is what *this* ingest charged, not the ledger's
+ * running total, so ingesting twice reads as two separate spends.
+ */
+export class IngestReport {
+    retriever;
+    documents;
+    chunks;
+    written;
+    tokens;
+    costUsd;
+    chunkIds;
+    constructor(init) {
+        this.retriever = init.retriever;
+        this.documents = init.documents;
+        this.chunks = init.chunks;
+        this.written = init.written;
+        this.tokens = init.tokens;
+        this.costUsd = init.costUsd;
+        this.chunkIds = [...init.chunkIds];
+    }
+    get isEmpty() {
+        return this.chunks === 0;
+    }
+}
+/**
+ * A bound retriever: its source, its chunker, its embedder, its store.
+ *
+ * Seams are injectable and default from the binding. Tests inject the fake embedder
+ * and an in-memory store; generated code passes the real ones.
+ */
+export class Retriever {
+    _binding;
+    _embedder;
+    _store;
+    _reranker;
+    _connector;
+    _baseDir;
+    _ledger;
+    _budget;
+    _candidateFactor;
+    _closed = false;
+    constructor(binding, options = {}) {
+        if (binding.refreshMode !== 'full') {
+            throw new FeatureDeferredError(`refresh mode ${repr(binding.refreshMode)} is declared but not implemented: ` +
+                'spec v0.1 reindexes the whole source, and incremental refresh needs change ' +
+                'detection the runtime does not have');
+        }
+        const candidateFactor = options.candidateFactor ?? DEFAULT_CANDIDATE_FACTOR;
+        if (candidateFactor < 1) {
+            throw new ConfigurationError('candidate_factor must be at least 1');
+        }
+        this._binding = binding;
+        this._embedder = options.embedder ?? embedderFor(binding.embedding);
+        this._store =
+            options.store ??
+                createStore(binding.storeKind, {
+                    uri: binding.storeUri,
+                    dimensions: binding.embedding.dimensions,
+                });
+        this._reranker = options.reranker ?? rerankerFor(binding.rerank);
+        this._connector = options.connector ?? null;
+        this._baseDir = options.baseDir ?? null;
+        this._ledger = options.ledger;
+        this._budget = options.budget;
+        this._candidateFactor = candidateFactor;
+    }
+    get binding() {
+        return this._binding;
+    }
+    get store() {
+        return this._store;
+    }
+    /**
+     * Chunk a source, embed it, and write it.
+     *
+     * Idempotent by construction: chunk ids are content hashes and the store upserts on
+     * them, so ingesting the same input twice replaces rather than duplicates.
+     * Re-ingesting is therefore a legitimate way to refresh a corpus.
+     */
+    async ingest(documents) {
+        const sourceDocuments = documents != null ? [...documents] : await this._readSource();
+        const chunker = chunkerFor(this._binding.chunking);
+        const chunks = [];
+        for (const document of sourceDocuments) {
+            for (const chunk of chunker.chunk(document)) {
+                chunks.push(chunk);
+            }
+        }
+        const records = [];
+        let tokens = 0;
+        let cost = 0.0;
+        for (let start = 0; start < chunks.length; start += BATCH_SIZE) {
+            const batch = chunks.slice(start, start + BATCH_SIZE);
+            const embedded = await this._embed(batch.map((chunk) => chunk.text));
+            tokens += embedded.batch.usage.inputTokens;
+            cost += embedded.costUsd;
+            const batchVectors = embedded.batch.vectors;
+            if (batchVectors.length !== batch.length) {
+                throw new ConfigurationError(`the embedder returned ${batchVectors.length} vectors for ${batch.length} texts`);
+            }
+            batch.forEach((chunk, offset) => {
+                records.push(new StoreRecord({ chunk, vector: batchVectors[offset] }));
+            });
+        }
+        const written = await this._store.upsert(records);
+        return new IngestReport({
+            retriever: this._binding.retrieverId,
+            documents: sourceDocuments.length,
+            chunks: chunks.length,
+            written,
+            tokens,
+            costUsd: cost,
+            chunkIds: chunks.map((chunk) => chunk.chunkId).sort((left, right) => (left < right ? -1 : 1)),
+        });
+    }
+    /** Search the store for `query` and return ranked, cited passages. */
+    async retrieve(query, options = {}) {
+        const wanted = options.topK ?? this._binding.topK;
+        if (wanted < 1) {
+            throw new ConfigurationError('top_k must be at least 1');
+        }
+        const queryBatch = await this._embed([query]);
+        const vector = queryBatch.batch.vectors[0];
+        if (vector === undefined) {
+            throw new ConfigurationError('the embedder returned no vector for the query');
+        }
+        const candidates = wanted * this._candidateFactor;
+        const hits = await this._store.search(vector, {
+            topK: candidates,
+            metric: this._binding.index.metric,
+        });
+        const ranked = await this._rank(query, hits, candidates);
+        let items = toItems(ranked);
+        if (this._reranker !== null) {
+            const topN = this._binding.rerank?.topN ?? wanted;
+            items = await this._reranker.rerank(query, items, { topN });
+        }
+        return new RetrievalResult({
+            retriever: this._binding.retrieverId,
+            query,
+            items: items.slice(0, wanted),
+        });
+    }
+    async close() {
+        if (this._closed)
+            return;
+        this._closed = true;
+        await this._store.close();
+        await this._embedder.close();
+        if (this._connector !== null) {
+            await this._connector.close();
+        }
+    }
+    async _readSource() {
+        if (this._connector === null) {
+            this._connector = openConnector(this._binding.source, { baseDir: this._baseDir });
+        }
+        return this._connector.documents();
+    }
+    /**
+     * Embed a batch, charge it to the ledger, and report what it cost.
+     *
+     * The cost is returned as well as charged so a caller can report what one operation
+     * spent: the ledger's total is cumulative across every call the process made, and
+     * reporting that as this ingest's cost would double-count.
+     */
+    async _embed(texts) {
+        const batch = await this._embedder.embed(texts, { model: this._binding.embedding });
+        const usage = new TokenUsage({
+            inputTokens: batch.usage.inputTokens,
+            outputTokens: batch.usage.outputTokens,
+        });
+        // Priced through CostProfile rather than a ModelSpec: a ModelSpec requires a
+        // context window and an output ceiling, and fabricating those to reuse a pricing
+        // helper would put invented numbers in a generated artifact.
+        const costUsd = this._binding.embedding.cost.costUsd(usage);
+        if (this._ledger !== undefined) {
+            this._ledger.charge(this._budget, new LedgerEntry({
+                alias: this._binding.embedModel,
+                model: this._binding.embedding.modelId,
+                provider: this._binding.embedding.provider,
+                usage,
+                costUsd,
+            }));
+        }
+        return { batch, costUsd };
+    }
+    /**
+     * The candidate ranking: vector only, or fused with a lexical ranking.
+     *
+     * Fusion is skipped when `index.hybrid` is false, and that is the whole meaning of
+     * the flag -- not "use a different metric", but "do not consult the lexical ranking
+     * at all".
+     */
+    async _rank(query, hits, candidates) {
+        if (!this._binding.index.hybrid) {
+            return hits.map((hit) => new ScoredChunk({ chunk: hit.record.chunk, score: hit.score }));
+        }
+        const corpus = await this._store.corpus();
+        const byId = new Map();
+        for (const record of corpus) {
+            byId.set(record.chunk.chunkId, record);
+        }
+        for (const hit of hits) {
+            if (!byId.has(hit.record.chunk.chunkId)) {
+                byId.set(hit.record.chunk.chunkId, hit.record);
+            }
+        }
+        const lexical = lexicalRanking(corpus.map((record) => record.chunk.text), corpus.map((record) => record.chunk.chunkId), query, { topK: candidates });
+        const fused = fuse([
+            hits.map((hit) => hit.record.chunk.chunkId),
+            lexical.map((entry) => entry.chunkId),
+        ]);
+        const ranked = [];
+        for (const entry of fused) {
+            const record = byId.get(entry.chunkId);
+            if (record !== undefined) {
+                ranked.push(new ScoredChunk({ chunk: record.chunk, score: entry.score }));
+            }
+        }
+        return ranked;
+    }
+}
+/** Attach provenance and assign contiguous 1-based ranks. */
+function toItems(ranked) {
+    return ranked.map((scored, offset) => new RetrievedItem({
+        chunk: scored.chunk,
+        score: scored.score,
+        rank: offset + 1,
+        citation: cite(scored.chunk),
+    }));
+}
+//# sourceMappingURL=retriever.js.map

package/dist/retrieval/retriever.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retriever.js","sourceRoot":"","sources":["../../src/retrieval/retriever.ts"],"names":[],"mappings":"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"}

package/dist/retrieval/stores.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Where vectors live and how they are searched.
+ *
+ * Two adapters behind one protocol: in-memory and pgvector. The in-memory store is
+ * not a stand-in for a "real" one -- it is the adapter every gate runs against, so it
+ * is the one whose behaviour is the contract. The pgvector adapter is covered by the
+ * same expectations and by nothing else: it is locally provisioned, and no required
+ * gate touches a database.
+ *
+ * Similarity is always reported as *higher is better*, including for L2, where the
+ * raw quantity is a distance. A store that inverted its sign for one metric would
+ * make every caller responsible for remembering which metric it asked for, and fusion
+ * and reranking downstream would silently rank backwards.
+ *
+ * Lexical search is deliberately absent from the store. The store owns the vector
+ * index; BM25 lives in `hybrid.ts` and reads the corpus through
+ * {@link VectorStore.corpus}. That keeps one lexical implementation instead of one
+ * per backend, at the cost of fetching the corpus per query -- a Phase 1
+ * simplification, correct at test scale and worth revisiting when a corpus outgrows
+ * memory.
+ */
+import type { Chunk, DistanceMetric, StoreKind } from './types.js';
+/** One chunk and its vector, exactly as it is written to a store. */
+export declare class StoreRecord {
+    readonly chunk: Chunk;
+    readonly vector: readonly number[];
+    constructor(init: {
+        readonly chunk: Chunk;
+        readonly vector: readonly number[];
+    });
+}
+/** A record and its similarity to the query, higher being better. */
+export declare class SearchHit {
+    readonly record: StoreRecord;
+    readonly score: number;
+    constructor(init: {
+        readonly record: StoreRecord;
+        readonly score: number;
+    });
+}
+/**
+ * Similarity of two equal-length vectors under `metric`.
+ *
+ * Always oriented so that a larger number means a better match.
+ */
+export declare function similarity(left: readonly number[], right: readonly number[], init: {
+    readonly metric: DistanceMetric;
+}): number;
+/**
+ * A vector index the retriever can ingest into and search.
+ *
+ * `close` must be idempotent, matching the other seams in this runtime.
+ */
+export interface VectorStore {
+    readonly kind: StoreKind;
+    /** Write records, keyed by `chunkId`. Returns the number written. */
+    upsert(records: readonly StoreRecord[]): Promise<number>;
+    search(vector: readonly number[], init: {
+        readonly topK: number;
+        readonly metric: DistanceMetric;
+    }): Promise<readonly SearchHit[]>;
+    /**
+     * Every stored record.
+     *
+     * Exists for the lexical half of hybrid search, and for assertions about a store's
+     * contents after re-ingest.
+     */
+    corpus(): Promise<readonly StoreRecord[]>;
+    close(): Promise<void>;
+}
+/**
+ * A map keyed by `chunkId`.
+ *
+ * The key choice is what makes ingest idempotent: re-ingesting identical input
+ * recomputes identical ids and overwrites in place, so the store's contents are a
+ * function of the input rather than of how many times it was ingested.
+ */
+export declare class InMemoryVectorStore implements VectorStore {
+    private readonly _kind;
+    private readonly _records;
+    constructor(init?: {
+        readonly kind?: StoreKind;
+    });
+    get kind(): StoreKind;
+    upsert(records: readonly StoreRecord[]): Promise<number>;
+    search(vector: readonly number[], init: {
+        readonly topK: number;
+        readonly metric: DistanceMetric;
+    }): Promise<readonly SearchHit[]>;
+    corpus(): Promise<readonly StoreRecord[]>;
+    close(): Promise<void>;
+}
+/**
+ * Select a store adapter.
+ *
+ * `pgvector.ts` is imported statically but loads its database driver lazily on first
+ * connect, so importing this module still pulls in no driver: the optional-extra
+ * property the Python adapter preserves at import time is preserved here at connect
+ * time instead. It keeps `createStore` synchronous, which is what the retriever's
+ * constructor needs.
+ */
+export declare function createStore(kind: StoreKind, init?: {
+    readonly uri?: string | null;
+    readonly dimensions?: number | null;
+}): VectorStore;
+//# sourceMappingURL=stores.d.ts.map

package/dist/retrieval/stores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.d.ts","sourceRoot":"","sources":["../../src/retrieval/stores.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEnE,qEAAqE;AACrE,qBAAa,WAAW;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAEnC,YAAY,IAAI,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAG9E;CACF;AAED,qEAAqE;AACrE,qBAAa,SAAS;IACpB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,YAAY,IAAI,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAGzE;CACF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,IAAI,EAAE;IAAE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GACxC,MAAM,CA8BR;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,qEAAqE;IACrE,MAAM,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACzD,MAAM,CACJ,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,IAAI,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;KAAE,GAC/D,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAAC;IACjC;;;;;OAKG;IACH,MAAM,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAC;IAC1C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,WAAW;IACrD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAE3D,YAAY,IAAI,GAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAA;KAAO,EAEnD;IAED,IAAI,IAAI,IAAI,SAAS,CAEpB;IAEK,MAAM,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAK7D;IAEK,MAAM,CACV,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,IAAI,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;KAAE,GAC/D,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAiB/B;IAEK,MAAM,IAAI,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAI9C;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAG3B;CACF;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,EACf,IAAI,GAAE;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GAC/E,WAAW,CAWb"}