@tryhamster/gerbil 1.0.0-rc.0 → 1.0.0-rc.1

package/dist/frameworks/express.d.mts

@@ -1,4 +1,4 @@
-import { s as GerbilConfig } from "../types-BS1N92Jt.mjs";
+import { c as GerbilConfig } from "../types-s6Py2_DL.mjs";
 import { Request, Response, Router } from "express";
 
 //#region src/frameworks/express.d.ts

package/dist/frameworks/express.mjs

@@ -1,7 +1,7 @@
 import { t as __require } from "../chunk-Ct1HF2bE.mjs";
-import "../models-DKULvhOr.mjs";
-import "../utils-7vXqtq2Q.mjs";
-import { t as Gerbil } from "../gerbil-BfnsFWRE.mjs";
+import { t as Gerbil } from "../gerbil-yoSpRHgv.mjs";
+import "../models-BAtL8qsA.mjs";
+import "../utils-CkB4Roi6.mjs";
 
 //#region src/frameworks/express.ts
 /**

package/dist/frameworks/fastify.d.mts

@@ -1,4 +1,4 @@
-import { s as GerbilConfig } from "../types-BS1N92Jt.mjs";
+import { c as GerbilConfig } from "../types-s6Py2_DL.mjs";
 
 //#region src/frameworks/fastify.d.ts
 

package/dist/frameworks/fastify.mjs

@@ -1,6 +1,6 @@
-import "../models-DKULvhOr.mjs";
-import "../utils-7vXqtq2Q.mjs";
-import { t as Gerbil } from "../gerbil-BfnsFWRE.mjs";
+import { t as Gerbil } from "../gerbil-yoSpRHgv.mjs";
+import "../models-BAtL8qsA.mjs";
+import "../utils-CkB4Roi6.mjs";
 
 //#region src/frameworks/fastify.ts
 /**

package/dist/frameworks/hono.d.mts

@@ -1,4 +1,4 @@
-import { s as GerbilConfig } from "../types-BS1N92Jt.mjs";
+import { c as GerbilConfig } from "../types-s6Py2_DL.mjs";
 import * as hono0 from "hono";
 import * as hono_types0 from "hono/types";
 

package/dist/frameworks/hono.mjs

@@ -1,6 +1,6 @@
-import "../models-DKULvhOr.mjs";
-import "../utils-7vXqtq2Q.mjs";
-import { t as Gerbil } from "../gerbil-BfnsFWRE.mjs";
+import { t as Gerbil } from "../gerbil-yoSpRHgv.mjs";
+import "../models-BAtL8qsA.mjs";
+import "../utils-CkB4Roi6.mjs";
 
 //#region src/frameworks/hono.ts
 /**

package/dist/frameworks/next.d.mts

@@ -1,5 +1,5 @@
-import { s as GerbilConfig } from "../types-BS1N92Jt.mjs";
-import { t as Gerbil } from "../gerbil-DZ1k3ChC.mjs";
+import { c as GerbilConfig } from "../types-s6Py2_DL.mjs";
+import { t as Gerbil } from "../gerbil-POAz8peb.mjs";
 
 //#region src/frameworks/next.d.ts
 

package/dist/frameworks/next.mjs

@@ -1,6 +1,6 @@
-import "../models-DKULvhOr.mjs";
-import "../utils-7vXqtq2Q.mjs";
-import { t as Gerbil } from "../gerbil-BfnsFWRE.mjs";
+import { t as Gerbil } from "../gerbil-yoSpRHgv.mjs";
+import "../models-BAtL8qsA.mjs";
+import "../utils-CkB4Roi6.mjs";
 
 //#region src/frameworks/next.ts
 /**

package/dist/frameworks/react.d.mts

@@ -1,4 +1,4 @@
-import { a as GenerateOptions, o as GenerateResult, s as GerbilConfig } from "../types-BS1N92Jt.mjs";
+import { c as GerbilConfig, o as GenerateOptions, s as GenerateResult } from "../types-s6Py2_DL.mjs";
 
 //#region src/frameworks/react.d.ts
 

package/dist/frameworks/trpc.d.mts

@@ -1,4 +1,4 @@
-import { s as GerbilConfig } from "../types-BS1N92Jt.mjs";
+import { c as GerbilConfig } from "../types-s6Py2_DL.mjs";
 
 //#region src/frameworks/trpc.d.ts
 

package/dist/frameworks/trpc.mjs

@@ -1,6 +1,6 @@
-import "../models-DKULvhOr.mjs";
-import "../utils-7vXqtq2Q.mjs";
-import { t as Gerbil } from "../gerbil-BfnsFWRE.mjs";
+import { t as Gerbil } from "../gerbil-yoSpRHgv.mjs";
+import "../models-BAtL8qsA.mjs";
+import "../utils-CkB4Roi6.mjs";
 import { z } from "zod";
 
 //#region src/frameworks/trpc.ts

package/dist/gerbil-DeQlX_Mt.mjs

@@ -0,0 +1,5 @@
+import { t as Gerbil } from "./gerbil-yoSpRHgv.mjs";
+import "./models-BAtL8qsA.mjs";
+import "./utils-CkB4Roi6.mjs";
+
+export { Gerbil };

package/dist/gerbil-POAz8peb.d.mts

@@ -0,0 +1,431 @@
+import { C as SpeakResult, E as SystemInfo, O as TranscribeOptions, S as SpeakOptions, T as StreamingTranscriptionSession, b as STTModelConfig, c as GerbilConfig, f as JsonOptions, g as ModelConfig, h as LoadTTSOptions, i as EmbedResult, j as VoiceInfo, k as TranscribeResult, m as LoadSTTOptions, o as GenerateOptions, p as LoadOptions, r as EmbedOptions, s as GenerateResult, t as AudioChunk, w as StreamingTranscriptionOptions, x as SessionStats } from "./types-s6Py2_DL.mjs";
+
+//#region src/core/gerbil.d.ts
+
+declare class Gerbil {
+  private generator;
+  private tokenizer;
+  private model;
+  private embedder;
+  private currentModel;
+  private modelConfig;
+  private readonly config;
+  private stats;
+  private useDirect;
+  private chromeBackend;
+  private _deviceMode;
+  private processor;
+  private visionModel;
+  private isVisionModel;
+  constructor(config?: GerbilConfig);
+  static listModels(): ModelConfig[];
+  static getModel(modelId: string): ModelConfig | undefined;
+  /**
+   * Load a model
+   *
+   * @example
+   * ```ts
+   * // Built-in model
+   * await g.loadModel("qwen3-0.6b");
+   *
+   * // HuggingFace model
+   * await g.loadModel("hf:microsoft/Phi-3-mini");
+   *
+   * // Local model
+   * await g.loadModel("file:./models/my-model");
+   *
+   * // Vision model
+   * await g.loadModel("ministral-3b");
+   * ```
+   */
+  loadModel(modelId?: string, options?: LoadOptions): Promise<void>;
+  /**
+   * Load a vision model (VLM)
+   * Uses AutoProcessor + AutoModelForImageTextToText instead of tokenizer + causal LM
+   */
+  private loadVisionModel;
+  /**
+   * Check if a model is loaded
+   */
+  isLoaded(): boolean;
+  /**
+   * Check if current model supports vision
+   */
+  supportsVision(): boolean;
+  /**
+   * Get current model info
+   */
+  getModelInfo(): ModelConfig | null;
+  /**
+   * Get current device mode (webgpu, cpu, or wasm)
+   */
+  getDeviceMode(): "webgpu" | "cpu" | "wasm";
+  /**
+   * Get dtype used for current model
+   */
+  getDtype(): string;
+  /**
+   * Get response cache statistics
+   */
+  getResponseCacheStats(): {
+    hits: number;
+    misses: number;
+    size: number;
+    hitRate: number;
+  };
+  /**
+   * Clear the response cache (for cached generate() results)
+   */
+  clearResponseCache(): void;
+  /**
+   * Get Chrome backend status (if using WebGPU via Chrome)
+   */
+  getChromeStatus(): {
+    pid: number | null;
+    port: number;
+    modelId: string;
+    startedAt: Date | null;
+  } | null;
+  /**
+   * Get Chrome memory usage (if using WebGPU via Chrome)
+   * Returns JS heap memory in bytes
+   */
+  getChromeMemory(): Promise<{
+    jsHeapUsed: number;
+    jsHeapTotal: number;
+  } | null>;
+  /**
+   * Get memory usage in GB (if using WebGPU via Chrome)
+   */
+  getMemoryUsage(): Promise<{
+    usedGB: number;
+    totalGB: number;
+    usedPercent: number;
+  } | null>;
+  /**
+   * Clear KV cache to free memory
+   * This will reset the conversation context but free up memory
+   */
+  clearCache(): Promise<void>;
+  /**
+   * Check memory usage and cleanup if needed
+   * @param thresholdGB Memory threshold in GB (default: 8)
+   * @returns true if cleanup was performed
+   */
+  checkMemoryAndCleanup(thresholdGB?: number): Promise<boolean>;
+  /**
+   * Generate text (automatically routes to vision generation if images provided)
+   *
+   * @example
+   * ```ts
+   * // Text generation
+   * const result = await g.generate("Hello!");
+   *
+   * // Vision generation (with vision model)
+   * const result = await g.generate("What's in this image?", {
+   *   images: [{ source: "https://example.com/cat.jpg" }]
+   * });
+   * ```
+   */
+  generate(prompt: string, options?: GenerateOptions): Promise<GenerateResult>;
+  /**
+   * Stream text generation (simulated token-by-token)
+   *
+   * Note: Yields the raw output including <think> tags if thinking mode is enabled.
+   * The final result has parsed thinking separated out.
+   */
+  stream(prompt: string, options?: GenerateOptions): AsyncGenerator<string, GenerateResult, unknown>;
+  /**
+   * Internal: Generate with raw text access for streaming
+   */
+  private generateRaw;
+  /**
+   * Generate text from images using a vision model
+   * Called automatically by generate() when images are provided
+   */
+  private generateWithVision;
+  /**
+   * Generate structured JSON output
+   */
+  json<T>(prompt: string, options: JsonOptions<T>): Promise<T>;
+  /**
+   * Generate embeddings
+   */
+  embed(text: string, options?: EmbedOptions): Promise<EmbedResult>;
+  /**
+   * Generate embeddings for multiple texts
+   */
+  embedBatch(texts: string[], options?: EmbedOptions): Promise<EmbedResult[]>;
+  /**
+   * Get session stats
+   */
+  getStats(): SessionStats;
+  /**
+   * Get system info
+   */
+  getInfo(): SystemInfo;
+  /**
+   * Reset stats
+   */
+  resetStats(): void;
+  private tts;
+  private ttsModelId;
+  /**
+   * Load TTS model for text-to-speech synthesis
+   *
+   * @example
+   * ```ts
+   * // Load default (Kokoro)
+   * await g.loadTTS({ onProgress: (p) => console.log(p.status) });
+   *
+   * // Load Supertonic (faster, 44kHz output)
+   * await g.loadTTS({ model: "supertonic-66m" });
+   *
+   * const result = await g.speak("Hello world");
+   * // result.audio = Float32Array, result.sampleRate = 24000 or 44100
+   * ```
+   */
+  loadTTS(options?: LoadTTSOptions & {
+    model?: string;
+  }): Promise<void>;
+  /**
+   * Ensure TTS model is loaded (lazy loading)
+   */
+  ensureTTSLoaded(options?: LoadTTSOptions): Promise<void>;
+  /**
+   * Generate speech from text
+   *
+   * @example
+   * ```ts
+   * const result = await g.speak("Hello world", { voice: "af_bella" });
+   * // result.audio = Float32Array PCM
+   * // result.sampleRate = 24000
+   * // result.duration = seconds
+   * ```
+   */
+  speak(text: string, options?: SpeakOptions): Promise<SpeakResult>;
+  /**
+   * Stream speech generation (yields audio chunks as they're generated)
+   *
+   * @example
+   * ```ts
+   * for await (const chunk of g.speakStream("Long text...")) {
+   *   // chunk.samples = Float32Array
+   *   // chunk.isFinal = boolean
+   *   playChunk(chunk);
+   * }
+   * ```
+   */
+  speakStream(text: string, options?: SpeakOptions): AsyncGenerator<AudioChunk, SpeakResult, unknown>;
+  /**
+   * Get list of available TTS voices
+   */
+  listVoices(): VoiceInfo[];
+  /**
+   * Check if TTS model is loaded
+   */
+  isTTSLoaded(): boolean;
+  /**
+   * Get current TTS model info
+   */
+  getTTSModelInfo(): {
+    id: string;
+    loaded: boolean;
+    device?: "webgpu" | "cpu";
+  } | null;
+  /**
+   * List available TTS models
+   */
+  listTTSModels(): Promise<Array<{
+    id: string;
+    description: string;
+    sampleRate: number;
+    voiceCount: number;
+  }>>;
+  private stt;
+  /**
+   * Load STT model for speech-to-text transcription
+   *
+   * @example
+   * ```ts
+   * await g.loadSTT({
+   *   onProgress: (p) => console.log(p.status)
+   * });
+   *
+   * const result = await g.transcribe(audioData);
+   * console.log(result.text);
+   * ```
+   */
+  loadSTT(modelId?: string, options?: LoadSTTOptions): Promise<void>;
+  /**
+   * Ensure STT model is loaded (lazy loading)
+   */
+  ensureSTTLoaded(modelId?: string, options?: LoadSTTOptions): Promise<void>;
+  /**
+   * Transcribe audio to text
+   *
+   * @param audio - Audio data as Float32Array (16kHz mono) or Uint8Array (WAV file)
+   * @param options - Transcription options
+   *
+   * @example
+   * ```ts
+   * // From Float32Array (16kHz mono)
+   * const result = await g.transcribe(audioData);
+   * console.log(result.text);
+   *
+   * // With timestamps
+   * const result = await g.transcribe(audioData, { timestamps: true });
+   * for (const seg of result.segments) {
+   *   console.log(`[${seg.start}s] ${seg.text}`);
+   * }
+   *
+   * // From WAV file
+   * const wavData = fs.readFileSync("audio.wav");
+   * const result = await g.transcribe(new Uint8Array(wavData));
+   * ```
+   */
+  transcribe(audio: Float32Array | Uint8Array, options?: TranscribeOptions): Promise<TranscribeResult>;
+  /**
+   * Create a streaming transcription session
+   *
+   * Transcribes audio in real-time by processing chunks at regular intervals.
+   * Perfect for live captioning, call transcription, or real-time subtitles.
+   *
+   * @param options - Streaming options
+   * @returns Streaming session controller
+   *
+   * @example
+   * ```ts
+   * const session = await g.createStreamingTranscription({
+   *   chunkDuration: 3000,  // Transcribe every 3 seconds
+   *   onChunk: (text, idx) => console.log(`Chunk ${idx}: ${text}`),
+   *   onTranscript: (fullText) => console.log("Full:", fullText),
+   * });
+   *
+   * // Feed audio data as it comes in
+   * session.feedAudio(audioChunk);
+   *
+   * // Start automatic interval-based transcription
+   * session.start();
+   *
+   * // Later, stop and get final transcript
+   * const finalText = await session.stop();
+   * ```
+   */
+  createStreamingTranscription(options?: StreamingTranscriptionOptions): Promise<StreamingTranscriptionSession>;
+  /**
+   * Get list of available STT models
+   */
+  listSTTModels(): Promise<STTModelConfig[]>;
+  /**
+   * Check if STT model is loaded
+   */
+  isSTTLoaded(): boolean;
+  /**
+   * Get current STT model info
+   */
+  getSTTModelInfo(): {
+    id: string;
+    loaded: boolean;
+    device?: "webgpu" | "cpu";
+  } | null;
+  /**
+   * Record audio from microphone and transcribe
+   *
+   * @example
+   * ```ts
+   * // Record for 5 seconds and transcribe
+   * const result = await g.listen(5000);
+   * console.log(result.text);
+   *
+   * // Use with voice chat
+   * const userInput = await g.listen(10000);
+   * const response = await g.generate(userInput.text);
+   * await g.speak(response.text);
+   * ```
+   */
+  listen(durationMs?: number, options?: {
+    onProgress?: (status: string) => void;
+  }): Promise<TranscribeResult>;
+  /**
+   * Check if microphone recording is available
+   */
+  isMicrophoneAvailable(): Promise<boolean>;
+  /**
+   * Dispose of resources
+   * @param disconnect If true, also disconnect from shared browser (for clean script exit)
+   */
+  dispose(disconnect?: boolean): Promise<void>;
+  /**
+   * Shutdown the shared Chrome backend completely.
+   * Call this when your script/process is done to ensure proper cleanup.
+   * This closes the shared browser used for WebGPU acceleration.
+   */
+  static shutdown(): Promise<void>;
+  /**
+   * Get global WebGPU process info (all active backends)
+   * Useful for monitoring and debugging memory leaks
+   */
+  static getWebGPUProcesses(): Promise<{
+    browser: {
+      running: boolean;
+      pid: number | null;
+      port: number;
+      activePagesCount: number;
+      maxPages: number;
+    };
+    backends: Array<{
+      modelId: string;
+      isVision: boolean;
+      isReady: boolean;
+      memory: {
+        usedGB: number;
+        totalGB: number;
+        usedPercent: number;
+      } | null;
+    }>;
+  } | null>;
+  /**
+   * Kill all WebGPU processes (for zombie cleanup)
+   * Use this if you suspect memory leaks from undisposed Gerbil instances
+   */
+  static killAllWebGPU(): Promise<{
+    pagesKilled: number;
+    browserKilled: boolean;
+  } | null>;
+  /**
+   * Kill a specific WebGPU backend by index
+   * @param index Index of the backend to kill (0-based)
+   */
+  static killWebGPUBackend(index: number): Promise<boolean>;
+  /**
+   * Get all Chrome pages across ALL Gerbil processes
+   * This provides cross-process visibility into WebGPU backends
+   */
+  static getAllChromePagesInfo(): Promise<Array<{
+    url: string;
+    title: string;
+    isOurs: boolean;
+    modelId: string | null;
+    memory: {
+      usedGB: number;
+      totalGB: number;
+    } | null;
+  }> | null>;
+  /**
+   * Kill a Chrome page by index (works across processes)
+   * @param index Index of the page to kill (0-based)
+   */
+  static killChromePage(index: number): Promise<boolean>;
+  /**
+   * Get total Chrome page count (all processes)
+   */
+  static getTotalChromePageCount(): Promise<number>;
+  private formatPrompt;
+  private buildMessages;
+  private parseThinking;
+  private cleanOutput;
+}
+//#endregion
+export { Gerbil as t };
+//# sourceMappingURL=gerbil-POAz8peb.d.mts.map

