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

package/docs/browser.md

@@ -34,6 +34,40 @@ function Chat() {
 
 That's it! The hook handles model loading, streaming, and state management.
 
+## Model Preloading
+
+Download models during app initialization so they're ready when users need them:
+
+```typescript
+import { 
+  preloadChatModel,
+  preloadEmbeddingModel,
+  preloadTTSModel,
+  preloadSTTModel 
+} from "@tryhamster/gerbil/browser";
+
+// During app initialization
+async function initApp() {
+  // Preload LLM
+  await preloadChatModel("qwen3-0.6b", {
+    onProgress: (p) => {
+      if (p.status === "downloading") {
+        console.log(`Downloading ${p.file}: ${p.progress}%`);
+      }
+    },
+  });
+
+  // Preload other models as needed
+  await preloadEmbeddingModel("Xenova/all-MiniLM-L6-v2");
+  await preloadTTSModel("kokoro-82m");
+  await preloadSTTModel("whisper-tiny.en");
+}
+
+initApp();
+```
+
+After preloading, hooks like `useChat` will load instantly from IndexedDB cache.
+
 ## React Hooks
 
 ### `useChat`
@@ -456,6 +490,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tryhamster/gerbil",
-  "version": "1.0.0-rc.11",
+  "version": "1.0.0-rc.13",
   "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 };