@qvac/sdk 0.4.1 → 0.6.0

package/dist/server/bare/rag-hyperdb/rag-operation-manager.d.ts

@@ -0,0 +1,7 @@
+import { type AbortSignal } from "bare-abort-controller";
+export declare function getWorkspaceKey(workspace?: string): string;
+export declare function registerRagOperation(workspace: string | undefined, operation: string): AbortSignal;
+export declare function unregisterRagOperation(workspace?: string): void;
+export declare function cancelRagOperation(workspace?: string): boolean;
+export declare function cancelAllRagOperations(): void;
+//# sourceMappingURL=rag-operation-manager.d.ts.map

package/dist/server/bare/rag-hyperdb/rag-operation-manager.js

@@ -0,0 +1,39 @@
+import { AbortController } from "bare-abort-controller";
+import { DEFAULT_WORKSPACE } from "./rag-workspace-manager.js";
+// Map of workspace -> active operation
+const activeOperations = new Map();
+export function getWorkspaceKey(workspace) {
+    return workspace ?? DEFAULT_WORKSPACE;
+}
+export function registerRagOperation(workspace, operation) {
+    const key = getWorkspaceKey(workspace);
+    // Cancel any existing operation on this workspace
+    cancelRagOperation(workspace);
+    const abortController = new AbortController();
+    activeOperations.set(key, {
+        abortController,
+        operation,
+        startTime: Date.now(),
+    });
+    return abortController.signal;
+}
+export function unregisterRagOperation(workspace) {
+    const key = getWorkspaceKey(workspace);
+    activeOperations.delete(key);
+}
+export function cancelRagOperation(workspace) {
+    const key = getWorkspaceKey(workspace);
+    const entry = activeOperations.get(key);
+    if (!entry) {
+        return false;
+    }
+    entry.abortController.abort();
+    activeOperations.delete(key);
+    return true;
+}
+export function cancelAllRagOperations() {
+    for (const [key, entry] of activeOperations.entries()) {
+        entry.abortController.abort();
+        activeOperations.delete(key);
+    }
+}

package/dist/server/bare/rag-hyperdb/rag-workspace-manager.d.ts

@@ -0,0 +1,15 @@
+import { RAG, HyperDBAdapter, type EmbeddingFunction } from "@qvac/rag";
+export declare const DEFAULT_WORKSPACE = "default";
+export declare function hasRagWorkspaceStorage(workspace?: string): boolean;
+export declare function getRagDbAdapter(workspace?: string): Promise<HyperDBAdapter>;
+export declare function getRagInstance(modelId: string, embeddingFunction: EmbeddingFunction, workspace?: string): Promise<RAG>;
+export declare function closeRagInstance(workspace?: string): Promise<void>;
+export declare function closeAllRagInstances(): Promise<void>;
+export interface RagWorkspaceInfo {
+    name: string;
+    open: boolean;
+}
+export declare function listWorkspaces(): RagWorkspaceInfo[];
+export declare function isWorkspaceLoaded(workspace: string): boolean;
+export declare function deleteWorkspace(workspace: string): Promise<boolean>;
+//# sourceMappingURL=rag-workspace-manager.d.ts.map

package/dist/server/bare/rag-hyperdb/rag-workspace-manager.js

