llm-checker 3.2.0 → 3.2.1

package/src/models/speculative-decoding-estimator.js

@@ -0,0 +1,245 @@
+const {
+    normalizeRuntime,
+    runtimeSupportsSpeculativeDecoding,
+    runtimeSupportedOnHardware,
+    getRuntimeModelRef
+} = require('../runtime/runtime-support');
+
+class SpeculativeDecodingEstimator {
+    constructor(options = {}) {
+        this.minDraftRatio = options.minDraftRatio || 0.1;
+        this.maxDraftRatio = options.maxDraftRatio || 0.65;
+        this.idealDraftRatio = options.idealDraftRatio || 0.28;
+
+        this.knownFamilies = [
+            'llama',
+            'qwen',
+            'mistral',
+            'mixtral',
+            'gemma',
+            'phi',
+            'deepseek',
+            'yi',
+            'command-r'
+        ];
+    }
+
+    estimate({ model, candidates = [], hardware = {}, runtime = 'ollama' } = {}) {
+        const selectedRuntime = normalizeRuntime(runtime);
+
+        if (!runtimeSupportsSpeculativeDecoding(selectedRuntime)) {
+            return null;
+        }
+
+        const targetParams = this.extractParams(model);
+        if (!targetParams || targetParams < 2) {
+            return {
+                runtime: selectedRuntime,
+                supported: true,
+                enabled: false,
+                reason: 'Target model is too small for meaningful speculative decoding gains.'
+            };
+        }
+
+        const family = this.extractFamily(model);
+        const draftCandidate = this.selectDraftCandidate(model, candidates, family, targetParams);
+
+        if (!draftCandidate) {
+            const suggestedDraftParams = this.getSuggestedDraftParams(targetParams);
+            const estimatedSpeedup = this.estimateSpeedup({
+                targetParams,
+                draftParams: suggestedDraftParams,
+                runtime: selectedRuntime,
+                hardware,
+                model
+            });
+
+            return {
+                runtime: selectedRuntime,
+                supported: true,
+                enabled: false,
+                estimatedSpeedup: Number(estimatedSpeedup.toFixed(2)),
+                estimatedThroughputGainPct: Math.round((estimatedSpeedup - 1) * 100),
+                suggestedDraftModel: family ? `${family} ~${suggestedDraftParams}B` : `~${suggestedDraftParams}B draft`,
+                reason: 'No compatible draft model found in the current shortlist.'
+            };
+        }
+
+        const draftParams = draftCandidate.params;
+        const estimatedSpeedup = this.estimateSpeedup({
+            targetParams,
+            draftParams,
+            runtime: selectedRuntime,
+            hardware,
+            model
+        });
+
+        const confidence = this.estimateConfidence({
+            family,
+            targetParams,
+            draftParams,
+            runtime: selectedRuntime,
+            hardware
+        });
+
+        return {
+            runtime: selectedRuntime,
+            supported: true,
+            enabled: true,
+            targetModelRef: getRuntimeModelRef(model, selectedRuntime),
+            draftModel: draftCandidate.model.name || draftCandidate.model.model_identifier || 'draft-model',
+            draftModelRef: getRuntimeModelRef(draftCandidate.model, selectedRuntime),
+            targetParams,
+            draftParams,
+            draftToTargetRatio: Number((draftParams / targetParams).toFixed(2)),
+            estimatedSpeedup: Number(estimatedSpeedup.toFixed(2)),
+            estimatedThroughputGainPct: Math.round((estimatedSpeedup - 1) * 100),
+            confidence: Number(confidence.toFixed(2)),
+            notes: this.buildNotes(selectedRuntime, family, estimatedSpeedup)
+        };
+    }
+
+    extractParams(model = {}) {
+        const direct = Number(model.params_b || model.paramsB);
+        if (Number.isFinite(direct) && direct > 0) {
+            return direct;
+        }
+
+        const sources = [
+            model.size,
+            model.name,
+            model.model_identifier,
+            model.ollamaTag,
+            model.ollamaId
+        ].filter(Boolean);
+
+        for (const source of sources) {
+            const text = String(source).toLowerCase();
+            const match = text.match(/(\d+(\.\d+)?)\s*b\b/i);
+            if (match) {
+                const params = Number(match[1]);
+                if (Number.isFinite(params) && params > 0) {
+                    return params;
+                }
+            }
+        }
+
+        return null;
+    }
+
+    extractFamily(model = {}) {
+        const text = String(
+            model.model_identifier ||
+            model.ollamaId ||
+            model.ollamaTag ||
+            model.name ||
+            ''
+        ).toLowerCase();
+
+        for (const family of this.knownFamilies) {
+            if (text.includes(family)) {
+                return family;
+            }
+        }
+
+        return '';
+    }
+
+    selectDraftCandidate(model, candidates, targetFamily, targetParams) {
+        const normalizedTargetName = String(model?.name || model?.model_identifier || '').toLowerCase();
+
+        const draftCandidates = candidates
+            .map((candidate) => {
+                const params = this.extractParams(candidate);
+                const family = this.extractFamily(candidate);
+                const ratio = params && targetParams ? params / targetParams : null;
+
+                return { model: candidate, params, family, ratio };
+            })
+            .filter((candidate) => {
+                const candidateName = String(candidate.model?.name || candidate.model?.model_identifier || '').toLowerCase();
+                if (!candidate.params || candidate.params >= targetParams) return false;
+                if (!candidate.ratio || candidate.ratio < this.minDraftRatio || candidate.ratio > this.maxDraftRatio) return false;
+                if (candidateName === normalizedTargetName) return false;
+
+                // Prefer same-family models due to tokenizer/embedding compatibility.
+                if (targetFamily && candidate.family) {
+                    return targetFamily === candidate.family;
+                }
+
+                return true;
+            })
+            .sort((a, b) => {
+                // Prefer ratio close to ideal draft ratio.
+                const scoreA = Math.abs((a.ratio || 0) - this.idealDraftRatio);
+                const scoreB = Math.abs((b.ratio || 0) - this.idealDraftRatio);
+                return scoreA - scoreB;
+            });
+
+        return draftCandidates[0] || null;
+    }
+
+    estimateSpeedup({ targetParams, draftParams, runtime, hardware, model }) {
+        const ratio = Math.max(1.01, targetParams / Math.max(0.1, draftParams));
+
+        // Base heuristic: diminishing returns as ratio grows.
+        let speedup = 1.05 + Math.log2(ratio) * 0.45;
+
+        if (ratio > 6) {
+            speedup -= 0.12;
+        }
+
+        if (runtime === 'vllm') {
+            speedup += 0.12;
+        } else if (runtime === 'mlx') {
+            speedup += 0.08;
+        }
+
+        if (runtime === 'mlx' && runtimeSupportedOnHardware('mlx', hardware)) {
+            speedup += 0.08;
+        }
+
+        if (model?.is_moe || model?.isMoE) {
+            speedup *= 0.92;
+        }
+
+        return Math.max(1.1, Math.min(2.8, speedup));
+    }
+
+    estimateConfidence({ family, targetParams, draftParams, runtime, hardware }) {
+        let confidence = 0.55;
+        const ratio = draftParams / targetParams;
+
+        if (family) confidence += 0.15;
+        if (ratio >= 0.2 && ratio <= 0.4) confidence += 0.15;
+        if (runtime === 'vllm') confidence += 0.05;
+        if (runtime === 'mlx') confidence += 0.03;
+
+        if (runtime === 'mlx' && runtimeSupportedOnHardware('mlx', hardware)) {
+            confidence += 0.05;
+        }
+
+        return Math.min(0.95, confidence);
+    }
+
+    getSuggestedDraftParams(targetParams) {
+        const draft = Math.max(1, targetParams * this.idealDraftRatio);
+        return Number(draft.toFixed(1));
+    }
+
+    buildNotes(runtime, family, speedup) {
+        const notes = [];
+        if (family) {
+            notes.push(`Same-family draft model (${family}) improves tokenizer/embedding alignment.`);
+        }
+        if (runtime === 'vllm') {
+            notes.push('Use --speculative-model in vLLM to enable speculative decoding.');
+        } else if (runtime === 'mlx') {
+            notes.push('MLX-LM speculative decoding works best with unified memory on Apple Silicon.');
+        }
+        notes.push(`Estimated throughput multiplier: x${speedup.toFixed(2)}.`);
+        return notes;
+    }
+}
+
+module.exports = SpeculativeDecodingEstimator;

