@tryhamster/gerbil 1.0.0-rc.12 → 1.0.0-rc.14

package/README.md

@@ -69,6 +69,30 @@ npm install @tryhamster/gerbil
 
 After global install, use `gerbil` directly instead of `npx @tryhamster/gerbil`.
 
+## Model Preloading
+
+Download models ahead of time so users don't wait:
+
+```typescript
+import { Gerbil } from "@tryhamster/gerbil";
+
+const g = new Gerbil();
+
+// Option 1: Preload for later (download only, free memory)
+await g.preloadModel("qwen3-0.6b", {
+  onProgress: (p) => console.log(p.status, p.progress),
+});
+// Later: loads from disk cache (fast, no network)
+await g.loadModel("qwen3-0.6b");
+
+// Option 2: Preload and keep in memory (instant use)
+await g.preloadModel("qwen3-0.6b", { keepLoaded: true });
+// Instant - no loading needed
+await g.generate("Hello");
+```
+
+Works for all model types: `preloadTTS()`, `preloadSTT()`, `preloadEmbedding()`.
+
 ## Quick Start
 
 ```typescript

package/dist/browser/index.d.ts

@@ -1041,8 +1041,8 @@ type UseEmbeddingReturn = {
   findNearest: (embedding: number[], candidates: string[], topK?: number) => Promise<BrowserSearchResult[]>;
   /** Compute cosine similarity between two vectors */
   cosineSimilarity: (a: number[], b: number[]) => number;
-  /** Manually load the model */
-  load: () => void;
+  /** Manually load the model - returns Promise that resolves when ready */
+  load: () => Promise<void>;
   /** Whether model is loading */
   isLoading: boolean;
   /** Whether model is ready */
@@ -1082,6 +1082,63 @@ type UseEmbeddingReturn = {
  * ```
  */
 declare function useEmbedding(options?: UseEmbeddingOptions): UseEmbeddingReturn;
+/** Progress callback for preloading */
+type PreloadProgress = {
+  status: "downloading" | "loading" | "ready" | "error";
+  file?: string;
+  progress?: number;
+  message?: string;
+};
+/** Preload options */
+type PreloadOptions = {
+  onProgress?: (progress: PreloadProgress) => void;
+};
+/**
+ * Preload a chat/LLM model (downloads to IndexedDB cache)
+ *
+ * Call this during app initialization to ensure the model is ready
+ * when users need it.
+ *
+ * @example
+ * ```ts
+ * // In your app's initialization
+ * import { preloadChatModel } from "@tryhamster/gerbil/browser";
+ *
+ * await preloadChatModel("qwen3-0.6b", {
+ *   onProgress: (p) => console.log(p.status, p.progress),
+ * });
+ *
+ * // Later, useChat will load instantly from cache
+ * ```
+ */
+declare function preloadChatModel(modelId: string, options?: PreloadOptions): Promise<void>;
+/**
+ * Preload an embedding model
+ *
+ * @example
+ * ```ts
+ * await preloadEmbeddingModel("Xenova/all-MiniLM-L6-v2");
+ * ```
+ */
+declare function preloadEmbeddingModel(modelId?: string, options?: PreloadOptions): Promise<void>;
+/**
+ * Preload a TTS model
+ *
+ * @example
+ * ```ts
+ * await preloadTTSModel("kokoro-82m");
+ * ```
+ */
+declare function preloadTTSModel(modelId?: TTSModelId, options?: PreloadOptions): Promise<void>;
+/**
+ * Preload an STT model
+ *
+ * @example
+ * ```ts
+ * await preloadSTTModel("whisper-tiny.en");
+ * ```
+ */
+declare function preloadSTTModel(modelId?: string, options?: PreloadOptions): Promise<void>;
 /**
  * Check if WebGPU is supported
  */
@@ -1100,7 +1157,11 @@ declare const _default: {
   createGerbilWorker: typeof createGerbilWorker;
   playAudio: typeof playAudio;
   createAudioPlayer: typeof createAudioPlayer;
+  preloadChatModel: typeof preloadChatModel;
+  preloadEmbeddingModel: typeof preloadEmbeddingModel;
+  preloadTTSModel: typeof preloadTTSModel;
+  preloadSTTModel: typeof preloadSTTModel;
 };
 //#endregion
