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

package/docs/browser.md

@@ -456,6 +456,75 @@ for await (const chunk of gerbil.speakStream("Long text...")) {
 }
 ```
 
+## Embeddings Hook
+
+### `useEmbedding`
+
+Generate embeddings for semantic search and similarity:
+
+```tsx
+import { useEmbedding } from "@tryhamster/gerbil/browser";
+
+function SemanticSearch() {
+  const { embed, similarity, search, isLoading, isReady, load } = useEmbedding({
+    model: "Xenova/all-MiniLM-L6-v2",  // Default
+    autoLoad: false,
+  });
+
+  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",
+    ], 2);  // topK = 2
+    
+    console.log(results);
+    // [{ text: "Paris is beautiful", score: 0.89, index: 0 }, ...]
+  };
+
+  const handleSimilarity = async () => {
+    const score = await similarity("Hello world", "Hi there");
+    console.log(score); // 0.85
+  };
+
+  return (
+    <div>
+      <button onClick={handleSearch}>Search</button>
+      <button onClick={handleSimilarity}>Compare</button>
+    </div>
+  );
+}
+```
+
+### Options
+
+```typescript
+const {
+  // Actions
+  embed,            // (text: string) => Promise<number[]>
+  embedBatch,       // (texts: string[]) => Promise<{ vector, text }[]>
+  similarity,       // (a: string, b: string) => Promise<number>
+  search,           // (query: string, corpus: string[], topK?) => Promise<SearchResult[]>
+  findNearest,      // (embedding: number[], candidates: string[], topK?) => Promise<SearchResult[]>
+  cosineSimilarity, // (a: number[], b: number[]) => number (sync)
+  load,             // () => void - manually load model
+  
+  // State
+  isLoading,        // boolean - model loading
+  isReady,          // boolean - model ready
+  loadingProgress,  // { status, message?, progress? }
+  error,            // string | null
+} = useEmbedding({
+  model: "Xenova/all-MiniLM-L6-v2",  // Embedding model
+  normalize: true,                    // Normalize vectors (default: true)
+  autoLoad: false,                    // Load on mount (default: false)
+  onReady: () => {},
+  onError: (err) => {},
+});
+```
+
 ## Low-Level API
 
 For full control, use `createGerbilWorker` directly:

package/docs/embeddings.md

@@ -0,0 +1,311 @@
+# Embeddings
+
+Gerbil provides local text embeddings using transformer models via ONNX. Generate semantic vectors for similarity search, clustering, and retrieval - all on-device with no API keys.
+
+## Quick Start
+
+### Node.js
+
+```typescript
+import { Gerbil } from "@tryhamster/gerbil";
+
+const g = new Gerbil();
+
+// Generate embedding
+const result = await g.embed("Hello world");
+console.log(result.vector); // number[384]
+
+// Compare similarity
+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 }, ...]
+```
+
+### React (Browser)
+
+```tsx
+import { useEmbedding } from "@tryhamster/gerbil/browser";
+
+function SemanticSearch() {
+  const { 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);
+  };
+
+  return <button onClick={handleSearch}>Search</button>;
+}
+```
+
+### AI SDK
+
+```typescript
+import { embed, embedMany } from "ai";
+import { gerbil } from "@tryhamster/gerbil/ai";
+
+// Single embedding
+const { embedding } = await embed({
+  model: gerbil.embedding(),
+  value: "Hello world",
+});
+
+// Multiple embeddings
+const { embeddings } = await embedMany({
+  model: gerbil.embedding(),
+  values: ["Hello", "World", "How are you?"],
+});
+```
+
+## Available Models
+
+| Model | Dimensions | Size | Description |
+|-------|------------|------|-------------|
+| `all-MiniLM-L6-v2` | 384 | ~23MB | Default, fast and versatile |
+| `bge-small-en-v1.5` | 384 | ~33MB | High quality English embeddings |
+| `gte-small` | 384 | ~33MB | General text embeddings |
+
+Use any ONNX model from HuggingFace:
+
+```typescript
+await g.embed("text", { model: "Xenova/all-MiniLM-L6-v2" });
+```
+
+## API Reference
+
+### Gerbil Class Methods
+
+```typescript
+class Gerbil {
+  // Generate embedding for text
+  async embed(text: string, options?: EmbedOptions): Promise<EmbedResult>;
+  
+  // Batch embedding
+  async embedBatch(texts: string[], options?: EmbedOptions): Promise<EmbedResult[]>;
+  
+  // Compare two texts
+  async similarity(textA: string, textB: string, options?: EmbedOptions): Promise<SimilarityResult>;
+  
+  // Semantic search
+  async search(query: string, corpus: string[], options?: SearchOptions): Promise<SearchResult[]>;
+  
+  // Find nearest text to an embedding
+  async findNearest(embedding: number[], candidates: string[], options?: SearchOptions): Promise<SearchResult[]>;
+  
+  // Raw vector similarity (synchronous)
+  cosineSimilarity(a: number[], b: number[]): number;
+}
+```
+
+### Types
+
+```typescript
+interface EmbedOptions {
+  /** Embedding model (default: "Xenova/all-MiniLM-L6-v2") */
+  model?: string;
+  /** Normalize vectors (default: true) */
+  normalize?: boolean;
+}
+
+interface EmbedResult {
+  /** Embedding vector */
+  vector: number[];
+  /** Original text */
+  text: string;
+  /** Time in ms */
+  totalTime: number;
+}
+
+interface SimilarityResult {
+  /** Similarity score (0-1) */
+  score: number;
+  /** First text */
+  textA: string;
+  /** Second text */
+  textB: string;
+  /** Time in ms */
+  totalTime: number;
+}
+
+interface SearchResult {
+  /** Matched text */
+  text: string;
+  /** Similarity score (0-1) */
+  score: number;
+  /** Index in original corpus */
+  index: number;
+}
+
+interface SearchOptions extends EmbedOptions {
+  /** Return only top K results */
+  topK?: number;
+}
+```
+
+## Use Cases
+
+### Semantic Search
+
+Find the most relevant documents for a query:
+
+```typescript
+const documents = [
+  "JavaScript is a programming language",
+  "Python is great for data science",
+  "The weather is sunny today",
+  "Machine learning uses algorithms",
+];
+
+const results = await g.search("coding languages", documents, { topK: 2 });
+// Returns JavaScript and Python documents
+```
+
+### Duplicate Detection
+
+Find similar or duplicate content:
+
+```typescript
+const similarity = await g.similarity(
+  "The quick brown fox jumps over the lazy dog",
+  "A fast brown fox leaps over a sleepy dog"
+);
+
+if (similarity.score > 0.9) {
+  console.log("Potential duplicate detected!");
+}
+```
+
+### Clustering
+
+Group similar items together:
+
+```typescript
+const items = ["apple", "banana", "car", "truck", "orange"];
+const embeddings = await g.embedBatch(items);
+
+// Use embeddings for k-means or hierarchical clustering
+// Each embedding.vector is a 384-dimensional vector
+```
+
+### RAG (Retrieval-Augmented Generation)
+
+Build a simple RAG pipeline:
+
+```typescript
+// 1. Index documents
+const documents = await loadDocuments();
+const docEmbeddings = await g.embedBatch(documents);
+
+// 2. Store embeddings (in-memory or vector DB)
+const index = docEmbeddings.map((e, i) => ({ 
+  embedding: e.vector, 
+  text: documents[i] 
+}));
+
+// 3. Retrieve relevant docs
+const queryEmbedding = (await g.embed(userQuestion)).vector;
+const relevant = await g.findNearest(
+  queryEmbedding, 
+  documents, 
+  { topK: 3 }
+);
+
+// 4. Generate answer with context
+const context = relevant.map(r => r.text).join("\n");
+const answer = await g.generate(`Context:\n${context}\n\nQuestion: ${userQuestion}`);
+```
+
+## useEmbedding Hook Reference
+
+```typescript
+const {
+  // Actions
+  embed,           // (text: string) => Promise<number[]>
+  embedBatch,      // (texts: string[]) => Promise<BrowserEmbedResult[]>
+  similarity,      // (a: string, b: string) => Promise<number>
+  search,          // (query: string, corpus: string[], topK?: number) => Promise<SearchResult[]>
+  findNearest,     // (embedding: number[], candidates: string[], topK?: number) => Promise<SearchResult[]>
+  cosineSimilarity,// (a: number[], b: number[]) => number (sync)
+  load,            // () => void - manually load model
+  
+  // State
+  isLoading,       // boolean - model loading
+  isReady,         // boolean - model ready
+  loadingProgress, // { status, message?, progress? }
+  error,           // string | null
+} = useEmbedding({
+  model: "Xenova/all-MiniLM-L6-v2",  // Embedding model
+  normalize: true,                    // Normalize vectors
+  autoLoad: false,                    // Load on first use
+  onReady: () => {},
+  onError: (err) => {},
+});
+```
+
+## Performance
+
+| Operation | Time (M1 Mac) |
+|-----------|---------------|
+| First load | 2-5s (downloads model) |
+| Cached load | <500ms |
+| Single embed | ~20ms |
+| Batch (10 texts) | ~150ms |
+| Search (100 docs) | ~300ms |
+
+## Limitations
+
+- **No reverse mapping**: Embeddings cannot be converted back to text
+- **English-optimized**: Default models work best with English text
+- **Fixed dimensions**: Each model produces fixed-size vectors (384 for default)
+
+## Troubleshooting
+
+### "Model not found"
+
+Use the full HuggingFace model ID:
+
+```typescript
+// ❌ Won't work
+await g.embed("text", { model: "MiniLM" });
+
+// ✅ Use full ID
+await g.embed("text", { model: "Xenova/all-MiniLM-L6-v2" });
+```
+
+### Slow first embedding
+
+The first call downloads the model (~23MB). Subsequent calls use the cached model.
+
+### Out of memory with large batches
+
+Process in smaller batches:
+
+```typescript
+const batchSize = 100;
+const allEmbeddings = [];
+
+for (let i = 0; i < texts.length; i += batchSize) {
+  const batch = texts.slice(i, i + batchSize);
+  const embeddings = await g.embedBatch(batch);
+  allEmbeddings.push(...embeddings);
+}
+```
+
+## See Also
+
+- [Browser Hooks](./browser.md) - useChat, useCompletion, useEmbedding
+- [AI SDK Integration](./ai-sdk.md) - embed, embedMany
+

package/docs/tts.md

@@ -500,7 +500,7 @@ export function createTTS(modelId: string = "kokoro-82m"): TTSBackend {
 
 ### 2. Browser Hook (`src/browser/index.ts`)
 
-Add browser support in the useSpeech hook:
+**Important:** Browser TTS runs in an inline Web Worker that loads from CDN. Direct imports don't work due to bundler issues with onnxruntime-web.
 
 ```typescript
 // 1. Add voice definitions for browser
