@tryhamster/gerbil 1.0.0-rc.0

package/dist/tools-BsiEE6f2.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-BsiEE6f2.mjs","names":["GERBIL_DOCS: Record<string, string>","matches: string[]","toolContext: ToolContext | null","results: LoadedToolResult[]"],"sources":["../src/core/docs.ts","../src/core/tools.ts"],"sourcesContent":["/**\n * Gerbil Documentation Content\n *\n * Documentation strings used by the gerbil_docs tool\n * for answering questions about Gerbil features.\n */\n\nexport const GERBIL_DOCS: Record<string, string> = {\n  // Core\n  quickstart: `Gerbil Quick Start:\n\\`\\`\\`typescript\nimport { Gerbil } from \"gerbil\";\n\nconst g = new Gerbil();\nawait g.loadModel(\"qwen3-0.6b\");\n\n// Generate text\nconst result = await g.generate(\"Write a haiku\");\nconsole.log(result.text);\n\n// Stream responses\nfor await (const chunk of g.stream(\"Tell me a story\")) {\n  process.stdout.write(chunk);\n}\n\\`\\`\\``,\n\n  generate: `Generate text with options:\n\\`\\`\\`typescript\nconst result = await gerbil.generate(prompt, {\n  maxTokens: 256,      // Max tokens to generate\n  temperature: 0.7,    // 0-2, higher = more creative\n  topP: 0.9,           // Nucleus sampling\n  topK: 50,            // Top-k sampling\n  thinking: false,     // Enable reasoning mode (Qwen3)\n  system: \"You are...\", // System prompt\n});\n\n// Result contains:\nresult.text           // Generated text\nresult.thinking       // Reasoning (if thinking=true)\nresult.tokensGenerated\nresult.tokensPerSecond\nresult.totalTime\n\\`\\`\\``,\n\n  stream: `Streaming responses:\n\\`\\`\\`typescript\nfor await (const chunk of gerbil.stream(\"Hello\")) {\n  process.stdout.write(chunk);\n}\n\n// With options\nconst stream = gerbil.stream(\"Explain React\", {\n  maxTokens: 500,\n  onToken: (token) => console.log(token),\n});\n\\`\\`\\``,\n\n  json: `Structured JSON output with Zod validation:\n\\`\\`\\`typescript\nimport { z } from \"zod\";\n\nconst PersonSchema = z.object({\n  name: z.string(),\n  age: z.number(),\n  city: z.string(),\n});\n\nconst data = await gerbil.json(\"Extract: John is 32 and lives in NYC\", {\n  schema: PersonSchema,\n  retries: 3,          // Retry on validation failure\n  temperature: 0.3,    // Lower = more consistent\n});\n// { name: \"John\", age: 32, city: \"NYC\" }\n\\`\\`\\``,\n\n  thinking: `Thinking mode (chain-of-thought reasoning) - Qwen3 models:\n\\`\\`\\`typescript\nconst result = await gerbil.generate(\"What is 127 × 43?\", {\n  thinking: true,\n});\n\nconsole.log(result.thinking);\n// \"Let me calculate step by step: 127 × 43 = 127 × 40 + 127 × 3...\"\n\nconsole.log(result.text);\n// \"5461\"\n\\`\\`\\`\n\nEnable in chat with /no_think or /think commands, or enable_thinking parameter.`,\n\n  embed: `Generate embeddings:\n\\`\\`\\`typescript\n// Single text\nconst { vector } = await gerbil.embed(\"Hello world\");\n// vector: number[] (384 dimensions by default)\n\n// Batch\nconst results = await gerbil.embedBatch([\"Hello\", \"World\"]);\n\\`\\`\\``,\n\n  // Models\n  models: `Available models:\n\n| Model | Size | Best For |\n|-------|------|----------|\n| qwen3-0.6b | ~400MB | General use, reasoning (thinking mode) |\n| qwen2.5-0.5b | ~350MB | Fast and capable |\n| qwen2.5-coder-0.5b | ~400MB | Code generation |\n| smollm2-360m | ~250MB | Very fast, simple tasks |\n| smollm2-135m | ~100MB | Fastest, basic generation |\n| phi-3-mini | ~2.1GB | High quality, larger |\n\nLoad any HuggingFace model:\n\\`\\`\\`typescript\nawait gerbil.loadModel(\"hf:org/model\");\nawait gerbil.loadModel(\"onnx-community/Qwen3-0.6B-ONNX\");\n\\`\\`\\``,\n\n  load: `Loading models:\n\\`\\`\\`typescript\nawait gerbil.loadModel(\"qwen3-0.6b\", {\n  device: \"auto\",     // \"auto\" | \"gpu\" | \"cpu\"\n  dtype: \"q4\",        // \"q4\" | \"q8\" | \"fp16\" | \"fp32\"\n  onProgress: (p) => {\n    console.log(p.status, p.progress, p.file);\n  },\n});\n\\`\\`\\``,\n\n  // AI SDK\n  \"ai-sdk\": `Vercel AI SDK v5 integration:\n\\`\\`\\`typescript\nimport { generateText, streamText } from \"ai\";\nimport { gerbil } from \"gerbil/ai\";\n\n// Generate\nconst { text } = await generateText({\n  model: gerbil(\"qwen3-0.6b\"),\n  prompt: \"Write a commit message\",\n});\n\n// Stream\nconst stream = streamText({\n  model: gerbil(\"qwen3-0.6b\"),\n  prompt: \"Explain React hooks\",\n});\n\nfor await (const chunk of stream.textStream) {\n  process.stdout.write(chunk);\n}\n\n// With thinking mode\nconst { text } = await generateText({\n  model: gerbil(\"qwen3-0.6b\", { thinking: true }),\n  prompt: \"What is 127 × 43?\",\n});\n\\`\\`\\``,\n\n  // Frameworks\n  next: `Next.js App Router integration:\n\\`\\`\\`typescript\n// app/api/chat/route.ts\nimport { gerbil } from \"gerbil/next\";\n\nexport const POST = gerbil.handler({ \n  model: \"qwen3-0.6b\",\n  maxTokens: 500,\n});\n\\`\\`\\``,\n\n  express: `Express.js integration:\n\\`\\`\\`typescript\nimport express from \"express\";\nimport { gerbil } from \"gerbil/express\";\n\nconst app = express();\napp.use(\"/ai\", gerbil()());\n\n// Endpoints created:\n// POST /ai/generate - Generate text\n// POST /ai/stream   - Stream text\n// POST /ai/json     - Structured output\n// POST /ai/embed    - Embeddings\n\\`\\`\\``,\n\n  react: `React hooks:\n\\`\\`\\`typescript\nimport { useGerbil, useChat } from \"gerbil/react\";\n\nfunction Chat() {\n  const { generate, isLoading } = useGerbil();\n  \n  const handleSubmit = async (prompt: string) => {\n    const result = await generate(prompt);\n    console.log(result.text);\n  };\n}\n\\`\\`\\``,\n\n  hono: `Hono integration:\n\\`\\`\\`typescript\nimport { Hono } from \"hono\";\nimport { gerbil } from \"gerbil/hono\";\n\nconst app = new Hono();\napp.route(\"/ai\", await gerbil()());\n\\`\\`\\``,\n\n  langchain: `LangChain integration:\n\\`\\`\\`typescript\nimport { GerbilLLM, GerbilEmbeddings } from \"gerbil/langchain\";\n\nconst llm = new GerbilLLM({ model: \"qwen3-0.6b\" });\nconst embeddings = new GerbilEmbeddings();\n\n// Use with chains\nconst chain = new LLMChain({ llm, prompt: template });\n\\`\\`\\``,\n\n  mcp: `MCP Server for Claude Desktop & Cursor:\n\\`\\`\\`bash\ngerbil serve --mcp\n\\`\\`\\`\n\nSkills are automatically exposed as MCP tools:\n- gerbil_generate\n- gerbil_commit\n- gerbil_summarize\n- gerbil_explain\n- etc.`,\n\n  // Skills\n  skills: `Skills are reusable AI tasks with Zod validation:\n\\`\\`\\`typescript\nimport { commit, summarize, explain, review } from \"gerbil/skills\";\n\n// Generate commit message\nconst msg = await commit({ type: \"conventional\", maxLength: 72 });\n\n// Summarize content\nconst summary = await summarize({ \n  content: doc, \n  length: \"short\",\n  format: \"bullets\" \n});\n\n// Explain code\nconst explanation = await explain({ \n  content: code, \n  level: \"beginner\" \n});\n\n// Code review\nconst feedback = await review({ \n  code, \n  focus: [\"security\", \"performance\"] \n});\n\\`\\`\\`\n\nBuilt-in skills: commit, summarize, explain, review, test, translate, extract, title`,\n\n  \"define-skill\": `Create custom skills:\n\\`\\`\\`typescript\nimport { defineSkill } from \"gerbil/skills\";\nimport { z } from \"zod\";\n\nexport const sentiment = defineSkill({\n  name: \"sentiment\",\n  description: \"Analyze text sentiment\",\n  input: z.object({ \n    text: z.string(),\n    detailed: z.boolean().default(false)\n  }),\n  output: z.object({\n    sentiment: z.enum([\"positive\", \"negative\", \"neutral\"]),\n    confidence: z.number(),\n  }),\n  temperature: 0.3,\n  maxTokens: 100,\n  \n  async run({ input, gerbil }) {\n    return gerbil.json(\\`Sentiment of: \\${input.text}\\`, {\n      schema: this.output,\n    });\n  },\n});\n\\`\\`\\``,\n\n  \"load-skills\": `Load skills from files:\n\\`\\`\\`typescript\nimport { loadSkills, useSkill, listSkills } from \"gerbil/skills\";\n\n// Load from directory (*.skill.ts files)\nawait loadSkills(\"./skills\");\n\n// Use by name\nconst skill = useSkill(\"my-skill\");\nconst result = await skill({ text: \"Hello\" });\n\n// List all\nconsole.log(listSkills()); // [\"commit\", \"summarize\", ...]\n\\`\\`\\``,\n\n  // CLI\n  cli: `CLI commands:\n\\`\\`\\`bash\ngerbil \"Write a haiku\"              # Generate text\ngerbil -m qwen3-0.6b \"prompt\"       # Specify model\ngerbil --thinking \"127 × 43\"        # Enable reasoning\n\ngerbil commit                        # Git commit message\ngerbil summarize README.md           # Summarize file\ngerbil explain src/index.ts          # Explain code\n\ngerbil chat                          # Interactive chat\ngerbil chat --thinking               # With reasoning\n\ngerbil serve                         # HTTP server\ngerbil serve --mcp                   # MCP server\n\ngerbil models                        # List models\ngerbil cache                         # Show cached models\ngerbil bench                         # Benchmark\ngerbil info                          # System info\n\ngerbil repl                          # Interactive TUI\n\\`\\`\\``,\n\n  // Tools/Agents\n  tools: `Gerbil supports tool calling with Qwen3 models:\n\\`\\`\\`typescript\nimport { defineTool, executeToolCall } from \"gerbil\";\n\nconst weatherTool = defineTool({\n  name: \"get_weather\",\n  description: \"Get current weather for a city\",\n  parameters: z.object({\n    city: z.string(),\n  }),\n  execute: async ({ city }) => {\n    return \\`Weather in \\${city}: 72°F, sunny\\`;\n  },\n});\n\\`\\`\\`\n\nIn the REPL, use Agent mode (Tab → Agent) to enable tools.`,\n};\n\n/**\n * Get all available documentation topics\n */\nexport function getDocTopics(): string[] {\n  return Object.keys(GERBIL_DOCS);\n}\n\n/**\n * Search documentation by topic\n */\nexport function searchDocs(query: string): string | null {\n  const words = query.toLowerCase().split(/\\s+/);\n  const keyWords = words.filter((w) => w.length > 2);\n\n  // Direct key match first\n  for (const [key, content] of Object.entries(GERBIL_DOCS)) {\n    const keyNorm = key.replace(/-/g, \"\");\n    for (const word of keyWords) {\n      if (keyNorm === word || key === word || keyNorm.includes(word)) {\n        return content;\n      }\n    }\n  }\n\n  // Try each word as a potential topic\n  for (const word of keyWords) {\n    for (const [key, content] of Object.entries(GERBIL_DOCS)) {\n      if (key.includes(word) || word.includes(key.replace(/-/g, \"\"))) {\n        return content;\n      }\n    }\n  }\n\n  // Fallback: search content\n  const matches: string[] = [];\n  for (const [key, content] of Object.entries(GERBIL_DOCS)) {\n    for (const word of keyWords) {\n      if (content.toLowerCase().includes(word)) {\n        matches.push(`## ${key}\\n${content}`);\n        break;\n      }\n    }\n  }\n\n  if (matches.length > 0) {\n    return matches.slice(0, 2).join(\"\\n\\n---\\n\\n\");\n  }\n\n  return null;\n}\n","/**\n * Tool Calling System for Gerbil\n *\n * Enables LLMs to call functions/tools during generation.\n * Compatible with Qwen3's tool calling format.\n */\n\nimport { z } from \"zod\";\nimport { getDocTopics, searchDocs } from \"./docs.js\";\nimport { zodToJsonSchema } from \"./utils.js\";\n\n// ============================================\n// Tool Context (for passing gerbil to tools)\n// ============================================\n\nexport type ToolContext = {\n  /** Generate text using the loaded model */\n  generate: (prompt: string) => Promise<string>;\n};\n\nlet toolContext: ToolContext | null = null;\n\n/**\n * Set the tool context (call this after loading a model)\n */\nexport function setToolContext(ctx: ToolContext): void {\n  toolContext = ctx;\n}\n\n/**\n * Get the tool context for use in tools\n */\nexport function getToolContext(): ToolContext | null {\n  return toolContext;\n}\n\n// ============================================\n// Tool Definition\n// ============================================\n\nexport type ToolDefinition<TParams = unknown> = {\n  /** Tool name (function name) */\n  name: string;\n\n  /** Description for the LLM */\n  description: string;\n\n  /** Zod schema for parameters */\n  parameters?: z.ZodType<TParams>;\n\n  /** The function to execute (receives params and optional context) */\n  execute: (params: TParams, ctx?: ToolContext | null) => Promise<string>;\n};\n\nexport type Tool<TParams = unknown> = {\n  definition: ToolDefinition<TParams>;\n  (params: TParams): Promise<string>;\n};\n\n// ============================================\n// Tool Registry\n// ============================================\n\nconst toolRegistry = new Map<string, Tool<any>>();\n\n/**\n * Define a tool\n */\nexport function defineTool<TParams>(def: ToolDefinition<TParams>): Tool<TParams> {\n  const tool = async (params: TParams): Promise<string> => {\n    // Validate params if schema provided\n    if (def.parameters) {\n      const parsed = def.parameters.parse(params);\n      return def.execute(parsed, toolContext);\n    }\n    return def.execute(params, toolContext);\n  };\n\n  (tool as Tool<TParams>).definition = def;\n\n  // Auto-register\n  toolRegistry.set(def.name, tool as Tool<any>);\n\n  return tool as Tool<TParams>;\n}\n\n/**\n * Get tool by name\n */\nexport function getTool(name: string): Tool<any> | undefined {\n  return toolRegistry.get(name);\n}\n\n/**\n * List all tools\n */\nexport function listTools(): string[] {\n  return Array.from(toolRegistry.keys());\n}\n\n/**\n * Get all tool definitions for prompt injection\n */\nexport function getToolDefinitions(): ToolDefinition<any>[] {\n  return Array.from(toolRegistry.values()).map((t) => t.definition);\n}\n\nexport type LoadedToolResult = {\n  name: string;\n  loaded: boolean;\n  error?: string;\n  path: string;\n};\n\n/**\n * Simple tool config (no imports needed in tool files)\n */\nexport type SimpleToolConfig = {\n  name: string;\n  description: string;\n  execute: (params: Record<string, any>) => Promise<string> | string;\n};\n\n/**\n * Load tools from a directory\n * Tools are simple .ts files with a default export config object\n * No module imports - we eval the execute function directly\n */\nexport async function loadTools(dir: string): Promise<LoadedToolResult[]> {\n  const fs = await import(\"fs\");\n  const pathModule = await import(\"path\");\n\n  if (!fs.existsSync(dir)) {\n    return [];\n  }\n\n  const files = fs.readdirSync(dir).filter((f) => f.endsWith(\".tool.ts\") || f.endsWith(\".tool.js\"));\n  const results: LoadedToolResult[] = [];\n\n  for (const file of files) {\n    const filePath = pathModule.join(dir, file);\n    const toolName = file.replace(/\\.tool\\.(ts|js)$/, \"\");\n\n    try {\n      // Read file content directly\n      const content = fs.readFileSync(filePath, \"utf-8\");\n\n      // Extract the config object using simple parsing\n      const config = parseToolFile(content, toolName);\n\n      if (config) {\n        // Register the tool\n        defineTool({\n          name: config.name,\n          description: config.description,\n          execute: async (params, ctx) => {\n            // Project tools may or may not accept ctx parameter\n            const executeFn = config.execute as any;\n            const result = await executeFn(params, ctx);\n            return typeof result === \"string\" ? result : String(result);\n          },\n        });\n        results.push({ name: config.name, loaded: true, path: filePath });\n      } else {\n        results.push({\n          name: toolName,\n          loaded: false,\n          error: \"Could not parse tool config\",\n          path: filePath,\n        });\n      }\n    } catch (e) {\n      const errorMsg = e instanceof Error ? e.message.split(\"\\n\")[0] : String(e);\n      results.push({ name: toolName, loaded: false, error: errorMsg, path: filePath });\n    }\n  }\n\n  return results;\n}\n\n/**\n * Parse a simple tool file and extract the config\n * Expected format:\n * ```\n * export default {\n *   name: \"tool_name\",\n *   description: \"...\",\n *   execute: async (params) => { ... }\n * }\n * ```\n */\nfunction parseToolFile(content: string, fallbackName: string): SimpleToolConfig | null {\n  try {\n    // Remove TypeScript type annotations for eval\n    let cleaned = content\n      .replace(/:\\s*\\{[^}]+\\}/g, \"\") // Remove type objects like : { theme?: string }\n      .replace(/:\\s*Record<[^>]+>/g, \"\") // Remove Record types\n      .replace(/:\\s*string\\b/g, \"\")\n      .replace(/:\\s*number\\b/g, \"\")\n      .replace(/:\\s*boolean\\b/g, \"\")\n      .replace(/:\\s*any\\b/g, \"\")\n      .replace(/:\\s*Promise<[^>]+>/g, \"\")\n      .replace(/export\\s+default\\s+/, \"return \");\n\n    // Remove comments\n    cleaned = cleaned.replace(/\\/\\/.*$/gm, \"\").replace(/\\/\\*[\\s\\S]*?\\*\\//g, \"\");\n\n    // Wrap in function and evaluate\n    const fn = new Function(cleaned);\n    const config = fn();\n\n    if (config && typeof config === \"object\" && config.name && config.execute) {\n      return {\n        name: config.name || fallbackName,\n        description: config.description || \"No description\",\n        execute: config.execute,\n      };\n    }\n    return null;\n  } catch (e) {\n    console.error(\"Failed to parse tool file:\", e);\n    return null;\n  }\n}\n\n/**\n * Load tools from project .gerbil/tools directory\n */\nexport async function loadProjectTools(): Promise<LoadedToolResult[]> {\n  const pathModule = await import(\"path\");\n  const toolsDir = pathModule.join(process.cwd(), \".gerbil\", \"tools\");\n  return loadTools(toolsDir);\n}\n\n// Re-export for backwards compatibility\nexport { zodToJsonSchema } from \"./utils.js\";\n\n/**\n * Format tools for Qwen3 prompt\n */\nexport function formatToolsForPrompt(tools: ToolDefinition<any>[]): string {\n  if (tools.length === 0) {\n    return \"\";\n  }\n\n  const toolDefs = tools\n    .map((t) => {\n      const params = t.parameters\n        ? zodToJsonSchema(t.parameters)\n        : { type: \"object\", properties: {} };\n      return `## ${t.name}\n\nDescription: ${t.description}\nParameters: ${JSON.stringify(params, null, 2)}`;\n    })\n    .join(\"\\n\\n\");\n\n  return `You are a helpful assistant with access to tools.\n\n# Tools\n\n${toolDefs}\n\n## How to call tools\n\nTo call a tool, use this exact format:\n<tool_call>\n{\"name\": \"tool_name\", \"arguments\": {\"param\": \"value\"}}\n</tool_call>\n\nWhen the user asks about Gerbil (documentation, features, how to use), call gerbil_docs with a topic like: tools, skills, ai-sdk, next, express, generate, stream, models, cli.\n\nFor other questions, respond normally without calling tools.`;\n}\n\n/**\n * Parse tool call from response\n */\nexport function parseToolCall(response: string): { tool: string; params: any } | null {\n  try {\n    // Try <tool_call> format first (Qwen style)\n    const toolCallMatch = response.match(/<tool_call>\\s*([\\s\\S]*?)\\s*<\\/tool_call>/);\n    if (toolCallMatch) {\n      const parsed = JSON.parse(toolCallMatch[1]);\n      if (parsed.name) {\n        return { tool: parsed.name, params: parsed.arguments || {} };\n      }\n    }\n\n    // Fallback: look for {\"name\": \"...\", \"arguments\": ...} pattern\n    const nameArgsMatch = response.match(\n      /\\{\\s*\"name\"\\s*:\\s*\"([^\"]+)\"[^}]*\"arguments\"\\s*:\\s*(\\{[^}]*\\})/,\n    );\n    if (nameArgsMatch) {\n      return { tool: nameArgsMatch[1], params: JSON.parse(nameArgsMatch[2]) };\n    }\n\n    // Fallback: {\"tool\": \"...\", \"params\": ...} pattern\n    const toolParamsMatch = response.match(\n      /\\{\\s*\"tool\"\\s*:\\s*\"([^\"]+)\"[^}]*\"params\"\\s*:\\s*(\\{[^}]*\\})/,\n    );\n    if (toolParamsMatch) {\n      return { tool: toolParamsMatch[1], params: JSON.parse(toolParamsMatch[2]) };\n    }\n\n    // Simple fallback\n    const simpleMatch = response.match(/\\{\\s*\"(?:tool|name)\"\\s*:\\s*\"([^\"]+)\"/);\n    if (simpleMatch) {\n      return { tool: simpleMatch[1], params: {} };\n    }\n  } catch {}\n  return null;\n}\n\n/**\n * Execute a tool call\n */\nexport async function executeToolCall(toolName: string, params: any): Promise<string> {\n  const tool = getTool(toolName);\n  if (!tool) {\n    return `Error: Unknown tool \"${toolName}\"`;\n  }\n\n  try {\n    return await tool(params);\n  } catch (e) {\n    return `Error executing ${toolName}: ${e}`;\n  }\n}\n\n// ============================================\n// Built-in Tools\n// ============================================\n\n/**\n * Docs tool - searches gerbil documentation\n * Documentation content is in core/docs.ts\n */\nexport const docsTool = defineTool({\n  name: \"gerbil_docs\",\n  description:\n    \"Search Gerbil documentation for information about features, API, integrations, skills, and usage examples\",\n  parameters: z.object({\n    query: z\n      .string()\n      .optional()\n      .default(\"quickstart\")\n      .describe(\n        \"Topic: quickstart, generate, stream, json, thinking, embed, models, ai-sdk, next, express, react, skills, define-skill, cli, tools\",\n      ),\n  }),\n  execute: async ({ query = \"quickstart\" }) => {\n    const result = searchDocs(query);\n    if (result) {\n      return result;\n    }\n    const topics = getDocTopics().join(\", \");\n    return `No documentation found for \"${query}\". Available topics: ${topics}`;\n  },\n});\n"],"mappings":"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"}

package/dist/types-BS1N92Jt.d.mts

@@ -0,0 +1,183 @@
+import { z } from "zod";
+
+//#region src/core/types.d.ts
+
+type ModelConfig = {
+  id: string;
+  repo: string;
+  description: string;
+  size: string;
+  contextLength: number;
+  supportsThinking: boolean;
+  supportsJson: boolean;
+  family: "qwen" | "smollm" | "phi" | "mistral" | "llama" | "other";
+};
+type ModelSource = {
+  type: "builtin" | "huggingface" | "local";
+  path: string;
+};
+type GenerateOptions = {
+  /** Maximum tokens to generate (default: 256) */
+  maxTokens?: number;
+  /** Temperature for sampling, 0-2 (default: 0.7) */
+  temperature?: number;
+  /** Top-p sampling (default: 0.9) */
+  topP?: number;
+  /** Top-k sampling (default: 50) */
+  topK?: number;
+  /** Stop sequences */
+  stopSequences?: string[];
+  /** System prompt */
+  system?: string;
+  /** Enable thinking/reasoning mode (Qwen3) */
+  thinking?: boolean;
+  /** Callback for each token (streaming) */
+  onToken?: (token: string) => void;
+};
+type GenerateResult = {
+  /** Generated text */
+  text: string;
+  /** Thinking/reasoning (if enabled) */
+  thinking?: string;
+  /** Tokens generated */
+  tokensGenerated: number;
+  /** Generation speed */
+  tokensPerSecond: number;
+  /** Total time in ms */
+  totalTime: number;
+  /** Why generation stopped */
+  finishReason: "stop" | "length" | "error";
+  /** Which provider was used (for hybrid mode) */
+  provider?: "local" | "openai" | "anthropic";
+  /** Whether result came from cache */
+  cached?: boolean;
+};
+type JsonOptions<T = unknown> = {
+  /** Zod schema for validation */
+  schema: z.ZodType<T>;
+  /** Number of retries on invalid JSON (default: 3) */
+  retries?: number;
+  /** Temperature (lower = more deterministic, default: 0.3) */
+  temperature?: number;
+  /** System prompt override */
+  system?: string;
+};
+type EmbedOptions = {
+  /** Model to use for embeddings */
+  model?: string;
+  /** Normalize vectors (default: true) */
+  normalize?: boolean;
+};
+type EmbedResult = {
+  /** Embedding vector */
+  vector: number[];
+  /** Original text */
+  text: string;
+  /** Time in ms */
+  totalTime: number;
+};
+type LoadOptions = {
+  /** Progress callback */
+  onProgress?: (info: ProgressInfo) => void;
+  /** Device: 'auto', 'gpu', 'cpu', 'webgpu' (default: 'auto') */
+  device?: "auto" | "gpu" | "cpu" | "webgpu";
+  /** Quantization: 'q4', 'q8', 'fp16', 'fp32' (default: 'q4') */
+  dtype?: "q4" | "q8" | "fp16" | "fp32";
+  /** Override context length */
+  contextLength?: number;
+};
+type ProgressInfo = {
+  status: string;
+  progress?: number;
+  file?: string;
+  loaded?: number;
+  total?: number;
+};
+type GerbilConfig = {
+  /** Default model */
+  model?: string;
+  /** Default device */
+  device?: "auto" | "gpu" | "cpu";
+  /** Default quantization */
+  dtype?: "q4" | "q8" | "fp16" | "fp32";
+  /** Cache configuration */
+  cache?: CacheConfig;
+  /** Fallback configuration */
+  fallback?: FallbackConfig;
+};
+type CacheConfig = {
+  /** Enable caching (default: true) */
+  enabled?: boolean;
+  /** Time-to-live in seconds (default: 3600) */
+  ttl?: number;
+  /** Max cache size (default: "500mb") */
+  maxSize?: string;
+  /** Storage backend */
+  storage?: "memory" | "disk" | "redis";
+  /** Redis URL (if storage is redis) */
+  redisUrl?: string;
+};
+type FallbackConfig = {
+  /** Fallback provider */
+  provider: "openai" | "anthropic";
+  /** API key */
+  apiKey: string;
+  /** Model to use */
+  model: string;
+  /** When to fallback */
+  when: "timeout" | "error" | "always-verify";
+  /** Timeout in ms before fallback (default: 5000) */
+  timeout?: number;
+};
+type SessionStats = {
+  prompts: number;
+  tokensIn: number;
+  tokensOut: number;
+  avgSpeed: number;
+  totalTime: number;
+  cacheHits: number;
+  cacheMisses: number;
+};
+type ModelStats = {
+  modelId: string;
+  avgSpeed: number;
+  totalGenerations: number;
+  totalTokens: number;
+};
+type SystemInfo = {
+  version: string;
+  model: ModelConfig | null;
+  device: {
+    backend: string;
+    gpu: string | null;
+    vram: string | null;
+    status: "ready" | "loading" | "error";
+  };
+  context: {
+    max: number;
+    used: number;
+    available: number;
+  };
+  cache: {
+    location: string;
+    size: string;
+    modelCount: number;
+  };
+};
+type GerbilModelSettings = {
+  /** Enable thinking mode */
+  thinking?: boolean;
+  /** Device to use */
+  device?: "auto" | "gpu" | "cpu";
+  /** Quantization level */
+  dtype?: "q4" | "q8" | "fp16" | "fp32";
+};
+type GerbilProviderSettings = {
+  /** Default device */
+  device?: "auto" | "gpu" | "cpu";
+  /** Default quantization */
+  dtype?: "q4" | "q8" | "fp16" | "fp32";
+};
+//#endregion
+export { SystemInfo as _, GenerateOptions as a, GerbilModelSettings as c, LoadOptions as d, ModelConfig as f, SessionStats as g, ProgressInfo as h, FallbackConfig as i, GerbilProviderSettings as l, ModelStats as m, EmbedOptions as n, GenerateResult as o, ModelSource as p, EmbedResult as r, GerbilConfig as s, CacheConfig as t, JsonOptions as u };
+//# sourceMappingURL=types-BS1N92Jt.d.mts.map

package/dist/types-BS1N92Jt.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-BS1N92Jt.d.mts","names":[],"sources":["../src/core/types.ts"],"sourcesContent":[],"mappings":";;;;AAqBY,KAXA,WAAA,GAWW;EASX,EAAA,EAAA,MAAA;EA0BA,IAAA,EAAA,MAAA;EA8BA,WAAA,EAAA,MAAW;EAkBX,IAAA,EAAA,MAAA;EAQA,aAAA,EAAW,MAAA;EAeX,gBAAW,EAAA,OAAA;EAcX,YAAA,EAAA,OAAY;EAYZ,MAAA,EAAA,MAAA,GAAY,QAAA,GAWd,KAAA,GAAA,SAGG,GAAA,OAAc,GAAA,OAAA;AAG3B,CAAA;AAiBY,KAtKA,WAAA,GAsKc;EAqBd,IAAA,EAAA,SAAY,GAAA,aAAA,GAAA,OAAA;EAUZ,IAAA,EAAA,MAAA;AAOZ,CAAA;AAyBY,KA5NA,eAAA,GA4NmB;EAWnB;;;;;;;;;;;;;;;;;KA7MA,cAAA;;;;;;;;;;;;;;;;;;KA8BA;;UAEF,CAAA,CAAE,QAAQ;;;;;;;;KAgBR,YAAA;;;;;;KAQA,WAAA;;;;;;;;KAeA,WAAA;;sBAEU;;;;;;;;KAYV,YAAA;;;;;;;KAYA,YAAA;;;;;;;;UAWF;;aAGG;;KAGD,WAAA;;;;;;;;;;;;KAiBA,cAAA;;;;;;;;;;;;KAqBA,YAAA;;;;;;;;;KAUA,UAAA;;;;;;KAOA,UAAA;;SAEH;;;;;;;;;;;;;;;;;;KAuBG,mBAAA;;;;;;;;KAWA,sBAAA"}

package/dist/utils-7vXqtq2Q.mjs

@@ -0,0 +1,63 @@
+//#region src/core/utils.ts
+/**
+* Convert Zod schema to JSON Schema (simplified)
+* Handles objects, arrays, primitives, enums, optionals, and defaults
+*/
+function zodToJsonSchema(schema) {
+	try {
+		if ("_def" in schema) {
+			const def = schema._def;
+			if (def.typeName === "ZodObject") {
+				const shape = def.shape();
+				const properties = {};
+				const required = [];
+				for (const [key, value] of Object.entries(shape)) {
+					properties[key] = zodToJsonSchema(value);
+					if (!value._def?.typeName?.includes("Optional")) required.push(key);
+				}
+				return {
+					type: "object",
+					properties,
+					required
+				};
+			}
+			if (def.typeName === "ZodString") return {
+				type: "string",
+				description: def.description
+			};
+			if (def.typeName === "ZodNumber") return {
+				type: "number",
+				description: def.description
+			};
+			if (def.typeName === "ZodBoolean") return { type: "boolean" };
+			if (def.typeName === "ZodArray") return {
+				type: "array",
+				items: zodToJsonSchema(def.type)
+			};
+			if (def.typeName === "ZodEnum") return {
+				type: "string",
+				enum: def.values
+			};
+			if (def.typeName === "ZodOptional") return zodToJsonSchema(def.innerType);
+			if (def.typeName === "ZodDefault") return {
+				...zodToJsonSchema(def.innerType),
+				default: def.defaultValue()
+			};
+		}
+	} catch {}
+	return { type: "string" };
+}
+/**
+* Extract JSON from text (finds first { } or [ ] block)
+*/
+function extractJson(text) {
+	const jsonMatch = text.match(/\{[\s\S]*\}/);
+	if (jsonMatch) return jsonMatch[0];
+	const arrayMatch = text.match(/\[[\s\S]*\]/);
+	if (arrayMatch) return arrayMatch[0];
+	return text;
+}
+
+//#endregion
+export { zodToJsonSchema as n, extractJson as t };
+//# sourceMappingURL=utils-7vXqtq2Q.mjs.map

package/dist/utils-7vXqtq2Q.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils-7vXqtq2Q.mjs","names":["properties: Record<string, any>","required: string[]"],"sources":["../src/core/utils.ts"],"sourcesContent":["/**\n * Shared utility functions for Gerbil core\n */\n\nimport type { z } from \"zod\";\n\n/**\n * Convert Zod schema to JSON Schema (simplified)\n * Handles objects, arrays, primitives, enums, optionals, and defaults\n */\nexport function zodToJsonSchema(schema: z.ZodType<any>): object {\n  try {\n    if (\"_def\" in schema) {\n      const def = (schema as any)._def;\n\n      if (def.typeName === \"ZodObject\") {\n        const shape = def.shape();\n        const properties: Record<string, any> = {};\n        const required: string[] = [];\n\n        for (const [key, value] of Object.entries(shape)) {\n          properties[key] = zodToJsonSchema(value as z.ZodType<any>);\n          // Check if required (not optional)\n          if (!(value as any)._def?.typeName?.includes(\"Optional\")) {\n            required.push(key);\n          }\n        }\n\n        return { type: \"object\", properties, required };\n      }\n      if (def.typeName === \"ZodString\") {\n        return { type: \"string\", description: def.description };\n      }\n      if (def.typeName === \"ZodNumber\") {\n        return { type: \"number\", description: def.description };\n      }\n      if (def.typeName === \"ZodBoolean\") {\n        return { type: \"boolean\" };\n      }\n      if (def.typeName === \"ZodArray\") {\n        return { type: \"array\", items: zodToJsonSchema(def.type) };\n      }\n      if (def.typeName === \"ZodEnum\") {\n        return { type: \"string\", enum: def.values };\n      }\n      if (def.typeName === \"ZodOptional\") {\n        return zodToJsonSchema(def.innerType);\n      }\n      if (def.typeName === \"ZodDefault\") {\n        const inner = zodToJsonSchema(def.innerType);\n        return { ...inner, default: def.defaultValue() };\n      }\n    }\n  } catch {}\n\n  return { type: \"string\" };\n}\n\n/**\n * Extract JSON from text (finds first { } or [ ] block)\n */\nexport function extractJson(text: string): string {\n  const jsonMatch = text.match(/\\{[\\s\\S]*\\}/);\n  if (jsonMatch) {\n    return jsonMatch[0];\n  }\n\n  const arrayMatch = text.match(/\\[[\\s\\S]*\\]/);\n  if (arrayMatch) {\n    return arrayMatch[0];\n  }\n\n  return text;\n}\n"],"mappings":";;;;;AAUA,SAAgB,gBAAgB,QAAgC;AAC9D,KAAI;AACF,MAAI,UAAU,QAAQ;GACpB,MAAM,MAAO,OAAe;AAE5B,OAAI,IAAI,aAAa,aAAa;IAChC,MAAM,QAAQ,IAAI,OAAO;IACzB,MAAMA,aAAkC,EAAE;IAC1C,MAAMC,WAAqB,EAAE;AAE7B,SAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,EAAE;AAChD,gBAAW,OAAO,gBAAgB,MAAwB;AAE1D,SAAI,CAAE,MAAc,MAAM,UAAU,SAAS,WAAW,CACtD,UAAS,KAAK,IAAI;;AAItB,WAAO;KAAE,MAAM;KAAU;KAAY;KAAU;;AAEjD,OAAI,IAAI,aAAa,YACnB,QAAO;IAAE,MAAM;IAAU,aAAa,IAAI;IAAa;AAEzD,OAAI,IAAI,aAAa,YACnB,QAAO;IAAE,MAAM;IAAU,aAAa,IAAI;IAAa;AAEzD,OAAI,IAAI,aAAa,aACnB,QAAO,EAAE,MAAM,WAAW;AAE5B,OAAI,IAAI,aAAa,WACnB,QAAO;IAAE,MAAM;IAAS,OAAO,gBAAgB,IAAI,KAAK;IAAE;AAE5D,OAAI,IAAI,aAAa,UACnB,QAAO;IAAE,MAAM;IAAU,MAAM,IAAI;IAAQ;AAE7C,OAAI,IAAI,aAAa,cACnB,QAAO,gBAAgB,IAAI,UAAU;AAEvC,OAAI,IAAI,aAAa,aAEnB,QAAO;IAAE,GADK,gBAAgB,IAAI,UAAU;IACzB,SAAS,IAAI,cAAc;IAAE;;SAG9C;AAER,QAAO,EAAE,MAAM,UAAU;;;;;AAM3B,SAAgB,YAAY,MAAsB;CAChD,MAAM,YAAY,KAAK,MAAM,cAAc;AAC3C,KAAI,UACF,QAAO,UAAU;CAGnB,MAAM,aAAa,KAAK,MAAM,cAAc;AAC5C,KAAI,WACF,QAAO,WAAW;AAGpB,QAAO"}

