@warlock.js/core 4.8.0 → 4.8.1

package/esm/ai/src/rag/rag.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"rag.mjs","names":["chunkText","runRetrieve"],"sources":["../../../../../../../../../@warlock.js/ai/src/rag/rag.ts"],"sourcesContent":["import { resolveDefaultStore } from \"../config\";\nimport { chunk as chunkText } from \"./chunk/chunk\";\nimport type { ChunkOptions } from \"./contracts/chunk-options.type\";\nimport type { RetrieveOptions, RetrieveResult } from \"./contracts/citation.type\";\nimport type {\n  Rag,\n  RagAsToolOptions,\n  RagConfig,\n} from \"./contracts/rag-config.type\";\nimport type { RagDocument } from \"./contracts/rag-document.type\";\nimport { ragAsTool } from \"./as-tool\";\nimport { retrieve as runRetrieve, type StoredChunk } from \"./retrieve\";\nimport { cacheVectorStore } from \"./store/cache-vector-store\";\nimport type { VectorStore } from \"./store/vector-store.contract\";\n\nconst DEFAULT_NAME = \"rag\";\nconst DEFAULT_NAMESPACE_PREFIX = \"ai.rag\";\n\n/**\n * Max chunk texts embedded per `embedder.embedMany()` call. One call is\n * one provider request, so a giant document is sub-batched to stay under\n * the provider's per-request token cap (the design's \"chunk larger than\n * provider per-request cap\" guard).\n */\nconst DEFAULT_MAX_BATCH = 96;\n\n/**\n * Create a RAG pipeline: **chunk → embed → vector store → retrieve →\n * rerank → cite**, reusing the app's `ai.embedder` for embedding, a\n * `@warlock.js/cache` `CacheDriver` as the vector store, and the\n * composite-as-tool engine to expose retrieval as a tool.\n *\n * Resolution is loud at construction (mirroring `memory()`):\n * - `embedder` is required — a provider with no embedder must be caught\n *   here, not at first index.\n * - `store` falls back to `ai.config({ defaultStore })`; if neither\n *   resolves, construction throws.\n *\n * `retrieve()` is return-only — it never auto-injects into a prompt; the\n * caller formats the cited chunks (or uses `asTool()` for the agent loop).\n * The reranker is OFF by default (cosine-only) unless `config.reranker`\n * is set.\n *\n * @example\n * import { ai } from \"@warlock.js/ai\";\n * import { MemoryCacheDriver } from \"@warlock.js/cache\";\n *\n * const kb = ai.rag({\n *   name: \"docs\",\n *   embedder: openai.embedder({ name: \"text-embedding-3-small\" }),\n *   store: new MemoryCacheDriver(),\n *   chunk: { type: \"markdown\", size: 800, overlap: 120 },\n * });\n *\n * await kb.index([{ id: \"guide\", text: longMarkdown, metadata: { url: \"/guide\" } }]);\n * const { chunks } = await kb.retrieve(\"how do I configure caching?\", { topK: 4 });\n */\nexport function rag(config: RagConfig): Rag {\n  const name = config.name ?? DEFAULT_NAME;\n\n  if (!config.embedder) {\n    throw new Error(\n      `rag(\"${name}\"): an \\`embedder\\` is required — pass one from a provider that supports embeddings (e.g. openai.embedder({ name: \"text-embedding-3-small\" }))`,\n    );\n  }\n\n  const driver = config.store ?? resolveDefaultStore();\n\n  if (!driver) {\n    throw new Error(\n      `rag(\"${name}\"): no store — pass \\`store\\` (a vector-capable @warlock.js/cache CacheDriver) or call \\`ai.config({ defaultStore })\\` at app boot before constructing the rag`,\n    );\n  }\n\n  const store: VectorStore = cacheVectorStore(driver);\n  const namespace = config.namespace ?? `${DEFAULT_NAMESPACE_PREFIX}.${name}`;\n  const embedder = config.embedder;\n\n  // Captured at first index for the dimension-mismatch guard in retrieve().\n  let indexedDimensions: number | undefined;\n\n  const instance: Rag = {\n    name,\n\n    async index(\n      docs: RagDocument[],\n      chunkOverride?: ChunkOptions,\n    ): Promise<{ chunks: number }> {\n      const chunkOptions = chunkOverride ?? config.chunk;\n\n      // Ingestion guardrails (D5) — fail BEFORE any embedding spend.\n      const limits = config.limits;\n      if (limits?.maxDocuments !== undefined && docs.length > limits.maxDocuments) {\n        throw new Error(\n          `rag(\"${name}\"): index() received ${docs.length} documents, exceeding the configured maxDocuments of ${limits.maxDocuments}`,\n        );\n      }\n      if (limits?.maxBytes !== undefined) {\n        const totalBytes = docs.reduce(\n          (sum, doc) => sum + Buffer.byteLength(doc.text ?? \"\"),\n          0,\n        );\n        if (totalBytes > limits.maxBytes) {\n          throw new Error(\n            `rag(\"${name}\"): index() received ${totalBytes} bytes of document text, exceeding the configured maxBytes of ${limits.maxBytes}`,\n          );\n        }\n      }\n\n      // Flatten every document into stored-chunk records + their texts,\n      // preserving document order so a single batched embed maps back 1:1.\n      const records: { key: string; value: StoredChunk; text: string; tags?: string[] }[] = [];\n\n      for (const doc of docs) {\n        const pieces = chunkText(doc.text, chunkOptions);\n\n        for (const piece of pieces) {\n          const value: StoredChunk = {\n            sourceId: doc.id,\n            chunkIndex: piece.index,\n            span: piece.span,\n            text: piece.text,\n            metadata: doc.metadata,\n          };\n\n          records.push({\n            key: keyFor(namespace, doc.id, piece.index),\n            value,\n            text: piece.text,\n            tags: doc.tags,\n          });\n        }\n      }\n\n      // Empty / whitespace-only documents yield zero chunks — write\n      // nothing and never embed an empty batch.\n      if (records.length === 0) {\n        return { chunks: 0 };\n      }\n\n      // Chunk cap (D5) — checked after chunking, still before embedding.\n      if (limits?.maxChunks !== undefined && records.length > limits.maxChunks) {\n        throw new Error(\n          `rag(\"${name}\"): index() produced ${records.length} chunks, exceeding the configured maxChunks of ${limits.maxChunks}`,\n        );\n      }\n\n      // Sub-batch the embed calls so one giant document does not blow the\n      // provider's per-request token cap.\n      for (let offset = 0; offset < records.length; offset += DEFAULT_MAX_BATCH) {\n        const batch = records.slice(offset, offset + DEFAULT_MAX_BATCH);\n        const { vectors, dimensions } = await embedder.embedMany(\n          batch.map((record) => record.text),\n        );\n\n        if (indexedDimensions === undefined && dimensions !== 0) {\n          indexedDimensions = dimensions;\n        }\n\n        await Promise.all(\n          batch.map((record, position) =>\n            store.upsert(record.key, record.value, vectors[position], record.tags),\n          ),\n        );\n      }\n\n      return { chunks: records.length };\n    },\n\n    async retrieve(query: string, options?: RetrieveOptions): Promise<RetrieveResult> {\n      return runRetrieve(\n        query,\n        {\n          embedder,\n          store,\n          namespace,\n          reranker: config.reranker,\n          defaults: config.retrieve,\n          indexedDimensions,\n        },\n        options,\n      );\n    },\n\n    async clear(): Promise<void> {\n      await store.removeNamespace(namespace);\n    },\n\n    asTool(options?: RagAsToolOptions) {\n      return ragAsTool(name, (query, retrieveOptions) => instance.retrieve(query, retrieveOptions), options);\n    },\n  };\n\n  return instance;\n}\n\n/**\n * Namespaced key for a stored chunk. Uses the `.` separator (matching\n * `SemanticMemory.keyFor`) so namespace-prefix filtering on the returned\n * `hit.key` stays aligned with the cache's `parseKey` normalization.\n */\nfunction keyFor(namespace: string, sourceId: string, chunkIndex: number): string {\n  return `${namespace}.${sourceId}.${chunkIndex}`;\n}\n"],"mappings":";;;;;;;AAeA,MAAM,eAAe;AACrB,MAAM,2BAA2B;;;;;;;AAQjC,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiC1B,SAAgB,IAAI,QAAwB;CAC1C,MAAM,OAAO,OAAO,QAAQ;CAE5B,IAAI,CAAC,OAAO,UACV,MAAM,IAAI,MACR,QAAQ,KAAK,+IACf;CAGF,MAAM,SAAS,OAAO,SAAS,oBAAoB;CAEnD,IAAI,CAAC,QACH,MAAM,IAAI,MACR,QAAQ,KAAK,+JACf;CAGF,MAAM,QAAqB,iBAAiB,MAAM;CAClD,MAAM,YAAY,OAAO,aAAa,GAAG,yBAAyB,GAAG;CACrE,MAAM,WAAW,OAAO;CAGxB,IAAI;CAEJ,MAAM,WAAgB;EACpB;EAEA,MAAM,MACJ,MACA,eAC6B;GAC7B,MAAM,eAAe,iBAAiB,OAAO;GAG7C,MAAM,SAAS,OAAO;GACtB,IAAI,QAAQ,iBAAiB,UAAa,KAAK,SAAS,OAAO,cAC7D,MAAM,IAAI,MACR,QAAQ,KAAK,uBAAuB,KAAK,OAAO,uDAAuD,OAAO,cAChH;GAEF,IAAI,QAAQ,aAAa,QAAW;IAClC,MAAM,aAAa,KAAK,QACrB,KAAK,QAAQ,MAAM,OAAO,WAAW,IAAI,QAAQ,EAAE,GACpD,CACF;IACA,IAAI,aAAa,OAAO,UACtB,MAAM,IAAI,MACR,QAAQ,KAAK,uBAAuB,WAAW,gEAAgE,OAAO,UACxH;GAEJ;GAIA,MAAM,UAAgF,CAAC;GAEvF,KAAK,MAAM,OAAO,MAAM;IACtB,MAAM,SAASA,MAAU,IAAI,MAAM,YAAY;IAE/C,KAAK,MAAM,SAAS,QAAQ;KAC1B,MAAM,QAAqB;MACzB,UAAU,IAAI;MACd,YAAY,MAAM;MAClB,MAAM,MAAM;MACZ,MAAM,MAAM;MACZ,UAAU,IAAI;KAChB;KAEA,QAAQ,KAAK;MACX,KAAK,OAAO,WAAW,IAAI,IAAI,MAAM,KAAK;MAC1C;MACA,MAAM,MAAM;MACZ,MAAM,IAAI;KACZ,CAAC;IACH;GACF;GAIA,IAAI,QAAQ,WAAW,GACrB,OAAO,EAAE,QAAQ,EAAE;GAIrB,IAAI,QAAQ,cAAc,UAAa,QAAQ,SAAS,OAAO,WAC7D,MAAM,IAAI,MACR,QAAQ,KAAK,uBAAuB,QAAQ,OAAO,iDAAiD,OAAO,WAC7G;GAKF,KAAK,IAAI,SAAS,GAAG,SAAS,QAAQ,QAAQ,UAAU,mBAAmB;IACzE,MAAM,QAAQ,QAAQ,MAAM,QAAQ,SAAS,iBAAiB;IAC9D,MAAM,EAAE,SAAS,eAAe,MAAM,SAAS,UAC7C,MAAM,KAAK,WAAW,OAAO,IAAI,CACnC;IAEA,IAAI,sBAAsB,UAAa,eAAe,GACpD,oBAAoB;IAGtB,MAAM,QAAQ,IACZ,MAAM,KAAK,QAAQ,aACjB,MAAM,OAAO,OAAO,KAAK,OAAO,OAAO,QAAQ,WAAW,OAAO,IAAI,CACvE,CACF;GACF;GAEA,OAAO,EAAE,QAAQ,QAAQ,OAAO;EAClC;EAEA,MAAM,SAAS,OAAe,SAAoD;GAChF,OAAOC,SACL,OACA;IACE;IACA;IACA;IACA,UAAU,OAAO;IACjB,UAAU,OAAO;IACjB;GACF,GACA,OACF;EACF;EAEA,MAAM,QAAuB;GAC3B,MAAM,MAAM,gBAAgB,SAAS;EACvC;EAEA,OAAO,SAA4B;GACjC,OAAO,UAAU,OAAO,OAAO,oBAAoB,SAAS,SAAS,OAAO,eAAe,GAAG,OAAO;EACvG;CACF;CAEA,OAAO;AACT;;;;;;AAOA,SAAS,OAAO,WAAmB,UAAkB,YAA4B;CAC/E,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG;AACrC"}

