@alexkroman1/aai 0.9.3 → 0.10.1

package/dist/sqlite-vector.js

@@ -0,0 +1,149 @@
+import { DatabaseSync } from "node:sqlite";
+//#region sqlite-vector.ts
+/**
+* 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/`.
+*/
+const DEFAULT_DIMENSIONS = 384;
+const DEFAULT_MODEL = "Xenova/all-MiniLM-L6-v2";
+/**
+* Create a local embedding function using `all-MiniLM-L6-v2`.
+*
+* The model is downloaded on first use (~86 MB) and cached locally.
+* Subsequent calls load from cache in ~90ms. Each embedding takes <2ms.
+*/
+function createLocalEmbedFn(cacheDir) {
+	let pipelinePromise = null;
+	async function getPipeline() {
+		if (!pipelinePromise) pipelinePromise = (async () => {
+			const { pipeline, env } = await import("@huggingface/transformers");
+			env.cacheDir = cacheDir;
+			return pipeline("feature-extraction", DEFAULT_MODEL);
+		})();
+		return pipelinePromise;
+	}
+	return async (text) => {
+		const output = await (await getPipeline())(text, {
+			pooling: "mean",
+			normalize: true
+		});
+		return Array.from(output.data);
+	};
+}
+/**
+* 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).
+*/
+function createTestEmbedFn(dimensions = DEFAULT_DIMENSIONS) {
+	return async (text) => {
+		const vec = new Float32Array(dimensions);
+		const words = text.toLowerCase().split(/\s+/).filter(Boolean);
+		for (const word of words) {
+			let hash = 0;
+			for (let i = 0; i < word.length; i++) hash = (hash << 5) - hash + word.charCodeAt(i) | 0;
+			for (let i = 0; i < 8; i++) {
+				const idx = Math.abs((hash + i * 31337) % dimensions);
+				vec[idx] = (vec[idx] ?? 0) + 1;
+			}
+		}
+		let norm = 0;
+		for (let i = 0; i < dimensions; i++) norm += (vec[i] ?? 0) * (vec[i] ?? 0);
+		norm = Math.sqrt(norm) || 1;
+		return Array.from(vec, (v) => v / norm);
+	};
+}
+/** Cosine similarity between two vectors stored as Buffers of float32. */
+function cosineSimilarity(a, b) {
+	const fa = new Float32Array(a.buffer, a.byteOffset, a.byteLength / 4);
+	const fb = new Float32Array(b.buffer, b.byteOffset, b.byteLength / 4);
+	let dot = 0;
+	let normA = 0;
+	let normB = 0;
+	for (let i = 0; i < fa.length; i++) {
+		const ai = fa[i] ?? 0;
+		const bi = fb[i] ?? 0;
+		dot += ai * bi;
+		normA += ai * ai;
+		normB += bi * bi;
+	}
+	const denom = Math.sqrt(normA) * Math.sqrt(normB);
+	return denom === 0 ? 0 : dot / denom;
+}
+/**
+* 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");
+* ```
+*/
+function createSqliteVectorStore(options) {
+	const dbPath = options?.path ?? ".aai/vectors.db";
+	const cacheDir = options?.modelCacheDir ?? ".aai/models";
+	const embedFn = options?.embedFn ?? createLocalEmbedFn(cacheDir);
+	const db = new DatabaseSync(dbPath);
+	db.exec("PRAGMA journal_mode = WAL");
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS vectors (
+      id TEXT PRIMARY KEY,
+      data TEXT NOT NULL,
+      metadata TEXT NOT NULL DEFAULT '',
+      embedding BLOB NOT NULL
+    )
+  `);
+	const stmtUpsert = db.prepare("INSERT OR REPLACE INTO vectors (id, data, metadata, embedding) VALUES (?, ?, ?, ?)");
+	const stmtDelete = db.prepare("DELETE FROM vectors WHERE id = ?");
+	const stmtAll = db.prepare("SELECT id, data, metadata, embedding FROM vectors");
+	return {
+		async upsert(id, data, metadata) {
+			const vector = await embedFn(data);
+			const embedding = Buffer.from(new Float32Array(vector).buffer);
+			const metaJson = metadata ? JSON.stringify(metadata) : "";
+			stmtUpsert.run(id, data, metaJson, embedding);
+		},
+		async query(text, queryOptions) {
+			const topK = queryOptions?.topK ?? 10;
+			if (!text.trim()) return [];
+			const queryVec = await embedFn(text);
+			const queryBuf = Buffer.from(new Float32Array(queryVec).buffer);
+			const scored = stmtAll.all().map((row) => ({
+				id: row.id,
+				score: cosineSimilarity(queryBuf, row.embedding),
+				data: row.data,
+				metadata: row.metadata && row.metadata !== "" ? JSON.parse(row.metadata) : void 0
+			}));
+			scored.sort((a, b) => b.score - a.score);
+			return scored.slice(0, topK);
+		},
+		async delete(ids) {
+			const idArray = Array.isArray(ids) ? ids : [ids];
+			for (const id of idArray) stmtDelete.run(id);
+		}
+	};
+}
+//#endregion
+export { createSqliteVectorStore, createTestEmbedFn };

package/dist/system-prompt.d.ts

@@ -0,0 +1,21 @@
+/**
+ * System prompt builder for S2S sessions.
+ */
+import type { AgentConfig } from "./_internal-types.ts";
+/**
+ * Build the system prompt sent to the LLM from the agent configuration.
+ *
+ * Assembles the default instructions, today's date, agent-specific instructions,
+ * and optional sections for tool usage preamble and voice output rules.
+ *
+ * @param config - The serializable agent configuration (name, instructions, etc.).
+ * @param opts.hasTools - When `true`, appends a preamble instructing the LLM to
+ *   speak a brief phrase before each tool call to fill silence.
+ * @param opts.voice - When `true`, appends strict voice-specific output rules
+ *   (no markdown, no bullet points, conversational tone, concise responses).
+ * @returns The assembled system prompt string.
+ */
+export declare function buildSystemPrompt(config: AgentConfig, opts: {
+    hasTools: boolean;
+    voice?: boolean;
+}): string;

package/dist/telemetry.d.ts

@@ -0,0 +1,49 @@
+/**
+ * OpenTelemetry instrumentation helpers for the AAI SDK.
+ *
+ * Uses `@opentelemetry/api` only — consumers bring their own SDK and
+ * exporters.  When no SDK is configured the API returns no-op instances,
+ * so the overhead in uninstrumented environments is negligible.
+ *
+ * Provides:
+ * - `tracer`  — a pre-scoped `Tracer` for creating spans
+ * - `meter`   — a pre-scoped `Meter` for recording metrics
+ * - Pre-built counters, histograms, and up/down counters covering the
+ *   STT → LLM → TTS pipeline
+ */
+import { type Meter, type Span, type Tracer } from "@opentelemetry/api";
+/** Tracer scoped to the AAI SDK. */
+export declare const tracer: Tracer;
+/** Meter scoped to the AAI SDK. */
+export declare const meter: Meter;
+/** Total sessions opened. */
+export declare const sessionCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Currently active sessions. */
+export declare const activeSessionsUpDown: import("@opentelemetry/api").UpDownCounter<import("@opentelemetry/api").Attributes>;
+/** Total user turns (speech → transcript). */
+export declare const turnCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Total tool calls executed. */
+export declare const toolCallCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Tool call execution duration in seconds. */
+export declare const toolCallDuration: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/** Total tool call errors. */
+export declare const toolCallErrorCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** S2S WebSocket connection duration in seconds. */
+export declare const s2sConnectionDuration: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/** Total S2S errors. */
+export declare const s2sErrorCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Number of agentic loop steps (tool calls) per completed turn. */
+export declare const turnStepsHistogram: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/** Total barge-in (reply interrupted) events. */
+export declare const bargeInCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Messages silently dropped because the WebSocket was closed. */
+export declare const wsSendDroppedCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Sessions closed due to S2S idle timeout. */
+export declare const idleTimeoutCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Run `fn` inside a new span. The span is automatically ended and its
+ * status set based on whether `fn` throws.
+ */
+export declare function withSpan<T>(name: string, fn: (span: Span) => T): T;
+export type { Meter, Span, Tracer } from "@opentelemetry/api";
+export { context, metrics, SpanStatusCode, trace } from "@opentelemetry/api";

package/dist/telemetry.js

@@ -0,0 +1,95 @@
+import { createRequire } from "node:module";
+import { SpanStatusCode, SpanStatusCode as SpanStatusCode$1, context, metrics, metrics as metrics$1, trace, trace as trace$1 } from "@opentelemetry/api";
+//#region telemetry.ts
+/**
+* OpenTelemetry instrumentation helpers for the AAI SDK.
+*
+* Uses `@opentelemetry/api` only — consumers bring their own SDK and
+* exporters.  When no SDK is configured the API returns no-op instances,
+* so the overhead in uninstrumented environments is negligible.
+*
+* Provides:
+* - `tracer`  — a pre-scoped `Tracer` for creating spans
+* - `meter`   — a pre-scoped `Meter` for recording metrics
+* - Pre-built counters, histograms, and up/down counters covering the
+*   STT → LLM → TTS pipeline
+*/
+const SCOPE = "aai";
+const _require = createRequire(import.meta.url);
+let VERSION = "0.0.0";
+try {
+	VERSION = _require("./package.json").version;
+} catch {
+	VERSION = _require("../package.json").version;
+}
+/** Tracer scoped to the AAI SDK. */
+const tracer = trace$1.getTracer(SCOPE, VERSION);
+/** Meter scoped to the AAI SDK. */
+const meter = metrics$1.getMeter(SCOPE, VERSION);
+/** Total sessions opened. */
+const sessionCounter = meter.createCounter("aai.session.count", { description: "Total voice sessions opened" });
+/** Currently active sessions. */
+const activeSessionsUpDown = meter.createUpDownCounter("aai.session.active", { description: "Currently active voice sessions" });
+/** Total user turns (speech → transcript). */
+const turnCounter = meter.createCounter("aai.turn.count", { description: "Total user turns" });
+/** Total tool calls executed. */
+const toolCallCounter = meter.createCounter("aai.tool.call.count", { description: "Total tool calls executed" });
+/** Tool call execution duration in seconds. */
+const toolCallDuration = meter.createHistogram("aai.tool.call.duration", {
+	description: "Tool call execution duration in seconds",
+	unit: "s"
+});
+/** Total tool call errors. */
+const toolCallErrorCounter = meter.createCounter("aai.tool.call.error.count", { description: "Total tool call errors" });
+/** S2S WebSocket connection duration in seconds. */
+const s2sConnectionDuration = meter.createHistogram("aai.s2s.connection.duration", {
+	description: "S2S WebSocket connection duration in seconds",
+	unit: "s"
+});
+/** Total S2S errors. */
+const s2sErrorCounter = meter.createCounter("aai.s2s.error.count", { description: "Total S2S errors" });
+/** Number of agentic loop steps (tool calls) per completed turn. */
+const turnStepsHistogram = meter.createHistogram("aai.turn.steps", { description: "Number of agentic loop steps per completed turn" });
+/** Total barge-in (reply interrupted) events. */
+const bargeInCounter = meter.createCounter("aai.turn.bargein.count", { description: "Total barge-in (reply interrupted) events" });
+/** Messages silently dropped because the WebSocket was closed. */
+const wsSendDroppedCounter = meter.createCounter("aai.ws.send_dropped", { description: "Messages silently dropped because the WebSocket was closed" });
+/** Sessions closed due to S2S idle timeout. */
+const idleTimeoutCounter = meter.createCounter("aai.session.idle.timeout.count", { description: "Sessions closed due to S2S idle timeout" });
+/**
+* Run `fn` inside a new span. The span is automatically ended and its
+* status set based on whether `fn` throws.
+*/
+function withSpan(name, fn) {
+	return tracer.startActiveSpan(name, (span) => {
+		try {
+			const result = fn(span);
+			if (result instanceof Promise) return result.then((v) => {
+				span.setStatus({ code: SpanStatusCode$1.OK });
+				span.end();
+				return v;
+			}).catch((err) => {
+				span.setStatus({
+					code: SpanStatusCode$1.ERROR,
+					message: err instanceof Error ? err.message : String(err)
+				});
+				span.recordException(err instanceof Error ? err : new Error(String(err)));
+				span.end();
+				throw err;
+			});
+			span.setStatus({ code: SpanStatusCode$1.OK });
+			span.end();
+			return result;
+		} catch (err) {
+			span.setStatus({
+				code: SpanStatusCode$1.ERROR,
+				message: err instanceof Error ? err.message : String(err)
+			});
+			span.recordException(err instanceof Error ? err : new Error(String(err)));
+			span.end();
+			throw err;
+		}
+	});
+}
+//#endregion
+export { SpanStatusCode, activeSessionsUpDown, bargeInCounter, context, idleTimeoutCounter, meter, metrics, s2sConnectionDuration, s2sErrorCounter, sessionCounter, toolCallCounter, toolCallDuration, toolCallErrorCounter, trace, tracer, turnCounter, turnStepsHistogram, withSpan, wsSendDroppedCounter };