@adonis-agora/agent 0.1.0

package/dist/src/rag/ingest.d.ts

@@ -0,0 +1,33 @@
+import type { EmbeddingProvider } from '../spi/embedding-provider.js';
+import { type ChunkOptions } from './chunk.js';
+import type { VectorStore } from './vector-store.js';
+/** A source document to ingest. `id` scopes the chunk ids (`${id}#${n}`); `source` is the citation. */
+export interface IngestDocument {
+    id: string;
+    text: string;
+    source?: string;
+    metadata?: Record<string, unknown>;
+}
+/** A chunked, not-yet-embedded record. */
+export interface ChunkRecord {
+    id: string;
+    text: string;
+    source?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface IngestChunksOptions {
+    embedder: EmbeddingProvider;
+    store: VectorStore;
+}
+export interface IngestOptions extends ChunkOptions, IngestChunksOptions {
+}
+/**
+ * Split documents into chunk records. Chunk ids are `${doc.id}#${index}`, so re-chunking the same
+ * document produces the same ids (upsert overwrites in place rather than duplicating).
+ */
+export declare function chunkDocuments(documents: IngestDocument[], options?: ChunkOptions): ChunkRecord[];
+/** Embed pre-chunked records (one batched `embed`) and upsert them. Returns the record count. */
+export declare function ingestChunks(chunks: ChunkRecord[], options: IngestChunksOptions): Promise<number>;
+/** Chunk → embed → upsert in one call. Returns the number of chunks indexed. */
+export declare function ingestDocuments(documents: IngestDocument[], options: IngestOptions): Promise<number>;
+//# sourceMappingURL=ingest.d.ts.map

package/dist/src/rag/ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.d.ts","sourceRoot":"","sources":["../../../src/rag/ingest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,EAAE,KAAK,YAAY,EAAa,MAAM,YAAY,CAAC;AAC1D,OAAO,KAAK,EAAgB,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEnE,uGAAuG;AACvG,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,KAAK,EAAE,WAAW,CAAC;CACpB;AAED,MAAM,WAAW,aAAc,SAAQ,YAAY,EAAE,mBAAmB;CAAG;AAE3E;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,cAAc,EAAE,EAC3B,OAAO,GAAE,YAAiB,GACzB,WAAW,EAAE,CAaf;AAED,iGAAiG;AACjG,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED,gFAAgF;AAChF,wBAAsB,eAAe,CACnC,SAAS,EAAE,cAAc,EAAE,EAC3B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,CAAC,CAEjB"}

package/dist/src/rag/ingest.js

@@ -0,0 +1,37 @@
+import { chunkText } from './chunk.js';
+/**
+ * Split documents into chunk records. Chunk ids are `${doc.id}#${index}`, so re-chunking the same
+ * document produces the same ids (upsert overwrites in place rather than duplicating).
+ */
+export function chunkDocuments(documents, options = {}) {
+    const chunks = [];
+    for (const document of documents) {
+        chunkText(document.text, options).forEach((text, index) => {
+            chunks.push({
+                id: `${document.id}#${index}`,
+                text,
+                ...(document.source !== undefined ? { source: document.source } : {}),
+                ...(document.metadata !== undefined ? { metadata: document.metadata } : {}),
+            });
+        });
+    }
+    return chunks;
+}
+/** Embed pre-chunked records (one batched `embed`) and upsert them. Returns the record count. */
+export async function ingestChunks(chunks, options) {
+    if (chunks.length === 0) {
+        return 0;
+    }
+    const embeddings = await options.embedder.embed(chunks.map((chunk) => chunk.text));
+    const records = chunks.map((chunk, index) => ({
+        ...chunk,
+        embedding: embeddings[index] ?? [],
+    }));
+    await options.store.upsert(records);
+    return records.length;
+}
+/** Chunk → embed → upsert in one call. Returns the number of chunks indexed. */
+export async function ingestDocuments(documents, options) {
+    return ingestChunks(chunkDocuments(documents, options), options);
+}
+//# sourceMappingURL=ingest.js.map

package/dist/src/rag/ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.js","sourceRoot":"","sources":["../../../src/rag/ingest.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,SAAS,EAAE,MAAM,YAAY,CAAC;AA0B1D;;;GAGG;AACH,MAAM,UAAU,cAAc,CAC5B,SAA2B,EAC3B,UAAwB,EAAE;IAE1B,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;YACxD,MAAM,CAAC,IAAI,CAAC;gBACV,EAAE,EAAE,GAAG,QAAQ,CAAC,EAAE,IAAI,KAAK,EAAE;gBAC7B,IAAI;gBACJ,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACrE,GAAG,CAAC,QAAQ,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC5E,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,iGAAiG;AACjG,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAqB,EACrB,OAA4B;IAE5B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IACnF,MAAM,OAAO,GAAmB,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QAC5D,GAAG,KAAK;QACR,SAAS,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE;KACnC,CAAC,CAAC,CAAC;IACJ,MAAM,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpC,OAAO,OAAO,CAAC,MAAM,CAAC;AACxB,CAAC;AAED,gFAAgF;AAChF,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,SAA2B,EAC3B,OAAsB;IAEtB,OAAO,YAAY,CAAC,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;AACnE,CAAC"}

package/dist/src/rag/memory-vector-store.d.ts

@@ -0,0 +1,16 @@
+import type { Passage } from '../spi/retriever.js';
+import { type IndexedDocument, type VectorRecord, type VectorSearchOptions, type VectorStore } from './vector-store.js';
+/**
+ * An in-process {@link VectorStore} — cosine similarity over a Map, no infra. The reference adapter for
+ * tests and small/embedded corpora; a pgvector/Lucid-backed store for production scale is deferred.
+ */
+export declare class MemoryVectorStore implements VectorStore {
+    private readonly records;
+    upsert(records: VectorRecord[]): Promise<void>;
+    remove(documentId: string): Promise<void>;
+    listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
+    search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]>;
+}
+/** Cosine similarity of two vectors; `0` when either has zero magnitude. Pure. */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+//# sourceMappingURL=memory-vector-store.d.ts.map