package/esm/ai/src/rag/rerank/keyword-reranker.mjs

@@ -1,58 +0,0 @@
-//#region ../@warlock.js/ai/src/rag/rerank/keyword-reranker.ts
-/** Splits text into lowercase alphanumeric terms. */
-function tokenize(text) {
-	return text.toLowerCase().split(/[^a-z0-9]+/).filter((term) => term.length > 0);
-}
-/**
-* Zero-dependency lexical reranker (a BM25-lite, IDF-free keyword overlap).
-*
-* For each candidate it computes the fraction of distinct query terms that
-* appear in the chunk, blends that with the candidate's original cosine
-* score by `weight`, and sorts descending. A pure-lexical pass costs
-* nothing beyond string splits — no peer, no model — so it is the
-* recommended opt-in reranker when an embedding-only ranking surfaces a
-* keyword-rich chunk too low.
-*
-* Ties (equal blended score) preserve the incoming order, so the cosine
-* ranking breaks ties deterministically.
-*
-* @example
-* const kb = ai.rag({ embedder, store, reranker: ai.rag.keywordReranker() });
-*/
-function keywordReranker(options = {}) {
-	const weight = options.weight ?? .5;
-	return {
-		name: "keyword",
-		async rerank(query, candidates) {
-			if (candidates.length === 0) return [];
-			const queryTerms = new Set(tokenize(query));
-			if (queryTerms.size === 0) return [...candidates];
-			const scored = candidates.map((candidate, position) => {
-				const chunkTerms = new Set(tokenize(candidate.text));
-				let overlap = 0;
-				for (const term of queryTerms) if (chunkTerms.has(term)) overlap += 1;
-				return {
-					candidate,
-					blended: weight * (overlap / queryTerms.size) + (1 - weight) * candidate.score,
-					position
-				};
-			});
-			scored.sort((first, second) => {
-				if (second.blended !== first.blended) return second.blended - first.blended;
-				return first.position - second.position;
-			});
-			return scored.map((entry) => ({
-				...entry.candidate,
-				score: entry.blended,
-				citation: {
-					...entry.candidate.citation,
-					score: entry.blended
-				}
-			}));
-		}
-	};
-}
-
-//#endregion
-export { keywordReranker };
-//# sourceMappingURL=keyword-reranker.mjs.map

