retriv 0.0.1

package/dist/db/pgvector.mjs

@@ -0,0 +1,80 @@
+import { resolveEmbedding } from "../embeddings/resolve.mjs";
+import pg from "pg";
+async function pgvector(config) {
+	const { url, table = "vectors", metric = "cosine" } = config;
+	if (!url) throw new Error("[pgvector] url is required");
+	if (!config.embeddings) throw new Error("[pgvector] embeddings is required");
+	const { embedder, dimensions } = await resolveEmbedding(config.embeddings);
+	const pool = new pg.Pool({ connectionString: url });
+	await pool.query("CREATE EXTENSION IF NOT EXISTS vector");
+	await pool.query(`
+    CREATE TABLE IF NOT EXISTS ${table} (
+      id TEXT PRIMARY KEY,
+      content TEXT,
+      metadata JSONB,
+      embedding vector(${dimensions})
+    )
+  `);
+	const indexName = `${table}_embedding_idx`;
+	const opClass = metric === "cosine" ? "vector_cosine_ops" : metric === "euclidean" ? "vector_l2_ops" : "vector_ip_ops";
+	await pool.query(`
+    CREATE INDEX IF NOT EXISTS ${indexName}
+    ON ${table} USING ivfflat (embedding ${opClass})
+    WITH (lists = 100)
+  `).catch(() => {});
+	const distanceOp = metric === "cosine" ? "<=>" : metric === "euclidean" ? "<->" : "<#>";
+	return {
+		async index(docs) {
+			if (docs.length === 0) return { count: 0 };
+			const embeddings = await embedder(docs.map((d) => d.content));
+			if (embeddings.length !== docs.length) throw new Error(`Embedding count mismatch: expected ${docs.length}, got ${embeddings.length}`);
+			for (let i = 0; i < docs.length; i++) {
+				const doc = docs[i];
+				const vectorStr = `[${embeddings[i].join(",")}]`;
+				await pool.query(`INSERT INTO ${table} (id, content, metadata, embedding)
+           VALUES ($1, $2, $3, $4)
+           ON CONFLICT (id) DO UPDATE SET
+             content = EXCLUDED.content,
+             metadata = EXCLUDED.metadata,
+             embedding = EXCLUDED.embedding`, [
+					doc.id,
+					doc.content,
+					doc.metadata || null,
+					vectorStr
+				]);
+			}
+			return { count: docs.length };
+		},
+		async search(query, options = {}) {
+			const { limit = 10, returnContent = false, returnMetadata = true } = options;
+			const [embedding] = await embedder([query]);
+			if (!embedding) throw new Error("Failed to generate query embedding");
+			const vectorStr = `[${embedding.join(",")}]`;
+			return (await pool.query(`SELECT id, content, metadata, embedding ${distanceOp} $1::vector as distance
+         FROM ${table}
+         ORDER BY embedding ${distanceOp} $1::vector
+         LIMIT $2`, [vectorStr, limit])).rows.map((row) => {
+				const score = metric === "inner_product" ? Math.max(0, Math.min(1, (row.distance + 1) / 2)) : Math.max(0, 1 - row.distance);
+				const searchResult = {
+					id: row.id,
+					score
+				};
+				if (returnContent && row.content) searchResult.content = row.content;
+				if (returnMetadata && row.metadata) searchResult.metadata = row.metadata;
+				return searchResult;
+			});
+		},
+		async remove(ids) {
+			await pool.query(`DELETE FROM ${table} WHERE id = ANY($1)`, [ids]);
+			return { count: ids.length };
+		},
+		async clear() {
+			await pool.query(`DELETE FROM ${table}`);
+		},
+		async close() {
+			await pool.end();
+		}
+	};
+}
+var pgvector_default = pgvector;
+export { pgvector_default as default, pgvector };

package/dist/db/sqlite-fts.d.mts

