GerbilGerbil

Getting Started

Get up and running with Gerbil in under 5 minutes.

Installation

One-off usage — try without installing:

Terminal
npx @tryhamster/gerbil "Write a haiku about coding"

Global install — use gerbil command directly:

Terminal
npm install -g @tryhamster/gerbil

Local install — for programmatic use in your project:

Terminal
npm install @tryhamster/gerbil
Note: CLI examples on this site use gerbil and assume global install. Substitute npx @tryhamster/gerbil if using without installing.

Quick Start

One-liner API

The simplest way to use Gerbil. No setup required:

index.ts
import gerbil from "@tryhamster/gerbil";


const text = await gerbil("Explain recursion in one sentence");
console.log(text);
// → "Recursion is when a function calls itself to solve smaller instances of the same problem."

Class-based API

For more control, use the Gerbil class:

standalone.ts
01import { Gerbil } from "@tryhamster/gerbil";
02

03const g = new Gerbil();
04

05// Load a model (downloads automatically on first use)
06await g.loadModel("qwen3-0.6b");
07

08// Generate text
09const result = await g.generate("Write a haiku about coding", {
10  maxTokens: 100,
11  temperature: 0.8,
12});
13

14console.log(result.text);
15console.log(`Speed: ${result.tokensPerSecond.toFixed(1)} tok/s`);
16

17// Clean up when done
18await g.dispose();

Streaming

Stream responses token by token:

streaming.ts
import { Gerbil } from "@tryhamster/gerbil";


const g = new Gerbil();
await g.loadModel("qwen3-0.6b");


for await (const chunk of g.stream("Tell me a story")) {
  process.stdout.write(chunk);
}


await g.dispose();

Thinking Mode

Qwen3 models support chain-of-thought reasoning. Enable it to see how the model thinks:

thinking.ts
const result = await g.generate("What is 127 × 43?", { 
  thinking: true 
});


console.log("Thinking:", result.thinking);
// → "127 × 43 = 127 × 40 + 127 × 3 = 5080 + 381 = 5461"


console.log("Answer:", result.text);
// → "5461"

Structured JSON Output

Get structured data with Zod schema validation:

json.ts
import { json } from "@tryhamster/gerbil";
import { z } from "zod";


const person = await json("Extract: John is 32 and lives in NYC", {
  schema: z.object({
    name: z.string(),
    age: z.number(),
    city: z.string(),
  }),
});


console.log(person);
// → { name: "John", age: 32, city: "NYC" }

Embeddings

Generate embeddings for semantic search and RAG:

embeddings.ts
import { embed, embedBatch } from "@tryhamster/gerbil";


// Single embedding
const result = await embed("Hello world");
console.log(result.vector); // [0.123, -0.456, ...]


// Batch embeddings
const results = await embedBatch([
  "Hello world",
  "Goodbye world",
]);

Vision AI

Load a vision-capable model and pass images to your prompts:

vision.ts
01import { Gerbil } from "@tryhamster/gerbil";
02

03const g = new Gerbil();
04await g.loadModel("ministral-3b"); // Vision + reasoning model
05

06// Describe an image
07const result = await g.generate("What's in this image?", {
08  images: [{ source: "https://example.com/photo.jpg" }]
09});
10

11console.log(result.text);
12// → "A golden retriever playing fetch in a sunny park..."
13

14await g.dispose();

See the Vision documentation for more details.

Text-to-Speech

Generate natural speech with Kokoro-82M (28 voices):

tts.ts
01import { Gerbil } from "@tryhamster/gerbil";
02

03const g = new Gerbil();
04await g.loadTTS();
05

06const { audio, sampleRate } = await g.speak("Hello from Gerbil!", {
07  voice: "af_heart",
08  speed: 1.0,
09});
10

11// audio = Float32Array, sampleRate = 24000

See the Text-to-Speech documentation for all 28 voices.

Speech-to-Text

Transcribe audio with Whisper ONNX models:

stt.ts
01import { Gerbil } from "@tryhamster/gerbil";
02import { readFileSync } from "fs";
03

04const g = new Gerbil();
05await g.loadSTT("whisper-tiny.en");
06

07const audio = new Uint8Array(readFileSync("audio.wav"));
08const { text, duration } = await g.transcribe(audio);
09

10console.log(text); // "Hello world"

See the Speech-to-Text documentation for all Whisper models.

Using Any HuggingFace Model

Load any compatible model from HuggingFace:

custom-model.ts
// Short syntax
await g.loadModel("hf:microsoft/Phi-3-mini-4k-instruct-onnx");


// Full URL
await g.loadModel("https://huggingface.co/Qwen/Qwen2.5-Coder-0.5B");


// Local model
await g.loadModel("file:./models/my-fine-tune");

💡 Pro Tip: Preload Models

Download models during app initialization so users don't wait on first use:

preload.ts
// Node.js - download only (frees RAM after)
await g.preloadModel("qwen3-0.6b");


// Node.js - keep in memory for instant use
await g.preloadModel("qwen3-0.6b", { keepLoaded: true });


// Browser
import { preloadChatModel } from "@tryhamster/gerbil/browser";
await preloadChatModel("qwen3-0.6b", { keepLoaded: true });

See Browser Preloading and AI SDK Preloading for details.

Next Steps