package/esm/ai/src/rag/rerank/keyword-reranker.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"keyword-reranker.mjs","names":[],"sources":["../../../../../../../../../../@warlock.js/ai/src/rag/rerank/keyword-reranker.ts"],"sourcesContent":["import type { RetrievedChunk } from \"../contracts/citation.type\";\nimport type { RagReranker } from \"./reranker.contract\";\n\n/** Options for the {@link keywordReranker}. */\nexport type KeywordRerankerOptions = {\n  /**\n   * Weight of the lexical-overlap signal blended with the original cosine\n   * score, in `[0, 1]`. `1` ranks purely by keyword overlap; `0` keeps the\n   * cosine order. Default `0.5`.\n   */\n  weight?: number;\n};\n\n/** Splits text into lowercase alphanumeric terms. */\nfunction tokenize(text: string): string[] {\n  return text\n    .toLowerCase()\n    .split(/[^a-z0-9]+/)\n    .filter((term) => term.length > 0);\n}\n\n/**\n * Zero-dependency lexical reranker (a BM25-lite, IDF-free keyword overlap).\n *\n * For each candidate it computes the fraction of distinct query terms that\n * appear in the chunk, blends that with the candidate's original cosine\n * score by `weight`, and sorts descending. A pure-lexical pass costs\n * nothing beyond string splits — no peer, no model — so it is the\n * recommended opt-in reranker when an embedding-only ranking surfaces a\n * keyword-rich chunk too low.\n *\n * Ties (equal blended score) preserve the incoming order, so the cosine\n * ranking breaks ties deterministically.\n *\n * @example\n * const kb = ai.rag({ embedder, store, reranker: ai.rag.keywordReranker() });\n */\nexport function keywordReranker(options: KeywordRerankerOptions = {}): RagReranker {\n  const weight = options.weight ?? 0.5;\n\n  return {\n    name: \"keyword\",\n    async rerank(query: string, candidates: RetrievedChunk[]): Promise<RetrievedChunk[]> {\n      if (candidates.length === 0) {\n        return [];\n      }\n\n      const queryTerms = new Set(tokenize(query));\n\n      if (queryTerms.size === 0) {\n        return [...candidates];\n      }\n\n      const scored = candidates.map((candidate, position) => {\n        const chunkTerms = new Set(tokenize(candidate.text));\n\n        let overlap = 0;\n        for (const term of queryTerms) {\n          if (chunkTerms.has(term)) {\n            overlap += 1;\n          }\n        }\n\n        const lexical = overlap / queryTerms.size;\n        const blended = weight * lexical + (1 - weight) * candidate.score;\n\n        return { candidate, blended, position };\n      });\n\n      scored.sort((first, second) => {\n        if (second.blended !== first.blended) {\n          return second.blended - first.blended;\n        }\n\n        // Stable on ties: keep the incoming (cosine) order.\n        return first.position - second.position;\n      });\n\n      return scored.map((entry) => ({\n        ...entry.candidate,\n        score: entry.blended,\n        citation: { ...entry.candidate.citation, score: entry.blended },\n      }));\n    },\n  };\n}\n"],"mappings":";;AAcA,SAAS,SAAS,MAAwB;CACxC,OAAO,KACJ,YAAY,CAAC,CACb,MAAM,YAAY,CAAC,CACnB,QAAQ,SAAS,KAAK,SAAS,CAAC;AACrC;;;;;;;;;;;;;;;;;AAkBA,SAAgB,gBAAgB,UAAkC,CAAC,GAAgB;CACjF,MAAM,SAAS,QAAQ,UAAU;CAEjC,OAAO;EACL,MAAM;EACN,MAAM,OAAO,OAAe,YAAyD;GACnF,IAAI,WAAW,WAAW,GACxB,OAAO,CAAC;GAGV,MAAM,aAAa,IAAI,IAAI,SAAS,KAAK,CAAC;GAE1C,IAAI,WAAW,SAAS,GACtB,OAAO,CAAC,GAAG,UAAU;GAGvB,MAAM,SAAS,WAAW,KAAK,WAAW,aAAa;IACrD,MAAM,aAAa,IAAI,IAAI,SAAS,UAAU,IAAI,CAAC;IAEnD,IAAI,UAAU;IACd,KAAK,MAAM,QAAQ,YACjB,IAAI,WAAW,IAAI,IAAI,GACrB,WAAW;IAOf,OAAO;KAAE;KAAW,SAFJ,UADA,UAAU,WAAW,SACD,IAAI,UAAU,UAAU;KAE/B;IAAS;GACxC,CAAC;GAED,OAAO,MAAM,OAAO,WAAW;IAC7B,IAAI,OAAO,YAAY,MAAM,SAC3B,OAAO,OAAO,UAAU,MAAM;IAIhC,OAAO,MAAM,WAAW,OAAO;GACjC,CAAC;GAED,OAAO,OAAO,KAAK,WAAW;IAC5B,GAAG,MAAM;IACT,OAAO,MAAM;IACb,UAAU;KAAE,GAAG,MAAM,UAAU;KAAU,OAAO,MAAM;IAAQ;GAChE,EAAE;EACJ;CACF;AACF"}

package/esm/ai/src/rag/rerank/llm-reranker.mjs

@@ -1,85 +0,0 @@
-//#region ../@warlock.js/ai/src/rag/rerank/llm-reranker.ts
-/**
-* Build the scoring prompt — the model rates each candidate's relevance to
-* the query on a `0..1` scale and replies with one `index: score` line per
-* candidate. Kept terse and JSON-light so any chat model can answer.
-*/
-function buildPrompt(query, candidates) {
-	return [{
-		role: "system",
-		content: "You are a relevance grader. For each numbered passage, rate how well it answers the query on a scale from 0 (irrelevant) to 1 (fully relevant). Reply with ONLY a JSON array of objects like [{\"index\":0,\"score\":0.9}], one entry per passage, no prose."
-	}, {
-		role: "user",
-		content: `Query: ${query}\n\nPassages:\n${candidates.map((candidate, index) => `[${index}] ${candidate.text}`).join("\n\n")}`
-	}];
-}
-/**
-* Parse the model's reply into a score map. Tolerant of surrounding prose:
-* extracts the first JSON array and reads `{ index, score }` entries.
-* Returns an empty map when nothing parseable is found, so the caller can
-* fall back to the original order.
-*/
-function parseScores(reply) {
-	const scores = /* @__PURE__ */ new Map();
-	const start = reply.indexOf("[");
-	const end = reply.lastIndexOf("]");
-	if (start === -1 || end === -1 || end <= start) return scores;
-	let parsed;
-	try {
-		parsed = JSON.parse(reply.slice(start, end + 1));
-	} catch {
-		return scores;
-	}
-	if (!Array.isArray(parsed)) return scores;
-	for (const entry of parsed) if (entry && typeof entry.index === "number" && typeof entry.score === "number" && Number.isFinite(entry.score)) scores.set(entry.index, Math.max(0, Math.min(1, entry.score)));
-	return scores;
-}
-/**
-* Optional model-backed reranker.
-*
-* Asks an LLM to grade each over-fetched candidate's relevance to the
-* query on a `0..1` scale, then sorts descending by the model's score.
-* Candidates the model does not score keep their original cosine score, so
-* a partial/garbled reply degrades gracefully rather than dropping hits.
-* Scoring is batched (`batchSize`) to bound prompt length.
-*
-* Unlike {@link keywordReranker}, this costs one or more model calls per
-* retrieval — opt in only when precision matters more than latency/cost.
-*
-* @example
-* const kb = ai.rag({
-*   embedder,
-*   store,
-*   reranker: ai.rag.llmReranker({ model: openai.model({ name: "gpt-4o-mini" }) }),
-* });
-*/
-function llmReranker(options) {
-	const batchSize = options.batchSize ?? 10;
-	return {
-		name: "llm",
-		async rerank(query, candidates) {
-			if (candidates.length === 0) return [];
-			const rescored = [];
-			for (let offset = 0; offset < candidates.length; offset += batchSize) {
-				const batch = candidates.slice(offset, offset + batchSize);
-				const scores = parseScores((await options.model.complete(buildPrompt(query, batch))).content);
-				batch.forEach((candidate, index) => {
-					const score = scores.has(index) ? scores.get(index) : candidate.score;
-					rescored.push({
-						...candidate,
-						score,
-						citation: {
-							...candidate.citation,
-							score
-						}
-					});
-				});
-			}
-			return rescored.sort((first, second) => second.score - first.score);
-		}
-	};
-}
-
-//#endregion
-export { llmReranker };
-//# sourceMappingURL=llm-reranker.mjs.map

