llm-checker 3.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pavelevich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,418 @@
+<p align="center">
+  <img src="llmlogo.jpg" alt="LLM Checker Logo" width="200">
+</p>
+
+<p align="center">
+  <h1 align="center">LLM Checker</h1>
+  <p align="center">
+    <strong>Intelligent Ollama Model Selector</strong>
+  </p>
+  <p align="center">
+    AI-powered CLI that analyzes your hardware and recommends optimal LLM models<br/>
+    Deterministic scoring across <b>35+ curated models</b> with hardware-calibrated memory estimation
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/llm-checker"><img src="https://img.shields.io/npm/v/llm-checker?style=flat-square&color=0066FF" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/llm-checker"><img src="https://img.shields.io/npm/dm/llm-checker?style=flat-square&color=0066FF" alt="npm downloads"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-0066FF?style=flat-square" alt="License"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D16-0066FF?style=flat-square" alt="Node.js"></a>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> &bull;
+  <a href="#quick-start">Quick Start</a> &bull;
+  <a href="#commands">Commands</a> &bull;
+  <a href="#scoring-system">Scoring</a> &bull;
+  <a href="#supported-hardware">Hardware</a>
+</p>
+
+---
+
+## Why LLM Checker?
+
+Choosing the right LLM for your hardware is complex. With thousands of model variants, quantization levels, and hardware configurations, finding the optimal model requires understanding memory bandwidth, VRAM limits, and performance characteristics.
+
+**LLM Checker solves this.** It analyzes your system, scores every compatible model across four dimensions (Quality, Speed, Fit, Context), and delivers actionable recommendations in seconds.
+
+---
+
+## Features
+
+| | Feature | Description |
+|:---:|---|---|
+| **35+** | Curated Models | Hand-picked catalog covering all major families and sizes (1B-32B) |
+| **4D** | Scoring Engine | Quality, Speed, Fit, Context &mdash; weighted by use case |
+| **Multi-GPU** | Hardware Detection | Apple Silicon, NVIDIA CUDA, AMD ROCm, Intel Arc, CPU |
+| **Calibrated** | Memory Estimation | Bytes-per-parameter formula validated against real Ollama sizes |
+| **Zero** | Native Dependencies | Pure JavaScript &mdash; works on any Node.js 16+ system |
+| **Optional** | SQLite Search | Install `sql.js` to unlock `sync`, `search`, and `smart-recommend` |
+
+---
+
+## Installation
+
+```bash
+# Install globally
+npm install -g llm-checker
+
+# Or run directly with npx
+npx llm-checker hw-detect
+```
+
+**Requirements:**
+- Node.js 16+ (any version: 16, 18, 20, 22, 24)
+- [Ollama](https://ollama.ai) installed for running models
+
+**Optional:** For database search features (`sync`, `search`, `smart-recommend`):
+```bash
+npm install sql.js
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Detect your hardware capabilities
+llm-checker hw-detect
+
+# 2. Get full analysis with compatible models
+llm-checker check
+
+# 3. Get intelligent recommendations by category
+llm-checker recommend
+
+# 4. (Optional) Sync full database and search
+llm-checker sync
+llm-checker search qwen --use-case coding
+```
+
+---
+
+## Commands
+
+### Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `hw-detect` | Detect GPU/CPU capabilities, memory, backends |
+| `check` | Full system analysis with compatible models and recommendations |
+| `recommend` | Intelligent recommendations by category (coding, reasoning, multimodal, etc.) |
+| `installed` | Rank your installed Ollama models by compatibility |
+
+### Advanced Commands (require `sql.js`)
+
+| Command | Description |
+|---------|-------------|
+| `sync` | Download the latest model catalog from Ollama registry |
+| `search <query>` | Search models with filters and intelligent scoring |
+| `smart-recommend` | Advanced recommendations using the full scoring engine |
+
+### AI Commands
+
+| Command | Description |
+|---------|-------------|
+| `ai-check` | AI-powered model evaluation with meta-analysis |
+| `ai-run` | AI-powered model selection and execution |
+
+---
+
+### `hw-detect` &mdash; Hardware Analysis
+
+```bash
+llm-checker hw-detect
+```
+
+```
+Summary:
+  Apple M4 Pro (24GB Unified Memory)
+  Tier: MEDIUM HIGH
+  Max model size: 15GB
+  Best backend: metal
+
+CPU:
+  Apple M4 Pro
+  Cores: 12 (12 physical)
+  SIMD: NEON
+
+Metal:
+  GPU Cores: 16
+  Unified Memory: 24GB
+  Memory Bandwidth: 273GB/s
+```
+
+### `recommend` &mdash; Category Recommendations
+
+```bash
+llm-checker recommend
+```
+
+```
+INTELLIGENT RECOMMENDATIONS BY CATEGORY
+Hardware Tier: HIGH | Models Analyzed: 205
+
+Coding:
+   qwen2.5-coder:14b (14B)
+   Score: 78/100
+   Command: ollama pull qwen2.5-coder:14b
+
+Reasoning:
+   deepseek-r1:14b (14B)
+   Score: 86/100
+   Command: ollama pull deepseek-r1:14b
+
+Multimodal:
+   llama3.2-vision:11b (11B)
+   Score: 83/100
+   Command: ollama pull llama3.2-vision:11b
+```
+
+### `search` &mdash; Model Search
+
+```bash
+llm-checker search llama -l 5
+llm-checker search coding --use-case coding
+llm-checker search qwen --quant Q4_K_M --max-size 8
+```
+
+| Option | Description |
+|--------|-------------|
+| `-l, --limit <n>` | Number of results (default: 10) |
+| `-u, --use-case <type>` | Optimize for: `general`, `coding`, `chat`, `reasoning`, `creative`, `fast` |
+| `--max-size <gb>` | Maximum model size in GB |
+| `--quant <type>` | Filter by quantization: `Q4_K_M`, `Q8_0`, `FP16`, etc. |
+| `--family <name>` | Filter by model family |
+
+---
+
+## Model Catalog
+
+The built-in catalog includes 35+ models from the most popular Ollama families:
+
+| Family | Models | Best For |
+|--------|--------|----------|
+| **Qwen 2.5/3** | 7B, 14B, Coder 7B/14B/32B, VL 3B/7B | Coding, general, vision |
+| **Llama 3.x** | 1B, 3B, 8B, Vision 11B | General, chat, multimodal |
+| **DeepSeek** | R1 8B/14B/32B, Coder V2 16B | Reasoning, coding |
+| **Phi-4** | 14B | Reasoning, math |
+| **Gemma 2** | 2B, 9B | General, efficient |
+| **Mistral** | 7B, Nemo 12B | Creative, chat |
+| **CodeLlama** | 7B, 13B | Coding |
+| **LLaVA** | 7B, 13B | Vision |
+| **Embeddings** | nomic-embed-text, mxbai-embed-large, bge-m3, all-minilm | RAG, search |
+
+Models are automatically combined with any locally installed Ollama models for scoring.
+
+---
+
+## Scoring System
+
+Models are evaluated across four dimensions, weighted by use case:
+
+| Dimension | Description |
+|-----------|-------------|
+| **Q** Quality | Model family reputation + parameter count + quantization penalty |
+| **S** Speed | Estimated tokens/sec based on hardware backend and model size |
+| **F** Fit | Memory utilization efficiency (how well it fits in available RAM) |
+| **C** Context | Context window capability vs. target context length |
+
+### Scoring Weights by Use Case
+
+Three scoring systems are available, each optimized for different workflows:
+
+**Deterministic Selector** (primary &mdash; used by `check` and `recommend`):
+
+| Category | Quality | Speed | Fit | Context |
+|----------|:-------:|:-----:|:---:|:-------:|
+| `general` | 45% | 35% | 15% | 5% |
+| `coding` | 55% | 20% | 15% | 10% |
+| `reasoning` | 60% | 10% | 20% | 10% |
+| `multimodal` | 50% | 15% | 20% | 15% |
+
+**Scoring Engine** (used by `smart-recommend` and `search`):
+
+| Use Case | Quality | Speed | Fit | Context |
+|----------|:-------:|:-----:|:---:|:-------:|
+| `general` | 40% | 35% | 15% | 10% |
+| `coding` | 55% | 20% | 15% | 10% |
+| `reasoning` | 60% | 15% | 10% | 15% |
+| `chat` | 40% | 40% | 15% | 5% |
+| `fast` | 25% | 55% | 15% | 5% |
+| `quality` | 65% | 10% | 15% | 10% |
+
+All weights are centralized in `src/models/scoring-config.js`.
+
+### Memory Estimation
+
+Memory requirements are calculated using calibrated bytes-per-parameter values:
+
+| Quantization | Bytes/Param | 7B Model | 14B Model | 32B Model |
+|:------------:|:-----------:|:--------:|:---------:|:---------:|
+| Q8_0 | 1.05 | ~8 GB | ~16 GB | ~35 GB |
+| Q4_K_M | 0.58 | ~5 GB | ~9 GB | ~20 GB |
+| Q3_K | 0.48 | ~4 GB | ~8 GB | ~17 GB |
+
+The selector automatically picks the best quantization that fits your available memory.
+
+---
+
+## Supported Hardware
+
+<details>
+<summary><strong>Apple Silicon</strong></summary>
+
+- M1, M1 Pro, M1 Max, M1 Ultra
+- M2, M2 Pro, M2 Max, M2 Ultra
+- M3, M3 Pro, M3 Max
+- M4, M4 Pro, M4 Max
+
+</details>
+
+<details>
+<summary><strong>NVIDIA (CUDA)</strong></summary>
+
+- RTX 50 Series (5090, 5080, 5070 Ti, 5070)
+- RTX 40 Series (4090, 4080, 4070 Ti, 4070, 4060 Ti, 4060)
+- RTX 30 Series (3090 Ti, 3090, 3080 Ti, 3080, 3070 Ti, 3070, 3060 Ti, 3060)
+- Data Center (H100, A100, A10, L40, T4)
+
+</details>
+
+<details>
+<summary><strong>AMD (ROCm)</strong></summary>
+
+- RX 7900 XTX, 7900 XT, 7800 XT, 7700 XT
+- RX 6900 XT, 6800 XT, 6800
+- Instinct MI300X, MI300A, MI250X, MI210
+
+</details>
+
+<details>
+<summary><strong>Intel</strong></summary>
+
+- Arc A770, A750, A580, A380
+- Integrated Iris Xe, UHD Graphics
+
+</details>
+
+<details>
+<summary><strong>CPU Backends</strong></summary>
+
+- AVX-512 + AMX (Intel Sapphire Rapids, Emerald Rapids)
+- AVX-512 (Intel Ice Lake+, AMD Zen 4)
+- AVX2 (Most modern x86 CPUs)
+- ARM NEON (Apple Silicon, AWS Graviton, Ampere Altra)
+
+</details>
+
+---
+
+## Architecture
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│  Hardware       │────>│  Model          │────>│  Deterministic  │
+│  Detection      │     │  Catalog (35+)  │     │  Selector       │
+└─────────────────┘     └─────────────────┘     └─────────────────┘
+        │                       │                       │
+   Detects GPU/CPU         JSON catalog +           4D scoring
+   Memory / Backend        Installed models         Per-category weights
+   Usable memory calc      Auto-dedup               Memory calibration
+                                                        │
+                                                        v
+                                               ┌─────────────────┐
+                                               │  Ranked         │
+                                               │  Recommendations│
+                                               └─────────────────┘
+```
+
+**Selector Pipeline:**
+1. **Hardware profiling** &mdash; CPU, GPU, RAM, acceleration backend
+2. **Model pool** &mdash; Merge catalog + installed Ollama models (deduped)
+3. **Category filter** &mdash; Keep models relevant to the use case
+4. **Quantization selection** &mdash; Best quant that fits in memory budget
+5. **4D scoring** &mdash; Q, S, F, C with category-specific weights
+6. **Ranking** &mdash; Top N candidates returned
+
+---
+
+## Examples
+
+**Detect your hardware:**
+```bash
+llm-checker hw-detect
+```
+
+**Get recommendations for all categories:**
+```bash
+llm-checker recommend
+```
+
+**Full system analysis with compatible models:**
+```bash
+llm-checker check
+```
+
+**Find the best coding model:**
+```bash
+llm-checker recommend --category coding
+```
+
+**Search for small, fast models under 5GB:**
+```bash
+llm-checker search "7b" --max-size 5 --use-case fast
+```
+
+**Get high-quality reasoning models:**
+```bash
+llm-checker smart-recommend --use-case reasoning
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/Pavelevich/llm-checker.git
+cd llm-checker
+npm install
+node bin/enhanced_cli.js hw-detect
+```
+
+### Project Structure
+
+```
+src/
+  models/
+    deterministic-selector.js  # Primary selection algorithm
+    scoring-config.js          # Centralized scoring weights
+    scoring-engine.js          # Advanced scoring (smart-recommend)
+    catalog.json               # Curated model catalog (35+ models)
+  ai/
+    multi-objective-selector.js  # Multi-objective optimization
+    ai-check-selector.js        # LLM-based evaluation
+  hardware/
+    detector.js                # Hardware detection
+    unified-detector.js        # Cross-platform detection
+  data/
+    model-database.js          # SQLite storage (optional)
+    sync-manager.js            # Database sync from Ollama registry
+bin/
+  enhanced_cli.js              # CLI entry point
+```
+
+---
+
+## License
+
+MIT License &mdash; see [LICENSE](LICENSE) for details.
+
+---
+
+<p align="center">
+  <a href="https://github.com/Pavelevich/llm-checker">GitHub</a> &bull;
+  <a href="https://www.npmjs.com/package/llm-checker">npm</a> &bull;
+  <a href="https://github.com/Pavelevich/llm-checker/issues">Issues</a>
+</p>