llm-checker 3.4.1 → 3.4.2

package/README.md

@@ -332,6 +332,7 @@ Claude will automatically call the right tools and give you actionable results.
 | `calibrate` | Generate calibration result + routing policy artifacts from a JSONL prompt suite |
 | `installed` | Rank your installed Ollama models by compatibility |
 | `ollama-plan` | Compute safe Ollama runtime env vars (`NUM_CTX`, `NUM_PARALLEL`, `MAX_LOADED_MODELS`) for selected local models |
+| `gpu-plan` | Simulate `pin`/`replica`/`spread` multi-GPU placement with memory-fit and throughput estimates per model |
 
 ### Advanced Commands (require `sql.js`)
 

package/bin/enhanced_cli.js

@@ -3255,6 +3255,140 @@ program
         }
     });
 
+program
+    .command('gpu-plan')
+    .description('Recommend multi-GPU placement strategies for selected local models')
+    .option('--models <models...>', 'Model tags/families to include (default: all local models)')
+    .option('--ctx <tokens>', 'Target context window in tokens', '8192')
+    .option('--concurrency <n>', 'Target parallel request count', '2')
+    .option('--objective <mode>', 'Optimization objective (latency|balanced|throughput)', 'balanced')
+    .option('--reserve-gb <gb>', 'Memory reserve to subtract from available GPU memory', '1')
+    .option('--json', 'Output plan as JSON')
+    .action(async (options) => {
+        const spinner = options.json ? null : ora('Building GPU placement plan...').start();
+
+        try {
+            const requestedObjective = String(options.objective || 'balanced').toLowerCase();
+            const supportedObjectives = new Set(['latency', 'balanced', 'throughput']);
+            if (!supportedObjectives.has(requestedObjective)) {
+                throw new Error(`Invalid objective "${options.objective}". Use latency, balanced, or throughput.`);
+            }
+
+            const targetContext = parsePositiveIntegerOption(options.ctx, '--ctx');
+            const targetConcurrency = parsePositiveIntegerOption(options.concurrency, '--concurrency');
+            const reserveGB = parseNonNegativeNumberOption(options.reserveGb, '--reserve-gb');
+
+            const OllamaClient = require('../src/ollama/client');
+            const UnifiedDetector = require('../src/hardware/unified-detector');
+            const OllamaGPUPlacementPlanner = require('../src/ollama/gpu-placement-planner');
+
+            const ollamaClient = new OllamaClient();
+            const availability = await ollamaClient.checkOllamaAvailability();
+            if (!availability.available) {
+                throw new Error(availability.error || 'Ollama is not available');
+            }
+
+            const localModels = await ollamaClient.getLocalModels();
+            if (!localModels || localModels.length === 0) {
+                throw new Error('No local Ollama models found. Install one with: ollama pull llama3.2:3b');
+            }
+
+            const { selected, missing } = selectModelsForPlan(localModels, options.models || []);
+            if (selected.length === 0) {
+                throw new Error(
+                    `No matching local models found for: ${(options.models || []).join(', ')}`
+                );
+            }
+
+            const detector = new UnifiedDetector();
+            const hardware = await detector.detect();
+            const planner = new OllamaGPUPlacementPlanner();
+
+            const plan = planner.plan({
+                hardware,
+                models: selected,
+                targetContext,
+                targetConcurrency,
+                objective: requestedObjective,
+                reserveGB
+            });
+
+            if (options.json) {
+                console.log(JSON.stringify({
+                    generated_at: new Date().toISOString(),
+                    selection: {
+                        requested: options.models || [],
+                        selected: selected.map((model) => model.name),
+                        missing
+                    },
+                    plan
+                }, null, 2));
+                return;
+            }
+
+            if (spinner) spinner.succeed('GPU placement plan generated');
+
+            console.log('\n' + chalk.bgMagenta.white.bold(' GPU PLACEMENT PLAN '));
+            console.log(chalk.magenta('Backend:'), `${plan.hardware.backend_name} (${plan.hardware.backend})`);
+            console.log(
+                chalk.magenta('GPU inventory:'),
+                `${plan.hardware.gpu_count} device(s), ${plan.hardware.total_usable_memory_gb}GB usable (reserve ${plan.hardware.reserve_gb}GB)`
+            );
+            console.log(
+                chalk.magenta('Target envelope:'),
+                `ctx=${plan.inputs.target_context}, concurrency=${plan.inputs.target_concurrency}, objective=${plan.objective}`
+            );
+
+            if (missing.length > 0) {
+                console.log(chalk.yellow('Missing model filters:'), missing.join(', '));
+            }
+
+            if (!plan.hardware.is_multi_gpu) {
+                console.log(chalk.yellow('Only one GPU detected: replica/spread are included for simulation but may be infeasible.'));
+            }
+
+            for (const modelPlan of plan.models) {
+                const recommended = modelPlan.recommended || {};
+                const recFit = recommended.feasible ? chalk.green('fit') : chalk.red('no-fit');
+                const recRisk = recommended.risk ? `${recommended.risk.level.toUpperCase()} (${recommended.risk.score})` : 'N/A';
+
+                console.log(chalk.magenta.bold(`\nModel: ${modelPlan.name} (${modelPlan.size})`));
+                console.log(
+                    `  Recommended: ${chalk.bold((recommended.strategy || 'unknown').toUpperCase())} | ${recFit} | ~${recommended.estimated_tps || 0} tok/s | risk ${recRisk}`
+                );
+
+                if (recommended.device_env_var && recommended.visible_devices) {
+                    console.log(`  Device pinning hint: export ${recommended.device_env_var}=${recommended.visible_devices}`);
+                }
+
+                console.log(chalk.magenta('  Strategies:'));
+                for (const strategy of modelPlan.strategies) {
+                    const fit = strategy.feasible ? chalk.green('fit') : chalk.red('no-fit');
+                    const risk = strategy.risk ? `${strategy.risk.level} (${strategy.risk.score})` : 'n/a';
+                    console.log(
+                        `    - ${strategy.strategy.padEnd(7)} ${fit} | ~${strategy.estimated_tps} tok/s | ${strategy.memory_per_gpu_gb}GB/GPU | risk ${risk}`
+                    );
+                }
+            }
+
+            if (plan.notes && plan.notes.length > 0) {
+                console.log(chalk.magenta.bold('\nNotes:'));
+                for (const note of plan.notes) {
+                    console.log(`  - ${note}`);
+                }
+            }
+
+            console.log('');
+        } catch (error) {
+            if (spinner) spinner.fail('Failed to build GPU placement plan');
+            console.error(chalk.red('Error:'), error.message);
+            if (process.env.DEBUG) {
+                console.error(error.stack);
+            }
+            process.exit(1);
+        }
+    });
+
 program
     .command('recommend')
     .description('Get intelligent model recommendations for your hardware')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-checker",