package/esm/ai/src/rag/rerank/llm-reranker.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"llm-reranker.mjs","names":[],"sources":["../../../../../../../../../../@warlock.js/ai/src/rag/rerank/llm-reranker.ts"],"sourcesContent":["import type { Message } from \"../../contracts/conversation-message.type\";\nimport type { ModelContract } from \"../../contracts/model.contract\";\nimport type { RetrievedChunk } from \"../contracts/citation.type\";\nimport type { RagReranker } from \"./reranker.contract\";\n\n/** Options for the {@link llmReranker}. */\nexport type LlmRerankerOptions = {\n  /** The model used to score candidate relevance. Required. */\n  model: ModelContract;\n  /**\n   * How many candidates to score per model call. Larger batches mean\n   * fewer round-trips but a longer prompt. Default `10`.\n   */\n  batchSize?: number;\n};\n\n/**\n * A single relevance score the model returns for a candidate, in `[0, 1]`,\n * keyed by the candidate's position in the batch.\n */\ntype ScoreLine = {\n  index: number;\n  score: number;\n};\n\n/**\n * Build the scoring prompt — the model rates each candidate's relevance to\n * the query on a `0..1` scale and replies with one `index: score` line per\n * candidate. Kept terse and JSON-light so any chat model can answer.\n */\nfunction buildPrompt(query: string, candidates: RetrievedChunk[]): Message[] {\n  const lines = candidates\n    .map((candidate, index) => `[${index}] ${candidate.text}`)\n    .join(\"\\n\\n\");\n\n  return [\n    {\n      role: \"system\",\n      content:\n        \"You are a relevance grader. For each numbered passage, rate how well it answers the query on a scale from 0 (irrelevant) to 1 (fully relevant). Reply with ONLY a JSON array of objects like [{\\\"index\\\":0,\\\"score\\\":0.9}], one entry per passage, no prose.\",\n    },\n    {\n      role: \"user\",\n      content: `Query: ${query}\\n\\nPassages:\\n${lines}`,\n    },\n  ];\n}\n\n/**\n * Parse the model's reply into a score map. Tolerant of surrounding prose:\n * extracts the first JSON array and reads `{ index, score }` entries.\n * Returns an empty map when nothing parseable is found, so the caller can\n * fall back to the original order.\n */\nfunction parseScores(reply: string): Map<number, number> {\n  const scores = new Map<number, number>();\n  const start = reply.indexOf(\"[\");\n  const end = reply.lastIndexOf(\"]\");\n\n  if (start === -1 || end === -1 || end <= start) {\n    return scores;\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(reply.slice(start, end + 1));\n  } catch {\n    return scores;\n  }\n\n  if (!Array.isArray(parsed)) {\n    return scores;\n  }\n\n  for (const entry of parsed as ScoreLine[]) {\n    if (\n      entry &&\n      typeof entry.index === \"number\" &&\n      typeof entry.score === \"number\" &&\n      Number.isFinite(entry.score)\n    ) {\n      scores.set(entry.index, Math.max(0, Math.min(1, entry.score)));\n    }\n  }\n\n  return scores;\n}\n\n/**\n * Optional model-backed reranker.\n *\n * Asks an LLM to grade each over-fetched candidate's relevance to the\n * query on a `0..1` scale, then sorts descending by the model's score.\n * Candidates the model does not score keep their original cosine score, so\n * a partial/garbled reply degrades gracefully rather than dropping hits.\n * Scoring is batched (`batchSize`) to bound prompt length.\n *\n * Unlike {@link keywordReranker}, this costs one or more model calls per\n * retrieval — opt in only when precision matters more than latency/cost.\n *\n * @example\n * const kb = ai.rag({\n *   embedder,\n *   store,\n *   reranker: ai.rag.llmReranker({ model: openai.model({ name: \"gpt-4o-mini\" }) }),\n * });\n */\nexport function llmReranker(options: LlmRerankerOptions): RagReranker {\n  const batchSize = options.batchSize ?? 10;\n\n  return {\n    name: \"llm\",\n    async rerank(query: string, candidates: RetrievedChunk[]): Promise<RetrievedChunk[]> {\n      if (candidates.length === 0) {\n        return [];\n      }\n\n      const rescored: RetrievedChunk[] = [];\n\n      for (let offset = 0; offset < candidates.length; offset += batchSize) {\n        const batch = candidates.slice(offset, offset + batchSize);\n        const response = await options.model.complete(buildPrompt(query, batch));\n        const scores = parseScores(response.content);\n\n        batch.forEach((candidate, index) => {\n          const score = scores.has(index) ? (scores.get(index) as number) : candidate.score;\n\n          rescored.push({\n            ...candidate,\n            score,\n            citation: { ...candidate.citation, score },\n          });\n        });\n      }\n\n      return rescored.sort((first, second) => second.score - first.score);\n    },\n  };\n}\n"],"mappings":";;;;;;AA8BA,SAAS,YAAY,OAAe,YAAyC;CAK3E,OAAO,CACL;EACE,MAAM;EACN,SACE;CACJ,GACA;EACE,MAAM;EACN,SAAS,UAAU,MAAM,iBAZf,WACX,KAAK,WAAW,UAAU,IAAI,MAAM,IAAI,UAAU,MAAM,CAAC,CACzD,KAAK,MAU0C;CAChD,CACF;AACF;;;;;;;AAQA,SAAS,YAAY,OAAoC;CACvD,MAAM,yBAAS,IAAI,IAAoB;CACvC,MAAM,QAAQ,MAAM,QAAQ,GAAG;CAC/B,MAAM,MAAM,MAAM,YAAY,GAAG;CAEjC,IAAI,UAAU,MAAM,QAAQ,MAAM,OAAO,OACvC,OAAO;CAGT,IAAI;CACJ,IAAI;EACF,SAAS,KAAK,MAAM,MAAM,MAAM,OAAO,MAAM,CAAC,CAAC;CACjD,QAAQ;EACN,OAAO;CACT;CAEA,IAAI,CAAC,MAAM,QAAQ,MAAM,GACvB,OAAO;CAGT,KAAK,MAAM,SAAS,QAClB,IACE,SACA,OAAO,MAAM,UAAU,YACvB,OAAO,MAAM,UAAU,YACvB,OAAO,SAAS,MAAM,KAAK,GAE3B,OAAO,IAAI,MAAM,OAAO,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,MAAM,KAAK,CAAC,CAAC;CAIjE,OAAO;AACT;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,YAAY,SAA0C;CACpE,MAAM,YAAY,QAAQ,aAAa;CAEvC,OAAO;EACL,MAAM;EACN,MAAM,OAAO,OAAe,YAAyD;GACnF,IAAI,WAAW,WAAW,GACxB,OAAO,CAAC;GAGV,MAAM,WAA6B,CAAC;GAEpC,KAAK,IAAI,SAAS,GAAG,SAAS,WAAW,QAAQ,UAAU,WAAW;IACpE,MAAM,QAAQ,WAAW,MAAM,QAAQ,SAAS,SAAS;IAEzD,MAAM,SAAS,aAAY,MADJ,QAAQ,MAAM,SAAS,YAAY,OAAO,KAAK,CAAC,EACpC,CAAC,OAAO;IAE3C,MAAM,SAAS,WAAW,UAAU;KAClC,MAAM,QAAQ,OAAO,IAAI,KAAK,IAAK,OAAO,IAAI,KAAK,IAAe,UAAU;KAE5E,SAAS,KAAK;MACZ,GAAG;MACH;MACA,UAAU;OAAE,GAAG,UAAU;OAAU;MAAM;KAC3C,CAAC;IACH,CAAC;GACH;GAEA,OAAO,SAAS,MAAM,OAAO,WAAW,OAAO,QAAQ,MAAM,KAAK;EACpE;CACF;AACF"}