-export { AudioChunk, BUILTIN_MODELS, BrowserEmbedResult, BrowserSearchResult, 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, SearchResult, SessionStats, SimilarityResult, SpeakOptions, SpeakResult, StreamingTranscriptionOptions, StreamingTranscriptionSession, SystemInfo, TTSModelConfig, TTSModelId, TTSProgress, TranscribeOptions, TranscribeResult, TranscribeSegment, UseChatOptions, UseChatReturn, UseCompletionOptions, UseCompletionReturn, UseEmbeddingOptions, UseEmbeddingReturn, UseSpeechOptions, UseSpeechReturn, UseVoiceChatOptions, UseVoiceChatReturn, UseVoiceInputOptions, UseVoiceInputReturn, VoiceChatMessage, VoiceInfo, WorkerComplete, WorkerProgress, WorkerToken, createAudioPlayer, createGerbilWorker, _default as default, getWebGPUInfo, isWebGPUSupported, playAudio, useChat, useCompletion, useEmbedding, useSpeech, useVoiceChat, useVoiceInput };
+export { AudioChunk, BUILTIN_MODELS, BrowserEmbedResult, BrowserSearchResult, BrowserVoiceInfo, CacheConfig, CompleteOptions, EmbedOptions, EmbedResult, FallbackConfig, GenerateOptions, GenerateResult, GenerateStreamOptions, GerbilConfig, GerbilModelSettings, GerbilProviderSettings, GerbilWorker, GerbilWorkerOptions, ImageInput, JsonOptions, LoadOptions, LoadSTTOptions, LoadTTSOptions, LoadingProgress, Message, ModelConfig, ModelSource, ModelStats, PreloadOptions, PreloadProgress, ProgressInfo, STTModelConfig, STTProgress, SearchResult, SessionStats, SimilarityResult, SpeakOptions, SpeakResult, StreamingTranscriptionOptions, StreamingTranscriptionSession, SystemInfo, TTSModelConfig, TTSModelId, TTSProgress, TranscribeOptions, TranscribeResult, TranscribeSegment, UseChatOptions, UseChatReturn, UseCompletionOptions, UseCompletionReturn, UseEmbeddingOptions, UseEmbeddingReturn, UseSpeechOptions, UseSpeechReturn, UseVoiceChatOptions, UseVoiceChatReturn, UseVoiceInputOptions, UseVoiceInputReturn, VoiceChatMessage, VoiceInfo, WorkerComplete, WorkerProgress, WorkerToken, createAudioPlayer, createGerbilWorker, _default as default, getWebGPUInfo, isWebGPUSupported, playAudio, preloadChatModel, preloadEmbeddingModel, preloadSTTModel, preloadTTSModel, useChat, useCompletion, useEmbedding, useSpeech, useVoiceChat, useVoiceInput };
 //# sourceMappingURL=index.d.ts.map

package/dist/browser/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/core/types.ts","../../src/core/models.ts","../../src/browser/index.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/core/types.ts","../../src/core/models.ts","../../src/browser/index.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/browser/index.js

