llm-fit 1.0.0

package/README.md

@@ -0,0 +1,134 @@
+# llm-fit
+
+`llm-fit` is a production-ready, open-source CLI that scans your hardware and recommends local LLMs and coding-focused models that fit your machine.
+
+It supports Windows first, and also works on macOS and Linux.
+
+## Features
+
+- Hardware scan (RAM, CPU, GPU, VRAM, OS, WSL detection)
+- Tiered recommendations: Recommended, Might Work, Not Recommended
+- Curated model catalog with category filters
+- Optional model installs through Ollama
+- Sync of trending GGUF models from Hugging Face
+- ESM-only Node.js codebase for modern ecosystem compatibility
+
+## Requirements
+
+- Node.js 18+
+- npm
+- Ollama (optional, only needed for `install` command)
+
+## Installation
+
+### From source
+
+```bash
+git clone https://github.com/your-username/llm-fit
+cd llm-fit
+npm install
+```
+
+### Link globally for development
+
+```bash
+npm link
+```
+
+### Use it
+
+```bash
+llm-fit scan
+llm-fit recommend
+llm-fit recommend --category coding
+llm-fit models
+llm-fit models --category general
+llm-fit models --json
+llm-fit install llama3.2:3b
+llm-fit update-models
+```
+
+## Commands
+
+### `llm-fit scan`
+
+Scans your local machine and prints a hardware summary.
+
+### `llm-fit recommend [--category coding|general|all]`
+
+Scans your machine and returns three recommendation tiers.
+
+- `--category coding` shows coding models only
+- `--category general` shows general-purpose models only
+- `--category all` (default) shows all curated models
+
+### `llm-fit models [--category coding|general|all] [--json]`
+
+Lists curated models in a table format or raw JSON.
+
+### `llm-fit install <modelName>`
+
+Installs a model via Ollama.
+
+- Accepts either local `name` or `ollama_tag`
+- If a model is unknown to local DB, install is still attempted
+
+### `llm-fit update-models`
+
+Fetches trending GGUF models from Hugging Face and appends only new entries without overwriting curated records.
+
+## Output Design
+
+- Cyan section headers for scan/results sections
+- Green/Yellow/Red tiers for recommendation status
+- 80-column-friendly table and boxed output
+
+## Project Structure
+
+```text
+llm-fit/
+├── index.js
+├── commands/
+│   ├── scan.js
+│   ├── recommend.js
+│   ├── models.js
+│   ├── install.js
+│   └── update-models.js
+├── services/
+│   ├── systemScanner.js
+│   ├── recommender.js
+│   └── huggingface.js
+├── data/
+│   └── models.json
+├── utils/
+│   └── formatter.js
+├── package.json
+└── README.md
+```
+
+## Extensibility Notes
+
+- `services/recommender.js` is intentionally stateless so the scoring function can be replaced by an AI-driven ranking service later.
+- `data/models.json` is schema-version-ready by design; a top-level migration strategy can be introduced in a future release.
+- `services/huggingface.js` uses only Node built-ins (`https`) so retry, caching, and offline fallback strategies can be added without external HTTP libraries.
+
+## Development
+
+Run directly without global linking:
+
+```bash
+node index.js --help
+node index.js scan
+node index.js recommend --category coding
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make changes with clear commit messages
+4. Open a pull request with before/after command output samples
+
+## License
+
+MIT

package/commands/install.js

@@ -0,0 +1,116 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { execSync, spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import ora from 'ora';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const MODELS_PATH = path.join(__dirname, '..', 'data', 'models.json');
+
+async function loadModels() {
+  const raw = await fs.readFile(MODELS_PATH, 'utf8');
+  const parsed = JSON.parse(raw.replace(/^\uFEFF/, ''));
+
+  if (!Array.isArray(parsed)) {
+    throw new Error('Model database is invalid: expected an array');
+  }
+
+  return parsed;
+}
+
+function resolveInstallTarget(models, modelNameInput) {
+  const normalized = modelNameInput.toLowerCase();
+  const found = models.find((model) => {
+    const byName = String(model.name || '').toLowerCase() === normalized;
+    const byTag = String(model.ollama_tag || '').toLowerCase() === normalized;
+    return byName || byTag;
+  });
+
+  if (!found) {
+    return {
+      model: null,
+      tag: modelNameInput
+    };
+  }
+
+  return {
+    model: found,
+    tag: found.ollama_tag || found.name
+  };
+}
+
+function ensureOllamaInstalled() {
+  const checkCmd = process.platform === 'win32' ? 'where ollama' : 'which ollama';
+
+  try {
+    execSync(checkCmd, { stdio: 'ignore' });
+  } catch {
+    throw new Error(
+      'Ollama is not installed. Install it from https://ollama.com/download'
+    );
+  }
+}
+
+async function pullModelViaOllama(tag) {
+  const spinner = ora(`Preparing Ollama install for ${tag}...`).start();
+
+  return new Promise((resolve, reject) => {
+    try {
+      ensureOllamaInstalled();
+      spinner.text = `Installing ${tag} via Ollama...`;
+    } catch (error) {
+      spinner.fail('Ollama not found');
+      reject(error);
+      return;
+    }
+
+    const child = spawn('ollama', ['pull', tag], {
+      stdio: 'inherit'
+    });
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        spinner.succeed(`Installed ${tag}`);
+        resolve();
+        return;
+      }
+
+      spinner.fail(`Install failed for ${tag}`);
+      reject(new Error(`Ollama exited with code ${code}`));
+    });
+
+    child.on('error', (error) => {
+      spinner.fail(`Install failed for ${tag}`);
+      reject(new Error(`Failed to launch Ollama: ${error.message}`));
+    });
+  });
+}
+
+export function registerInstallCommand(program) {
+  program
+    .command('install <modelName>')
+    .description('Install a model via Ollama')
+    .action(async (modelName) => {
+      try {
+        const models = await loadModels();
+        const resolved = resolveInstallTarget(models, modelName);
+
+        if (!resolved.model) {
+          console.log(
+            chalk.yellow(
+              `⚠️ Model '${modelName}' not found in local database. Attempting install anyway.`
+            )
+          );
+        }
+
+        await pullModelViaOllama(resolved.tag);
+        process.exit(0);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown install error';
+        console.error(chalk.red(`❌ ${message}`));
+        process.exit(1);
+      }
+    });
+}

package/commands/models.js

@@ -0,0 +1,60 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { formatModelsTable, formatSectionHeader } from '../utils/formatter.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const MODELS_PATH = path.join(__dirname, '..', 'data', 'models.json');
+
+async function loadModels() {
+  const raw = await fs.readFile(MODELS_PATH, 'utf8');
+  const parsed = JSON.parse(raw.replace(/^\uFEFF/, ''));
+
+  if (!Array.isArray(parsed)) {
+    throw new Error('Model database is invalid: expected an array');
+  }
+
+  return parsed;
+}
+
+function filterByCategory(models, category) {
+  if (category === 'all') {
+    return models;
+  }
+
+  return models.filter((model) => model.category === category);
+}
+
+export function registerModelsCommand(program) {
+  program
+    .command('models')
+    .description('List all curated models')
+    .option('--category <category>', 'coding|general|all', 'all')
+    .option('--json', 'Output as raw JSON', false)
+    .action(async (options) => {
+      const category = String(options.category || 'all').toLowerCase();
+      if (!['coding', 'general', 'all'].includes(category)) {
+        console.error("error: invalid --category. Use 'coding', 'general', or 'all'.");
+        process.exit(1);
+      }
+
+      try {
+        const models = await loadModels();
+        const filtered = filterByCategory(models, category);
+
+        if (options.json) {
+          console.log(JSON.stringify(filtered, null, 2));
+          process.exit(0);
+        }
+
+        console.log(formatSectionHeader('Model Catalog'));
+        console.log(formatModelsTable(filtered));
+        process.exit(0);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown models error';
+        console.error(`error: ${message}`);
+        process.exit(1);
+      }
+    });
+}

package/commands/recommend.js

@@ -0,0 +1,62 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import ora from 'ora';
+import { scanSystemWithScore } from './scan.js';
+import { rankModelsForSystem } from '../services/recommender.js';
+import {
+  formatRecommendationBuckets,
+  formatSectionHeader
+} from '../utils/formatter.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const MODELS_PATH = path.join(__dirname, '..', 'data', 'models.json');
+
+async function loadModels() {
+  const raw = await fs.readFile(MODELS_PATH, 'utf8');
+  const parsed = JSON.parse(raw.replace(/^\uFEFF/, ''));
+
+  if (!Array.isArray(parsed)) {
+    throw new Error('Model database is invalid: expected an array');
+  }
+
+  return parsed;
+}
+
+export function registerRecommendCommand(program) {
+  program
+    .command('recommend')
+    .description('Recommend models based on your hardware')
+    .option('--category <category>', 'coding|general|all', 'all')
+    .action(async (options) => {
+      const category = String(options.category || 'all').toLowerCase();
+      if (!['coding', 'general', 'all'].includes(category)) {
+        console.error("error: invalid --category. Use 'coding', 'general', or 'all'.");
+        process.exit(1);
+      }
+
+      const spinner = ora('Scanning your system hardware...').start();
+
+      try {
+        const [{ system, score }, models] = await Promise.all([
+          scanSystemWithScore(),
+          loadModels()
+        ]);
+
+        spinner.succeed('Hardware scan complete');
+
+        const buckets = rankModelsForSystem(system, models, category);
+        console.log(formatSectionHeader('Model Recommendations'));
+        console.log(`Readiness score: ${score.score}/100 (${score.grade} - ${score.label})`);
+        console.log(formatRecommendationBuckets(buckets));
+        process.exit(0);
+      } catch (error) {
+        spinner.fail('Recommendation failed');
+        const message =
+          error instanceof Error ? error.message : 'Unknown recommendation error';
+        console.error(`error: ${message}`);
+        process.exit(1);
+      }
+    });
+}

package/commands/scan.js

@@ -0,0 +1,97 @@
+import ora from 'ora';
+import chalk from 'chalk';
+import { scanSystemHardware } from '../services/systemScanner.js';
+import { formatSectionHeader, formatSystemBox } from '../utils/formatter.js';
+import { computeScore } from '../utils/scoreEngine.js';
+
+const BAR_WIDTH = 30;
+
+function getScoreColor(score) {
+  if (score >= 70) {
+    return chalk.green;
+  }
+  if (score >= 40) {
+    return chalk.yellow;
+  }
+  return chalk.red;
+}
+
+function toBar(value, max) {
+  const ratio = max <= 0 ? 0 : value / max;
+  const filledCount = Math.max(0, Math.min(BAR_WIDTH, Math.round(ratio * BAR_WIDTH)));
+  return `${'█'.repeat(filledCount)}${'░'.repeat(BAR_WIDTH - filledCount)}`;
+}
+
+function formatVerdictLines(verdict) {
+  const [firstSentence, ...rest] = String(verdict).split('. ').filter(Boolean);
+  if (rest.length === 0) {
+    return [firstSentence.endsWith('.') ? firstSentence : `${firstSentence}.`];
+  }
+
+  const first = firstSentence.endsWith('.') ? firstSentence : `${firstSentence}.`;
+  const second = rest.join('. ');
+  return [first, second.endsWith('.') ? second : `${second}.`];
+}
+
+function formatReadinessSection(scoreResult) {
+  const colorize = getScoreColor(scoreResult.score);
+  const headlineBar = toBar(scoreResult.score, 100);
+  const verdictLines = formatVerdictLines(scoreResult.verdict);
+  const lines = [
+    formatSectionHeader('LLM Readiness Score'),
+    '',
+    `  ${colorize(headlineBar)}  ${scoreResult.score} / 100`,
+    '',
+    `  Grade   : ${scoreResult.grade}  -  ${scoreResult.label}`,
+    `  Verdict : ${verdictLines[0]}`
+  ];
+
+  if (verdictLines[1]) {
+    lines.push(`            ${verdictLines[1]}`);
+  }
+
+  lines.push('', '  Breakdown:');
+
+  const breakdownRows = [
+    ['RAM', scoreResult.breakdown.ram, 40],
+    ['CPU Cores', scoreResult.breakdown.cpu, 25],
+    ['GPU', scoreResult.breakdown.gpu, 25],
+    ['VRAM', scoreResult.breakdown.vram, 10]
+  ];
+
+  for (const [label, value, max] of breakdownRows) {
+    const paddedLabel = String(label).padEnd(11, ' ');
+    lines.push(`    ${paddedLabel} ${toBar(value, max)}  ${value} / ${max}`);
+  }
+
+  return lines.join('\n');
+}
+
+export async function scanSystemWithScore() {
+  const system = await scanSystemHardware();
+  const score = computeScore(system);
+  return { system, score };
+}
+
+export function registerScanCommand(program) {
+  program
+    .command('scan')
+    .description('Scan and print system hardware information')
+    .action(async () => {
+      const spinner = ora('Scanning your system hardware...').start();
+
+      try {
+        const { system, score } = await scanSystemWithScore();
+        spinner.succeed('Hardware scan complete');
+        console.log(formatSectionHeader('System Info'));
+        console.log(formatSystemBox(system));
+        console.log(formatReadinessSection(score));
+        process.exit(0);
+      } catch (error) {
+        spinner.fail('Hardware scan failed');
+        const message = error instanceof Error ? error.message : 'Unknown scan error';
+        console.error(`error: ${message}`);
+        process.exit(1);
+      }
+    });
+}

package/commands/update-models.js

@@ -0,0 +1,52 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import ora from 'ora';
+import {
+  fetchTrendingGgufModels,
+  mergeModelsWithLocalDb,
+  writeJsonAtomic
+} from '../services/huggingface.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const MODELS_PATH = path.join(__dirname, '..', 'data', 'models.json');
+
+async function readLocalModels() {
+  const raw = await fs.readFile(MODELS_PATH, 'utf8');
+  const parsed = JSON.parse(raw.replace(/^\uFEFF/, ''));
+
+  if (!Array.isArray(parsed)) {
+    throw new Error('Model database is invalid: expected an array');
+  }
+
+  return parsed;
+}
+
+export function registerUpdateModelsCommand(program) {
+  program
+    .command('update-models')
+    .description('Sync trending GGUF models from Hugging Face')
+    .action(async () => {
+      const spinner = ora('Syncing models from Hugging Face...').start();
+
+      try {
+        const localModels = await readLocalModels();
+        const fetched = await fetchTrendingGgufModels();
+        const { merged, addedCount } = mergeModelsWithLocalDb(localModels, fetched);
+
+        await writeJsonAtomic(MODELS_PATH, merged);
+
+        spinner.succeed('Model database updated');
+        console.log(
+          `Added ${addedCount} new models. Database now has ${merged.length} models.`
+        );
+        process.exit(0);
+      } catch (error) {
+        spinner.fail('Model sync failed');
+        const message = error instanceof Error ? error.message : 'Unknown sync error';
+        console.error(`error: ${message}`);
+        process.exit(1);
+      }
+    });
+}