@alexkroman1/aai 0.9.2 → 0.10.0

package/dist/session.d.ts

@@ -1,43 +1,50 @@
-/**
- * S2S session — relays audio between the client and AssemblyAI's
- * Speech-to-Speech API, intercepting only tool calls for local execution.
- */
+/** S2S session — relays audio between client and AssemblyAI S2S API. */
 import type { AgentConfig, ToolSchema } from "./_internal-types.ts";
+import { type SessionPersistence } from "./_session-persist.ts";
+import type { HookInvoker } from "./middleware.ts";
 import type { ClientSink } from "./protocol.ts";
 import type { Logger, S2SConfig } from "./runtime.ts";
 import { type CreateS2sWebSocket, connectS2s } from "./s2s.ts";
-import { type StepInfo } from "./types.ts";
 import type { ExecuteTool } from "./worker-entry.ts";
-/** A voice session managing the S2S connection for one client. */
+export type { S2sSessionCtx } from "./_session-ctx.ts";
+export type { PersistedSession, SessionPersistence } from "./_session-persist.ts";
+export { persistKey } from "./_session-persist.ts";
+export type { HookInvoker, ToolInterceptResult } from "./middleware.ts";
+export { buildSystemPrompt } from "./system-prompt.ts";
+/**
+ * A voice session managing the Speech-to-Speech connection for one client.
+ *
+ * Created by {@link createS2sSession}. Each session owns a single S2S WebSocket
+ * connection and relays audio between the browser client and AssemblyAI.
+ *
+ * @internal Exported for use by `ws-handler.ts`, `server.ts`, and `direct-executor.ts`.
+ */
 export type Session = {
+    /** Open the S2S connection and fire the `onConnect` hook. */
     start(): Promise<void>;
+    /** Gracefully shut down: wait for in-flight turns, close the S2S socket, fire `onDisconnect`. */
     stop(): Promise<void>;
+    /** Forward raw PCM audio from the client microphone to the S2S connection. */
     onAudio(data: Uint8Array): void;
+    /** Called when the client has finished setting up its audio pipeline. For S2S sessions this is a no-op since the greeting comes automatically. */
     onAudioReady(): void;
+    /** Handle a client-initiated cancellation (barge-in). Sends a `cancelled` event. */
     onCancel(): void;
+    /** Reset the session: clear conversation history, bump generation counters, reconnect S2S. */
     onReset(): void;
+    /**
+     * Inject conversation history from the client (e.g. on reconnect).
+     * @param incoming - Messages with `{role, content}` fields.
+     */
     onHistory(incoming: readonly {
         role: "user" | "assistant";
-        text: string;
+        content: string;
     }[]): void;
+    /** Returns a promise that resolves when the current in-flight turn completes, or resolves immediately if no turn is active. */
     waitForTurn(): Promise<void>;
 };
-/** Generic interface for invoking agent lifecycle hooks. */
-export type HookInvoker = {
-    onConnect(sessionId: string, timeoutMs?: number): Promise<void>;
-    onDisconnect(sessionId: string, timeoutMs?: number): Promise<void>;
-    onTurn(sessionId: string, text: string, timeoutMs?: number): Promise<void>;
-    onError(sessionId: string, error: {
-        message: string;
-    }, timeoutMs?: number): Promise<void>;
-    onStep(sessionId: string, step: StepInfo, timeoutMs?: number): Promise<void>;
-    resolveTurnConfig(sessionId: string, timeoutMs?: number): Promise<{
-        maxSteps?: number;
-        activeTools?: string[];
-    } | null>;
-};
 /** Configuration options for creating a new session. */