package/dist/src/rag/memory-vector-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-vector-store.d.ts","sourceRoot":"","sources":["../../../src/rag/memory-vector-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAEjB,MAAM,mBAAmB,CAAC;AAE3B;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,WAAW;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAErD,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9C,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQzC,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAiB3E,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAgBpF;AAED,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAcjE"}

package/dist/src/rag/memory-vector-store.js

@@ -0,0 +1,70 @@
+import { matchesFilter } from './filter.js';
+import { documentIdOf, } from './vector-store.js';
+/**
+ * An in-process {@link VectorStore} — cosine similarity over a Map, no infra. The reference adapter for
+ * tests and small/embedded corpora; a pgvector/Lucid-backed store for production scale is deferred.
+ */
+export class MemoryVectorStore {
+    records = new Map();
+    async upsert(records) {
+        for (const record of records) {
+            this.records.set(record.id, record);
+        }
+    }
+    async remove(documentId) {
+        for (const id of this.records.keys()) {
+            if (documentIdOf(id) === documentId) {
+                this.records.delete(id);
+            }
+        }
+    }
+    async listDocuments(filter) {
+        const documents = new Map();
+        for (const record of this.records.values()) {
+            if (filter !== undefined && !matchesFilter(record.metadata, filter)) {
+                continue;
+            }
+            const id = documentIdOf(record.id);
+            if (!documents.has(id)) {
+                documents.set(id, {
+                    id,
+                    ...(record.metadata !== undefined ? { metadata: record.metadata } : {}),
+                });
+            }
+        }
+        return [...documents.values()];
+    }
+    async search(embedding, options) {
+        const scored = [];
+        for (const record of this.records.values()) {
+            if (options.filter !== undefined && !matchesFilter(record.metadata, options.filter)) {
+                continue;
+            }
+            scored.push({
+                id: record.id,
+                text: record.text,
+                score: cosineSimilarity(embedding, record.embedding),
+                ...(record.source !== undefined ? { source: record.source } : {}),
+                ...(record.metadata !== undefined ? { metadata: record.metadata } : {}),
+            });
+        }
+        return scored.sort((a, b) => b.score - a.score).slice(0, options.topK);
+    }
+}
+/** Cosine similarity of two vectors; `0` when either has zero magnitude. Pure. */
+export function cosineSimilarity(a, b) {
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    const length = Math.min(a.length, b.length);
+    for (let index = 0; index < length; index += 1) {
+        const valueA = a[index] ?? 0;
+        const valueB = b[index] ?? 0;
+        dot += valueA * valueB;
+        normA += valueA * valueA;
+        normB += valueB * valueB;
+    }
+    const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+    return denominator === 0 ? 0 : dot / denominator;
+}
+//# sourceMappingURL=memory-vector-store.js.map

