@tryhamster/gerbil 1.0.0-rc.11 → 1.0.0-rc.12

package/README.md

@@ -11,6 +11,7 @@
 <p align="center">
   <a href="#install">Install</a> •
   <a href="#quick-start">Quick Start</a> •
+  <a href="#embeddings">Embeddings</a> •
   <a href="#text-to-speech">TTS</a> •
   <a href="#speech-to-text">STT</a> •
   <a href="./docs/vision.md">Vision</a> •
@@ -46,6 +47,7 @@ const text = await gerbil("Explain recursion in one sentence");
 - **Zero Config** — `npx @tryhamster/gerbil "your prompt"` just works
 - **Local & Private** — No API keys, no data leaves your machine
 - **GPU Accelerated** — WebGPU with CPU fallback
+- **Embeddings** — Semantic search, similarity, RAG
 - **Vision** — Analyze images with Ministral 3B
 - **Complete Audio** — Text-to-Speech (Kokoro/Supertonic) & Speech-to-Text (Whisper)
 - **Framework Ready** — AI SDK v5, Next.js, Express, LangChain
@@ -95,6 +97,30 @@ const data = await g.json("Extract: John, 32, NYC", {
 });
 ```
 
+## Embeddings
+
+Generate semantic embeddings for search, similarity, and RAG:
+
+```typescript
+// Compare two texts
+const similarity = await g.similarity("Hello world", "Hi there");
+console.log(similarity.score); // 0.85
+
+// Semantic search
+const results = await g.search("capital of France", [
+  "Paris is beautiful",
+  "London is in England",
+  "Dogs are pets"
+]);
+// [{ text: "Paris is beautiful", score: 0.89, index: 0 }, ...]
+
+// Generate embedding vector
+const { vector } = await g.embed("Hello world");
+// number[384]
+```
+
+📖 **[Full Embeddings Documentation →](./docs/embeddings.md)**
+
 ## Text-to-Speech
 
 Generate natural speech locally using Kokoro TTS (28 voices):
@@ -298,6 +324,7 @@ Use any HuggingFace model: `npx @tryhamster/gerbil -m hf:org/model "prompt"`
 
 | Guide | Description |
 |-------|-------------|
+| [📖 Embeddings](./docs/embeddings.md) | Semantic search, similarity, RAG |
 | [📖 Vision](./docs/vision.md) | Image analysis with Ministral 3B |
 | [📖 Text-to-Speech](./docs/tts.md) | Kokoro & Supertonic TTS, streaming audio |
 | [📖 Speech-to-Text](./docs/stt.md) | Whisper STT, transcription, voice input |
@@ -305,7 +332,7 @@ Use any HuggingFace model: `npx @tryhamster/gerbil -m hf:org/model "prompt"`
 | [📖 Skills](./docs/skills.md) | Built-in skills, custom skill development |
 | [📖 Tools](./docs/tools.md) | Tool calling, agentic workflows |
 | [📖 REPL](./docs/repl.md) | Interactive terminal dashboard |
-| [📖 AI SDK](./docs/ai-sdk.md) | Vercel AI SDK v5 (LLM, TTS, STT) |
+| [📖 AI SDK](./docs/ai-sdk.md) | Vercel AI SDK v5 (LLM, TTS, STT, Embeddings) |
 | [📖 Frameworks](./docs/frameworks.md) | Next.js, Express, React, LangChain |
 | [📖 CLI](./docs/cli.md) | All CLI commands and options |
 | [📖 MCP Server](./docs/mcp.md) | MCP server for Claude Desktop & Cursor |

package/dist/browser/index.d.ts

@@ -92,6 +92,24 @@ type EmbedResult = {
   /** Time in ms */
   totalTime: number;
 };
+type SearchResult = {
+  /** The matched text */
+  text: string;
+  /** Similarity score (0-1, higher is more similar) */
+  score: number;
+  /** Index in the original corpus */
+  index: number;
+};
+type SimilarityResult = {
+  /** Similarity score (0-1, higher is more similar) */
+  score: number;
+  /** First text */
+  textA: string;
+  /** Second text */
+  textB: string;
+  /** Time in ms */
+  totalTime: number;
+};
 type LoadOptions = {
   /** Progress callback */
   onProgress?: (info: ProgressInfo) => void;
@@ -985,6 +1003,85 @@ type UseVoiceChatReturn = {
  * ```
  */
 declare function useVoiceChat(options?: UseVoiceChatOptions): UseVoiceChatReturn;