-  "version": "3.4.1",
+  "version": "3.4.2",
   "description": "Intelligent CLI tool with AI-powered model selection that analyzes your hardware and recommends optimal LLM models for your system",
   "bin": {
     "llm-checker": "bin/cli.js",

package/src/ollama/gpu-placement-planner.js

@@ -0,0 +1,496 @@
+class OllamaGPUPlacementPlanner {
+    constructor(options = {}) {
+        this.minContext = options.minContext || 2048;
+        this.defaultReserveGB = options.defaultReserveGB || 1;
+        this.kvFactorPer4k = options.kvFactorPer4k || 0.08; // GB per 1B params at 4K context
+        this.modelOverheadGB = options.modelOverheadGB || 0.7;
+        this.spreadOverheadGB = options.spreadOverheadGB || 0.35;
+    }
+
+    toFiniteNumber(value, fallback = 0) {
+        const numeric = Number(value);
+        return Number.isFinite(numeric) ? numeric : fallback;
+    }
+
+    clamp(value, min, max) {
+        return Math.min(max, Math.max(min, value));
+    }
+
+    normalizeObjective(objective) {
+        const normalized = String(objective || 'balanced').toLowerCase();
+        if (normalized === 'latency' || normalized === 'balanced' || normalized === 'throughput') {
+            return normalized;
+        }
+        return 'balanced';
+    }
+
+    parseParamsB(model = {}) {
+        const bySize = String(model.size || '').match(/(\d+(?:\.\d+)?)\s*b/i);
+        if (bySize) {
+            return this.toFiniteNumber(bySize[1], 0);
+        }
+
+        const byName = String(model.name || '').match(/(\d+(?:\.\d+)?)\s*b\b/i);
+        if (byName) {
+            return this.toFiniteNumber(byName[1], 0);
+        }
+
+        const fileSizeGB = this.toFiniteNumber(model.fileSizeGB, 0);
+        if (fileSizeGB > 0) {
+            return fileSizeGB / 0.65;
+        }
+
+        return 7;
+    }
+
+    estimateBaseMemoryGB(model = {}) {
+        const fileSizeGB = this.toFiniteNumber(model.fileSizeGB, 0);
+        if (fileSizeGB > 0) {
+            return fileSizeGB + this.modelOverheadGB;
+        }
+
+        const paramsB = this.parseParamsB(model);
+        return paramsB * 0.65 + this.modelOverheadGB;
+    }
+
+    estimateKVCacheGB(paramsB, contextTokens) {
+        const ctx = this.toFiniteNumber(contextTokens, this.minContext);
+        return paramsB * this.kvFactorPer4k * (ctx / 4096);
+    }
+
+    normalizeQuantization(rawQuant) {
+        const quant = String(rawQuant || 'Q4_K_M').toUpperCase();
+        if (quant.includes('FP16') || quant.includes('F16')) return 'FP16';
+        if (quant.includes('Q8')) return 'Q8_0';
+        if (quant.includes('Q6')) return 'Q6_K';
+        if (quant.includes('Q5')) return 'Q5_K_M';
+        if (quant.includes('IQ4')) return 'IQ4_XS';
+        if (quant.includes('Q4')) return 'Q4_K_M';
+        if (quant.includes('IQ3')) return 'IQ3_XXS';
+        if (quant.includes('Q3')) return 'Q3_K_M';
+        if (quant.includes('Q2')) return 'Q2_K';
+        return 'Q4_K_M';
+    }
+
+    quantizationMultiplier(quantization) {
+        const table = {
+            FP16: 1.0,
+            Q8_0: 1.5,
+            Q6_K: 1.8,
+            Q5_K_M: 2.0,
+            Q4_K_M: 2.4,
+            IQ4_XS: 2.5,
+            Q3_K_M: 2.9,
+            IQ3_XXS: 3.1,
+            Q2_K: 3.4
+        };
+        return table[this.normalizeQuantization(quantization)] || 2.0;
+    }
+
+    estimateTokensPerSecond(gpu, model, contextTokens) {
+        const paramsB = Math.max(0.5, this.toFiniteNumber(model.paramsB, 7));
+        const speedCoefficient = Math.max(1, this.toFiniteNumber(gpu.speedCoefficient, 60));
+        const quantMult = this.quantizationMultiplier(model.quantization);
+
+        // Larger contexts reduce generation speed in practice.
+        const contextScale = Math.max(0.55, Math.pow(4096 / Math.max(4096, contextTokens), 0.12));
+        return Math.max(1, Math.round((speedCoefficient / paramsB) * quantMult * contextScale));
+    }
+
+    normalizeModels(models = []) {
+        const normalized = models
+            .filter((model) => model && model.name)
+            .map((model) => {
+                const paramsB = this.parseParamsB(model);
+                const baseMemoryGB = this.estimateBaseMemoryGB(model);
+                const fileSizeGB = this.toFiniteNumber(model.fileSizeGB, Math.max(0, baseMemoryGB - this.modelOverheadGB));
+                const quantization = model.quantization || model.details?.quantization_level || 'Q4_K_M';
+                return {
+                    name: model.name,
+                    size: model.size || `${Math.round(paramsB)}B`,
+                    fileSizeGB: Math.round(fileSizeGB * 10) / 10,
+                    paramsB: Math.round(paramsB * 10) / 10,
+                    baseMemoryGB: Math.round(baseMemoryGB * 100) / 100,
+                    quantization
+                };
+            });
+
+        normalized.sort((a, b) => b.baseMemoryGB - a.baseMemoryGB);
+        return normalized;
+    }
+
+    resolveDeviceEnvVar(backend) {
+        if (backend === 'cuda') return 'CUDA_VISIBLE_DEVICES';
+        if (backend === 'rocm') return 'HIP_VISIBLE_DEVICES';
+        return null;
+    }
+
+    resolveHardware(hardware = {}, reserveGB = null) {
+        const summary = hardware.summary || {};
+        const primary = hardware.primary || {};
+        const backend = summary.bestBackend || primary.type || 'cpu';
+        const backendName = summary.backendName || primary.name || 'CPU';
+
+        const backendInfo = primary.info || hardware.backends?.[backend]?.info || {};
+        const rawGpus = Array.isArray(backendInfo.gpus) ? backendInfo.gpus : [];
+
+        let gpus = rawGpus.map((gpu, index) => ({
+            index: this.toFiniteNumber(gpu.index, index),
+            name: String(gpu.name || `GPU ${index}`),
+            memoryGB: Math.max(1, this.toFiniteNumber(gpu.memory?.total, 0)),
+            speedCoefficient: Math.max(1, this.toFiniteNumber(gpu.speedCoefficient, summary.speedCoefficient || 60))
+        }));
+
+        if (!gpus.length && this.toFiniteNumber(summary.totalVRAM, 0) > 0) {
+            gpus = [{
+                index: 0,
+                name: summary.gpuModel || 'GPU 0',
+                memoryGB: Math.max(1, this.toFiniteNumber(summary.totalVRAM, 0)),
+                speedCoefficient: Math.max(1, this.toFiniteNumber(summary.speedCoefficient, 80))
+            }];
+        }
+
+        if (!gpus.length) {
+            gpus = [{
+                index: 0,
+                name: summary.cpuModel || 'CPU',
+                memoryGB: Math.max(4, this.toFiniteNumber(summary.effectiveMemory, this.toFiniteNumber(hardware.memory?.total, 16) * 0.7)),
+                speedCoefficient: Math.max(1, this.toFiniteNumber(summary.speedCoefficient, 25))
+            }];
+        }
+
+        gpus.sort((a, b) => {
+            if (b.speedCoefficient !== a.speedCoefficient) return b.speedCoefficient - a.speedCoefficient;
+            return b.memoryGB - a.memoryGB;
+        });
+
+        const reserve = this.toFiniteNumber(reserveGB, this.defaultReserveGB);
+        const reservePerGPU = reserve / Math.max(1, gpus.length);
+        const usableGPUs = gpus.map((gpu) => ({
+            ...gpu,
+            usableMemoryGB: Math.max(1, Math.round((gpu.memoryGB - reservePerGPU) * 100) / 100)
+        }));
+
+        const totalUsableGB = usableGPUs.reduce((sum, gpu) => sum + gpu.usableMemoryGB, 0);
+
+        return {
+            backend,
+            backendName,
+            reserveGB: Math.round(reserve * 100) / 100,
+            isMultiGPU: usableGPUs.length > 1,
+            deviceEnvVar: this.resolveDeviceEnvVar(backend),
+            gpus: usableGPUs,
+            totalUsableGB: Math.round(totalUsableGB * 100) / 100
+        };
+    }
+
+    makeRisk(utilization, fits, strategy) {
+        if (!fits) {
+            return { level: 'critical', score: 95 };
+        }
+
+        const complexityPenalty = strategy === 'spread' ? 12 : strategy === 'replica' ? 6 : 0;
+        const score = Math.min(100, Math.round((utilization * 72) + complexityPenalty));
+
+        let level = 'low';
+        if (score >= 75) level = 'critical';
+        else if (score >= 55) level = 'high';
+        else if (score >= 35) level = 'medium';
+
+        return { level, score };
+    }
+
+    strategyScore(strategyPlan, objective) {
+        const complexityPenalty = strategyPlan.strategy === 'spread'
+            ? (objective === 'latency' ? 12 : 8)
+            : strategyPlan.strategy === 'replica'
+                ? (objective === 'latency' ? 5 : 3)
+                : 0;
+
+        const riskWeight = objective === 'throughput' ? 0.15 : objective === 'latency' ? 0.28 : 0.22;
+        const infeasiblePenalty = strategyPlan.feasible ? 0 : 220;
+
+        return strategyPlan.estimated_tps - (strategyPlan.risk.score * riskWeight) - complexityPenalty - infeasiblePenalty;
+    }
+
+    simulatePin(model, hardwarePlan, contextTokens, targetConcurrency) {
+        const gpu = hardwarePlan.gpus[0];
+        const kvPerRequestGB = this.estimateKVCacheGB(model.paramsB, contextTokens);
+        const totalMemoryGB = model.baseMemoryGB + (kvPerRequestGB * targetConcurrency);
+        const fits = totalMemoryGB <= gpu.usableMemoryGB;
+        const utilization = totalMemoryGB / Math.max(0.1, gpu.usableMemoryGB);
+
+        const baseTPS = this.estimateTokensPerSecond(gpu, model, contextTokens);
+        const throughputPenalty = fits ? 1 : Math.max(0.25, gpu.usableMemoryGB / Math.max(0.1, totalMemoryGB));
+
+        return {
+            strategy: 'pin',
+            feasible: fits,
+            estimated_tps: Math.max(1, Math.round(baseTPS * throughputPenalty)),
+            memory_per_gpu_gb: Math.round(totalMemoryGB * 100) / 100,
+            total_memory_gb: Math.round(totalMemoryGB * 100) / 100,
+            utilization_percent: Math.round(utilization * 100),
+            gpu_count: 1,
+            placement: [{
+                gpu_index: gpu.index,
+                gpu_name: gpu.name,
+                concurrency: targetConcurrency
+            }],
+            device_env_var: hardwarePlan.deviceEnvVar,
+            visible_devices: hardwarePlan.deviceEnvVar ? String(gpu.index) : null,
+            risk: this.makeRisk(utilization, fits, 'pin'),
+            notes: fits
+                ? ['Single-GPU placement keeps routing simple and minimizes scheduling overhead.']
+                : ['Model+context+concurrency exceeds single-GPU memory.']
+        };
+    }
+
+    simulateReplica(model, hardwarePlan, contextTokens, targetConcurrency) {
+        const gpus = hardwarePlan.gpus;
+        const maxReplicas = Math.min(gpus.length, targetConcurrency);
+        const kvPerRequestGB = this.estimateKVCacheGB(model.paramsB, contextTokens);
+
+        let selectedReplicas = 1;
+        let memoryPerReplicaGB = model.baseMemoryGB + (kvPerRequestGB * targetConcurrency);
+        let feasible = false;
+
+        for (let replicas = maxReplicas; replicas >= 1; replicas -= 1) {
+            const perReplicaConcurrency = Math.ceil(targetConcurrency / replicas);
+            const candidateMemory = model.baseMemoryGB + (kvPerRequestGB * perReplicaConcurrency);
+            const candidateGPUs = gpus.slice(0, replicas);
+            const fitsAll = candidateGPUs.every((gpu) => candidateMemory <= gpu.usableMemoryGB);
+            if (fitsAll) {
+                selectedReplicas = replicas;
+                memoryPerReplicaGB = candidateMemory;
+                feasible = true;
+                break;
+            }
+        }
+
+        const chosenGPUs = gpus.slice(0, selectedReplicas);
+        const baseTPS = chosenGPUs.reduce(
+            (sum, gpu) => sum + this.estimateTokensPerSecond(gpu, model, contextTokens),
+            0
+        );
+        const replicaEfficiency = Math.max(0.8, 0.95 - ((selectedReplicas - 1) * 0.02));
+        const estimatedTPS = Math.max(1, Math.round(baseTPS * replicaEfficiency));
+
+        const maxUtilization = chosenGPUs.reduce((max, gpu) => {
+            const util = memoryPerReplicaGB / Math.max(0.1, gpu.usableMemoryGB);
+            return Math.max(max, util);
+        }, 0);
+
+        const placement = [];
+        let remaining = targetConcurrency;
+        for (let i = 0; i < chosenGPUs.length; i += 1) {
+            const gpu = chosenGPUs[i];
+            const slotsLeft = chosenGPUs.length - i;
+            const assigned = Math.ceil(remaining / slotsLeft);
+            placement.push({
+                gpu_index: gpu.index,
+                gpu_name: gpu.name,
+                concurrency: assigned
+            });
+            remaining -= assigned;
+        }
+
+        const visibleDevices = chosenGPUs.map((gpu) => gpu.index).join(',');
+
+        return {
+            strategy: 'replica',
+            feasible,
+            estimated_tps: estimatedTPS,
+            memory_per_gpu_gb: Math.round(memoryPerReplicaGB * 100) / 100,
+            total_memory_gb: Math.round(memoryPerReplicaGB * selectedReplicas * 100) / 100,
+            utilization_percent: Math.round(maxUtilization * 100),
+            gpu_count: selectedReplicas,
+            placement,
+            device_env_var: hardwarePlan.deviceEnvVar,
+            visible_devices: hardwarePlan.deviceEnvVar ? visibleDevices : null,
+            risk: this.makeRisk(maxUtilization, feasible, 'replica'),
+            notes: feasible
+                ? ['Replica strategy scales throughput by running independent model copies per GPU.']
+                : ['No replica count can satisfy per-GPU memory constraints at requested settings.']
+        };
+    }
+
+    simulateSpread(model, hardwarePlan, contextTokens, targetConcurrency) {
+        const gpus = hardwarePlan.gpus;
+        if (gpus.length < 2) {
+            return {
+                strategy: 'spread',
+                feasible: false,
+                estimated_tps: 0,
+                memory_per_gpu_gb: 0,
+                total_memory_gb: 0,
+                utilization_percent: 0,
+                gpu_count: 1,
+                placement: [],
+                device_env_var: hardwarePlan.deviceEnvVar,
+                visible_devices: null,
+                risk: { level: 'critical', score: 100 },
+                notes: ['Tensor/spread placement requires at least two GPUs.']
+            };
+        }
+
+        const kvPerRequestGB = this.estimateKVCacheGB(model.paramsB, contextTokens);
+        const totalMemoryGB = model.baseMemoryGB + (kvPerRequestGB * targetConcurrency);
+
+        let selectedGPUCount = 2;
+        let memoryPerGPU = totalMemoryGB / selectedGPUCount + this.spreadOverheadGB;
+        let feasible = false;
+
+        for (let shardCount = 2; shardCount <= gpus.length; shardCount += 1) {
+            const candidatePerGPU = totalMemoryGB / shardCount + this.spreadOverheadGB;
+            const shardGPUs = gpus.slice(0, shardCount);
+            const fits = shardGPUs.every((gpu) => candidatePerGPU <= gpu.usableMemoryGB);
+            if (fits) {
+                selectedGPUCount = shardCount;
+                memoryPerGPU = candidatePerGPU;
+                feasible = true;
+                break;
+            }
+        }
+
+        if (!feasible) {
+            selectedGPUCount = gpus.length;
+            memoryPerGPU = totalMemoryGB / selectedGPUCount + this.spreadOverheadGB;
+        }
+
+        const chosenGPUs = gpus.slice(0, selectedGPUCount);
+        const primaryTPS = this.estimateTokensPerSecond(chosenGPUs[0], model, contextTokens);
+        const scaleFactor = 1 + (0.55 * (selectedGPUCount - 1));
+        const interconnectPenalty = Math.max(0.65, 1 - (0.07 * (selectedGPUCount - 1)));
+        const estimatedTPS = Math.max(1, Math.round(primaryTPS * scaleFactor * interconnectPenalty));
+
+        const minUsableMemory = chosenGPUs.reduce((min, gpu) => Math.min(min, gpu.usableMemoryGB), Infinity);
+        const utilization = memoryPerGPU / Math.max(0.1, minUsableMemory);
+        const visibleDevices = chosenGPUs.map((gpu) => gpu.index).join(',');
+
+        return {
+            strategy: 'spread',
+            feasible,
+            estimated_tps: estimatedTPS,
+            memory_per_gpu_gb: Math.round(memoryPerGPU * 100) / 100,
+            total_memory_gb: Math.round(memoryPerGPU * selectedGPUCount * 100) / 100,
+            utilization_percent: Math.round(utilization * 100),
+            gpu_count: selectedGPUCount,
+            placement: chosenGPUs.map((gpu) => ({
+                gpu_index: gpu.index,
+                gpu_name: gpu.name,
+                role: 'shard'
+            })),
+            device_env_var: hardwarePlan.deviceEnvVar,
+            visible_devices: hardwarePlan.deviceEnvVar ? visibleDevices : null,
+            risk: this.makeRisk(utilization, feasible, 'spread'),
+            notes: feasible
+                ? ['Spread strategy shards one model across multiple GPUs and favors capacity over simplicity.']
+                : ['Even full spread cannot fit requested settings within per-GPU memory limits.']
+        };
+    }
+
+    pickRecommendedStrategy(strategies, objective) {
+        const scored = strategies.map((plan) => ({
+            ...plan,
+            objective_score: Math.round(this.strategyScore(plan, objective) * 100) / 100
+        }));
+
+        scored.sort((a, b) => b.objective_score - a.objective_score);
+        return scored[0];
+    }
+
+    buildNotes(hardwarePlan, modelPlans) {
+        const notes = [];
+        if (!hardwarePlan.isMultiGPU) {
+            notes.push('Detected single-GPU (or CPU-only) runtime; replica/spread strategies may not be feasible.');
+        }
+
+        const infeasibleCount = modelPlans.filter((model) => !model.recommended?.feasible).length;
+        if (infeasibleCount > 0) {
+            notes.push(`${infeasibleCount} model(s) exceed safe memory at requested ctx/concurrency. Lower --ctx or --concurrency.`);
+        }
+
+        if (!hardwarePlan.deviceEnvVar) {
+            notes.push('Backend does not expose a standard GPU visibility env var; use strategy output as conceptual placement guidance.');
+        }
+
+        return notes;
+    }
+
+    plan({
+        hardware,
+        models,
+        targetContext = 8192,
+        targetConcurrency = 2,
+        objective = 'balanced',
+        reserveGB = null
+    }) {
+        const normalizedModels = this.normalizeModels(models);
+        if (!normalizedModels.length) {
+            throw new Error('At least one model is required for GPU planning.');
+        }
+
+        const normalizedObjective = this.normalizeObjective(objective);
+        const contextTokens = this.clamp(
+            Math.round(this.toFiniteNumber(targetContext, 8192)),
+            512,
+            131072
+        );
+        const concurrency = this.clamp(
+            Math.round(this.toFiniteNumber(targetConcurrency, 2)),
+            1,
+            64
+        );
+
+        const hardwarePlan = this.resolveHardware(hardware, reserveGB);
+
+        const modelPlans = normalizedModels.map((model) => {
+            const strategies = [
+                this.simulatePin(model, hardwarePlan, contextTokens, concurrency),
+                this.simulateReplica(model, hardwarePlan, contextTokens, concurrency),
+                this.simulateSpread(model, hardwarePlan, contextTokens, concurrency)
+            ];
+
+            const recommended = this.pickRecommendedStrategy(strategies, normalizedObjective);
+
+            return {
+                name: model.name,
+                size: model.size,
+                file_size_gb: model.fileSizeGB,
+                params_b: model.paramsB,
+                quantization: this.normalizeQuantization(model.quantization),
+                estimated_base_memory_gb: model.baseMemoryGB,
+                recommended,
+                strategies
+            };
+        });
+
+        return {
+            objective: normalizedObjective,
+            inputs: {
+                target_context: contextTokens,
+                target_concurrency: concurrency
+            },
+            hardware: {
+                backend: hardwarePlan.backend,
+                backend_name: hardwarePlan.backendName,
+                is_multi_gpu: hardwarePlan.isMultiGPU,
+                gpu_count: hardwarePlan.gpus.length,
+                reserve_gb: hardwarePlan.reserveGB,
+                total_usable_memory_gb: hardwarePlan.totalUsableGB,
+                device_env_var: hardwarePlan.deviceEnvVar,
+                gpus: hardwarePlan.gpus.map((gpu) => ({
+                    index: gpu.index,
+                    name: gpu.name,
+                    memory_gb: gpu.memoryGB,
+                    usable_memory_gb: gpu.usableMemoryGB,
+                    speed_coefficient: gpu.speedCoefficient
+                }))
+            },
+            models: modelPlans,
+            notes: this.buildNotes(hardwarePlan, modelPlans)
+        };
+    }
+}
+
+module.exports = OllamaGPUPlacementPlanner;