@tryhamster/gerbil 1.0.0-rc.8 → 1.0.0

package/dist/gerbil-BT9fCydo.d.mts

@@ -0,0 +1,488 @@
+import { A as SpeakResult, C as PreloadOptions, D as SessionStats, E as SearchResult, I as TranscribeOptions, L as TranscribeResult, M as StreamingTranscriptionSession, N as SystemInfo, O as SimilarityResult, T as STTModelConfig, _ as LoadSTTOptions, a as EmbedResult, d as GerbilConfig, g as LoadOptions, h as JsonOptions, i as EmbedOptions, j as StreamingTranscriptionOptions, k as SpeakOptions, l as GenerateOptions, t as AudioChunk, u as GenerateResult, v as LoadTTSOptions, y as ModelConfig, z as VoiceInfo } from "./types-D6FiR_oh.mjs";
+import { i as GenerateObjectResult, r as GenerateObjectOptions } from "./index-jEAL2s-A.mjs";
+
+//#region src/core/gerbil.d.ts
+
+declare class Gerbil {
+  private currentModel;
+  private modelConfig;
+  private readonly config;
+  private stats;
+  private _deviceMode;
+  private webgpuEngine;
+  private nativeEmbedEngine;
+  private nativeEmbedRepo;
+  private nativeSTT;
+  private nativeTTSEngine;
+  private isVisionModel;
+  private readonly queue;
+  private readonly telemetry;
+  constructor(config?: GerbilConfig);
+  private reportError;
+  /**
+   * Whether the native (src/gpu) WebGPU engine should be used for a capability
+   * (embed / transcribe / speak / vision). The native WebGPU engine is the only
+   * inference backend, so this is always true; kept as a seam for callers.
+   */
+  private preferNative;
+  static listModels(): ModelConfig[];
+  static getModel(modelId: string): ModelConfig | undefined;
+  /**
+   * Load a model
+   *
+   * @example
+   * ```ts
+   * // Built-in model
+   * await g.loadModel("qwen3.5-0.8b");
+   *
+   * // 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) on the native WebGPU engine.
+   * The native engine loads the vision-capable safetensors checkpoint directly
+   * and builds its ViT tower on demand (enableVision: true). describeImage() then
+   * runs encode → splice → decode entirely in WebGPU compute.
+   */
+  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 the in-memory weight quantization the native engine uses for the loaded
+   * model. The WebGPU engine quantizes weights to INT4 ("q4") on load; the KV
+   * cache precision (f16/f32) is separate and device-detected.
+   */
+  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;
+  /**
+   * Check if a model is cached (downloaded) without loading it
+   *
+   * @example
+   * ```ts
+   * if (await g.isModelCached("qwen3.5-0.8b")) {
+   *   console.log("Model ready, will load instantly");
+   * } else {
+   *   console.log("Model needs to download (~400MB)");
+   * }
+   * ```
+   */
+  isModelCached(modelId: string): Promise<boolean>;
+  /**
+   * Check whether the native WebGPU engine has a repo cached on disk.
+   * The native loader stores files under ~/.cache/gerbil/<repo>/<revision>/.
+   */
+  private isNativeRepoCached;
+  /**
+   * Preload a model (download without initializing for inference)
+   *
+   * Use this to download models ahead of time, e.g., during app startup,
+   * so users don't wait when they first use AI.
+   *
+   * @example
+   * ```ts
+   * // Preload for later (download only, free memory)
+   * await g.preloadModel("qwen3.5-0.8b", {
+   *   onProgress: (p) => console.log(p.status, p.progress),
+   * });
+   *
+   * // Preload and keep in memory for instant use
+   * await g.preloadModel("qwen3.5-0.8b", { keepLoaded: true });
+   * await g.generate("Hello"); // Instant, no loading needed
+   * ```
+   */
+  preloadModel(modelId: string, options?: PreloadOptions): Promise<void>;
+  /**
+   * Check if the native TTS model is cached. The native engine always uses the
+   * Kani-TTS-2 checkpoint, so `modelId` is accepted for API compatibility only.
+   */
+  isTTSCached(_modelId?: string): Promise<boolean>;
+  /**
+   * Preload the native TTS model (downloads Kani-TTS-2 weights to disk cache).
+   *
+   * @param modelId - Accepted for API compatibility; native TTS uses Kani-TTS-2.
+   * @param options.keepLoaded - Keep the engine in memory for instant use.
+   */
+  preloadTTS(modelId?: string, options?: PreloadOptions): Promise<void>;
+  /**
+   * Check if the native STT model is cached. The native engine always uses the
+   * Moonshine checkpoint, so `modelId` is accepted for API compatibility only.
+   */
+  isSTTCached(_modelId?: string): Promise<boolean>;
+  /**
+   * Preload the native STT model (downloads Moonshine weights to disk cache).
+   *
+   * @param modelId - Accepted for API compatibility; native STT uses Moonshine.
+   * @param options.keepLoaded - Keep the engine in memory for instant use.
+   */
+  preloadSTT(modelId?: string, options?: PreloadOptions): Promise<void>;
+  /**
+   * Check if a native embedding model is cached. Defaults to the native
+   * EmbeddingGemma checkpoint when no repo is provided.
+   */
+  isEmbeddingCached(modelId?: string): Promise<boolean>;
+  /**
+   * Preload a native embedding model (downloads weights to disk cache).
+   *
+   * @param modelId - Embedding repo (default: native EmbeddingGemma).
+   * @param options.keepLoaded - Keep the engine in memory for instant use.
+   */
+  preloadEmbedding(modelId?: string, options?: PreloadOptions): Promise<void>;
+  /**
+   * Clear KV cache to free memory.
+   * The native engine manages its own KV cache; this is a no-op kept for API
+   * compatibility.
+   */
+  clearCache(): Promise<void>;
+  /**
+   * 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>;
+  /**
+   * Internal generate implementation (called within queue)
+   */
+  private generateInternal;
+  /**
+   * 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>;
+  /**
+   * Generate text from images using a vision model
+   * Called automatically by generate() when images are provided
+   */
+  private generateWithVision;
+  /**
+   * Decode an image source (http(s) URL, file path, or data URI) to raw RGB
+   * pixels for the native vision encoder. Supports 8-bit non-interlaced PNG
+   * (color types 2/RGB and 6/RGBA). Other formats throw a clear error — callers
+   * can pre-decode and use the lower-level WebGPUEngine.describeImage() with
+   * pixels directly.
+   */
+  private decodeImageToPixels;
+  /** Fetch an image source to raw bytes (URL, data URI, or local file path). */
+  private fetchImageBytes;
+  /**
+   * Generate structured JSON output
+   */
+  json<T>(prompt: string, options: JsonOptions<T>): Promise<T>;
+  /**
+   * Generate a structured object via the native engine's retrying
+   * `generateObject` (extract JSON → validate → retry with a nudge).
+   *
+   * Unlike {@link json} (which is Zod-driven), this passes through to the engine
+   * and accepts either a predicate validator `(o) => boolean` or a minimal
+   * `{ required: [...] }` schema; omit `schema` to accept any valid JSON.
+   *
+   * @example
+   * ```ts
+   * const { object } = await g.generateObject<{ name: string; age: number }>(
+   *   'Extract {name, age} from: "I am Sarah, 28"',
+   *   { schema: { required: ["name", "age"] } },
+   * );
+   * ```
+   */
+  generateObject<T = unknown>(prompt: string, options?: GenerateObjectOptions): Promise<GenerateObjectResult<T>>;
+  /**
+   * Generate embeddings
+   */
+  embed(text: string, options?: EmbedOptions): Promise<EmbedResult>;
+  /**
+   * Lazily build (or reuse) the native embedding engine. Re-creates it when the
+   * requested repo differs from the cached one. The default native embedding
+   * model is resolved by the engine itself (EmbeddingGemma) when no repo given.
+   */
+  private ensureNativeEmbedEngine;
+  /**
+   * Generate embeddings for multiple texts
+   */
+  embedBatch(texts: string[], options?: EmbedOptions): Promise<EmbedResult[]>;
+  /**
+   * Compute cosine similarity between two vectors
+   *
+   * @example
+   * ```ts
+   * const sim = g.cosineSimilarity([1, 0, 0], [1, 0, 0]); // 1.0
+   * const sim2 = g.cosineSimilarity([1, 0, 0], [0, 1, 0]); // 0.0
+   * ```
+   */
+  cosineSimilarity(a: number[], b: number[]): number;
+  /**
+   * Compare similarity between two texts
+   *
+   * @example
+   * ```ts
+   * const result = await g.similarity("Hello world", "Hi there");
+   * console.log(result.score); // 0.85
+   * ```
+   */
+  similarity(textA: string, textB: string, options?: EmbedOptions): Promise<SimilarityResult>;
+  /**
+   * Semantic search - find most similar texts from a corpus
+   *
+   * @example
+   * ```ts
+   * const results = await g.search("capital of France", [
+   *   "Paris is beautiful",
+   *   "London is in England",
+   *   "Dogs are pets"
+   * ]);
+   * // [{ text: "Paris is beautiful", score: 0.89, index: 0 }, ...]
+   * ```
+   */
+  search(query: string, corpus: string[], options?: EmbedOptions & {
+    topK?: number;
+  }): Promise<SearchResult[]>;
+  /**
+   * Find the nearest text to an embedding vector
+   *
+   * @example
+   * ```ts
+   * const embedding = (await g.embed("dog")).vector;
+   * const match = await g.findNearest(embedding, ["cat", "car", "tree"]);
+   * // { text: "cat", score: 0.85, index: 0 }
+   * ```
+   */
+  findNearest(embedding: number[], candidates: string[], options?: EmbedOptions & {
+    topK?: number;
+  }): Promise<SearchResult[]>;
+  /**
+   * Get session stats
+   */
+  getStats(): SessionStats;
+  /**
+   * Get system info
+   */
+  getInfo(): SystemInfo;
+  /**
+   * Reset stats
+   */
+  resetStats(): void;
+  private readonly ttsModelId;
+  /**
+   * Load the native TTS model (Kani-TTS-2) for text-to-speech synthesis.
+   *
+   * @example
+   * ```ts
+   * await g.loadTTS({ onProgress: (p) => console.log(p.status) });
+   * const result = await g.speak("Hello world");
+   * // result.audio = Float32Array PCM, result.sampleRate = 22050
+   * ```
+   */
+  loadTTS(_options?: LoadTTSOptions & {
+    model?: string;
+  }): Promise<void>;
+  /**
+   * Ensure TTS model is loaded (lazy loading)
+   */
+  ensureTTSLoaded(_options?: LoadTTSOptions): Promise<void>;
+  /**
+   * Generate speech from text using the native Kani-TTS-2 WebGPU engine.
+   *
+   * @example
+   * ```ts
+   * const result = await g.speak("Hello world");
+   * // result.audio = Float32Array PCM, result.sampleRate = 22050
+   * ```
+   */
+  speak(text: string, options?: SpeakOptions): Promise<SpeakResult>;
+  /** Lazily build (or reuse) the native Kani-TTS WebGPUEngine (default repo). */
+  private ensureNativeTTSEngine;
+  /**
+   * Stream speech generation. The native engine synthesizes the full clip, so a
+   * single final audio chunk is yielded.
+   */
+  speakStream(text: string, options?: SpeakOptions): AsyncGenerator<AudioChunk, SpeakResult, unknown>;
+  /**
+   * Get list of available TTS voices (native Kani-TTS-2 default voice).
+   */
+  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 (native Kani-TTS-2).
+   */
+  listTTSModels(): Promise<Array<{
+    id: string;
+    description: string;
+    sampleRate: number;
+    voiceCount: number;
+  }>>;
+  /**
+   * Load the native STT model (Moonshine) for speech-to-text transcription.
+   *
+   * @example
+   * ```ts
+   * await g.loadSTT();
+   * 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>;
+  /** Lazily build (or reuse) the native MoonshineSTT engine (default repo). */
+  private ensureNativeSTT;
+  /**
+   * 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 (native Moonshine).
+   */
+  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 (releases all native WebGPU engines and their devices).
+   * @param _disconnect Accepted for API compatibility; no longer used.
+   */
+  dispose(_disconnect?: boolean): Promise<void>;
+  /**
+   * @deprecated The shared Chrome backend was removed; this is now a no-op.
+   */
+  static shutdown(): Promise<void>;
+  private parseThinking;
+  private cleanOutput;
+}
+//#endregion
+export { Gerbil as t };
+//# sourceMappingURL=gerbil-BT9fCydo.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gerbil-BT9fCydo.d.mts","names":[],"sources":["../src/core/gerbil.ts"],"sourcesContent":[],"mappings":";;;;;AA8OsB,cAvBT,MAAA,CAuBS;EAgDC,QAAA,YAAA;EAIa,QAAA,WAAA;EA0BgB,iBAAA,MAAA;EAAmB,QAAA,KAAA;EAoLrD,QAAA,WAAA;EAyDsB,QAAA,YAAA;EAyCO,QAAA,iBAAA;EAAsB,QAAA,eAAA;EAqC7B,QAAA,SAAA;EAWM,QAAA,eAAA;EAAsB,QAAA,aAAA;EAgC5B,iBAAA,KAAA;EAWM,iBAAA,SAAA;EAAsB,WAAA,CAAA,MAAA,CAAA,EA/b9C,YA+b8C;EAgCvB,QAAA,WAAA;EAWO;;;;;EAyDa,QAAA,YAAA;EA0MpD,OAAA,UAAA,CAAA,CAAA,EA7rBU,WA6rBV,EAAA;EACe,OAAA,QAAA,CAAA,OAAA,EAAA,MAAA,CAAA,EA1rBQ,WA0rBR,GAAA,SAAA;EAAvB;;;;;;;;;;;;;;;;;;EAwZQ,SAAA,CAAA,OAAA,CAAA,EAAA,MAAA,EAAA,OAAA,CAAA,EAxjCuC,WAwjCvC,CAAA,EAxjC0D,OAwjC1D,CAAA,IAAA,CAAA;EAAY;;;;;;EAgEZ,QAAA,eAAA;EAuDa;;;EAO0B,QAAA,CAAA,CAAA,EAAA,OAAA;EAaf;;;EAuCxB,cAAA,CAAA,CAAA,EAAA,OAAA;EACO;;;EAcJ,YAAA,CAAA,CAAA,EArkCE,WAqkCF,GAAA,IAAA;EA8BZ;;;EA2B+D,aAAA,CAAA,CAAA,EAAA,QAAA,GAAA,KAAA,GAAA,MAAA;EAQN;;;;;EA8BhD,QAAA,CAAA,CAAA,EAAA,MAAA;EAAR;;;EAqEA,qBAAA,CAAA,CAAA,EAAA;IAW4B,IAAA,EAAA,MAAA;IAAR,MAAA,EAAA,MAAA;IAyDZ,IAAA,EAAA,MAAA;IAAR,OAAA,EAAA,MAAA;EAmC4B,CAAA;EAkBK;;;;;;;;;;;;;;;;kCAzyCE;;;;;;;;;;;;;;;;;;;;;;;;0CAyCO,iBAAsB;;;;;kCAqC7B;;;;;;;yCAWM,iBAAsB;;;;;kCAgC5B;;;;;;;yCAWM,iBAAsB;;;;;uCAgCvB;;;;;;;+CAWO,iBAAsB;;;;;;gBAmCpD;;;;;;;;;;;;;;;qCAsBoB,kBAAuB,QAAQ;;;;;;;;;;;mCA0M5D,kBACR,uBAAuB;;;;;;;;;;;;;;;;;;;mCA6Ma,YAAY,KAAK,QAAQ;;;;;;;;;;;;;;;;;wDAgDrD,wBACR,QAAQ,qBAAqB;;;;gCAiBG,eAAoB,QAAQ;;;;;;;;;;wCAoDpB,eAAoB,QAAQ;;;;;;;;;;;;;;;;;;;;qDAkD5D,eACR,QADyB,gBAAA;;;;;;;;;;;;;;oDAmCjB;;MACR,QADoB,YAAA;;;;;;;;;;;mEAgCZ;;MACR,QADoB,YAAA;;;;cAyBX;;;;aAOD;;;;;;;;;;;;;;;;qBAuDa;;MAA2C;;;;6BAOlC,iBAAiB;;;;;;;;;;gCAaf,eAAoB,QAAQ;;;;;;;sCAuCpD,eACR,eAAe,YAAY;;;;gBAchB;;;;;;;;;;;;;;;;mBA6BS,QACrB;;;;;;;;;;;;;;;;wCA2ByC,iBAAsB;;;;gDAQN,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;oBA4BnE,eAAe,sBACb,oBACR,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;0CAoEC,gCACT,QAAQ;;;;mBAWY,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAyD5B,QAAQ;;;;2BAmCoB;;;;;kCAkBK;;;;qBAmDX"}

package/dist/gerbil-DomNfIr1.mjs

@@ -0,0 +1,4 @@
+import { t as Gerbil } from "./gerbil-BHrJJIa4.mjs";
+import "./utils-DKO55ZmZ.mjs";
+
+export { Gerbil };