@cogenta/agents 0.1.2 → 0.2.0

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

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

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

@@ -0,0 +1,34 @@
+import { type DatabaseHandle, type Driver } from '@cogenta/core';
+import { type VectorConfig, type VectorStore } from './types.js';
+export interface PgVectorOptions {
+    readonly db: DatabaseHandle;
+    readonly dimensions: number;
+    readonly table?: string;
+}
+/**
+ * A pgvector literal.
+ *
+ * Bound as a parameter and cast in SQL (`$1::vector`), never interpolated: the
+ * numbers come from an embedding provider, which is code, but "it came from code
+ * this time" is not a property that survives a refactor. Non-finite values are
+ * refused rather than serialised — `NaN` in a vector column silently poisons
+ * every distance it takes part in.
+ */
+export declare function vectorLiteral(vector: readonly number[]): string;
+/**
+ * The optimal tier for the `vector` need — the row `docs/02-architecture.md`
+ * already named ("pgvector") and nothing implemented until L18.
+ *
+ * Distance is cosine (`<=>`), and the score handed back is `1 - distance`, so
+ * it is the same cosine similarity the memory and file drivers return: the
+ * shared contract suite compares the *same* numbers across all three, which is
+ * the only way "swap the driver, change nothing else" is a claim rather than a
+ * hope.
+ */
+export declare function createPgVectorStore(options: PgVectorOptions): Promise<VectorStore>;
+export interface PgVectorDriverOptions {
+    /** Absent means "this site has no database handle to lend", and the driver simply is not available. */
+    readonly db?: DatabaseHandle;
+}
+export declare function pgVectorDriver(options?: PgVectorDriverOptions): Driver<VectorStore, VectorConfig>;
+//# sourceMappingURL=pgvector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pgvector.d.ts","sourceRoot":"","sources":["../../../src/rag/vector/pgvector.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,MAAM,EAOZ,MAAM,eAAe,CAAA;AACtB,OAAO,EAEL,KAAK,YAAY,EAKjB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAA;AAInB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,cAAc,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAgBD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAW/D;AA+CD;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CA0JxF;AAED,MAAM,WAAW,qBAAqB;IACpC,uGAAuG;IACvG,QAAQ,CAAC,EAAE,CAAC,EAAE,cAAc,CAAA;CAC7B;AAED,wBAAgB,cAAc,CAC5B,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAAC,WAAW,EAAE,YAAY,CAAC,CAiDnC"}

package/dist/rag/vector/pgvector.js

