@tryhamster/gerbil 1.0.0-rc.0

package/docs/browser.md

@@ -0,0 +1,328 @@
+# Browser Usage
+
+Run LLMs directly in the browser with WebGPU acceleration. No server required.
+
+## Quick Start (React)
+
+```tsx
+import { useChat } from "@tryhamster/gerbil/browser";
+
+function Chat() {
+  const { messages, input, setInput, handleSubmit, isLoading, isGenerating } = useChat();
+
+  if (isLoading) return <div>Loading model...</div>;
+
+  return (
+    <div>
+      {messages.map(m => (
+        <div key={m.id}>
+          <strong>{m.role}:</strong> {m.content}
+        </div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input 
+          value={input} 
+          onChange={e => setInput(e.target.value)}
+          placeholder="Say something..."
+        />
+        <button disabled={isGenerating}>Send</button>
+      </form>
+    </div>
+  );
+}
+```
+
+That's it! The hook handles model loading, streaming, and state management.
+
+## React Hooks
+
+### `useChat`
+
+Full-featured chat hook with message history, streaming, and thinking mode.
+
+```tsx
+import { useChat } from "@tryhamster/gerbil/browser";
+
+function Chat() {
+  const {
+    messages,        // Message[] - chat history
+    input,           // string - current input
+    setInput,        // (value: string) => void
+    handleSubmit,    // (e?) => void - submit handler
+    isLoading,       // boolean - model loading
+    loadingProgress, // { status, file?, progress?, downloadCount? }
+    isGenerating,    // boolean - generating response
+    thinking,        // string - current thinking (streaming)
+    stop,            // () => void - stop generation
+    clear,           // () => void - clear messages
+    tps,             // number - tokens per second
+    isReady,         // boolean - model ready
+    error,           // string | null
+    load,            // () => void - manually load model
+  } = useChat({
+    model: "qwen3-0.6b",     // Model ID
+    system: "You are helpful.", // System prompt
+    thinking: true,          // Enable thinking mode
+    maxTokens: 512,          // Max tokens per response
+    temperature: 0.7,        // Sampling temperature
+    autoLoad: false,         // Auto-load on mount (default: false)
+  });
+}
+```
+
+#### Message Type
+
+```typescript
+interface Message {
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+  thinking?: string;  // Thinking content (if enabled)
+}
+```
+
+#### Auto-Loading Behavior
+
+By default, hooks **don't** auto-load on mount (to avoid unexpected downloads). The model loads when:
+1. You call `handleSubmit()` / `complete()` - triggers load automatically
+2. You call `load()` manually
+3. You set `autoLoad: true` - loads on mount
+
+```tsx
+// Default: loads when user submits first message
+function Chat() {
+  const { handleSubmit, isLoading } = useChat();
+  // Model loads on first handleSubmit()
+}
+
+// Explicit preload on mount
+function ChatPreloaded() {
+  const { handleSubmit, isLoading } = useChat({ autoLoad: true });
+  // Model starts loading immediately
+}
+
+// Manual load control
+function ChatManual() {
+  const { load, isLoading, isReady } = useChat();
+  return <button onClick={load} disabled={isLoading || isReady}>Load Model</button>;
+}
+```
+
+#### With Thinking Mode
+
+```tsx
+function ChatWithThinking() {
+  const { messages, input, setInput, handleSubmit, isLoading } = useChat({
+    thinking: true,
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {messages.map(m => (
+        <div key={m.id}>
+          {m.thinking && (
+            <details>
+              <summary>Thinking...</summary>
+              <pre>{m.thinking}</pre>
+            </details>
+          )}
+          <p>{m.content}</p>
+        </div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={e => setInput(e.target.value)} />
+      </form>
+    </div>
+  );
+}
+```
+
+#### With Loading Progress
+
+The `loadingProgress` object tells you what's happening:
+
+- `status: "loading"` - Initial load / compiling shaders
+- `status: "downloading"` - Downloading model files from network
+- `status: "ready"` - Model ready
+
+When loading from **cache**, you'll only see `"loading"` → `"ready"` (no `"downloading"`).
+When **downloading**, you'll see `"downloading"` with progress info.
+
+```tsx
+function ChatWithProgress() {
+  const { messages, handleSubmit, isLoading, loadingProgress } = useChat();
+
+  if (isLoading) {
+    const p = loadingProgress;
+    
+    if (p?.status === "downloading") {
+      // Downloading from network - show progress
+      return <div>Downloading {p.file}: {p.progress}%</div>;
+    }
+    
+    // Loading from cache or compiling shaders
+    return <div>{p?.message || "Loading model..."}</div>;
+  }
+
+  // ... rest of chat UI
+}
+```
+
+### `useCompletion`
+
+Simple completion hook for one-off generations.
+
+```tsx
+import { useCompletion } from "@tryhamster/gerbil/browser";
+
+function App() {
+  const { complete, completion, isLoading, isGenerating, tps } = useCompletion();
+
+  if (isLoading) return <div>Loading model...</div>;
+
+  return (
+    <div>
+      <button 
+        onClick={() => complete("Write a haiku about coding")}
+        disabled={isGenerating}
+      >
+        Generate
+      </button>
+      <p>{completion}</p>
+      {isGenerating && <span>{tps.toFixed(0)} tok/s</span>}
+    </div>
+  );
+}
+```
+
+#### API
+
+```typescript
+const {
+  completion,      // string - generated text
+  thinking,        // string - thinking content
+  complete,        // (prompt: string) => Promise<string>
+  isLoading,       // boolean - model loading
+  loadingProgress, // { status, file?, progress? }
+  isGenerating,    // boolean - generating
+  stop,            // () => void - stop generation
+  tps,             // number - tokens per second
+  isReady,         // boolean - model ready
+  error,           // string | null
+} = useCompletion({
+  model: "qwen3-0.6b",
+  thinking: false,
+  maxTokens: 512,
+});
+```
+
+## Low-Level API
+
+For full control, use `createGerbilWorker` directly:
+
+```typescript
+import { createGerbilWorker, isWebGPUSupported } from "@tryhamster/gerbil/browser";
+
+if (!isWebGPUSupported()) {
+  console.log("WebGPU not supported");
+  return;
+}
+
+const gerbil = await createGerbilWorker({
+  modelId: "qwen3-0.6b",
+  onProgress: (p) => console.log(p.status),
+  onToken: (token) => console.log(token.text),
+  onComplete: (result) => console.log(`${result.tps} tok/s`),
+});
+
+await gerbil.generate("Hello!", { thinking: true });
+gerbil.terminate();
+```
+
+### `createGerbilWorker(options)`
+
+```typescript
+interface GerbilWorkerOptions {
+  modelId?: string;                           // Default: "qwen3-0.6b"
+  onProgress?: (progress: WorkerProgress) => void;
+  onToken?: (token: WorkerToken) => void;
+  onComplete?: (result: WorkerComplete) => void;
+  onError?: (error: string) => void;
+}
+
+interface GerbilWorker {
+  generate: (prompt: string, options?: GenerateOptions) => Promise<string>;
+  interrupt: () => void;
+  reset: () => void;
+  terminate: () => void;
+  isReady: () => boolean;
+}
+```
+
+### Generation Options
+
+```typescript
+interface GenerateOptions {
+  maxTokens?: number;    // Default: 256
+  temperature?: number;  // Default: 0.7
+  topP?: number;         // Default: 0.9
+  topK?: number;         // Default: 20
+  thinking?: boolean;    // Enable thinking mode
+  system?: string;       // System prompt
+}
+```
+
+## Utilities
+
+### `isWebGPUSupported()`
+
+```typescript
+import { isWebGPUSupported } from "@tryhamster/gerbil/browser";
+
+if (!isWebGPUSupported()) {
+  // Show fallback or error
+}
+```
+
+### `getWebGPUInfo()`
+
+```typescript
+import { getWebGPUInfo } from "@tryhamster/gerbil/browser";
+
+const info = await getWebGPUInfo();
+// { supported: true, adapter: "Apple", device: "Apple M4 Max" }
+```
+
+## Models
+
+| Model | Size | Best For |
+|-------|------|----------|
+| `qwen3-0.6b` | ~400MB | General use, thinking mode |
+| `smollm2-360m` | ~250MB | Faster, smaller |
+| `smollm2-135m` | ~100MB | Fastest, basic tasks |
+
+Models are cached in IndexedDB after first download.
+
+## Browser Support
+
+- **Chrome/Edge 113+** — Full WebGPU support
+- **Safari 18+** — WebGPU support (may have quirks)
+- **Firefox** — WebGPU behind flag, not recommended
+
+## Troubleshooting
+
+### "WebGPU not supported"
+
+- Update to Chrome/Edge 113+
+- Check `chrome://gpu` for WebGPU status
+- Try `chrome://flags/#enable-unsafe-webgpu`
+
+### Slow first load
+
+First load downloads the model (~400MB for qwen3-0.6b) and compiles WebGPU shaders. Subsequent loads use IndexedDB cache (~2-5s).
+
+### Out of memory
+
+Use smaller models like `smollm2-135m`. Close other GPU-intensive tabs.

