@cogenta/agents 0.1.2 → 0.2.0

package/dist/providers/image/types.js

@@ -0,0 +1,33 @@
+/**
+ * L18 task 4 — the image provider abstraction.
+ *
+ * Shaped exactly like `ProviderClient` (L4) and for the same stated reason:
+ * "un fournisseur d'image (driver, comme les fournisseurs LLM existants —
+ * plusieurs implémentations, jamais un seul fournisseur en dur)". Vendors
+ * disagree on nearly everything above the wire — OpenAI returns
+ * `data[].b64_json`, Stability returns `artifacts[].base64`, sizes are a
+ * `"1024x1024"` string in one and a width/height pair in the other — and this
+ * interface is the one place that difference is allowed to live.
+ *
+ * Unlike cache or storage there is **no degraded tier**, and there deliberately
+ * is no `Driver`/registry-with-fallback here: there is no local, service-free
+ * way to draw a picture from a sentence, so the honest degradation is that the
+ * feature is absent, not that it is slower. `createImageProviderRegistry`
+ * returns an empty registry for a site that configured none, and the tool is
+ * never built.
+ */
+/** Deliberately a small closed set: every vendor supports these three shapes. */
+export const IMAGE_SIZES = ['square', 'landscape', 'portrait'];
+const MAX_COUNT = 4;
+export function clampCount(count) {
+    if (count === undefined)
+        return 1;
+    return Math.min(Math.max(Math.trunc(count), 1), MAX_COUNT);
+}
+/** Pixel dimensions for the three named shapes. One table, so two adapters cannot disagree. */
+export const IMAGE_DIMENSIONS = Object.freeze({
+    square: { width: 1024, height: 1024 },
+    landscape: { width: 1536, height: 640 },
+    portrait: { width: 640, height: 1536 },
+});
+//# sourceMappingURL=types.js.map

package/dist/providers/image/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/providers/image/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,iFAAiF;AACjF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAQ,EAAE,WAAW,EAAE,UAAU,CAAU,CAAA;AAgCvE,MAAM,SAAS,GAAG,CAAC,CAAA;AAEnB,MAAM,UAAU,UAAU,CAAC,KAAyB;IAClD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,CAAC,CAAA;IACjC,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,CAAA;AAC5D,CAAC;AAED,+FAA+F;AAC/F,MAAM,CAAC,MAAM,gBAAgB,GAEzB,MAAM,CAAC,MAAM,CAAC;IAChB,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IACrC,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;IACvC,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE;CACvC,CAAC,CAAA"}

package/dist/rag/semantic/search.d.ts

