@runanywhere/web 0.1.0-beta.1

package/dist/Infrastructure/ModelManager.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Model Manager - Thin orchestrator for model lifecycle
+ *
+ * Composes ModelRegistry (catalog) + ModelDownloader (downloads) and adds
+ * model-loading orchestration (STT / TTS / LLM / VLM routing).
+ *
+ * The public API is unchanged — `ModelManager` is still a singleton that
+ * exposes `registerModels()`, `downloadModel()`, `loadModel()`, `onChange()`, etc.
+ * Internally it delegates catalog operations to the Registry and download
+ * operations to the Downloader.
+ */
+import { ModelCategory, LLMFramework, ModelStatus, DownloadStage } from '../types/enums';
+import type { LLMModelLoader, STTModelLoader, TTSModelLoader, VADModelLoader } from './ModelLoaderTypes';
+import type { ManagedModel, CompactModelDef, DownloadProgress, ModelFileDescriptor, ModelChangeCallback, ArtifactType } from './ModelRegistry';
+export { ModelCategory, LLMFramework, ModelStatus, DownloadStage };
+export type { ManagedModel, CompactModelDef, DownloadProgress, ModelFileDescriptor, ArtifactType };
+/** Parameters for loading a VLM model in a dedicated worker. */
+export interface VLMLoadParams {
+    modelOpfsKey: string;
+    modelFilename: string;
+    mmprojOpfsKey: string;
+    mmprojFilename: string;
+    modelId: string;
+    modelName: string;
+    /**
+     * Optional: raw model data to transfer to the Worker when OPFS doesn't
+     * have the file (memory-cache fallback for quota-exceeded scenarios).
+     * Transferred via postMessage (zero-copy).
+     */
+    modelData?: ArrayBuffer;
+    /** Optional: raw mmproj data (same fallback). */
+    mmprojData?: ArrayBuffer;
+}
+/**
+ * Interface for VLM (vision-language model) loading.
+ * The app provides an implementation (typically backed by a Web Worker)
+ * via `ModelManager.setVLMLoader()`.
+ */
+export interface VLMLoader {
+    init(): Promise<void>;
+    readonly isInitialized: boolean;
+    loadModel(params: VLMLoadParams): Promise<void>;
+    unloadModel(): Promise<void>;
+}
+declare class ModelManagerImpl {
+    private readonly registry;
+    private readonly storage;
+    private readonly downloader;
+    /**
+     * Tracks loaded models per category — allows STT + LLM + TTS simultaneously
+     * for the voice pipeline. Key = ModelCategory, Value = model id.
+     */
+    private loadedByCategory;
+    /** LRU metadata: lastUsedAt timestamps persisted in OPFS */
+    private metadata;
+    /** Pluggable VLM loader (set by the app via setVLMLoader) */
+    private vlmLoader;
+    /** Pluggable model loaders — registered by the Public layer during init */
+    private llmLoader;
+    private sttLoader;
+    private ttsLoader;
+    private vadLoader;
+    constructor();
+    private initStorage;
+    /**
+     * Register a catalog of models. Resolves compact definitions into full
+     * ManagedModel entries and checks OPFS for previously downloaded files.
+     */
+    registerModels(models: CompactModelDef[]): void;
+    /**
+     * Set the VLM loader implementation. Called by the app to plug in
+     * worker-based VLM loading (the SDK doesn't create Web Workers directly).
+     */
+    setVLMLoader(loader: VLMLoader): void;
+    /** Register the LLM model loader (text generation extension). */
+    setLLMLoader(loader: LLMModelLoader): void;
+    /** Register the STT model loader (speech-to-text extension). */
+    setSTTLoader(loader: STTModelLoader): void;
+    /** Register the TTS model loader (text-to-speech extension). */
+    setTTSLoader(loader: TTSModelLoader): void;
+    /** Register the VAD model loader (voice activity detection extension). */
+    setVADLoader(loader: VADModelLoader): void;
+    /** Request persistent storage to prevent browser from evicting cached models */
+    private requestPersistentStorage;
+    /**
+     * Check OPFS for models that were downloaded in a previous session.
+     * Updates their status from 'registered' to 'downloaded'.
+     * Also loads persisted LRU metadata for each model.
+     * Only checks file existence + size — does NOT read file contents into memory.
+     */
+    private refreshDownloadStatus;
+    getModels(): ManagedModel[];
+    getModelsByCategory(category: ModelCategory): ManagedModel[];
+    getModelsByFramework(framework: LLMFramework): ManagedModel[];
+    getLLMModels(): ManagedModel[];
+    getVLMModels(): ManagedModel[];
+    getSTTModels(): ManagedModel[];
+    getTTSModels(): ManagedModel[];
+    getVADModels(): ManagedModel[];
+    getLoadedModel(category?: ModelCategory): ManagedModel | null;
+    getLoadedModelId(category?: ModelCategory): string | null;
+    /** Check if models for all given categories are loaded */
+    areAllLoaded(categories: ModelCategory[]): boolean;
+    /**
+     * Ensure a model is loaded for the given category.
+     * If already loaded, returns the loaded model. If a downloaded model exists,
+     * loads it automatically. Returns null if no suitable model is available.
+     *
+     * @param options.coexist  Forwarded to `loadModel()`. When true, only swaps
+     *   models of the same category instead of unloading everything.
+     */
+    ensureLoaded(category: ModelCategory, options?: {
+        coexist?: boolean;
+    }): Promise<ManagedModel | null>;
+    /**
+     * Check whether downloading a model will fit in OPFS without eviction.
+     * Returns a result indicating whether it fits and which models could be
+     * evicted if not. Does NOT perform any mutations.
+     */
+    checkDownloadFit(modelId: string): Promise<import('./ModelDownloader').QuotaCheckResult>;
+    downloadModel(modelId: string): Promise<void>;
+    /**
+     * Load a model by ID.
+     *
+     * @param options.coexist  When `true`, only unload the model of the **same
+     *   category** (swap) rather than unloading ALL loaded models. Use this for
+     *   multi-model pipelines like Voice (STT + LLM + TTS).
+     *   Default is `false` — unloads everything to reclaim memory.
+     */
+    loadModel(modelId: string, options?: {
+        coexist?: boolean;
+    }): Promise<boolean>;
+    unloadModel(modelId: string): Promise<void>;
+    /**
+     * Unload ALL currently loaded models.
+     *
+     * Called automatically before loading a new model, and can also be called
+     * explicitly by app code (e.g. on tab switch) to release all resources.
+     *
+     * @param exceptModelId - Optional model ID to skip (the model about to be loaded).
+     *                        Avoids redundant unload+reload of the same model.
+     */
+    unloadAll(exceptModelId?: string): Promise<void>;
+    deleteModel(modelId: string): Promise<void>;
+    /** Clear all models from OPFS and reset registry statuses. */
+    clearAll(): Promise<void>;
+    getStorageInfo(): Promise<{
+        modelCount: number;
+        totalSize: number;
+        available: number;
+    }>;
+    /** Get the last-used timestamp for a model (0 if never recorded). */
+    getModelLastUsedAt(modelId: string): number;
+    /** Update lastUsedAt for a model and persist to OPFS (fire-and-forget). */
+    private touchLastUsed;
+    /** Remove metadata entry when a model is deleted. */
+    private removeMetadata;
+    onChange(callback: ModelChangeCallback): () => void;
+    /**
+     * Load an LLM/VLM model into the RACommons Emscripten FS.
+     */
+    private loadLLMModel;
+    /**
+     * Load an STT model into sherpa-onnx.
+     *
+     * Supports two modes:
+     *  1. **Archive** (isArchive=true): Download is a .tar.gz that bundles encoder,
+     *     decoder, tokens, etc. Matches the Swift SDK approach.
+     *  2. **Individual files**: Separate encoder/decoder/tokens downloads.
+     */
+    private loadSTTModel;
+    /**
+     * Load an STT model from a .tar.gz archive (matching Swift SDK approach).
+     * Extracts encoder, decoder, and tokens from the archive automatically.
+     */
+    private loadSTTFromArchive;
+    /**
+     * Load an STT model from individual downloaded files (legacy path).
+     */
+    private loadSTTFromIndividualFiles;
+    /**
+     * Load a TTS model into the sherpa-onnx Emscripten FS and initialise the TTS engine.
+     *
+     * Supports two modes:
+     *  1. **Archive** (isArchive=true): Download is a .tar.gz that bundles model files +
+     *     espeak-ng-data. Matches the Swift SDK approach — extract and write all files.
+     *  2. **Individual files** (legacy): Separate model + companion file downloads.
+     */
+    private loadTTSModel;
+    /**
+     * Load a TTS model from a .tar.gz archive (matching Swift SDK approach).
+     *
+     * The archive contains all necessary files in a nested directory:
+     *   model.onnx, tokens.txt, espeak-ng-data/, etc.
+     * We extract everything and write it to the sherpa virtual FS.
+     */
+    private loadTTSFromArchive;
+    /**
+     * Load a TTS model from individual downloaded files.
+     * Used when models are registered with individual file URLs (e.g. HuggingFace)
+     * rather than tar.gz archives. Downloads espeak-ng-data on-demand for Piper models.
+     */
+    private loadTTSFromIndividualFiles;
+    /**
+     * Load a VAD model (Silero) into the sherpa-onnx Emscripten FS.
+     * The Silero VAD is a single ONNX file — write it to FS and initialise.
+     */
+    private loadVADModel;
+    /**
+     * Find the common directory prefix in archive entry paths.
+     * Archives typically contain a single top-level directory (nested structure).
+     * Returns the prefix including trailing '/', or empty string if no common prefix.
+     */
+    private findArchivePrefix;
+    /** Unload the currently loaded model for a specific category */
+    private unloadModelByCategory;
+}
+export declare const ModelManager: ModelManagerImpl;
+//# sourceMappingURL=ModelManager.d.ts.map