@@ -0,0 +1,135 @@
+import { RAG, HyperDBAdapter } from "@qvac/rag";
+import Corestore from "corestore";
+import fs, { promises as fsPromises } from "bare-fs";
+import path from "bare-path";
+import { getConfiguredCacheDir } from "../registry/config-registry.js";
+import { RAGWorkspaceModelMismatchError, RAGWorkspaceNotOpenError, } from "../../../utils/errors-server.js";
+import { createStreamLogger, getServerLogger, ADDON_NAMESPACES, } from "../../../logging/index.js";
+import { cancelAllRagOperations } from "./rag-operation-manager.js";
+const logger = getServerLogger();
+const ragWorkspaces = new Map();
+export const DEFAULT_WORKSPACE = "default";
+function getWorkspaceKey(workspace) {
+    return workspace ?? DEFAULT_WORKSPACE;
+}
+function getRagBaseDir() {
+    const cacheDir = getConfiguredCacheDir();
+    return path.join(path.dirname(cacheDir), "rag-hyperdb");
+}
+function getStorePath(workspace) {
+    return path.join(getRagBaseDir(), workspace);
+}
+export function hasRagWorkspaceStorage(workspace) {
+    const key = getWorkspaceKey(workspace);
+    if (ragWorkspaces.has(key))
+        return true;
+    return fs.existsSync(getStorePath(key));
+}
+async function getOrCreateWorkspaceEntry(workspace) {
+    const key = getWorkspaceKey(workspace);
+    const existing = ragWorkspaces.get(key);
+    if (existing) {
+        return existing;
+    }
+    const storePath = getStorePath(key);
+    const corestore = new Corestore(storePath);
+    const dbAdapter = new HyperDBAdapter({
+        store: corestore,
+        dbName: key,
+    });
+    await dbAdapter.ready();
+    const entry = {
+        corestore,
+        dbAdapter,
+    };
+    ragWorkspaces.set(key, entry);
+    return entry;
+}
+export async function getRagDbAdapter(workspace) {
+    const entry = await getOrCreateWorkspaceEntry(workspace);
+    return entry.dbAdapter;
+}
+export async function getRagInstance(modelId, embeddingFunction, workspace) {
+    const key = getWorkspaceKey(workspace);
+    const entry = await getOrCreateWorkspaceEntry(workspace);
+    if (entry.rag) {
+        if (entry.modelId && entry.modelId !== modelId) {
+            throw new RAGWorkspaceModelMismatchError(key, entry.modelId, modelId);
+        }
+        return entry.rag;
+    }
+    const workspaceLogger = createStreamLogger(key, ADDON_NAMESPACES.RAG_HYPERDB);
+    const rag = new RAG({
+        dbAdapter: entry.dbAdapter,
+        embeddingFunction,
+        logger: workspaceLogger,
+    });
+    await rag.ready();
+    entry.rag = rag;
+    entry.modelId = modelId;
+    return rag;
+}
+export async function closeRagInstance(workspace) {
+    const key = getWorkspaceKey(workspace);
+    const entry = ragWorkspaces.get(key);
+    if (!entry) {
+        throw new RAGWorkspaceNotOpenError(key);
+    }
+    if (entry.rag) {
+        await entry.rag.close();
+    }
+    await entry.dbAdapter.close();
+    await entry.corestore.close();
+    ragWorkspaces.delete(key);
+}
+let isCleaningUp = false;
+export async function closeAllRagInstances() {
+    if (isCleaningUp)
+        return;
+    isCleaningUp = true;
+    try {
+        cancelAllRagOperations();
+        const closures = Array.from(ragWorkspaces.entries()).map(async ([key, entry]) => {
+            if (entry.rag) {
+                await entry.rag.close();
+            }
+            await entry.dbAdapter.close();
+            await entry.corestore.close();
+            ragWorkspaces.delete(key);
+        });
+        await Promise.all(closures);
+    }
+    catch (error) {
+        logger.error("❌ Error during RAG cleanup:", error);
+    }
+    finally {
+        isCleaningUp = false;
+    }
+}
+export function listWorkspaces() {
+    const baseDir = getRagBaseDir();
+    if (!fs.existsSync(baseDir)) {
+        return [];
+    }
+    const entries = fs.readdirSync(baseDir, {
+        withFileTypes: true,
+    });
+    const directories = entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith("."));
+    return directories.map((entry) => ({
+        name: entry.name,
+        open: ragWorkspaces.has(entry.name),
+    }));
+}
+export function isWorkspaceLoaded(workspace) {
+    const key = getWorkspaceKey(workspace);
+    return ragWorkspaces.has(key);
+}
+export async function deleteWorkspace(workspace) {
+    const key = getWorkspaceKey(workspace);
+    const storePath = getStorePath(key);
+    if (!fs.existsSync(storePath)) {
+        return false;
+    }
+    await fsPromises.rm(storePath, { recursive: true, force: true });
+    return true;
+}

package/dist/server/bare/registry/config-registry.d.ts