@@ -0,0 +1,84 @@
+import type { EmbeddingProvider } from '../embeddings/types.js';
+import type { VectorStore } from '../vector/types.js';
+/**
+ * The slice of `@cogenta/schema`'s `SearchDriver` this module calls, declared
+ * structurally rather than imported — the same reasoning `ContentServiceLike`
+ * documents: the dependency arrow from `@cogenta/agents` to the content engine
+ * points one way only, and it is not this way.
+ *
+ * A real `SearchDriver` satisfies it as-is.
+ */
+export interface FullTextSearchLike {
+    search(query: {
+        readonly text: string;
+        readonly locale: string;
+        readonly status?: string;
+        readonly collections?: readonly string[];
+        readonly limit?: number;
+    }): Promise<{
+        readonly hits: readonly {
+            readonly id: string;
+            readonly collection: string;
+            readonly locale: string;
+            readonly status: string;
+            readonly title: string;
+            readonly score: number;
+        }[];
+    }>;
+}
+export interface SemanticHit {
+    readonly id: string;
+    readonly collection: string;
+    readonly locale: string;
+    readonly status: string;
+    readonly title: string;
+    /** The chunk that matched, when the hit came from the vector side. Absent for a full-text-only hit. */
+    readonly excerpt?: string;
+    /** Fused RRF score — a rank signal, never a distance or a probability. */
+    readonly score: number;
+    /** Which halves of the hybrid produced this hit. Shown in the admin, and the thing that makes "why is this here?" answerable. */
+    readonly matched: readonly ('semantic' | 'full-text')[];
+}
+export interface SemanticSearchQuery {
+    readonly text: string;
+    readonly locale: string;
+    readonly siteId: string;
+    readonly status?: string;
+    /** Already narrowed to what the actor may read — this module never decides that. */
+    readonly collections: readonly string[];
+    readonly limit?: number;
+}
+export interface SemanticSearch {
+    /** True when a vector store and an embedding provider are both wired in. */
+    readonly available: boolean;
+    search(query: SemanticSearchQuery): Promise<readonly SemanticHit[]>;
+}
+export interface SemanticSearchOptions {
+    readonly store: VectorStore;
+    readonly embeddings: EmbeddingProvider;
+    /**
+     * L10's full-text index. Optional, and its absence is not an error: the
+     * hybrid degrades to the vector half alone rather than refusing. The reverse
+     * — no vector half — is handled by not building this object at all.
+     */
+    readonly fullText?: FullTextSearchLike;
+    /** How many candidates each half contributes before fusion. */
+    readonly candidates?: number;
+}
+/**
+ * Semantic search, fused with the full-text search L10 wired up — **beside it,
+ * never instead of it**, which is what L18's dependency line asks for in as many
+ * words.
+ *
+ * Fusion is RRF over the two ranked lists, reusing L4's `reciprocalRankFusion`
+ * unchanged. Fusing ranks rather than scores is not a stylistic choice: a
+ * `ts_rank`, an InnoDB fulltext score and a cosine similarity live on three
+ * incomparable scales, and averaging them produces a number that means nothing.
+ *
+ * The known failure of pure vector search — exact-keyword queries, a part
+ * number, a person's name — is exactly what the full-text half covers, and the
+ * architecture document says so at line 190. Neither half is allowed to be the
+ * only one.
+ */
+export declare function createSemanticSearch(options: SemanticSearchOptions): SemanticSearch;
+//# sourceMappingURL=search.d.ts.map

package/dist/rag/semantic/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../../src/rag/semantic/search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAG/D,OAAO,KAAK,EAAe,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAElE;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,KAAK,EAAE;QACZ,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;QACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;QACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KACxB,GAAG,OAAO,CAAC;QACV,QAAQ,CAAC,IAAI,EAAE,SAAS;YACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;YACnB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;YAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;YACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;YACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;YACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;SACvB,EAAE,CAAA;KACJ,CAAC,CAAA;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,uGAAuG;IACvG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,iIAAiI;IACjI,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,UAAU,GAAG,WAAW,CAAC,EAAE,CAAA;CACxD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,oFAAoF;IACpF,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,MAAM,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAA;CACpE;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAA;IACtC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAmGnF"}

package/dist/rag/semantic/search.js

