@aid-framework/runtime 0.0.0 → 0.1.39

package/dist/retrieval/stores.js

@@ -0,0 +1,142 @@
+/**
+ * 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 { ConfigurationError, FeatureDeferredError } from '../errors.js';
+import { repr } from '../internal/json.js';
+import { PgVectorStore } from './pgvector.js';
+/** One chunk and its vector, exactly as it is written to a store. */
+export class StoreRecord {
+    chunk;
+    vector;
+    constructor(init) {
+        this.chunk = init.chunk;
+        this.vector = [...init.vector];
+    }
+}
+/** A record and its similarity to the query, higher being better. */
+export class SearchHit {
+    record;
+    score;
+    constructor(init) {
+        this.record = init.record;
+        this.score = init.score;
+    }
+}
+/**
+ * Similarity of two equal-length vectors under `metric`.
+ *
+ * Always oriented so that a larger number means a better match.
+ */
+export function similarity(left, right, init) {
+    if (left.length !== right.length) {
+        throw new ConfigurationError(`cannot compare vectors of ${left.length} and ${right.length} dimensions; the query ` +
+            "and the stored vectors must share the embedding's pinned width");
+    }
+    let dot = 0;
+    for (let index = 0; index < left.length; index += 1) {
+        dot += left[index] * right[index];
+    }
+    if (init.metric === 'dot') {
+        return dot;
+    }
+    if (init.metric === 'l2') {
+        let squares = 0;
+        for (let index = 0; index < left.length; index += 1) {
+            const difference = left[index] - right[index];
+            squares += difference * difference;
+        }
+        return -Math.sqrt(squares);
+    }
+    const leftNorm = Math.sqrt(left.reduce((total, value) => total + value * value, 0));
+    const rightNorm = Math.sqrt(right.reduce((total, value) => total + value * value, 0));
+    if (leftNorm === 0.0 || rightNorm === 0.0) {
+        // A zero vector has no direction, so cosine similarity is undefined rather than
+        // zero; returning 0.0 keeps it last without inventing a ranking.
+        return 0.0;
+    }
+    return dot / (leftNorm * rightNorm);
+}
+/**
+ * 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 class InMemoryVectorStore {
+    _kind;
+    _records = new Map();
+    constructor(init = {}) {
+        this._kind = init.kind ?? 'memory';
+    }
+    get kind() {
+        return this._kind;
+    }
+    async upsert(records) {
+        for (const record of records) {
+            this._records.set(record.chunk.chunkId, record);
+        }
+        return records.length;
+    }
+    async search(vector, init) {
+        if (init.topK < 1) {
+            throw new ConfigurationError('top_k must be at least 1');
+        }
+        const hits = [...this._records.values()].map((record) => new SearchHit({ record, score: similarity(vector, record.vector, init) }));
+        // Ties break on chunk id, never on insertion order: two runs that ingest the same
+        // corpus in a different order must produce the same ranking.
+        hits.sort((left, right) => left.score !== right.score
+            ? right.score - left.score
+            : left.record.chunk.chunkId < right.record.chunk.chunkId
+                ? -1
+                : 1);
+        return hits.slice(0, init.topK);
+    }
+    async corpus() {
+        return [...this._records.keys()]
+            .sort((left, right) => (left < right ? -1 : 1))
+            .map((chunkId) => this._records.get(chunkId));
+    }
+    async close() {
+        // The in-memory store owns no external resource, so there is nothing to release.
+        return Promise.resolve();
+    }
+}
+/**
+ * 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 function createStore(kind, init = {}) {
+    if (kind === 'memory') {
+        return new InMemoryVectorStore();
+    }
+    if (kind === 'pgvector') {
+        return new PgVectorStore({ uri: init.uri ?? null, dimensions: init.dimensions ?? null });
+    }
+    throw new FeatureDeferredError(`vector store kind ${repr(kind)} is declared in the IR but has no adapter in this ` +
+        "runtime; Phase 1 ships 'memory' and 'pgvector'");
+}
+//# sourceMappingURL=stores.js.map

package/dist/retrieval/stores.js.map

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

package/dist/retrieval/types.d.ts

@@ -0,0 +1,314 @@
+/**
+ * Shapes the retrieval runtime shares across its modules.
+ *
+ * Two families live here and the split is deliberate.
+ *
+ * * The **IR mirror** models (`SourceSpec`, `ChunkingSpec`, `IndexSpec`,
+ *   `RerankSpec`, `RefreshSpec`, `RetrieverSpec`, `EmbeddingSpec`,
+ *   `VectorStoreSpec`) reproduce the L1 IR's `retrievers` / `embeddings` /
+ *   `stores` entries field for field. The IR spells these in camelCase
+ *   (`keepMetadata`, `embedModel`, `topK`, `inputPerMTok`, ...) and so does this
+ *   file, because in TypeScript the IR's own spelling *is* the natural one: there
+ *   is no second vocabulary to translate from. Enum values are the IR's own
+ *   strings (`recursive`, `pgvector`, `cosine`) and are never re-spelled.
+ * * The **resolved** models (`PinnedEmbedding`, `RetrieverBinding`) are what
+ *   generated code binds with literals. They carry the exact embedding model id
+ *   rather than an alias, so a run is reproducible from the generated source
+ *   alone and nothing is resolved at run time.
+ */
+import { CostProfile } from '../types.js';
+/** `retriever.index.metric`. */
+export type DistanceMetric = 'cosine' | 'dot' | 'l2';
+export declare const DISTANCE_METRICS: readonly DistanceMetric[];
+/**
+ * `retriever.source.kind`.
+ *
+ * `file` is the only kind the Phase 1 connector implements; the rest are part of
+ * the IR contract and fail loudly rather than silently indexing nothing.
+ */
+export type SourceKind = 'file' | 's3' | 'http' | 'db' | 'mcp';
+/** `retriever.chunking.strategy`. */
+export type ChunkingStrategy = 'fixed' | 'recursive' | 'semantic' | 'code';
+/** `vectorStore.kind`. */
+export type StoreKind = 'memory' | 'pgvector' | 'qdrant' | 'pinecone' | 'weaviate' | 'custom';
+/** `retriever.refresh.mode`. Only `full` is implemented. */
+export type RefreshMode = 'full' | 'incremental';
+/** `retriever.source`. */
+export declare class SourceSpec {
+    readonly kind: SourceKind;
+    readonly uri: string;
+    readonly glob: string | null;
+    constructor(init: {
+        readonly kind: SourceKind;
+        readonly uri: string;
+        readonly glob?: string | null;
+    });
+}
+/** `retriever.chunking`. */
+export declare class ChunkingSpec {
+    readonly strategy: ChunkingStrategy;
+    readonly size: number;
+    readonly overlap: number;
+    readonly keepMetadata: readonly string[];
+    constructor(init: {
+        readonly strategy: ChunkingStrategy;
+        readonly size: number;
+        readonly overlap: number;
+        readonly keepMetadata?: readonly string[];
+    });
+}
+/** `retriever.index`. */
+export declare class IndexSpec {
+    readonly metric: DistanceMetric;
+    readonly hybrid: boolean;
+    readonly params: Readonly<Record<string, unknown>> | null;
+    constructor(init: {
+        readonly metric: DistanceMetric;
+        readonly hybrid: boolean;
+        readonly params?: Readonly<Record<string, unknown>> | null;
+    });
+}
+/** `retriever.rerank`. */
+export declare class RerankSpec {
+    readonly model: string;
+    readonly topN: number;
+    constructor(init: {
+        readonly model: string;
+        readonly topN: number;
+    });
+}
+/** `retriever.refresh`. */
+export declare class RefreshSpec {
+    readonly mode: RefreshMode;
+    readonly schedule: string | null;
+    constructor(init: {
+        readonly mode: RefreshMode;
+        readonly schedule?: string | null;
+    });
+}
+/** One entry of the IR's `retrievers` map. */
+export declare class RetrieverSpec {
+    readonly id: string;
+    readonly source: SourceSpec;
+    readonly chunking: ChunkingSpec;
+    readonly embedModel: string;
+    readonly store: string;
+    readonly index: IndexSpec;
+    readonly topK: number;
+    readonly rerank: RerankSpec | null;
+    readonly filters: readonly string[] | null;
+    readonly refresh: RefreshSpec;
+    readonly traits: readonly string[];
+    constructor(init: {
+        readonly id: string;
+        readonly source: SourceSpec;
+        readonly chunking: ChunkingSpec;
+        readonly embedModel: string;
+        readonly store: string;
+        readonly index: IndexSpec;
+        readonly topK: number;
+        readonly rerank?: RerankSpec | null;
+        readonly filters?: readonly string[] | null;
+        readonly refresh: RefreshSpec;
+        readonly traits?: readonly string[];
+    });
+}
+/**
+ * `embedding.costProfile` -- USD per **million** tokens.
+ *
+ * Not interchangeable with {@link CostProfile}, which prices per *thousand*
+ * tokens because it predates the IR. {@link pinnedEmbedding} is the single place
+ * the two are converted, so the factor of 1000 is stated once rather than assumed
+ * at every call site.
+ */
+export declare class EmbeddingCostProfile {
+    readonly inputPerMTok: number;
+    readonly outputPerMTok: number;
+    constructor(init: {
+        readonly inputPerMTok: number;
+        readonly outputPerMTok: number;
+    });
+}
+/**
+ * One entry of the IR's `embeddings` map.
+ *
+ * `id` is the *alias* a retriever's `embedModel` names -- the resolution the
+ * runtime must never repeat at run time.
+ */
+export declare class EmbeddingSpec {
+    readonly id: string;
+    readonly provider: string;
+    readonly modelId: string;
+    readonly dimensions: number | null;
+    readonly costProfile: EmbeddingCostProfile | null;
+    readonly traits: readonly string[];
+    constructor(init: {
+        readonly id: string;
+        readonly provider: string;
+        readonly modelId: string;
+        readonly dimensions?: number | null;
+        readonly costProfile?: EmbeddingCostProfile | null;
+        readonly traits?: readonly string[];
+    });
+}
+/** One entry of the IR's `stores` map. */
+export declare class VectorStoreSpec {
+    readonly id: string;
+    readonly kind: StoreKind;
+    readonly uri: string | null;
+    readonly dimensions: number | null;
+    readonly traits: readonly string[];
+    constructor(init: {
+        readonly id: string;
+        readonly kind: StoreKind;
+        readonly uri?: string | null;
+        readonly dimensions?: number | null;
+        readonly traits?: readonly string[];
+    });
+}
+/** The IR's `retrieval` metric variant: `{kind, expectDocs, k}`. */
+export declare class RetrievalMetricSpec {
+    readonly kind: 'retrieval';
+    readonly expectDocs: readonly string[];
+    readonly k: number;
+    constructor(init: {
+        readonly expectDocs: readonly string[];
+        readonly k: number;
+    });
+}
+/**
+ * An `embedModel` alias already resolved to an exact embedding model.
+ *
+ * The same contract as `PinnedModel`: a baseline recorded against
+ * `text-embedding-3-small` means nothing if the alias floats to another
+ * revision, so the resolved id, the dimensions and the price are all *recorded
+ * inputs* rather than lookups a run performs.
+ */
+export declare class PinnedEmbedding {
+    readonly alias: string;
+    readonly provider: string;
+    readonly modelId: string;
+    readonly dimensions: number;
+    readonly cost: CostProfile;
+    constructor(init: {
+        readonly alias: string;
+        readonly provider: string;
+        readonly modelId: string;
+        readonly dimensions: number;
+        readonly cost: CostProfile;
+    });
+}
+/**
+ * A retriever as generated code binds it, with every alias resolved.
+ *
+ * `embedModel` keeps the declared alias purely so cost can be attributed to the
+ * name the spec used; `embedding` is the resolved model actually called.
+ * `storeKind` is resolved from the store entry, because a run must not discover
+ * at search time which backend it wrote to.
+ *
+ * `storeUri` is deliberately kept *unresolved*: a hosted store's location is a
+ * deployment secret, which is why the IR writes `env:PGVECTOR_URL` rather than a
+ * DSN. The name is pinned in code; the value is read from the environment at run
+ * time, and an environment variable is not an alias.
+ */
+export declare class RetrieverBinding {
+    readonly retrieverId: string;
+    readonly source: SourceSpec;
+    readonly chunking: ChunkingSpec;
+    readonly embedModel: string;
+    readonly embedding: PinnedEmbedding;
+    readonly store: string;
+    readonly storeKind: StoreKind;
+    readonly storeUri: string | null;
+    readonly index: IndexSpec;
+    readonly topK: number;
+    readonly rerank: RerankSpec | null;
+    readonly refreshMode: RefreshMode;
+    readonly traits: readonly string[];
+    constructor(init: {
+        readonly retrieverId: string;
+        readonly source: SourceSpec;
+        readonly chunking: ChunkingSpec;
+        readonly embedModel: string;
+        readonly embedding: PinnedEmbedding;
+        readonly store: string;
+        readonly storeKind: StoreKind;
+        readonly storeUri?: string | null;
+        readonly index: IndexSpec;
+        readonly topK: number;
+        readonly rerank?: RerankSpec | null;
+        readonly refreshMode?: RefreshMode;
+        readonly traits?: readonly string[];
+    });
+}
+/**
+ * One indexed passage.
+ *
+ * `chunkId` hashes the document id, the chunk's position *and* its text. That is
+ * what makes ingest idempotent: identical input re-chunks to identical ids, so a
+ * second ingest replaces rather than duplicates. Position is part of the hash on
+ * purpose -- two byte-identical paragraphs in one document must stay two chunks
+ * instead of colliding into one.
+ */
+export declare class Chunk {
+    readonly chunkId: string;
+    readonly docId: string;
+    readonly uri: string;
+    readonly index: number;
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+    readonly metadata: Readonly<Record<string, string>>;
+    constructor(init: {
+        readonly chunkId: string;
+        readonly docId: string;
+        readonly uri?: string;
+        readonly index: number;
+        readonly start: number;
+        readonly end: number;
+        readonly text: string;
+        readonly metadata?: Readonly<Record<string, string>>;
+    });
+}
+/** A chunk with the score that ranked it. */
+export declare class ScoredChunk {
+    readonly chunk: Chunk;
+    readonly score: number;
+    constructor(init: {
+        readonly chunk: Chunk;
+        readonly score: number;
+    });
+}
+/**
+ * The content hash that identifies a chunk.
+ *
+ * Shared by every chunker so the id scheme cannot differ between strategies; a
+ * strategy that changed the id scheme would silently duplicate a corpus on
+ * re-ingest instead of replacing it.
+ */
+export declare function chunkIdFor(docId: string, index: number, text: string): string;
+/**
+ * Resolve an IR embedding entry into the pinned form generated code carries.
+ *
+ * `dimensions` may be supplied when the IR entry omits it (the schema makes it
+ * optional); it is an error to have neither, because an unpinned width would let a
+ * store accept vectors a later run cannot compare against.
+ */
+export declare function pinnedEmbedding(spec: EmbeddingSpec, init: {
+    readonly alias: string;
+    readonly dimensions?: number | null;
+}): PinnedEmbedding;
+/**
+ * Bind one IR retriever entry to the embedding and store it names.
+ *
+ * `embedModel` names an *embeddings entry id*, not a provider model, and `store`
+ * names a *stores entry id*. Both are checked here rather than trusted, because a
+ * mistyped reference in generated code would otherwise surface as an empty or
+ * mis-scored corpus far from its cause.
+ */
+export declare function bindingFromSpec(spec: RetrieverSpec, init: {
+    readonly embedding: EmbeddingSpec;
+    readonly store: VectorStoreSpec;
+    readonly dimensions?: number | null;
+}): RetrieverBinding;
+//# sourceMappingURL=types.d.ts.map

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

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