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

package/dist/browser/index.d.ts

@@ -0,0 +1,1009 @@
+import { z } from "zod";
+
+//#region src/core/types.d.ts
+
+type ModelConfig = {
+  id: string;
+  repo: string;
+  description: string;
+  size: string;
+  contextLength: number;
+  supportsThinking: boolean;
+  supportsJson: boolean;
+  /** Whether model supports vision/image input */
+  supportsVision?: boolean;
+  /** Vision encoder size (for display, e.g., "0.4B") */
+  visionEncoderSize?: string;
+  family: "qwen" | "smollm" | "phi" | "mistral" | "llama" | "other";
+};
+type ModelSource = {
+  type: "builtin" | "huggingface" | "local";
+  path: string;
+};
+type ImageInput = {
+  /** Image source: URL, base64 data URI, or local file path */
+  source: string;
+  /** Optional alt text for context */
+  alt?: string;
+};
+type GenerateOptions = {
+  /** Maximum tokens to generate (default: 256) */
+  maxTokens?: number;
+  /** Temperature for sampling, 0-2 (default: 0.7) */
+  temperature?: number;
+  /** Top-p sampling (default: 0.9) */
+  topP?: number;
+  /** Top-k sampling (default: 50) */
+  topK?: number;
+  /** Stop sequences */
+  stopSequences?: string[];
+  /** System prompt */
+  system?: string;
+  /** Enable thinking/reasoning mode (Qwen3) */
+  thinking?: boolean;
+  /** Callback for each token (streaming) */
+  onToken?: (token: string) => void;
+  /** Images to include (only used if model supports vision) */
+  images?: ImageInput[];
+  /** Enable response caching (default: false) */
+  cache?: boolean;
+  /** Cache TTL in milliseconds (default: 5 minutes) */
+  cacheTtl?: number;
+};
+type GenerateResult = {
+  /** Generated text */
+  text: string;
+  /** Thinking/reasoning (if enabled) */
+  thinking?: string;
+  /** Tokens generated */
+  tokensGenerated: number;
+  /** Generation speed */
+  tokensPerSecond: number;
+  /** Total time in ms */
+  totalTime: number;
+  /** Why generation stopped */
+  finishReason: "stop" | "length" | "error";
+  /** Which provider was used (for hybrid mode) */
+  provider?: "local" | "openai" | "anthropic";
+  /** Whether result came from cache */
+  cached?: boolean;
+};
+type JsonOptions<T = unknown> = {
+  /** Zod schema for validation */
+  schema: z.ZodType<T>;
+  /** Number of retries on invalid JSON (default: 3) */
+  retries?: number;
+  /** Temperature (lower = more deterministic, default: 0.3) */
+  temperature?: number;
+  /** System prompt override */
+  system?: string;
+};
+type EmbedOptions = {
+  /** Model to use for embeddings */
+  model?: string;
+  /** Normalize vectors (default: true) */
+  normalize?: boolean;
+};
+type EmbedResult = {
+  /** Embedding vector */
+  vector: number[];
+  /** Original text */
+  text: string;
+  /** Time in ms */
+  totalTime: number;
+};
+type LoadOptions = {
+  /** Progress callback */
+  onProgress?: (info: ProgressInfo) => void;
+  /** Device: 'auto', 'gpu', 'cpu', 'webgpu' (default: 'auto') */
+  device?: "auto" | "gpu" | "cpu" | "webgpu";
+  /** Quantization: 'q4', 'q8', 'fp16', 'fp32' (default: 'q4') */
+  dtype?: "q4" | "q8" | "fp16" | "fp32";
+  /** Override context length */
+  contextLength?: number;
+};
+type ProgressInfo = {
+  status: string;
+  progress?: number;
+  file?: string;
+  loaded?: number;
+  total?: number;
+};
+type GerbilConfig = {
+  /** Default model */
+  model?: string;
+  /** Default device */
+  device?: "auto" | "gpu" | "cpu";
+  /** Default quantization */
+  dtype?: "q4" | "q8" | "fp16" | "fp32";
+  /** Cache configuration */
+  cache?: CacheConfig;
+  /** Fallback configuration */
+  fallback?: FallbackConfig;
+};
+type CacheConfig = {
+  /** Enable caching (default: true) */
+  enabled?: boolean;
+  /** Time-to-live in seconds (default: 3600) */
+  ttl?: number;
+  /** Max cache size (default: "500mb") */
+  maxSize?: string;
+  /** Storage backend */
+  storage?: "memory" | "disk" | "redis";
+  /** Redis URL (if storage is redis) */
+  redisUrl?: string;
+};
+type FallbackConfig = {
+  /** Fallback provider */
+  provider: "openai" | "anthropic";
+  /** API key */
+  apiKey: string;
+  /** Model to use */
+  model: string;
+  /** When to fallback */
+  when: "timeout" | "error" | "always-verify";
+  /** Timeout in ms before fallback (default: 5000) */
+  timeout?: number;
+};
+type SessionStats = {
+  prompts: number;
+  tokensIn: number;
+  tokensOut: number;
+  avgSpeed: number;
+  totalTime: number;
+  cacheHits: number;
+  cacheMisses: number;
+};
+type ModelStats = {
+  modelId: string;
+  avgSpeed: number;
+  totalGenerations: number;
+  totalTokens: number;
+};
+type SystemInfo = {
+  version: string;
+  model: ModelConfig | null;
+  device: {
+    backend: string;
+    gpu: string | null;
+    vram: string | null;
+    status: "ready" | "loading" | "error";
+  };
+  context: {
+    max: number;
+    used: number;
+    available: number;
+  };
+  cache: {
+    location: string;
+    size: string;
+    modelCount: number;
+  };
+};
+type GerbilModelSettings = {
+  /** Enable thinking mode */
+  thinking?: boolean;
+  /** Device to use */
+  device?: "auto" | "gpu" | "cpu";
+  /** Quantization level */
+  dtype?: "q4" | "q8" | "fp16" | "fp32";
+};
+type GerbilProviderSettings = {
+  /** Default device */
+  device?: "auto" | "gpu" | "cpu";
+  /** Default quantization */
+  dtype?: "q4" | "q8" | "fp16" | "fp32";
+};
+type VoiceInfo = {
+  /** Voice ID (e.g., "af_bella", "am_adam") */
+  id: string;
+  /** Display name (e.g., "Bella", "Adam") */
+  name: string;
+  /** Gender: male, female, or neutral */
+  gender: "male" | "female" | "neutral";
+  /** Language code (e.g., "en", "en-us", "zh") */
+  language: string;
+  /** Optional description */
+  description?: string;
+  /** Speaker embedding file name (internal) */
+  embeddingFile?: string;
+};
+type TTSModelConfig = {
+  /** Model ID (e.g., "kokoro-82m") */
+  id: string;
+  /** HuggingFace repo path */
+  repo: string;
+  /** Human-readable description */
+  description: string;
+  /** Approximate model size */
+  size: string;
+  /** Output sample rate in Hz (e.g., 24000) */
+  sampleRate: number;
+  /** Available voices */
+  voices: VoiceInfo[];
+  /** Default voice ID */
+  defaultVoice: string;
+  /** Supported languages */
+  languages: string[];
+};
+type SpeakOptions = {
+  /** Voice ID to use (default: model's default voice) */
+  voice?: string;
+  /** Speech speed multiplier (0.5 = half speed, 2.0 = double speed, default: 1.0) */
+  speed?: number;
+  /** Progress callback */
+  onProgress?: (info: ProgressInfo) => void;
+  /** Callback for audio chunks during streaming */
+  onAudioChunk?: (chunk: AudioChunk) => void;
+};
+type AudioChunk = {
+  /** Raw PCM audio samples (Float32Array) */
+  samples: Float32Array;
+  /** Sample rate in Hz */
+  sampleRate: number;
+  /** Chunk index (0-based) */
+  index: number;
+  /** Whether this is the final chunk */
+  isFinal: boolean;
+};
+type SpeakResult = {
+  /** Raw PCM audio samples (Float32Array) */
+  audio: Float32Array;
+  /** Sample rate in Hz */
+  sampleRate: number;
+  /** Audio duration in seconds */
+  duration: number;
+  /** Voice used */
+  voice: string;
+  /** Total processing time in ms */
+  totalTime: number;
+};
+type LoadTTSOptions = {
+  /** Progress callback */
+  onProgress?: (info: ProgressInfo) => void;
+  /** Device: 'auto', 'webgpu', 'cpu' (default: 'auto') */
+  device?: "auto" | "webgpu" | "cpu";
+};
+type STTModelConfig = {
+  /** Model ID (e.g., "whisper-tiny.en") */
+  id: string;
+  /** HuggingFace repo path */
+  repo: string;
+  /** Human-readable description */
+  description: string;
+  /** Model size (e.g., "39M", "244M") */
+  size: string;
+  /** Whether model supports multiple languages */
+  multilingual: boolean;
+  /** Supported languages (ISO 639-1 codes) */
+  languages: string[];
+  /** Expected sample rate (default: 16000) */
+  sampleRate: number;
+};
+type TranscribeOptions = {
+  /** Language hint (ISO 639-1 code like "en", "es", "fr") - only for multilingual models */
+  language?: string;
+  /** Return word/segment timestamps */
+  timestamps?: boolean;
+  /** Progress callback */
+  onProgress?: (info: ProgressInfo) => void;
+};
+type TranscribeSegment = {
+  /** Segment text */
+  text: string;
+  /** Start time in seconds */
+  start: number;
+  /** End time in seconds */
+  end: number;
+};
+type TranscribeResult = {
+  /** Full transcribed text */
+  text: string;
+  /** Detected or specified language */
+  language: string;
+  /** Segments with timestamps (if timestamps option enabled) */
+  segments?: TranscribeSegment[];
+  /** Audio duration in seconds */
+  duration: number;
+  /** Total processing time in ms */
+  totalTime: number;
+};
+type LoadSTTOptions = {
+  /** Progress callback */
+  onProgress?: (info: ProgressInfo) => void;
+  /** Device: 'auto', 'webgpu', 'cpu' (default: 'auto') */
+  device?: "auto" | "webgpu" | "cpu";
+};
+type StreamingTranscriptionOptions = {
+  /** Interval between transcriptions in ms (default: 3000) */
+  chunkDuration?: number;
+  /** Minimum audio samples before transcribing (default: 8000 = 0.5s at 16kHz) */
+  minChunkSize?: number;
+  /** Callback for each transcribed chunk */
+  onChunk?: (text: string, chunkIndex: number) => void;
+  /** Callback with full accumulated transcript */
+  onTranscript?: (fullText: string) => void;
+  /** Callback on transcription error */
+  onError?: (error: string) => void;
+  /** Language hint (for multilingual models) */
+  language?: string;
+};
+type StreamingTranscriptionSession = {
+  /** Feed audio data to the buffer (Float32Array at 16kHz) */
+  feedAudio: (audio: Float32Array) => void;
+  /** Manually trigger transcription of buffered audio */
+  flush: () => Promise<string>;
+  /** Start automatic interval-based transcription */
+  start: () => void;
+  /** Stop transcription and return final transcript */
+  stop: () => Promise<string>;
+  /** Immediately abort without final transcription (for cleanup) */
+  abort: () => void;
+  /** Check if session is running */
+  isRunning: () => boolean;
+  /** Get current full transcript */
+  getTranscript: () => string;
+  /** Get number of chunks transcribed */
+  getChunkCount: () => number;
+  /** Reset session (clear buffer and transcript) */
+  reset: () => void;
+};
+//#endregion
+//#region src/core/models.d.ts
+declare const BUILTIN_MODELS: Record<string, ModelConfig>;
+//#endregion
+//#region src/browser/index.d.ts
+
+type WorkerProgress = {
+  status: "loading" | "downloading" | "ready" | "error";
+  message?: string;
+  file?: string;
+  progress?: number;
+  /** Number of files being downloaded (0 = loading from cache) */
+  downloadCount?: number;
+  /** Total files to process */
+  totalFiles?: number;
+  error?: string;
+};
+type WorkerToken = {
+  status: "token";
+  text: string;
+  state: "thinking" | "answering";
+  numTokens: number;
+  tps: number;
+};
+type WorkerComplete = {
+  status: "complete";
+  text: string;
+  numTokens: number;
+  totalTime: number;
+  tps: number;
+};
+type GerbilWorkerOptions = {
+  /** Model ID to load (default: "qwen3-0.6b") */
+  modelId?: string;
+  /** Called during model loading with progress updates */
+  onProgress?: (progress: WorkerProgress) => void;
+  /** Called for each token during streaming generation */
+  onToken?: (token: WorkerToken) => void;
+  /** Called when generation is complete */
+  onComplete?: (result: WorkerComplete) => void;
+  /** Called on errors */
+  onError?: (error: string) => void;
+  /** Worker script URL (auto-detected if not provided) */
+  workerUrl?: string;
+};
+type GenerateStreamOptions = {
+  /** Maximum tokens to generate */
+  maxTokens?: number;
+  /** Temperature for sampling (0 = deterministic) */
+  temperature?: number;
+  /** Top-p nucleus sampling */
+  topP?: number;
+  /** Top-k sampling */
+  topK?: number;
+  /** Enable thinking mode (Qwen3) */
+  thinking?: boolean;
+  /** System prompt */
+  system?: string;
+  /** Image URLs or data URIs (for vision models) */
+  images?: string[];
+  /** Conversation history for multi-turn (includes all previous messages) */
+  history?: Array<{
+    role: "user" | "assistant" | "system";
+    content: string;
+  }>;
+};
+type GerbilWorker = {
+  /** Generate text with streaming */
+  generate: (prompt: string, options?: GenerateStreamOptions) => Promise<string>;
+  /** Interrupt current generation */
+  interrupt: () => void;
+  /** Reset conversation cache */
+  reset: () => void;
+  /** Terminate the worker */
+  terminate: () => void;
+  /** Check if model is loaded */
+  isReady: () => boolean;
+};
+/**
+ * Create a Gerbil worker for streaming WebGPU inference
+ *
+ * Uses a Web Worker to keep the UI responsive during model loading
+ * and text generation, with real-time token streaming.
+ */
+declare function createGerbilWorker(options?: GerbilWorkerOptions): Promise<GerbilWorker>;
+/** Message in a chat conversation */
+type Message = {
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+  thinking?: string;
+  /** Attached images (URLs or data URIs) - for vision models */
+  images?: string[];
+};
+/** Loading progress state */
+type LoadingProgress = {
+  status: "loading" | "downloading" | "ready" | "error";
+  message?: string;
+  file?: string;
+  progress?: number;
+  /** Number of files being downloaded (0 = loading from cache) */
+  downloadCount?: number;
+  /** Total files to process */
+  totalFiles?: number;
+};
+/** Options for useChat hook */
+type UseChatOptions = {
+  /** Model ID (default: "qwen3-0.6b") */
+  model?: string;
+  /** System prompt */
+  system?: string;
+  /** Enable thinking mode (Qwen3) */
+  thinking?: boolean;
+  /** Max tokens per response */
+  maxTokens?: number;
+  /** Temperature (0-2) */
+  temperature?: number;
+  /** Initial messages */
+  initialMessages?: Message[];
+  /** Auto-load model on mount (default: false - loads on first generate or load()) */
+  autoLoad?: boolean;
+  /** Called when model is ready */
+  onReady?: () => void;
+  /** Called on error */
+  onError?: (error: string) => void;
+};
+/** Return type for useChat hook */
+type UseChatReturn = {
+  /** Chat messages */
+  messages: Message[];
+  /** Current input value */
+  input: string;
+  /** Set input value */
+  setInput: (value: string) => void;
+  /** Submit current input */
+  handleSubmit: (e?: {
+    preventDefault?: () => void;
+  }) => void;
+  /** Whether model is loading */
+  isLoading: boolean;
+  /** Loading progress */
+  loadingProgress: LoadingProgress | null;
+  /** Whether generating a response */
+  isGenerating: boolean;
+  /** Current thinking content (streaming) */
+  thinking: string;
+  /** Stop generation */
+  stop: () => void;
+  /** Clear all messages */
+  clear: () => void;
+  /** Current tokens per second */
+  tps: number;
+  /** Whether model is ready */
+  isReady: boolean;
+  /** Error message if any */
+  error: string | null;
+  /** Load the model (only needed if lazy: true) */
+  load: () => void;
+  /** Currently attached images (for next message) */
+  attachedImages: string[];
+  /** Attach an image to the next message */
+  attachImage: (imageUrl: string) => void;
+  /** Remove an attached image */
+  removeImage: (index: number) => void;
+  /** Clear all attached images */
+  clearImages: () => void;
+  /** Send message with specific images (convenience method) */
+  sendWithImages: (text: string, images: string[]) => void;
+};
+/**
+ * React hook for chat with local LLM
+ *
+ * @example
+ * ```tsx
+ * import { useChat } from "@tryhamster/gerbil/browser";
+ *
+ * function Chat() {
+ *   const { messages, input, setInput, handleSubmit, isLoading, isGenerating } = useChat();
+ *
+ *   if (isLoading) return <div>Loading model...</div>;
+ *
+ *   return (
+ *     <div>
+ *       {messages.map(m => (
+ *         <div key={m.id}>{m.role}: {m.content}</div>
+ *       ))}
+ *       <form onSubmit={handleSubmit}>
+ *         <input value={input} onChange={e => setInput(e.target.value)} />
+ *         <button disabled={isGenerating}>Send</button>
+ *       </form>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useChat(options?: UseChatOptions): UseChatReturn;
+/** Options for useCompletion hook */
+type UseCompletionOptions = {
+  /** Model ID (default: "qwen3-0.6b") */
+  model?: string;
+  /** System prompt */
+  system?: string;
+  /** Enable thinking mode (Qwen3) */
+  thinking?: boolean;
+  /** Max tokens */
+  maxTokens?: number;
+  /** Temperature (0-2) */
+  temperature?: number;
+  /** Auto-load model on mount (default: false - loads on first complete() or load()) */
+  autoLoad?: boolean;
+  /** Called when model is ready */
+  onReady?: () => void;
+  /** Called on error */
+  onError?: (error: string) => void;
+};
+/** Options for single completion call */
+type CompleteOptions = {
+  /** Image URLs or data URIs to analyze (for vision models) */
+  images?: string[];
+};
+/** Return type for useCompletion hook */
+type UseCompletionReturn = {
+  /** Generated completion */
+  completion: string;
+  /** Thinking content (if enabled) */
+  thinking: string;
+  /** Generate completion (optionally with images for vision models) */
+  complete: (prompt: string, options?: CompleteOptions) => Promise<string>;
+  /** Whether model is loading */
+  isLoading: boolean;
+  /** Loading progress */
+  loadingProgress: LoadingProgress | null;
+  /** Whether generating */
+  isGenerating: boolean;
+  /** Stop generation */
+  stop: () => void;
+  /** Current tokens per second */
+  tps: number;
+  /** Whether model is ready */
+  isReady: boolean;
+  /** Error message if any */
+  error: string | null;
+  /** Load the model (only needed if lazy: true) */
+  load: () => void;
+};
+/**
+ * React hook for text completion with local LLM
+ *
+ * @example
+ * ```tsx
+ * import { useCompletion } from "@tryhamster/gerbil/browser";
+ *
+ * function App() {
+ *   const { complete, completion, isLoading, isGenerating } = useCompletion();
+ *
+ *   if (isLoading) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => complete("Write a haiku")}>Generate</button>
+ *       <p>{completion}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useCompletion(options?: UseCompletionOptions): UseCompletionReturn;
+/** TTS loading progress */
+type TTSProgress = {
+  status: "idle" | "loading" | "downloading" | "ready" | "error";
+  message?: string;
+  file?: string;
+  progress?: number;
+  error?: string;
+};
+/** Available TTS models */
+type TTSModelId = "kokoro-82m" | "supertonic-66m";
+/** Voice info for TTS models */
+type BrowserVoiceInfo = {
+  id: string;
+  name: string;
+  gender: "male" | "female";
+  language: string;
+  description: string;
+};
+/** Options for useSpeech hook */
+type UseSpeechOptions = {
+  /** TTS model to use (default: "kokoro-82m") */
+  model?: TTSModelId;
+  /** Default voice ID (default: model's default voice) */
+  voice?: string;
+  /** Speech speed multiplier (default: 1.0) */
+  speed?: number;
+  /** Auto-load TTS model on mount (default: false) */
+  autoLoad?: boolean;
+  /** Called when model is ready */
+  onReady?: () => void;
+  /** Called on error */
+  onError?: (error: string) => void;
+  /** Called when speech starts */
+  onStart?: () => void;
+  /** Called when speech ends */
+  onEnd?: () => void;
+};
+/** Return type for useSpeech hook */
+type UseSpeechReturn = {
+  /** Speak text aloud */
+  speak: (text: string, options?: {
+    voice?: string;
+    speed?: number;
+  }) => Promise<void>;
+  /** Stop current speech */
+  stop: () => void;
+  /** Whether TTS model is loading */
+  isLoading: boolean;
+  /** Loading progress */
+  loadingProgress: TTSProgress | null;
+  /** Whether currently speaking */
+  isSpeaking: boolean;
+  /** Whether TTS model is ready */
+  isReady: boolean;
+  /** Load the TTS model */
+  load: () => void;
+  /** Error message if any */
+  error: string | null;
+  /** List available voices for current model */
+  listVoices: () => BrowserVoiceInfo[];
+  /** Current voice ID */
+  currentVoice: string;
+  /** Set current voice */
+  setVoice: (voiceId: string) => void;
+  /** Current speed */
+  currentSpeed: number;
+  /** Set speed */
+  setSpeed: (speed: number) => void;
+  /** Current TTS model ID */
+  currentModel: TTSModelId;
+  /** Sample rate for current model (24000 for Kokoro, 44100 for Supertonic) */
+  sampleRate: number;
+};
+/**
+ * React hook for text-to-speech with Web Audio API playback
+ *
+ * Supports both Kokoro (24kHz, high quality) and Supertonic (44.1kHz, faster).
+ *
+ * @example
+ * ```tsx
+ * import { useSpeech } from "@tryhamster/gerbil/browser";
+ *
+ * function App() {
+ *   // Default: Kokoro TTS
+ *   const { speak, stop, isLoading, isSpeaking, listVoices, setVoice } = useSpeech();
+ *
+ *   // Or use Supertonic (44.1kHz, faster)
+ *   // const { speak, listVoices } = useSpeech({ model: "supertonic-66m" });
+ *
+ *   if (isLoading) return <div>Loading TTS...</div>;
+ *
+ *   return (
+ *     <div>
+ *       <select onChange={e => setVoice(e.target.value)}>
+ *         {listVoices().map(v => (
+ *           <option key={v.id} value={v.id}>{v.name}</option>
+ *         ))}
+ *       </select>
+ *       <button onClick={() => speak("Hello world!")}>
+ *         {isSpeaking ? "Speaking..." : "Speak"}
+ *       </button>
+ *       {isSpeaking && <button onClick={stop}>Stop</button>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useSpeech(options?: UseSpeechOptions): UseSpeechReturn;
+/**
+ * Play audio from Float32Array using Web Audio API
+ *
+ * @example
+ * ```ts
+ * import { playAudio } from "@tryhamster/gerbil/browser";
+ *
+ * const audio = new Float32Array([...]); // TTS output
+ * const controller = await playAudio(audio, 24000);
+ *
+ * // Stop playback
+ * controller.stop();
+ * ```
+ */
+declare function playAudio(audio: Float32Array, sampleRate?: number): Promise<{
+  stop: () => void;
+  onEnded: Promise<void>;
+}>;
+/**
+ * Create a reusable audio player for streaming TTS
+ *
+ * @example
+ * ```ts
+ * import { createAudioPlayer } from "@tryhamster/gerbil/browser";
+ *
+ * const player = createAudioPlayer(24000);
+ *
+ * // Queue audio chunks as they arrive
+ * player.queue(chunk1);
+ * player.queue(chunk2);
+ *
+ * // Stop and clear
+ * player.stop();
+ * ```
+ */
+declare function createAudioPlayer(sampleRate?: number): {
+  queue: (audio: Float32Array) => void;
+  stop: () => void;
+  isPlaying: () => boolean;
+};
+/**
+ * Progress info for STT loading
+ */
+type STTProgress = {
+  status: "downloading" | "loading" | "ready" | "error";
+  message?: string;
+  progress?: number;
+  file?: string;
+};
+/**
+ * Options for useVoiceInput hook
+ */
+type UseVoiceInputOptions = {
+  /** STT model ID (default: whisper-tiny.en) */
+  model?: string;
+  /** Auto-load model on mount (default: false) */
+  autoLoad?: boolean;
+  /** Callback when model is ready */
+  onReady?: () => void;
+  /** Callback when transcription completes (or for each chunk in streaming mode) */
+  onTranscript?: (text: string) => void;
+  /** Callback on error */
+  onError?: (error: string) => void;
+  /** Callback during loading */
+  onProgress?: (progress: STTProgress) => void;
+  /** Enable streaming transcription - transcribes audio in chunks as you speak */
+  streaming?: boolean;
+  /** Chunk duration in ms for streaming mode (default: 3000 = 3 seconds) */
+  chunkDuration?: number;
+  /** Callback for each streaming chunk with partial transcript */
+  onChunk?: (text: string, chunkIndex: number) => void;
+};
+/**
+ * Return type for useVoiceInput hook
+ */
+type UseVoiceInputReturn = {
+  /** Start recording audio */
+  startRecording: () => Promise<void>;
+  /** Stop recording and transcribe */
+  stopRecording: () => Promise<string>;
+  /** Cancel recording without transcribing */
+  cancelRecording: () => void;
+  /** Transcribe raw audio data (Float32Array at 16kHz) */
+  transcribe: (audio: Float32Array) => Promise<string>;
+  /** Whether currently recording */
+  isRecording: boolean;
+  /** Whether transcribing */
+  isTranscribing: boolean;
+  /** Whether model is loading */
+  isLoading: boolean;
+  /** Whether model is ready */
+  isReady: boolean;
+  /** Latest transcription result (full transcript in streaming mode) */
+  transcript: string;
+  /** Current streaming chunk being transcribed (streaming mode only) */
+  streamingChunk: string;
+  /** Number of chunks transcribed so far (streaming mode only) */
+  chunkCount: number;
+  /** Loading progress */
+  loadingProgress: STTProgress | null;
+  /** Error message */
+  error: string | null;
+  /** Manually load the model */
+  load: () => void;
+};
+/**
+ * React hook for voice input with browser microphone
+ *
+ * Uses MediaRecorder to capture audio and Whisper for transcription.
+ * Supports both one-shot and streaming transcription modes.
+ *
+ * @example Basic usage (one-shot)
+ * ```tsx
+ * function VoiceInput() {
+ *   const { startRecording, stopRecording, isRecording, transcript } = useVoiceInput({
+ *     onTranscript: (text) => console.log("User said:", text),
+ *   });
+ *
+ *   return (
+ *     <button onClick={isRecording ? stopRecording : startRecording}>
+ *       {isRecording ? "Stop" : "Record"}
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example Streaming transcription (real-time)
+ * ```tsx
+ * function LiveTranscription() {
+ *   const { startRecording, stopRecording, isRecording, transcript, streamingChunk } = useVoiceInput({
+ *     streaming: true,           // Enable streaming mode
+ *     chunkDuration: 1500,       // Transcribe every 1.5 seconds (default)
+ *     onChunk: (text, idx) => console.log(`Chunk ${idx}: ${text}`),
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={isRecording ? stopRecording : startRecording}>
+ *         {isRecording ? "Stop" : "Start Live Transcription"}
+ *       </button>
+ *       <p>Current chunk: {streamingChunk}</p>
+ *       <p>Full transcript: {transcript}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useVoiceInput(options?: UseVoiceInputOptions): UseVoiceInputReturn;
+/**
+ * Options for useVoiceChat hook
+ */
+type UseVoiceChatOptions = {
+  /** LLM model ID (default: qwen3-0.6b) */
+  llmModel?: string;
+  /** STT model ID (default: whisper-tiny.en) */
+  sttModel?: string;
+  /** TTS model ID (default: kokoro-82m, also supports supertonic-66m) */
+  ttsModel?: TTSModelId;
+  /** System prompt for LLM */
+  system?: string;
+  /** Enable thinking mode (default: false) */
+  thinking?: boolean;
+  /** TTS voice ID (default: model's default voice) */
+  voice?: string;
+  /** TTS speech speed (default: 1.0) */
+  speed?: number;
+  /** Auto-load all models on mount (default: false) */
+  autoLoad?: boolean;
+  /** Callback when user speaks */
+  onUserSpeak?: (text: string) => void;
+  /** Callback when assistant responds */
+  onAssistantSpeak?: (text: string) => void;
+  /** Callback on error */
+  onError?: (error: string) => void;
+};
+/**
+ * Message in voice chat
+ */
+type VoiceChatMessage = {
+  id: string;
+  role: "user" | "assistant";
+  content: string;
+  thinking?: string;
+  audioUrl?: string;
+};
+/**
+ * Return type for useVoiceChat hook
+ */
+type UseVoiceChatReturn = {
+  /** Messages in the conversation */
+  messages: VoiceChatMessage[];
+  /** Start recording user speech */
+  startListening: () => Promise<void>;
+  /** Stop recording and process (STT → LLM → TTS) */
+  stopListening: () => Promise<void>;
+  /** Cancel current operation */
+  cancel: () => void;
+  /** Clear conversation history */
+  clear: () => void;
+  /** Whether recording user speech */
+  isListening: boolean;
+  /** Whether processing (STT/LLM/TTS) */
+  isProcessing: boolean;
+  /** Whether assistant is speaking */
+  isSpeaking: boolean;
+  /** Current stage: idle, listening, transcribing, thinking, speaking */
+  stage: "idle" | "listening" | "transcribing" | "thinking" | "speaking";
+  /** Whether all models are loaded */
+  isReady: boolean;
+  /** Whether loading models */
+  isLoading: boolean;
+  /** Loading progress message */
+  loadingMessage: string;
+  /** Error message */
+  error: string | null;
+  /** Manually load all models */
+  load: () => void;
+};
+/**
+ * React hook for voice conversation with STT + LLM + TTS
+ *
+ * Complete voice-to-voice conversation loop:
+ * 1. User presses button to speak
+ * 2. Speech is transcribed (Whisper)
+ * 3. LLM generates response
+ * 4. Response is spoken aloud (Kokoro or Supertonic TTS)
+ *
+ * @example
+ * ```tsx
+ * function VoiceChat() {
+ *   const {
+ *     messages,
+ *     startListening,
+ *     stopListening,
+ *     isListening,
+ *     isSpeaking,
+ *     stage,
+ *   } = useVoiceChat({
+ *     system: "You are a helpful voice assistant.",
+ *     voice: "af_bella",
+ *     // Or use Supertonic for faster synthesis:
+ *     // ttsModel: "supertonic-66m",
+ *     // voice: "F1",
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {messages.map(m => (
+ *         <div key={m.id}>{m.role}: {m.content}</div>
+ *       ))}
+ *       <button
+ *         onMouseDown={startListening}
+ *         onMouseUp={stopListening}
+ *       >
+ *         {stage === "idle" ? "🎤 Hold to Speak" : stage}
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useVoiceChat(options?: UseVoiceChatOptions): UseVoiceChatReturn;
+/**
+ * Check if WebGPU is supported
+ */
+declare function isWebGPUSupported(): boolean;
+/**
+ * Get WebGPU adapter info
+ */
+declare function getWebGPUInfo(): Promise<{
+  supported: boolean;
+  adapter?: string;
+  device?: string;
+} | null>;
+declare const _default: {
+  isWebGPUSupported: typeof isWebGPUSupported;
+  getWebGPUInfo: typeof getWebGPUInfo;
+  createGerbilWorker: typeof createGerbilWorker;
+  playAudio: typeof playAudio;
+  createAudioPlayer: typeof createAudioPlayer;
+};
+//#endregion
+export { AudioChunk, BUILTIN_MODELS, BrowserVoiceInfo, CacheConfig, CompleteOptions, EmbedOptions, EmbedResult, FallbackConfig, GenerateOptions, GenerateResult, GenerateStreamOptions, GerbilConfig, GerbilModelSettings, GerbilProviderSettings, GerbilWorker, GerbilWorkerOptions, ImageInput, JsonOptions, LoadOptions, LoadSTTOptions, LoadTTSOptions, LoadingProgress, Message, ModelConfig, ModelSource, ModelStats, ProgressInfo, STTModelConfig, STTProgress, SessionStats, SpeakOptions, SpeakResult, StreamingTranscriptionOptions, StreamingTranscriptionSession, SystemInfo, TTSModelConfig, TTSModelId, TTSProgress, TranscribeOptions, TranscribeResult, TranscribeSegment, UseChatOptions, UseChatReturn, UseCompletionOptions, UseCompletionReturn, UseSpeechOptions, UseSpeechReturn, UseVoiceChatOptions, UseVoiceChatReturn, UseVoiceInputOptions, UseVoiceInputReturn, VoiceChatMessage, VoiceInfo, WorkerComplete, WorkerProgress, WorkerToken, createAudioPlayer, createGerbilWorker, _default as default, getWebGPUInfo, isWebGPUSupported, playAudio, useChat, useCompletion, useSpeech, useVoiceChat, useVoiceInput };
+//# sourceMappingURL=index.d.ts.map