@van1s1mys/ai-router 1.0.1 → 1.2.0

package/README.md

@@ -32,6 +32,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 +75,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 +97,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