@@ -1,5 +1,14 @@
-import type { SDKConfig } from "../../../schemas/index";
-export declare const setSDKConfig: (config: SDKConfig) => void;
-export declare const getSDKConfig: () => SDKConfig;
-export declare const getConfiguredCacheDir: () => string;
+import type { QvacConfig } from "../../../schemas/index";
+/**
+ * Sets the SDK configuration. This can only be called ONCE during initialization.
+ * After the first call, the config becomes immutable and any subsequent calls will throw.
+ *
+ * @param config - The configuration to set
+ * @throws {ConfigAlreadySetError} If config has already been set
+ * @throws {CacheDirNotAbsoluteError} If cacheDirectory is not an absolute path
+ * @throws {CacheDirNotWritableError} If cacheDirectory is not writable
+ */
+export declare function setSDKConfig(config: QvacConfig): void;
+export declare function getSDKConfig(): QvacConfig;
+export declare function getConfiguredCacheDir(): string;
 //# sourceMappingURL=config-registry.d.ts.map

package/dist/server/bare/registry/config-registry.js

@@ -1,12 +1,32 @@
 import fs from "bare-fs";
 import path from "bare-path";
 import { getEnv } from "../../worker.js";
-import { CacheDirNotAbsoluteError, CacheDirNotWritableError, } from "../../../utils/errors-server.js";
+import { CacheDirNotAbsoluteError, CacheDirNotWritableError, ConfigAlreadySetError, } from "../../../utils/errors-server.js";
+import { getServerLogger, setGlobalConsoleOutput, setGlobalLogLevel, } from "../../../logging/index.js";
+const logger = getServerLogger();
 const configRegistry = {
     cacheDirectory: undefined,
     swarmRelays: undefined,
+    loggerLevel: undefined,
+    loggerConsoleOutput: undefined,
+    httpDownloadConcurrency: undefined,
+    deviceDefaults: undefined,
 };