package/src/runtime/runtime-support.js

@@ -0,0 +1,174 @@
+const SUPPORTED_RUNTIMES = ['ollama', 'vllm', 'mlx'];
+
+function normalizeRuntime(runtime = 'ollama') {
+    const normalized = String(runtime || 'ollama').trim().toLowerCase();
+    return SUPPORTED_RUNTIMES.includes(normalized) ? normalized : 'ollama';
+}
+
+function getRuntimeDisplayName(runtime = 'ollama') {
+    const normalized = normalizeRuntime(runtime);
+    if (normalized === 'vllm') return 'vLLM';
+    if (normalized === 'mlx') return 'MLX-LM';
+    return 'Ollama';
+}
+
+function isAppleSiliconHardware(hardware = {}) {
+    const osPlatform = String(hardware?.os?.platform || '').toLowerCase();
+    const arch = String(
+        hardware?.cpu?.architecture ||
+        hardware?.summary?.architecture ||
+        ''
+    ).toLowerCase();
+    const cpuBrand = String(hardware?.cpu?.brand || '').toLowerCase();
+    const gpuModel = String(hardware?.gpu?.model || '').toLowerCase();
+    const isDarwin = osPlatform === 'darwin' || osPlatform === 'macos';
+    const hasAppleChipSignal =
+        arch.includes('apple silicon') ||
+        cpuBrand.includes('apple') ||
+        gpuModel.includes('apple');
+
+    // Prefer explicit Apple signals and avoid treating generic Linux ARM64 as Apple Silicon.
+    if (isDarwin) {
+        return arch === 'arm64' || hasAppleChipSignal;
+    }
+
+    // Fallback for partial hardware payloads that still expose Apple-specific identifiers.
+    return hasAppleChipSignal;
+}
+
+function runtimeSupportedOnHardware(runtime = 'ollama', hardware = {}) {
+    const normalized = normalizeRuntime(runtime);
+    if (normalized === 'mlx') {
+        return isAppleSiliconHardware(hardware);
+    }
+    return true;
+}
+
+function runtimeSupportsSpeculativeDecoding(runtime = 'ollama') {
+    const normalized = normalizeRuntime(runtime);
+    return normalized === 'vllm' || normalized === 'mlx';
+}
+
+function shellEscapeArg(value = '') {
+    const text = String(value || '');
+    if (!text) return "''";
+    return `'${text.replace(/'/g, `'\\''`)}'`;
+}
+
+function extractFromInstallCommand(command = '') {
+    const match = String(command).match(/ollama\s+pull\s+(.+)$/i);
+    return match ? match[1].trim() : '';
+}
+
+function slugifyModelName(text = '') {
+    return String(text)
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'model';
+}
+
+function getRuntimeModelRef(model = {}, runtime = 'ollama') {
+    const normalized = normalizeRuntime(runtime);
+
+    const candidates = [
+        model.hfModel,
+        model.hfId,
+        model.huggingfaceId,
+        model.model_identifier,
+        model.identifier,
+        model.cloudData?.identifier,
+        model.ollamaTag,
+        extractFromInstallCommand(model.installation?.ollama),
+        model.ollamaId,
+        model.name
+    ].filter(Boolean);
+
+    const raw = String(candidates[0] || '').trim();
+    if (!raw) return 'model';
+
+    if (normalized === 'ollama') {
+        return raw;
+    }
+
+    if (raw.includes('/')) {
+        return raw;
+    }
+
+    // Remove Ollama-style tag suffix for non-Ollama runtimes.
+    const base = raw.split(':')[0].trim();
+    if (base) {
+        return /\s/.test(base) ? slugifyModelName(base) : base;
+    }
+
+    return slugifyModelName(raw);
+}
+
+function getRuntimeInstallCommand(runtime = 'ollama') {
+    const normalized = normalizeRuntime(runtime);
+
+    if (normalized === 'vllm') {
+        return 'pip install -U "vllm>=0.6.0"';
+    }
+
+    if (normalized === 'mlx') {
+        return 'pip install -U mlx-lm';
+    }
+
+    return 'ollama --version || (brew install ollama)';
+}
+
+function getRuntimePullCommand(model = {}, runtime = 'ollama') {
+    const normalized = normalizeRuntime(runtime);
+    const modelRef = getRuntimeModelRef(model, runtime);
+
+    if (normalized === 'vllm') {
+        return `huggingface-cli download ${shellEscapeArg(modelRef)}`;
+    }
+
+    if (normalized === 'mlx') {
+        const localName = slugifyModelName(modelRef);
+        return `python -m mlx_lm.convert --hf-path ${shellEscapeArg(modelRef)} --mlx-path ./models/${localName}`;
+    }
+
+    return `ollama pull ${modelRef}`;
+}
+
+function getRuntimeRunCommand(model = {}, runtime = 'ollama') {
+    const normalized = normalizeRuntime(runtime);
+    const modelRef = getRuntimeModelRef(model, runtime);
+
+    if (normalized === 'vllm') {
+        return `python -m vllm.entrypoints.openai.api_server --model ${shellEscapeArg(modelRef)} --host 0.0.0.0 --port 8000`;
+    }
+
+    if (normalized === 'mlx') {
+        return `python -m mlx_lm.generate --model ${shellEscapeArg(modelRef)} --prompt "Hello"`;
+    }
+
+    return `ollama run ${modelRef}`;
+}
+
+function getRuntimeCommandSet(model = {}, runtime = 'ollama') {
+    const normalized = normalizeRuntime(runtime);
+    return {
+        runtime: normalized,
+        displayName: getRuntimeDisplayName(normalized),
+        modelRef: getRuntimeModelRef(model, normalized),
+        install: getRuntimeInstallCommand(normalized),
+        pull: getRuntimePullCommand(model, normalized),
+        run: getRuntimeRunCommand(model, normalized)
+    };
+}
+
+module.exports = {
+    SUPPORTED_RUNTIMES,
+    normalizeRuntime,
+    getRuntimeDisplayName,
+    runtimeSupportedOnHardware,
+    runtimeSupportsSpeculativeDecoding,
+    getRuntimeModelRef,
+    getRuntimeInstallCommand,
+    getRuntimePullCommand,
+    getRuntimeRunCommand,
+    getRuntimeCommandSet
+};

package/bin/CLAUDE.md

@@ -1,27 +0,0 @@
-<claude-mem-context>
-# Recent Activity
-
-<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
-
-### Feb 12, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #3492 | 10:24 PM | 🔵 | Enhanced CLI Structure - Lazy Loading with ASCII Art Branding | ~456 |
-| #3436 | 9:57 PM | 🔵 | Enhanced CLI Implementation - Command-Line Interface with ASCII Art and Ollama Integration | ~575 |
-
-### Feb 14, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #4369 | 7:19 PM | 🟣 | Added 6 advanced MCP-exclusive tools for benchmarking, optimization, and intelligent model management | ~703 |
-| #4368 | " | 🟣 | MCP server implementation added to llm-checker with benchmark tool | ~387 |
-| #4363 | 7:18 PM | 🟣 | MCP tools test suite successfully validates all 7 llm-checker tools | ~551 |
-| #4361 | 7:17 PM | 🟣 | MCP server test suite created for validating Ollama integration tools | ~524 |
-| #4356 | " | 🟣 | Six advanced MCP tools added to llm-checker server beyond CLI wrapping | ~750 |
-| #4349 | 7:15 PM | 🟣 | MCP server implementation exposes 9 tools for LLM hardware analysis and Ollama model management | ~539 |
-| #4341 | 6:49 PM | 🟣 | MCP server implementation committed to llm-checker repository | ~431 |
-| #4339 | " | 🟣 | MCP server implementation and documentation added to llm-checker repository | ~457 |
-| #4338 | " | ✅ | MCP server validated in llm-checker repository structure | ~245 |
-| #4333 | 6:48 PM | 🟣 | MCP server integrated into llm-checker package distribution | ~409 |
-</claude-mem-context>

package/src/CLAUDE.md

@@ -1,18 +0,0 @@
-<claude-mem-context>
-# Recent Activity
-
-<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
-
-### Feb 12, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #3485 | 10:23 PM | 🔵 | Dead Code in Main Analysis Method - Lines 73-214 Unreachable | ~555 |
-| #3435 | 9:57 PM | 🔵 | Main LLMChecker Class Architecture - Platform-Specific Analysis Engine | ~630 |
-
-### Feb 14, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #4339 | 6:49 PM | 🟣 | MCP server implementation and documentation added to llm-checker repository | ~457 |
-</claude-mem-context>

package/src/data/CLAUDE.md

@@ -1,17 +0,0 @@
-<claude-mem-context>
-# Recent Activity
-
-<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
-
-### Feb 12, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #3464 | 10:03 PM | 🔵 | SQL Database Schema - Indexed Model Repository with Benchmarks | ~555 |
-
-### Feb 14, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #4339 | 6:49 PM | 🟣 | MCP server implementation and documentation added to llm-checker repository | ~457 |
-</claude-mem-context>

package/src/hardware/CLAUDE.md

@@ -1,18 +0,0 @@
-<claude-mem-context>
-# Recent Activity
-
-<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
-
-### Feb 12, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #3490 | 10:24 PM | 🔵 | Hardware Detector Cache Implementation - 5-Minute TTL Without Force Refresh Option | ~536 |
-| #3440 | 9:58 PM | 🔵 | Hardware Detection System - Multi-GPU Support with Intelligent Selection | ~611 |
-
-### Feb 14, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #4339 | 6:49 PM | 🟣 | MCP server implementation and documentation added to llm-checker repository | ~457 |
-</claude-mem-context>

package/src/hardware/backends/CLAUDE.md

@@ -1,17 +0,0 @@
-<claude-mem-context>
-# Recent Activity
-
-<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
-
-### Feb 12, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #3453 | 10:01 PM | 🔵 | CUDA Detector Implementation - NVIDIA GPU Detection via nvidia-smi | ~497 |
-
-### Feb 14, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #4339 | 6:49 PM | 🟣 | MCP server implementation and documentation added to llm-checker repository | ~457 |
-</claude-mem-context>

package/src/models/CLAUDE.md

@@ -1,23 +0,0 @@
-<claude-mem-context>
-# Recent Activity
-
-<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
-
-### Feb 12, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #3442 | 9:59 PM | 🔵 | Static Model Database Structure - Hardcoded LLM Specifications | ~572 |
-
-### Feb 13, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #3699 | 12:05 AM | ✅ | Git Push Consolidated Architecture Changes to GitHub | ~367 |
-
-### Feb 14, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #4339 | 6:49 PM | 🟣 | MCP server implementation and documentation added to llm-checker repository | ~457 |
-</claude-mem-context>

package/src/ollama/CLAUDE.md

@@ -1,30 +0,0 @@
-<claude-mem-context>
-# Recent Activity
-
-<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
-
-### Feb 12, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #3500 | 10:26 PM | 🔴 | pullModel() Stream Handling Improved - Success Validation Added | ~458 |
-| #3499 | " | 🔴 | Race Condition Fixed in Ollama Availability Cache | ~440 |
-| #3498 | 10:25 PM | 🔵 | testModelPerformance() Timeout Already Fixed | ~418 |
-| #3497 | " | 🔴 | Timeout Fixed in deleteModel() Using AbortController | ~391 |
-| #3496 | " | 🔴 | Timeout Fixed in testConnection() Using AbortController | ~395 |
-| #3495 | " | 🔴 | Fixed unbounded memory growth in native scraper HTTP request handler | ~361 |
-| #3493 | " | 🔴 | Fixed race condition in checkOllamaAvailability() with promise deduplication | ~398 |
-| #3491 | 10:24 PM | 🔴 | Added missing clearTimeout() in testModelPerformance() | ~319 |
-| #3489 | " | 🔴 | Fixed node-fetch timeout handling in testModelPerformance() | ~332 |
-| #3488 | " | 🔴 | Fixed node-fetch timeout handling in testConnection() tags check | ~303 |
-| #3486 | " | 🔴 | Fixed node-fetch timeout handling in getRunningModels() | ~308 |
-| #3484 | 10:23 PM | 🔵 | Ollama Client Timeout Implementation - Mixed Patterns with AbortController | ~554 |
-| #3443 | 9:59 PM | 🔵 | Ollama Native Scraper - Web Scraping with Dual Cache Strategy | ~594 |
-| #3437 | 9:58 PM | 🔵 | Ollama Client Implementation - HTTP API Wrapper with Connection Management | ~605 |
-
-### Feb 14, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #4339 | 6:49 PM | 🟣 | MCP server implementation and documentation added to llm-checker repository | ~457 |
-</claude-mem-context>

package/src/plugins/CLAUDE.md

@@ -1,17 +0,0 @@
-<claude-mem-context>
-# Recent Activity
-
-<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
-
-### Feb 12, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #3462 | 10:02 PM | 🔵 | Plugin System Architecture - Hook-Based Extensibility Framework | ~648 |
-
-### Feb 14, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #4339 | 6:49 PM | 🟣 | MCP server implementation and documentation added to llm-checker repository | ~457 |
-</claude-mem-context>

package/src/utils/CLAUDE.md

@@ -1,17 +0,0 @@
-<claude-mem-context>
-# Recent Activity
-
-<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
-
-### Feb 12, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #3438 | 9:58 PM | 🔵 | Configuration Management System - Comprehensive Settings with Environment Overrides | ~580 |
-
-### Feb 14, 2026
-
-| ID | Time | T | Title | Read |
-|----|------|---|-------|------|
-| #4339 | 6:49 PM | 🟣 | MCP server implementation and documentation added to llm-checker repository | ~457 |
-</claude-mem-context>