@@ -0,0 +1,113 @@
+import { reciprocalRankFusion } from '../index/rrf.js';
+const DEFAULT_LIMIT = 10;
+const DEFAULT_CANDIDATES = 30;
+function keyOf(collection, id) {
+    return `${collection}:${id}`;
+}
+/**
+ * Semantic search, fused with the full-text search L10 wired up — **beside it,
+ * never instead of it**, which is what L18's dependency line asks for in as many
+ * words.
+ *
+ * Fusion is RRF over the two ranked lists, reusing L4's `reciprocalRankFusion`
+ * unchanged. Fusing ranks rather than scores is not a stylistic choice: a
+ * `ts_rank`, an InnoDB fulltext score and a cosine similarity live on three
+ * incomparable scales, and averaging them produces a number that means nothing.
+ *
+ * The known failure of pure vector search — exact-keyword queries, a part
+ * number, a person's name — is exactly what the full-text half covers, and the
+ * architecture document says so at line 190. Neither half is allowed to be the
+ * only one.
+ */
+export function createSemanticSearch(options) {
+    const candidates = options.candidates ?? DEFAULT_CANDIDATES;
+    async function vectorHalf(query) {
+        const [vector] = await options.embeddings.embed([query.text]);
+        const byKey = new Map();
+        if (vector === undefined)
+            return { ranked: [], byKey };
+        const matches = await options.store.search(vector, {
+            limit: candidates,
+            filter: {
+                siteId: query.siteId,
+                collections: query.collections,
+                locales: [query.locale],
+                ...(query.status === undefined ? {} : { statuses: [query.status] }),
+            },
+        });
+        const ranked = [];
+        for (const match of matches) {
+            const key = keyOf(match.record.collection, match.record.entryId);
+            // Several chunks of one entry can match. The entry appears once, at its
+            // best chunk's rank — otherwise a long article crowds out every other
+            // result purely by having more chunks.
+            if (byKey.has(key))
+                continue;
+            byKey.set(key, match);
+            ranked.push({ id: key, score: match.score });
+        }
+        return { ranked, byKey };
+    }
+    async function textHalf(query) {
+        const byKey = new Map();
+        if (options.fullText === undefined)
+            return { ranked: [], byKey };
+        const results = await options.fullText.search({
+            text: query.text,
+            locale: query.locale,
+            collections: query.collections,
+            limit: candidates,
+            ...(query.status === undefined ? {} : { status: query.status }),
+        });
+        const ranked = [];
+        for (const hit of results.hits) {
+            const key = keyOf(hit.collection, hit.id);
+            if (byKey.has(key))
+                continue;
+            byKey.set(key, { title: hit.title, status: hit.status });
+            ranked.push({ id: key, score: hit.score });
+        }
+        return { ranked, byKey };
+    }
+    return {
+        available: true,
+        async search(query) {
+            if (query.collections.length === 0)
+                return [];
+            // Both halves run against the *already narrowed* collection list, so a
+            // collection the actor may not read is invisible to ranking rather than
+            // filtered out afterwards — the same ordering `createMemoryRagIndex`
+            // enforces, and for the same reason.
+            const [vector, text] = await Promise.all([vectorHalf(query), textHalf(query)]);
+            const fused = reciprocalRankFusion([vector.ranked, text.ranked]);
+            const limit = query.limit ?? DEFAULT_LIMIT;
+            const hits = [];
+            for (const { id: key, score } of fused) {
+                const match = vector.byKey.get(key);
+                const textHit = text.byKey.get(key);
+                const matched = [];
+                if (match !== undefined)
+                    matched.push('semantic');
+                if (textHit !== undefined)
+                    matched.push('full-text');
+                const collection = key.slice(0, key.indexOf(':'));
+                const entryId = key.slice(key.indexOf(':') + 1);
+                const title = textHit?.title ?? match?.record.chunk.text.slice(0, 80) ?? entryId;
+                hits.push({
+                    id: entryId,
+                    collection,
+                    locale: query.locale,
+                    status: textHit?.status ?? match?.record.status ?? 'published',
+                    title,
+                    ...(match === undefined ? {} : { excerpt: match.record.chunk.text }),
+                    score,
+                    matched,
+                });
+                if (hits.length >= limit)
+                    break;
+            }
+            return hits;
+        },
+    };
+}
+//# sourceMappingURL=search.js.map

package/dist/rag/semantic/search.js.map

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

package/dist/rag/vector/file.d.ts

@@ -0,0 +1,23 @@
+import { type Driver } from '@cogenta/core';
+import type { VectorConfig, VectorStore } from './types.js';
+export interface FileVectorOptions {
+    readonly dimensions: number;
+    readonly path?: string;
+}
+/**
+ * Vectors that survive a restart, with no service to install.
+ *
+ * Ranking is delegated to the memory store — the whole file is the working set,
+ * and re-ranking it in memory is exactly what the degraded row of
+ * `docs/02-architecture.md` describes. What this driver adds over `memory` is
+ * only durability, and that is deliberately the *only* difference: two drivers
+ * that also ranked differently would make the shared contract suite meaningless.
+ *
+ * JSONL, rewritten whole on every mutation through a temp file and a rename.
+ * That is O(n) per write and openly so: this driver is for the site that does
+ * not run Postgres, where n is thousands of chunks. A site past that point
+ * belongs on `pgvector`, and its health report says which one is running.
+ */
+export declare function createFileVectorStore(options: FileVectorOptions): Promise<VectorStore>;
+export declare function fileVectorDriver(): Driver<VectorStore, VectorConfig>;
+//# sourceMappingURL=file.d.ts.map