package/esm/ai/src/rag/retrieve.mjs

@@ -1,68 +0,0 @@
-//#region ../@warlock.js/ai/src/rag/retrieve.ts
-/** Default number of chunks returned after reranking. */
-const DEFAULT_TOP_K = 5;
-/** Default cosine floor applied at the vector-store stage. */
-const DEFAULT_THRESHOLD = .5;
-/**
-* The cite pipeline: embed the query → over-fetch candidates from the
-* store → filter to this rag's namespace → map to {@link RetrievedChunk}s
-* with a {@link Citation} → optionally rerank → slice `topK`.
-*
-* Behavior matches the design's failure modes:
-* - No hits clearing the threshold → `{ query, chunks: [] }`, never throws.
-* - Namespace-prefix filtering keeps two rags sharing one driver isolated.
-* - A reranker that throws is caught; the raw cosine order is used instead.
-* - A dimension mismatch (indexed with model A, queried with model B)
-*   throws a clear error rather than returning garbage hits.
-*/
-async function retrieve(query, deps, options = {}) {
-	const topK = options.topK ?? deps.defaults?.topK ?? 5;
-	const threshold = options.threshold ?? deps.defaults?.threshold ?? .5;
-	const tags = options.tags ?? deps.defaults?.tags;
-	const candidates = options.candidates ?? deps.defaults?.candidates ?? Math.max(topK * 4, topK);
-	const { vector, dimensions } = await deps.embedder.embed(query);
-	if (deps.indexedDimensions !== void 0 && dimensions !== 0 && deps.indexedDimensions !== 0 && dimensions !== deps.indexedDimensions) throw new Error(`rag.retrieve(): query embedder dimensions (${dimensions}) do not match the dimensions captured at index time (${deps.indexedDimensions}); index and query must use the same embedding model`);
-	const hits = await deps.store.query(vector, {
-		topK: candidates,
-		threshold,
-		tags
-	});
-	const prefix = `${deps.namespace}.`;
-	let retrieved = hits.filter((hit) => hit.key.startsWith(prefix)).map((hit) => toRetrievedChunk(hit.value, hit.score));
-	retrieved = await applyReranker(query, retrieved, deps.reranker);
-	return {
-		query,
-		chunks: retrieved.slice(0, topK)
-	};
-}
-/** Build a cited {@link RetrievedChunk} from a stored chunk + its cosine score. */
-function toRetrievedChunk(stored, score) {
-	const citation = {
-		sourceId: stored.sourceId,
-		chunkIndex: stored.chunkIndex,
-		span: stored.span,
-		score,
-		metadata: stored.metadata
-	};
-	return {
-		text: stored.text,
-		score,
-		citation
-	};
-}
-/**
-* Run the optional reranker, degrading to the raw cosine order if it
-* throws — a flaky optional reranker must never fail the whole retrieval.
-*/
-async function applyReranker(query, candidates, reranker) {
-	if (!reranker) return candidates;
-	try {
-		return await reranker.rerank(query, candidates);
-	} catch {
-		return candidates;
-	}
-}
-
-//#endregion
-export { retrieve };
-//# sourceMappingURL=retrieve.mjs.map

package/esm/ai/src/rag/retrieve.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"retrieve.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/rag/retrieve.ts"],"sourcesContent":["import type { EmbedderContract } from \"../contracts/embedder.contract\";\nimport type {\n  Citation,\n  RetrievedChunk,\n  RetrieveOptions,\n  RetrieveResult,\n} from \"./contracts/citation.type\";\nimport type { RagReranker } from \"./rerank/reranker.contract\";\nimport type { VectorStore } from \"./store/vector-store.contract\";\n\n/** Default number of chunks returned after reranking. */\nexport const DEFAULT_TOP_K = 5;\n\n/** Default cosine floor applied at the vector-store stage. */\nexport const DEFAULT_THRESHOLD = 0.5;\n\n/**\n * Shape persisted per chunk in the vector store. The vector itself is held\n * by the driver's own index (passed via `set({ vector })`), so it is not\n * duplicated here.\n */\nexport type StoredChunk = {\n  sourceId: string;\n  chunkIndex: number;\n  span: [start: number, end: number];\n  text: string;\n  metadata?: Record<string, unknown>;\n};\n\n/** Dependencies the retrieve pipeline needs, resolved once by `rag()`. */\nexport type RetrieveDeps = {\n  embedder: EmbedderContract;\n  store: VectorStore;\n  /** Namespace prefix every stored key carries (e.g. `\"ai.rag.docs\"`). */\n  namespace: string;\n  /** Optional reranker; when absent the cosine order is kept. */\n  reranker?: RagReranker;\n  /** Pipeline-level retrieval defaults. */\n  defaults?: RetrieveOptions;\n  /**\n   * Dimension count captured at first index for the mismatch guard. When\n   * set, the query embedder's `dimensions` must equal it.\n   */\n  indexedDimensions?: number;\n};\n\n/**\n * The cite pipeline: embed the query → over-fetch candidates from the\n * store → filter to this rag's namespace → map to {@link RetrievedChunk}s\n * with a {@link Citation} → optionally rerank → slice `topK`.\n *\n * Behavior matches the design's failure modes:\n * - No hits clearing the threshold → `{ query, chunks: [] }`, never throws.\n * - Namespace-prefix filtering keeps two rags sharing one driver isolated.\n * - A reranker that throws is caught; the raw cosine order is used instead.\n * - A dimension mismatch (indexed with model A, queried with model B)\n *   throws a clear error rather than returning garbage hits.\n */\nexport async function retrieve(\n  query: string,\n  deps: RetrieveDeps,\n  options: RetrieveOptions = {},\n): Promise<RetrieveResult> {\n  const topK = options.topK ?? deps.defaults?.topK ?? DEFAULT_TOP_K;\n  const threshold = options.threshold ?? deps.defaults?.threshold ?? DEFAULT_THRESHOLD;\n  const tags = options.tags ?? deps.defaults?.tags;\n  const candidates = options.candidates ?? deps.defaults?.candidates ?? Math.max(topK * 4, topK);\n\n  const { vector, dimensions } = await deps.embedder.embed(query);\n\n  if (\n    deps.indexedDimensions !== undefined &&\n    dimensions !== 0 &&\n    deps.indexedDimensions !== 0 &&\n    dimensions !== deps.indexedDimensions\n  ) {\n    throw new Error(\n      `rag.retrieve(): query embedder dimensions (${dimensions}) do not match the dimensions captured at index time (${deps.indexedDimensions}); index and query must use the same embedding model`,\n    );\n  }\n\n  const hits = await deps.store.query<StoredChunk>(vector, {\n    topK: candidates,\n    threshold,\n    tags,\n  });\n\n  const prefix = `${deps.namespace}.`;\n\n  let retrieved: RetrievedChunk[] = hits\n    .filter((hit) => hit.key.startsWith(prefix))\n    .map((hit) => toRetrievedChunk(hit.value, hit.score));\n\n  retrieved = await applyReranker(query, retrieved, deps.reranker);\n\n  return { query, chunks: retrieved.slice(0, topK) };\n}\n\n/** Build a cited {@link RetrievedChunk} from a stored chunk + its cosine score. */\nfunction toRetrievedChunk(stored: StoredChunk, score: number): RetrievedChunk {\n  const citation: Citation = {\n    sourceId: stored.sourceId,\n    chunkIndex: stored.chunkIndex,\n    span: stored.span,\n    score,\n    metadata: stored.metadata,\n  };\n\n  return { text: stored.text, score, citation };\n}\n\n/**\n * Run the optional reranker, degrading to the raw cosine order if it\n * throws — a flaky optional reranker must never fail the whole retrieval.\n */\nasync function applyReranker(\n  query: string,\n  candidates: RetrievedChunk[],\n  reranker: RagReranker | undefined,\n): Promise<RetrievedChunk[]> {\n  if (!reranker) {\n    return candidates;\n  }\n\n  try {\n    return await reranker.rerank(query, candidates);\n  } catch {\n    // Logged at the call site in a richer build; here we degrade silently\n    // to vector-only ranking rather than aborting the retrieval.\n    return candidates;\n  }\n}\n"],"mappings":";;AAWA,MAAa,gBAAgB;;AAG7B,MAAa,oBAAoB;;;;;;;;;;;;;AA4CjC,eAAsB,SACpB,OACA,MACA,UAA2B,CAAC,GACH;CACzB,MAAM,OAAO,QAAQ,QAAQ,KAAK,UAAU;CAC5C,MAAM,YAAY,QAAQ,aAAa,KAAK,UAAU;CACtD,MAAM,OAAO,QAAQ,QAAQ,KAAK,UAAU;CAC5C,MAAM,aAAa,QAAQ,cAAc,KAAK,UAAU,cAAc,KAAK,IAAI,OAAO,GAAG,IAAI;CAE7F,MAAM,EAAE,QAAQ,eAAe,MAAM,KAAK,SAAS,MAAM,KAAK;CAE9D,IACE,KAAK,sBAAsB,UAC3B,eAAe,KACf,KAAK,sBAAsB,KAC3B,eAAe,KAAK,mBAEpB,MAAM,IAAI,MACR,8CAA8C,WAAW,wDAAwD,KAAK,kBAAkB,qDAC1I;CAGF,MAAM,OAAO,MAAM,KAAK,MAAM,MAAmB,QAAQ;EACvD,MAAM;EACN;EACA;CACF,CAAC;CAED,MAAM,SAAS,GAAG,KAAK,UAAU;CAEjC,IAAI,YAA8B,KAC/B,QAAQ,QAAQ,IAAI,IAAI,WAAW,MAAM,CAAC,CAAC,CAC3C,KAAK,QAAQ,iBAAiB,IAAI,OAAO,IAAI,KAAK,CAAC;CAEtD,YAAY,MAAM,cAAc,OAAO,WAAW,KAAK,QAAQ;CAE/D,OAAO;EAAE;EAAO,QAAQ,UAAU,MAAM,GAAG,IAAI;CAAE;AACnD;;AAGA,SAAS,iBAAiB,QAAqB,OAA+B;CAC5E,MAAM,WAAqB;EACzB,UAAU,OAAO;EACjB,YAAY,OAAO;EACnB,MAAM,OAAO;EACb;EACA,UAAU,OAAO;CACnB;CAEA,OAAO;EAAE,MAAM,OAAO;EAAM;EAAO;CAAS;AAC9C;;;;;AAMA,eAAe,cACb,OACA,YACA,UAC2B;CAC3B,IAAI,CAAC,UACH,OAAO;CAGT,IAAI;EACF,OAAO,MAAM,SAAS,OAAO,OAAO,UAAU;CAChD,QAAQ;EAGN,OAAO;CACT;AACF"}

