@tryhamster/gerbil 1.0.0-rc.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Wheel Go Fast.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

package/README.md

@@ -0,0 +1,253 @@
+<p align="center">
+  <img src="https://em-content.zobj.net/source/twitter/408/hamster_1f439.png" width="80" />
+</p>
+
+<h1 align="center">Gerbil</h1>
+
+<p align="center">
+  <strong>Local LLM inference for Node.js. GPU-accelerated. Zero config.</strong>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#skills">Skills</a> •
+  <a href="./docs/ai-sdk.md">AI SDK</a> •
+  <a href="./docs/frameworks.md">Frameworks</a> •
+  <a href="./docs/cli.md">CLI</a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/@tryhamster/gerbil?style=flat-square" alt="npm version" />
+  <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="license" />
+  <img src="https://img.shields.io/badge/node-%3E%3D18-green?style=flat-square" alt="node version" />
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/AI_SDK-black?style=flat-square&logo=vercel" alt="AI SDK" />
+  <img src="https://img.shields.io/badge/Next.js-black?style=flat-square&logo=next.js" alt="Next.js" />
+  <img src="https://img.shields.io/badge/Express-black?style=flat-square&logo=express" alt="Express" />
+  <img src="https://img.shields.io/badge/React-black?style=flat-square&logo=react" alt="React" />
+  <img src="https://img.shields.io/badge/LangChain-black?style=flat-square" alt="LangChain" />
+  <img src="https://img.shields.io/badge/Hono-black?style=flat-square" alt="Hono" />
+</p>
+
+---
+
+```typescript
+import gerbil from "@tryhamster/gerbil";
+
+const text = await gerbil("Explain recursion in one sentence");
+```
+
+## Why Gerbil?
+
+- **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
+- **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
+
+## Install
+
+```bash
+# Try without installing (one-off usage)
+npx @tryhamster/gerbil
+
+# Install globally
+npm install -g @tryhamster/gerbil
+
+# Or install in your project
+npm install @tryhamster/gerbil
+```
+
+After global install, use `gerbil` directly instead of `npx @tryhamster/gerbil`.
+
+## Quick Start
+
+```typescript
+import { Gerbil } from "@tryhamster/gerbil";
+
+const g = new Gerbil();
+await g.loadModel("qwen3-0.6b");
+
+// Generate
+const result = await g.generate("Write a haiku");
+console.log(result.text);
+
+// Stream
+for await (const chunk of g.stream("Tell me a story")) {
+  process.stdout.write(chunk);
+}
+
+// Thinking mode (Qwen3)
+const math = await g.generate("What is 127 × 43?", { thinking: true });
+console.log(math.thinking); // Shows reasoning
+console.log(math.text);     // "5461"
+
+// Structured JSON
+const data = await g.json("Extract: John, 32, NYC", {
+  schema: z.object({ name: z.string(), age: z.number(), city: z.string() }),
+});
+```
+
+## Skills
+
+Built-in AI skills with Zod-validated inputs:
+
+```typescript
+import { commit, summarize, explain, review } from "@tryhamster/gerbil/skills";
+
+const msg = await commit({ type: "conventional" });
+const summary = await summarize({ content: doc, length: "short" });
+const explanation = await explain({ content: code, level: "beginner" });
+```
+
+### Custom Skills
+
+```typescript
+import { defineSkill, loadSkills, useSkill } from "@tryhamster/gerbil/skills";
+
+// Define inline
+const sentiment = defineSkill({
+  name: "sentiment",
+  description: "Analyze text sentiment",
+  input: z.object({ text: z.string() }),
+  async run(input, gerbil) {
+    return gerbil.json(`Sentiment of: ${input.text}`, { schema: outputSchema });
+  },
+});
+
+// Or load from files
+await loadSkills("./skills");  // loads *.skill.ts
+const skill = useSkill("my-skill");
+```
+
+📖 **[Full Skills Documentation →](./docs/skills.md)**
+
+## Tools & Agents
+
+Gerbil supports tool calling with Qwen3 models for agentic workflows:
+
+```typescript
+import { defineTool, executeToolCall } from "@tryhamster/gerbil";
+
+const weatherTool = defineTool({
+  name: "get_weather",
+  description: "Get weather for a city",
+  parameters: z.object({ city: z.string() }),
+  execute: async ({ city }) => `Weather in ${city}: 72°F, sunny`,
+});
+```
+
+**Built-in tools:**
+- `gerbil_docs` — Search Gerbil documentation
+- `run_skill` — Execute any Gerbil skill
+
+In the REPL, **Agent mode** is on by default and enables tool calling:
+
+```bash
+npx @tryhamster/gerbil repl
+# Press ⌘A to toggle agent mode on/off
+# Ask: "how do I use gerbil with next.js?"
+# Gerbil will call the docs tool and synthesize an answer
+```
+
+📖 **[Full Tools Documentation →](./docs/tools.md)**
+
+## CLI
+
+```bash
+# Without installing (use npx)
+npx @tryhamster/gerbil                        # Interactive REPL (default)
+npx @tryhamster/gerbil "Write a haiku"        # Generate text
+
+# After installing globally (npm i -g @tryhamster/gerbil)
+gerbil                                        # Interactive REPL
+gerbil "Write a haiku"                        # Generate text
+gerbil commit                                 # Commit message from staged changes
+gerbil summarize README.md                    # Summarize file
+gerbil chat --thinking                        # Interactive chat
+gerbil serve --mcp                            # MCP server for Claude/Cursor
+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)**
+
+## Browser Usage
+
+Run LLMs directly in the browser with WebGPU — no server required:
+
+```tsx
+import { useChat } from "@tryhamster/gerbil/browser";
+
+function Chat() {
+  const { messages, input, setInput, handleSubmit, isLoading } = useChat();
+
+  if (isLoading) return <div>Loading model...</div>;
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {messages.map(m => <div key={m.id}>{m.role}: {m.content}</div>)}
+      <input value={input} onChange={e => setInput(e.target.value)} />
+    </form>
+  );
+}
+```
+
+📖 **[Full Browser Documentation →](./docs/browser.md)**
+
+## Integrations
+
+| Integration | Import | Docs |
+|-------------|--------|------|
+| **Browser** | `@tryhamster/gerbil/browser` | [📖 Browser Guide](./docs/browser.md) |
+| **AI SDK v5** | `@tryhamster/gerbil/ai` | [📖 AI SDK Guide](./docs/ai-sdk.md) |
+| **Next.js** | `@tryhamster/gerbil/next` | [📖 Frameworks](./docs/frameworks.md) |
+| **Express** | `@tryhamster/gerbil/express` | [📖 Frameworks](./docs/frameworks.md) |
+| **React** | `@tryhamster/gerbil/react` | [📖 Frameworks](./docs/frameworks.md) |
+| **LangChain** | `@tryhamster/gerbil/langchain` | [📖 Frameworks](./docs/frameworks.md) |
+| **MCP Server** | `npx @tryhamster/gerbil serve --mcp` | [📖 MCP Guide](./docs/mcp.md) |
+| **MCP Client** | `@tryhamster/gerbil/mcp-client` | [📖 MCP Client](./docs/mcp-client.md) |
+
+## Models
+
+| Model | Size | Best For |
+|-------|------|----------|
+| `qwen3-0.6b` | ~400MB | General use, reasoning (thinking mode) |
+| `qwen2.5-coder-0.5b` | ~400MB | Code generation |
+| `smollm2-135m` | ~100MB | Quick completions |
+
+Use any HuggingFace model: `npx @tryhamster/gerbil -m hf:org/model "prompt"`
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [📖 Browser](./docs/browser.md) | WebGPU inference in the browser |
+| [📖 Skills](./docs/skills.md) | Built-in skills, custom skill development, registry API |
+| [📖 Tools](./docs/tools.md) | Tool calling, agentic workflows, custom tools |
+| [📖 REPL](./docs/repl.md) | Interactive terminal dashboard |
+| [📖 AI SDK](./docs/ai-sdk.md) | Vercel AI SDK v5 integration |
+| [📖 Frameworks](./docs/frameworks.md) | Next.js, Express, React, Fastify, Hono, tRPC, LangChain |
+| [📖 CLI](./docs/cli.md) | All CLI commands and options |
+| [📖 MCP Server](./docs/mcp.md) | MCP server setup for Claude Desktop & Cursor |
+| [📖 MCP Client](./docs/mcp-client.md) | Connect to external MCP servers |
+
+## Requirements
+
+- Node.js 18+
+- For GPU: WebGPU-compatible environment
+
+## License
+
+MIT
+
+---
+
+<p align="center">
+  <sub>Part of the <a href="https://tryhamster.com">Hamster</a> family 🐹</sub>
+</p>

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.mjs";

package/dist/auto-update-BbNHbSU1.mjs

@@ -0,0 +1,3 @@
+import { i as installUpdate, n as checkForUpdate, r as compareVersions, t as CURRENT_VERSION } from "./cli.mjs";
+
+export { CURRENT_VERSION, checkForUpdate, installUpdate };

package/dist/browser/index.d.mts

@@ -0,0 +1,262 @@
+import { _ as SystemInfo, a as GenerateOptions, c as GerbilModelSettings, d as LoadOptions, f as ModelConfig, g as SessionStats, h as ProgressInfo, i as FallbackConfig, l as GerbilProviderSettings, m as ModelStats, n as EmbedOptions, o as GenerateResult, p as ModelSource, r as EmbedResult, s as GerbilConfig, t as CacheConfig, u as JsonOptions } from "../types-BS1N92Jt.mjs";
+import { t as BUILTIN_MODELS } from "../models-De2-_GmQ.mjs";
+
+//#region src/browser/index.d.ts
+
+type WorkerProgress = {
+  status: "loading" | "downloading" | "ready" | "error";
+  message?: string;
+  file?: string;
+  progress?: number;
+  /** Number of files being downloaded (0 = loading from cache) */
+  downloadCount?: number;
+  /** Total files to process */
+  totalFiles?: number;
+  error?: string;
+};
+type WorkerToken = {
+  status: "token";
+  text: string;
+  state: "thinking" | "answering";
+  numTokens: number;
+  tps: number;
+};
+type WorkerComplete = {
+  status: "complete";
+  text: string;
+  numTokens: number;
+  totalTime: number;
+  tps: number;
+};
+type GerbilWorkerOptions = {
+  /** Model ID to load (default: "qwen3-0.6b") */
+  modelId?: string;
+  /** Called during model loading with progress updates */
+  onProgress?: (progress: WorkerProgress) => void;
+  /** Called for each token during streaming generation */
+  onToken?: (token: WorkerToken) => void;
+  /** Called when generation is complete */
+  onComplete?: (result: WorkerComplete) => void;
+  /** Called on errors */
+  onError?: (error: string) => void;
+  /** Worker script URL (auto-detected if not provided) */
+  workerUrl?: string;
+};
+type GenerateStreamOptions = {
+  /** Maximum tokens to generate */
+  maxTokens?: number;
+  /** Temperature for sampling (0 = deterministic) */
+  temperature?: number;
+  /** Top-p nucleus sampling */
+  topP?: number;
+  /** Top-k sampling */
+  topK?: number;
+  /** Enable thinking mode (Qwen3) */
+  thinking?: boolean;
+  /** System prompt */
+  system?: string;
+};
+type GerbilWorker = {
+  /** Generate text with streaming */
+  generate: (prompt: string, options?: GenerateStreamOptions) => Promise<string>;
+  /** Interrupt current generation */
+  interrupt: () => void;
+  /** Reset conversation cache */
+  reset: () => void;
+  /** Terminate the worker */
+  terminate: () => void;
+  /** Check if model is loaded */
+  isReady: () => boolean;
+};
+/**
+ * Create a Gerbil worker for streaming WebGPU inference
+ *
+ * Uses a Web Worker to keep the UI responsive during model loading
+ * and text generation, with real-time token streaming.
+ */
+declare function createGerbilWorker(options?: GerbilWorkerOptions): Promise<GerbilWorker>;
+/** Message in a chat conversation */
+type Message = {
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+  thinking?: string;
+};
+/** Loading progress state */
+type LoadingProgress = {
+  status: "loading" | "downloading" | "ready" | "error";
+  message?: string;
+  file?: string;
+  progress?: number;
+  /** Number of files being downloaded (0 = loading from cache) */
+  downloadCount?: number;
+  /** Total files to process */
+  totalFiles?: number;
+};
+/** Options for useChat hook */
+type UseChatOptions = {
+  /** Model ID (default: "qwen3-0.6b") */
+  model?: string;
+  /** System prompt */
+  system?: string;
+  /** Enable thinking mode (Qwen3) */
+  thinking?: boolean;
+  /** Max tokens per response */
+  maxTokens?: number;
+  /** Temperature (0-2) */
+  temperature?: number;
+  /** Initial messages */
+  initialMessages?: Message[];
+  /** Auto-load model on mount (default: false - loads on first generate or load()) */
+  autoLoad?: boolean;
+  /** Called when model is ready */
+  onReady?: () => void;
+  /** Called on error */
+  onError?: (error: string) => void;
+};
+/** Return type for useChat hook */
+type UseChatReturn = {
+  /** Chat messages */
+  messages: Message[];
+  /** Current input value */
+  input: string;
+  /** Set input value */
+  setInput: (value: string) => void;
+  /** Submit current input */
+  handleSubmit: (e?: {
+    preventDefault?: () => void;
+  }) => void;
+  /** Whether model is loading */
+  isLoading: boolean;
+  /** Loading progress */
+  loadingProgress: LoadingProgress | null;
+  /** Whether generating a response */
+  isGenerating: boolean;
+  /** Current thinking content (streaming) */
+  thinking: string;
+  /** Stop generation */
+  stop: () => void;
+  /** Clear all messages */
+  clear: () => void;
+  /** Current tokens per second */
+  tps: number;
+  /** Whether model is ready */
+  isReady: boolean;
+  /** Error message if any */
+  error: string | null;
+  /** Load the model (only needed if lazy: true) */
+  load: () => void;
+};
+/**
+ * React hook for chat with local LLM
+ *
+ * @example
+ * ```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}>{m.role}: {m.content}</div>
+ *       ))}
+ *       <form onSubmit={handleSubmit}>
+ *         <input value={input} onChange={e => setInput(e.target.value)} />
+ *         <button disabled={isGenerating}>Send</button>
+ *       </form>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useChat(options?: UseChatOptions): UseChatReturn;
+/** Options for useCompletion hook */
+type UseCompletionOptions = {
+  /** Model ID (default: "qwen3-0.6b") */
+  model?: string;
+  /** System prompt */
+  system?: string;
+  /** Enable thinking mode (Qwen3) */
+  thinking?: boolean;
+  /** Max tokens */
+  maxTokens?: number;
+  /** Temperature (0-2) */
+  temperature?: number;
+  /** Auto-load model on mount (default: false - loads on first complete() or load()) */
+  autoLoad?: boolean;
+  /** Called when model is ready */
+  onReady?: () => void;
+  /** Called on error */
+  onError?: (error: string) => void;
+};
+/** Return type for useCompletion hook */
+type UseCompletionReturn = {
+  /** Generated completion */
+  completion: string;
+  /** Thinking content (if enabled) */
+  thinking: string;
+  /** Generate completion */
+  complete: (prompt: string) => Promise<string>;
+  /** Whether model is loading */
+  isLoading: boolean;
+  /** Loading progress */
+  loadingProgress: LoadingProgress | null;
+  /** Whether generating */
+  isGenerating: boolean;
+  /** Stop generation */
+  stop: () => void;
+  /** Current tokens per second */
+  tps: number;
+  /** Whether model is ready */
+  isReady: boolean;
+  /** Error message if any */
+  error: string | null;
+  /** Load the model (only needed if lazy: true) */
+  load: () => void;
+};
+/**
+ * React hook for text completion with local LLM
+ *
+ * @example
+ * ```tsx
+ * import { useCompletion } from "@tryhamster/gerbil/browser";
+ *
+ * function App() {
+ *   const { complete, completion, isLoading, isGenerating } = useCompletion();
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => complete("Write a haiku")}>Generate</button>
+ *       <p>{completion}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useCompletion(options?: UseCompletionOptions): UseCompletionReturn;
+/**
+ * Check if WebGPU is supported
+ */
+declare function isWebGPUSupported(): boolean;
+/**
+ * Get WebGPU adapter info
+ */
+declare function getWebGPUInfo(): Promise<{
+  supported: boolean;
+  adapter?: string;
+  device?: string;
+} | null>;
+declare const _default: {
+  isWebGPUSupported: typeof isWebGPUSupported;
+  getWebGPUInfo: typeof getWebGPUInfo;
+  createGerbilWorker: typeof createGerbilWorker;
+};
+//#endregion
+export { BUILTIN_MODELS, CacheConfig, EmbedOptions, EmbedResult, FallbackConfig, GenerateOptions, GenerateResult, GenerateStreamOptions, GerbilConfig, GerbilModelSettings, GerbilProviderSettings, GerbilWorker, GerbilWorkerOptions, JsonOptions, LoadOptions, LoadingProgress, Message, ModelConfig, ModelSource, ModelStats, ProgressInfo, SessionStats, SystemInfo, UseChatOptions, UseChatReturn, UseCompletionOptions, UseCompletionReturn, WorkerComplete, WorkerProgress, WorkerToken, createGerbilWorker, _default as default, getWebGPUInfo, isWebGPUSupported, useChat, useCompletion };
+//# sourceMappingURL=index.d.mts.map

package/dist/browser/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/browser/index.ts"],"sourcesContent":[],"mappings":";;;;;KA6DY,cAAA;;;;;;;;;;;KAYA,WAAA;;;;;;;KAQA,cAAA;;;;;;;KAQA,mBAAA;;;;0BAIc;;oBAEN;;wBAEI;;;;;;KAOZ,qBAAA;;;;;;;;;;;;;;KAeA,YAAA;;uCAE2B,0BAA0B;;;;;;;;;;;;;;;;iBAqB3C,kBAAA,WAA4B,sBAA2B,QAAQ;;KAwTzE,OAAA;;;;;;;KAQA,eAAA;;;;;;;;;;;KAYA,cAAA;;;;;;;;;;;;oBAYQ;;;;;;;;;KAUR,aAAA;;YAEA;;;;;;;;;;;;mBAUO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6CH,OAAA,WAAiB,iBAAsB;;KAmQ3C,oBAAA;;;;;;;;;;;;;;;;;;;KAoBA,mBAAA;;;;;;gCAMoB;;;;mBAIb;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoCH,aAAA,WAAuB,uBAA4B;;;;iBAqMnD,iBAAA,CAAA;;;;iBAUM,aAAA,CAAA,GAAiB;;;;;cAwBtC"}