llm-checker 3.5.15 → 3.7.0

package/src/data/registry-recommender.js

@@ -0,0 +1,514 @@
+const ModelDatabase = require('./model-database');
+const DeterministicModelSelector = require('../models/deterministic-selector');
+
+function toArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+
+function parseParamsB(...values) {
+    for (const value of values) {
+        if (typeof value === 'number' && Number.isFinite(value) && value > 0) {
+            return value;
+        }
+        const text = String(value || '').replace(/,/g, '');
+        // Mixture-of-Experts "NxMB" (e.g. 8x7B) -> experts * per-expert size,
+        // so MoE models are not sized as if they were a single expert.
+        const moe = text.match(/(\d+)\s*x\s*(\d+(?:\.\d+)?)\s*b\b/i);
+        if (moe) {
+            const experts = Number(moe[1]);
+            const perExpert = Number(moe[2]);
+            if (experts > 0 && Number.isFinite(perExpert) && perExpert > 0) {
+                return experts * perExpert;
+            }
+        }
+        const match = text.match(/(\d+(?:\.\d+)?)\s*([bmt])\b/i);
+        if (!match) continue;
+        const amount = Number(match[1]);
+        if (!Number.isFinite(amount) || amount <= 0) continue;
+        const unit = match[2].toLowerCase();
+        if (unit === 't') return amount * 1000;
+        if (unit === 'm') return amount / 1000;
+        return amount;
+    }
+    return null;
+}
+
+// Active-param naming, e.g. "...-A17B" in "Qwen3-397B-A17B".
+function parseActiveParamsFromName(...values) {
+    for (const value of values) {
+        const m = String(value || '').match(/(?:^|[-_\s/])a(\d+(?:\.\d+)?)\s*b\b/i);
+        if (m) {
+            const v = Number(m[1]);
+            if (Number.isFinite(v) && v > 0) return v;
+        }
+    }
+    return null;
+}
+
+// Detect Mixture-of-Experts naming so we size by total params (memory) and can
+// apply MoE speed assumptions. Covers "8x7B", "397B-A17B", "moe", and Mixtral.
+function isMoEName(...values) {
+    return values.some((value) =>
+        /(\d+\s*x\s*\d+(?:\.\d+)?\s*b\b)|(\d+(?:\.\d+)?\s*b[-_\s]*a\d)|\bmoe\b|mixtral/i.test(String(value || ''))
+    );
+}
+
+function inferFamily(identifier = '') {
+    const text = String(identifier || '').toLowerCase();
+    const families = [
+        ['deepseek-r1', /deepseek[-_ ]?r1/],
+        ['deepseek-coder', /deepseek[-_ ]?coder/],
+        ['deepseek', /deepseek/],
+        ['qwen3', /qwen3/],
+        ['qwen2.5', /qwen2\.5/],
+        ['qwen2', /qwen2/],
+        ['qwen', /qwen/],
+        ['llama3.2', /llama3\.2|llama-?3\.2/],
+        ['llama3.1', /llama3\.1|llama-?3\.1/],
+        ['llama3', /llama3|llama-?3/],
+        ['llama2', /llama2|llama-?2/],
+        ['mistral', /mistral/],
+        ['mixtral', /mixtral/],
+        ['gemma3', /gemma3/],
+        ['gemma2', /gemma2/],
+        ['gemma', /gemma/],
+        ['phi4', /phi-?4/],
+        ['phi3', /phi-?3/],
+        ['phi', /phi/],
+        ['codellama', /codellama|code-?llama/],
+        ['starcoder', /starcoder/],
+        ['llava', /llava/],
+        ['nomic-embed', /nomic-embed/],
+        ['bge', /\bbge\b/]
+    ];
+
+    for (const [family, pattern] of families) {
+        if (pattern.test(text)) return family;
+    }
+    return 'other';
+}
+
+function normalizeQuantization(row = {}) {
+    const raw = row.quantization || row.precision || '';
+    if (raw) return raw;
+    if (row.format === 'safetensors' || row.format === 'pytorch' || row.format === 'pytorch_bin') {
+        return 'FP16';
+    }
+    return 'Q4_K_M';
+}
+
+function isShardedWeightFile(filename = '') {
+    return /-\d{5,}-of-\d{5,}\.(safetensors|bin)$/i.test(String(filename || ''));
+}
+
+function choosePreferredRuntime(runtimeSupport = [], format = '', sourceId = '') {
+    const runtimes = toArray(runtimeSupport).map((runtime) => String(runtime).toLowerCase());
+    const normalizedFormat = String(format || '').toLowerCase();
+    const source = String(sourceId || '').toLowerCase();
+
+    if (source === 'ollama' || runtimes.includes('ollama')) return 'ollama';
+    if (normalizedFormat === 'mlx' || runtimes.includes('mlx')) return 'mlx';
+    if (normalizedFormat === 'gguf' || runtimes.includes('llama.cpp')) return 'llama.cpp';
+    if (runtimes.includes('vllm')) return 'vllm';
+    if (runtimes.includes('transformers')) return 'transformers';
+    return runtimes[0] || 'transformers';
+}
+
+function artifactToSelectorModel(row) {
+    const shardedFile = row.source_id === 'huggingface' && isShardedWeightFile(row.filename || row.artifact_name);
+    const identifier = shardedFile
+        ? (row.canonical_model_id || row.repo_id)
+        : (row.artifact_name || row.filename || row.canonical_model_id || row.repo_id);
+    const displayName = row.canonical_model_id || row.repo_display_name || identifier;
+    const quant = normalizeQuantization(row);
+
+    // MEMORY sizing must use the TOTAL parameter count (for MoE, ALL experts are
+    // resident), never the active count. We re-derive the total from the model
+    // name (MoE-aware) and take the max with the stored column, so a stale or
+    // under-reported DB value (an MoE saved as one expert, or an active-param
+    // count) can never make a huge model look tiny and "fit" small hardware.
+    const nameStrings = [row.artifact_name, row.filename, row.canonical_model_id, row.repo_id];
+    const storedTotalB = parseParamsB(row.parameter_count_b);
+    const nameTotalB = parseParamsB(...nameStrings);
+    const totalParamsB = Math.max(storedTotalB || 0, nameTotalB || 0) || null;
+    const activeParamsB = parseParamsB(row.active_parameter_count_b) || parseActiveParamsFromName(...nameStrings);
+    const isMoE = isMoEName(...nameStrings)
+        || (Number.isFinite(activeParamsB) && Number.isFinite(totalParamsB) && activeParamsB < totalParamsB);
+
+    // The sizing param is the total; fall back to the active count only if no
+    // total can be determined at all.
+    const paramsB = Number.isFinite(totalParamsB) && totalParamsB > 0
+        ? totalParamsB
+        : parseParamsB(row.active_parameter_count_b);
+
+    if (!identifier || !Number.isFinite(paramsB) || paramsB <= 0) {
+        return null;
+    }
+
+    // Flag MoE and carry the TOTAL parameter count so memory is sized by the
+    // full weight set (all experts are resident under Ollama / Metal / vLLM).
+    // We deliberately do NOT set activeParamsB here: that would switch the memory
+    // model to "sparse inference" (sizing by active params), which would let a
+    // 397B-A17B model falsely "fit" ~11GB. Active params drive speed only, and
+    // sparse offload is not how the local runtimes this tool targets behave, so
+    // we stay conservative on memory.
+    const moeFields = {};
+    if (isMoE && Number.isFinite(totalParamsB) && totalParamsB > 0) {
+        moeFields.isMoE = true;
+        moeFields.totalParamsB = totalParamsB;
+        moeFields.total_params_b = totalParamsB;
+    }
+
+    const runtimeSupport = toArray(row.runtime_support);
+    const preferredRuntime = choosePreferredRuntime(runtimeSupport, row.format, row.source_id);
+    const tasks = toArray(row.tasks);
+    const modalities = toArray(row.modalities);
+    const tags = [
+        row.source_id,
+        row.format,
+        quant,
+        ...runtimeSupport,
+        ...tasks
+    ]
+        .filter(Boolean)
+        .map((tag) => String(tag).toLowerCase());
+
+    const sizeGB = Number(row.size_gb);
+    const sizeByQuant = Number.isFinite(sizeGB) && sizeGB > 0
+        ? { [quant]: sizeGB }
+        : {};
+
+    return {
+        name: displayName,
+        model_identifier: identifier,
+        family: inferFamily(`${displayName} ${identifier}`),
+        paramsB,
+        ...moeFields,
+        quant,
+        availableQuantizations: [quant],
+        sizeGB: Number.isFinite(sizeGB) && sizeGB > 0 ? sizeGB : undefined,
+        sizeByQuant,
+        ctxMax: Number(row.context_length) > 0 ? Number(row.context_length) : 4096,
+        tags,
+        modalities: modalities.length > 0 ? modalities : ['text'],
+        pulls: Number(row.downloads) || 0,
+        source: row.source_id,
+        registry: row.source_name || row.source_id,
+        version: shardedFile ? (row.repo_id || identifier) : (row.artifact_name || row.filename || identifier),
+        license: row.license || 'unknown',
+        digest: row.sha256 || row.etag || 'unknown',
+        installCommand: shardedFile && row.repo_id ? `hf download ${row.repo_id}` : (row.install_command || ''),
+        downloadUrl: shardedFile ? (row.repo_url || '') : (row.download_url || ''),
+        preferredRuntime,
+        artifact: row,
+        provenance: {
+            source: row.source_id,
+            registry: row.source_name || row.source_id,
+            version: shardedFile ? (row.repo_id || identifier) : (row.artifact_name || row.filename || identifier),
+            license: row.license || 'unknown',
+            digest: row.sha256 || row.etag || 'unknown',
+            download_url: shardedFile ? (row.repo_url || '') : (row.download_url || ''),
+            install_command: shardedFile && row.repo_id ? `hf download ${row.repo_id}` : (row.install_command || ''),
+            repo_url: row.repo_url || ''
+        }
+    };
+}
+
+function dedupeRecommendationPool(models) {
+    const deduped = new Map();
+    for (const model of models) {
+        const artifact = model.artifact || {};
+        const key = [
+            model.source,
+            artifact.repo_id || model.name,
+            model.model_identifier,
+            model.preferredRuntime
+        ].join('|');
+
+        const existing = deduped.get(key);
+        if (!existing) {
+            deduped.set(key, model);
+            continue;
+        }
+
+        const existingSize = Number(existing.sizeGB || existing.artifact?.size_gb || Number.MAX_SAFE_INTEGER);
+        const size = Number(model.sizeGB || model.artifact?.size_gb || Number.MAX_SAFE_INTEGER);
+        if (size < existingSize) {
+            deduped.set(key, model);
+        }
+    }
+    return [...deduped.values()];
+}
+
+function candidateToRecommendation(candidate) {
+    const artifact = candidate.meta.artifact || {};
+    return {
+        model: candidate.meta.name,
+        artifact: candidate.meta.model_identifier,
+        source: candidate.meta.source,
+        registry: candidate.meta.registry,
+        score: candidate.score,
+        params_b: candidate.meta.paramsB,
+        quantization: candidate.quant,
+        size_gb: candidate.meta.sizeGB || artifact.size_gb || null,
+        required_gb: candidate.requiredGB,
+        estimated_tps: candidate.estTPS,
+        runtime: candidate.runtime,
+        install_command: candidate.meta.installCommand || artifact.install_command || '',
+        download_url: candidate.meta.downloadUrl || artifact.download_url || '',
+        license: candidate.meta.license,
+        gated: Boolean(artifact.gated),
+        requires_auth: Boolean(artifact.requires_auth),
+        tasks: toArray(artifact.tasks),
+        modalities: toArray(artifact.modalities),
+        rationale: candidate.rationale,
+        components: candidate.components,
+        memory: candidate.memory,
+        speed: candidate.speed
+    };
+}
+
+function normalizeHardwareForSelector(hardware = {}) {
+    if (hardware.memory?.totalGB && hardware.gpu && hardware.acceleration) {
+        return hardware;
+    }
+
+    const summary = hardware.summary || {};
+    const cpuInfo = hardware.cpu || hardware.backends?.cpu?.info || {};
+    const cpuCores = cpuInfo.cores || {};
+    const bestBackend = summary.bestBackend || hardware.primary?.type || 'cpu';
+    const systemRAM = Number(summary.systemRAM || summary.effectiveMemory || 8);
+    const totalVRAM = Number(summary.totalVRAM || 0);
+    const gpuModel = summary.gpuModel || summary.gpuInventory || hardware.primary?.name || '';
+    const isMetal = bestBackend === 'metal';
+    const isCuda = bestBackend === 'cuda';
+    const isRocm = bestBackend === 'rocm';
+
+    return {
+        cpu: {
+            architecture: cpuInfo.architecture || process.arch,
+            cores: Number(cpuCores.logical || cpuCores.physical || cpuInfo.cores || 4),
+            model: cpuInfo.brand || summary.cpuModel || ''
+        },
+        gpu: {
+            type: isMetal ? 'apple_silicon' : (isCuda ? 'nvidia' : (isRocm ? 'amd' : 'cpu_only')),
+            model: gpuModel,
+            vramGB: totalVRAM,
+            totalVRAM,
+            gpuCount: Math.max(1, Number(summary.gpuCount || 1)),
+            unified: Boolean(isMetal || (summary.hasIntegratedGPU && !summary.hasDedicatedGPU)),
+            isMultiGPU: Boolean(summary.isMultiGPU)
+        },
+        memory: {
+            totalGB: systemRAM,
+            total: systemRAM
+        },
+        acceleration: {
+            supports_metal: isMetal,
+            supports_cuda: isCuda,
+            supports_rocm: isRocm
+        },
+        usableMemGB: Number(summary.effectiveMemory) > 0 ? Number(summary.effectiveMemory) : undefined
+    };
+}
+
+class RegistryRecommender {
+    constructor(options = {}) {
+        this.database = options.database || new ModelDatabase(options.databaseOptions || {});
+        this.selector = options.selector || new DeterministicModelSelector();
+    }
+
+    async initialize() {
+        await this.database.initialize();
+    }
+
+    async recommend(options = {}) {
+        const selection = await this.selectCategory(options);
+        return {
+            category: selection.category,
+            runtime: selection.runtime,
+            optimizeFor: selection.result.optimizeFor,
+            total_artifacts: selection.rows.length,
+            total_candidates: selection.modelPool.length,
+            total_evaluated: selection.result.total_evaluated,
+            recommendations: selection.result.candidates.map(candidateToRecommendation),
+            registry: this.database.getRegistryStats(),
+            generated_at: new Date().toISOString()
+        };
+    }
+
+    async selectCategory(options = {}) {
+        const category = options.category || 'general';
+        const runtime = options.runtime || 'auto';
+        const runtimeFilter = ['auto', 'all', '*'].includes(String(runtime).toLowerCase()) ? undefined : runtime;
+        const limit = Number(options.limit) > 0 ? Number(options.limit) : 10;
+        const poolLimit = Number(options.poolLimit) > 0 ? Number(options.poolLimit) : 20000;
+        const targetCtx = Number(options.targetContext) > 0 ? Number(options.targetContext) : undefined;
+
+        const rows = this.database.searchModelArtifacts(options.query || '', {
+            source: options.source,
+            format: options.format,
+            runtime: runtimeFilter,
+            quantization: options.quantization,
+            maxSizeGB: options.maxSizeGB,
+            minParamsB: options.minParamsB,
+            maxParamsB: options.maxParamsB,
+            localOnly: options.localOnly !== false,
+            limit: poolLimit
+        });
+        const modelPool = dedupeRecommendationPool(rows.map(artifactToSelectorModel).filter(Boolean));
+
+        const selectorHardware = normalizeHardwareForSelector(options.hardware || {});
+        const normalizedRuntime = runtimeFilter || 'auto';
+        const result = runtimeFilter
+            ? await this.selector.selectModels(category, {
+                topN: limit,
+                enableProbe: false,
+                silent: true,
+                optimizeFor: options.optimizeFor || 'balanced',
+                runtime: runtimeFilter,
+                targetCtx,
+                hardware: selectorHardware,
+                installedModels: [],
+                modelPool
+            })
+            : this.scoreAutoRuntimePool({
+                category,
+                limit,
+                targetCtx,
+                optimizeFor: options.optimizeFor || 'balanced',
+                hardware: selectorHardware,
+                modelPool
+            });
+
+        return {
+            category,
+            runtime: normalizedRuntime,
+            rows,
+            modelPool,
+            result
+        };
+    }
+
+    async getBestModelsForHardware(hardware, options = {}) {
+        const categories = options.categories || ['coding', 'reasoning', 'multimodal', 'creative', 'talking', 'reading', 'general'];
+        const recommendations = {};
+        const runtime = options.runtime || 'auto';
+        const optimizeFor = options.optimizeFor || options.optimize || 'balanced';
+        const limit = Number(options.limit) > 0 ? Number(options.limit) : 3;
+        const registryStats = this.database.getRegistryStats();
+        const analyzedModels = new Set();
+
+        for (const category of categories) {
+            try {
+                const selection = await this.selectCategory({
+                    ...options,
+                    category,
+                    runtime,
+                    optimizeFor,
+                    limit,
+                    hardware
+                });
+                for (const model of selection.modelPool) {
+                    const artifact = model.artifact || {};
+                    analyzedModels.add([
+                        artifact.artifact_id || artifact.id || artifact.filename || model.model_identifier,
+                        model.source,
+                        model.preferredRuntime
+                    ].filter(Boolean).join('|'));
+                }
+                const normalizedHardware = this.selector.normalizeHardwareProfile(
+                    normalizeHardwareForSelector(hardware || {})
+                );
+                recommendations[category] = {
+                    tier: this.selector.mapHardwareTier(normalizedHardware),
+                    optimizeFor: selection.result.optimizeFor,
+                    runtime: selection.runtime,
+                    source: 'registry',
+                    bestModels: selection.result.candidates.map((candidate) => this.selector.mapCandidateToLegacyFormat(candidate)),
+                    totalEvaluated: selection.result.total_evaluated,
+                    totalArtifacts: selection.rows.length,
+                    totalCandidates: selection.modelPool.length,
+                    category: this.selector.getCategoryInfo(category)
+                };
+            } catch (error) {
+                recommendations[category] = {
+                    tier: 'unknown',
+                    optimizeFor,
+                    runtime,
+                    source: 'registry',
+                    bestModels: [],
+                    totalEvaluated: 0,
+                    totalArtifacts: 0,
+                    totalCandidates: 0,
+                    error: error.message,
+                    category: this.selector.getCategoryInfo(category)
+                };
+            }
+        }
+
+        return {
+            recommendations,
+            registryStats,
+            totalModelsAnalyzed: analyzedModels.size
+        };
+    }
+
+    scoreAutoRuntimePool({ category, limit, targetCtx, optimizeFor, hardware, modelPool }) {
+        const normalizedHardware = this.selector.normalizeHardwareProfile(hardware);
+        const objective = this.selector.normalizeOptimizationObjective(optimizeFor);
+        const ctx = targetCtx || this.selector.targetContexts[category] || this.selector.targetContexts.general;
+        const totalMem = normalizedHardware?.memory?.totalGB ?? normalizedHardware?.memory?.total ?? 8;
+        const usableMem = typeof normalizedHardware.usableMemGB === 'number'
+            ? normalizedHardware.usableMemGB
+            : Math.max(1, Math.min(0.8 * totalMem, totalMem - 2));
+        const isUnified = Boolean(normalizedHardware?.gpu?.unified) || normalizedHardware?.gpu?.type === 'apple_silicon';
+        const vram = normalizedHardware?.gpu?.vramGB ?? normalizedHardware?.gpu?.vram ?? 0;
+        const budget = isUnified ? usableMem : (vram || usableMem);
+        const filtered = this.selector.filterByCategory(modelPool, category);
+        const candidates = [];
+
+        for (const model of filtered) {
+            const runtime = model.preferredRuntime || choosePreferredRuntime(
+                model.artifact?.runtime_support,
+                model.artifact?.format,
+                model.source
+            );
+            const candidate = this.selector.evaluateModel(
+                model,
+                normalizedHardware,
+                category,
+                ctx,
+                budget,
+                objective,
+                runtime
+            );
+            if (candidate) candidates.push(candidate);
+        }
+
+        candidates.sort((a, b) => b.score - a.score);
+
+        return {
+            category,
+            optimizeFor: objective,
+            runtime: 'auto',
+            hardware: normalizedHardware,
+            candidates: candidates.slice(0, limit),
+            total_evaluated: filtered.length,
+            timestamp: new Date().toISOString()
+        };
+    }
+
+    close() {
+        this.database.close();
+    }
+}
+
+module.exports = {
+    RegistryRecommender,
+    artifactToSelectorModel,
+    candidateToRecommendation,
+    normalizeHardwareForSelector,
+    choosePreferredRuntime,
+    dedupeRecommendationPool
+};

