llm-checker 3.3.0 → 3.4.1

package/README.md

@@ -133,9 +133,22 @@ llm-checker ai-run --calibrated --category coding --prompt "Refactor this functi
 
 LLM Checker is published in all primary channels:
 
-- npm (latest): [`llm-checker@latest`](https://www.npmjs.com/package/llm-checker)
+- npm (latest, recommended): [`llm-checker@latest`](https://www.npmjs.com/package/llm-checker)
 - GitHub Releases: [Release history](https://github.com/Pavelevich/llm-checker/releases)
-- GitHub Packages: [`@pavelevich/llm-checker`](https://github.com/users/Pavelevich/packages/npm/package/llm-checker)
+- GitHub Packages (legacy mirror, may lag): [`@pavelevich/llm-checker`](https://github.com/users/Pavelevich/packages/npm/package/llm-checker)
+
+### Important: Use npm for Latest Builds
+
+If you need the newest release, install from npm (`llm-checker`), not the scoped GitHub Packages mirror.
+
+If you installed `@pavelevich/llm-checker` and version looks old:
+
+```bash
+npm uninstall -g @pavelevich/llm-checker
+npm install -g llm-checker@latest
+hash -r
+llm-checker --version
+```
 
 ### v3.3.0 Highlights
 
@@ -148,7 +161,9 @@ LLM Checker is published in all primary channels:
 - Hardened Jetson CUDA detection to avoid false CPU-only fallback.
 - Documentation reorganized under `docs/` with clearer onboarding paths.
 
-### Optional: Install from GitHub Packages
+### Optional (Legacy): Install from GitHub Packages
+
+Use this only if you explicitly need GitHub Packages. It may not match npm latest.
 
 ```bash
 # 1) Configure registry + token (PAT with read:packages)
@@ -261,6 +276,11 @@ 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_plan` | Build a capacity plan for local models with recommended context/parallel/memory settings |
+| `ollama_plan_env` | Return ready-to-paste `export ...` env vars from the recommended or fallback plan profile |
+| `policy_validate` | Validate a policy file against the v1 schema and return structured validation output |
+| `audit_export` | Run policy compliance export (`json`/`csv`/`sarif`/`all`) for `check` or `recommend` flows |
+| `calibrate` | Generate calibration artifacts from a prompt suite with typed MCP inputs |
 
 **Ollama Management:**
 
@@ -281,6 +301,8 @@ Once connected, Claude can use these tools:
 | `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 |
+| `cli_help` | List all allowlisted CLI commands exposed through MCP |
+| `cli_exec` | Execute any allowlisted `llm-checker` CLI command with custom args (policy/audit/calibrate/sync/ai-run/etc.) |
 
 ### Example Prompts
 
@@ -309,6 +331,7 @@ Claude will automatically call the right tools and give you actionable results.
 | `recommend` | Intelligent recommendations by category (coding, reasoning, multimodal, etc.) |
 | `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 |
 
 ### Advanced Commands (require `sql.js`)
 

package/bin/enhanced_cli.js

@@ -591,6 +591,80 @@ async function checkOllamaAndExit() {
     }
 }
 
+function parsePositiveIntegerOption(rawValue, optionName) {
+    const parsed = Number(rawValue);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`Invalid ${optionName}: ${rawValue}`);
+    }
+    return Math.round(parsed);
+}
+
+function parseNonNegativeNumberOption(rawValue, optionName) {
+    const parsed = Number(rawValue);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error(`Invalid ${optionName}: ${rawValue}`);
+    }
+    return parsed;
+}
+
+function selectModelsForPlan(installedModels, requestedModels = []) {
+    const requested = Array.isArray(requestedModels)
+        ? requestedModels.map((model) => String(model || '').trim()).filter(Boolean)
+        : [];
+
+    if (!requested.length) {
+        return {
+            selected: installedModels.slice(),
+            missing: []
+        };
+    }
+
+    const selected = [];
+    const missing = [];
+    const seen = new Set();
+
+    for (const request of requested) {
+        const normalized = request.toLowerCase();
+
+        let match = installedModels.find(
+            (model) => String(model.name || '').toLowerCase() === normalized
+        );
+
+        if (!match) {
+            match = installedModels.find((model) =>
+                String(model.name || '').toLowerCase().startsWith(`${normalized}:`)
+            );
+        }
+
+        if (!match) {
+            match = installedModels.find(
+                (model) => String(model.family || '').toLowerCase() === normalized
+            );
+        }
+
+        if (!match) {
+            match = installedModels.find((model) =>
+                String(model.name || '').toLowerCase().includes(normalized)
+            );
+        }
+
+        if (!match) {
+            missing.push(request);
+            continue;
+        }
+
+        if (!seen.has(match.name)) {
+            selected.push(match);
+            seen.add(match.name);
+        }
+    }
+
+    return {
+        selected,
+        missing
+    };
+}
+
 function getStatusIcon(model, ollamaModels) {
     const ollamaModel = ollamaModels?.find(om => om.matchedModel?.name === model.name);
 
@@ -3042,6 +3116,145 @@ program
         }
     });
 