package/dist/src/rag/memory-vector-store.js.map

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

package/dist/src/rag/pg-vector-store.d.ts

@@ -0,0 +1,84 @@
+import type { EmbeddingProvider } from '../spi/embedding-provider.js';
+import type { Passage } from '../spi/retriever.js';
+import type { LucidDatabaseLike } from '../stores/lucid.js';
+import { EmbeddingRetriever } from './embedding-retriever.js';
+import type { IndexedDocument, VectorRecord, VectorSearchOptions, VectorStore } from './vector-store.js';
+/**
+ * The similarity metric — which pgvector distance operator ranks results (and which index opclass the
+ * migration should build). `cosine` (the default) is scale-invariant and the right choice for most
+ * embedding models; `l2` (Euclidean) and `inner` (inner product) are offered for models trained for them.
+ */
+export type PgVectorMetric = 'cosine' | 'l2' | 'inner';
+/**
+ * Physical column names for the pgvector chunk table. Every field defaults to the mirror of the
+ * in-memory store's record shape (`id`/`text`/`source`/`metadata`/`embedding`); override to point the
+ * store at an existing table. Each name is validated against a strict identifier regex before it is ever
+ * spliced into SQL — the ONLY parts of a statement not passed as a positional binding.
+ */
+export interface PgVectorColumns {
+    /** Chunk id column (PK). Chunk ids are `${documentId}#<n>`. Default `id`. */
+    id?: string;
+    /** Chunk text column. Default `text`. */
+    text?: string;
+    /** Citation/source column (nullable). Default `source`. */
+    source?: string;
+    /** `jsonb` metadata column (nullable). Default `metadata`. */
+    metadata?: string;
+    /** `vector(N)` embedding column. Default `embedding`. */
+    embedding?: string;
+}
+export interface PgVectorStoreOptions {
+    /** Table name. Default `agent_rag_chunks`. Validated against the identifier regex. */
+    table?: string;
+    /** Embedding width — must match your model (e.g. 1536 for text-embedding-3-small). Default 1536. */
+    dimension?: number;
+    /** Similarity metric / distance operator. Default `cosine`. */
+    metric?: PgVectorMetric;
+    /** Override the physical column names (each validated). */
+    columns?: PgVectorColumns;
+}
+/** pgvector accepts a `'[1,2,3]'` text literal cast to `vector`; the literal itself is a `?` binding. */
+export declare function toVectorLiteral(embedding: number[]): string;
+/**
+ * A pgvector-backed {@link VectorStore} — the production RAG adapter, the durable twin of
+ * {@link import('./memory-vector-store.js').MemoryVectorStore}. It runs over the structural
+ * {@link LucidDatabaseLike} (so `@adonisjs/lucid` stays an optional peer — this file imports no Lucid
+ * types) with raw SQL for the pgvector operators. Similarity ranks via the `<=>`/`<->`/`<#>` operator for
+ * the configured {@link PgVectorMetric}; the query embedding is always a `?::vector` positional binding
+ * (NEVER string-interpolated) and metadata filters an `@> ?::jsonb` binding, so only the (validated)
+ * table/column identifiers are ever spliced into a statement.
+ *
+ * Usually you don't construct this directly: `config/agent.ts` selects it via `retrievers.pgvector({...})`
+ * and the provider builds it, lazily importing `@adonisjs/lucid` only when the pgvector retriever is
+ * chosen. Call {@link PgVectorStore.ensureSchema} once (or run the bundled migration) to provision the
+ * `vector` extension, the chunk table, and the metric's index.
+ */
+export declare class PgVectorStore implements VectorStore {
+    private readonly db;
+    private readonly table;
+    private readonly dimension;
+    private readonly metric;
+    private readonly metricName;
+    private readonly col;
+    constructor(db: LucidDatabaseLike, options?: PgVectorStoreOptions);
+    /**
+     * Idempotent DDL — the `vector` extension, the chunk table, and the metric's index. Handy for tests
+     * and scripts; an AdonisJS app should prefer the bundled migration so the schema is versioned.
+     */
+    ensureSchema(): Promise<void>;
+    /** The `CREATE EXTENSION` / `CREATE TABLE` / `CREATE INDEX` statements {@link ensureSchema} issues. */
+    schemaStatements(): string[];
+    upsert(records: VectorRecord[]): Promise<void>;
+    remove(documentId: string): Promise<void>;
+    listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
+    search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]>;
+}
+/**
+ * A {@link import('../spi/retriever.js').Retriever} over a {@link PgVectorStore}: embed the query, then
+ * pgvector-search. The production sibling of the in-memory {@link EmbeddingRetriever} wiring — this is
+ * what `retrievers.pgvector({...})` builds. Construct it directly for programmatic use, or let the factory.
+ */
+export declare class PgVectorRetriever extends EmbeddingRetriever {
+    constructor(embedder: EmbeddingProvider, store: PgVectorStore);
+}
+//# sourceMappingURL=pg-vector-store.d.ts.map