package/src/data/seed/README.md

@@ -1,8 +1,16 @@
-This directory contains the packaged Ollama model database snapshot used on
-first run.
+This directory contains the packaged model database snapshot used on first run.
 
 `models.db` is copied to `~/.llm-checker/models.db` only when the user does not
 already have a local database. After that, `llm-checker sync` updates the user's
-local copy.
+local Ollama copy, and `llm-checker registry-sync` can refresh the multi-source
+registry in the user's local copy.
+
+The snapshot includes:
+
+- the Ollama catalog used by classic recommendation/search commands
+- a multi-source registry of exact installable/downloadable artifacts from
+  Hugging Face, Ollama, and GPT4All
+- Hugging Face pages are fetched with cursor pagination; the default packaged
+  snapshot uses the top 3000 repositories by downloads
 
 Refresh cadence: weekly via `.github/workflows/update-model-db.yml`.

package/src/data/sync-manager.js

@@ -47,22 +47,27 @@ class SyncManager {
 
         this.onProgress({ phase: 'start', message: 'Starting full sync...' });
 
-        // Clear existing data
-        this.db.clear();
-
-        // Scrape all models
-        const result = await this.scraper.scrapeAll((model, variants) => {
-            // Save model as we go
-            this.db.upsertModel(model);
-
-            // Save variants
-            for (const variant of variants) {
-                this.db.upsertVariant(variant);
-            }
-        });
+        // Batch all writes into a single atomic DB file write at the end. Saving on
+        // every upsert re-exported and rewrote the whole sql.js DB thousands of
+        // times, turning the sync into O(n^2) disk I/O.
+        this.db.beginBatch();
+        try {
+            // Clear existing data
+            this.db.clear();
+
+            // Scrape all models
+            await this.scraper.scrapeAll((model, variants) => {
+                this.db.upsertModel(model);
+                for (const variant of variants) {
+                    this.db.upsertVariant(variant);
+                }
+            });
 
-        // Update sync timestamp
-        this.db.setLastSync(new Date().toISOString());
+            // Update sync timestamp
+            this.db.setLastSync(new Date().toISOString());
+        } finally {
+            this.db.endBatch();
+        }
 
         const stats = this.db.getStats();
 
@@ -110,6 +115,9 @@ class SyncManager {
         let updated = 0;
         let added = 0;
 
+        // Batch all upserts into a single atomic DB write at the end (see fullSync).
+        this.db.beginBatch();
+        try {
         // Process new models
         for (const { id } of newModels) {
             try {
@@ -157,12 +165,18 @@ class SyncManager {
 
                 await this.sleep(100);
             } catch (error) {
-                // Ignore errors during incremental update
+                // Log instead of silently swallowing: a systematic failure here
+                // (network down, schema mismatch) would otherwise report success
+                // with updated: 0 and leave the catalog quietly stale.
+                this.onError(`Error updating ${id}: ${error.message}`);
             }
         }
 
-        // Update sync timestamp
-        this.db.setLastSync(new Date().toISOString());
+            // Update sync timestamp
+            this.db.setLastSync(new Date().toISOString());
+        } finally {
+            this.db.endBatch();
+        }
 
         const stats = this.db.getStats();
 

package/src/hardware/backends/apple-silicon.js

@@ -283,7 +283,11 @@ class AppleSiliconDetector {
         const info = this.detect();
         if (!info) return null;
 
-        return `apple-${info.chip.toLowerCase().replace(/\s+/g, '-')}-${info.memory.unified}gb`;
+        // info.chip stays null when the sysctl brand-string read fails (sandboxed
+        // env, missing binary); fall back so this can't throw on null.toLowerCase().
+        const chip = info.chip || 'apple-silicon';
+        const unified = info.memory?.unified || 0;
+        return `apple-${chip.toLowerCase().replace(/\s+/g, '-')}-${unified}gb`;
     }
 
     /**