package/docs/cli.md

@@ -0,0 +1,155 @@
+# Gerbil CLI
+
+## Quick Start
+
+```bash
+# Without installing (one-off usage)
+npx @tryhamster/gerbil              # Opens interactive REPL (default)
+npx @tryhamster/gerbil "Your prompt"  # Quick text generation
+
+# After installing globally
+npm install -g @tryhamster/gerbil
+gerbil                              # Opens interactive REPL
+gerbil "Your prompt"                 # Quick text generation
+```
+
+> All examples below use `gerbil` (assumes global install). If using `npx`, replace `gerbil` with `npx @tryhamster/gerbil`.
+
+## Generate Text
+
+```bash
+gerbil "Write a haiku about code"
+gerbil "Explain monads" --thinking
+gerbil "Hello" -m qwen3-0.6b --stream
+```
+
+Options:
+- `-m, --model <id>` - Model to use (default: qwen3-0.6b)
+- `-n, --max-tokens <n>` - Max tokens (default: 256)
+- `-t, --temperature <t>` - Temperature (default: 0.7)
+- `-s, --system <text>` - System prompt
+- `--thinking` - Enable thinking mode
+- `--stream` - Stream output
+- `--json` - Output as JSON
+
+## Skills
+
+```bash
+gerbil commit                      # Commit message from staged changes
+gerbil commit --type conventional  # Conventional commit format
+gerbil commit --write              # Write to .git/COMMIT_EDITMSG
+
+gerbil summarize README.md         # Summarize file
+gerbil summarize README.md -l short
+
+gerbil explain src/index.ts        # Explain code
+gerbil explain src/index.ts -l beginner
+
+gerbil review src/                 # Code review
+gerbil review src/ -f security,performance
+```
+
+## Interactive REPL
+
+```bash
+gerbil              # Opens REPL (or just run 'gerbil' with no args)
+gerbil repl         # Same as above
+gerbil repl --gpu   # Force WebGPU mode
+gerbil repl --cpu   # Force CPU mode
+```
+
+Launches the interactive terminal dashboard with:
+- Chat with multiple modes (Assistant, Coder, Teacher, Agent)
+- Skills execution and creation
+- Model management
+- Benchmark testing (compare CPU vs GPU performance)
+- Server management
+
+### REPL Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `t` | Toggle thinking mode (Qwen3) |
+| `a` | Toggle agent mode (tool calling) |
+| `m` | Switch between CPU and GPU mode |
+| `q` | Quit |
+| `1-8` | Jump to menu item |
+
+## Chat
+
+Opens the REPL directly in chat view:
+
+```bash
+gerbil chat
+gerbil chat --gpu    # Chat with WebGPU acceleration
+```
+
+This is equivalent to `gerbil` (or `gerbil repl`) and then pressing `1` for Chat.
+
+## Server
+
+```bash
+gerbil serve                       # HTTP server on :3000
+gerbil serve -p 8080               # Custom port
+gerbil serve --mcp                 # MCP server (stdio)
+```
+
+HTTP endpoints:
+- `POST /generate` - Generate text
+- `GET /info` - Server info
+
+## Model Management
+
+```bash
+gerbil models                      # List built-in models
+gerbil models --search "code"      # Search models
+gerbil info                        # System info
+gerbil info -m qwen3-0.6b          # Model info
+```
+
+## Updates
+
+Gerbil checks for updates automatically but **never installs without your permission**.
+
+```bash
+gerbil update                      # Check and install updates
+```
+
+### Update Notifications
+
+After running any command, you'll see:
+
+```
+💡 Update available: v1.0.0 → v1.0.1
+   Run 'gerbil update' to install
+```
+
+### In REPL
+
+When using the REPL, updates appear in the header:
+
+```
+gerbil 1.0.0 / Chat  |  Update v1.0.1 → Press u to update
+```
+
+Press **`u`** to install the update.
+
+## Use Any Model
+
+```bash
+gerbil -m hf:microsoft/Phi-3-mini "Hello"
+gerbil -m hf:Qwen/Qwen2.5-Coder-0.5B "Write a function"
+```
+
+## CI/CD Integration
+
+```yaml
+# .github/workflows/commit.yml
+- name: Generate Commit Message
+  run: npx @tryhamster/gerbil commit --write
+```
+
+Pre-commit hook:
+```bash
+npx husky add .husky/prepare-commit-msg "npx @tryhamster/gerbil commit --write"
+```