package/dist/rag/vector/file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file.d.ts","sourceRoot":"","sources":["../../../src/rag/vector/file.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,MAAM,EAAqB,MAAM,eAAe,CAAA;AAE5E,OAAO,KAAK,EACV,YAAY,EAIZ,WAAW,EACZ,MAAM,YAAY,CAAA;AAsBnB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAyCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CA2E5F;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,WAAW,EAAE,YAAY,CAAC,CAoCpE"}

package/dist/rag/vector/file.js

@@ -0,0 +1,170 @@
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import process from 'node:process';
+import { CogentaError } from '@cogenta/core';
+import { createMemoryVectorStore } from './memory.js';
+const DEFAULT_PATH = './.cogenta/vectors';
+const FILE_NAME = 'index.jsonl';
+/** Transient on Windows while another handle is still open on the target; clears within milliseconds. */
+const RETRYABLE = new Set(['EPERM', 'EACCES', 'EBUSY']);
+const RETRY_DELAYS_MS = [5, 10, 20, 40, 80, 160];
+async function withWindowsRetry(operation) {
+    for (const [attempt, delay] of RETRY_DELAYS_MS.entries()) {
+        try {
+            await operation();
+            return;
+        }
+        catch (error) {
+            const code = error.code ?? '';
+            if (!RETRYABLE.has(code) || attempt === RETRY_DELAYS_MS.length - 1)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, delay * (0.5 + Math.random())));
+        }
+    }
+}
+function storeFailed(message, hint, cause) {
+    return new CogentaError({
+        code: 'VECTOR_STORE_FAILED',
+        message,
+        hint,
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+async function readRecords(file) {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw storeFailed(`The vector index at ${file} could not be read.`, 'Check the file permissions, or delete the file to re-index from scratch.', error);
+    }
+    const records = [];
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            records.push(JSON.parse(trimmed));
+        }
+        catch (error) {
+            throw storeFailed(`The vector index at ${file} contains a line that is not JSON.`, 'Delete the file to re-index from scratch — it holds only derived embeddings, never content of record.', error);
+        }
+    }
+    return records;
+}
+/**
+ * Vectors that survive a restart, with no service to install.
+ *
+ * Ranking is delegated to the memory store — the whole file is the working set,
+ * and re-ranking it in memory is exactly what the degraded row of
+ * `docs/02-architecture.md` describes. What this driver adds over `memory` is
+ * only durability, and that is deliberately the *only* difference: two drivers
+ * that also ranked differently would make the shared contract suite meaningless.
+ *
+ * JSONL, rewritten whole on every mutation through a temp file and a rename.
+ * That is O(n) per write and openly so: this driver is for the site that does
+ * not run Postgres, where n is thousands of chunks. A site past that point
+ * belongs on `pgvector`, and its health report says which one is running.
+ */
+export async function createFileVectorStore(options) {
+    const directory = options.path ?? DEFAULT_PATH;
+    const file = join(directory, FILE_NAME);
+    const inner = createMemoryVectorStore({ dimensions: options.dimensions });
+    await mkdir(directory, { recursive: true });
+    /** The store interface has no enumeration, so durability needs its own mirror of what was written. */
+    const mirror = new Map();
+    const loaded = await readRecords(file);
+    // A file written under another model's dimensions is refused here, loudly,
+    // rather than silently ranking two vector spaces against each other.
+    await inner.upsert(loaded);
+    for (const record of loaded)
+        mirror.set(record.chunk.id, record);
+    async function persist() {
+        const body = [...mirror.values()].map((record) => JSON.stringify(record)).join('\n');
+        const temporary = `${file}.${process.pid}.tmp`;
+        await writeFile(temporary, body.length === 0 ? '' : `${body}\n`, 'utf8');
+        try {
+            await withWindowsRetry(() => rename(temporary, file));
+        }
+        catch (error) {
+            await rm(temporary, { force: true });
+            throw storeFailed(`The vector index at ${file} could not be written.`, 'Check that the directory is writable, or point vector.path somewhere that is.', error);
+        }
+    }
+    return {
+        dimensions: options.dimensions,
+        async upsert(records) {
+            // Validation first (the memory store refuses a wrong dimension), so a
+            // rejected batch never reaches the mirror and never reaches the disk.
+            await inner.upsert(records);
+            for (const record of records)
+                mirror.set(record.chunk.id, record);
+            await persist();
+        },
+        async remove(chunkIds) {
+            await inner.remove(chunkIds);
+            for (const id of chunkIds)
+                mirror.delete(id);
+            await persist();
+        },
+        async removeEntries(scope) {
+            await inner.removeEntries(scope);
+            const entries = new Set(scope.entryIds);
+            for (const [id, record] of mirror) {
+                if (record.siteId === scope.siteId &&
+                    record.collection === scope.collection &&
+                    entries.has(record.entryId)) {
+                    mirror.delete(id);
+                }
+            }
+            await persist();
+        },
+        search: (queryVector, searchOptions) => inner.search(queryVector, searchOptions),
+        count: (filter) => inner.count(filter),
+        async clear() {
+            await inner.clear();
+            mirror.clear();
+            await persist();
+        },
+    };
+}
+export function fileVectorDriver() {
+    let store = null;
+    let path = DEFAULT_PATH;
+    return {
+        name: 'file',
+        tier: 'degraded',
+        available: async (config) => {
+            try {
+                await mkdir(config.path ?? DEFAULT_PATH, { recursive: true });
+                return true;
+            }
+            catch {
+                // A read-only filesystem is a real answer, not a crash: the registry
+                // falls through to `memory` and the site still starts.
+                return false;
+            }
+        },
+        init: async (config) => {
+            path = config.path ?? DEFAULT_PATH;
+            store = await createFileVectorStore({
+                dimensions: config.dimensions,
+                ...(config.path === undefined ? {} : { path: config.path }),
+            });
+            return store;
+        },
+        dispose: async () => {
+            store = null;
+        },
+        health: async () => ({
+            status: 'degraded',
+            driver: 'file',
+            tier: 'degraded',
+            message: `Embeddings are kept on disk in ${path} and survive a restart; ranking is exact, over the whole index.`,
+            ...(store === null ? {} : { details: { records: await store.count() } }),
+        }),
+    };
+}
+//# sourceMappingURL=file.js.map