+/** Embedding result type */
+type BrowserEmbedResult = {
+  vector: number[];
+  text: string;
+};
+/** Search result type */
+type BrowserSearchResult = {
+  text: string;
+  score: number;
+  index: number;
+};
+/** useEmbedding options */
+type UseEmbeddingOptions = {
+  /** Embedding model (default: "Xenova/all-MiniLM-L6-v2") */
+  model?: string;
+  /** Normalize vectors (default: true) */
+  normalize?: boolean;
+  /** Auto-load on mount (default: false) */
+  autoLoad?: boolean;
+  /** Callback when ready */
+  onReady?: () => void;
+  /** Callback on error */
+  onError?: (error: string) => void;
+};
+/** useEmbedding return type */
+type UseEmbeddingReturn = {
+  /** Generate embedding for text */
+  embed: (text: string) => Promise<number[]>;
+  /** Generate embeddings for multiple texts */
+  embedBatch: (texts: string[]) => Promise<BrowserEmbedResult[]>;
+  /** Compute cosine similarity between two texts */
+  similarity: (textA: string, textB: string) => Promise<number>;
+  /** Semantic search - find most similar texts */
+  search: (query: string, corpus: string[], topK?: number) => Promise<BrowserSearchResult[]>;
+  /** Find nearest text to an embedding vector */
+  findNearest: (embedding: number[], candidates: string[], topK?: number) => Promise<BrowserSearchResult[]>;
+  /** Compute cosine similarity between two vectors */
+  cosineSimilarity: (a: number[], b: number[]) => number;
+  /** Manually load the model */
+  load: () => void;
+  /** Whether model is loading */
+  isLoading: boolean;
+  /** Whether model is ready */
+  isReady: boolean;
+  /** Loading progress */
+  loadingProgress: {
+    status: string;
+    message?: string;
+    progress?: number;
+  } | null;
+  /** Error message */
+  error: string | null;
+};
+/**
+ * React hook for text embeddings in the browser
+ *
+ * @example
+ * ```tsx
+ * import { useEmbedding } from "@tryhamster/gerbil/browser";
+ *
+ * function App() {
+ *   const { embed, similarity, search, isLoading, isReady } = useEmbedding();
+ *
+ *   if (isLoading) return <div>Loading embedding model...</div>;
+ *
+ *   const handleSearch = async () => {
+ *     const results = await search("capital of France", [
+ *       "Paris is beautiful",
+ *       "London is in England",
+ *       "Dogs are pets"
+ *     ]);
+ *     console.log(results); // [{ text: "Paris is beautiful", score: 0.89, index: 0 }, ...]
+ *   };
+ *
+ *   return <button onClick={handleSearch}>Search</button>;
+ * }
+ * ```
+ */
+declare function useEmbedding(options?: UseEmbeddingOptions): UseEmbeddingReturn;
 /**
  * Check if WebGPU is supported
  */
@@ -1005,5 +1102,5 @@ declare const _default: {
   createAudioPlayer: typeof createAudioPlayer;
 };
 //#endregion