package/esm/ai/src/rag/store/cache-vector-store.mjs

@@ -1,48 +0,0 @@
-//#region ../@warlock.js/ai/src/rag/store/cache-vector-store.ts
-/**
-* Adapt any `@warlock.js/cache` `CacheDriver` to the {@link VectorStore}
-* narrowing the RAG pipeline depends on. The cache driver IS the vector
-* store — exactly as `SemanticMemory` and `semanticCache` already use it:
-*
-* - `upsert` → `driver.set(key, value, { vector, tags })`
-* - `query`  → `driver.similar<T>(vector, { topK, threshold, tags })`
-* - `removeNamespace` → `driver.removeNamespace(namespace)`
-*
-* Drivers without similarity support throw `CacheUnsupportedError` from
-* `set({ vector })` / `similar()`; the error surfaces unchanged so the
-* caller sees the cache layer's own message (pointing at the `pg` /
-* `redis` drivers for production-scale similarity).
-*
-* @example
-* const store = cacheVectorStore(new MemoryCacheDriver());
-* await store.upsert("ai.rag.docs.guide.0", { text: "…" }, vector);
-* const hits = await store.query(queryVector, { topK: 5, threshold: 0.5 });
-*/
-function cacheVectorStore(driver) {
-	return {
-		async upsert(key, value, vector, tags) {
-			await driver.set(key, value, tags && tags.length > 0 ? {
-				vector,
-				tags
-			} : { vector });
-		},
-		async query(vector, options) {
-			return (await driver.similar(vector, {
-				topK: options.topK,
-				threshold: options.threshold,
-				tags: options.tags
-			})).map((hit) => ({
-				key: hit.key,
-				value: hit.value,
-				score: hit.score
-			}));
-		},
-		async removeNamespace(namespace) {
-			await driver.removeNamespace(namespace);
-		}
-	};
-}
-
-//#endregion
-export { cacheVectorStore };
-//# sourceMappingURL=cache-vector-store.mjs.map

package/esm/ai/src/rag/store/cache-vector-store.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"cache-vector-store.mjs","names":[],"sources":["../../../../../../../../../../@warlock.js/ai/src/rag/store/cache-vector-store.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\nimport type { VectorStore } from \"./vector-store.contract\";\n\n/**\n * Adapt any `@warlock.js/cache` `CacheDriver` to the {@link VectorStore}\n * narrowing the RAG pipeline depends on. The cache driver IS the vector\n * store — exactly as `SemanticMemory` and `semanticCache` already use it:\n *\n * - `upsert` → `driver.set(key, value, { vector, tags })`\n * - `query`  → `driver.similar<T>(vector, { topK, threshold, tags })`\n * - `removeNamespace` → `driver.removeNamespace(namespace)`\n *\n * Drivers without similarity support throw `CacheUnsupportedError` from\n * `set({ vector })` / `similar()`; the error surfaces unchanged so the\n * caller sees the cache layer's own message (pointing at the `pg` /\n * `redis` drivers for production-scale similarity).\n *\n * @example\n * const store = cacheVectorStore(new MemoryCacheDriver());\n * await store.upsert(\"ai.rag.docs.guide.0\", { text: \"…\" }, vector);\n * const hits = await store.query(queryVector, { topK: 5, threshold: 0.5 });\n */\nexport function cacheVectorStore(driver: CacheDriver<any, any>): VectorStore {\n  return {\n    async upsert(\n      key: string,\n      value: unknown,\n      vector: number[],\n      tags?: string[],\n    ): Promise<void> {\n      await driver.set(key, value, tags && tags.length > 0 ? { vector, tags } : { vector });\n    },\n\n    async query<T>(\n      vector: number[],\n      options: { topK: number; threshold?: number; tags?: string[] },\n    ): Promise<{ key: string; value: T; score: number }[]> {\n      const hits = await driver.similar<T>(vector, {\n        topK: options.topK,\n        threshold: options.threshold,\n        tags: options.tags,\n      });\n\n      return hits.map((hit: { key: string; value: T; score: number }) => ({\n        key: hit.key,\n        value: hit.value,\n        score: hit.score,\n      }));\n    },\n\n    async removeNamespace(namespace: string): Promise<void> {\n      await driver.removeNamespace(namespace);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,iBAAiB,QAA4C;CAC3E,OAAO;EACL,MAAM,OACJ,KACA,OACA,QACA,MACe;GACf,MAAM,OAAO,IAAI,KAAK,OAAO,QAAQ,KAAK,SAAS,IAAI;IAAE;IAAQ;GAAK,IAAI,EAAE,OAAO,CAAC;EACtF;EAEA,MAAM,MACJ,QACA,SACqD;GAOrD,QAAO,MANY,OAAO,QAAW,QAAQ;IAC3C,MAAM,QAAQ;IACd,WAAW,QAAQ;IACnB,MAAM,QAAQ;GAChB,CAAC,EAEU,CAAC,KAAK,SAAmD;IAClE,KAAK,IAAI;IACT,OAAO,IAAI;IACX,OAAO,IAAI;GACb,EAAE;EACJ;EAEA,MAAM,gBAAgB,WAAkC;GACtD,MAAM,OAAO,gBAAgB,SAAS;EACxC;CACF;AACF"}

