feat(intelligence) Add model name caching

intelligence/ts/src/engines/common.ts

@@ -14,15 +14,79 @@
 // =============================================================================
 
 import { REMOTE_URL, SDK, VERSION } from '../constants';
+import { isNode } from '../env';
 import { FailureCode, Result } from '../typing';
 
+const STALE_TIMEOUT_MS = 24 * 60 * 60 * 1000; // 24 hours.
+const CACHE_KEY = 'flowerintelligence-model-name-cache'; // For browser localStorage.
+
 interface ModelResponse {
   is_supported: boolean;
   engine_model: string | undefined;
   model: string | undefined;
 }
 
-export async function getEngineModelName(model: string, engine: string): Promise<Result<string>> {
+interface CachedEntry {
+  engineModel: string;
+  timestamp: number;
+}
+
+interface CachedMapping {
+  mapping: Record<string, CachedEntry>;
+}
+
+async function getCacheFilePath(): Promise<string> {
+  if (!isNode) return ''; // Not used in browsers.
+  const path = await import('path');
+  const os = await import('os');
+  const fs = await import('fs/promises');
+
+  const homeDir = os.homedir();
+  const cacheFolder = path.join(homeDir, '.flwr', 'cache');
+  await fs.mkdir(cacheFolder, { recursive: true });
+  return path.join(cacheFolder, 'intelligence-model-names.json');
+}
+
+/**
+ * Loads the cached mapping from persistent storage.
+ */
+async function loadCache(): Promise<CachedMapping | null> {
+  if (isNode) {
+    try {
+      const { readFile } = await import('fs/promises');
+      const filePath = await getCacheFilePath();
+      const data = await readFile(filePath, 'utf-8');
+      return JSON.parse(data) as CachedMapping;
+    } catch (_) {
+      return null;
+    }
+  } else {
+    const data = localStorage.getItem(CACHE_KEY);
+    if (data) {
+      try {
+        return JSON.parse(data) as CachedMapping;
+      } catch {
+        return null;
+      }
+    }
+    return null;
+  }
+}
+
+/**
+ * Saves the cache to persistent storage.
+ */
+async function saveCache(cache: CachedMapping): Promise<void> {
+  if (isNode) {
+    const { writeFile } = await import('fs/promises');
+    const filePath = await getCacheFilePath();
+    await writeFile(filePath, JSON.stringify(cache), 'utf-8');
+  } else {
+    localStorage.setItem(CACHE_KEY, JSON.stringify(cache));
+  }
+}
+
+async function updateModel(model: string, engine: string): Promise<Result<string>> {
   try {
     const response = await fetch(`${REMOTE_URL}/v1/fetch-model-config`, {
       method: 'POST',
@@ -48,8 +112,10 @@ export async function getEngineModelName(model: string, engine: string): Promise
     const data = (await response.json()) as ModelResponse;
 
     if (data.is_supported && data.engine_model) {
+      await addOrUpdateCache(model, engine, data.engine_model);
       return { ok: true, value: data.engine_model };
     } else {
+      await removeFromCache(model, engine);
       return {
         ok: false,
         failure: {
@@ -68,3 +134,60 @@ export async function getEngineModelName(model: string, engine: string): Promise
     };
   }
 }
+
+/**
+ * Adds or updates a model mapping in the cache with the current timestamp.
+ */
+async function addOrUpdateCache(model: string, engine: string, engineModel: string): Promise<void> {
+  const now = Date.now();
+  let cache = await loadCache();
+  if (!cache) {
+    cache = { mapping: {} };
+  }
+  const key = `${model}_${engine}`;
+  cache.mapping[key] = { engineModel, timestamp: now };
+  await saveCache(cache);
+}
+
+/**
+ * Removes a model from the cache.
+ */
+async function removeFromCache(model: string, engine: string): Promise<void> {
+  const cache = await loadCache();
+  const key = `${model}_${engine}`;
+  if (cache && key in cache.mapping) {
+    const { [key]: removed, ...rest } = cache.mapping;
+    cache.mapping = rest;
+    await saveCache(cache);
+  }
+}
+
+/**
+ * Checks if a model is supported.
+ * - If the model exists in the cache and its timestamp is fresh, return it.
+ * - If it exists but is stale (older than 24 hours), trigger a background update (and return the stale mapping).
+ * - If it does not exist, update synchronously.
+ */
+export async function getEngineModelName(model: string, engine: string): Promise<Result<string>> {
+  const now = Date.now();
+  let cache = await loadCache();
+  if (!cache) {
+    cache = { mapping: {} };
+  }
+
+  const key = `${model}_${engine}`;
+  if (key in cache.mapping) {
+    const cachedEntry = cache.mapping[key];
+    // If the cached entry is stale, trigger a background update.
+    if (now - cachedEntry.timestamp > STALE_TIMEOUT_MS) {
+      updateModel(model, engine).catch((err: unknown) => {
+        console.warn(`Background update failed for model ${model}:`, String(err));
+      });
+    }
+    // Return the (possibly stale) cached result.
+    return { ok: true, value: cachedEntry.engineModel };
+  } else {
+    // Not in cache, call updateModel synchronously.
+    return await updateModel(model, engine);
+  }
+}

intelligence/ts/src/env.ts

@@ -0,0 +1,18 @@
+// Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// =============================================================================
+
+/* eslint-disable @typescript-eslint/no-unnecessary-condition */
+export const isNode: boolean = typeof process !== 'undefined' && process.versions?.node != null;
+/* eslint-enable @typescript-eslint/no-unnecessary-condition */

intelligence/ts/src/flowerintelligence.ts

@@ -19,10 +19,7 @@ import { TransformersEngine } from './engines/transformersEngine';
 import { ChatOptions, ChatResponseResult, FailureCode, Message, Progress, Result } from './typing';
 import { WebllmEngine } from './engines/webllmEngine';
 import { DEFAULT_MODEL } from './constants';
-
-/* eslint-disable @typescript-eslint/no-unnecessary-condition */
-const isNode = typeof process !== 'undefined' && process.versions.node != null;
-/* eslint-enable @typescript-eslint/no-unnecessary-condition */
+import { isNode } from './env';
 
 /**
  * Class representing the core intelligence service for Flower Labs.

intelligence/ts/vite.config.ts

@@ -18,7 +18,15 @@ export default defineConfig({
       fileName: (format) => `flowerintelligence.${format}.js`,
     },
     rollupOptions: {
-      external: ['@huggingface/transformers', '@mlc-ai/web-llm', 'crypto'],
+      external: [
+        '@huggingface/transformers',
+        '@mlc-ai/web-llm',
+        'crypto',
+        'fs',
+        'fs/promises',
+        'path',
+        'os',
+      ],
     },
   },
 });