package/dist/src/rag/pg-vector-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pg-vector-store.d.ts","sourceRoot":"","sources":["../../../src/rag/pg-vector-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,WAAW,EACZ,MAAM,mBAAmB,CAAC;AAE3B;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oGAAoG;IACpG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,eAAe,CAAC;CAC3B;AAsDD,yGAAyG;AACzG,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAE3D;AAuCD;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,YAAW,WAAW;IAQ7C,OAAO,CAAC,QAAQ,CAAC,EAAE;IAPrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;gBAG7B,EAAE,EAAE,iBAAiB,EACtC,OAAO,GAAE,oBAAyB;IAgBpC;;;OAGG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAMnC,uGAAuG;IACvG,gBAAgB,IAAI,MAAM,EAAE;IAgBtB,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAsB9C,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMzC,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAoB3E,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAmCpF;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,kBAAkB;gBAE3C,QAAQ,EAAE,iBAAiB,EAAE,KAAK,EAAE,aAAa;CAG9D"}

package/dist/src/rag/pg-vector-store.js

@@ -0,0 +1,220 @@
+import { EmbeddingRetriever } from './embedding-retriever.js';
+const METRICS = {
+    cosine: {
+        operator: '<=>',
+        opclass: 'vector_cosine_ops',
+        score: (col) => `1 - (${col} <=> ?::vector)`,
+    },
+    l2: {
+        operator: '<->',
+        opclass: 'vector_l2_ops',
+        score: (col) => `-(${col} <-> ?::vector)`,
+    },
+    inner: {
+        // pgvector's `<#>` returns the NEGATIVE inner product, so `-(a <#> b)` recovers the inner product
+        // and `ORDER BY a <#> b ASC` ranks the largest inner product first — consistent with the others.
+        operator: '<#>',
+        opclass: 'vector_ip_ops',
+        score: (col) => `-(${col} <#> ?::vector)`,
+    },
+};
+/** Only unqualified SQL identifiers (letter/underscore start, then letters/digits/underscores) are allowed. */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Reject any table/column name that is not a bare SQL identifier. Table and column names are the only
+ * parts of a pgvector statement that CANNOT be a positional binding (an identifier is not a value), so
+ * every one is validated here before it is spliced in — closing the injection vector that raw operator
+ * SQL would otherwise open. Embeddings, filters, top-K are always `?` bindings and never reach this path.
+ */
+function assertIdentifier(name, role) {
+    if (!IDENTIFIER.test(name)) {
+        throw new Error(`Invalid ${role} "${name}": a pgvector identifier must match ${IDENTIFIER.source}`);
+    }
+    return name;
+}
+/** pgvector accepts a `'[1,2,3]'` text literal cast to `vector`; the literal itself is a `?` binding. */
+export function toVectorLiteral(embedding) {
+    return `[${embedding.join(',')}]`;
+}
+/** Normalize whatever a Lucid `rawQuery` returns (PG `{rows}`, SQLite array, MySQL `[rows,fields]`). */
+function normalizeRows(raw) {
+    if (Array.isArray(raw)) {
+        if (raw.length > 0 && Array.isArray(raw[0])) {
+            return raw[0];
+        }
+        return raw;
+    }
+    if (raw !== null && typeof raw === 'object' && Array.isArray(raw.rows)) {
+        return raw.rows;
+    }
+    return [];
+}
+/** A `jsonb` column comes back parsed (object) on `pg` or as a string on some drivers — accept both. */
+function parseMetadata(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    if (typeof value === 'object')
+        return value;
+    if (typeof value === 'string' && value.length > 0) {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * SQL that collapses a chunk id (`${documentId}#<n>`) back to its source document id — the pgvector
+ * mirror of {@link import('./vector-store.js').documentIdOf}. Shared by `remove` and `listDocuments` so
+ * both key on the exact same definition of "chunk belongs to document". `col` is a validated identifier.
+ */
+function documentIdExpr(col) {
+    return `regexp_replace(${col}, '#[0-9]+$', '')`;
+}
+/**
+ * A pgvector-backed {@link VectorStore} — the production RAG adapter, the durable twin of
+ * {@link import('./memory-vector-store.js').MemoryVectorStore}. It runs over the structural
+ * {@link LucidDatabaseLike} (so `@adonisjs/lucid` stays an optional peer — this file imports no Lucid
+ * types) with raw SQL for the pgvector operators. Similarity ranks via the `<=>`/`<->`/`<#>` operator for
+ * the configured {@link PgVectorMetric}; the query embedding is always a `?::vector` positional binding
+ * (NEVER string-interpolated) and metadata filters an `@> ?::jsonb` binding, so only the (validated)
+ * table/column identifiers are ever spliced into a statement.
+ *
+ * Usually you don't construct this directly: `config/agent.ts` selects it via `retrievers.pgvector({...})`
+ * and the provider builds it, lazily importing `@adonisjs/lucid` only when the pgvector retriever is
+ * chosen. Call {@link PgVectorStore.ensureSchema} once (or run the bundled migration) to provision the
+ * `vector` extension, the chunk table, and the metric's index.
+ */
+export class PgVectorStore {
+    db;
+    table;
+    dimension;
+    metric;
+    metricName;
+    col;
+    constructor(db, options = {}) {
+        this.db = db;
+        this.table = assertIdentifier(options.table ?? 'agent_rag_chunks', 'table');
+        this.dimension = options.dimension ?? 1536;
+        this.metricName = options.metric ?? 'cosine';
+        this.metric = METRICS[this.metricName];
+        const columns = options.columns ?? {};
+        this.col = {
+            id: assertIdentifier(columns.id ?? 'id', 'column'),
+            text: assertIdentifier(columns.text ?? 'text', 'column'),
+            source: assertIdentifier(columns.source ?? 'source', 'column'),
+            metadata: assertIdentifier(columns.metadata ?? 'metadata', 'column'),
+            embedding: assertIdentifier(columns.embedding ?? 'embedding', 'column'),
+        };
+    }
+    /**
+     * Idempotent DDL — the `vector` extension, the chunk table, and the metric's index. Handy for tests
+     * and scripts; an AdonisJS app should prefer the bundled migration so the schema is versioned.
+     */
+    async ensureSchema() {
+        for (const statement of this.schemaStatements()) {
+            await this.db.rawQuery(statement);
+        }
+    }
+    /** The `CREATE EXTENSION` / `CREATE TABLE` / `CREATE INDEX` statements {@link ensureSchema} issues. */
+    schemaStatements() {
+        const c = this.col;
+        return [
+            'CREATE EXTENSION IF NOT EXISTS vector',
+            `CREATE TABLE IF NOT EXISTS ${this.table} (
+        ${c.id} TEXT PRIMARY KEY,
+        ${c.text} TEXT NOT NULL,
+        ${c.source} TEXT,
+        ${c.metadata} JSONB,
+        ${c.embedding} vector(${this.dimension}) NOT NULL
+      )`,
+            `CREATE INDEX IF NOT EXISTS ${this.table}_${c.embedding}_idx
+        ON ${this.table} USING hnsw (${c.embedding} ${this.metric.opclass})`,
+        ];
+    }
+    async upsert(records) {
+        const c = this.col;
+        for (const record of records) {
+            await this.db.rawQuery(`INSERT INTO ${this.table} (${c.id}, ${c.text}, ${c.source}, ${c.metadata}, ${c.embedding})
+         VALUES (?, ?, ?, ?::jsonb, ?::vector)
+         ON CONFLICT (${c.id}) DO UPDATE SET
+           ${c.text} = EXCLUDED.${c.text},
+           ${c.source} = EXCLUDED.${c.source},
+           ${c.metadata} = EXCLUDED.${c.metadata},
+           ${c.embedding} = EXCLUDED.${c.embedding}`, [
+                record.id,
+                record.text,
+                record.source ?? null,
+                record.metadata !== undefined ? JSON.stringify(record.metadata) : null,
+                toVectorLiteral(record.embedding),
+            ]);
+        }
+    }
+    async remove(documentId) {
+        await this.db.rawQuery(`DELETE FROM ${this.table} WHERE ${documentIdExpr(this.col.id)} = ?`, [
+            documentId,
+        ]);
+    }
+    async listDocuments(filter) {
+        const c = this.col;
+        const docExpr = documentIdExpr(c.id);
+        const hasFilter = filter !== undefined && Object.keys(filter).length > 0;
+        const raw = await this.db.rawQuery(`SELECT DISTINCT ON (${docExpr}) ${docExpr} AS doc_id, ${c.metadata} AS metadata
+       FROM ${this.table}
+       ${hasFilter ? `WHERE ${c.metadata} @> ?::jsonb` : ''}
+       ORDER BY ${docExpr}`, hasFilter ? [JSON.stringify(filter)] : []);
+        return normalizeRows(raw).map((row) => {
+            const metadata = parseMetadata(row.metadata);
+            return {
+                id: String(row.doc_id),
+                ...(metadata !== undefined ? { metadata } : {}),
+            };
+        });
+    }
+    async search(embedding, options) {
+        const c = this.col;
+        const vector = toVectorLiteral(embedding);
+        const hasFilter = options.filter !== undefined && Object.keys(options.filter).length > 0;
+        // Bindings are consumed positionally, in the exact order the `?`s appear: score expr (embedding),
+        // then the optional filter, then the ORDER BY embedding, then the LIMIT. The embedding is bound
+        // TWICE — once per `?::vector` — because a positional `?` cannot be reused like a numbered `$1`.
+        const bindings = [vector];
+        let where = '';
+        if (hasFilter) {
+            where = `WHERE ${c.metadata} @> ?::jsonb`;
+            bindings.push(JSON.stringify(options.filter));
+        }
+        bindings.push(vector, options.topK);
+        const raw = await this.db.rawQuery(`SELECT ${c.id} AS id, ${c.text} AS text, ${c.source} AS source, ${c.metadata} AS metadata,
+              ${this.metric.score(c.embedding)} AS score
+       FROM ${this.table}
+       ${where}
+       ORDER BY ${c.embedding} ${this.metric.operator} ?::vector
+       LIMIT ?`, bindings);
+        return normalizeRows(raw).map((row) => {
+            const metadata = parseMetadata(row.metadata);
+            const source = row.source;
+            return {
+                id: String(row.id),
+                text: String(row.text),
+                score: Number(row.score),
+                ...(source !== null && source !== undefined ? { source: String(source) } : {}),
+                ...(metadata !== undefined ? { metadata } : {}),
+            };
+        });
+    }
+}
+/**
+ * A {@link import('../spi/retriever.js').Retriever} over a {@link PgVectorStore}: embed the query, then
+ * pgvector-search. The production sibling of the in-memory {@link EmbeddingRetriever} wiring — this is
+ * what `retrievers.pgvector({...})` builds. Construct it directly for programmatic use, or let the factory.
+ */
+export class PgVectorRetriever extends EmbeddingRetriever {
+    // biome-ignore lint/complexity/noUselessConstructor: not useless — it NARROWS `store` from the base's `VectorStore` to `PgVectorStore`, which is this subclass's whole point. Delete it and `new PgVectorRetriever(embedder, anyInMemoryStore)` starts compiling.
+    constructor(embedder, store) {
+        super(embedder, store);
+    }
+}
+//# sourceMappingURL=pg-vector-store.js.map

package/dist/src/rag/pg-vector-store.js.map

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

package/dist/src/rag/vector-store.d.ts

@@ -0,0 +1,47 @@
+import type { Passage } from '../spi/retriever.js';
+/** A stored, embedded chunk. `embedding` length must match the store's configured dimensions. */
+export interface VectorRecord {
+    id: string;
+    text: string;
+    embedding: number[];
+    /** Citation-facing origin (document title, URL, row id). */
+    source?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface VectorSearchOptions {
+    topK: number;
+    /** Exact-match metadata filter (all keys must equal). Passed through from `RetrieveOptions.filter`. */
+    filter?: Record<string, unknown>;
+}
+/**
+ * The write + search side of RAG storage. This package ships {@link import('./memory-vector-store.js').MemoryVectorStore}
+ * (in-JS cosine, tests + small/embedded corpora); a pgvector/Lucid-backed store is deferred. Pair one
+ * with an {@link import('../spi/embedding-provider.js').EmbeddingProvider} via
+ * {@link import('./embedding-retriever.js').EmbeddingRetriever} to get a `Retriever`.
+ */
+export interface VectorStore {
+    upsert(records: VectorRecord[]): Promise<void>;
+    search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]>;
+    /**
+     * Delete every chunk belonging to a source document — all records whose id is `${documentId}` or
+     * `${documentId}#<n>` (the id scheme {@link import('./ingest.js').chunkDocuments} produces). Use it to
+     * drop a document from the index, and before re-ingesting one: `upsert` overwrites matching ids but
+     * can't remove chunks a shorter new version no longer produces, so a re-ingest without a preceding
+     * `remove` leaves the old tail orphaned.
+     */
+    remove(documentId: string): Promise<void>;
+    /**
+     * List the distinct source documents currently indexed (chunk ids collapsed back to their document by
+     * stripping the trailing `#<n>`), each with a representative chunk's `metadata`, optionally narrowed
+     * by a metadata `filter`.
+     */
+    listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;
+}
+/** A distinct source document as seen by the index — its id plus a representative chunk's metadata. */
+export interface IndexedDocument {
+    id: string;
+    metadata?: Record<string, unknown>;
+}
+/** Collapse a chunk id (`${documentId}#<n>`) back to its source document id. */
+export declare function documentIdOf(chunkId: string): string;
+//# sourceMappingURL=vector-store.d.ts.map

package/dist/src/rag/vector-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store.d.ts","sourceRoot":"","sources":["../../../src/rag/vector-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAEnD,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9E;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C;;;;OAIG;IACH,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CAC7E;AAED,uGAAuG;AACvG,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,gFAAgF;AAChF,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/src/rag/vector-store.js

@@ -0,0 +1,5 @@
+/** Collapse a chunk id (`${documentId}#<n>`) back to its source document id. */
+export function documentIdOf(chunkId) {
+    return chunkId.replace(/#\d+$/, '');
+}
+//# sourceMappingURL=vector-store.js.map

package/dist/src/rag/vector-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store.js","sourceRoot":"","sources":["../../../src/rag/vector-store.ts"],"names":[],"mappings":"AAiDA,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAAC,OAAe;IAC1C,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC"}

package/dist/src/rag-media/diagnostics.d.ts

@@ -0,0 +1,43 @@
+export type RagMediaSkipReason = 'unsupported-type' | 'too-large' | 'empty-text';
+/** Emitted on `agora:rag:media.ingested` once a media file's chunks are embedded + upserted. */
+export interface RagMediaIngestedPayload {
+    mediaId: string;
+    ownerType?: string;
+    ownerId?: string;
+    collection?: string;
+    tenantRef?: string;
+    chunks: number;
+}
+/** Emitted on `agora:rag:media.removed` when a media document's chunks are dropped from the store. */
+export interface RagMediaRemovedPayload {
+    mediaId: string;
+}
+/** Emitted on `agora:rag:media.skipped` when a file is not indexed (unsupported/too-large/empty). */
+export interface RagMediaSkippedPayload {
+    mediaId: string;
+    contentType: string;
+    reason: RagMediaSkipReason;
+}
+/** Emitted on `agora:rag:media.failed` when an ingestion throws (bytes fetch / embed / upsert). */
+export interface RagMediaFailedPayload {
+    mediaId: string;
+    error: string;
+}
+/** Maps each event name to its payload type, so {@link publishRagMedia} is checked at the call site. */
+export interface RagMediaDiagnosticPayloads {
+    'media.ingested': RagMediaIngestedPayload;
+    'media.removed': RagMediaRemovedPayload;
+    'media.skipped': RagMediaSkippedPayload;
+    'media.failed': RagMediaFailedPayload;
+}
+export type RagMediaDiagnosticEvent = keyof RagMediaDiagnosticPayloads;
+/**
+ * Publish a rag-media event on `agora:rag:<event>` via the structural diagnostics slot. No-op when
+ * diagnostics isn't installed (the slot is empty) — and it never throws back into an ingestion.
+ */
+export declare function publishRagMedia<E extends RagMediaDiagnosticEvent>(event: E, payload: RagMediaDiagnosticPayloads[E]): void;
+export declare function publishRagMediaIngested(payload: RagMediaIngestedPayload): void;
+export declare function publishRagMediaRemoved(payload: RagMediaRemovedPayload): void;
+export declare function publishRagMediaSkipped(payload: RagMediaSkippedPayload): void;
+export declare function publishRagMediaFailed(payload: RagMediaFailedPayload): void;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/src/rag-media/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../src/rag-media/diagnostics.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,kBAAkB,GAAG,kBAAkB,GAAG,WAAW,GAAG,YAAY,CAAC;AAEjF,gGAAgG;AAChG,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AACD,sGAAsG;AACtG,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AACD,qGAAqG;AACrG,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AACD,mGAAmG;AACnG,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wGAAwG;AACxG,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,EAAE,uBAAuB,CAAC;IAC1C,eAAe,EAAE,sBAAsB,CAAC;IACxC,eAAe,EAAE,sBAAsB,CAAC;IACxC,cAAc,EAAE,qBAAqB,CAAC;CACvC;AAED,MAAM,MAAM,uBAAuB,GAAG,MAAM,0BAA0B,CAAC;AAEvE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,uBAAuB,EAC/D,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,0BAA0B,CAAC,CAAC,CAAC,GACrC,IAAI,CASN;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAE9E;AACD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAE5E;AACD,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAE5E;AACD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAE1E"}