-export { AudioChunk, BUILTIN_MODELS, BrowserVoiceInfo, CacheConfig, CompleteOptions, EmbedOptions, EmbedResult, FallbackConfig, GenerateOptions, GenerateResult, GenerateStreamOptions, GerbilConfig, GerbilModelSettings, GerbilProviderSettings, GerbilWorker, GerbilWorkerOptions, ImageInput, JsonOptions, LoadOptions, LoadSTTOptions, LoadTTSOptions, LoadingProgress, Message, ModelConfig, ModelSource, ModelStats, ProgressInfo, STTModelConfig, STTProgress, SessionStats, SpeakOptions, SpeakResult, StreamingTranscriptionOptions, StreamingTranscriptionSession, SystemInfo, TTSModelConfig, TTSModelId, TTSProgress, TranscribeOptions, TranscribeResult, TranscribeSegment, UseChatOptions, UseChatReturn, UseCompletionOptions, UseCompletionReturn, UseSpeechOptions, UseSpeechReturn, UseVoiceChatOptions, UseVoiceChatReturn, UseVoiceInputOptions, UseVoiceInputReturn, VoiceChatMessage, VoiceInfo, WorkerComplete, WorkerProgress, WorkerToken, createAudioPlayer, createGerbilWorker, _default as default, getWebGPUInfo, isWebGPUSupported, playAudio, useChat, useCompletion, useSpeech, useVoiceChat, useVoiceInput };
+export { AudioChunk, BUILTIN_MODELS, BrowserEmbedResult, BrowserSearchResult, BrowserVoiceInfo, CacheConfig, CompleteOptions, EmbedOptions, EmbedResult, FallbackConfig, GenerateOptions, GenerateResult, GenerateStreamOptions, GerbilConfig, GerbilModelSettings, GerbilProviderSettings, GerbilWorker, GerbilWorkerOptions, ImageInput, JsonOptions, LoadOptions, LoadSTTOptions, LoadTTSOptions, LoadingProgress, Message, ModelConfig, ModelSource, ModelStats, ProgressInfo, STTModelConfig, STTProgress, SearchResult, SessionStats, SimilarityResult, SpeakOptions, SpeakResult, StreamingTranscriptionOptions, StreamingTranscriptionSession, SystemInfo, TTSModelConfig, TTSModelId, TTSProgress, TranscribeOptions, TranscribeResult, TranscribeSegment, UseChatOptions, UseChatReturn, UseCompletionOptions, UseCompletionReturn, UseEmbeddingOptions, UseEmbeddingReturn, UseSpeechOptions, UseSpeechReturn, UseVoiceChatOptions, UseVoiceChatReturn, UseVoiceInputOptions, UseVoiceInputReturn, VoiceChatMessage, VoiceInfo, WorkerComplete, WorkerProgress, WorkerToken, createAudioPlayer, createGerbilWorker, _default as default, getWebGPUInfo, isWebGPUSupported, playAudio, useChat, useCompletion, useEmbedding, useSpeech, useVoiceChat, useVoiceInput };
 //# sourceMappingURL=index.d.ts.map

package/dist/browser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/core/types.ts","../../src/core/models.ts","../../src/browser/index.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/core/types.ts","../../src/core/models.ts","../../src/browser/index.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/browser/index.js

@@ -2715,6 +2715,316 @@ function useVoiceChat(options = {}) {
 		load
 	};
 }
