@tryhamster/gerbil 1.1.2 → 1.2.0

package/docs/skills.md

@@ -1,261 +0,0 @@
-# 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/structured-output.md

@@ -1,123 +0,0 @@
-# Structured Output
-
-Gerbil can make a model return a **JSON object** instead of free-form text. The engine
-generates, extracts the JSON from the output, validates it, and — if it fails — retries with
-a corrective nudge until the result is valid or the retry budget is exhausted.
-
-This is available at three levels:
-
-- **Engine** — `WebGPUEngine.generateObject()` (lowest level)
-- **`Gerbil` class** — `g.generateObject()` (Node-facing wrapper)
-- **One-liner** — `generateObject()` (zero-setup singleton)
-- **React** — the `useObject` hook (`@tryhamster/gerbil/gpu/hooks`)
-
-> `generateObject` is distinct from the Zod-driven `Gerbil.json()`. `json()` parses against a
-> Zod schema; `generateObject()` validates with a predicate or a minimal
-> `{ required: [...] }` schema and is the same code path the `useObject` hook uses.
-
-## Validation
-
-The `schema` option is an `ObjectValidator`, either:
-
-- **A predicate** `(o: unknown) => boolean` — full control; return `true` when the parsed
-  value is acceptable.
-- **A minimal schema object** `{ required: string[]; properties?: Record<string, unknown> }`
-  — only the `required` key set is enforced (every key must exist on the parsed object).
-- **Omitted** — any syntactically valid JSON value (object or array) is accepted.
-
-`maxRetries` (default `4`) is the number of retries **after** the first attempt, so up to
-`maxRetries + 1` generations run. The result includes `attempts` (1 = first try).
-
-## Engine
-
-```typescript
-import { WebGPUEngine } from "@tryhamster/gerbil/gpu";
-
-const engine = await WebGPUEngine.create({ repo: "mlx-community/Qwen3.5-0.8B-4bit" });
-
-const { object, text, attempts } = await engine.generateObject(
-  'Extract {name, age} from: "I am Sarah, 28"',
-  { schema: { required: ["name", "age"] }, maxRetries: 4 },
-);
-// object === { name: "Sarah", age: 28 }
-```
-
-`generateObject` extends the engine's `GenerateOptions`, so `maxTokens`, `systemPrompt`, and
-`sampling` (e.g. `{ temperature: 0.2 }`) are all available.
-
-## `Gerbil` class
-
-```typescript
-import { Gerbil } from "@tryhamster/gerbil";
-
-const g = new Gerbil();
-await g.loadModel("qwen3.5-0.8b");
-
-const { object } = await g.generateObject<{ primes: number[] }>(
-  "List the first 3 primes as {primes: number[]}",
-  { schema: (o) => Array.isArray((o as any).primes) },
-);
-```
-
-## One-liner
-
-```typescript
-import { generateObject } from "@tryhamster/gerbil";
-
-const { object } = await generateObject(
-  "Return {ok: true}",
-  { model: "qwen3.5-0.8b", schema: { required: ["ok"] } },
-);
-```
-
-## React (`useObject`)
-
-```tsx
-import { useObject } from "@tryhamster/gerbil/gpu/hooks";
-
-function CityExtractor() {
-  const { generate, object, isGenerating, attempts } = useObject<{ city: string }>({
-    model: "mlx-community/Qwen3.5-0.8B-4bit",
-  });
-
-  return (
-    <div>
-      <button
-        disabled={isGenerating}
-        onClick={() =>
-          generate("Extract the city: I live in Paris", { schema: { required: ["city"] } })
-        }
-      >
-        Extract
-      </button>
-      {object && <pre>{JSON.stringify(object, null, 2)} ({attempts} attempts)</pre>}
-    </div>
-  );
-}
-```
-
-## CLI
-
-```bash
-# Inline, no schema (any valid JSON accepted)
-gerbil object "Return {ok: true} as JSON"
-
-# With a schema file (a minimal { required: [...] } validator)
-echo '{ "required": ["name", "age"] }' > person.json
-gerbil object "Extract {name, age}: I am Sarah, 28" --schema person.json
-
-# Flags: --model, --max-tokens, --temperature, --retries, --schema
-```
-
-The command prints the parsed object as pretty JSON followed by the attempt count.
-
-## Types
-
-```typescript
-import type {
-  GenerateObjectOptions,
-  GenerateObjectResult,
-  ObjectSchema,
-  ObjectValidator,
-} from "@tryhamster/gerbil";
-```

