@tryhamster/gerbil 1.0.0-rc.0

package/docs/skills.md

@@ -0,0 +1,261 @@
+# Gerbil Skills
+
+Skills are reusable AI tasks with Zod-validated inputs and outputs.
+
+## Built-in Skills
+
+```typescript
+import { 
+  commit, summarize, explain, review, 
+  test, translate, extract, title 
+} from "@tryhamster/gerbil/skills";
+```
+
+### commit
+
+Generate git commit messages from staged changes.
+
+```typescript
+const msg = await commit({ 
+  type: "conventional",  // "conventional" | "simple" | "detailed"
+  maxLength: 72 
+});
+```
+
+### summarize
+
+Summarize content.
+
+```typescript
+const summary = await summarize({ 
+  content: document,
+  length: "short",      // "short" | "medium" | "long"
+  format: "bullets",    // "paragraph" | "bullets"
+  focus: ["key points"]
+});
+```
+
+### explain
+
+Explain code or concepts.
+
+```typescript
+const explanation = await explain({ 
+  content: code,
+  level: "beginner",    // "beginner" | "intermediate" | "expert"
+  language: "typescript"
+});
+```
+
+### review
+
+Code review.
+
+```typescript
+const feedback = await review({ 
+  code,
+  focus: ["security", "performance"],  // "security" | "performance" | "style" | "bugs" | "all"
+  format: "detailed"                    // "inline" | "summary" | "detailed"
+});
+```
+
+### test
+
+Generate tests.
+
+```typescript
+const tests = await test({ 
+  code,
+  framework: "vitest",  // "jest" | "vitest" | "mocha" | "playwright"
+  style: "unit"         // "unit" | "integration" | "e2e"
+});
+```
+
+### translate
+
+Translate text.
+
+```typescript
+const spanish = await translate({ 
+  text,
+  to: "es",
+  from: "en",           // optional, auto-detected
+  preserveFormatting: true
+});
+```
+
+### extract
+
+Extract structured data.
+
+```typescript
+const data = await extract({ 
+  content: "John is 32 and lives in NYC",
+  schema: z.object({ name: z.string(), age: z.number(), city: z.string() }),
+  context: "Extract person info"
+});
+```
+
+### title
+
+Generate titles.
+
+```typescript
+const heading = await title({ 
+  content: article,
+  style: "seo",         // "professional" | "clickbait" | "seo" | "simple"
+  maxLength: 60
+});
+```
+
+## Custom Skills
+
+### defineSkill
+
+Create a custom skill:
+
+```typescript
+import { defineSkill } from "@tryhamster/gerbil/skills";
+import { z } from "zod";
+
+export const sentiment = defineSkill({
+  // Required
+  name: "sentiment",           // kebab-case
+  description: "Analyze text sentiment",
+  
+  // Input/Output validation
+  input: z.object({ 
+    text: z.string(),
+    detailed: z.boolean().default(false)
+  }),
+  output: z.object({
+    sentiment: z.enum(["positive", "negative", "neutral"]),
+    confidence: z.number(),
+    keywords: z.array(z.string()).optional()
+  }),
+  
+  // Defaults
+  temperature: 0.3,
+  maxTokens: 100,
+  thinking: false,
+  
+  // Model (skill loads this automatically if different from current)
+  model: "qwen2.5-coder-0.5b",
+  
+  // Metadata
+  version: "1.0.0",
+  author: "your-name",
+  
+  // Implementation - receives (input, gerbil)
+  async run(input, gerbil) {
+    const prompt = input.detailed
+      ? `Analyze sentiment with keywords: ${input.text}`
+      : `What is the sentiment: ${input.text}`;
+    
+    return gerbil.json(prompt, { schema: this.output });
+  },
+});
+```
+
+### File Convention
+
+Skills can be loaded from files matching `*.skill.ts` or `*.skill.js`:
+
+```typescript
+// skills/sentiment.skill.ts
+import { defineSkill } from "@tryhamster/gerbil/skills";
+
+export default defineSkill({
+  name: "sentiment",
+  // ...
+});
+```
+
+### Loading Skills
+
+```typescript
+import { loadSkills, loadSkillPackage, useSkill } from "@tryhamster/gerbil/skills";
+
+// Load from directory
+await loadSkills("./skills");  // loads *.skill.ts files
+
+// Load from npm package
+await loadSkillPackage("gerbil-skills-extra");
+
+// Use by name
+const sentiment = useSkill("sentiment");
+const result = await sentiment({ text: "I love this!" });
+```
+
+### Skill-Specific Models
+
+Skills can specify which model they prefer:
+
+```typescript
+export const codeReview = defineSkill({
+  name: "code-review",
+  description: "Review code for issues",
+  model: "qwen2.5-coder-0.5b",  // Uses coder model
+  
+  async run(input, gerbil) {
+    // gerbil is already loaded with qwen2.5-coder-0.5b
+    return gerbil.generate(`Review this code: ${input.code}`);
+  },
+});
+```
+
+When a skill specifies a different model than the currently loaded one, Gerbil automatically switches models. To avoid this overhead, you can pre-load the skill's model or pass your own Gerbil instance:
+
+```typescript
+// Option 1: Let skill switch automatically (may incur loading time)
+const result = await codeReview({ code: myCode });
+
+// Option 2: Pass pre-loaded Gerbil instance
+const g = new Gerbil();
+await g.loadModel("qwen2.5-coder-0.5b");
+const result = await codeReview.run({ code: myCode }, g);
+```
+
+### Registry API
+
+```typescript
+import { 
+  listSkills,     // Get all skill names
+  getSkillInfo,   // Get skill metadata
+  hasSkill,       // Check if skill exists
+  removeSkill,    // Unregister a skill
+  clearSkills     // Clear all skills
+} from "@tryhamster/gerbil/skills";
+
+console.log(listSkills());
+// ["commit", "summarize", "explain", "review", ...]
+
+const info = getSkillInfo("commit");
+// { name, description, version, author, builtin: true }
+```
+
+## REPL Skills View
+
+In the Gerbil REPL, press `2` or navigate to **Skills** to access all available skills.
+
+**Controls:**
+- **Up/Down** — Navigate skill list
+- **Enter** — Select and run a skill
+- **c** — Create a new skill (opens wizard)
+- **Esc** — Back to menu
+
+The first option **"+ Create new skill"** opens a guided wizard that helps you build a custom skill step-by-step.
+
+---
+
+## MCP Integration
+
+Skills are automatically exposed as MCP tools:
+
+```bash
+gerbil serve --mcp
+```
+
+Each skill becomes a tool: `gerbil_commit`, `gerbil_summarize`, etc.
+
+Custom skills loaded via `loadSkills()` are also exposed.