@@ -522,10 +522,15 @@ const TTS_MODELS: Record<TTSModelId, {...}> = {
 // 3. Update TTSModelId type
 export type TTSModelId = "kokoro-82m" | "supertonic-66m" | "my-model-50m";
 
-// 4. Add loading logic in useSpeech useEffect
-if (modelId === "my-model-50m") {
-  // Load using appropriate method (pipeline, custom loader, etc.)
-}
+// 4. Update TTS_WORKER_CODE to handle the new model
+const TTS_WORKER_CODE = `
+  import { pipeline } from "https://cdn.jsdelivr.net/npm/@huggingface/transformers@3.8.1";
+  
+  // Add loading logic for new model
+  if (modelType === "my-model") {
+    // Load from CDN, not npm
+  }
+`;
 ```
 
 ### 3. Gerbil Class (`src/core/gerbil.ts`)
@@ -553,17 +558,15 @@ Update these integration files if applicable:
 Update documentation:
 
 - `docs/tts.md`: Add model to tables and examples
-- `.cursor/rules/gerbil/tts.mdc`: Update implementation patterns
 
 ### File Summary
 
 | File | Purpose |
 |------|---------|
 | `src/core/tts.ts` | Core TTS classes, voice registry, model config |
-| `src/browser/index.ts` | React hooks (useSpeech, useVoiceChat) |
+| `src/browser/index.ts` | React hooks (useSpeech, useVoiceChat) + TTS worker |
 | `src/core/gerbil.ts` | Main Gerbil class integration |
 | `src/integrations/ai-sdk.ts` | AI SDK v5 speech model |
 | `src/skills/builtin/speak.ts` | Speak skill voice options |
 | `docs/tts.md` | User documentation |
-| `.cursor/rules/gerbil/tts.mdc` | Developer patterns |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryhamster/gerbil",
-  "version": "1.0.0-rc.10",
+  "version": "1.0.0-rc.12",
   "description": "Local LLM inference for Node.js. GPU-accelerated. Zero config. Works standalone or with Vercel AI SDK.",
   "type": "module",
   "main": "dist/index.mjs",

package/dist/gerbil-DJGqq7BX.mjs

@@ -1,4 +0,0 @@
-import { t as Gerbil } from "./gerbil-DoDGHe6Z.mjs";
-import "./utils-CZBZ8dgR.mjs";
-
-export { Gerbil };

package/dist/gerbil-qOTe1nl2.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"gerbil-qOTe1nl2.d.mts","names":[],"sources":["../src/core/gerbil.ts"],"sourcesContent":[],"mappings":";;;;AAqOsB,cAlBT,MAAA,CAkBS;EAiBC,QAAA,SAAA;EAIa,QAAA,SAAA;EA0Be,QAAA,KAAA;EAAmB,QAAA,QAAA;EA8SpD,QAAA,YAAA;EA+CH,QAAA,WAAA;EAYY,iBAAA,MAAA;EAUD,QAAA,KAAA;EAWJ,QAAA,SAAA;EAW0B,QAAA,aAAA;EAyBN,QAAA,WAAA;EAA+B,QAAA,SAAA;EAAR,QAAA,WAAA;EAsNpD,QAAA,aAAA;EACe,WAAA,CAAA,MAAA,CAAA,EAxqBN,YAwqBM;EAAvB,OAAA,UAAA,CAAA,CAAA,EAvpBkB,WAupBlB,EAAA;EA0SgD,OAAA,QAAA,CAAA,OAAA,EAAA,MAAA,CAAA,EA77BjB,WA67BiB,GAAA,SAAA;EAAZ;;;;;;;;;;;;;;;;;;EAgN5B,SAAA,CAAA,OAAA,CAAA,EAAA,MAAA,EAAA,OAAA,CAAA,EAnnCsC,WAmnCtC,CAAA,EAnnCyD,OAmnCzD,CAAA,IAAA,CAAA;EACO;;;;EAyChB,QAAA,eAAA;EADqB;;;EAiDkC,QAAA,CAAA,CAAA,EAAA,OAAA;EAAiB;;;EA+B/D,cAAA,CAAA,CAAA,EAAA,OAAA;EACA;;;EAkCA,YAAA,CAAA,CAAA,EAj+BK,WAi+BL,GAAA,IAAA;EAAR;;;EAyDQ,aAAA,CAAA,CAAA,EAAA,QAAA,GAAA,KAAA,GAAA,MAAA;EAAR;;;EAiIsB,QAAA,CAAA,CAAA,EAAA,MAAA;EAkBb;;;EA6CmC,qBAAA,CAAA,CAAA,EAAA;IAkBD,IAAA,EAAA,MAAA;IAAR,MAAA,EAAA,MAAA;IAuBM,IAAA,EAAA,MAAA;IAgBJ,OAAA,EAAA,MAAA;EAAO,CAAA;;;;;;;;;;;;eApuClC;;;;;;qBAYY;;;;;;;oBAUD;;;;;;;;;gBAWJ;;;;;;+CAW0B;;;;;;;;;;;;;;;qCAyBN,kBAAuB,QAAQ;;;;;;;mCAsN5D,kBACR,uBAAuB;;;;;;;;;;;;;mCA0Sa,YAAY,KAAK,QAAQ;;;;gCAqC7B,eAAoB,QAAQ;;;;wCAyBpB,eAAoB,QAAQ;;;;cAe3D;;;;aAOD;;;;;;;;;;;;;;;;;;;;;;oBA4DY;;MAA2C;;;;4BA4BlC,iBAAiB;;;;;;;;;;;;gCAiBd,eAAoB,QAAQ;;;;;;;;;;;;;sCAmBpD,eACR,eAAe,YAAY;;;;gBAQhB;;;;;;;;;;;;;;;;mBAgCS,QACrB;;;;;;;;;;;;;;;;;;;;sCA8BuC,iBAAsB;;;;8CAkBN,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;oBA8BjE,eAAe,sBACb,oBACR,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;yCAiCA,gCACR,QAAQ;;;;mBAQY,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAiD5B,QAAQ;;;;2BAmCoB;;;;;iCAiBI;;;;;;qBA6EV;;;;;+BAUU;;;;;;;;cAQvB;;;;;;;;;;;;;;;0BA2BkB;;;;;;;;2CAkBiB;;;;;kCAkBT,QAAQ;;;;;;;;;;;;;;wCAuBF;;;;oCAgBJ"}