@van1s1mys/ai-router 1.1.0 → 1.2.1

package/README.md

@@ -1,7 +1,12 @@
 # @van1s1mys/ai-router
 
+[![npm](https://img.shields.io/npm/v/@van1s1mys/ai-router)](https://www.npmjs.com/package/@van1s1mys/ai-router)
+[![GitHub](https://img.shields.io/github/stars/IvanMalkS/ai-router)](https://github.com/IvanMalkS/ai-router)
+
 Semantic search routing for SPAs — find the best route by meaning, not keywords.
 
+[Documentation](https://ivanmalks.github.io/ai-router/) | [Live Demo](https://ai-router-search.vercel.app) | [npm](https://www.npmjs.com/package/@van1s1mys/ai-router) | [GitHub](https://github.com/IvanMalkS/ai-router)
+
 Runs a HuggingFace embedding model inside a **Web Worker** and uses [Orama](https://orama.com) hybrid (text + vector) search to match user queries by semantic similarity.
 
 ## Install
@@ -32,6 +37,31 @@ const result = await router.search('how to reach support?');
 router.destroy(); // cleanup when done
 ```
 
+## Progressive model loading
+
+Start with a fast model, upgrade to a better one in the background:
+
+```ts
+const router = new SmartRouter({
+  routes,
+  model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small'],
+  onModelUpgrade: (modelId) => console.log(`Upgraded to ${modelId}`),
+});
+
+await router.ready; // first model ready — search works immediately
+```
+
+## Instance caching & preloading
+
+```ts
+// Pre-warm at page load
+SmartRouter.preload({ routes, model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small'] });
+
+// Later — returns cached instance, no re-download
+const router = SmartRouter.create({ routes, model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small'] });
+await router.ready; // instant if preload finished
+```
+
 ## Multilingual support
 
 The default model (`Xenova/all-MiniLM-L6-v2`) works best for English. For other languages, use the multilingual model:
@@ -50,12 +80,21 @@ const router = new SmartRouter({
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `routes` | `RouteConfig[]` | required | Routes to index |
-| `model` | `string` | `"Xenova/all-MiniLM-L6-v2"` | HuggingFace model ID (384-dim) |
+| `model` | `string \| string[]` | `"Xenova/all-MiniLM-L6-v2"` | Model ID or ordered array for progressive loading |
 | `threshold` | `number` | `0.5` | Minimum similarity score (0-1) |
+| `onModelUpgrade` | `(modelId: string) => void` | — | Called when the router switches to the next model |
+
+### `SmartRouter.create(options): SmartRouter`
+
+Returns a cached instance for the given model config. Safe to call on every component mount.
+
+### `SmartRouter.preload(options): SmartRouter`
+
+Same as `create()`, but intended to be called at page load to pre-warm the model.
 
 ### `router.ready: Promise<void>`
 
-Resolves when the model is loaded and routes are indexed. Resolves immediately during SSR.
+Resolves when the first model is loaded and routes are indexed. Resolves immediately during SSR.
 
 ### `router.search(query): Promise<SearchResult | null>`
 
@@ -63,7 +102,7 @@ Returns `{ path, score }` or `null` if no route meets the threshold. Returns `nu
 
 ### `router.destroy()`
 
-Terminates the worker and cleans up resources. Safe to call multiple times.
+Terminates the worker, cleans up resources, and removes from cache. Safe to call multiple times.
 
 ## SSR
 

package/dist/index.cjs

@@ -36,7 +36,7 @@ function createBlobWorker() {
   URL.revokeObjectURL(url);
   return worker;
 }
-var SmartRouter = class {
+var _SmartRouter = class _SmartRouter {
   /**
    * Creates a new SmartRouter instance.
    *
@@ -52,6 +52,7 @@ var SmartRouter = class {
     this.worker = null;
     this.pendingSearches = /* @__PURE__ */ new Map();
     this.destroyed = false;
+    this._cacheKey = null;
     this.ssr = !isBrowser;
     this.readyPromise = new Promise((resolve, reject) => {
       this.resolveReady = resolve;
@@ -64,6 +65,63 @@ var SmartRouter = class {
     this.onModelUpgrade = options.onModelUpgrade;
     this.initWorker(options);
   }
+  /**
+   * Returns a cached SmartRouter instance for the given options.
+   * If an instance with the same model configuration already exists and
+   * hasn't been destroyed, it is returned immediately — no new worker
+   * is spawned and no model is re-downloaded.
+   *
+   * Use this instead of `new SmartRouter()` when the router may be
+   * created multiple times (e.g. React component mounts/unmounts).
+   *
+   * @param options - Routes to index, model ID, and similarity threshold.
+   *
+   * @example
+   * ```ts
+   * // Safe to call on every mount — returns the same instance
+   * const router = SmartRouter.create({ routes, model: 'Xenova/all-MiniLM-L6-v2' });
+   * await router.ready;
+   * ```
+   */
+  static create(options) {
+    const key = _SmartRouter.cacheKey(options);
+    const cached = _SmartRouter.cache.get(key);
+    if (cached && !cached.destroyed) return cached;
+    const instance = new _SmartRouter(options);
+    instance._cacheKey = key;
+    _SmartRouter.cache.set(key, instance);
+    return instance;
+  }
+  /**
+   * Pre-downloads the model(s) and indexes routes in the background
+   * so that a later {@link create} call returns an already-ready instance.
+   *
+   * Safe to call at page load — runs in a Web Worker and does not
+   * block the main thread. No-op on the server (SSR).
+   * Calling it multiple times with the same options is a no-op.
+   *
+   * @param options - Routes to index, model ID, and similarity threshold.
+   * @returns The pre-warming SmartRouter instance (await `.ready` if needed).
+   *
+   * @example
+   * ```ts
+   * // At page load — start downloading the model immediately
+   * SmartRouter.preload({ routes, model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small'] });
+   *
+   * // Later, when the user opens search — instant, model is already loaded
+   * const router = SmartRouter.create({ routes, model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small'] });
+   * await router.ready; // resolves immediately if preload finished
+   * ```
+   */
+  static preload(options) {
+    return _SmartRouter.create(options);
+  }
+  /** @internal Generates a stable cache key from options. */
+  static cacheKey(options) {
+    return JSON.stringify(
+      Array.isArray(options.model) ? options.model : [options.model || "Xenova/all-MiniLM-L6-v2"]
+    );
+  }
   /**
    * Promise that resolves when the model is loaded and routes are indexed.
    * Rejects if initialization fails (e.g. network error, invalid model).
@@ -195,6 +253,9 @@ var SmartRouter = class {
   destroy() {
     if (this.destroyed) return;
     this.destroyed = true;
+    if (this._cacheKey) {
+      _SmartRouter.cache.delete(this._cacheKey);
+    }
     this.rejectAllPending(new Error("SmartRouter destroyed"));
     if (this.worker) {
       try {
@@ -213,6 +274,8 @@ var SmartRouter = class {
     this.pendingSearches.clear();
   }
 };
+_SmartRouter.cache = /* @__PURE__ */ new Map();
+var SmartRouter = _SmartRouter;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SmartRouter

package/dist/index.d.cts

@@ -119,6 +119,7 @@ interface SearchResult {
  * ```
  */
 declare class SmartRouter {
+    private static cache;
     private worker;
     private readyPromise;
     private resolveReady;
@@ -127,6 +128,50 @@ declare class SmartRouter {
     private destroyed;
     private readonly ssr;
     private onModelUpgrade?;
+    private _cacheKey;
+    /**
+     * Returns a cached SmartRouter instance for the given options.
+     * If an instance with the same model configuration already exists and
+     * hasn't been destroyed, it is returned immediately — no new worker
+     * is spawned and no model is re-downloaded.
+     *
+     * Use this instead of `new SmartRouter()` when the router may be
+     * created multiple times (e.g. React component mounts/unmounts).
+     *
+     * @param options - Routes to index, model ID, and similarity threshold.
+     *
+     * @example
+     * ```ts
+     * // Safe to call on every mount — returns the same instance
+     * const router = SmartRouter.create({ routes, model: 'Xenova/all-MiniLM-L6-v2' });
+     * await router.ready;
+     * ```
+     */
+    static create(options: RouteOptions): SmartRouter;
+    /**
+     * Pre-downloads the model(s) and indexes routes in the background
+     * so that a later {@link create} call returns an already-ready instance.
+     *
+     * Safe to call at page load — runs in a Web Worker and does not
+     * block the main thread. No-op on the server (SSR).
+     * Calling it multiple times with the same options is a no-op.
+     *
+     * @param options - Routes to index, model ID, and similarity threshold.
+     * @returns The pre-warming SmartRouter instance (await `.ready` if needed).
+     *
+     * @example
+     * ```ts
+     * // At page load — start downloading the model immediately
+     * SmartRouter.preload({ routes, model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small'] });
+     *
+     * // Later, when the user opens search — instant, model is already loaded
+     * const router = SmartRouter.create({ routes, model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small'] });
+     * await router.ready; // resolves immediately if preload finished
+     * ```
+     */
+    static preload(options: RouteOptions): SmartRouter;
+    /** @internal Generates a stable cache key from options. */
+    private static cacheKey;
     /**
      * Creates a new SmartRouter instance.
      *

package/dist/index.d.ts

@@ -119,6 +119,7 @@ interface SearchResult {
  * ```
  */
 declare class SmartRouter {
+    private static cache;
     private worker;
     private readyPromise;
     private resolveReady;
@@ -127,6 +128,50 @@ declare class SmartRouter {
     private destroyed;
     private readonly ssr;
     private onModelUpgrade?;
+    private _cacheKey;
+    /**
+     * Returns a cached SmartRouter instance for the given options.
+     * If an instance with the same model configuration already exists and
+     * hasn't been destroyed, it is returned immediately — no new worker
+     * is spawned and no model is re-downloaded.
+     *
+     * Use this instead of `new SmartRouter()` when the router may be
+     * created multiple times (e.g. React component mounts/unmounts).
+     *
+     * @param options - Routes to index, model ID, and similarity threshold.
+     *
+     * @example
+     * ```ts
+     * // Safe to call on every mount — returns the same instance
+     * const router = SmartRouter.create({ routes, model: 'Xenova/all-MiniLM-L6-v2' });
+     * await router.ready;
+     * ```
+     */
+    static create(options: RouteOptions): SmartRouter;
+    /**
+     * Pre-downloads the model(s) and indexes routes in the background
+     * so that a later {@link create} call returns an already-ready instance.
+     *
+     * Safe to call at page load — runs in a Web Worker and does not
+     * block the main thread. No-op on the server (SSR).
+     * Calling it multiple times with the same options is a no-op.
+     *
+     * @param options - Routes to index, model ID, and similarity threshold.
+     * @returns The pre-warming SmartRouter instance (await `.ready` if needed).
+     *
+     * @example
+     * ```ts
+     * // At page load — start downloading the model immediately
+     * SmartRouter.preload({ routes, model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small'] });
+     *
+     * // Later, when the user opens search — instant, model is already loaded
+     * const router = SmartRouter.create({ routes, model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small'] });
+     * await router.ready; // resolves immediately if preload finished
+     * ```
+     */
+    static preload(options: RouteOptions): SmartRouter;
+    /** @internal Generates a stable cache key from options. */
+    private static cacheKey;
     /**
      * Creates a new SmartRouter instance.
      *

package/dist/index.js

@@ -10,7 +10,7 @@ function createBlobWorker() {
   URL.revokeObjectURL(url);
   return worker;
 }
-var SmartRouter = class {
+var _SmartRouter = class _SmartRouter {
   /**
    * Creates a new SmartRouter instance.
    *
@@ -26,6 +26,7 @@ var SmartRouter = class {
     this.worker = null;
     this.pendingSearches = /* @__PURE__ */ new Map();
     this.destroyed = false;
+    this._cacheKey = null;
     this.ssr = !isBrowser;
     this.readyPromise = new Promise((resolve, reject) => {
       this.resolveReady = resolve;
@@ -38,6 +39,63 @@ var SmartRouter = class {
     this.onModelUpgrade = options.onModelUpgrade;
     this.initWorker(options);
   }
+  /**
+   * Returns a cached SmartRouter instance for the given options.
+   * If an instance with the same model configuration already exists and
+   * hasn't been destroyed, it is returned immediately — no new worker
+   * is spawned and no model is re-downloaded.
+   *
+   * Use this instead of `new SmartRouter()` when the router may be
+   * created multiple times (e.g. React component mounts/unmounts).
+   *
+   * @param options - Routes to index, model ID, and similarity threshold.
+   *
+   * @example
+   * ```ts
+   * // Safe to call on every mount — returns the same instance
+   * const router = SmartRouter.create({ routes, model: 'Xenova/all-MiniLM-L6-v2' });
+   * await router.ready;
+   * ```
+   */
+  static create(options) {
+    const key = _SmartRouter.cacheKey(options);
+    const cached = _SmartRouter.cache.get(key);
+    if (cached && !cached.destroyed) return cached;
+    const instance = new _SmartRouter(options);
+    instance._cacheKey = key;
+    _SmartRouter.cache.set(key, instance);
+    return instance;
+  }
+  /**
+   * Pre-downloads the model(s) and indexes routes in the background
+   * so that a later {@link create} call returns an already-ready instance.
+   *
+   * Safe to call at page load — runs in a Web Worker and does not
+   * block the main thread. No-op on the server (SSR).
+   * Calling it multiple times with the same options is a no-op.
+   *
+   * @param options - Routes to index, model ID, and similarity threshold.
+   * @returns The pre-warming SmartRouter instance (await `.ready` if needed).
+   *
+   * @example
+   * ```ts
+   * // At page load — start downloading the model immediately
+   * SmartRouter.preload({ routes, model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small'] });
+   *
+   * // Later, when the user opens search — instant, model is already loaded
+   * const router = SmartRouter.create({ routes, model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small'] });
+   * await router.ready; // resolves immediately if preload finished
+   * ```
+   */
+  static preload(options) {
+    return _SmartRouter.create(options);
+  }
+  /** @internal Generates a stable cache key from options. */
+  static cacheKey(options) {
+    return JSON.stringify(
+      Array.isArray(options.model) ? options.model : [options.model || "Xenova/all-MiniLM-L6-v2"]
+    );
+  }
   /**
    * Promise that resolves when the model is loaded and routes are indexed.
    * Rejects if initialization fails (e.g. network error, invalid model).
@@ -169,6 +227,9 @@ var SmartRouter = class {
   destroy() {
     if (this.destroyed) return;
     this.destroyed = true;
+    if (this._cacheKey) {
+      _SmartRouter.cache.delete(this._cacheKey);
+    }
     this.rejectAllPending(new Error("SmartRouter destroyed"));
     if (this.worker) {
       try {
@@ -187,6 +248,8 @@ var SmartRouter = class {
     this.pendingSearches.clear();
   }
 };
+_SmartRouter.cache = /* @__PURE__ */ new Map();
+var SmartRouter = _SmartRouter;
 export {
   SmartRouter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@van1s1mys/ai-router",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Semantic search routing using AI embeddings — find the best route by meaning, not keywords",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -34,6 +34,15 @@
     "spa",
     "navigation"
   ],
+  "homepage": "https://ivanmalks.github.io/ai-router/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IvanMalkS/ai-router.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/IvanMalkS/ai-router/issues"
+  },
   "license": "MIT",
   "devDependencies": {
     "esbuild": "^0.27.0"