@@ -1878,7 +1878,7 @@ function useVoiceInput(options = {}) {
 	const fullTranscriptRef = useRef("");
 	const transcribeResolveRef = useRef(null);
 	const transcribeRejectRef = useRef(null);
-	const resolveSTTModel = (modelId) => {
+	const resolveSTTModel$1 = (modelId) => {
 		return {
 			"whisper-tiny": "onnx-community/whisper-tiny",
 			"whisper-tiny.en": "onnx-community/whisper-tiny.en",
@@ -1969,7 +1969,7 @@ function useVoiceInput(options = {}) {
 		};
 		worker.postMessage({
 			type: "load",
-			payload: { model: resolveSTTModel(model) }
+			payload: { model: resolveSTTModel$1(model) }
 		});
 		return () => {
 			mountedRef.current = false;
@@ -2348,7 +2348,7 @@ function useVoiceChat(options = {}) {
 	const isListening = stage === "listening";
 	const isProcessing = stage === "transcribing" || stage === "thinking";
 	const isSpeaking = stage === "speaking";
-	const resolveSTTModel = (modelId) => {
+	const resolveSTTModel$1 = (modelId) => {
 		return {
 			"whisper-tiny": "onnx-community/whisper-tiny",
 			"whisper-tiny.en": "onnx-community/whisper-tiny.en",
@@ -2381,7 +2381,7 @@ function useVoiceChat(options = {}) {
 					sttWorker.onerror = (e) => reject(new Error(e.message));
 					sttWorker.postMessage({
 						type: "load",
-						payload: { model: resolveSTTModel(sttModel) }
+						payload: { model: resolveSTTModel$1(sttModel) }
 					});
 				});
 				if (cancelled || !mountedRef.current) {
@@ -2831,7 +2831,8 @@ function useEmbedding(options = {}) {
 	const [loadingProgress, setLoadingProgress] = useState(null);
 	const workerRef = useRef(null);
 	const loadRequestedRef = useRef(false);
-	const pendingRequestsRef = useRef(/* @__PURE__ */ new Map());
+	const readyPromiseRef = useRef(null);
+	const readyResolveRef = useRef(null);
 	const cosineSimilarity = useCallback((a, b) => {
 		if (a.length !== b.length) throw new Error(`Vector dimensions must match: ${a.length} vs ${b.length}`);
 		let dotProduct = 0;
@@ -2847,13 +2848,17 @@ function useEmbedding(options = {}) {
 		return dotProduct / magnitude;
 	}, []);
 	const load = useCallback(() => {
-		if (loadRequestedRef.current || isReady) return;
+		if (isReady && workerRef.current) return Promise.resolve();
+		if (loadRequestedRef.current && readyPromiseRef.current) return readyPromiseRef.current;
 		loadRequestedRef.current = true;
 		setIsLoading(true);
 		setLoadingProgress({
 			status: "loading",
 			message: "Loading embedding model..."
 		});
+		readyPromiseRef.current = new Promise((resolve) => {
+			readyResolveRef.current = resolve;
+		});
 		const worker = createEmbeddingWorker();
 		workerRef.current = worker;
 		worker.onmessage = (e) => {
@@ -2868,23 +2873,19 @@ function useEmbedding(options = {}) {
 				setIsLoading(false);
 				setIsReady(true);
 				setLoadingProgress({ status: "ready" });
+				readyResolveRef.current?.();
 				onReady?.();
 			} else if (type === "error") {
 				setIsLoading(false);
 				setError(payload);
 				onError?.(payload);
-			} else if (type === "embedding" || type === "embeddings") {
-				const pending = pendingRequestsRef.current.get(type);
-				if (pending) {
-					pending.resolve(payload);
-					pendingRequestsRef.current.delete(type);
-				}
 			}
 		};
 		worker.postMessage({
 			type: "load",
 			payload: { model }
 		});
+		return readyPromiseRef.current;
 	}, [
 		model,
 		isReady,
@@ -2901,33 +2902,26 @@ function useEmbedding(options = {}) {
 		};
 	}, [autoLoad, load]);
 	const embed = useCallback(async (text) => {
-		if (!isReady) {
-			load();
-			await new Promise((resolve) => {
-				const checkReady = setInterval(() => {
-					if (workerRef.current) {
-						const handler = (e) => {
-							if (e.data.type === "ready") {
-								clearInterval(checkReady);
-								resolve();
-							}
-						};
-						workerRef.current.addEventListener("message", handler, { once: true });
-					}
-				}, 100);
-			});
-		}
+		const loadPromise = load();
+		if (readyPromiseRef.current) await readyPromiseRef.current;
+		else await loadPromise;
 		return new Promise((resolve, reject) => {
 			const worker = workerRef.current;
 			if (!worker) {
-				reject(/* @__PURE__ */ new Error("Worker not initialized"));
+				reject(/* @__PURE__ */ new Error("Worker not initialized. Call load() first."));
 				return;
 			}
+			const timeout = setTimeout(() => {
+				worker.removeEventListener("message", handler);
+				reject(/* @__PURE__ */ new Error("Embedding timeout after 30s"));
+			}, 3e4);
 			const handler = (e) => {
 				if (e.data.type === "embedding") {
+					clearTimeout(timeout);
 					worker.removeEventListener("message", handler);
 					resolve(e.data.payload.vector);
 				} else if (e.data.type === "error") {
+					clearTimeout(timeout);
 					worker.removeEventListener("message", handler);
 					reject(new Error(e.data.payload));
 				}
@@ -2941,34 +2935,28 @@ function useEmbedding(options = {}) {
 				}
 			});
 		});
-	}, [
-		isReady,
-		load,
-		normalize
-	]);
+	}, [load, normalize]);
 	const embedBatch = useCallback(async (texts) => {
-		if (!isReady) {
-			load();
-			await new Promise((resolve) => {
-				const check = setInterval(() => {
-					if (isReady) {
-						clearInterval(check);
-						resolve();
-					}
-				}, 100);
-			});
-		}
+		const loadPromise = load();
+		if (readyPromiseRef.current) await readyPromiseRef.current;
+		else await loadPromise;
 		return new Promise((resolve, reject) => {
 			const worker = workerRef.current;
 			if (!worker) {
-				reject(/* @__PURE__ */ new Error("Worker not initialized"));
+				reject(/* @__PURE__ */ new Error("Worker not initialized. Call load() first."));
 				return;
 			}
+			const timeout = setTimeout(() => {
+				worker.removeEventListener("message", handler);
+				reject(/* @__PURE__ */ new Error("Batch embedding timeout after 60s"));
+			}, 6e4);
 			const handler = (e) => {
 				if (e.data.type === "embeddings") {
+					clearTimeout(timeout);
 					worker.removeEventListener("message", handler);
 					resolve(e.data.payload);
 				} else if (e.data.type === "error") {
+					clearTimeout(timeout);
 					worker.removeEventListener("message", handler);
 					reject(new Error(e.data.payload));
 				}
@@ -2982,11 +2970,7 @@ function useEmbedding(options = {}) {
 				}
 			});
 		});
-	}, [
-		isReady,
-		load,
-		normalize
-	]);
+	}, [load, normalize]);
 	return {
 		embed,
 		embedBatch,
@@ -3026,6 +3010,191 @@ function useEmbedding(options = {}) {
 	};
 }
 /**
+* Preload a chat/LLM model (downloads to IndexedDB cache)
+*
+* Call this during app initialization to ensure the model is ready
+* when users need it.
+*
+* @example
+* ```ts
+* // In your app's initialization
+* import { preloadChatModel } from "@tryhamster/gerbil/browser";
+*
+* await preloadChatModel("qwen3-0.6b", {
+*   onProgress: (p) => console.log(p.status, p.progress),
+* });
+*
+* // Later, useChat will load instantly from cache
+* ```
+*/
+async function preloadChatModel(modelId, options = {}) {
+	const { onProgress } = options;
+	const worker = await createGerbilWorker({
+		modelId,
+		onProgress: (p) => {
+			if (p.status === "downloading") onProgress?.({
+				status: "downloading",
+				file: p.file,
+				progress: p.progress
+			});
+			else onProgress?.({
+				status: "loading",
+				message: p.status
+			});
+		}
+	});
+	onProgress?.({ status: "ready" });
+	worker.terminate();
+}
+/**
+* Preload an embedding model
+*
+* @example
+* ```ts
+* await preloadEmbeddingModel("Xenova/all-MiniLM-L6-v2");
+* ```
+*/
+async function preloadEmbeddingModel(modelId = "Xenova/all-MiniLM-L6-v2", options = {}) {
+	const { onProgress } = options;
+	return new Promise((resolve, reject) => {
+		const worker = createEmbeddingWorker();
+		worker.onmessage = (e) => {
+			const { type, payload } = e.data;
+			if (type === "progress") {
+				if (payload.status === "progress" && payload.file) onProgress?.({
+					status: "downloading",
+					file: payload.file,
+					progress: Math.round(payload.loaded / payload.total * 100)
+				});
+			} else if (type === "ready") {
+				onProgress?.({ status: "ready" });
+				worker.terminate();
+				resolve();
+			} else if (type === "error") {
+				onProgress?.({
+					status: "error",
+					message: payload
+				});
+				worker.terminate();
+				reject(new Error(payload));
+			}
+		};
+		onProgress?.({
+			status: "loading",
+			message: `Loading ${modelId}...`
+		});
+		worker.postMessage({
+			type: "load",
+			payload: { model: modelId }
+		});
+	});
+}
+/**
+* Preload a TTS model
+*
+* @example
+* ```ts
+* await preloadTTSModel("kokoro-82m");
+* ```
+*/
+async function preloadTTSModel(modelId = "kokoro-82m", options = {}) {
+	const { onProgress } = options;
+	const modelConfig = TTS_MODELS[modelId];
+	if (!modelConfig) throw new Error(`Unknown TTS model: ${modelId}`);
+	return new Promise((resolve, reject) => {
+		const worker = createTTSWorker();
+		worker.onmessage = (e) => {
+			const { type, payload } = e.data;
+			if (type === "progress") {
+				if (payload.status === "progress" && payload.file) onProgress?.({
+					status: "downloading",
+					file: payload.file,
+					progress: Math.round(payload.loaded / payload.total * 100)
+				});
+			} else if (type === "ready") {
+				onProgress?.({ status: "ready" });
+				worker.terminate();
+				resolve();
+			} else if (type === "error") {
+				onProgress?.({
+					status: "error",
+					message: payload
+				});
+				worker.terminate();
+				reject(new Error(payload));
+			}
+		};
+		onProgress?.({
+			status: "loading",
+			message: `Loading ${modelId}...`
+		});
+		worker.postMessage({
+			type: "load",
+			payload: {
+				modelId,
+				repo: modelConfig.repo,
+				voices: modelConfig.voices
+			}
+		});
+	});
+}
+/**
+* Preload an STT model
+*
+* @example
+* ```ts
+* await preloadSTTModel("whisper-tiny.en");
+* ```
+*/
+async function preloadSTTModel(modelId = "whisper-tiny.en", options = {}) {
+	const { onProgress } = options;
+	const resolved = resolveSTTModel(modelId);
+	return new Promise((resolve, reject) => {
+		const worker = createSTTWorker();
+		worker.onmessage = (e) => {
+			const { type, payload } = e.data;
+			if (type === "progress") {
+				if (payload.status === "progress" && payload.file) onProgress?.({
+					status: "downloading",
+					file: payload.file,
+					progress: Math.round(payload.loaded / payload.total * 100)
+				});
+			} else if (type === "ready") {
+				onProgress?.({ status: "ready" });
+				worker.terminate();
+				resolve();
+			} else if (type === "error") {
+				onProgress?.({
+					status: "error",
+					message: payload
+				});
+				worker.terminate();
+				reject(new Error(payload));
+			}
+		};
+		onProgress?.({
+			status: "loading",
+			message: `Loading ${modelId}...`
+		});
+		worker.postMessage({
+			type: "load",
+			payload: { model: resolved }
+		});
+	});
+}
+/** Helper to resolve STT model ID to repo */
+function resolveSTTModel(modelId) {
+	return {
+		"whisper-tiny": "onnx-community/whisper-tiny",
+		"whisper-tiny.en": "onnx-community/whisper-tiny.en",
+		"whisper-base": "onnx-community/whisper-base",
+		"whisper-base.en": "onnx-community/whisper-base.en",
+		"whisper-small": "onnx-community/whisper-small",
+		"whisper-small.en": "onnx-community/whisper-small.en",
+		"whisper-large-v3-turbo": "onnx-community/whisper-large-v3-turbo"
+	}[modelId] || modelId;
+}
+/**
 * Check if WebGPU is supported
 */
 function isWebGPUSupported() {
@@ -3055,9 +3224,13 @@ var browser_default = {
 	getWebGPUInfo,
 	createGerbilWorker,
 	playAudio,
-	createAudioPlayer
+	createAudioPlayer,
+	preloadChatModel,
+	preloadEmbeddingModel,
+	preloadTTSModel,
+	preloadSTTModel
 };
 
 //#endregion
-export { BUILTIN_MODELS, createAudioPlayer, createGerbilWorker, browser_default as default, getWebGPUInfo, isWebGPUSupported, playAudio, useChat, useCompletion, useEmbedding, useSpeech, useVoiceChat, useVoiceInput };
+export { BUILTIN_MODELS, createAudioPlayer, createGerbilWorker, browser_default as default, getWebGPUInfo, isWebGPUSupported, playAudio, preloadChatModel, preloadEmbeddingModel, preloadSTTModel, preloadTTSModel, useChat, useCompletion, useEmbedding, useSpeech, useVoiceChat, useVoiceInput };
 //# sourceMappingURL=index.js.map