@tryhamster/gerbil 1.0.0 → 1.0.2

package/README.md

@@ -9,14 +9,15 @@
 </p>
 
 <p align="center">
+  <a href="https://gerbilsdk.com"><strong>gerbilsdk.com</strong></a> •
   <a href="#install">Install</a> •
   <a href="#native-webgpu-engine">Engine</a> •
   <a href="#react-quickstart">React</a> •
   <a href="#embeddings">Embeddings</a> •
   <a href="#vision">Vision</a> •
   <a href="#speech">Speech</a> •
-  <a href="./docs/ai-sdk.md">AI SDK</a> •
-  <a href="./docs/cli.md">CLI</a>
+  <a href="https://gerbilsdk.com/docs/frameworks/ai-sdk">AI SDK</a> •
+  <a href="https://gerbilsdk.com/docs/cli">CLI</a>
 </p>
 
 <p align="center">
@@ -43,13 +44,14 @@ const engine = await WebGPUEngine.create({ repo: "mlx-community/Qwen3.5-0.8B-4bi
 const { text } = await engine.generate("Explain recursion in one sentence");
 ```
 
-> **Pre-1.0.** Gerbil is a release-candidate (`1.0.0-rc.26`, changeset pre-release). The
-> native engine surface below is the path going forward; APIs may still shift before 1.0.
+> **📚 Full docs → [gerbilsdk.com/docs](https://gerbilsdk.com/docs)** · live playground & demos at **[gerbilsdk.com](https://gerbilsdk.com)**
 
 ## Why Gerbil?
 
 - **One native engine** — a from-scratch WebGPU/WGSL engine, pure compute shaders, nothing
   extra to ship.
+- **~90 KB gzipped** — the _entire_ multimodal engine. No heavyweight ML runtime; model
+  weights stream from the HuggingFace Hub at run time.
 - **Multimodal, all native** — text, vision (image→text), embeddings, and speech run on the
   same engine, loading safetensors directly from the HuggingFace Hub.
 - **Browser & Node** — Chrome 113+, Safari 26+ (iOS 26+), Firefox 141+, and Node via Dawn
@@ -137,6 +139,20 @@ function Chat() {
 The same hook exposes `describeImage` (vision), `embed`/`similarity` (embeddings), `stop`,
 and `dispose`. Pass `enableVision: true` or `embedding: true` to load those modalities.
 
+**Gate your app behind the download.** Wrap your app in `<GerbilGate>` to show a splash
+until the engine is ready — and keep it warm across navigation (no GPU re-upload):
+
+```tsx
+import { GerbilGate } from "@tryhamster/gerbil/gpu/hooks";
+
+<GerbilGate
+  model="mlx-community/Qwen3.5-0.8B-4bit"
+  fallback={({ progress }) => <Splash percent={progress} />}
+>
+  <App />
+</GerbilGate>;
+```
+
 ## Structured Output
 
 `generateObject` makes the model return a JSON object: it generates, extracts the JSON,
@@ -209,7 +225,7 @@ const doc = await engine.embed("Paris is the capital of France", { taskType: "do
 const sim = query.reduce((s, v, i) => s + v * doc[i], 0);
 ```
 
-📖 **[Full Embeddings Documentation →](./docs/embeddings.md)**
+📖 **[Full Embeddings Documentation →](https://gerbilsdk.com/docs)**
 
 ## Vision
 
@@ -230,7 +246,7 @@ const { text } = await engine.describeImage(
 );
 ```
 
-📖 **[Full Vision Documentation →](./docs/vision.md)**
+📖 **[Full Vision Documentation →](https://gerbilsdk.com/docs/vision)**
 
 ## Speech
 
@@ -249,10 +265,13 @@ via the dedicated `MoonshineSTT` class.
 import { MoonshineSTT } from "@tryhamster/gerbil/gpu";
 
 const stt = await MoonshineSTT.create({ repo: "UsefulSensors/moonshine-base" });
-const { text } = await stt.transcribe(pcm16kMono); // Float32Array @ 16 kHz
+const { text, noSpeech } = await stt.transcribe(pcm16kMono); // noSpeech flags silence
 ```
 
-📖 **[Full TTS Documentation →](./docs/tts.md)** · **[Full STT Documentation →](./docs/stt.md)**
+`transcribe` returns `noSpeech` (RMS VAD + min-duration + marker denylist) so you can skip
+silent/empty clips; `useSTT` surfaces it too, with an `onNoSpeech` callback.
+
+📖 **[Full TTS Documentation →](https://gerbilsdk.com/docs/tts)** · **[Full STT Documentation →](https://gerbilsdk.com/docs/stt)**
 
 ## Skills
 
@@ -286,7 +305,7 @@ await loadSkills("./skills");  // loads *.skill.ts
 const skill = useSkill("my-skill");
 ```
 
-📖 **[Full Skills Documentation →](./docs/skills.md)**
+📖 **[Full Skills Documentation →](https://gerbilsdk.com/docs/skills)**
 
 ## Tools & Agents
 
@@ -303,6 +322,27 @@ const weatherTool = defineTool({
 });
 ```
 
+**Agentic loop, on-device.** `engine.generateWithTools` (and the `useAgent` React hook)
+run the whole loop — generate → call a tool → feed the result back → repeat — and return a
+step trace for UIs:
+
+```tsx
+import { useAgent } from "@tryhamster/gerbil/gpu/hooks";
+
+const { run, steps, answer, isRunning } = useAgent({
+  model: "mlx-community/Qwen3.5-0.8B-4bit",
+  tools: [
+    {
+      name: "get_weather",
+      description: "Get the weather for a city",
+      parameters: { city: "string" },
+      execute: ({ city }) => `Weather in ${city}: 72°F, sunny`,
+    },
+  ],
+});
+await run("What's the weather in Paris?"); // steps[]: tool_call → tool_result → answer
+```
+
 **Built-in tools:**
 - `gerbil_docs` — Search Gerbil documentation
 - `run_skill` — Execute any Gerbil skill
@@ -316,7 +356,28 @@ npx @tryhamster/gerbil repl
 # Gerbil will call the docs tool and synthesize an answer
 ```
 
-📖 **[Full Tools Documentation →](./docs/tools.md)**
+📖 **[Full Tools Documentation →](https://gerbilsdk.com/docs/tools)**
+
+## Autocomplete & Rewrite
+
+Inline autocomplete — `engine.autocomplete(prefix)` and the debounced `useAutocomplete`
+hook return a brief single-line continuation (low-latency defaults + cleanup):
+
+```tsx
+import { useAutocomplete } from "@tryhamster/gerbil/gpu/hooks";
+
+const { suggestion, onInput, accept, dismiss } = useAutocomplete({
+  model: "mlx-community/Qwen3.5-0.8B-4bit",
+});
+// <input onChange={(e) => onInput(e.target.value)} /> — render `suggestion` as ghost text;
+// Tab → accept(), Esc → dismiss()
+```
+
+Tone rewrite — `engine.rewrite(text, { tone })` (and `useEngine().rewrite`) re-generates
+text in a target tone (`"professional"`, `"friendly"`, `"concise"`, `"playful"`,
+`"pirate"`) or with free-form `instructions`.
+
+📖 **[Full Autocomplete Documentation →](https://gerbilsdk.com/docs/autocomplete)**
 
 ## CLI
 
@@ -339,7 +400,7 @@ gerbil update                                 # Update to latest version
 
 > **Updates**: Gerbil checks for updates but never installs without permission. Press `u` in REPL or run `gerbil update`.
 
-📖 **[Full CLI Documentation →](./docs/cli.md)**
+📖 **[Full CLI Documentation →](https://gerbilsdk.com/docs/cli)**
 
 ## Browser Usage
 
@@ -363,22 +424,22 @@ function Chat() {
 }
 ```
 
-`@tryhamster/gerbil/browser` still exports the device/WebGPU utilities
+`@tryhamster/gerbil/browser` exports the device & storage utilities
 (`isModelSafeForDevice`, `detectMemoryCrash`, `downloadModelChunked`,
-`checkWebGPUCapabilities`, `getBrowserDiagnostics`, …).
+`getRecommendedModels`, `requestPersistentStorage`, …).
 
-📖 **[Full Browser Documentation →](./docs/browser.md)**
+📖 **[Full Browser Documentation →](https://gerbilsdk.com/docs/browser)**
 
 ## Integrations
 
 | Integration | Import | Docs |
 |-------------|--------|------|
-| **Browser** | `@tryhamster/gerbil/browser` | [📖 Browser](./docs/browser.md) |
-| **AI SDK v5** | `@tryhamster/gerbil/ai` | [📖 AI SDK](./docs/ai-sdk.md) |
-| **Next.js** | `@tryhamster/gerbil/next` | [📖 Frameworks](./docs/frameworks.md) |
-| **Express** | `@tryhamster/gerbil/express` | [📖 Frameworks](./docs/frameworks.md) |
-| **LangChain** | `@tryhamster/gerbil/langchain` | [📖 Frameworks](./docs/frameworks.md) |
-| **MCP Server** | `npx @tryhamster/gerbil serve --mcp` | [📖 MCP](./docs/mcp.md) |
+| **Browser** | `@tryhamster/gerbil/browser` | [📖 Browser](https://gerbilsdk.com/docs/browser) |
+| **AI SDK v5** | `@tryhamster/gerbil/ai` | [📖 AI SDK](https://gerbilsdk.com/docs/frameworks/ai-sdk) |
+| **Next.js** | `@tryhamster/gerbil/next` | [📖 Next.js](https://gerbilsdk.com/docs/frameworks/nextjs) |
+| **Express** | `@tryhamster/gerbil/express` | [📖 Express](https://gerbilsdk.com/docs/frameworks/express) |
+| **LangChain** | `@tryhamster/gerbil/langchain` | [📖 LangChain](https://gerbilsdk.com/docs/frameworks/langchain) |
+| **MCP Server** | `npx @tryhamster/gerbil serve --mcp` | [📖 MCP](https://gerbilsdk.com/docs/mcp) |
 
 **Native engine:** `import { WebGPUEngine } from "@tryhamster/gerbil/gpu"` (or `useEngine` from `@tryhamster/gerbil/gpu/hooks` for React) is the primary surface for text, vision, embeddings, and speech.
 
@@ -444,22 +505,26 @@ HiFi-GAN (NanoCodec decoder), and more.
 
 ## Documentation
 
+Full documentation, guides, and a live playground live at **[gerbilsdk.com/docs](https://gerbilsdk.com/docs)**.
+
 | Guide | Description |
 |-------|-------------|
-| [📖 Structured Output](./docs/structured-output.md) | `generateObject` / `useObject` — validated JSON with retries |
-| [📖 Embeddings](./docs/embeddings.md) | EmbeddingGemma semantic search, similarity, RAG |
-| [📖 Vision](./docs/vision.md) | Image → text with Qwen3.5 ViT & Gemma 4 ViT |
-| [📖 Text-to-Speech](./docs/tts.md) | Native Kani-TTS-2 (`engine.speak()`) |
-| [📖 Speech-to-Text](./docs/stt.md) | Native Moonshine (`MoonshineSTT`) |
-| [📖 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, 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 |
-| [📖 MCP Client](./docs/mcp-client.md) | Connect to external MCP servers |
+| [📖 Getting Started](https://gerbilsdk.com/docs/getting-started) | Install, load a model, core concepts |
+| [📖 Structured Output](https://gerbilsdk.com/docs) | `generateObject` / `useObject` — validated JSON with retries |
+| [📖 Embeddings](https://gerbilsdk.com/docs) | EmbeddingGemma semantic search, similarity, RAG |
+| [📖 Vision](https://gerbilsdk.com/docs/vision) | Image → text with Qwen3.5 ViT & Gemma 4 ViT |
+| [📖 Text-to-Speech](https://gerbilsdk.com/docs/tts) | Native Kani-TTS-2 (`engine.speak()`) |
+| [📖 Speech-to-Text](https://gerbilsdk.com/docs/stt) | Native Moonshine (`MoonshineSTT`) |
+| [📖 Browser](https://gerbilsdk.com/docs/browser) | WebGPU inference, React hooks |
+| [📖 Hooks](https://gerbilsdk.com/docs/hooks) | `useEngine` / `useObject` / `useTTS` / `useSTT` |
+| [📖 Skills](https://gerbilsdk.com/docs/skills) | Built-in skills, custom skill development |
+| [📖 Tools](https://gerbilsdk.com/docs/tools) | Tool calling, agentic workflows |
+| [📖 REPL](https://gerbilsdk.com/docs/repl) | Interactive terminal dashboard |
+| [📖 AI SDK](https://gerbilsdk.com/docs/frameworks/ai-sdk) | Vercel AI SDK v5 (LLM, TTS, STT, Embeddings) |
+| [📖 Frameworks](https://gerbilsdk.com/docs/frameworks) | Next.js, Express, React, LangChain |
+| [📖 CLI](https://gerbilsdk.com/docs/cli) | All CLI commands and options |
+| [📖 Mobile](https://gerbilsdk.com/docs/mobile) | iOS / iPadOS guidance & memory guards |
+| [📖 MCP](https://gerbilsdk.com/docs/mcp) | MCP server for Claude Desktop & Cursor |
 
 ## Requirements
 

package/dist/browser/index.d.ts

@@ -41,8 +41,12 @@ type GenerateOptions = {
   system?: string;
   /** Enable thinking/reasoning mode (Qwen3) */
   thinking?: boolean;
-  /** Callback for each token (streaming) */
-  onToken?: (token: string) => void;
+  /** Callback for each token (streaming); `meta` carries live decode-only tok/s */
+  onToken?: (token: string, meta?: {
+    tokenIndex: number;
+    tps: number;
+    elapsedMs: number;
+  }) => void;
   /** Images to include (only used if model supports vision) */
   images?: ImageInput[];
   /** Enable response caching (default: false) */
@@ -581,6 +585,12 @@ declare const MODEL_SIZES: Record<string, number>;
  */
 declare function isModelSafeForDevice(modelId: string): {
   safe: boolean;
+  /**
+   * Borderline: may run on the newest hardware but is prone to OOM. Reported
+   * unsafe (`safe: false`) so callers block by default; a UI can use `risky` to
+   * offer an explicit "load anyway" on capable devices.
+   */
+  risky: boolean;
   reason: string;
   recommendation?: string;
   maxSafeModel?: string;

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/pwa.ts","../../src/browser/audio.ts","../../src/browser/device-guards.ts","../../src/browser/download.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/pwa.ts","../../src/browser/audio.ts","../../src/browser/device-guards.ts","../../src/browser/download.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/browser/index.js

@@ -280,8 +280,8 @@ function normalizeId(modelId) {
 * - blocked: too large for the WKWebView memory ceiling on iPhone — will crash.
 *   gemma-4-e2b (~3.6GB) plus any vision checkpoint (the vision encoder pushes
 *   the working set well past what an iPhone can hold).
-* - risky: borderline on iPhone — Qwen3.5-2B (~1.7GB) fits on newer devices but
-*   warns and can OOM on older ones.
+* - risky: Qwen3.5-2B (~1.7GB) OOM-crashes iPhone WKWebView in practice — now
+*   treated as unsafe to auto-load (flagged `risky` so a UI can offer to force it).
 * - everything else (Qwen3.5-0.8B ~0.65GB, LFM2.5-350M) is allowed everywhere.
 */
 const IOS_MODEL_LIMITS = {
@@ -314,41 +314,48 @@ function isModelSafeForDevice(modelId) {
 	if (isIPhone) {
 		if (isBlocked) return {
 			safe: false,
+			risky: false,
 			reason: `Model ${modelId} will crash on iPhone${isIOSChrome ? " (iOS Chrome uses WKWebView, same limits as Safari)" : ""}. ${isVision ? "Vision checkpoints need a separate image encoder in memory" : "It is too large (~3.6GB)"}, which exceeds the WKWebView memory ceiling.`,
 			recommendation: `Use ${SAFE_MOBILE_CHAT} (Qwen3.5-0.8B) on iPhone, or run larger models on desktop.`,
 			maxSafeModel: SAFE_MOBILE_CHAT
 		};
 		if (isRisky) return {
-			safe: true,
-			reason: `Model ${modelId} (~1.7GB) is borderline on iPhone and may run out of memory on older devices.`,
-			recommendation: `If it crashes, fall back to ${SAFE_MOBILE_CHAT} (Qwen3.5-0.8B).`,
+			safe: false,
+			risky: true,
+			reason: `Model ${modelId} (~1.7GB) exceeds the iPhone WKWebView memory budget and is likely to crash.`,
+			recommendation: `Use ${SAFE_MOBILE_CHAT} (Qwen3.5-0.8B) on iPhone; run Qwen3.5-2B on iPad or desktop.`,
 			maxSafeModel: SAFE_MOBILE_CHAT
 		};
 		return {
 			safe: true,
+			risky: false,
 			reason: "Model is within iPhone memory limits."
 		};
 	}
 	if (isIPad) {
 		if (isBlocked) return {
 			safe: false,
+			risky: false,
 			reason: `Model ${modelId} may crash on iPad. ${isVision ? "Vision checkpoints need a separate image encoder in memory" : "It is too large (~3.6GB)"}, which can exceed the WKWebView memory ceiling.`,
 			recommendation: `Use ${SAFE_MOBILE_CHAT} (Qwen3.5-0.8B) or Qwen3.5-2B on iPad.`,
 			maxSafeModel: "mlx-community/Qwen3.5-2B-4bit"
 		};
 		return {
 			safe: true,
+			risky: false,
 			reason: "Model is within iPad memory limits."
 		};
 	}
 	if (/Android/.test(ua) && isBlocked) return {
 		safe: false,
+		risky: false,
 		reason: `Model ${modelId} is very large and may crash on Android devices.`,
 		recommendation: `Use ${SAFE_MOBILE_CHAT} (Qwen3.5-0.8B) or Qwen3.5-2B on Android.`,
 		maxSafeModel: "mlx-community/Qwen3.5-2B-4bit"
 	};
 	return {
 		safe: true,
+		risky: false,
 		reason: "Desktop browser has sufficient memory."
 	};
 }