+program
+    .command('ollama-plan')
+    .description('Plan safe Ollama runtime settings 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 for OS and background workloads', '2')
+    .option('--json', 'Output plan as JSON')
+    .action(async (options) => {
+        const spinner = options.json ? null : ora('Building Ollama capacity 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 OllamaCapacityPlanner = require('../src/ollama/capacity-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 OllamaCapacityPlanner();
+
+            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('Capacity plan generated');
+
+            console.log('\n' + chalk.bgBlue.white.bold(' OLLAMA CAPACITY PLAN '));
+            console.log(
+                chalk.blue('Hardware:'),
+                `${plan.hardware.backendName} (${plan.hardware.backend})`
+            );
+            console.log(
+                chalk.blue('Memory budget:'),
+                `${plan.memory.budgetGB}GB usable (reserve ${plan.hardware.reserveGB}GB)`
+            );
+
+            if (missing.length > 0) {
+                console.log(
+                    chalk.yellow('Missing model filters:'),
+                    missing.join(', ')
+                );
+            }
+
+            console.log(chalk.blue.bold('\nSelected models:'));
+            for (const model of plan.models) {
+                console.log(
+                    `  - ${model.name} (${model.size}, ~${model.estimatedBaseMemoryGB}GB base)`
+                );
+            }
+
+            console.log(chalk.blue.bold('\nRecommended envelope:'));
+            console.log(
+                `  Context: ${plan.envelope.context.recommended} (requested ${plan.envelope.context.requested})`
+            );
+            console.log(
+                `  Parallel: ${plan.envelope.parallel.recommended} (requested ${plan.envelope.parallel.requested})`
+            );
+            console.log(
+                `  Loaded models: ${plan.envelope.loaded_models.recommended} (requested ${plan.envelope.loaded_models.requested})`
+            );
+            console.log(
+                `  Estimated memory: ${plan.memory.recommendedEstimatedGB}GB / ${plan.memory.budgetGB}GB (${plan.memory.utilizationPercent}%)`
+            );
+            console.log(`  Risk: ${plan.risk.level.toUpperCase()} (${plan.risk.score}/100)`);
+
+            if (plan.notes.length > 0) {
+                console.log(chalk.blue.bold('\nNotes:'));
+                for (const note of plan.notes) {
+                    console.log(`  - ${note}`);
+                }
+            }
+
+            console.log(chalk.blue.bold('\nRecommended env vars:'));
+            for (const [key, value] of Object.entries(plan.shell.env)) {
+                console.log(`  export ${key}=${value}`);
+            }
+
+            console.log(chalk.blue.bold('\nFallback profile:'));
+            console.log(
+                `  OLLAMA_NUM_CTX=${plan.fallback.num_ctx} OLLAMA_NUM_PARALLEL=${plan.fallback.num_parallel} OLLAMA_MAX_LOADED_MODELS=${plan.fallback.max_loaded_models}`
+            );
+            console.log('');
+        } catch (error) {
+            if (spinner) spinner.fail('Failed to build capacity 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')
@@ -3942,8 +4155,8 @@ program
                 }
 
                 if (backend === 'cuda' && info.info) {
-                    console.log(`  Driver: ${info.info.driver}`);
-                    console.log(`  CUDA: ${info.info.cuda}`);
+                    console.log(`  Driver: ${info.info.driver || 'unknown'}`);
+                    console.log(`  CUDA: ${info.info.cuda || 'unknown'}`);
                     console.log(`  Total VRAM: ${info.info.totalVRAM}GB`);
                     for (const gpu of info.info.gpus) {
                         console.log(`  ${gpu.name}: ${gpu.memory.total}GB`);

package/bin/mcp-server.mjs

@@ -101,13 +101,89 @@ function nsToSec(ns) {
   return (ns / 1e9).toFixed(2);
 }
 
+function tryParseJSON(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function formatExportBlock(envObject) {
+  if (!envObject || typeof envObject !== "object") return "";
+  const entries = Object.entries(envObject).filter(([, value]) => value !== undefined && value !== null);
+  if (entries.length === 0) return "";
+  return entries
+    .map(([key, value]) => `export ${key}="${String(value)}"`)
+    .join("\n");
+}
+
+function summarizeOllamaPlan(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  const plan = payload.plan;
+  if (!plan || typeof plan !== "object") return null;
+
+  const selectedModels = Array.isArray(plan.models)
+    ? plan.models.map((model) => model?.name).filter(Boolean)
+    : [];
+  const hardware = plan.hardware || {};
+  const memory = plan.memory || {};
+  const recommendation = plan.recommendation || {};
+  const risk = plan.risk || {};
+
+  const lines = [
+    "OLLAMA CAPACITY PLAN",
+    `Hardware: ${hardware.backendName || hardware.backend || "unknown"}`,
+    `Models: ${selectedModels.length > 0 ? selectedModels.join(", ") : "none selected"}`,
+    "",
+    "Recommended envelope:",
+    `  Context: ${plan.envelope?.context?.recommended ?? "?"}`,
+    `  Parallel: ${plan.envelope?.parallel?.recommended ?? "?"}`,
+    `  Loaded models: ${plan.envelope?.loaded_models?.recommended ?? "?"}`,
+    `  Estimated memory: ${memory.recommendedEstimatedGB ?? "?"}GB / ${memory.budgetGB ?? "?"}GB (${memory.utilizationPercent ?? "?"}%)`,
+    `  Risk: ${(risk.level || "unknown").toUpperCase()} (${risk.score ?? "?"}/100)`,
+  ];
+
+  if (recommendation && Object.keys(recommendation).length > 0) {
+    lines.push("");
+    lines.push("Recommended env vars:");
+    if (recommendation.num_ctx !== undefined) lines.push(`  export OLLAMA_NUM_CTX="${recommendation.num_ctx}"`);
+    if (recommendation.num_parallel !== undefined) lines.push(`  export OLLAMA_NUM_PARALLEL="${recommendation.num_parallel}"`);
+    if (recommendation.max_loaded_models !== undefined) lines.push(`  export OLLAMA_MAX_LOADED_MODELS="${recommendation.max_loaded_models}"`);
+    if (recommendation.max_queue !== undefined) lines.push(`  export OLLAMA_MAX_QUEUE="${recommendation.max_queue}"`);
+    if (recommendation.keep_alive !== undefined) lines.push(`  export OLLAMA_KEEP_ALIVE="${recommendation.keep_alive}"`);
+    if (recommendation.flash_attention !== undefined) lines.push(`  export OLLAMA_FLASH_ATTENTION="${recommendation.flash_attention}"`);
+  }
+
+  return lines.join("\n");
+}
+
+const ALLOWED_CLI_COMMANDS = new Set([
+  "policy",
+  "audit",
+  "calibrate",
+  "check",
+  "ollama",
+  "installed",
+  "ollama-plan",
+  "recommend",
+  "list-models",
+  "ai-check",
+  "ai-run",
+  "demo",
+  "sync",
+  "search",
+  "smart-recommend",
+  "hw-detect",
+]);
+
 // ============================================================================
 // MCP SERVER
 // ============================================================================
 
 const server = new McpServer({
   name: "llm-checker",
-  version: "3.2.0",
+  version: "3.4.0",
 });
 
 // ============================================================================
@@ -198,6 +274,352 @@ server.tool(
   }
 );
 
+server.tool(
+  "ollama_plan",
+  "Build an Ollama capacity plan for selected local models and return recommended context/parallel/memory settings",
+  {
+    models: z
+      .array(z.string())
+      .optional()
+      .describe("Optional list of model tags/families to include (default: all local models)"),
+    ctx: z.number().int().positive().optional().describe("Target context window in tokens"),
+    concurrency: z.number().int().positive().optional().describe("Target parallel request count"),
+    objective: z
+      .enum(["latency", "balanced", "throughput"])
+      .optional()
+      .describe("Optimization objective"),
+    reserve_gb: z.number().min(0).optional().describe("Memory reserve in GB for OS/background workloads"),
+  },
+  async ({ models, ctx, concurrency, objective, reserve_gb }) => {
+    const args = ["ollama-plan", "--json"];
+    if (Array.isArray(models) && models.length > 0) args.push("--models", ...models);
+    if (ctx !== undefined) args.push("--ctx", String(ctx));
+    if (concurrency !== undefined) args.push("--concurrency", String(concurrency));
+    if (objective) args.push("--objective", objective);
+    if (reserve_gb !== undefined) args.push("--reserve-gb", String(reserve_gb));
+
+    const result = await run(args, 180000);
+    const payload = tryParseJSON(result);
+
+    if (!payload) {
+      return {
+        content: [{ type: "text", text: result }],
+      };
+    }
+
+    const summary = summarizeOllamaPlan(payload);
+    const output = summary
+      ? `${summary}\n\nRAW JSON:\n${JSON.stringify(payload, null, 2)}`
+      : JSON.stringify(payload, null, 2);
+
+    return {
+      content: [{ type: "text", text: output }],
+    };
+  }
+);
+
+server.tool(
+  "ollama_plan_env",
+  "Return shell export commands from an Ollama capacity plan (recommended or fallback profile)",
+  {
+    profile: z
+      .enum(["recommended", "fallback"])
+      .optional()
+      .describe("Which profile to return (default: recommended)"),
+    models: z
+      .array(z.string())
+      .optional()
+      .describe("Optional list of model tags/families to include (default: all local models)"),
+    ctx: z.number().int().positive().optional().describe("Target context window in tokens"),
+    concurrency: z.number().int().positive().optional().describe("Target parallel request count"),
+    objective: z
+      .enum(["latency", "balanced", "throughput"])
+      .optional()
+      .describe("Optimization objective"),
+    reserve_gb: z.number().min(0).optional().describe("Memory reserve in GB for OS/background workloads"),
+  },
+  async ({ profile, models, ctx, concurrency, objective, reserve_gb }) => {
+    const args = ["ollama-plan", "--json"];
+    if (Array.isArray(models) && models.length > 0) args.push("--models", ...models);
+    if (ctx !== undefined) args.push("--ctx", String(ctx));
+    if (concurrency !== undefined) args.push("--concurrency", String(concurrency));
+    if (objective) args.push("--objective", objective);
+    if (reserve_gb !== undefined) args.push("--reserve-gb", String(reserve_gb));
+
+    const result = await run(args, 180000);
+    const payload = tryParseJSON(result);
+    if (!payload?.plan) {
+      return {
+        content: [{ type: "text", text: `Failed to parse ollama-plan output:\n${result}` }],
+        isError: true,
+      };
+    }
+
+    const selectedProfile = profile || "recommended";
+    const plan = payload.plan;
+    let envValues = null;
+
+    if (selectedProfile === "fallback") {
+      const fallback = plan.fallback || {};
+      envValues = {
+        OLLAMA_NUM_CTX: fallback.num_ctx,
+        OLLAMA_NUM_PARALLEL: fallback.num_parallel,
+        OLLAMA_MAX_LOADED_MODELS: fallback.max_loaded_models,
+      };
+    } else {
+      envValues = plan.shell?.env || null;
+      if (!envValues) {
+        const recommendation = plan.recommendation || {};
+        envValues = {
+          OLLAMA_NUM_CTX: recommendation.num_ctx,
+          OLLAMA_NUM_PARALLEL: recommendation.num_parallel,
+          OLLAMA_MAX_LOADED_MODELS: recommendation.max_loaded_models,
+          OLLAMA_MAX_QUEUE: recommendation.max_queue,
+          OLLAMA_KEEP_ALIVE: recommendation.keep_alive,
+          OLLAMA_FLASH_ATTENTION: recommendation.flash_attention,
+        };
+      }
+    }
+
+    const exports = formatExportBlock(envValues);
+    if (!exports) {
+      return {
+        content: [{ type: "text", text: "No environment values available for this plan/profile." }],
+        isError: true,
+      };
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: [`PROFILE: ${selectedProfile.toUpperCase()}`, "", exports].join("\n"),
+        },
+      ],
+    };
+  }
+);
+
+server.tool(
+  "cli_help",
+  "List all llm-checker CLI commands exposed via cli_exec",
+  {},
+  async () => {
+    const commands = [...ALLOWED_CLI_COMMANDS].sort();
+    const lines = [
+      "Available commands for cli_exec:",
+      ...commands.map((command) => `  - ${command}`),
+      "",
+      "Examples:",
+      '  cli_exec command="ollama-plan" args=["--json"]',
+      '  cli_exec command="policy" args=["validate","--file","policy.yaml","--json"]',
+      '  cli_exec command="search" args=["qwen","--use-case","coding","--limit","5"]',
+    ];
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+);
+
+server.tool(
+  "cli_exec",
+  "Execute any supported llm-checker CLI command (allowlisted) with custom arguments",
+  {
+    command: z.string().describe("Top-level command (use cli_help to list allowed commands)"),
+    args: z
+      .array(z.string())
+      .optional()
+      .describe("Additional CLI args, exactly as used in terminal (without shell quoting)"),
+    timeout_ms: z.number().int().min(1000).max(600000).optional().describe("Execution timeout in milliseconds"),
+  },
+  async ({ command, args, timeout_ms }) => {
+    const trimmedCommand = String(command || "").trim();
+    if (!ALLOWED_CLI_COMMANDS.has(trimmedCommand)) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Unsupported command "${trimmedCommand}". Use cli_help to list allowed commands.`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    const safeArgs = Array.isArray(args) ? args : [];
+    if (safeArgs.length > 100) {
+      return {
+        content: [{ type: "text", text: "Too many arguments. Limit is 100." }],
+        isError: true,
+      };
+    }
+
+    const result = await run([trimmedCommand, ...safeArgs], timeout_ms || 180000);
+    return { content: [{ type: "text", text: result }] };
+  }
+);
+
+server.tool(
+  "policy_validate",
+  "Validate a policy file against the v1 schema and return structured validation output",
+  {
+    file: z.string().optional().describe("Policy file path (default: policy.yaml)"),
+  },
+  async ({ file }) => {
+    const args = ["policy", "validate", "--json"];
+    if (file) args.push("--file", file);
+
+    const result = await run(args, 120000);
+    const payload = tryParseJSON(result);
+    if (!payload) {
+      return {
+        content: [{ type: "text", text: result }],
+      };
+    }
+
+    const status = payload.valid ? "VALID" : "INVALID";
+    const header = [
+      `POLICY VALIDATION: ${status}`,
+      `File: ${payload.file || file || "policy.yaml"}`,
+      `Errors: ${payload.errorCount ?? (Array.isArray(payload.errors) ? payload.errors.length : 0)}`,
+    ].join("\n");
+
+    return {
+      content: [{ type: "text", text: `${header}\n\n${JSON.stringify(payload, null, 2)}` }],
+      isError: !payload.valid,
+    };
+  }
+);
+
+server.tool(
+  "audit_export",
+  "Run policy compliance audit export (json/csv/sarif/all) for check/recommend flows",
+  {
+    policy: z.string().describe("Policy file path"),
+    command: z
+      .enum(["check", "recommend"])
+      .optional()
+      .describe("Evaluation source (default: check)"),
+    format: z
+      .enum(["json", "csv", "sarif", "all"])
+      .optional()
+      .describe("Export format (default: json)"),
+    out: z.string().optional().describe("Output file path (single format only)"),
+    out_dir: z.string().optional().describe("Output directory when --out is omitted"),
+    use_case: z.string().optional().describe("Use case when command=check"),
+    category: z.string().optional().describe("Category hint when command=recommend"),
+    optimize: z
+      .enum(["balanced", "speed", "quality", "context", "coding"])
+      .optional()
+      .describe("Optimization profile when command=recommend"),
+    runtime: z
+      .enum(["ollama", "vllm", "mlx"])
+      .optional()
+      .describe("Runtime backend for check mode"),
+    include_cloud: z.boolean().optional().describe("Include cloud models in check-mode analysis"),
+    max_size: z.string().optional().describe('Maximum model size for check mode (example: "24B" or "12GB")'),
+    min_size: z.string().optional().describe('Minimum model size for check mode (example: "3B" or "2GB")'),
+    limit: z.number().int().positive().optional().describe("Model analysis limit for check mode"),
+    verbose: z.boolean().optional().describe("Enable verbose progress (default: true)"),
+  },
+  async ({
+    policy,
+    command,
+    format,
+    out,
+    out_dir,
+    use_case,
+    category,
+    optimize,
+    runtime,
+    include_cloud,
+    max_size,
+    min_size,
+    limit,
+    verbose,
+  }) => {
+    const args = ["audit", "export", "--policy", policy];
+    if (command) args.push("--command", command);
+    if (format) args.push("--format", format);
+    if (out) args.push("--out", out);
+    if (out_dir) args.push("--out-dir", out_dir);
+    if (use_case) args.push("--use-case", use_case);
+    if (category) args.push("--category", category);
+    if (optimize) args.push("--optimize", optimize);
+    if (runtime) args.push("--runtime", runtime);
+    if (include_cloud) args.push("--include-cloud");
+    if (max_size) args.push("--max-size", max_size);
+    if (min_size) args.push("--min-size", min_size);
+    if (limit !== undefined) args.push("--limit", String(limit));
+    if (verbose === false) args.push("--no-verbose");
+
+    const result = await run(args, 300000);
+    const hadFailure =
+      /audit export failed:/i.test(result) ||
+      /blocking violations detected/i.test(result) ||
+      /enforcement result:\s*blocking/i.test(result);
+    return {
+      content: [{ type: "text", text: result }],
+      isError: hadFailure,
+    };
+  }
+);
+
+server.tool(
+  "calibrate",
+  "Generate calibration artifacts from a JSONL prompt suite (dry-run, contract-only, or full benchmark mode)",
+  {
+    suite: z.string().describe("Prompt suite path in JSONL format"),
+    models: z.array(z.string()).describe("Model identifiers to include"),
+    output: z.string().describe("Calibration result output path (.json/.yaml/.yml)"),
+    runtime: z
+      .enum(["ollama", "vllm", "mlx"])
+      .optional()
+      .describe("Inference runtime backend"),
+    mode: z
+      .enum(["dry-run", "contract-only", "full"])
+      .optional()
+      .describe("Execution mode"),
+    objective: z
+      .enum(["speed", "quality", "balanced"])
+      .optional()
+      .describe("Calibration objective"),
+    policy_out: z.string().optional().describe("Optional calibration policy output path"),
+    warmup: z.number().int().positive().optional().describe("Warmup runs per prompt in full mode"),
+    iterations: z.number().int().positive().optional().describe("Measured iterations per prompt in full mode"),
+    timeout_ms: z.number().int().positive().optional().describe("Per-prompt timeout in full mode (ms)"),
+    dry_run: z.boolean().optional().describe("Shortcut flag for dry-run mode"),
+  },
+  async ({
+    suite,
+    models,
+    output,
+    runtime,
+    mode,
+    objective,
+    policy_out,
+    warmup,
+    iterations,
+    timeout_ms,
+    dry_run,
+  }) => {
+    const args = ["calibrate", "--suite", suite, "--models", ...models, "--output", output];
+    if (runtime) args.push("--runtime", runtime);
+    if (mode) args.push("--mode", mode);
+    if (objective) args.push("--objective", objective);
+    if (policy_out) args.push("--policy-out", policy_out);
+    if (warmup !== undefined) args.push("--warmup", String(warmup));
+    if (iterations !== undefined) args.push("--iterations", String(iterations));
+    if (timeout_ms !== undefined) args.push("--timeout-ms", String(timeout_ms));
+    if (dry_run) args.push("--dry-run");
+
+    const result = await run(args, 600000);
+    const hadFailure = /calibration failed:/i.test(result);
+    return {
+      content: [{ type: "text", text: result }],
+      isError: hadFailure,
+    };
+  }
+);
+
 // ============================================================================
 // OLLAMA MANAGEMENT TOOLS
 // ============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-checker",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "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/hardware/backends/cuda-detector.js

@@ -322,7 +322,7 @@ class CUDADetector {
         const modelRaw = this.readJetsonModel();
         const model = this.normalizeJetsonModel(modelRaw);
         const cudaVersion = this.detectJetsonCudaVersion();
-        const driverVersion = this.detectJetsonDriverVersion();
+        const driverVersion = this.detectJetsonDriverVersion() || 'unknown';
         const totalSystemGB = Math.max(1, Math.round(os.totalmem() / (1024 ** 3)));
         const sharedGpuMemoryGB = Math.max(1, Math.round(totalSystemGB * 0.85));
         const capabilities = this.getJetsonCapabilities(modelRaw || model);
@@ -423,11 +423,26 @@ class CUDADetector {
     }
 
     detectJetsonDriverVersion() {
-        const versionInfo = this.readFileIfExists('/proc/driver/nvidia/version');
-        if (!versionInfo) return null;
+        const driverSources = [
+            '/proc/driver/nvidia/version',
+            '/sys/module/nvidia/version'
+        ];
+
+        for (const source of driverSources) {
+            const versionInfo = this.readFileIfExists(source);
+            if (!versionInfo) continue;
+
+            const kernelMatch = versionInfo.match(/Kernel Module(?:\s+for\s+\w+)?\s+([0-9]+(?:\.[0-9]+){1,3})/i);
+            if (kernelMatch) return kernelMatch[1];
+
+            const nvrmMatch = versionInfo.match(/NVRM version:\s*.*?([0-9]+(?:\.[0-9]+){1,3})/i);
+            if (nvrmMatch) return nvrmMatch[1];
 
-        const match = versionInfo.match(/Kernel Module\s+([0-9.]+)/i);
-        return match ? match[1] : null;
+            const genericMatch = versionInfo.match(/\b([0-9]+(?:\.[0-9]+){1,3})\b/);
+            if (genericMatch) return genericMatch[1];
+        }
+
+        return null;
     }
 
     getJetsonCapabilities(model) {
@@ -734,10 +749,13 @@ class CUDADetector {
         const primary = this.getPrimaryGPU();
         const gpuName = primary.name.toLowerCase()
             .replace(/nvidia|geforce|quadro|tesla/gi, '')
-            .replace(/\s+/g, '-')
-            .trim();
+            .replace(/[^a-z0-9]+/gi, '-')
+            .replace(/-+/g, '-')
+            .replace(/^-|-$/g, '');
+        const normalizedGpuName = gpuName || 'gpu';
+        const normalizedVRAM = Number.isFinite(info.totalVRAM) ? Math.max(0, Math.round(info.totalVRAM)) : 0;
 
-        return `cuda-${gpuName}-${info.totalVRAM}gb${info.isMultiGPU ? '-x' + info.gpus.length : ''}`;
+        return `cuda-${normalizedGpuName}-${normalizedVRAM}gb${info.isMultiGPU ? '-x' + info.gpus.length : ''}`;
     }
 
     /**

package/src/ollama/capacity-planner.js

@@ -0,0 +1,399 @@
+class OllamaCapacityPlanner {
+    constructor(options = {}) {
+        this.minContext = options.minContext || 2048;
+        this.maxParallelCap = options.maxParallelCap || 8;
+        this.defaultReserveGB = options.defaultReserveGB || 2;
+        this.kvFactorPer4k = options.kvFactorPer4k || 0.08; // GB per 1B params at 4k ctx
+        this.modelOverheadGB = options.modelOverheadGB || 0.7;
+    }
+
+    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 === 'throughput' || normalized === 'balanced') {
+            return normalized;
+        }
+        return 'balanced';
+    }
+
+    objectiveProfile(objective) {
+        if (objective === 'latency') {
+            return {
+                parallelCap: 2,
+                loadedCap: 1,
+                keepAlive: '30m'
+            };
+        }
+
+        if (objective === 'throughput') {
+            return {
+                parallelCap: 6,
+                loadedCap: 3,
+                keepAlive: '10m'
+            };
+        }
+
+        return {
+            parallelCap: 3,
+            loadedCap: 2,
+            keepAlive: '15m'
+        };
+    }
+
+    estimateParamsB(model = {}) {
+        const sizeMatch = String(model.size || '').match(/(\d+(?:\.\d+)?)\s*b/i);
+        if (sizeMatch) {
+            return this.toFiniteNumber(sizeMatch[1], 0);
+        }
+
+        const nameMatch = String(model.name || '').match(/(\d+(?:\.\d+)?)\s*b\b/i);
+        if (nameMatch) {
+            return this.toFiniteNumber(nameMatch[1], 0);
+        }
+
+        // Approximate from quantized model file size (Q4 ~0.65 GB per 1B params)
+        const fileSizeGB = this.toFiniteNumber(model.fileSizeGB, 0);
+        if (fileSizeGB > 0) {
+            return fileSizeGB / 0.65;
+        }
+
+        return 7; // conservative fallback
+    }
+
+    estimateBaseMemoryGB(model = {}) {
+        const fileSizeGB = this.toFiniteNumber(model.fileSizeGB, 0);
+        if (fileSizeGB > 0) {
+            return fileSizeGB + this.modelOverheadGB;
+        }
+
+        const paramsB = this.estimateParamsB(model);
+        return paramsB * 0.65 + this.modelOverheadGB;
+    }
+
+    estimateKVCacheGB(paramsB, contextTokens) {
+        const ctx = this.toFiniteNumber(contextTokens, this.minContext);
+        return paramsB * this.kvFactorPer4k * (ctx / 4096);
+    }
+
+    normalizeModels(models = []) {
+        const normalized = models
+            .filter((model) => model && model.name)
+            .map((model) => {
+                const paramsB = this.estimateParamsB(model);
+                const baseMemoryGB = this.estimateBaseMemoryGB(model);
+                const fileSizeGB = this.toFiniteNumber(model.fileSizeGB, Math.max(0, baseMemoryGB - this.modelOverheadGB));
+                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
+                };
+            });
+
+        // Heaviest first to keep planning conservative
+        normalized.sort((a, b) => b.baseMemoryGB - a.baseMemoryGB);
+        return normalized;
+    }
+
+    resolveHardwareBudget(hardware = {}, reserveGB = null) {
+        const summary = hardware.summary || {};
+        const reserve = this.toFiniteNumber(reserveGB, this.defaultReserveGB);
+
+        const effectiveMemory = this.toFiniteNumber(summary.effectiveMemory, 0);
+        const systemRAM = this.toFiniteNumber(summary.systemRAM, 0);
+        const vram = this.toFiniteNumber(summary.totalVRAM, 0);
+        const fallbackTotal = this.toFiniteNumber(hardware.memory?.total, 8);
+
+        const rawCapacityGB = effectiveMemory || vram || (systemRAM > 0 ? systemRAM * 0.7 : 0) || fallbackTotal * 0.7;
+        const memoryBudgetGB = Math.max(2, rawCapacityGB - reserve);
+
+        return {
+            backend: summary.bestBackend || 'cpu',
+            backendName: summary.backendName || summary.bestBackend || 'CPU',
+            rawCapacityGB: Math.round(rawCapacityGB * 10) / 10,
+            reserveGB: Math.round(reserve * 10) / 10,
+            memoryBudgetGB: Math.round(memoryBudgetGB * 10) / 10
+        };
+    }
+
+    computeLoadState(models, contextTokens, loadedCount, budgetGB) {
+        const activeModels = models.slice(0, loadedCount);
+        const baseTotalGB = activeModels.reduce((sum, model) => sum + model.baseMemoryGB, 0);
+        const maxParamsB = activeModels.reduce((max, model) => Math.max(max, model.paramsB), 0);
+        const kvAtContextGB = this.estimateKVCacheGB(maxParamsB, contextTokens);
+        const kvPerTokenGB = maxParamsB > 0 ? (maxParamsB * this.kvFactorPer4k) / 4096 : 0;
+        const availableForKVGB = budgetGB - baseTotalGB;
+
+        let maxParallelAtContext = 0;
+        if (kvAtContextGB <= 0) {
+            maxParallelAtContext = this.maxParallelCap;
+        } else if (availableForKVGB > 0) {
+            maxParallelAtContext = Math.floor(availableForKVGB / kvAtContextGB);
+        }
+
+        return {
+            activeModels,
+            baseTotalGB,
+            maxParamsB,
+            kvAtContextGB,
+            kvPerTokenGB,
+            availableForKVGB,
+            maxParallelAtContext
+        };
+    }
+
+    maxLoadedModelsFor(models, contextTokens, parallel, budgetGB, hardCap) {
+        const cap = Math.max(1, Math.min(hardCap, models.length));
+        let best = 1;
+        for (let i = 1; i <= cap; i += 1) {
+            const state = this.computeLoadState(models, contextTokens, i, budgetGB);
+            const estimatedTotal = state.baseTotalGB + (state.kvAtContextGB * parallel);
+            if (estimatedTotal <= budgetGB) {
+                best = i;
+            } else {
+                break;
+            }
+        }
+        return best;
+    }
+
+    calculateRiskLevel({
+        budgetGB,
+        requestedTotalGB,
+        recommendedTotalGB,
+        requestedFits
+    }) {
+        const safeBudget = Math.max(0.1, budgetGB);
+        const requestedUtil = requestedTotalGB / safeBudget;
+        const recommendedUtil = recommendedTotalGB / safeBudget;
+        const overage = Math.max(0, requestedTotalGB - safeBudget) / safeBudget;
+
+        const score = Math.min(
+            100,
+            Math.round((overage * 100) + (recommendedUtil * 55) + (requestedFits ? 0 : 20))
+        );
+
+        let level = 'low';
+        if (score >= 75) level = 'critical';
+        else if (score >= 55) level = 'high';
+        else if (score >= 35) level = 'medium';
+
+        return { level, score };
+    }
+
+    plan({
+        hardware,
+        models,
+        targetContext = 8192,
+        targetConcurrency = 2,
+        objective = 'balanced',
+        reserveGB = null
+    }) {
+        const normalizedObjective = this.normalizeObjective(objective);
+        const profile = this.objectiveProfile(normalizedObjective);
+        const modelPool = this.normalizeModels(models);
+
+        if (modelPool.length === 0) {
+            throw new Error('At least one model is required for planning.');
+        }
+
+        const requestedCtx = this.clamp(
+            Math.round(this.toFiniteNumber(targetContext, 8192)),
+            512,
+            131072
+        );
+        const requestedConcurrency = this.clamp(
+            Math.round(this.toFiniteNumber(targetConcurrency, 2)),
+            1,
+            64
+        );
+
+        const hardwareBudget = this.resolveHardwareBudget(hardware, reserveGB);
+        const budgetGB = hardwareBudget.memoryBudgetGB;
+
+        const desiredLoaded = Math.max(1, Math.min(profile.loadedCap, modelPool.length));
+        let loadedModels = desiredLoaded;
+
+        // Ensure the base model memory is feasible.
+        while (loadedModels > 1) {
+            const state = this.computeLoadState(modelPool, requestedCtx, loadedModels, budgetGB);
+            if (state.availableForKVGB > 0) {
+                break;
+            }
+            loadedModels -= 1;
+        }
+
+        let requestedState = this.computeLoadState(modelPool, requestedCtx, loadedModels, budgetGB);
+        let recommendedCtx = requestedCtx;
+
+        if (requestedState.maxParallelAtContext < 1) {
+            const ctxFitAtParallel1 = requestedState.kvPerTokenGB > 0
+                ? Math.floor(requestedState.availableForKVGB / requestedState.kvPerTokenGB)
+                : requestedCtx;
+            recommendedCtx = this.clamp(
+                Math.max(this.minContext, Math.min(requestedCtx, ctxFitAtParallel1 || this.minContext)),
+                this.minContext,
+                requestedCtx
+            );
+        }
+
+        let recommendedState = this.computeLoadState(modelPool, recommendedCtx, loadedModels, budgetGB);
+        if (recommendedState.maxParallelAtContext < 1) {
+            recommendedCtx = this.minContext;
+            recommendedState = this.computeLoadState(modelPool, recommendedCtx, loadedModels, budgetGB);
+        }
+
+        let recommendedParallel = Math.max(
+            1,
+            Math.min(
+                requestedConcurrency,
+                profile.parallelCap,
+                this.maxParallelCap,
+                Math.max(1, recommendedState.maxParallelAtContext)
+            )
+        );
+
+        let recommendedLoaded = this.maxLoadedModelsFor(
+            modelPool,
+            recommendedCtx,
+            recommendedParallel,
+            budgetGB,
+            profile.loadedCap
+        );
+
+        // Recompute state after final loaded model selection.
+        recommendedState = this.computeLoadState(modelPool, recommendedCtx, recommendedLoaded, budgetGB);
+
+        const maxCtxParallel1 = recommendedState.kvPerTokenGB > 0
+            ? Math.floor(recommendedState.availableForKVGB / recommendedState.kvPerTokenGB)
+            : requestedCtx;
+        const maxCtxAtRecommendedParallel = recommendedState.kvPerTokenGB > 0
+            ? Math.floor(recommendedState.availableForKVGB / (recommendedState.kvPerTokenGB * recommendedParallel))
+            : requestedCtx;
+
+        if (maxCtxAtRecommendedParallel > 0) {
+            recommendedCtx = this.clamp(
+                Math.min(recommendedCtx, maxCtxAtRecommendedParallel),
+                this.minContext,
+                requestedCtx
+            );
+        }
+
+        recommendedState = this.computeLoadState(modelPool, recommendedCtx, recommendedLoaded, budgetGB);
+        const requestedTotalGB = requestedState.baseTotalGB + (requestedState.kvAtContextGB * requestedConcurrency);
+        const recommendedTotalGB = recommendedState.baseTotalGB + (recommendedState.kvAtContextGB * recommendedParallel);
+        const requestedFits = requestedTotalGB <= budgetGB;
+
+        const risk = this.calculateRiskLevel({
+            budgetGB,
+            requestedTotalGB,
+            recommendedTotalGB,
+            requestedFits
+        });
+
+        const flashAttention = hardwareBudget.backend === 'cpu' ? '0' : '1';
+        const maxQueue = Math.max(4, recommendedParallel * 4);
+
+        const fallbackCtx = this.clamp(Math.min(4096, recommendedCtx), this.minContext, recommendedCtx);
+        const fallbackState = this.computeLoadState(modelPool, fallbackCtx, 1, budgetGB);
+        const fallbackTotalGB = fallbackState.baseTotalGB + fallbackState.kvAtContextGB;
+
+        const notes = [];
+        if (!requestedFits) {
+            notes.push('Requested settings exceed available memory budget; reduced settings are recommended.');
+        }
+        if (recommendedCtx < requestedCtx) {
+            notes.push(`Context reduced from ${requestedCtx} to ${recommendedCtx} to avoid memory pressure.`);
+        }
+        if (recommendedParallel < requestedConcurrency) {
+            notes.push(`Parallelism reduced from ${requestedConcurrency} to ${recommendedParallel} to keep memory stable.`);
+        }
+        if (recommendedLoaded < desiredLoaded) {
+            notes.push(`Loaded models capped at ${recommendedLoaded} for this objective and memory budget.`);
+        }
+
+        return {
+            objective: normalizedObjective,
+            inputs: {
+                targetContext: requestedCtx,
+                targetConcurrency: requestedConcurrency
+            },
+            hardware: hardwareBudget,
+            models: recommendedState.activeModels.map((model) => ({
+                name: model.name,
+                size: model.size,
+                fileSizeGB: model.fileSizeGB,
+                paramsB: model.paramsB,
+                estimatedBaseMemoryGB: Math.round(model.baseMemoryGB * 100) / 100
+            })),
+            envelope: {
+                context: {
+                    requested: requestedCtx,
+                    recommended: recommendedCtx,
+                    min_safe: this.minContext,
+                    max_for_parallel_1: Math.max(0, maxCtxParallel1 || 0),
+                    max_for_recommended_parallel: Math.max(0, maxCtxAtRecommendedParallel || 0)
+                },
+                parallel: {
+                    requested: requestedConcurrency,
+                    recommended: recommendedParallel,
+                    max_at_requested_ctx: Math.max(0, requestedState.maxParallelAtContext)
+                },
+                loaded_models: {
+                    requested: desiredLoaded,
+                    recommended: recommendedLoaded,
+                    max_at_recommended_settings: this.maxLoadedModelsFor(
+                        modelPool,
+                        recommendedCtx,
+                        recommendedParallel,
+                        budgetGB,
+                        modelPool.length
+                    )
+                }
+            },
+            recommendation: {
+                num_ctx: recommendedCtx,
+                num_parallel: recommendedParallel,
+                max_loaded_models: recommendedLoaded,
+                max_queue: maxQueue,
+                keep_alive: profile.keepAlive,
+                flash_attention: flashAttention
+            },
+            memory: {
+                budgetGB: Math.round(budgetGB * 100) / 100,
+                requestedEstimatedGB: Math.round(requestedTotalGB * 100) / 100,
+                recommendedEstimatedGB: Math.round(recommendedTotalGB * 100) / 100,
+                utilizationPercent: Math.round((recommendedTotalGB / Math.max(0.1, budgetGB)) * 100)
+            },
+            risk,
+            fallback: {
+                num_ctx: fallbackCtx,
+                num_parallel: 1,
+                max_loaded_models: 1,
+                estimated_memory_gb: Math.round(fallbackTotalGB * 100) / 100
+            },
+            shell: {
+                env: {
+                    OLLAMA_NUM_CTX: String(recommendedCtx),
+                    OLLAMA_NUM_PARALLEL: String(recommendedParallel),
+                    OLLAMA_MAX_LOADED_MODELS: String(recommendedLoaded),
+                    OLLAMA_MAX_QUEUE: String(maxQueue),
+                    OLLAMA_KEEP_ALIVE: profile.keepAlive,
+                    OLLAMA_FLASH_ATTENTION: flashAttention
+                }
+            },
+            notes
+        };
+    }
+}
+
+module.exports = OllamaCapacityPlanner;