+const EMBEDDING_WORKER_CODE = `
+  // Embedding Worker - runs in separate thread, loads from CDN
+  import { pipeline, env } from "https://cdn.jsdelivr.net/npm/@huggingface/transformers@3.8.1";
+  
+  // Configure environment
+  env.useBrowserCache = true;
+  env.allowLocalModels = false;
+  
+  let embedder = null;
+  let modelId = null;
+  
+  self.onmessage = async (e) => {
+    const { type, payload } = e.data;
+    
+    if (type === "load") {
+      try {
+        modelId = payload.model || "Xenova/all-MiniLM-L6-v2";
+        
+        embedder = await pipeline("feature-extraction", modelId, {
+          progress_callback: (progress) => {
+            self.postMessage({ type: "progress", payload: progress });
+          },
+        });
+        
+        // Warmup
+        try {
+          await embedder("hello", { pooling: "mean", normalize: true });
+        } catch (e) {
+          console.warn("Embedding warmup failed:", e);
+        }
+        
+        self.postMessage({ type: "ready" });
+      } catch (err) {
+        self.postMessage({ type: "error", payload: err.message || String(err) });
+      }
+    }
+    
+    if (type === "embed") {
+      try {
+        const { text, normalize } = payload;
+        const output = await embedder(text, {
+          pooling: "mean",
+          normalize: normalize !== false,
+        });
+        
+        const vector = Array.from(output.data);
+        self.postMessage({ type: "embedding", payload: { vector, text } });
+      } catch (err) {
+        self.postMessage({ type: "error", payload: err.message || String(err) });
+      }
+    }
+    
+    if (type === "embedBatch") {
+      try {
+        const { texts, normalize } = payload;
+        const results = [];
+        
+        for (const text of texts) {
+          const output = await embedder(text, {
+            pooling: "mean",
+            normalize: normalize !== false,
+          });
+          results.push({ vector: Array.from(output.data), text });
+        }
+        
+        self.postMessage({ type: "embeddings", payload: results });
+      } catch (err) {
+        self.postMessage({ type: "error", payload: err.message || String(err) });
+      }
+    }
+  };
+`;
+/** Create Embedding worker instance */
+function createEmbeddingWorker() {
+	const blob = new Blob([EMBEDDING_WORKER_CODE], { type: "application/javascript" });
+	const url = URL.createObjectURL(blob);
+	const worker = new Worker(url, { type: "module" });
+	URL.revokeObjectURL(url);
+	return worker;
+}
+/**
+* React hook for text embeddings in the browser
+*
+* @example
+* ```tsx
+* import { useEmbedding } from "@tryhamster/gerbil/browser";
+*
+* function App() {
+*   const { embed, similarity, search, isLoading, isReady } = useEmbedding();
+*
+*   if (isLoading) return <div>Loading embedding model...</div>;
+*
+*   const handleSearch = async () => {
+*     const results = await search("capital of France", [
+*       "Paris is beautiful",
+*       "London is in England",
+*       "Dogs are pets"
+*     ]);
+*     console.log(results); // [{ text: "Paris is beautiful", score: 0.89, index: 0 }, ...]
+*   };
+*
+*   return <button onClick={handleSearch}>Search</button>;
+* }
+* ```
+*/
+function useEmbedding(options = {}) {
+	const React = globalThis.React;
+	if (!React) throw new Error("useEmbedding requires React. Make sure React is available in the global scope.");
+	const { useState, useEffect, useRef, useCallback } = React;
+	const { model = "Xenova/all-MiniLM-L6-v2", normalize = true, autoLoad = false, onReady, onError } = options;
+	const [isLoading, setIsLoading] = useState(false);
+	const [isReady, setIsReady] = useState(false);
+	const [error, setError] = useState(null);
+	const [loadingProgress, setLoadingProgress] = useState(null);
+	const workerRef = useRef(null);
+	const loadRequestedRef = useRef(false);
+	const pendingRequestsRef = useRef(/* @__PURE__ */ new Map());
+	const cosineSimilarity = useCallback((a, b) => {
+		if (a.length !== b.length) throw new Error(`Vector dimensions must match: ${a.length} vs ${b.length}`);
+		let dotProduct = 0;
+		let normA = 0;
+		let normB = 0;
+		for (let i = 0; i < a.length; i++) {
+			dotProduct += a[i] * b[i];
+			normA += a[i] * a[i];
+			normB += b[i] * b[i];
+		}
+		const magnitude = Math.sqrt(normA) * Math.sqrt(normB);
+		if (magnitude === 0) return 0;
+		return dotProduct / magnitude;
+	}, []);
+	const load = useCallback(() => {
+		if (loadRequestedRef.current || isReady) return;
+		loadRequestedRef.current = true;
+		setIsLoading(true);
+		setLoadingProgress({
+			status: "loading",
+			message: "Loading embedding model..."
+		});
+		const worker = createEmbeddingWorker();
+		workerRef.current = worker;
+		worker.onmessage = (e) => {
+			const { type, payload } = e.data;
+			if (type === "progress") {
+				if (payload.status === "progress" && payload.file) setLoadingProgress({
+					status: "downloading",
+					message: `Downloading ${payload.file}`,
+					progress: Math.round(payload.loaded / payload.total * 100)
+				});
+			} else if (type === "ready") {
+				setIsLoading(false);
+				setIsReady(true);
+				setLoadingProgress({ status: "ready" });
+				onReady?.();
+			} else if (type === "error") {
+				setIsLoading(false);
+				setError(payload);
+				onError?.(payload);
+			} else if (type === "embedding" || type === "embeddings") {
+				const pending = pendingRequestsRef.current.get(type);
+				if (pending) {
+					pending.resolve(payload);
+					pendingRequestsRef.current.delete(type);
+				}
+			}
+		};
+		worker.postMessage({
+			type: "load",
+			payload: { model }
+		});
+	}, [
+		model,
+		isReady,
+		onReady,
+		onError
+	]);
+	useEffect(() => {
+		if (autoLoad) load();
+		return () => {
+			if (workerRef.current) {
+				workerRef.current.terminate();
+				workerRef.current = null;
+			}
+		};
+	}, [autoLoad, load]);
+	const embed = useCallback(async (text) => {
+		if (!isReady) {
+			load();
+			await new Promise((resolve) => {
+				const checkReady = setInterval(() => {
+					if (workerRef.current) {
+						const handler = (e) => {
+							if (e.data.type === "ready") {
+								clearInterval(checkReady);
+								resolve();
+							}
+						};
+						workerRef.current.addEventListener("message", handler, { once: true });
+					}
+				}, 100);
+			});
+		}
+		return new Promise((resolve, reject) => {
+			const worker = workerRef.current;
+			if (!worker) {
+				reject(/* @__PURE__ */ new Error("Worker not initialized"));
+				return;
+			}
+			const handler = (e) => {
+				if (e.data.type === "embedding") {
+					worker.removeEventListener("message", handler);
+					resolve(e.data.payload.vector);
+				} else if (e.data.type === "error") {
+					worker.removeEventListener("message", handler);
+					reject(new Error(e.data.payload));
+				}
+			};
+			worker.addEventListener("message", handler);
+			worker.postMessage({
+				type: "embed",
+				payload: {
+					text,
+					normalize
+				}
+			});
+		});
+	}, [
+		isReady,
+		load,
+		normalize
+	]);
+	const embedBatch = useCallback(async (texts) => {
+		if (!isReady) {
+			load();
+			await new Promise((resolve) => {
+				const check = setInterval(() => {
+					if (isReady) {
+						clearInterval(check);
+						resolve();
+					}
+				}, 100);
+			});
+		}
+		return new Promise((resolve, reject) => {
+			const worker = workerRef.current;
+			if (!worker) {
+				reject(/* @__PURE__ */ new Error("Worker not initialized"));
+				return;
+			}
+			const handler = (e) => {
+				if (e.data.type === "embeddings") {
+					worker.removeEventListener("message", handler);
+					resolve(e.data.payload);
+				} else if (e.data.type === "error") {
+					worker.removeEventListener("message", handler);
+					reject(new Error(e.data.payload));
+				}
+			};
+			worker.addEventListener("message", handler);
+			worker.postMessage({
+				type: "embedBatch",
+				payload: {
+					texts,
+					normalize
+				}
+			});
+		});
+	}, [
+		isReady,
+		load,
+		normalize
+	]);
+	return {
+		embed,
+		embedBatch,
+		similarity: useCallback(async (textA, textB) => {
+			const [embA, embB] = await Promise.all([embed(textA), embed(textB)]);
+			return cosineSimilarity(embA, embB);
+		}, [embed, cosineSimilarity]),
+		search: useCallback(async (query, corpus, topK) => {
+			const [queryEmb, corpusEmbs] = await Promise.all([embed(query), embedBatch(corpus)]);
+			const results = corpusEmbs.map((doc, index) => ({
+				text: doc.text,
+				score: cosineSimilarity(queryEmb, doc.vector),
+				index
+			}));
+			results.sort((a, b) => b.score - a.score);
+			return topK ? results.slice(0, topK) : results;
+		}, [
+			embed,
+			embedBatch,
+			cosineSimilarity
+		]),
+		findNearest: useCallback(async (embedding, candidates, topK) => {
+			const results = (await embedBatch(candidates)).map((doc, index) => ({
+				text: doc.text,
+				score: cosineSimilarity(embedding, doc.vector),
+				index
+			}));
+			results.sort((a, b) => b.score - a.score);
+			return topK ? results.slice(0, topK) : results;
+		}, [embedBatch, cosineSimilarity]),
+		cosineSimilarity,
+		load,
+		isLoading,
+		isReady,
+		loadingProgress,
+		error
+	};
+}
 /**
 * Check if WebGPU is supported
 */
@@ -2749,5 +3059,5 @@ var browser_default = {
 };
 
 //#endregion
-export { BUILTIN_MODELS, createAudioPlayer, createGerbilWorker, browser_default as default, getWebGPUInfo, isWebGPUSupported, playAudio, useChat, useCompletion, useSpeech, useVoiceChat, useVoiceInput };
+export { BUILTIN_MODELS, createAudioPlayer, createGerbilWorker, browser_default as default, getWebGPUInfo, isWebGPUSupported, playAudio, useChat, useCompletion, useEmbedding, useSpeech, useVoiceChat, useVoiceInput };
 //# sourceMappingURL=index.js.map