llm-checker 3.1.1 → 3.2.1

package/README.md

@@ -52,6 +52,20 @@ Choosing the right LLM for your hardware is complex. With thousands of model var
 
 ---
 
+## Comparison with Other Tooling (e.g. `llmfit`)
+
+LLM Checker and `llmfit` solve related but different problems:
+
+| Tool | Primary Focus | Typical Output |
+|------|---------------|----------------|
+| **LLM Checker** | Hardware-aware **model selection** for local inference | Ranked recommendations, compatibility scores, pull/run commands |
+| **llmfit** | LLM workflow support and model-fit evaluation from another angle | Different optimization workflow and selection heuristics |
+
+If your goal is: *"What should I run on this exact machine right now?"*, use **LLM Checker** first.  
+If your goal is broader experimentation across custom pipelines, using both tools can be complementary.
+
+---
+
 ## Installation
 
 ```bash
@@ -118,6 +132,8 @@ Restart Claude Code and you're done.
 
 Once connected, Claude can use these tools:
 
+**Core Analysis:**
+
 | Tool | Description |
 |------|-------------|
 | `hw_detect` | Detect your hardware (CPU, GPU, RAM, acceleration backend) |
@@ -126,19 +142,38 @@ Once connected, Claude can use these tools:
 | `installed` | Rank your already-downloaded Ollama models |
 | `search` | Search the Ollama model catalog with filters |
 | `smart_recommend` | Advanced recommendations using the full scoring engine |
-| `ollama_list` | List all downloaded Ollama models |
+
+**Ollama Management:**
+
+| Tool | Description |
+|------|-------------|
+| `ollama_list` | List all downloaded models with params, quant, family, and size |
 | `ollama_pull` | Download a model from the Ollama registry |
-| `ollama_run` | Run a prompt against a local Ollama model |
+| `ollama_run` | Run a prompt against a local model (with tok/s metrics) |
+| `ollama_remove` | Delete a model to free disk space |
+
+**Advanced (MCP-exclusive):**
+
+| Tool | Description |
+|------|-------------|
+| `ollama_optimize` | Generate optimal Ollama env vars for your hardware (NUM_GPU, PARALLEL, FLASH_ATTENTION, etc.) |
+| `benchmark` | Benchmark a model with 3 standardized prompts — measures tok/s, load time, prompt eval |
+| `compare_models` | Head-to-head comparison of two models on the same prompt with speed + response side-by-side |
+| `cleanup_models` | Analyze installed models — find redundancies, cloud-only models, oversized models, and upgrade candidates |
+| `project_recommend` | Scan a project directory (languages, frameworks, size) and recommend the best model for that codebase |
+| `ollama_monitor` | Real-time system status: RAM usage, loaded models, memory headroom analysis |
 
 ### Example Prompts
 
 After setup, you can ask Claude things like:
 
 - *"What's the best coding model for my hardware?"*
-- *"What models do I have installed and how do they rank?"*
-- *"Pull the top reasoning model for my system"*
-- *"Search for multimodal models under 8GB"*
-- *"Run this prompt on qwen2.5-coder"*
+- *"Benchmark qwen2.5-coder and show me the tok/s"*
+- *"Compare llama3.2 vs codellama for coding tasks"*
+- *"Clean up my Ollama — what should I remove?"*
+- *"What model should I use for this Rust project?"*
+- *"Optimize my Ollama config for maximum performance"*
+- *"How much RAM is Ollama using right now?"*
 
 Claude will automatically call the right tools and give you actionable results.
 

package/analyzer/compatibility.js

@@ -1,4 +1,10 @@
 const { getLogger } = require('../src/utils/logger');
+const {
+    normalizeRuntime,
+    getRuntimeDisplayName,
+    runtimeSupportedOnHardware,
+    runtimeSupportsSpeculativeDecoding
+} = require('../src/runtime/runtime-support');
 
 class CompatibilityAnalyzer {
     constructor() {
@@ -451,6 +457,7 @@ class CompatibilityAnalyzer {
 
     generateRecommendations(hardware, results, options = {}) {
         const recommendations = [];
+        const runtime = normalizeRuntime(options.runtime || 'ollama');
         const tier = this.getHardwareTier(hardware);
 
         if (hardware.memory.total < 16) {
@@ -511,6 +518,19 @@ class CompatibilityAnalyzer {
             }
         }
 
+        if (runtime !== 'ollama') {
+            const runtimeLabel = getRuntimeDisplayName(runtime);
+            if (runtimeSupportedOnHardware(runtime, hardware)) {
+                recommendations.push(`Runtime selected: ${runtimeLabel}`);
+            } else {
+                recommendations.push(`${runtimeLabel} is not recommended on this hardware (fallback to Ollama).`);
+            }
+
+            if (runtimeSupportsSpeculativeDecoding(runtime)) {
+                recommendations.push(`Enable speculative decoding in ${runtimeLabel} for higher throughput.`);
+            }
+        }
+
         return recommendations;
     }
 

package/bin/cli.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+'use strict';
+
+const majorNodeVersion = Number.parseInt(process.versions.node.split('.')[0], 10);
+
+if (!Number.isFinite(majorNodeVersion) || majorNodeVersion < 16) {
+    console.error(
+        `[llm-checker] Unsupported Node.js version: ${process.versions.node}. ` +
+        'Please use Node.js 16 or newer.'
+    );
+    process.exit(1);
+}
+
+require('./enhanced_cli');

package/bin/enhanced_cli.js

@@ -16,6 +16,14 @@ function getLLMChecker() {
 const { getLogger } = require('../src/utils/logger');
 const fs = require('fs');
 const path = require('path');
+const {
+    SUPPORTED_RUNTIMES,
+    normalizeRuntime,
+    runtimeSupportedOnHardware,
+    getRuntimeDisplayName,
+    getRuntimeCommandSet
+} = require('../src/runtime/runtime-support');
+const SpeculativeDecodingEstimator = require('../src/models/speculative-decoding-estimator');
 
 // ASCII Art for each command - Large text banners
 const ASCII_ART = {
@@ -1406,10 +1414,18 @@ function displaySimplifiedSystemInfo(hardware) {
     console.log(`Hardware Tier: ${tierColor.bold(tier)}`);
 }
 
-async function displayModelRecommendations(analysis, hardware, useCase = 'general', limit = 1) {
+async function displayModelRecommendations(analysis, hardware, useCase = 'general', limit = 1, runtime = 'ollama') {
     const title = limit === 1 ? 'RECOMMENDED MODEL' : `TOP ${limit} COMPATIBLE MODELS`;
     console.log(chalk.green.bold(`\n${title}`));
     console.log(chalk.gray('─'.repeat(50)));
+
+    const selectedRuntime = normalizeRuntime(runtime);
+    const runtimeLabel = getRuntimeDisplayName(selectedRuntime);
+    const speculativeEstimator = new SpeculativeDecodingEstimator();
+    const speculativeCandidatePool = [
+        ...(analysis?.compatible || []),
+        ...(analysis?.marginal || [])
+    ];
     
     // Find the best models from compatible models considering use case
     let selectedModels = [];
@@ -1760,42 +1776,75 @@ async function displayModelRecommendations(analysis, hardware, useCase = 'genera
             if (model.performanceEstimate) {
                 console.log(`Estimated Speed: ${chalk.yellow(model.performanceEstimate.estimatedTokensPerSecond || 'N/A')} tokens/sec`);
             }
-            
-            // Check if it's already installed by comparing with Ollama integration
+
+            console.log(`Runtime: ${chalk.white(runtimeLabel)}`);
+            const runtimeCommands = getRuntimeCommandSet(model, selectedRuntime);
+
+            // Check installation only when using Ollama runtime.
             let isInstalled = false;
-            try {
-                isInstalled = await checkIfModelInstalled(model, analysis.ollamaInfo);
-                if (isInstalled) {
-                    console.log(`Status: ${chalk.green('Already installed in Ollama')}`);
-                } else if (analysis.ollamaInfo && analysis.ollamaInfo.available) {
-                    console.log(`Status: ${chalk.gray('Available for installation')}`);
-                } else {
-                    console.log(`Status: ${chalk.yellow('Requires Ollama (not detected)')}`);
+            if (selectedRuntime === 'ollama') {
+                try {
+                    isInstalled = await checkIfModelInstalled(model, analysis.ollamaInfo);
+                    if (isInstalled) {
+                        console.log(`Status: ${chalk.green('Already installed in Ollama')}`);
+                    } else if (analysis.ollamaInfo && analysis.ollamaInfo.available) {
+                        console.log(`Status: ${chalk.gray('Available for installation')}`);
+                    } else {
+                        console.log(`Status: ${chalk.yellow('Requires Ollama (not detected)')}`);
+                    }
+                } catch (installCheckError) {
+                    if (analysis.ollamaInfo && analysis.ollamaInfo.available) {
+                        console.log(`Status: ${chalk.gray('Available for installation')}`);
+                    } else {
+                        console.log(`Status: ${chalk.yellow('Requires Ollama (not detected)')}`);
+                    }
                 }
-            } catch (installCheckError) {
-                // If checking installation status fails, show based on Ollama availability
-                if (analysis.ollamaInfo && analysis.ollamaInfo.available) {
-                    console.log(`Status: ${chalk.gray('Available for installation')}`);
-                } else {
-                    console.log(`Status: ${chalk.yellow('Requires Ollama (not detected)')}`);
+
+                const ollamaCommand = getOllamaInstallCommand(model);
+                if (ollamaCommand) {
+                    const modelName = extractModelName(ollamaCommand);
+                    if (isInstalled) {
+                        console.log(`\nRun: ${chalk.cyan.bold(`ollama run ${modelName}`)}`);
+                    } else {
+                        console.log(`\nPull: ${chalk.cyan.bold(ollamaCommand)}`);
+                    }
+                } else if (model.ollamaTag || model.ollamaId) {
+                    const tag = model.ollamaTag || model.ollamaId;
+                    if (isInstalled) {
+                        console.log(`\nRun: ${chalk.cyan.bold(`ollama run ${tag}`)}`);
+                    } else {
+                        console.log(`\nPull: ${chalk.cyan.bold(`ollama pull ${tag}`)}`);
+                    }
+                }
+            } else {
+                console.log(`Status: ${chalk.gray(`${runtimeLabel} runtime selected`)}`);
+                console.log(`\nRun: ${chalk.cyan.bold(runtimeCommands.run)}`);
+                if (index === 0) {
+                    console.log(`Install runtime: ${chalk.cyan.bold(runtimeCommands.install)}`);
+                    console.log(`Fetch model: ${chalk.cyan.bold(runtimeCommands.pull)}`);
                 }
             }
 
-            // Show pull/run command directly in each model block (Issue #3)
-            const ollamaCommand = getOllamaInstallCommand(model);
-            if (ollamaCommand) {
-                const modelName = extractModelName(ollamaCommand);
-                if (isInstalled) {
-                    console.log(`\nCommand: ${chalk.cyan.bold(`ollama run ${modelName}`)}`);
-                } else {
-                    console.log(`\nCommand: ${chalk.cyan.bold(ollamaCommand)}`);
-                }
-            } else if (model.ollamaTag || model.ollamaId) {
-                const tag = model.ollamaTag || model.ollamaId;
-                if (isInstalled) {
-                    console.log(`\nCommand: ${chalk.cyan.bold(`ollama run ${tag}`)}`);
-                } else {
-                    console.log(`\nCommand: ${chalk.cyan.bold(`ollama pull ${tag}`)}`);
+            const speculativeInfo =
+                model.speculativeDecoding ||
+                speculativeEstimator.estimate({
+                    model,
+                    candidates: speculativeCandidatePool,
+                    hardware,
+                    runtime: selectedRuntime
+                });
+
+            if (speculativeInfo && speculativeInfo.runtime === selectedRuntime) {
+                if (speculativeInfo.enabled) {
+                    console.log(
+                        `SpecDec: ${chalk.green(`+${speculativeInfo.estimatedThroughputGainPct}%`)} ` +
+                        `(${chalk.gray(`draft: ${speculativeInfo.draftModel}`)})`
+                    );
+                } else if (speculativeInfo.estimatedSpeedup) {
+                    const suggested = speculativeInfo.suggestedDraftModel ? ` with ${speculativeInfo.suggestedDraftModel}` : '';
+                    console.log(
+                        `SpecDec estimate: ${chalk.yellow(`+${speculativeInfo.estimatedThroughputGainPct}%`)}${chalk.gray(suggested)}`
+                    );
                 }
             }
         }
@@ -1807,9 +1856,12 @@ async function displayModelRecommendations(analysis, hardware, useCase = 'genera
     return selectedModels;
 }
 
-async function displayQuickStartCommands(analysis, recommendedModel = null, allRecommended = null) {
+async function displayQuickStartCommands(analysis, recommendedModel = null, allRecommended = null, runtime = 'ollama') {
     console.log(chalk.yellow.bold('\nQUICK START'));
     console.log(chalk.gray('─'.repeat(50)));
+
+    const selectedRuntime = normalizeRuntime(runtime);
+    const runtimeLabel = getRuntimeDisplayName(selectedRuntime);
     
     // Use the first model from allRecommended if available, otherwise fallback to recommendedModel
     let bestModel = (allRecommended && allRecommended.length > 0) ? allRecommended[0] : recommendedModel;
@@ -1824,6 +1876,33 @@ async function displayQuickStartCommands(analysis, recommendedModel = null, allR
         }
     }
     
+    if (selectedRuntime !== 'ollama') {
+        if (!bestModel) {
+            console.log(`1. Try expanding search: ${chalk.cyan('llm-checker check --include-cloud')}`);
+            return;
+        }
+
+        const runtimeCommands = getRuntimeCommandSet(bestModel, selectedRuntime);
+        console.log(`1. Install ${runtimeLabel}:`);
+        console.log(`   ${chalk.cyan.bold(runtimeCommands.install)}`);
+        console.log(`2. Fetch model weights:`);
+        console.log(`   ${chalk.cyan.bold(runtimeCommands.pull)}`);
+        console.log(`3. Run model:`);
+        console.log(`   ${chalk.cyan.bold(runtimeCommands.run)}`);
+
+        const speculative = bestModel.speculativeDecoding;
+        if (speculative && speculative.enabled) {
+            console.log(`4. SpecDec suggestion (${chalk.green(`+${speculative.estimatedThroughputGainPct}%`)}):`);
+            if (selectedRuntime === 'vllm') {
+                console.log(`   ${chalk.cyan.bold(`${runtimeCommands.run} --speculative-model '${speculative.draftModelRef || speculative.draftModel}'`)}`);
+            } else if (selectedRuntime === 'mlx') {
+                console.log(`   ${chalk.gray(`Use draft model ${speculative.draftModelRef || speculative.draftModel} when enabling speculative decoding in MLX-LM`)}`);
+            }
+        }
+
+        return;
+    }
+
     if (analysis.ollamaInfo && !analysis.ollamaInfo.available) {
         console.log(`1. Install Ollama: ${chalk.underline('https://ollama.ai')}`);
         console.log(`2. Come back and run this command again`);
@@ -1992,6 +2071,7 @@ program
     .option('--min-size <size>', 'Minimum model size to consider (e.g., "7B" or "7GB")')
     .option('--include-cloud', 'Include cloud models in analysis')
     .option('--ollama-only', 'Only show models available in Ollama')
+    .option('--runtime <runtime>', `Inference runtime (${SUPPORTED_RUNTIMES.join('|')})`, 'ollama')
     .option('--performance-test', 'Run performance benchmarks')
     .option('--show-ollama-analysis', 'Show detailed Ollama model analysis')
     .option('--no-verbose', 'Disable step-by-step progress display')
@@ -2008,6 +2088,16 @@ program
             }
 
             const hardware = await checker.getSystemInfo();
+            let selectedRuntime = normalizeRuntime(options.runtime);
+            if (!runtimeSupportedOnHardware(selectedRuntime, hardware)) {
+                const runtimeLabel = getRuntimeDisplayName(selectedRuntime);
+                console.log(
+                    chalk.yellow(
+                        `\nWarning: ${runtimeLabel} is not supported on this hardware. Falling back to Ollama.`
+                    )
+                );
+                selectedRuntime = 'ollama';
+            }
             
             // Normalize and fix use-case typos
             const normalizeUseCase = (useCase = '') => {
@@ -2049,7 +2139,8 @@ program
                 performanceTest: options.performanceTest,
                 limit: parseInt(options.limit) || 10,
                 maxSize: maxSize,
-                minSize: minSize
+                minSize: minSize,
+                runtime: selectedRuntime
             });
 
             if (!verboseEnabled) {
@@ -2058,8 +2149,14 @@ program
 
             // Simplified output - show only essential information
             displaySimplifiedSystemInfo(hardware);
-            const recommendedModels = await displayModelRecommendations(analysis, hardware, normalizedUseCase, parseInt(options.limit) || 1);
-            await displayQuickStartCommands(analysis, recommendedModels[0], recommendedModels);
+            const recommendedModels = await displayModelRecommendations(
+                analysis,
+                hardware,
+                normalizedUseCase,
+                parseInt(options.limit) || 1,
+                selectedRuntime
+            );
+            await displayQuickStartCommands(analysis, recommendedModels[0], recommendedModels, selectedRuntime);
 
         } catch (error) {
             console.error(chalk.red('\nError:'), error.message);