package/dist/rag/vector/file.js.map

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

package/dist/rag/vector/index.d.ts

@@ -0,0 +1,24 @@
+import { type DatabaseHandle, type DriverRegistry, type Logger } from '@cogenta/core';
+import type { VectorConfig, VectorStore } from './types.js';
+export type { FileVectorOptions } from './file.js';
+export { createFileVectorStore, fileVectorDriver } from './file.js';
+export { createMemoryVectorStore, memoryVectorDriver } from './memory.js';
+export type { PgVectorDriverOptions, PgVectorOptions } from './pgvector.js';
+export { createPgVectorStore, pgVectorDriver, vectorLiteral } from './pgvector.js';
+export type { VectorConfig, VectorFilter, VectorMatch, VectorRecord, VectorScope, VectorSearchOptions, VectorStore, } from './types.js';
+export { matchesFilter, VECTOR_DEFAULTS } from './types.js';
+export interface VectorRegistryOptions {
+    /** The site database, lent to `pgvector`. Absent means only the two service-free drivers can run. */
+    readonly db?: DatabaseHandle;
+    readonly logger?: Logger;
+}
+/**
+ * The vector drivers Cogenta ships, in tier order.
+ *
+ * `file` before `memory` among the degraded pair, for the same reason the cache
+ * registry orders them that way: both need no service, and the one that survives
+ * a restart is worth more than the one that does not. A site with no Postgres
+ * still gets working semantic search — that is R1, not a nicety.
+ */
+export declare function createVectorRegistry(options?: VectorRegistryOptions): DriverRegistry<VectorStore, VectorConfig>;
+//# sourceMappingURL=index.d.ts.map

