@tryhamster/gerbil 1.0.0-rc.2 → 1.0.0-rc.21

package/README.md

@@ -11,8 +11,10 @@
 <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> •
   <a href="./docs/ai-sdk.md">AI SDK</a> •
   <a href="./docs/cli.md">CLI</a>
 </p>
@@ -45,7 +47,9 @@ 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
-- **Complete Audio** — Text-to-Speech (Kokoro) & Speech-to-Text (Whisper)
+- **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
 - **Skills System** — Built-in + custom skills with Zod validation
 - **Tool Calling** — Agentic capabilities with Qwen3 models
@@ -65,6 +69,30 @@ npm install @tryhamster/gerbil
 
 After global install, use `gerbil` directly instead of `npx @tryhamster/gerbil`.
 
+## Model Preloading
+
+Download models ahead of time so users don't wait:
+
+```typescript
+import { Gerbil } from "@tryhamster/gerbil";
+
+const g = new Gerbil();
+
+// Option 1: Preload for later (download only, free memory)
+await g.preloadModel("qwen3-0.6b", {
+  onProgress: (p) => console.log(p.status, p.progress),
+});
+// Later: loads from disk cache (fast, no network)
+await g.loadModel("qwen3-0.6b");
+
+// Option 2: Preload and keep in memory (instant use)
+await g.preloadModel("qwen3-0.6b", { keepLoaded: true });
+// Instant - no loading needed
+await g.generate("Hello");
+```
+
+Works for all model types: `preloadTTS()`, `preloadSTT()`, `preloadEmbedding()`.
+
 ## Quick Start
 
 ```typescript
@@ -93,6 +121,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):
@@ -272,8 +324,12 @@ function Chat() {
 | Model | Size | Best For |
 |-------|------|----------|
 | `qwen3-0.6b` | ~400MB | General use, reasoning (thinking mode) |
+| `qwen2.5-0.5b` | ~350MB | Fast and capable |
 | `qwen2.5-coder-0.5b` | ~400MB | Code generation |
-| `smollm2-135m` | ~100MB | Quick completions |
+| `smollm2-360m` | ~250MB | Fast, simple tasks |
+| `smollm2-135m` | ~100MB | Fastest, basic |
+| `phi-3-mini` | ~2.1GB | High quality |
+| `ministral-3b` | ~2.5GB | **Vision** + reasoning, 256k context |
 
 Use any HuggingFace model: `npx @tryhamster/gerbil -m hf:org/model "prompt"`
 
@@ -281,22 +337,26 @@ Use any HuggingFace model: `npx @tryhamster/gerbil -m hf:org/model "prompt"`
 
 | Model | Type | Size | Notes |
 |-------|------|------|-------|
-| `kokoro-82m` | TTS | ~330MB | 28 voices, English |
+| `kokoro-82m` | TTS | ~330MB | 28 voices, English (default) |
+| `supertonic-66m` | TTS | ~250MB | 4 voices, 44.1kHz, faster |
 | `whisper-tiny.en` | STT | 39MB | English, fastest |
 | `whisper-base.en` | STT | 74MB | English, balanced |
-| `whisper-small` | STT | 244MB | 80+ languages |
+| `whisper-small` | STT | 244MB | Multilingual, 80+ languages |
+| `whisper-large-v3-turbo` | STT | 809MB | Best quality, 5.4x faster than v3 |
 
 ## Documentation
 
 | Guide | Description |
 |-------|-------------|
-| [📖 Text-to-Speech](./docs/tts.md) | Kokoro TTS, 28 voices, streaming audio |
+| [📖 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 |
 | [📖 Browser](./docs/browser.md) | WebGPU inference, React hooks |
 | [📖 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 |