@@ -0,0 +1,23 @@
+import { BaseDriverConfig, SearchProvider } from "../types.mjs";
+
+//#region src/db/sqlite-fts.d.ts
+interface SqliteFtsConfig extends BaseDriverConfig {
+  /** Path to SQLite database file. Use ':memory:' for in-memory. */
+  path?: string;
+}
+/**
+ * Create a SQLite FTS5 full-text search provider
+ * Uses the built-in FTS5 extension for fast BM25-based search
+ *
+ * @example
+ * ```ts
+ * import { sqliteFts } from 'retriv/db/sqlite-fts'
+ *
+ * const db = await sqliteFts({
+ *   path: 'search.db',
+ * })
+ * ```
+ */
+declare function sqliteFts(config?: SqliteFtsConfig): Promise<SearchProvider>;
+//#endregion
+export { SqliteFtsConfig, sqliteFts as default, sqliteFts };

package/dist/db/sqlite-fts.mjs

@@ -0,0 +1,68 @@
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import Database from "better-sqlite3";
+async function sqliteFts(config = {}) {
+	const dbPath = config.path || ":memory:";
+	if (dbPath !== ":memory:") mkdirSync(dirname(dbPath), { recursive: true });
+	const db = new Database(dbPath);
+	db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS documents_fts USING fts5(
+      id,
+      content,
+      metadata,
+      tokenize='porter unicode61'
+    )
+  `);
+	return {
+		async index(docs) {
+			const insert = db.prepare(`
+        INSERT OR REPLACE INTO documents_fts (id, content, metadata)
+        VALUES (?, ?, ?)
+      `);
+			db.transaction((documents) => {
+				for (const doc of documents) insert.run(doc.id, doc.content, doc.metadata ? JSON.stringify(doc.metadata) : null);
+			})(docs);
+			return { count: docs.length };
+		},
+		async search(query, options = {}) {
+			const { limit = 10, returnContent = false, returnMetadata = true } = options;
+			const sanitized = query.replace(/[?"():^*-]/g, " ").replace(/\s+/g, " ").trim();
+			if (!sanitized) return [];
+			return db.prepare(`
+        SELECT
+          id,
+          ${returnContent ? "content," : ""}
+          ${returnMetadata ? "metadata," : ""}
+          bm25(documents_fts) as score
+        FROM documents_fts
+        WHERE documents_fts MATCH ?
+        ORDER BY bm25(documents_fts)
+        LIMIT ?
+      `).all(sanitized, limit).map((row) => {
+				const normalizedScore = Math.max(0, Math.min(1, 1 / (1 + Math.abs(row.score))));
+				const result = {
+					id: row.id,
+					score: normalizedScore
+				};
+				if (returnContent && row.content) result.content = row.content;
+				if (returnMetadata && row.metadata) result.metadata = JSON.parse(row.metadata);
+				return result;
+			});
+		},
+		async remove(ids) {
+			const del = db.prepare("DELETE FROM documents_fts WHERE id = ?");
+			db.transaction((docIds) => {
+				for (const id of docIds) del.run(id);
+			})(ids);
+			return { count: ids.length };
+		},
+		async clear() {
+			db.exec("DELETE FROM documents_fts");
+		},
+		async close() {
+			db.close();
+		}
+	};
+}
+var sqlite_fts_default = sqliteFts;
+export { sqlite_fts_default as default, sqliteFts };

package/dist/db/sqlite-vec.d.mts

@@ -0,0 +1,27 @@
+import { BaseDriverConfig, EmbeddingConfig, SearchProvider } from "../types.mjs";
+
+//#region src/db/sqlite-vec.d.ts
+interface SqliteVecConfig extends BaseDriverConfig {
+  /** Path to SQLite database file. Use ':memory:' for in-memory. */
+  path?: string;
+  /** Embedding provider from retriv/embeddings/ */
+  embeddings: EmbeddingConfig;
+}
+/**
+ * Create a sqlite-vec vector search provider
+ * Requires Node.js >= 22.5
+ *
+ * @example
+ * ```ts
+ * import { sqliteVec } from 'retriv/db/sqlite-vec'
+ * import { openai } from 'retriv/embeddings/openai'
+ *
+ * const db = await sqliteVec({
+ *   path: 'vectors.db',
+ *   embeddings: openai({ model: 'text-embedding-3-small' }),
+ * })
+ * ```
+ */
+declare function sqliteVec(config: SqliteVecConfig): Promise<SearchProvider>;
+//#endregion
+export { SqliteVecConfig, sqliteVec as default, sqliteVec };

package/dist/db/sqlite-vec.mjs

@@ -0,0 +1,108 @@
+import { resolveEmbedding } from "../embeddings/resolve.mjs";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import * as sqliteVecExt from "sqlite-vec";
+async function sqliteVec(config) {
+	const dbPath = config.path || ":memory:";
+	if (!config.embeddings) throw new Error("[sqlite-vec] embeddings is required");
+	const { embedder, dimensions } = await resolveEmbedding(config.embeddings);
+	const nodeSqlite = globalThis.process?.getBuiltinModule?.("node:sqlite");
+	if (!nodeSqlite) throw new Error("node:sqlite not available. Requires Node.js >= 22.5");
+	if (dbPath !== ":memory:") mkdirSync(dirname(dbPath), { recursive: true });
+	const db = new nodeSqlite.DatabaseSync(dbPath, {
+		allowExtension: true,
+		open: true,
+		readOnly: false
+	});
+	sqliteVecExt.load(db);
+	db.exec("PRAGMA foreign_keys = ON");
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS vector_metadata (
+      id TEXT PRIMARY KEY,
+      content TEXT,
+      metadata TEXT
+    )
+  `);
+	db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS vectors
+    USING vec0(embedding float[${dimensions}])
+  `);
+	return {
+		async index(docs) {
+			if (docs.length === 0) return { count: 0 };
+			const embeddings = await embedder(docs.map((d) => d.content));
+			if (embeddings.length !== docs.length) throw new Error(`Embedding count mismatch: expected ${docs.length}, got ${embeddings.length}`);
+			db.prepare("BEGIN").run();
+			try {
+				for (let i = 0; i < docs.length; i++) {
+					const doc = docs[i];
+					const vector = embeddings[i];
+					if (vector.length !== dimensions) throw new Error(`Vector dimension mismatch: expected ${dimensions}, got ${vector.length}`);
+					const embedding = new Float32Array(vector);
+					const existing = db.prepare("SELECT rowid FROM vector_metadata WHERE id = ?").get(doc.id);
+					if (existing) {
+						db.prepare("UPDATE vectors SET embedding = ? WHERE rowid = ?").run(embedding, existing.rowid);
+						db.prepare("UPDATE vector_metadata SET content = ?, metadata = ? WHERE rowid = ?").run(doc.content, doc.metadata ? JSON.stringify(doc.metadata) : null, existing.rowid);
+					} else {
+						const rowid = db.prepare("INSERT INTO vectors (embedding) VALUES (?)").run(embedding).lastInsertRowid;
+						db.prepare("INSERT INTO vector_metadata (rowid, id, content, metadata) VALUES (?, ?, ?, ?)").run(rowid, doc.id, doc.content, doc.metadata ? JSON.stringify(doc.metadata) : null);
+					}
+				}
+				db.prepare("COMMIT").run();
+				return { count: docs.length };
+			} catch (error) {
+				db.prepare("ROLLBACK").run();
+				throw error;
+			}
+		},
+		async search(query, options = {}) {
+			const { limit = 10, returnContent = false, returnMetadata = true } = options;
+			const [embedding] = await embedder([query]);
+			if (!embedding) throw new Error("Failed to generate query embedding");
+			const queryEmbedding = new Float32Array(embedding);
+			return db.prepare(`
+        SELECT rowid, distance
+        FROM vectors
+        WHERE embedding MATCH ?
+        ORDER BY distance
+        LIMIT ?
+      `).all(queryEmbedding, limit).map((row) => {
+				const meta = db.prepare("SELECT id, content, metadata FROM vector_metadata WHERE rowid = ?").get(row.rowid);
+				if (!meta) return null;
+				const result = {
+					id: meta.id,
+					score: 1 / (1 + row.distance)
+				};
+				if (returnContent && meta.content) result.content = meta.content;
+				if (returnMetadata && meta.metadata) result.metadata = JSON.parse(meta.metadata);
+				return result;
+			}).filter(Boolean);
+		},
+		async remove(ids) {
+			db.prepare("BEGIN").run();
+			try {
+				for (const id of ids) {
+					const meta = db.prepare("SELECT rowid FROM vector_metadata WHERE id = ?").get(id);
+					if (meta) {
+						db.prepare("DELETE FROM vectors WHERE rowid = ?").run(meta.rowid);
+						db.prepare("DELETE FROM vector_metadata WHERE rowid = ?").run(meta.rowid);
+					}
+				}
+				db.prepare("COMMIT").run();
+				return { count: ids.length };
+			} catch (error) {
+				db.prepare("ROLLBACK").run();
+				throw error;
+			}
+		},
+		async clear() {
+			db.exec("DELETE FROM vectors");
+			db.exec("DELETE FROM vector_metadata");
+		},
+		async close() {
+			db.close?.();
+		}
+	};
+}
+var sqlite_vec_default = sqliteVec;
+export { sqlite_vec_default as default, sqliteVec };

package/dist/db/upstash.d.mts

@@ -0,0 +1,28 @@
+import { BaseDriverConfig, SearchProvider } from "../types.mjs";
+
+//#region src/db/upstash.d.ts
+interface UpstashConfig extends BaseDriverConfig {
+  /** Upstash Vector REST URL */
+  url: string;
+  /** Upstash Vector REST token */
+  token: string;
+  /** Optional namespace for vectors */
+  namespace?: string;
+}
+/**
+ * Create an Upstash Vector search provider
+ * Text-native: Uses Upstash's server-side embeddings (no local embedding needed)
+ *
+ * @example
+ * ```ts
+ * import { upstash } from 'retriv/db/upstash'
+ *
+ * const db = await upstash({
+ *   url: process.env.UPSTASH_VECTOR_URL,
+ *   token: process.env.UPSTASH_VECTOR_TOKEN,
+ * })
+ * ```
+ */
+declare function upstash(config: UpstashConfig): Promise<SearchProvider>;
+//#endregion
+export { UpstashConfig, upstash as default, upstash };

package/dist/db/upstash.mjs

@@ -0,0 +1,56 @@
+import { Index } from "@upstash/vector";
+async function upstash(config) {
+	const { url, token, namespace } = config;
+	if (!url) throw new Error("[upstash] url is required");
+	if (!token) throw new Error("[upstash] token is required");
+	const index = new Index({
+		url,
+		token
+	});
+	const ns = namespace || "chunks";
+	return {
+		async index(docs) {
+			if (docs.length === 0) return { count: 0 };
+			const upstashVectors = docs.map((doc) => ({
+				id: doc.id,
+				data: doc.content,
+				metadata: {
+					...doc.metadata,
+					_content: doc.content
+				}
+			}));
+			await index.upsert(upstashVectors, { namespace: ns });
+			return { count: docs.length };
+		},
+		async search(query, options = {}) {
+			const { limit = 10, returnContent = false, returnMetadata = true } = options;
+			return (await index.query({
+				data: query,
+				topK: limit,
+				includeMetadata: true,
+				includeData: true
+			}, { namespace: ns }) || []).map((m) => {
+				const result = {
+					id: m.id,
+					score: Math.max(0, Math.min(1, m.score))
+				};
+				if (returnContent && m.metadata?._content) result.content = m.metadata._content;
+				if (returnMetadata && m.metadata) {
+					const { _content, ...rest } = m.metadata;
+					if (Object.keys(rest).length > 0) result.metadata = rest;
+				}
+				return result;
+			});
+		},
+		async remove(ids) {
+			await index.delete(ids, { namespace: ns });
+			return { count: ids.length };
+		},
+		async clear() {
+			await index.reset({ namespace: ns });
+		},
+		async close() {}
+	};
+}
+var upstash_default = upstash;
+export { upstash_default as default, upstash };

package/dist/embeddings/cohere.d.mts

@@ -0,0 +1,28 @@
+import { EmbeddingConfig } from "../types.mjs";
+
+//#region src/embeddings/cohere.d.ts
+interface CohereEmbeddingOptions {
+  /** Model name (default: embed-english-v3.0) */
+  model?: string;
+  /** API key (falls back to COHERE_API_KEY env) */
+  apiKey?: string;
+  /** Base URL override */
+  baseUrl?: string;
+}
+/**
+ * Cohere embedding provider
+ *
+ * @example
+ * ```ts
+ * import { cohere } from 'retriv/embeddings/cohere'
+ * import { sqliteVec } from 'retriv/db/sqlite-vec'
+ *
+ * const db = await sqliteVec({
+ *   path: 'vectors.db',
+ *   embeddings: cohere({ model: 'embed-english-v3.0' }),
+ * })
+ * ```
+ */
+declare function cohere(options?: CohereEmbeddingOptions): EmbeddingConfig;
+//#endregion
+export { CohereEmbeddingOptions, cohere };

package/dist/embeddings/cohere.mjs

@@ -0,0 +1,39 @@
+import { embed, embedMany } from "ai";
+import { createCohere } from "@ai-sdk/cohere";
+function cohere(options = {}) {
+	const { model = "embed-english-v3.0", apiKey, baseUrl } = options;
+	let cached = null;
+	return { async resolve() {
+		if (cached) return cached;
+		const embeddingModel = createCohere({
+			apiKey,
+			baseURL: baseUrl
+		}).textEmbeddingModel(model);
+		const { embedding: testEmbedding } = await embed({
+			model: embeddingModel,
+			value: "test"
+		});
+		const dimensions = testEmbedding.length;
+		const embedder = async (texts) => {
+			if (texts.length === 0) return [];
+			if (texts.length === 1) {
+				const { embedding } = await embed({
+					model: embeddingModel,
+					value: texts[0]
+				});
+				return [embedding];
+			}
+			const { embeddings } = await embedMany({
+				model: embeddingModel,
+				values: texts
+			});
+			return embeddings;
+		};
+		cached = {
+			embedder,
+			dimensions
+		};
+		return cached;
+	} };
+}
+export { cohere };

package/dist/embeddings/google.d.mts

@@ -0,0 +1,28 @@
+import { EmbeddingConfig } from "../types.mjs";
+
+//#region src/embeddings/google.d.ts
+interface GoogleEmbeddingOptions {
+  /** Model name (default: text-embedding-004) */
+  model?: string;
+  /** API key (falls back to GOOGLE_API_KEY env) */
+  apiKey?: string;
+  /** Base URL override */
+  baseUrl?: string;
+}
+/**
+ * Google AI embedding provider
+ *
+ * @example
+ * ```ts
+ * import { google } from 'retriv/embeddings/google'
+ * import { sqliteVec } from 'retriv/db/sqlite-vec'
+ *
+ * const db = await sqliteVec({
+ *   path: 'vectors.db',
+ *   embeddings: google({ model: 'text-embedding-004' }),
+ * })
+ * ```
+ */
+declare function google(options?: GoogleEmbeddingOptions): EmbeddingConfig;
+//#endregion
+export { GoogleEmbeddingOptions, google };

package/dist/embeddings/google.mjs

@@ -0,0 +1,39 @@
+import { embed, embedMany } from "ai";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+function google(options = {}) {
+	const { model = "text-embedding-004", apiKey, baseUrl } = options;
+	let cached = null;
+	return { async resolve() {
+		if (cached) return cached;
+		const embeddingModel = createGoogleGenerativeAI({
+			apiKey,
+			baseURL: baseUrl
+		}).textEmbeddingModel(model);
+		const { embedding: testEmbedding } = await embed({
+			model: embeddingModel,
+			value: "test"
+		});
+		const dimensions = testEmbedding.length;
+		const embedder = async (texts) => {
+			if (texts.length === 0) return [];
+			if (texts.length === 1) {
+				const { embedding } = await embed({
+					model: embeddingModel,
+					value: texts[0]
+				});
+				return [embedding];
+			}
+			const { embeddings } = await embedMany({
+				model: embeddingModel,
+				values: texts
+			});
+			return embeddings;
+		};
+		cached = {
+			embedder,
+			dimensions
+		};
+		return cached;
+	} };
+}
+export { google };

package/dist/embeddings/mistral.d.mts

@@ -0,0 +1,28 @@
+import { EmbeddingConfig } from "../types.mjs";
+
+//#region src/embeddings/mistral.d.ts
+interface MistralEmbeddingOptions {
+  /** Model name (default: mistral-embed) */
+  model?: string;
+  /** API key (falls back to MISTRAL_API_KEY env) */
+  apiKey?: string;
+  /** Base URL override */
+  baseUrl?: string;
+}
+/**
+ * Mistral AI embedding provider
+ *
+ * @example
+ * ```ts
+ * import { mistral } from 'retriv/embeddings/mistral'
+ * import { sqliteVec } from 'retriv/db/sqlite-vec'
+ *
+ * const db = await sqliteVec({
+ *   path: 'vectors.db',
+ *   embeddings: mistral({ model: 'mistral-embed' }),
+ * })
+ * ```
+ */
+declare function mistral(options?: MistralEmbeddingOptions): EmbeddingConfig;
+//#endregion
+export { MistralEmbeddingOptions, mistral };

package/dist/embeddings/mistral.mjs

@@ -0,0 +1,39 @@
+import { embed, embedMany } from "ai";
+import { createMistral } from "@ai-sdk/mistral";
+function mistral(options = {}) {
+	const { model = "mistral-embed", apiKey, baseUrl } = options;
+	let cached = null;
+	return { async resolve() {
+		if (cached) return cached;
+		const embeddingModel = createMistral({
+			apiKey,
+			baseURL: baseUrl
+		}).textEmbeddingModel(model);
+		const { embedding: testEmbedding } = await embed({
+			model: embeddingModel,
+			value: "test"
+		});
+		const dimensions = testEmbedding.length;
+		const embedder = async (texts) => {
+			if (texts.length === 0) return [];
+			if (texts.length === 1) {
+				const { embedding } = await embed({
+					model: embeddingModel,
+					value: texts[0]
+				});
+				return [embedding];
+			}
+			const { embeddings } = await embedMany({
+				model: embeddingModel,
+				values: texts
+			});
+			return embeddings;
+		};
+		cached = {
+			embedder,
+			dimensions
+		};
+		return cached;
+	} };
+}
+export { mistral };

package/dist/embeddings/ollama.d.mts

@@ -0,0 +1,26 @@
+import { EmbeddingConfig } from "../types.mjs";
+
+//#region src/embeddings/ollama.d.ts
+interface OllamaEmbeddingOptions {
+  /** Model name (default: nomic-embed-text) */
+  model?: string;
+  /** Base URL (default: http://localhost:11434) */
+  baseUrl?: string;
+}
+/**
+ * Ollama embedding provider (local)
+ *
+ * @example
+ * ```ts
+ * import { ollama } from 'retriv/embeddings/ollama'
+ * import { sqliteVec } from 'retriv/db/sqlite-vec'
+ *
+ * const db = await sqliteVec({
+ *   path: 'vectors.db',
+ *   embeddings: ollama({ model: 'nomic-embed-text' }),
+ * })
+ * ```
+ */
+declare function ollama(options?: OllamaEmbeddingOptions): EmbeddingConfig;
+//#endregion
+export { OllamaEmbeddingOptions, ollama };

package/dist/embeddings/ollama.mjs

@@ -0,0 +1,37 @@
+import { embed, embedMany } from "ai";
+import { createOllama } from "ollama-ai-provider-v2";
+function ollama(options = {}) {
+	const { model = "nomic-embed-text", baseUrl } = options;
+	let cached = null;
+	return { async resolve() {
+		if (cached) return cached;
+		const ollamaBaseUrl = baseUrl || process.env.OLLAMA_BASE_URL || "http://localhost:11434";
+		const embeddingModel = createOllama({ baseURL: ollamaBaseUrl.endsWith("/api") ? ollamaBaseUrl : `${ollamaBaseUrl}/api` }).textEmbeddingModel(model);
+		const { embedding: testEmbedding } = await embed({
+			model: embeddingModel,
+			value: "test"
+		});
+		const dimensions = testEmbedding.length;
+		const embedder = async (texts) => {
+			if (texts.length === 0) return [];
+			if (texts.length === 1) {
+				const { embedding } = await embed({
+					model: embeddingModel,
+					value: texts[0]
+				});
+				return [embedding];
+			}
+			const { embeddings } = await embedMany({
+				model: embeddingModel,
+				values: texts
+			});
+			return embeddings;
+		};
+		cached = {
+			embedder,
+			dimensions
+		};
+		return cached;
+	} };
+}
+export { ollama };