package/dist/rag/vector/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/rag/vector/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,MAAM,EACZ,MAAM,eAAe,CAAA;AAItB,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE3D,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AACnE,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AACzE,YAAY,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC3E,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAClF,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,WAAW,GACZ,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAE3D,MAAM,WAAW,qBAAqB;IACpC,qGAAqG;IACrG,QAAQ,CAAC,EAAE,CAAC,EAAE,cAAc,CAAA;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAAC,WAAW,EAAE,YAAY,CAAC,CAW3C"}

package/dist/rag/vector/index.js

@@ -0,0 +1,27 @@
+import { createDriverRegistry, } from '@cogenta/core';
+import { fileVectorDriver } from './file.js';
+import { memoryVectorDriver } from './memory.js';
+import { pgVectorDriver } from './pgvector.js';
+export { createFileVectorStore, fileVectorDriver } from './file.js';
+export { createMemoryVectorStore, memoryVectorDriver } from './memory.js';
+export { createPgVectorStore, pgVectorDriver, vectorLiteral } from './pgvector.js';
+export { matchesFilter, VECTOR_DEFAULTS } from './types.js';
+/**
+ * The vector drivers Cogenta ships, in tier order.
+ *
+ * `file` before `memory` among the degraded pair, for the same reason the cache
+ * registry orders them that way: both need no service, and the one that survives
+ * a restart is worth more than the one that does not. A site with no Postgres
+ * still gets working semantic search — that is R1, not a nicety.
+ */
+export function createVectorRegistry(options = {}) {
+    const registry = createDriverRegistry({
+        need: 'vector',
+        ...(options.logger === undefined ? {} : { logger: options.logger }),
+    });
+    registry.register(pgVectorDriver(options.db === undefined ? {} : { db: options.db }));
+    registry.register(fileVectorDriver());
+    registry.register(memoryVectorDriver());
+    return registry;
+}
+//# sourceMappingURL=index.js.map

package/dist/rag/vector/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/rag/vector/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,GAIrB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAI9C,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AACnE,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEzE,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAUlF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAQ3D;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAO,GAA0B,EAAE;IAEnC,MAAM,QAAQ,GAAG,oBAAoB,CAA4B;QAC/D,IAAI,EAAE,QAAQ;QACd,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;KACpE,CAAC,CAAA;IAEF,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;IACrF,QAAQ,CAAC,QAAQ,CAAC,gBAAgB,EAAE,CAAC,CAAA;IACrC,QAAQ,CAAC,QAAQ,CAAC,kBAAkB,EAAE,CAAC,CAAA;IAEvC,OAAO,QAAQ,CAAA;AACjB,CAAC"}

package/dist/rag/vector/memory.d.ts

@@ -0,0 +1,16 @@
+import { type Driver } from '@cogenta/core';
+import { type VectorConfig, type VectorStore } from './types.js';
+/**
+ * The always-available tier (R1): every process has memory, nothing to install,
+ * nothing to configure. Exact cosine over every record in scope — which is what
+ * `docs/02-architecture.md` names as the degraded row for this need, and it is
+ * exact rather than approximate, so it is the *reference* answer the persistent
+ * drivers are checked against by the shared contract suite.
+ *
+ * Scoring is `vectorRank` from L4, unchanged and un-duplicated.
+ */
+export declare function createMemoryVectorStore(options: {
+    readonly dimensions: number;
+}): VectorStore;
+export declare function memoryVectorDriver(): Driver<VectorStore, VectorConfig>;
+//# sourceMappingURL=memory.d.ts.map

package/dist/rag/vector/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../src/rag/vector/memory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,MAAM,EAAqB,MAAM,eAAe,CAAA;AAE5E,OAAO,EAGL,KAAK,YAAY,EAKjB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAA;AAEnB;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,CA8E7F;AAED,wBAAgB,kBAAkB,IAAI,MAAM,CAAC,WAAW,EAAE,YAAY,CAAC,CA0BtE"}