package/dist/Infrastructure/ModelManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModelManager.d.ts","sourceRoot":"","sources":["../../src/Infrastructure/ModelManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAgB,MAAM,gBAAgB,CAAC;AACvG,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAMzG,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,YAAY,EACb,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC;AACnE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,YAAY,EAAE,CAAC;AAMnG,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,iDAAiD;IACjD,UAAU,CAAC,EAAE,WAAW,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAQD,cAAM,gBAAgB;IACpB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAE7C;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAAyC;IAEjE,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAmB;IAEnC,6DAA6D;IAC7D,OAAO,CAAC,SAAS,CAA0B;IAE3C,2EAA2E;IAC3E,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,SAAS,CAA+B;IAChD,OAAO,CAAC,SAAS,CAA+B;;YAUlC,WAAW;IAMzB;;;OAGG;IACH,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,IAAI;IAM/C;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAIrC,iEAAiE;IACjE,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAE1C,gEAAgE;IAChE,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAE1C,gEAAgE;IAChE,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAE1C,0EAA0E;IAC1E,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAI1C,gFAAgF;YAClE,wBAAwB;IAWtC;;;;;OAKG;YACW,qBAAqB;IAgCnC,SAAS,IAAI,YAAY,EAAE;IAI3B,mBAAmB,CAAC,QAAQ,EAAE,aAAa,GAAG,YAAY,EAAE;IAI5D,oBAAoB,CAAC,SAAS,EAAE,YAAY,GAAG,YAAY,EAAE;IAI7D,YAAY,IAAI,YAAY,EAAE;IAI9B,YAAY,IAAI,YAAY,EAAE;IAI9B,YAAY,IAAI,YAAY,EAAE;IAI9B,YAAY,IAAI,YAAY,EAAE;IAI9B,YAAY,IAAI,YAAY,EAAE;IAI9B,cAAc,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,YAAY,GAAG,IAAI;IAQ7D,gBAAgB,CAAC,QAAQ,CAAC,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI;IAQzD,0DAA0D;IAC1D,YAAY,CAAC,UAAU,EAAE,aAAa,EAAE,GAAG,OAAO;IAIlD;;;;;;;OAOG;IACG,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAmB1G;;;;OAIG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,mBAAmB,EAAE,gBAAgB,CAAC;IASxF,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnD;;;;;;;OAOG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAoF7E,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOjD;;;;;;;;OAQG;IACG,SAAS,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYhD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwBjD,8DAA8D;IACxD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAezB,cAAc,IAAI,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IA+B7F,qEAAqE;IACrE,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAI3C,2EAA2E;IAC3E,OAAO,CAAC,aAAa;IAMrB,qDAAqD;IACrD,OAAO,CAAC,cAAc;IAOtB,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,IAAI;IAQnD;;OAEG;YACW,YAAY;IAiG1B;;;;;;;OAOG;YACW,YAAY;IAiB1B;;;OAGG;YACW,kBAAkB;IA4EhC;;OAEG;YACW,0BAA0B;IAqFxC;;;;;;;OAOG;YACW,YAAY;IAiB1B;;;;;;OAMG;YACW,kBAAkB;IAyDhC;;;;OAIG;YACW,0BAA0B;IA4CxC;;;OAGG;YACW,YAAY;IAgB1B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAYzB,gEAAgE;YAClD,qBAAqB;CA4CpC;AAED,eAAO,MAAM,YAAY,kBAAyB,CAAC"}