@@ -0,0 +1,273 @@
+import { CogentaError, identifier, sql, limit as sqlLimit, unsafeRaw, } from '@cogenta/core';
+import { VECTOR_DEFAULTS, } from './types.js';
+const DEFAULT_TABLE = 'cogenta_vectors';
+/**
+ * A pgvector literal.
+ *
+ * Bound as a parameter and cast in SQL (`$1::vector`), never interpolated: the
+ * numbers come from an embedding provider, which is code, but "it came from code
+ * this time" is not a property that survives a refactor. Non-finite values are
+ * refused rather than serialised — `NaN` in a vector column silently poisons
+ * every distance it takes part in.
+ */
+export function vectorLiteral(vector) {
+    for (const value of vector) {
+        if (!Number.isFinite(value)) {
+            throw new CogentaError({
+                code: 'VECTOR_DIMENSION_MISMATCH',
+                message: 'An embedding contains a value that is not a finite number.',
+                hint: 'The embedding provider returned NaN or Infinity — re-embed the text, and check the provider response.',
+            });
+        }
+    }
+    return `[${vector.join(',')}]`;
+}
+function whereFrom(filter) {
+    if (filter === undefined)
+        return sql `true`;
+    const clauses = [sql `true`];
+    if (filter.siteId !== undefined)
+        clauses.push(sql `site_id = ${filter.siteId}`);
+    if (filter.collections !== undefined) {
+        clauses.push(filter.collections.length === 0
+            ? sql `false`
+            : sql `collection = any(${asTextArray(filter.collections)})`);
+    }
+    if (filter.locales !== undefined) {
+        clauses.push(filter.locales.length === 0 ? sql `false` : sql `locale = any(${asTextArray(filter.locales)})`);
+    }
+    if (filter.statuses !== undefined) {
+        clauses.push(filter.statuses.length === 0
+            ? sql `false`
+            : sql `status = any(${asTextArray(filter.statuses)})`);
+    }
+    if (filter.excludeEntryIds !== undefined && filter.excludeEntryIds.length > 0) {
+        clauses.push(sql `not (entry_id = any(${asTextArray(filter.excludeEntryIds)}))`);
+    }
+    let combined = clauses[0] ?? sql `true`;
+    for (const clause of clauses.slice(1))
+        combined = sql `${combined} and ${clause}`;
+    return combined;
+}
+/**
+ * `text[]` for `= any(…)`.
+ *
+ * `encodeValue` turns any array into JSON text, which Postgres will not accept
+ * as an array, so the values are bound one by one into an `array[…]`
+ * constructor instead. Still bound — no value ever reaches the SQL text.
+ */
+function asTextArray(values) {
+    let inner = sql `${values[0] ?? ''}::text`;
+    for (const value of values.slice(1))
+        inner = sql `${inner}, ${value}::text`;
+    return sql `array[${inner}]`;
+}
+/**
+ * The optimal tier for the `vector` need — the row `docs/02-architecture.md`
+ * already named ("pgvector") and nothing implemented until L18.
+ *
+ * Distance is cosine (`<=>`), and the score handed back is `1 - distance`, so
+ * it is the same cosine similarity the memory and file drivers return: the
+ * shared contract suite compares the *same* numbers across all three, which is
+ * the only way "swap the driver, change nothing else" is a claim rather than a
+ * hope.
+ */
+export async function createPgVectorStore(options) {
+    const { db, dimensions } = options;
+    const table = options.table ?? DEFAULT_TABLE;
+    if (db.dialect !== 'postgres') {
+        throw new CogentaError({
+            code: 'DB_DIALECT_UNSUPPORTED',
+            message: `The pgvector store needs Postgres and this site is on ${db.dialect}.`,
+            hint: 'Use the file or memory vector driver, or move the site to Postgres with the pgvector extension.',
+            details: { dialect: db.dialect },
+        });
+    }
+    const name = identifier(table, 'postgres');
+    await db.query(sql `create extension if not exists vector`);
+    await db.query(sql `
+    create table if not exists ${name} (
+      chunk_id text primary key,
+      site_id text not null,
+      collection text not null,
+      entry_id text not null,
+      locale text not null,
+      status text not null,
+      document_id text not null,
+      block_ids text not null,
+      chunk_text text not null,
+      chunk_hash text not null,
+      embedding vector(${unsafeRaw(String(Math.trunc(dimensions)))}) not null
+    )
+  `);
+    await db.query(sql `
+    create index if not exists ${identifier(`${table}_scope`, 'postgres')}
+      on ${name} (site_id, collection, entry_id)
+  `);
+    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 },
+        });
+    }
+    function toRecord(row) {
+        return {
+            siteId: row.site_id,
+            collection: row.collection,
+            entryId: row.entry_id,
+            locale: row.locale,
+            status: row.status,
+            chunk: {
+                id: row.chunk_id,
+                documentId: row.document_id,
+                blockIds: JSON.parse(row.block_ids),
+                text: row.chunk_text,
+                hash: row.chunk_hash,
+            },
+            // Not selected: a search result is used for its text and its score, and
+            // pulling every embedding back over the wire to hand it to a caller that
+            // discards it is pure cost. `upsert` is the only thing that needs the
+            // numbers, and it already has them.
+            vector: [],
+        };
+    }
+    return {
+        dimensions,
+        async upsert(records) {
+            for (const record of records)
+                assertDimensions(record);
+            if (records.length === 0)
+                return;
+            await db.transaction(async (tx) => {
+                for (const record of records) {
+                    await tx.query(sql `
+            insert into ${name}
+              (chunk_id, site_id, collection, entry_id, locale, status,
+               document_id, block_ids, chunk_text, chunk_hash, embedding)
+            values (
+              ${record.chunk.id}, ${record.siteId}, ${record.collection}, ${record.entryId},
+              ${record.locale}, ${record.status}, ${record.chunk.documentId},
+              ${JSON.stringify([...record.chunk.blockIds])}, ${record.chunk.text},
+              ${record.chunk.hash}, ${vectorLiteral([...record.vector])}::vector
+            )
+            on conflict (chunk_id) do update set
+              site_id = excluded.site_id,
+              collection = excluded.collection,
+              entry_id = excluded.entry_id,
+              locale = excluded.locale,
+              status = excluded.status,
+              document_id = excluded.document_id,
+              block_ids = excluded.block_ids,
+              chunk_text = excluded.chunk_text,
+              chunk_hash = excluded.chunk_hash,
+              embedding = excluded.embedding
+          `);
+                }
+            });
+        },
+        async remove(chunkIds) {
+            if (chunkIds.length === 0)
+                return;
+            await db.query(sql `delete from ${name} where chunk_id = any(${asTextArray([...chunkIds])})`);
+        },
+        async removeEntries(scope) {
+            if (scope.entryIds.length === 0)
+                return;
+            await db.query(sql `
+        delete from ${name}
+        where site_id = ${scope.siteId}
+          and collection = ${scope.collection}
+          and entry_id = any(${asTextArray([...scope.entryIds])})
+      `);
+        },
+        async search(queryVector, searchOptions) {
+            const count = searchOptions?.limit ?? VECTOR_DEFAULTS.limit;
+            const literal = vectorLiteral([...queryVector]);
+            const result = await db.query(sql `
+        select chunk_id, site_id, collection, entry_id, locale, status,
+               document_id, block_ids, chunk_text, chunk_hash,
+               1 - (embedding <=> ${literal}::vector) as score
+        from ${name}
+        where ${whereFrom(searchOptions?.filter)}
+        order by embedding <=> ${literal}::vector
+        limit ${sqlLimit(count)}
+      `);
+            const minScore = searchOptions?.minScore;
+            const matches = [];
+            for (const row of result.rows) {
+                const score = Number(row.score);
+                // The memory driver drops a zero or negative similarity; matching that
+                // here is what keeps the contract suite's expectations identical.
+                if (score <= 0)
+                    continue;
+                if (minScore !== undefined && score < minScore)
+                    continue;
+                matches.push({ record: toRecord(row), score });
+            }
+            return matches;
+        },
+        async count(filter) {
+            const result = await db.query(sql `select count(*) as total from ${name} where ${whereFrom(filter)}`);
+            return Number(result.rows[0]?.total ?? 0);
+        },
+        async clear() {
+            await db.query(sql `delete from ${name}`);
+        },
+    };
+}
+export function pgVectorDriver(options = {}) {
+    let store = null;
+    return {
+        name: 'pgvector',
+        tier: 'optimal',
+        available: async () => {
+            const db = options.db;
+            if (db === undefined || db.dialect !== 'postgres')
+                return false;
+            // "Does the service actually answer?", not "is a URL configured?" — the
+            // extension has to be installable, which on a managed Postgres it may
+            // well not be, and finding that out at `create table` time would be a
+            // startup crash instead of a fallback.
+            try {
+                await db.query(sql `create extension if not exists vector`);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        init: async (config) => {
+            const db = options.db;
+            if (db === undefined) {
+                throw new CogentaError({
+                    code: 'DRIVER_INIT_FAILED',
+                    message: 'The pgvector driver was selected without a database handle.',
+                    hint: 'Pass the site database to pgVectorDriver({ db }) when building the vector registry.',
+                });
+            }
+            store = await createPgVectorStore({
+                db,
+                dimensions: config.dimensions,
+                ...(config.table === undefined ? {} : { table: config.table }),
+            });
+            return store;
+        },
+        dispose: async () => {
+            // The handle belongs to the site, not to this driver: closing it here
+            // would take the whole CMS down with the vector index.
+            store = null;
+        },
+        health: async () => ({
+            status: 'ok',
+            driver: 'pgvector',
+            tier: 'optimal',
+            message: 'Embeddings are stored in Postgres with the pgvector extension.',
+            ...(store === null ? {} : { details: { records: await store.count() } }),
+        }),
+    };
+}
+//# sourceMappingURL=pgvector.js.map

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

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

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

@@ -0,0 +1,113 @@
+/**
+ * The `vector` driver need — L18 task 1 and task 5.
+ *
+ * **Task 1 was to check what already exists before writing anything, and the
+ * answer changed the shape of this file.** What was found:
+ *
+ * - `docs/02-architecture.md` names `vector` in the driver row ("pgvector,
+ *   MariaDB VECTOR | Cosinus exact en mémoire") and in the driver list of the
+ *   layer diagram — planned, never implemented.
+ * - `packages/core/src/drivers/` has the generic registry (`Driver`,
+ *   `createDriverRegistry`) that cache/queue/storage/database are all built on,
+ *   but **no** `vector` need registered anywhere.
+ * - `@cogenta/agents` already ships, from L4, the *retrieval* half: an
+ *   `EmbeddingProvider` interface with a real local implementation
+ *   (`createHashingEmbeddingProvider`), and a whole hybrid index —
+ *   `createMemoryRagIndex`, `bm25Rank`, `vectorRank`, `reciprocalRankFusion`,
+ *   with query-time permission filtering.
+ * - `packages/core/src/config/schema.ts` already has an `embeddings` section
+ *   (`provider`/`model`/`dimensions`).
+ *
+ * So the missing piece was never "a way to rank vectors" — that exists and is
+ * tested. It was **a place to keep them that outlives the process**, and a
+ * driver registry to pick between such places. That is exactly what this
+ * interface is, and nothing here re-implements cosine similarity: the memory
+ * driver calls the existing `vectorRank`.
+ *
+ * The interface is async where `RagIndex` is sync, because a store that reaches
+ * a database cannot be anything else. `RagIndex` is deliberately left alone: it
+ * is the in-request ranking primitive, this is the persistence one.
+ */
+import type { Chunk } from '../chunking/types.js';
+/**
+ * The scope every record carries, and the only thing a store may filter on.
+ *
+ * Deliberately not "any metadata": a store that accepts arbitrary filter
+ * predicates has to implement them per backend, and the ones that matter for a
+ * CMS are exactly these. Anything finer is the caller's `canAccess` predicate,
+ * applied above the store, where the real permission layer lives.
+ */
+export interface VectorScope {
+    readonly siteId: string;
+    readonly collection: string;
+    readonly entryId: string;
+    readonly locale: string;
+    /** `draft` / `published` / … — mirrors `ContentStatus` without importing `@cogenta/schema`. */
+    readonly status: string;
+}
+export interface VectorRecord extends VectorScope {
+    readonly chunk: Chunk;
+    readonly vector: readonly number[];
+}
+export interface VectorFilter {
+    readonly siteId?: string;
+    readonly collections?: readonly string[];
+    readonly locales?: readonly string[];
+    readonly statuses?: readonly string[];
+    /** Excludes one entry from its own results — what duplicate detection needs. */
+    readonly excludeEntryIds?: readonly string[];
+}
+export interface VectorMatch {
+    readonly record: VectorRecord;
+    /** Cosine similarity in `[-1, 1]`, comparable across backends because every backend computes cosine. */
+    readonly score: number;
+}
+export interface VectorSearchOptions {
+    readonly limit?: number;
+    readonly filter?: VectorFilter;
+    /**
+     * Discards matches below this cosine similarity. Absent means "keep
+     * everything the limit allows" — a threshold is a product decision (how close
+     * is "a duplicate"?), never a default this layer invents.
+     */
+    readonly minScore?: number;
+}
+/**
+ * Where embeddings live between requests.
+ *
+ * `dimensions` is on the store, not on each call, and `upsert` refuses a vector
+ * of any other length: an index holding two models' vectors ranks nonsense with
+ * no error anywhere, which is the single worst failure mode of this subsystem.
+ * The L4 rule stands unchanged — changing model means a parallel index, not a
+ * mixed one.
+ */
+export interface VectorStore {
+    readonly dimensions: number;
+    upsert(records: readonly VectorRecord[]): Promise<void>;
+    /** By chunk id. Unknown ids are ignored, not an error — a re-ingest must be idempotent. */
+    remove(chunkIds: readonly string[]): Promise<void>;
+    /** Everything belonging to these entries, whatever their chunk ids are. */
+    removeEntries(scope: {
+        readonly siteId: string;
+        readonly collection: string;
+        readonly entryIds: readonly string[];
+    }): Promise<void>;
+    search(queryVector: readonly number[], options?: VectorSearchOptions): Promise<readonly VectorMatch[]>;
+    count(filter?: VectorFilter): Promise<number>;
+    clear(): Promise<void>;
+}
+/** The resolved `vector` section of the configuration — same shape family as `CacheConfig`. */
+export interface VectorConfig {
+    readonly driver?: string;
+    readonly dimensions: number;
+    /** Where the `file` driver keeps its records. */
+    readonly path?: string;
+    /** Table name for the `pgvector` driver. */
+    readonly table?: string;
+}
+export declare const VECTOR_DEFAULTS: Readonly<{
+    limit: 10;
+}>;
+/** Shared by every driver so "which records are in scope" cannot drift between them. */
+export declare function matchesFilter(record: VectorRecord, filter?: VectorFilter): boolean;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/rag/vector/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAA;AAEjD;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CACnC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,gFAAgF;IAChF,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC7C;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,wGAAwG;IACxG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAA;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,MAAM,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACvD,2FAA2F;IAC3F,MAAM,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClD,2EAA2E;IAC3E,aAAa,CAAC,KAAK,EAAE;QACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;QAC3B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;KACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjB,MAAM,CACJ,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,SAAS,WAAW,EAAE,CAAC,CAAA;IAClC,KAAK,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED,+FAA+F;AAC/F,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAID,eAAO,MAAM,eAAe;;EAA0C,CAAA;AAEtE,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,YAAY,GAAG,OAAO,CAYlF"}

package/dist/rag/vector/types.js

@@ -0,0 +1,51 @@
+/**
+ * The `vector` driver need — L18 task 1 and task 5.
+ *
+ * **Task 1 was to check what already exists before writing anything, and the
+ * answer changed the shape of this file.** What was found:
+ *
+ * - `docs/02-architecture.md` names `vector` in the driver row ("pgvector,
+ *   MariaDB VECTOR | Cosinus exact en mémoire") and in the driver list of the
+ *   layer diagram — planned, never implemented.
+ * - `packages/core/src/drivers/` has the generic registry (`Driver`,
+ *   `createDriverRegistry`) that cache/queue/storage/database are all built on,
+ *   but **no** `vector` need registered anywhere.
+ * - `@cogenta/agents` already ships, from L4, the *retrieval* half: an
+ *   `EmbeddingProvider` interface with a real local implementation
+ *   (`createHashingEmbeddingProvider`), and a whole hybrid index —
+ *   `createMemoryRagIndex`, `bm25Rank`, `vectorRank`, `reciprocalRankFusion`,
+ *   with query-time permission filtering.
+ * - `packages/core/src/config/schema.ts` already has an `embeddings` section
+ *   (`provider`/`model`/`dimensions`).
+ *
+ * So the missing piece was never "a way to rank vectors" — that exists and is
+ * tested. It was **a place to keep them that outlives the process**, and a
+ * driver registry to pick between such places. That is exactly what this
+ * interface is, and nothing here re-implements cosine similarity: the memory
+ * driver calls the existing `vectorRank`.
+ *
+ * The interface is async where `RagIndex` is sync, because a store that reaches
+ * a database cannot be anything else. `RagIndex` is deliberately left alone: it
+ * is the in-request ranking primitive, this is the persistence one.
+ */
+const DEFAULT_LIMIT = 10;
+export const VECTOR_DEFAULTS = Object.freeze({ limit: DEFAULT_LIMIT });
+/** Shared by every driver so "which records are in scope" cannot drift between them. */
+export function matchesFilter(record, filter) {
+    if (filter === undefined)
+        return true;
+    if (filter.siteId !== undefined && record.siteId !== filter.siteId)
+        return false;
+    if (filter.collections !== undefined && !filter.collections.includes(record.collection)) {
+        return false;
+    }
+    if (filter.locales !== undefined && !filter.locales.includes(record.locale))
+        return false;
+    if (filter.statuses !== undefined && !filter.statuses.includes(record.status))
+        return false;
+    if (filter.excludeEntryIds !== undefined && filter.excludeEntryIds.includes(record.entryId)) {
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/rag/vector/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AA0FH,MAAM,aAAa,GAAG,EAAE,CAAA;AAExB,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC,CAAA;AAEtE,wFAAwF;AACxF,MAAM,UAAU,aAAa,CAAC,MAAoB,EAAE,MAAqB;IACvE,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IACrC,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAChF,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QACxF,OAAO,KAAK,CAAA;IACd,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAA;IACzF,IAAI,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAA;IAC3F,IAAI,MAAM,CAAC,eAAe,KAAK,SAAS,IAAI,MAAM,CAAC,eAAe,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5F,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/site-plan/analyse-brief.d.ts

@@ -0,0 +1,23 @@
+import type { ExtractedDocument } from '../documents/extract-text.js';
+import type { ProviderClient } from '../providers/types.js';
+import type { SiteBrief } from './types.js';
+export interface AnalyseBriefOptions {
+    readonly client: ProviderClient;
+    readonly model: string;
+    readonly documents: readonly ExtractedDocument[];
+    /** Shown to the model as context; never used to grant it anything. */
+    readonly siteName?: string;
+    /** "Trois tentatives" by default, the same budget `generateSkin` uses. */
+    readonly maxAttempts?: number;
+}
+export type AnalyseBriefResult = {
+    readonly ok: true;
+    readonly brief: SiteBrief;
+    readonly attempts: number;
+} | {
+    readonly ok: false;
+    readonly attempts: number;
+    readonly reason: string;
+};
+export declare function analyseBrief(options: AnalyseBriefOptions): Promise<AnalyseBriefResult>;
+//# sourceMappingURL=analyse-brief.d.ts.map

package/dist/site-plan/analyse-brief.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyse-brief.d.ts","sourceRoot":"","sources":["../../src/site-plan/analyse-brief.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAErE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAK3D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAgD3C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAA;IAChD,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,0EAA0E;IAC1E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAwE9E,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA2G5F"}