package/dist/rag/vector/memory.js

@@ -0,0 +1,107 @@
+import { CogentaError } from '@cogenta/core';
+import { vectorRank } from '../index/vector-rank.js';
+import { matchesFilter, VECTOR_DEFAULTS, } from './types.js';
+/**
+ * The always-available tier (R1): every process has memory, nothing to install,
+ * nothing to configure. Exact cosine over every record in scope — which is what
+ * `docs/02-architecture.md` names as the degraded row for this need, and it is
+ * exact rather than approximate, so it is the *reference* answer the persistent
+ * drivers are checked against by the shared contract suite.
+ *
+ * Scoring is `vectorRank` from L4, unchanged and un-duplicated.
+ */
+export function createMemoryVectorStore(options) {
+    const { dimensions } = options;
+    const records = new Map();
+    function assertDimensions(record) {
+        if (record.vector.length === dimensions)
+            return;
+        throw new CogentaError({
+            code: 'VECTOR_DIMENSION_MISMATCH',
+            message: `This store holds ${dimensions}-dimension vectors and was handed one of ${record.vector.length}.`,
+            hint: 'Changing embedding model means a new, parallel index — never mixing two models in one store. Re-index from scratch after a model change.',
+            details: { expected: dimensions, received: record.vector.length, chunkId: record.chunk.id },
+        });
+    }
+    return {
+        dimensions,
+        async upsert(incoming) {
+            // Validated up front, all of them, before a single write lands: a batch
+            // that fails half-way through would leave the index in a state no caller
+            // can reason about.
+            for (const record of incoming)
+                assertDimensions(record);
+            for (const record of incoming)
+                records.set(record.chunk.id, record);
+        },
+        async remove(chunkIds) {
+            for (const id of chunkIds)
+                records.delete(id);
+        },
+        async removeEntries(scope) {
+            const entries = new Set(scope.entryIds);
+            for (const [id, record] of records) {
+                if (record.siteId === scope.siteId &&
+                    record.collection === scope.collection &&
+                    entries.has(record.entryId)) {
+                    records.delete(id);
+                }
+            }
+        },
+        async search(queryVector, searchOptions) {
+            const scoped = [...records.values()].filter((record) => matchesFilter(record, searchOptions?.filter));
+            const byId = new Map(scoped.map((record) => [record.chunk.id, record]));
+            const ranked = vectorRank(scoped.map((record) => ({
+                chunk: record.chunk,
+                siteId: record.siteId,
+                vector: record.vector,
+            })), queryVector);
+            const limit = searchOptions?.limit ?? VECTOR_DEFAULTS.limit;
+            const minScore = searchOptions?.minScore;
+            const matches = [];
+            for (const { id, score } of ranked) {
+                if (minScore !== undefined && score < minScore)
+                    break;
+                const record = byId.get(id);
+                if (record === undefined)
+                    continue;
+                matches.push({ record, score });
+                if (matches.length >= limit)
+                    break;
+            }
+            return matches;
+        },
+        async count(filter) {
+            return [...records.values()].filter((record) => matchesFilter(record, filter)).length;
+        },
+        async clear() {
+            records.clear();
+        },
+    };
+}
+export function memoryVectorDriver() {
+    let store = null;
+    return {
+        name: 'memory',
+        tier: 'degraded',
+        // Memory is the one thing that is always there. Saying so plainly is what
+        // makes it a usable last resort rather than one more thing that can refuse.
+        available: async () => true,
+        init: async (config) => {
+            store = createMemoryVectorStore({ dimensions: config.dimensions });
+            return store;
+        },
+        dispose: async () => {
+            await store?.clear();
+            store = null;
+        },
+        health: async () => ({
+            status: 'degraded',
+            driver: 'memory',
+            tier: 'degraded',
+            message: 'Embeddings are kept in memory and are lost on restart; the site re-indexes on the next ingest.',
+            ...(store === null ? {} : { details: { records: await store.count() } }),
+        }),
+    };
+}
+//# sourceMappingURL=memory.js.map