-export const setSDKConfig = (config) => {
+let configIsSet = false;
+/**
+ * Sets the SDK configuration. This can only be called ONCE during initialization.
+ * After the first call, the config becomes immutable and any subsequent calls will throw.
+ *
+ * @param config - The configuration to set
+ * @throws {ConfigAlreadySetError} If config has already been set
+ * @throws {CacheDirNotAbsoluteError} If cacheDirectory is not an absolute path
+ * @throws {CacheDirNotWritableError} If cacheDirectory is not writable
+ */
+export function setSDKConfig(config) {
+    // Enforce immutability - config can only be set once
+    if (configIsSet) {
+        throw new ConfigAlreadySetError();
+    }
     if (config.cacheDirectory !== undefined && config.cacheDirectory !== null) {
         if (!path.isAbsolute(config.cacheDirectory)) {
             throw new CacheDirNotAbsoluteError();
@@ -21,19 +41,42 @@ export const setSDKConfig = (config) => {
             throw new CacheDirNotWritableError(config.cacheDirectory, error instanceof Error ? error.message : String(error), error);
         }
         configRegistry.cacheDirectory = config.cacheDirectory;
-        console.log(`✅ Cache directory set to: ${config.cacheDirectory}`);
+        logger.info(`✅ Cache directory set to: ${config.cacheDirectory}`);
     }
     if (config.swarmRelays !== undefined && config.swarmRelays !== null) {
         configRegistry.swarmRelays = config.swarmRelays;
+        logger.info(`✅ Swarm relays configured: ${config.swarmRelays.length} relay(s)`);
     }
-};
-export const getSDKConfig = () => {
+    if (config.loggerLevel !== undefined && config.loggerLevel !== null) {
+        configRegistry.loggerLevel = config.loggerLevel;
+        setGlobalLogLevel(config.loggerLevel);
+        logger.info(`Log level set to: ${config.loggerLevel}`);
+    }
+    if (config.loggerConsoleOutput !== undefined &&
+        config.loggerConsoleOutput !== null) {
+        configRegistry.loggerConsoleOutput = config.loggerConsoleOutput;
+        setGlobalConsoleOutput(config.loggerConsoleOutput);
+        logger.info(`Console output ${config.loggerConsoleOutput ? "enabled" : "disabled"}`);
+    }
+    if (config.httpDownloadConcurrency !== undefined &&
+        config.httpDownloadConcurrency !== null) {
+        configRegistry.httpDownloadConcurrency = config.httpDownloadConcurrency;
+        logger.info(`HTTP download concurrency set to: ${config.httpDownloadConcurrency}`);
+    }
+    if (config.deviceDefaults !== undefined && config.deviceDefaults !== null) {
+        configRegistry.deviceDefaults = config.deviceDefaults;
+        logger.info(`✅ Device defaults configured: ${config.deviceDefaults.length} pattern(s)`);
+    }
+    // Mark config as set - now it's immutable
+    configIsSet = true;
+}
+export function getSDKConfig() {
     return { ...configRegistry };
-};
-const getDefaultCacheDir = () => {
+}
+function getDefaultCacheDir() {
     const homeDir = getEnv().HOME_DIR;
     return path.join(homeDir, ".qvac", "models");
-};
-export const getConfiguredCacheDir = () => {
+}
+export function getConfiguredCacheDir() {
     return configRegistry.cacheDirectory || getDefaultCacheDir();
-};
+}

package/dist/server/bare/registry/logging-stream-registry.d.ts

@@ -1,13 +1,30 @@
+/**
+ * Logging Stream Registry
+ *
+ * Manages RPC subscriptions for streaming logs from server to connected clients.
+ *
+ * Purpose:
+ * - Registers client subscriptions to model/SDK log streams
+ * - Routes log messages to subscribed clients via RPC
+ * - Buffers logs during model loading (before client subscribes)
+ * - Manages stream lifecycle (subscribe/unsubscribe)
+ *
+ */
 import type { LogLevel } from "@qvac/logging";
-export declare function registerLoggingStream(modelId: string, streamHandler: (level: LogLevel, namespace: string, message: string) => void): void;
-export declare function unregisterLoggingStream(modelId: string, streamHandler: (level: LogLevel, namespace: string, message: string) => void): void;
-export declare function unregisterAllLoggingStreams(modelId: string): void;
-export declare function sendLogToStreams(modelId: string, level: LogLevel, namespace: string, message: string): void;
-export declare function hasLoggingStreams(modelId: string): boolean | undefined;
+export declare function startLogBuffering(id: string): void;
+export declare function stopLogBufferingWithTimeout(id: string): void;
+export declare function registerLoggingStream(id: string, streamHandler: (level: LogLevel, namespace: string, message: string) => void): void;
+export declare function unregisterLoggingStream(id: string, streamHandler: (level: LogLevel, namespace: string, message: string) => void): void;
+export declare function unregisterAllLoggingStreams(id: string): void;
+export declare function sendLogToStreams(id: string, level: LogLevel, namespace: string, message: string): void;
+export declare function hasLoggingStreams(id: string): boolean | undefined;
 export declare function getLoggingStreamStats(): {
-    totalModels: number;
-    modelIds: string[];
+    totalIds: number;
+    ids: string[];
     totalStreams: number;
+    bufferedIds: number;
+    idsWithBuffering: number;
+    activeTimeouts: number;
 };
 export declare function clearAllLoggingStreams(): void;
 //# sourceMappingURL=logging-stream-registry.d.ts.map

package/dist/server/bare/registry/logging-stream-registry.js

@@ -1,53 +1,132 @@
+/**
+ * Logging Stream Registry
+ *
+ * Manages RPC subscriptions for streaming logs from server to connected clients.
+ *
+ * Purpose:
+ * - Registers client subscriptions to model/SDK log streams
+ * - Routes log messages to subscribed clients via RPC
+ * - Buffers logs during model loading (before client subscribes)
+ * - Manages stream lifecycle (subscribe/unsubscribe)
+ *
+ */
 const loggingStreams = new Map();
-export function registerLoggingStream(modelId, streamHandler) {
-    if (!loggingStreams.has(modelId)) {
-        loggingStreams.set(modelId, new Set());
+// Buffering for logs emitted during model loading (before client subscribes)
+const MAX_BUFFERED_LOGS_PER_MODEL = 100;
+const BUFFER_EXPIRY_MS = 30_000;
+const BUFFERING_TIMEOUT_MS = 5_000;
+const logBuffer = new Map();
+const modelsWithBuffering = new Set();
+const bufferingTimeouts = new Map();
+function clearBufferingTimeout(id) {
+    const timeout = bufferingTimeouts.get(id);
+    if (timeout) {
+        clearTimeout(timeout);
+        bufferingTimeouts.delete(id);
     }
-    loggingStreams.get(modelId).add(streamHandler);
 }
-export function unregisterLoggingStream(modelId, streamHandler) {
-    const streams = loggingStreams.get(modelId);
+export function startLogBuffering(id) {
+    modelsWithBuffering.add(id);
+}
+export function stopLogBufferingWithTimeout(id) {
+    clearBufferingTimeout(id);
+    const timeout = setTimeout(() => {
+        if (modelsWithBuffering.has(id)) {
+            modelsWithBuffering.delete(id);
+            logBuffer.delete(id);
+        }
+        bufferingTimeouts.delete(id);
+    }, BUFFERING_TIMEOUT_MS);
+    bufferingTimeouts.set(id, timeout);
+}
+export function registerLoggingStream(id, streamHandler) {
+    if (!loggingStreams.has(id)) {
+        loggingStreams.set(id, new Set());
+    }
+    loggingStreams.get(id).add(streamHandler);
+    const buffered = logBuffer.get(id);
+    if (buffered && buffered.length > 0) {
+        for (const log of buffered) {
+            try {
+                streamHandler(log.level, log.namespace, log.message);
+            }
+            catch (error) {
+                console.error(`Error flushing buffered log for ID ${id}:`, error); // fallback (avoid recursion)
+            }
+        }
+        logBuffer.delete(id);
+    }
+    modelsWithBuffering.delete(id);
+    clearBufferingTimeout(id);
+}
+export function unregisterLoggingStream(id, streamHandler) {
+    const streams = loggingStreams.get(id);
     if (streams) {
         streams.delete(streamHandler);
         if (streams.size === 0) {
-            loggingStreams.delete(modelId);
+            loggingStreams.delete(id);
         }
     }
 }
-export function unregisterAllLoggingStreams(modelId) {
-    // Simply remove all logging handlers for this model
+export function unregisterAllLoggingStreams(id) {
+    // Simply remove all logging handlers
     // Active streams will naturally terminate when no more logs flow
-    loggingStreams.delete(modelId);
-    console.debug(`Unregistered all logging streams for model ${modelId}`);
+    loggingStreams.delete(id);
+    logBuffer.delete(id);
+    modelsWithBuffering.delete(id);
+    clearBufferingTimeout(id);
 }
-export function sendLogToStreams(modelId, level, namespace, message) {
-    const streams = loggingStreams.get(modelId);
-    if (streams) {
+export function sendLogToStreams(id, level, namespace, message) {
+    const streams = loggingStreams.get(id);
+    const isBuffering = modelsWithBuffering.has(id);
+    if (streams && streams.size > 0) {
         for (const streamHandler of streams) {
             try {
                 streamHandler(level, namespace, message);
             }
             catch (error) {
-                console.error(`Error sending log to stream for model ${modelId}:`, error);
+                console.error(`Error sending log to stream for ID ${id}:`, error); // fallback (avoid recursion)
             }
         }
     }
+    else if (isBuffering) {
+        if (!logBuffer.has(id)) {
+            logBuffer.set(id, []);
+        }
+        const buffer = logBuffer.get(id);
+        const now = Date.now();
+        const validLogs = buffer.filter((log) => now - log.timestamp < BUFFER_EXPIRY_MS);
+        if (validLogs.length >= MAX_BUFFERED_LOGS_PER_MODEL) {
+            validLogs.shift();
+        }
+        validLogs.push({ level, namespace, message, timestamp: now });
+        logBuffer.set(id, validLogs);
+    }
 }
-export function hasLoggingStreams(modelId) {
-    const streams = loggingStreams.get(modelId);
+export function hasLoggingStreams(id) {
+    const streams = loggingStreams.get(id);
     return streams && streams.size > 0;
 }
 export function getLoggingStreamStats() {
     return {
-        totalModels: loggingStreams.size,
-        modelIds: Array.from(loggingStreams.keys()),
+        totalIds: loggingStreams.size,
+        ids: Array.from(loggingStreams.keys()),
         totalStreams: Array.from(loggingStreams.values()).reduce((sum, streams) => sum + streams.size, 0),
+        bufferedIds: logBuffer.size,
+        idsWithBuffering: modelsWithBuffering.size,
+        activeTimeouts: bufferingTimeouts.size,
     };
 }
 export function clearAllLoggingStreams() {
     const count = loggingStreams.size;
+    for (const timeout of bufferingTimeouts.values()) {
+        clearTimeout(timeout);
+    }
     loggingStreams.clear();
+    logBuffer.clear();
+    modelsWithBuffering.clear();
+    bufferingTimeouts.clear();
     if (count > 0) {
-        console.log(`🧹 Cleared logging streams for ${count} model(s)`);
+        console.log(`🧹 Cleared logging streams for ${count} ID(s)`); // fallback (avoid recursion)
     }
 }

package/dist/server/bare/registry/model-config-registry.d.ts

@@ -0,0 +1,4 @@
+import type { CanonicalModelType } from "../../../schemas/index";
+export { CANONICAL_TO_ALIAS, MODEL_CONFIG_SCHEMAS, BUILTIN_DEVICE_PATTERNS, matchesPattern, findAllMatchingPatterns, getDefaultsFromPattern, resolveModelConfigWithContext, } from "./model-config-utils";
+export declare function resolveModelConfig<T>(modelType: CanonicalModelType, userInput: Record<string, unknown>): T;
+//# sourceMappingURL=model-config-registry.d.ts.map

package/dist/server/bare/registry/model-config-registry.js

@@ -0,0 +1,15 @@
+import { getSDKConfig } from "./config-registry.js";
+import { getRuntimeContext } from "./runtime-context-registry.js";
+import { getServerLogger } from "../../../logging/index.js";
+export { CANONICAL_TO_ALIAS, MODEL_CONFIG_SCHEMAS, BUILTIN_DEVICE_PATTERNS, matchesPattern, findAllMatchingPatterns, getDefaultsFromPattern, resolveModelConfigWithContext, } from "./model-config-utils.js";
+import { BUILTIN_DEVICE_PATTERNS, resolveModelConfigWithContext, } from "./model-config-utils.js";
+const logger = getServerLogger();
+export function resolveModelConfig(modelType, userInput) {
+    const ctx = getRuntimeContext();
+    const userPatterns = getSDKConfig().deviceDefaults ?? [];
+    return resolveModelConfigWithContext(modelType, userInput, ctx, userPatterns, BUILTIN_DEVICE_PATTERNS, (log) => {
+        if (log.appliedPatterns.length > 0) {
+            logger.debug(`[device-defaults] ${modelType}: applied [${log.appliedPatterns.join(" → ")}]`);
+        }
+    });
+}

package/dist/server/bare/registry/model-config-utils.d.ts

@@ -0,0 +1,15 @@
+import type { ZodSchema } from "zod";
+import { type CanonicalModelType, type DevicePattern, type DeviceMatch, type RuntimeContext } from "../../../schemas/index";
+export declare const CANONICAL_TO_ALIAS: Record<CanonicalModelType, string>;
+export declare const MODEL_CONFIG_SCHEMAS: Partial<Record<CanonicalModelType, ZodSchema>>;
+export declare const BUILTIN_DEVICE_PATTERNS: DevicePattern[];
+export declare function matchesPattern(ctx: RuntimeContext, match: DeviceMatch): boolean;
+export declare function findAllMatchingPatterns(ctx: RuntimeContext, patterns: DevicePattern[]): DevicePattern[];
+export declare function getDefaultsFromPattern(modelType: CanonicalModelType, pattern: DevicePattern): Record<string, unknown> | undefined;
+export type ConfigResolutionLog = {
+    appliedPatterns: string[];
+    mergedDefaults: Record<string, unknown>;
+    finalConfig: Record<string, unknown>;
+};
+export declare function resolveModelConfigWithContext<T>(modelType: CanonicalModelType, userInput: Record<string, unknown>, ctx: RuntimeContext, userPatterns: DevicePattern[], builtinPatterns?: DevicePattern[], onLog?: (log: ConfigResolutionLog) => void): T;
+//# sourceMappingURL=model-config-utils.d.ts.map

package/dist/server/bare/registry/model-config-utils.js

@@ -0,0 +1,121 @@
+import { ModelType, } from "../../../schemas/index.js";
+import { llmConfigSchema, embedConfigSchema } from "../../../schemas/llamacpp-config.js";
+import { whisperConfigSchema } from "../../../schemas/whispercpp-config.js";
+import { ocrConfigSchema } from "../../../schemas/ocr.js";
+export const CANONICAL_TO_ALIAS = {
+    [ModelType.llamacppCompletion]: "llm",
+    [ModelType.llamacppEmbedding]: "embeddings",
+    [ModelType.whispercppTranscription]: "whisper",
+    [ModelType.nmtcppTranslation]: "nmt",
+    [ModelType.onnxTts]: "tts",
+    [ModelType.onnxOcr]: "ocr",
+};
+export const MODEL_CONFIG_SCHEMAS = {
+    [ModelType.llamacppCompletion]: llmConfigSchema,
+    [ModelType.llamacppEmbedding]: embedConfigSchema,
+    [ModelType.whispercppTranscription]: whisperConfigSchema,
+    [ModelType.onnxOcr]: ocrConfigSchema,
+};
+// Ordered general → specific (later patterns override earlier)
+export const BUILTIN_DEVICE_PATTERNS = [
+    {
+        name: "Android devices (SDK default)",
+        match: {
+            platform: "android",
+        },
+        defaults: {
+            [ModelType.llamacppEmbedding]: { flashAttention: "off" },
+        },
+    },
+    {
+        name: "Pixel devices (SDK default)",
+        match: {
+            platform: "android",
+            deviceBrand: "google",
+            deviceModelPrefix: "Pixel",
+        },
+        defaults: {
+            [ModelType.llamacppCompletion]: { device: "cpu" },
+            [ModelType.llamacppEmbedding]: { device: "cpu" },
+        },
+    },
+    {
+        name: "iPhone 17",
+        match: {
+            platform: "ios",
+            deviceModelPrefix: "iPhone 17",
+        },
+        defaults: {
+            [ModelType.llamacppCompletion]: { device: "cpu" },
+            [ModelType.llamacppEmbedding]: { device: "cpu" },
+        },
+    },
+];
+export function matchesPattern(ctx, match) {
+    if (match.platform !== undefined && ctx.platform !== match.platform) {
+        return false;
+    }
+    if (match.deviceBrand !== undefined &&
+        ctx.deviceBrand?.toLowerCase() !== match.deviceBrand.toLowerCase()) {
+        return false;
+    }
+    if (match.deviceModelPrefix !== undefined &&
+        !(ctx.deviceModel?.startsWith(match.deviceModelPrefix) ?? false)) {
+        return false;
+    }
+    if (match.deviceModelContains !== undefined &&
+        !(ctx.deviceModel?.includes(match.deviceModelContains) ?? false)) {
+        return false;
+    }
+    return true;
+}
+export function findAllMatchingPatterns(ctx, patterns) {
+    return patterns.filter((pattern) => matchesPattern(ctx, pattern.match));
+}
+export function getDefaultsFromPattern(modelType, pattern) {
+    let defaults = pattern.defaults[modelType];
+    if (!defaults) {
+        const aliasKey = CANONICAL_TO_ALIAS[modelType];
+        if (aliasKey && aliasKey in pattern.defaults) {
+            defaults = pattern.defaults[aliasKey];
+        }
+    }
+    return defaults;
+}
+export function resolveModelConfigWithContext(modelType, userInput, ctx, userPatterns, builtinPatterns = BUILTIN_DEVICE_PATTERNS, onLog) {
+    // Find ALL matching patterns (general → specific order preserved)
+    const matchingBuiltin = findAllMatchingPatterns(ctx, builtinPatterns);
+    const matchingUser = findAllMatchingPatterns(ctx, userPatterns);
+    // Merge in order: builtin patterns → user patterns → user input
+    // Later values override earlier (more specific wins)
+    const appliedPatterns = [];
+    let mergedDefaults = {};
+    for (const pattern of matchingBuiltin) {
+        const defaults = getDefaultsFromPattern(modelType, pattern);
+        if (defaults) {
+            appliedPatterns.push(pattern.name);
+            mergedDefaults = { ...mergedDefaults, ...defaults };
+        }
+    }
+    for (const pattern of matchingUser) {
+        const defaults = getDefaultsFromPattern(modelType, pattern);
+        if (defaults) {
+            appliedPatterns.push(pattern.name);
+            mergedDefaults = { ...mergedDefaults, ...defaults };
+        }
+    }
+    const merged = {
+        ...mergedDefaults,
+        ...userInput,
+    };
+    const schema = MODEL_CONFIG_SCHEMAS[modelType];
+    const finalConfig = schema ? schema.parse(merged) : merged;
+    if (onLog) {
+        onLog({
+            appliedPatterns,
+            mergedDefaults,
+            finalConfig: finalConfig,
+        });
+    }
+    return finalConfig;
+}