package/docs/tools.md

@@ -0,0 +1,304 @@
+# Gerbil Tools & Agents
+
+Gerbil supports tool calling with Qwen3 models, enabling agentic workflows where the LLM can call functions to accomplish tasks.
+
+## Quick Start
+
+### Simple Tool (Recommended)
+
+Create a file in `.gerbil/tools/` with the `.tool.ts` extension:
+
+```typescript
+// .gerbil/tools/get_weather.tool.ts
+
+export default {
+  name: "get_weather",
+  description: "Get current weather for a city",
+  parameters: {
+    city: { type: "string", description: "City name" },
+  },
+  execute: async (params: { city: string }) => {
+    return `Weather in ${params.city}: 72°F, sunny`;
+  },
+};
+```
+
+That's it! Gerbil automatically loads tools from `.gerbil/tools/` when the REPL starts.
+
+### Advanced Tool (with Zod)
+
+For more complex validation, use `defineTool` with Zod schemas:
+
+```typescript
+import { defineTool } from "@tryhamster/gerbil";
+import { z } from "zod";
+
+export const weatherTool = defineTool({
+  name: "get_weather",
+  description: "Get current weather for a city",
+  parameters: z.object({
+    city: z.string().describe("City name"),
+    units: z.enum(["celsius", "fahrenheit"]).optional().default("fahrenheit"),
+  }),
+  execute: async ({ city, units }) => {
+    return `Weather in ${city}: ${units === "celsius" ? "22°C" : "72°F"}, sunny`;
+  },
+});
+```
+
+## Project Tools
+
+Store your custom tools in `.gerbil/tools/`:
+
+```
+.gerbil/
+└── tools/
+    ├── get_weather.tool.ts
+    ├── search_docs.tool.ts
+    └── calculator.tool.ts
+```
+
+### Tool File Format
+
+Each `.tool.ts` file exports a config object:
+
+```typescript
+// .gerbil/tools/my_tool.tool.ts
+
+export default {
+  name: "my_tool",                    // Tool name (snake_case)
+  description: "What the tool does",  // LLM uses this to decide when to call
+  parameters: {                       // Optional input parameters
+    param1: { type: "string", description: "First param" },
+    param2: { type: "number", optional: true },
+  },
+  execute: async (params) => {
+    // Your implementation
+    return "result string";
+  },
+};
+```
+
+### Managing Tools in REPL
+
+Press `3` or select **Tools** from the menu to:
+- View all registered tools (builtin + project)
+- Create new tools with the guided wizard
+- Execute tools directly with `x`
+- Open tool files in VS Code with `o`
+
+## Built-in Tools
+
+### `gerbil_docs`
+
+Search Gerbil documentation for any topic.
+
+```typescript
+import { docsTool } from "@tryhamster/gerbil";
+
+const result = await docsTool({ query: "streaming" });
+// Returns documentation about streaming responses
+```
+
+**Available topics:**
+- `quickstart` — Getting started
+- `generate` — Text generation options
+- `stream` — Streaming responses
+- `json` — Structured JSON output
+- `thinking` — Chain-of-thought reasoning
+- `embed` — Embeddings
+- `models` — Available models
+- `ai-sdk` — Vercel AI SDK integration
+- `next`, `express`, `react`, `hono` — Framework integrations
+- `skills` — Skills system
+- `cli` — CLI commands
+- `tools` — Tool calling
+
+## Tool Examples
+
+### Calculator
+
+```typescript
+// .gerbil/tools/calculator.tool.ts
+
+export default {
+  name: "calculator",
+  description: "Perform basic math calculations",
+  parameters: {
+    expression: { type: "string", description: "Math expression like '2 + 2'" },
+  },
+  execute: async (params: { expression: string }) => {
+    try {
+      // Simple evaluator (use a proper math lib in production)
+      const result = Function(`return ${params.expression}`)();
+      return `${params.expression} = ${result}`;
+    } catch {
+      return `Error: Invalid expression "${params.expression}"`;
+    }
+  },
+};
+```
+
+### File Reader
+
+```typescript
+// .gerbil/tools/read_file.tool.ts
+
+import fs from "fs/promises";
+
+export default {
+  name: "read_file",
+  description: "Read contents of a file",
+  parameters: {
+    path: { type: "string", description: "File path to read" },
+  },
+  execute: async (params: { path: string }) => {
+    try {
+      const content = await fs.readFile(params.path, "utf-8");
+      return content.slice(0, 2000); // Limit output size
+    } catch (e) {
+      return `Error reading file: ${e}`;
+    }
+  },
+};
+```
+
+### API Caller
+
+```typescript
+// .gerbil/tools/fetch_url.tool.ts
+
+export default {
+  name: "fetch_url",
+  description: "Fetch content from a URL",
+  parameters: {
+    url: { type: "string", description: "URL to fetch" },
+  },
+  execute: async (params: { url: string }) => {
+    try {
+      const res = await fetch(params.url);
+      const text = await res.text();
+      return text.slice(0, 2000);
+    } catch (e) {
+      return `Error fetching URL: ${e}`;
+    }
+  },
+};
+```
+
+### Joke Generator
+
+```typescript
+// .gerbil/tools/generate_joke.tool.ts
+
+export default {
+  name: "generate_joke",
+  description: "Generates a joke based on a theme",
+  parameters: {
+    theme: { type: "string", description: "The theme (optional)", optional: true },
+  },
+  execute: async (params: { theme?: string }) => {
+    const theme = params?.theme || "programming";
+    const jokes: Record<string, string> = {
+      programming: "Why do programmers prefer dark mode? Because light attracts bugs!",
+      coffee: "Why do Java developers wear glasses? Because they can't C#!",
+      ai: "Why did the neural network break up with the algorithm? Too many trust issues!",
+    };
+    return jokes[theme.toLowerCase()] || `Why did the ${theme} cross the road? To optimize the other side!`;
+  },
+};
+```
+
+## Tool Registry API
+
+```typescript
+import { 
+  defineTool, 
+  getTool, 
+  listTools, 
+  getToolDefinitions,
+  loadProjectTools
+} from "@tryhamster/gerbil";
+
+// Load tools from .gerbil/tools/
+await loadProjectTools();
+
+// Get tool by name
+const tool = getTool("get_weather");
+await tool({ city: "NYC" });
+
+// List all tool names
+console.log(listTools());
+// ["gerbil_docs", "get_weather", "calculator"]
+
+// Get all definitions (for prompt injection)
+const definitions = getToolDefinitions();
+```
+
+## Using Tools in Chat
+
+### REPL Agent Mode
+
+The easiest way to use tools is in the REPL's Agent mode:
+
+```bash
+gerbil repl
+# Press ⌘A (Cmd+A) to toggle agent mode
+```
+
+**Toggle shortcuts:**
+- **⌘A (Cmd+A)**: Toggle agent mode on/off (works anywhere)
+- **⌘T (Cmd+T)**: Toggle thinking mode on/off
+
+When agent mode is enabled:
+- Shows `+tools` badge in the header
+- Tool calls display in cyan boxes with results
+- Works with any chat persona
+
+In Agent mode, the model can:
+1. See available tools in its system prompt
+2. Call tools using the `<tool_call>` format
+3. Receive tool results and synthesize a response
+
+### Programmatic Usage
+
+```typescript
+import { 
+  formatToolsForPrompt, 
+  parseToolCall, 
+  executeToolCall,
+  getToolDefinitions 
+} from "@tryhamster/gerbil";
+
+// Add tools to system prompt
+const tools = getToolDefinitions();
+const systemPrompt = `You are a helpful assistant.\n\n${formatToolsForPrompt(tools)}`;
+
+// Generate response
+const response = await gerbil.generate(userQuery, { system: systemPrompt });
+
+// Check for tool calls
+const toolCall = parseToolCall(response.text);
+if (toolCall) {
+  const result = await executeToolCall(toolCall.tool, toolCall.params);
+  // Continue conversation with tool result
+}
+```
+
+## Best Practices
+
+1. **Clear descriptions** — The model uses descriptions to decide when to call tools
+2. **Handle missing params** — Use defaults for optional parameters
+3. **Limit output size** — Long tool outputs consume context (aim for <2000 chars)
+4. **Return strings** — Execute function must return a string
+5. **Graceful errors** — Catch exceptions and return helpful error messages
+6. **Snake_case names** — Use `get_weather` not `getWeather`
+
+## Model Compatibility
+
+Tool calling works best with:
+- **Qwen3-0.6B** — Excellent tool calling support, fast
+- **Qwen3-1.7B** — Better reasoning, still fast
+- **Qwen2.5 models** — Good support
+
+Smaller models (SmolLM2) may struggle with consistent tool call formatting.