-export type SessionOptions = {
+export type S2sSessionOptions = {
     id: string;
     agent: string;
     client: ClientSink;
@@ -51,13 +58,33 @@ export type SessionOptions = {
     hookInvoker?: HookInvoker;
     skipGreeting?: boolean;
     logger?: Logger;
+    /** Maximum number of conversation messages to retain. Older messages are
+     *  dropped (sliding window) to bound memory in long-running sessions.
+     *  Defaults to 200. Set to 0 or Infinity to disable trimming. */
+    maxHistory?: number;
+    /** Persistence configuration for auto-saving/restoring session data. */
+    persistence?: SessionPersistence;
+    /** Old session ID to resume from. Loads persisted state/messages from KV
+     *  and attempts S2S session resume. */
+    resumeFrom?: string;
 };
+/** @internal Not part of the public API. Exposed for testing only. */
 export declare const _internals: {
     connectS2s: typeof connectS2s;
 };
-/** Create an S2S-backed session with the same interface as the STT+LLM+TTS session. */
-export declare function createS2sSession(opts: SessionOptions): Session;
-export declare function buildSystemPrompt(config: AgentConfig, opts: {
-    hasTools: boolean;
-    voice?: boolean;
-}): string;
+/**
+ * Create a Speech-to-Speech backed session implementing the {@link Session} interface.
+ *
+ * Connects to AssemblyAI's S2S WebSocket, configures the system prompt and tools,
+ * and wires up event listeners for user transcripts, agent replies, tool calls,
+ * barge-ins, and session lifecycle. Manages reconnection on `onReset` via a
+ * `connectGeneration` guard that prevents stale connection attempts from overwriting
+ * newer ones during rapid resets. A `sessionAbort` AbortController is used to
+ * coordinate cleanup on `stop()`.
+ *
+ * @param opts - Session configuration. See {@link S2sSessionOptions} for all fields
+ *   including the agent config, tool schemas, API key, and optional hooks.
+ * @returns A {@link Session} with `start`, `stop`, `onAudio`, `onReset`, and other
+ *   lifecycle methods.
+ */
+export declare function createS2sSession(opts: S2sSessionOptions): Session;

package/dist/session.js

@@ -1,312 +1,2 @@
-import { DEFAULT_INSTRUCTIONS } from "./types.js";
-import { errorMessage } from "./_utils.js";
-import { HOOK_TIMEOUT_MS } from "./protocol.js";
-import { consoleLogger } from "./runtime.js";
-import { connectS2s, defaultCreateS2sWebSocket } from "./s2s.js";
-//#region session.ts
-const _internals = { connectS2s };
-/** Create an S2S-backed session with the same interface as the STT+LLM+TTS session. */
-function createS2sSession(opts) {
-	const { id, agent, client, toolSchemas, apiKey, s2sConfig, executeTool, createWebSocket = defaultCreateS2sWebSocket, hookInvoker, logger: log = consoleLogger } = opts;
-	const agentConfig = opts.skipGreeting ? {
-		...opts.agentConfig,
-		greeting: ""
-	} : opts.agentConfig;
-	const systemPrompt = buildSystemPrompt(agentConfig, {
-		hasTools: toolSchemas.length > 0 || (agentConfig.builtinTools?.length ?? 0) > 0,
-		voice: true
-	});
-	const s2sTools = toolSchemas.map((ts) => ({
-		type: "function",
-		name: ts.name,
-		description: ts.description,
-		parameters: ts.parameters
-	}));
-	let s2s = null;
-	const sessionAbort = new AbortController();
-	let toolCallCount = 0;
-	let turnPromise = null;
-	let conversationMessages = [];
-	let pendingTools = [];
-	async function resolveTurnConfig() {
-		if (!hookInvoker) return null;
-		return await hookInvoker.resolveTurnConfig(id, HOOK_TIMEOUT_MS);
-	}
-	function fireHook(name, fn) {
-		if (!hookInvoker) return;
-		try {
-			fn(hookInvoker).catch((err) => {
-				log.warn(`${name} hook failed`, { err: errorMessage(err) });
-			});
-		} catch (err) {
-			log.warn(`${name} hook failed`, { err: errorMessage(err) });
-		}
-	}
-	/** Check if a tool call should be refused due to turn config limits. Returns a result string to short-circuit, or null. */
-	function checkTurnLimits(turnConfig, name) {
-		const maxSteps = turnConfig?.maxSteps ?? agentConfig.maxSteps;
-		toolCallCount++;
-		if (maxSteps !== void 0 && toolCallCount > maxSteps) {
-			log.info("maxSteps exceeded, refusing tool call", {
-				toolCallCount,
-				maxSteps
-			});
-			return "Maximum tool steps reached. Please respond to the user now.";
-		}
-		if (turnConfig?.activeTools && !turnConfig.activeTools.includes(name)) {
-			log.info("Tool filtered by activeTools", { name });
-			return JSON.stringify({ error: `Tool "${name}" is not available at this step.` });
-		}
-		return null;
-	}
-	async function handleToolCall(detail) {
-		const { call_id, name, args: parsedArgs } = detail;
-		client.event({
-			type: "tool_call_start",
-			toolCallId: call_id,
-			toolName: name,
-			args: parsedArgs
-		});
-		let turnConfig;
-		try {
-			turnConfig = await resolveTurnConfig();
-		} catch (err) {
-			const msg = `resolveTurnConfig hook error: ${errorMessage(err)}`;
-			log.error(msg);
-			pendingTools.push({
-				call_id,
-				result: msg
-			});
-			client.event({
-				type: "tool_call_done",
-				toolCallId: call_id,
-				result: msg
-			});
-			return;
-		}
-		const refused = checkTurnLimits(turnConfig, name);
-		if (refused !== null) {
-			pendingTools.push({
-				call_id,
-				result: refused
-			});
-			client.event({
-				type: "tool_call_done",
-				toolCallId: call_id,
-				result: refused
-			});
-			return;
-		}
-		fireHook("onStep", (h) => h.onStep(id, {
-			stepNumber: toolCallCount - 1,
-			toolCalls: [{
-				toolName: name,
-				args: parsedArgs
-			}],
-			text: ""
-		}, HOOK_TIMEOUT_MS));
-		log.info("S2S tool call", {
-			tool: name,
-			call_id,
-			args: parsedArgs,
-			agent
-		});
-		let result;
-		try {
-			result = await executeTool(name, parsedArgs, id, conversationMessages);
-		} catch (err) {
-			const msg = errorMessage(err);
-			log.error("Tool execution failed", {
-				tool: name,
-				error: msg
-			});
-			result = JSON.stringify({ error: msg });
-		}
-		log.info("S2S tool result", {
-			tool: name,
-			call_id,
-			resultLength: result.length
-		});
-		pendingTools.push({
-			call_id,
-			result
-		});
-		client.event({
-			type: "tool_call_done",
-			toolCallId: call_id,
-			result
-		});
-	}
-	/** Wire all S2S events to the client sink, hooks, and session state. */
-	function setupListeners(handle) {
-		handle.on("ready", ({ session_id }) => {
-			log.info("S2S session ready", { session_id });
-		});
-		handle.on("session_expired", () => {
-			log.info("S2S session expired");
-			handle.close();
-		});
-		handle.on("speech_started", () => client.event({ type: "speech_started" }));
-		handle.on("speech_stopped", () => client.event({ type: "speech_stopped" }));
-		handle.on("user_transcript_delta", ({ text }) => {
-			client.event({
-				type: "transcript",
-				text,
-				isFinal: false
-			});
-		});
-		handle.on("user_transcript", ({ text }) => {
-			log.info("S2S user transcript", { text });
-			client.event({
-				type: "transcript",
-				text,
-				isFinal: true
-			});
-			client.event({
-				type: "turn",
-				text
-			});
-			conversationMessages.push({
-				role: "user",
-				content: text
-			});
-			fireHook("onTurn", (h) => h.onTurn(id, text, HOOK_TIMEOUT_MS));
-		});
-		handle.on("reply_started", () => {
-			toolCallCount = 0;
-		});
-		handle.on("audio", ({ audio }) => {
-			client.playAudioChunk(audio);
-		});
-		handle.on("agent_transcript_delta", ({ text }) => {
-			client.event({
-				type: "chat_delta",
-				text
-			});
-		});
-		handle.on("agent_transcript", ({ text }) => {
-			client.event({
-				type: "chat",
-				text
-			});
-			conversationMessages.push({
-				role: "assistant",
-				content: text
-			});
-		});
-		handle.on("tool_call", (detail) => {
-			const p = handleToolCall(detail).catch((err) => {
-				log.error("Tool call handler failed", { err: errorMessage(err) });
-			});
-			turnPromise = (turnPromise ?? Promise.resolve()).then(() => p);
-		});
-		handle.on("reply_done", ({ status }) => {
-			if (status === "interrupted") {
-				log.info("S2S reply interrupted (barge-in)");
-				pendingTools = [];
-				client.event({ type: "cancelled" });
-			} else if (pendingTools.length > 0) {
-				for (const tool of pendingTools) s2s?.sendToolResult(tool.call_id, tool.result);
-				pendingTools = [];
-			} else {
-				client.playAudioDone();
-				client.event({ type: "tts_done" });
-			}
-		});
-		handle.on("error", ({ code, message }) => {
-			log.error("S2S error", {
-				code,
-				message
-			});
-			client.event({
-				type: "error",
-				code: "internal",
-				message
-			});
-			handle.close();
-		});
-		handle.on("close", () => {
-			log.info("S2S closed");
-			s2s = null;
-		});
-	}
-	async function connectAndSetup() {
-		try {
-			const handle = await _internals.connectS2s({
-				apiKey,
-				config: s2sConfig,
-				createWebSocket,
-				logger: log
-			});
-			setupListeners(handle);
-			handle.updateSession({
-				system_prompt: systemPrompt,
-				tools: s2sTools,
-				...agentConfig.greeting ? { greeting: agentConfig.greeting } : {}
-			});
-			s2s = handle;
-		} catch (err) {
-			const msg = errorMessage(err);
-			log.error("S2S connect failed", { error: msg });
-			client.event({
-				type: "error",
-				code: "internal",
-				message: msg
-			});
-		}
-	}
-	return {
-		async start() {
-			fireHook("onConnect", (h) => h.onConnect(id, HOOK_TIMEOUT_MS));
-			await connectAndSetup();
-		},
-		async stop() {
-			if (sessionAbort.signal.aborted) return;
-			sessionAbort.abort();
-			if (turnPromise) await turnPromise;
-			s2s?.close();
-			fireHook("onDisconnect", (h) => h.onDisconnect(id, HOOK_TIMEOUT_MS));
-		},
-		onAudio(data) {
-			s2s?.sendAudio(data);
-		},
-		onAudioReady() {},
-		onCancel() {
-			client.event({ type: "cancelled" });
-		},
-		onReset() {
-			conversationMessages = [];
-			toolCallCount = 0;
-			turnPromise = null;
-			pendingTools = [];
-			s2s?.close();
-			client.event({ type: "reset" });
-			connectAndSetup().catch((err) => {
-				log.error("S2S reset reconnect failed", { error: errorMessage(err) });
-			});
-		},
-		onHistory(incoming) {
-			for (const msg of incoming) conversationMessages.push({
-				role: msg.role,
-				content: msg.text
-			});
-		},
-		waitForTurn() {
-			return turnPromise ?? Promise.resolve();
-		}
-	};
-}
-const VOICE_RULES = "\n\nCRITICAL OUTPUT RULES — you MUST follow these for EVERY response:\nYour response will be spoken aloud by a TTS system and displayed as plain text.\n- NEVER use markdown: no **, no *, no _, no #, no `, no [](), no ---\n- NEVER use bullet points (-, *, •) or numbered lists (1., 2.)\n- NEVER use code blocks or inline code\n- NEVER mention tools, search, APIs, or technical failures to the user. If a tool returns no results, just answer naturally without explaining why.\n- Write exactly as you would say it out loud to a friend\n- Use short conversational sentences. To list things, say \"First,\" \"Next,\" \"Finally,\"\n- Keep responses concise — 1 to 3 sentences max";
-function buildSystemPrompt(config, opts) {
-	const { hasTools } = opts;
-	const agentInstructions = config.instructions && config.instructions !== DEFAULT_INSTRUCTIONS ? `\n\nAgent-Specific Instructions:\n${config.instructions}` : "";
-	const toolPreamble = hasTools ? "\n\nWhen you decide to use a tool, ALWAYS say a brief natural phrase BEFORE the tool call (e.g. \"Let me look that up\" or \"One moment while I check\"). This fills silence while the tool executes. Keep preambles to one short sentence." : "";
-	return DEFAULT_INSTRUCTIONS + `\n\nToday's date is ${(/* @__PURE__ */ new Date()).toLocaleDateString("en-US", {
-		weekday: "long",
-		year: "numeric",
-		month: "long",
-		day: "numeric"
-	})}.` + agentInstructions + toolPreamble + (opts.voice ? VOICE_RULES : "");
-}
-//#endregion
-export { _internals, buildSystemPrompt, createS2sSession };
+import { i as persistKey, n as createS2sSession, r as buildSystemPrompt, t as _internals } from "./session-BkN9u0ni.js";
+export { _internals, buildSystemPrompt, createS2sSession, persistKey };

package/dist/sqlite-kv.d.ts

@@ -0,0 +1,34 @@
+/**
+ * SQLite-backed key-value storage for local development.
+ *
+ * Persists data across restarts using a local SQLite database file.
+ * Uses `node:sqlite` (built into Node 22+) — no native dependencies.
+ * Drop-in replacement for the in-memory KV store.
+ */
+import type { Kv } from "./kv.ts";
+/**
+ * Options for creating a SQLite-backed KV store.
+ */
+export type SqliteKvOptions = {
+    /** Path to the SQLite database file. Defaults to `.aai/local.db`. */
+    path?: string;
+};
+/**
+ * Create a SQLite-backed KV store for local development.
+ *
+ * Data persists to a local SQLite file (default: `.aai/local.db`).
+ * TTL expiration is enforced on reads and periodically cleaned up.
+ *
+ * @param options - Optional configuration. See {@link SqliteKvOptions}.
+ * @returns A {@link Kv} instance backed by SQLite.
+ *
+ * @example
+ * ```ts
+ * import { createSqliteKv } from "@alexkroman1/aai/sqlite-kv";
+ *
+ * const kv = createSqliteKv();
+ * await kv.set("greeting", "hello");
+ * const value = await kv.get<string>("greeting"); // "hello"
+ * ```
+ */
+export declare function createSqliteKv(options?: SqliteKvOptions): Kv;

package/dist/sqlite-kv.js

@@ -0,0 +1,133 @@
+import { MAX_VALUE_SIZE, matchGlob, sortAndPaginate } from "./kv.js";
+import { DatabaseSync } from "node:sqlite";
+//#region sqlite-kv.ts
+/**
+* SQLite-backed key-value storage for local development.
+*
+* Persists data across restarts using a local SQLite database file.
+* Uses `node:sqlite` (built into Node 22+) — no native dependencies.
+* Drop-in replacement for the in-memory KV store.
+*/
+/**
+* Create a SQLite-backed KV store for local development.
+*
+* Data persists to a local SQLite file (default: `.aai/local.db`).
+* TTL expiration is enforced on reads and periodically cleaned up.
+*
+* @param options - Optional configuration. See {@link SqliteKvOptions}.
+* @returns A {@link Kv} instance backed by SQLite.
+*
+* @example
+* ```ts
+* import { createSqliteKv } from "@alexkroman1/aai/sqlite-kv";
+*
+* const kv = createSqliteKv();
+* await kv.set("greeting", "hello");
+* const value = await kv.get<string>("greeting"); // "hello"
+* ```
+*/
+function createSqliteKv(options) {
+	const db = new DatabaseSync(options?.path ?? ".aai/local.db");
+	db.exec("PRAGMA journal_mode = WAL");
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS kv (
+      key   TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      expires_at INTEGER
+    )
+  `);
+	db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_kv_expires_at ON kv(expires_at)
+      WHERE expires_at IS NOT NULL
+  `);
+	const stmtGet = db.prepare("SELECT value, expires_at FROM kv WHERE key = ?");
+	const stmtUpsert = db.prepare("INSERT INTO kv (key, value, expires_at) VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at");
+	const stmtDelete = db.prepare("DELETE FROM kv WHERE key = ?");
+	const stmtDeleteExpired = db.prepare("DELETE FROM kv WHERE expires_at IS NOT NULL AND expires_at <= ?");
+	const stmtListPrefix = db.prepare("SELECT key, value FROM kv WHERE key >= ? AND key < ? AND (expires_at IS NULL OR expires_at > ?)");
+	const stmtListAll = db.prepare("SELECT key, value FROM kv WHERE expires_at IS NULL OR expires_at > ?");
+	const stmtKeysAll = db.prepare("SELECT key FROM kv WHERE expires_at IS NULL OR expires_at > ?");
+	const stmtKeysPrefix = db.prepare("SELECT key FROM kv WHERE key >= ? AND key < ? AND (expires_at IS NULL OR expires_at > ?)");
+	/** Compute the exclusive upper bound for a prefix scan. */
+	function prefixUpperBound(prefix) {
+		if (prefix === "") return "￿";
+		const last = prefix.charCodeAt(prefix.length - 1);
+		return prefix.slice(0, -1) + String.fromCharCode(last + 1);
+	}
+	const cleanupInterval = setInterval(() => {
+		stmtDeleteExpired.run(Date.now());
+	}, 6e4);
+	if (cleanupInterval.unref) cleanupInterval.unref();
+	return {
+		close() {
+			clearInterval(cleanupInterval);
+			db.close();
+		},
+		get(key) {
+			const now = Date.now();
+			const row = stmtGet.get(key);
+			if (!row) return Promise.resolve(null);
+			if (row.expires_at !== null && row.expires_at <= now) {
+				stmtDelete.run(key);
+				return Promise.resolve(null);
+			}
+			return Promise.resolve(JSON.parse(row.value));
+		},
+		set(key, value, setOptions) {
+			try {
+				const raw = JSON.stringify(value);
+				if (raw.length > 65536) return Promise.reject(/* @__PURE__ */ new Error(`Value exceeds max size of ${MAX_VALUE_SIZE} bytes`));
+				const expireIn = setOptions?.expireIn;
+				const expiresAt = expireIn && expireIn > 0 ? Date.now() + expireIn : null;
+				stmtUpsert.run(key, raw, expiresAt);
+				return Promise.resolve();
+			} catch (err) {
+				return Promise.reject(err);
+			}
+		},
+		delete(keys) {
+			const keyArray = Array.isArray(keys) ? keys : [keys];
+			for (const k of keyArray) stmtDelete.run(k);
+			return Promise.resolve();
+		},
+		list(prefix, listOptions) {
+			const now = Date.now();
+			let rows;
+			if (prefix === "") rows = stmtListAll.all(now);
+			else {
+				const upper = prefixUpperBound(prefix);
+				rows = stmtListPrefix.all(prefix, upper, now);
+			}
+			const entries = rows.map((row) => ({
+				key: row.key,
+				value: JSON.parse(row.value)
+			}));
+			return Promise.resolve(sortAndPaginate(entries, listOptions));
+		},
+		keys(pattern) {
+			const now = Date.now();
+			const isGlob = pattern?.includes("*");
+			if (!pattern) {
+				const keys = stmtKeysAll.all(now).map((r) => r.key);
+				return Promise.resolve(keys.sort((a, b) => a.localeCompare(b)));
+			}
+			if (isGlob) {
+				const starIdx = pattern.indexOf("*");
+				const prefix = pattern.slice(0, starIdx);
+				let rows;
+				if (prefix === "") rows = stmtKeysAll.all(now);
+				else {
+					const upper = prefixUpperBound(prefix);
+					rows = stmtKeysPrefix.all(prefix, upper, now);
+				}
+				const keys = rows.filter((r) => matchGlob(r.key, pattern)).map((r) => r.key);
+				return Promise.resolve(keys.sort((a, b) => a.localeCompare(b)));
+			}
+			const upper = prefixUpperBound(pattern);
+			const keys = stmtKeysPrefix.all(pattern, upper, now).map((r) => r.key);
+			return Promise.resolve(keys.sort((a, b) => a.localeCompare(b)));
+		}
+	};
+}
+//#endregion
+export { createSqliteKv };

package/dist/sqlite-vector.d.ts

@@ -0,0 +1,58 @@
+/**
+ * SQLite-backed vector store with local embeddings.
+ *
+ * Persists data across restarts using a local SQLite database file.
+ * Uses brute-force cosine similarity over `node:sqlite` — no native
+ * extensions required. Fast enough for local dev (sub-ms for <10k vectors).
+ * Embeddings are computed locally via `all-MiniLM-L6-v2` (384 dims) —
+ * no external API key required. The model is downloaded on first use
+ * (~86 MB) and cached in `.aai/models/`.
+ */
+import type { VectorStore } from "./vector.ts";
+/** Function that converts text into an embedding vector. */
+export type EmbedFn = (text: string) => Promise<number[]>;
+/**
+ * Options for creating a SQLite-vec backed vector store.
+ */
+export type SqliteVecVectorStoreOptions = {
+    /** Path to the SQLite database file. Defaults to `.aai/vectors.db`. */
+    path?: string;
+    /** Custom embedding function. Defaults to local `all-MiniLM-L6-v2` model. */
+    embedFn?: EmbedFn;
+    /** Embedding dimensions. Must match the embedFn output. Defaults to 384. */
+    dimensions?: number;
+    /** Directory for caching downloaded models. Defaults to `.aai/models`. */
+    modelCacheDir?: string;
+};
+/**
+ * Create a deterministic hash-based embedding function for testing.
+ *
+ * Produces repeatable vectors where similar text yields similar embeddings.
+ * Not suitable for production — use the default local model instead.
+ *
+ * @param dimensions - Vector dimensions (default: 384).
+ */
+export declare function createTestEmbedFn(dimensions?: number): EmbedFn;
+/**
+ * Create a SQLite-backed vector store with local embeddings.
+ *
+ * Data persists to a local SQLite file (default: `.aai/vectors.db`).
+ * Embeddings are computed locally using `all-MiniLM-L6-v2` by default —
+ * no API key required. The model auto-downloads on first use (~86 MB).
+ *
+ * Vector search uses brute-force cosine similarity over all stored
+ * embeddings. This is fast for local dev workloads (<10k vectors).
+ *
+ * @param options - See {@link SqliteVecVectorStoreOptions}.
+ * @returns A {@link VectorStore} instance.
+ *
+ * @example
+ * ```ts
+ * import { createSqliteVectorStore } from "@alexkroman1/aai/sqlite-vector";
+ *
+ * const vector = createSqliteVectorStore();
+ * await vector.upsert("doc-1", "The capital of France is Paris.");
+ * const results = await vector.query("France capital");
+ * ```
+ */
+export declare function createSqliteVectorStore(options?: SqliteVecVectorStoreOptions): VectorStore;