package/docs/ai-sdk.md

@@ -0,0 +1,80 @@
+# Gerbil + AI SDK
+
+Gerbil works as a [Vercel AI SDK v5](https://sdk.vercel.ai/) provider.
+
+## Setup
+
+```typescript
+import { generateText, streamText } from "ai";
+import { gerbil } from "@tryhamster/gerbil/ai";
+```
+
+## Generate Text
+
+```typescript
+const { text } = await generateText({
+  model: gerbil("qwen3-0.6b"),
+  prompt: "Write a commit message for adding dark mode",
+});
+```
+
+## Stream Text
+
+```typescript
+const stream = streamText({
+  model: gerbil("qwen3-0.6b"),
+  prompt: "Explain React hooks",
+});
+
+for await (const chunk of stream.textStream) {
+  process.stdout.write(chunk);
+}
+```
+
+## With System Prompt
+
+```typescript
+const { text } = await generateText({
+  model: gerbil("qwen3-0.6b"),
+  system: "You are a helpful coding assistant.",
+  prompt: "How do I handle errors in async/await?",
+});
+```
+
+## Model Settings
+
+```typescript
+import { createGerbil } from "@tryhamster/gerbil/ai";
+
+// Create provider with defaults
+const local = createGerbil({
+  device: "gpu",
+  dtype: "q4",
+});
+
+// Use with settings
+const { text } = await generateText({
+  model: local("qwen3-0.6b", { thinking: true }),
+  prompt: "What is 127 × 43?",
+});
+```
+
+## Available Options
+
+```typescript
+gerbil(modelId, {
+  thinking?: boolean,    // Enable reasoning mode (Qwen3)
+  device?: "auto" | "gpu" | "cpu",
+  dtype?: "q4" | "q8" | "fp16" | "fp32",
+})
+```
+
+## Specification
+
+Gerbil implements `LanguageModelV2` from `@ai-sdk/provider`:
+
+- `specificationVersion: "v2"`
+- Streaming with `text-start`, `text-delta`, `text-end`, `finish` events
+- Reasoning content type for thinking mode
+
+

package/docs/architecture/README.md

@@ -0,0 +1,84 @@
+# Gerbil Architecture
+
+Technical deep-dive into how Gerbil works under the hood.
+
+## Contents
+
+| Document | Description |
+|----------|-------------|
+| [Overview](./overview.md) | High-level architecture and design decisions |
+| [Inference Pipeline](./inference.md) | ONNX Runtime, transformers.js, quantization |
+| [WebGPU](./webgpu.md) | GPU acceleration in browser and Node.js |
+| [Streaming](./streaming.md) | Web Worker architecture and token streaming |
+| [Caching](./caching.md) | Model caching strategies |
+
+## Quick Overview
+
+```
+┌───────────────────────────────────────────────────────────────────┐
+│                         Your Application                          │
+├───────────────────────────────────────────────────────────────────┤
+│                                                                   │
+│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐    │
+│  │   Browser   │    │   Node.js   │    │      CLI/REPL       │    │
+│  │  (WebGPU)   │    │ (CPU/WebGPU)│    │    (CPU/WebGPU)     │    │
+│  └──────┬──────┘    └──────┬──────┘    └──────────┬──────────┘    │
+│         │                  │                       │              │
+│         ▼                  ▼                       ▼              │
+│  ┌─────────────────────────────────────────────────────────────┐  │
+│  │                     Gerbil Core                             │  │
+│  │  ┌─────────┐  ┌──────────┐  ┌────────┐  ┌───────────────┐   │  │
+│  │  │ Models  │  │ Generate │  │ Stream │  │ JSON/Embed    │   │  │
+│  │  └────┬────┘  └────┬─────┘  └───┬────┘  └───────┬───────┘   │  │
+│  └───────┼────────────┼────────────┼───────────────┼───────────┘  │
+│          │            │            │               │              │
+│          ▼            ▼            ▼               ▼              │
+│  ┌─────────────────────────────────────────────────────────────┐  │
+│  │                   transformers.js                           │  │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │  │
+│  │  │  Tokenizer  │  │    Model    │  │   TextStreamer      │  │  │
+│  │  └─────────────┘  └──────┬──────┘  └─────────────────────┘  │  │
+│  └──────────────────────────┼──────────────────────────────────┘  │
+│                             │                                     │
+│                             ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────┐  │
+│  │                    ONNX Runtime                             │  │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │  │
+│  │  │   WebGPU    │  │     CPU     │  │       WASM          │  │  │
+│  │  │  (Browser)  │  │   (Node.js) │  │   (Fallback)        │  │  │
+│  │  └─────────────┘  └─────────────┘  └─────────────────────┘  │  │
+│  └─────────────────────────────────────────────────────────────┘  │
+│                                                                   │
+└───────────────────────────────────────────────────────────────────┘
+```
+
+## Key Design Decisions
+
+### 1. transformers.js as the Foundation
+
+We use [Hugging Face transformers.js](https://huggingface.co/docs/transformers.js) which provides:
+- Pre-converted ONNX models from Hugging Face Hub
+- Tokenizers that match the original models exactly
+- Unified API across CPU/GPU/WASM backends
+
+### 2. WebGPU First
+
+WebGPU provides 5-10x speedup over CPU for inference:
+- **Browser**: Native WebGPU via `navigator.gpu`
+- **Node.js**: Headless Chrome as a WebGPU accelerator (ChromeGPUBackend)
+
+### 3. Quantization for Speed
+
+All models use quantized weights:
+- **q4f16**: 4-bit weights, fp16 compute (WebGPU)
+- **q4**: 4-bit weights, fp32 compute (CPU/WASM)
+
+This reduces model size by ~4x and improves inference speed.
+
+### 4. Streaming via Web Workers
+
+Browser inference runs in a Web Worker to:
+- Keep the UI responsive during model loading
+- Stream tokens in real-time without blocking
+- Isolate GPU memory from the main thread
+