package/esm/ai/src/rag/store/pg-vector-store.mjs

@@ -1,328 +0,0 @@
-//#region ../@warlock.js/ai/src/rag/store/pg-vector-store.ts
-/**
-* Default backing table — provisions the store with no extra config when
-* the dev runs {@link VectorStore.schema | ensureSchema} through their
-* migration tool.
-*/
-const DEFAULT_TABLE = "warlock_ai_rag_vectors";
-/** Default embedding width baked into the DDL (OpenAI `text-embedding-3-small`). */
-const DEFAULT_DIMENSIONS = 1536;
-/** Default `ivfflat` list count when that index strategy is chosen. */
-const DEFAULT_IVFFLAT_LISTS = 100;
-/**
-* Allowed characters in a Postgres identifier (table name). The table name
-* is interpolated into DDL/DML, so anything outside this conservative
-* ASCII subset is rejected — interpolating an arbitrary string would be a
-* SQL-injection footgun (mirrors the snapshot / human-interrupt pg stores
-* and `@warlock.js/cache`'s `PgCacheDriver`).
-*/
-const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
-/**
-* Module specifier for the optional `pg` driver. Held in a `string`
-* variable so the dynamic `import()` is not statically resolved at compile
-* time — `pg` is an optional peer that need not be installed for this
-* package to type-check or for a cache-only consumer to run.
-*/
-const PG_MODULE = "pg";
-/**
-* Curated install string surfaced (at use time) when a `connectionString`
-* is configured but the optional `pg` driver is absent. Never thrown at
-* import — a cache-only consumer must be able to load this module.
-*/
-const PG_INSTALL_INSTRUCTIONS = `
-The @warlock.js/ai Postgres vector store requires the pg package and a
-Postgres database with the pgvector extension. Install the driver with:
-
-  npm install pg
-
-Or with your preferred package manager:
-
-  pnpm add pg
-  yarn add pg
-`.trim();
-/**
-* Lazily import `pg` and return a `Pool` built from `connectionString`. A
-* bare `catch` rethrows the curated install string — a missing optional
-* peer surfaces as actionable guidance, never a raw resolution error.
-*/
-async function buildPgClient(connectionString) {
-	let sdk;
-	try {
-		sdk = await import(PG_MODULE);
-	} catch {
-		throw new Error(PG_INSTALL_INSTRUCTIONS);
-	}
-	return new sdk.Pool({ connectionString });
-}
-/**
-* Serialize a JS `number[]` to the pgvector text literal: `[1,2,3]`.
-* pgvector accepts a vector either as this bracketed literal or via a
-* typed parameter; passing the literal string + an explicit `::vector`
-* cast keeps the store driver-agnostic (no dependency on a registered
-* `pg` type parser).
-*
-* Non-finite components (`NaN` / `±Infinity`) are rejected — pgvector
-* stores only finite floats, and silently coercing them would corrupt the
-* index. The check is cheap relative to the embed call that produced the
-* vector.
-*
-* @example
-* vectorLiteral([1, 0.5, -2]); // "[1,0.5,-2]"
-*/
-function vectorLiteral(vector) {
-	let literal = "[";
-	for (let index = 0; index < vector.length; index++) {
-		const component = vector[index];
-		if (!Number.isFinite(component)) throw new TypeError(`pgVectorStore: embedding component at index ${index} is not finite (${component}); pgvector stores only finite floats.`);
-		if (index > 0) literal += ",";
-		literal += String(component);
-	}
-	return literal + "]";
-}
-/**
-* Coerce a `value` JSONB column back into the stored payload. node-postgres
-* parses `JSONB` into a JS value already, but some pool wrappers hand back
-* the raw string — be defensive across both (mirrors the snapshot store's
-* `parsePayload`).
-*/
-function parseValue(value) {
-	if (typeof value === "string") return JSON.parse(value);
-	return value;
-}
-/**
-* Coerce a pgvector cosine **distance** (`<=>`, in `[0, 2]`, 0 = identical)
-* into the cosine **similarity** score the {@link VectorStore} contract
-* declares (`[0, 1]`, 1 = identical). `pg` returns the computed distance
-* column as a string for `double precision`; parse then map `1 - distance`,
-* clamped to `[0, 1]` so a tiny floating-point overshoot never yields a
-* score just outside the contract's range.
-*/
-function distanceToScore(distance) {
-	const score = 1 - (typeof distance === "string" ? Number(distance) : distance);
-	if (score < 0) return 0;
-	if (score > 1) return 1;
-	return score;
-}
-/**
-* Postgres + pgvector-backed {@link VectorStore} — one durable row per
-* indexed chunk, keyed by the RAG pipeline's dotted `key`
-* (`ai.rag.<name>.<sourceId>.<chunkIndex>`), with the chunk payload in a
-* `value` JSONB column and the embedding in a `vector` column.
-*
-* Owns: the three RAG vector operations against a pgvector index —
-* `upsert` (INSERT … ON CONFLICT DO UPDATE), `query` (cosine
-* `ORDER BY embedding <=> $vec` with a `threshold` floor + optional `tags`
-* overlap filter, capped at `topK`), and `removeNamespace` (prefix DELETE).
-* Also emits the reference DDL via {@link PgVectorStore.schema} (alias
-* {@link PgVectorStore.ensureSchema}).
-*
-* Does NOT own: the connection lifecycle (a dev-supplied `client` is never
-* closed; a store-built `Pool` from a `connectionString` is also left open
-* for the process to reuse) or schema migration — the dev runs the DDL
-* through their own tool; the framework never auto-migrates.
-*
-* Front it with the {@link pgVectorStore} factory — callers never `new` it.
-*/
-var PgVectorStore = class {
-	constructor(options) {
-		const table = options.table ?? DEFAULT_TABLE;
-		if (!SAFE_IDENTIFIER.test(table)) throw new TypeError(`pgVectorStore: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`);
-		this.table = table;
-		this.dimensions = options.dimensions ?? DEFAULT_DIMENSIONS;
-		this.index = options.index ?? "hnsw";
-		this.ivfflatLists = options.ivfflatLists ?? DEFAULT_IVFFLAT_LISTS;
-		if (options.client) {
-			if (typeof options.client.query !== "function") throw new TypeError("pgVectorStore requires a 'client' option implementing { query(text, params) } — pass a pg.Pool or pg.Client.");
-			this.clientPromise = Promise.resolve(options.client);
-			return;
-		}
-		if (options.connectionString) {
-			this.clientPromise = buildPgClient(options.connectionString);
-			return;
-		}
-		throw new TypeError("pgVectorStore requires either a 'client' or a 'connectionString' option.");
-	}
-	/**
-	* Resolve the backing client, surfacing the lazy `pg` import's curated
-	* install string on the first call that needs it.
-	*/
-	client() {
-		return this.clientPromise;
-	}
-	/**
-	* Index `value` under `key` with its embedding `vector`. Upserts on the
-	* `key` primary key — re-indexing the same chunk overwrites its payload,
-	* embedding, and tags rather than appending a duplicate row. Optional
-	* `tags` ride a `text[]` column so {@link query} can restrict the
-	* candidate set with an array-overlap filter.
-	*
-	* The embedding is sent as a pgvector text literal (`$3`) cast to
-	* `::vector`, so the store needs no registered `pg` type parser. `tags`
-	* defaults to an empty array (never `NULL`) to keep the overlap filter's
-	* `&&` semantics simple.
-	*/
-	async upsert(key, value, vector, tags) {
-		await (await this.client()).query(`INSERT INTO ${this.table} (key, value, embedding, tags)
-       VALUES ($1, $2::jsonb, $3::vector, $4::text[])
-       ON CONFLICT (key) DO UPDATE
-         SET value = EXCLUDED.value,
-             embedding = EXCLUDED.embedding,
-             tags = EXCLUDED.tags`, [
-			key,
-			JSON.stringify(value),
-			vectorLiteral(vector),
-			tags ?? []
-		]);
-	}
-	/**
-	* Return the cosine-nearest rows to `vector`, mapped to the contract's
-	* `{ key, value, score }` shape. The SQL:
-	*
-	* - computes `embedding <=> $1::vector` (cosine **distance**) once, aliased
-	*   `distance`, and `ORDER BY` it ascending (nearest first);
-	* - applies the `threshold` floor as `distance <= 1 - threshold`
-	*   (similarity `>=` threshold), so the default `0.5` floor maps to a
-	*   `<= 0.5` distance bound — the filter runs in SQL, not in JS, so a
-	*   below-floor row never crosses the wire;
-	* - when `tags` are given, restricts to rows whose `tags` array overlaps
-	*   the requested set via `tags && $tags::text[]` (one-of semantics,
-	*   matching the cache store);
-	* - caps the result at `topK` with `LIMIT`.
-	*
-	* The returned `score` is `1 - distance`, clamped to `[0, 1]`, so callers
-	* see the same cosine-similarity scale the cache store emits.
-	*/
-	async query(vector, options) {
-		const client = await this.client();
-		const params = [vectorLiteral(vector), options.topK];
-		const conditions = [];
-		if (options.threshold !== void 0) {
-			params.push(1 - options.threshold);
-			conditions.push(`(embedding <=> $1::vector) <= $${params.length}`);
-		}
-		if (options.tags !== void 0 && options.tags.length > 0) {
-			params.push(options.tags);
-			conditions.push(`tags && $${params.length}::text[]`);
-		}
-		const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-		const { rows } = await client.query(`SELECT key, value, (embedding <=> $1::vector) AS distance
-       FROM ${this.table}
-       ${where}
-       ORDER BY embedding <=> $1::vector
-       LIMIT $2`, params);
-		return rows.map((row) => ({
-			key: row.key,
-			value: parseValue(row.value),
-			score: distanceToScore(row.distance)
-		}));
-	}
-	/**
-	* Drop every entry written under `namespace`. The RAG pipeline keys
-	* chunks as `<namespace>.<sourceId>.<chunkIndex>`, so a row belongs to
-	* the namespace when its `key` equals it OR begins with `<namespace>.`
-	* — deleting `ai.rag.docs` must not also catch `ai.rag.docs2`. The `_`
-	* and `%` LIKE wildcards in the namespace are escaped so a namespace
-	* that happens to contain them is matched literally.
-	*/
-	async removeNamespace(namespace) {
-		const client = await this.client();
-		const escaped = namespace.replace(/\\/g, "\\\\").replace(/_/g, "\\_").replace(/%/g, "\\%");
-		await client.query(`DELETE FROM ${this.table}
-       WHERE key = $1 OR key LIKE $2 ESCAPE '\\'`, [namespace, `${escaped}.%`]);
-	}
-	/**
-	* Return the reference migration DDL for this store's backing table,
-	* interpolating the configured table name, embedding width, and ANN
-	* index strategy. The dev runs it once through their migration tool —
-	* the framework never auto-migrates.
-	*
-	* The emitted statements:
-	* 1. `CREATE EXTENSION IF NOT EXISTS vector;` — enables pgvector (needs
-	*    a superuser or a role with `CREATE` on the database the first time).
-	* 2. `CREATE TABLE IF NOT EXISTS <table> (key TEXT PRIMARY KEY, value
-	*    JSONB NOT NULL, embedding vector(<dimensions>) NOT NULL, tags
-	*    text[] NOT NULL DEFAULT '{}');`
-	* 3. A GIN index on `tags` so the array-overlap filter stays sargable.
-	* 4. The chosen ANN index over `embedding` using `vector_cosine_ops`:
-	*    - `"hnsw"` → `USING hnsw (embedding vector_cosine_ops)`;
-	*    - `"ivfflat"` → `USING ivfflat (embedding vector_cosine_ops)
-	*      WITH (lists = <ivfflatLists>)`;
-	*    - `"none"` → emitted as a comment (exact scan, no ANN index).
-	*
-	* @example
-	* const store = pgVectorStore({ client: pool, dimensions: 1536 });
-	* await pool.query(store.ensureSchema());
-	*/
-	schema() {
-		const lines = [
-			`CREATE EXTENSION IF NOT EXISTS vector;`,
-			`CREATE TABLE IF NOT EXISTS ${this.table} (`,
-			`  key        TEXT PRIMARY KEY,`,
-			`  value      JSONB NOT NULL,`,
-			`  embedding  vector(${this.dimensions}) NOT NULL,`,
-			`  tags       TEXT[] NOT NULL DEFAULT '{}'`,
-			`);`,
-			`CREATE INDEX IF NOT EXISTS idx_${this.table}_tags`,
-			`  ON ${this.table} USING gin (tags);`
-		];
-		if (this.index === "hnsw") lines.push(`CREATE INDEX IF NOT EXISTS idx_${this.table}_embedding`, `  ON ${this.table} USING hnsw (embedding vector_cosine_ops);`);
-		else if (this.index === "ivfflat") lines.push(`CREATE INDEX IF NOT EXISTS idx_${this.table}_embedding`, `  ON ${this.table} USING ivfflat (embedding vector_cosine_ops)`, `  WITH (lists = ${this.ivfflatLists});`);
-		else lines.push(`-- No ANN index requested (index: "none"): cosine queries fall back`, `-- to an exact sequential scan, which is correct but linear in rows.`);
-		return lines.join("\n");
-	}
-	/**
-	* Alias for {@link PgVectorStore.schema} — reads more naturally in a
-	* migration script (`await pool.query(store.ensureSchema())`). Returns
-	* the identical DDL string; it does NOT execute anything against the
-	* database (the store never auto-migrates).
-	*/
-	ensureSchema() {
-		return this.schema();
-	}
-};
-/**
-* Create a Postgres + pgvector-backed {@link VectorStore} for the RAG
-* pipeline. Either pass a live `pg.Pool` / `pg.Client` (`{ client }`) —
-* `@warlock.js/ai` never imports `pg` in that case — or a
-* `{ connectionString }` and let the store lazily `import("pg")` to build
-* its own pool. When `pg` is not installed, a curated install string
-* surfaces on first use, never at import.
-*
-* Run {@link PgVectorStoreInstance.ensureSchema} through your migration
-* tool once before use (it enables the `vector` extension, creates the
-* table, and builds the tag + ANN indexes); the store never auto-migrates.
-*
-* Index and query MUST use the same embedding model — the `vector(N)`
-* column width is fixed at table-creation time from `dimensions`.
-*
-* @example
-* import { Pool } from "pg";
-* import { ai } from "@warlock.js/ai";
-*
-* const pool = new Pool({ connectionString: process.env.DATABASE_URL });
-* const store = ai.rag.pgVectorStore({ client: pool, dimensions: 1536 });
-*
-* // Once, via your migration tooling:
-* // await pool.query(store.ensureSchema());
-*
-* const kb = ai.rag({
-*   name: "docs",
-*   embedder: openai.embedder({ name: "text-embedding-3-small" }),
-*   store,
-* });
-*
-* @example
-* // Let the store build its own pool from a connection string:
-* const store = ai.rag.pgVectorStore({
-*   connectionString: process.env.DATABASE_URL,
-*   index: "ivfflat",
-*   ivfflatLists: 200,
-* });
-*/
-function pgVectorStore(options) {
-	return new PgVectorStore(options);
-}
-
-//#endregion
-export { pgVectorStore, vectorLiteral };
-//# sourceMappingURL=pg-vector-store.mjs.map