package/dist/gerbil-POAz8peb.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gerbil-POAz8peb.d.mts","names":[],"sources":["../src/core/gerbil.ts"],"sourcesContent":[],"mappings":";;;;AAqOsB,cAlBT,MAAA,CAkBS;EAiBC,QAAA,SAAA;EAIa,QAAA,SAAA;EA0Be,QAAA,KAAA;EAAmB,QAAA,QAAA;EA8SpD,QAAA,YAAA;EA+CH,QAAA,WAAA;EAYY,iBAAA,MAAA;EAUD,QAAA,KAAA;EAWJ,QAAA,SAAA;EAW0B,QAAA,aAAA;EAyBN,QAAA,WAAA;EAA+B,QAAA,SAAA;EAAR,QAAA,WAAA;EAsNpD,QAAA,aAAA;EACe,WAAA,CAAA,MAAA,CAAA,EAxqBN,YAwqBM;EAAvB,OAAA,UAAA,CAAA,CAAA,EAvpBkB,WAupBlB,EAAA;EA0SgD,OAAA,QAAA,CAAA,OAAA,EAAA,MAAA,CAAA,EA77BjB,WA67BiB,GAAA,SAAA;EAAZ;;;;;;;;;;;;;;;;;;EAgN5B,SAAA,CAAA,OAAA,CAAA,EAAA,MAAA,EAAA,OAAA,CAAA,EAnnCsC,WAmnCtC,CAAA,EAnnCyD,OAmnCzD,CAAA,IAAA,CAAA;EACO;;;;EAyChB,QAAA,eAAA;EADqB;;;EAiDkC,QAAA,CAAA,CAAA,EAAA,OAAA;EAAiB;;;EA+B/D,cAAA,CAAA,CAAA,EAAA,OAAA;EACA;;;EAkCA,YAAA,CAAA,CAAA,EAj+BK,WAi+BL,GAAA,IAAA;EAAR;;;EAyDQ,aAAA,CAAA,CAAA,EAAA,QAAA,GAAA,KAAA,GAAA,MAAA;EAAR;;;EAiIsB,QAAA,CAAA,CAAA,EAAA,MAAA;EAkBb;;;EA6CmC,qBAAA,CAAA,CAAA,EAAA;IAkBD,IAAA,EAAA,MAAA;IAAR,MAAA,EAAA,MAAA;IAuBM,IAAA,EAAA,MAAA;IAgBJ,OAAA,EAAA,MAAA;EAAO,CAAA;;;;;;;;;;;;eApuClC;;;;;;qBAYY;;;;;;;oBAUD;;;;;;;;;gBAWJ;;;;;;+CAW0B;;;;;;;;;;;;;;;qCAyBN,kBAAuB,QAAQ;;;;;;;mCAsN5D,kBACR,uBAAuB;;;;;;;;;;;;;mCA0Sa,YAAY,KAAK,QAAQ;;;;gCAqC7B,eAAoB,QAAQ;;;;wCAyBpB,eAAoB,QAAQ;;;;cAe3D;;;;aAOD;;;;;;;;;;;;;;;;;;;;;;oBA4DY;;MAA2C;;;;4BA4BlC,iBAAiB;;;;;;;;;;;;gCAiBd,eAAoB,QAAQ;;;;;;;;;;;;;sCAmBpD,eACR,eAAe,YAAY;;;;gBAQhB;;;;;;;;;;;;;;;;mBAgCS,QACrB;;;;;;;;;;;;;;;;;;;;sCA8BuC,iBAAsB;;;;8CAkBN,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;oBA8BjE,eAAe,sBACb,oBACR,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;yCAiCA,gCACR,QAAQ;;;;mBAQY,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAiD5B,QAAQ;;;;2BAmCoB;;;;;iCAiBI;;;;;;qBA6EV;;;;;+BAUU;;;;;;;;cAQvB;;;;;;;;;;;;;;;0BA2BkB;;;;;;;;2CAkBiB;;;;;kCAkBT,QAAQ;;;;;;;;;;;;;;wCAuBF;;;;oCAgBJ"}