package/docs/frameworks.md

@@ -0,0 +1,90 @@
+# Framework Integrations
+
+## Next.js
+
+```typescript
+// app/api/chat/route.ts
+import { gerbil } from "@tryhamster/gerbil/next";
+
+export const POST = gerbil.handler({ model: "qwen3-0.6b" });
+```
+
+## Express
+
+```typescript
+import express from "express";
+import { gerbil } from "@tryhamster/gerbil/express";
+
+const app = express();
+app.use("/ai", gerbil());
+
+// Endpoints:
+// POST /ai/generate
+// POST /ai/stream
+// POST /ai/json
+// POST /ai/embed
+```
+
+## React Hooks
+
+```typescript
+import { useGerbil, useChat } from "@tryhamster/gerbil/react";
+
+function Chat() {
+  const { generate, isLoading } = useGerbil();
+  
+  const handleSubmit = async (prompt: string) => {
+    const result = await generate(prompt);
+  };
+}
+```
+
+## Fastify
+
+```typescript
+import Fastify from "fastify";
+import { gerbilPlugin } from "@tryhamster/gerbil/fastify";
+
+const app = Fastify();
+app.register(gerbilPlugin, { prefix: "/ai" });
+```
+
+## Hono
+
+```typescript
+import { Hono } from "hono";
+import { gerbil } from "@tryhamster/gerbil/hono";
+
+const app = new Hono();
+app.route("/ai", gerbil());
+```
+
+## tRPC
+
+```typescript
+import { gerbilRouter } from "@tryhamster/gerbil/trpc";
+
+const appRouter = t.router({
+  ai: gerbilRouter(t),
+});
+```
+
+## LangChain
+
+```typescript
+import { GerbilLLM, GerbilEmbeddings } from "@tryhamster/gerbil/langchain";
+
+const llm = new GerbilLLM({ model: "qwen3-0.6b" });
+const embeddings = new GerbilEmbeddings();
+
+// Use with chains
+const chain = new LLMChain({ llm, prompt: template });
+```
+
+## LlamaIndex
+
+```typescript
+import { GerbilLLM } from "@tryhamster/gerbil/llamaindex";
+
+const llm = new GerbilLLM({ model: "qwen3-0.6b" });
+```