@van1s1mys/ai-router 1.0.1 → 1.2.0

package/dist/index.d.cts

@@ -40,11 +40,29 @@ interface RouteOptions {
     /** Array of routes to index for semantic search. */
     routes: RouteConfig[];
     /**
-     * HuggingFace model ID for generating embeddings.
+     * HuggingFace model ID (or an ordered array of IDs) for generating embeddings.
      * Must produce 384-dimensional vectors.
+     *
+     * When an array is provided, the first model is loaded and used immediately.
+     * Heavier models are downloaded in the background; once ready, the router
+     * hot-swaps to the next model and re-indexes all routes automatically.
+     *
      * @default "Xenova/all-MiniLM-L6-v2"
+     *
+     * @example
+     * ```ts
+     * // Start fast with a light model, upgrade to a better one in the background
+     * model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small']
+     * ```
      */
-    model?: string;
+    model?: string | string[];
+    /**
+     * Called each time the router upgrades to the next model in the chain.
+     * Only relevant when {@link model} is an array with more than one entry.
+     *
+     * @param modelId - The HuggingFace model ID that just became active.
+     */
+    onModelUpgrade?: (modelId: string) => void;
     /**
      * Minimum similarity score (0–1) for a result to be returned.
      * Results below this threshold are discarded.
@@ -83,10 +101,13 @@ interface SearchResult {
  *     { path: '/pricing', title: 'Pricing', description: 'cost, plans, subscription' },
  *     { path: '/contact', title: 'Contact', description: 'support, phone, address' },
  *   ],
+ *   // Start with a fast lightweight model, then upgrade to a better one in the background
+ *   model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small'],
  *   threshold: 0.5,
+ *   onModelUpgrade: (modelId) => console.log(`Upgraded to ${modelId}`),
  * });
  *
- * // Wait for the model to load (~22 MB on first run, cached afterwards)
+ * // Wait for the first (lightest) model to load — ready to search immediately
  * await router.ready;
  *
  * // Search by meaning — typos and synonyms work too
@@ -98,6 +119,7 @@ interface SearchResult {
  * ```
  */
 declare class SmartRouter {
+    private static cache;
     private worker;
     private readyPromise;
     private resolveReady;
@@ -105,6 +127,51 @@ declare class SmartRouter {
     private pendingSearches;
     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

@@ -40,11 +40,29 @@ interface RouteOptions {
     /** Array of routes to index for semantic search. */
     routes: RouteConfig[];
     /**
-     * HuggingFace model ID for generating embeddings.
+     * HuggingFace model ID (or an ordered array of IDs) for generating embeddings.
      * Must produce 384-dimensional vectors.
+     *
+     * When an array is provided, the first model is loaded and used immediately.
+     * Heavier models are downloaded in the background; once ready, the router
+     * hot-swaps to the next model and re-indexes all routes automatically.
+     *
      * @default "Xenova/all-MiniLM-L6-v2"
+     *
+     * @example
+     * ```ts
+     * // Start fast with a light model, upgrade to a better one in the background
+     * model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small']
+     * ```
      */
-    model?: string;
+    model?: string | string[];
+    /**
+     * Called each time the router upgrades to the next model in the chain.
+     * Only relevant when {@link model} is an array with more than one entry.
+     *
+     * @param modelId - The HuggingFace model ID that just became active.
+     */
+    onModelUpgrade?: (modelId: string) => void;
     /**
      * Minimum similarity score (0–1) for a result to be returned.
      * Results below this threshold are discarded.
@@ -83,10 +101,13 @@ interface SearchResult {
  *     { path: '/pricing', title: 'Pricing', description: 'cost, plans, subscription' },
  *     { path: '/contact', title: 'Contact', description: 'support, phone, address' },
  *   ],
+ *   // Start with a fast lightweight model, then upgrade to a better one in the background
+ *   model: ['Xenova/all-MiniLM-L6-v2', 'Xenova/multilingual-e5-small'],
  *   threshold: 0.5,
+ *   onModelUpgrade: (modelId) => console.log(`Upgraded to ${modelId}`),
  * });
  *
- * // Wait for the model to load (~22 MB on first run, cached afterwards)
+ * // Wait for the first (lightest) model to load — ready to search immediately
  * await router.ready;
  *
  * // Search by meaning — typos and synonyms work too
@@ -98,6 +119,7 @@ interface SearchResult {
  * ```
  */
 declare class SmartRouter {
+    private static cache;
     private worker;
     private readyPromise;
     private resolveReady;
@@ -105,6 +127,51 @@ declare class SmartRouter {
     private pendingSearches;
     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.
      *