package/docs/stt.md

@@ -1,111 +0,0 @@
-# Speech-to-Text (STT)
-
-Gerbil transcribes audio with **Moonshine** — a native, raw-waveform encoder/decoder STT
-model (no FFT, no log-mel) running on the WebGPU engine. It uses a Conv1d front-end over the
-raw waveform, encodes once, then autoregressively decodes with cross-attention into the
-frozen encoder K/V. No ONNX, no API keys.
-
-> **Pre-1.0.** Moonshine is the only STT path. The old Whisper ONNX/transformers.js lane has
-> been removed. The `Gerbil`-class `transcribe()` method still works but now runs native
-> Moonshine under the hood (see [below](#gerbil-class-transcribe-native-wrapper)).
-
-## Quick Start
-
-Moonshine has its own engine class, `MoonshineSTT`. Feed it raw **16 kHz mono PCM**
-(`Float32Array`).
-
-```typescript
-import { MoonshineSTT } from "@tryhamster/gerbil/gpu";
-
-const stt = await MoonshineSTT.create({ repo: "UsefulSensors/moonshine-base" });
-
-// pcm: Float32Array, 16 kHz mono
-const result = await stt.transcribe(pcm);
-console.log(result.text);
-
-stt.destroy();
-```
-
-## API
-
-### `MoonshineSTT.create(options?)`
-
-```typescript
-interface MoonshineSTTOptions {
-  /** HF repo (default "UsefulSensors/moonshine-base"). */
-  repo?: string;
-  revision?: string;
-  hfToken?: string;
-  cacheDir?: string;
-  onProgress?: (loaded: number, total: number, message: string) => void;
-}
-```
-
-### `transcribe(pcm, options?)`
-
-```typescript
-interface TranscribeOptions {
-  /** Stop after this many decoded tokens (default 194). */
-  maxNewTokens?: number;
-}
-
-interface TranscribeResult {
-  text: string;
-  /** Decoded token ids (excluding the start token, including trailing EOS). */
-  tokens: number[];
-  /** Encoder frames produced by the conv frontend. */
-  encoderFrames: number;
-  /** Audio duration in seconds (samples / 16000). */
-  audioSeconds: number;
-}
-```
-
-`pcm` must be raw 16 kHz mono `Float32Array` samples. If your audio is a WAV file or at a
-different sample rate, decode and resample it to 16 kHz first.
-
-### Decoding / resampling helpers
-
-```typescript
-// Reuse the audio utilities from the core package to get 16 kHz mono PCM.
-import { decodeWav, resampleAudio } from "@tryhamster/gerbil/core/stt";
-
-const { audio, sampleRate } = decodeWav(wavUint8Array);
-const pcm16k = sampleRate === 16000 ? audio : resampleAudio(audio, sampleRate, 16000);
-
-const { text } = await stt.transcribe(pcm16k);
-```
-
-## Model
-
-### Moonshine
-
-- **Architecture:** `MoonshineForConditionalGeneration` (encoder-decoder)
-- **Front-end:** raw-waveform Conv1d (no FFT / log-mel)
-- **Default repo:** `UsefulSensors/moonshine-base`
-- **Sample rate:** 16 kHz mono
-- **Language:** English (the native engine is English-only; multilingual Whisper has been removed).
-
----
-
-## `Gerbil`-class `transcribe()` (native wrapper)
-
-> The Whisper ONNX/transformers.js lane (and its multilingual support) has been removed. The
-> `Gerbil`-class `transcribe()` method now runs native Moonshine: it requires WebGPU,
-> accepts 16 kHz mono `Float32Array` PCM (not WAV bytes), is English-only, and does not
-> produce timestamps. The browser `useVoiceInput` hook is gone — use `useSTT` from
-> `@tryhamster/gerbil/gpu/hooks`. The AI SDK `gerbil.transcription()` provider also routes
-> through this native path.
-
-```typescript
-import { Gerbil } from "@tryhamster/gerbil";
-
-const g = new Gerbil();
-const pcm16kMono = /* Float32Array @ 16 kHz */;
-const result = await g.transcribe(pcm16kMono);
-console.log(result.text);
-```
-
-## See Also
-
-- [Text-to-Speech (TTS)](./tts.md) — native Kani-TTS-2
-- [Browser Hooks](./browser.md) — React hooks