Metadata-Version: 2.4
Name: ai-model-detector
Version: 1.4.0
Summary: Deep hardware scanner that recommends and auto-downloads the best local AI model for your system
License: MIT License
        
        Copyright (c) 2026 eliekh05
        
        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.
        
Project-URL: Homepage, https://github.com/eliekh05/AI-Model-Detector-Auto-Downloader
Project-URL: Issues, https://github.com/eliekh05/AI-Model-Detector-Auto-Downloader/issues
Keywords: ollama,llm,ai,hardware,model-selection,local-ai
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Hardware
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.9
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13.7
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: ruff>=0.4; extra == "dev"
Dynamic: license-file

# AI Model Detector & Auto Downloader

> Deep hardware scanning · Live model registry · Smart recommendations · Auto install

A precise, transparent tool that scans your entire system — from OS and CPU instruction sets to GPU drivers and available VRAM — then queries the **live** Ollama library, Hugging Face, and community issue trackers to recommend and install the best local AI model for your hardware.

Unlike tools that rely solely on GPU data or maintain a hardcoded model list, this tool fetches its registry fresh every run, so newly released models appear automatically without requiring a software update.

---

## Install

```bash
pip3 install ai-model-detector --break-system-packages
```

**Requirements:** Python ≥ 3.11, internet connection (for live registry fetch)

---

## Quick Start

```bash
# Scan hardware, fetch live registry, recommend + optionally install
ai-model-detector

# Filter by use-case
ai-model-detector --category code
ai-model-detector --category vision
ai-model-detector --category math
ai-model-detector --category reasoning

# Show more recommendations
ai-model-detector --top 10

# Import a macOS system profile instead of live scan
ai-model-detector --import ~/Desktop/MyMac.spx

# Pull a specific model directly
ai-model-detector --pull llama3.2:3b

# Output full JSON (pipe to other tools)
ai-model-detector --json > results.json

# List already-installed models
ai-model-detector --installed
```

---

## How It Works

### 1 — System Scan

Reads hardware directly from the OS — no config file needed:

| Source | Data collected |
|--------|---------------|
| `/proc/cpuinfo` · `sysctl` · `wmic` | CPU brand, cores, AVX / AVX2 / AVX-512 / F16C flags |
| `psutil` | RAM total, RAM available |
| `dmidecode` · `system_profiler` · `wmic` | RAM speed |
| `nvidia-smi` | NVIDIA GPU name, VRAM, CUDA version |
| `rocm-smi` · `rocminfo` | AMD GPU name, VRAM, ROCm version |
| `system_profiler SPDisplaysDataType` | Apple Silicon GPU, Metal support |
| `psutil.disk_usage` | Free disk space |
| `ollama --version` | Ollama presence and version |

On macOS, `machdep.cpu.features` and `machdep.cpu.leaf7_features` are both queried so AVX2 is correctly detected on Intel Macs (it only appears in `leaf7_features`).

On macOS, pass `--import file.spx` to read a `system_profiler` export instead of scanning live hardware.

### 2 — Live Registry Fetch

Every run fetches fresh data — no model list is stored in the source code:

- **Ollama library** — all available models with tags, sizes, and pull counts
- **Hugging Face API** — top GGUF models by download count (shown for reference; flagged as manual-download only)
- **Ollama GitHub issues** — open bug reports mapped to model names

### 3 — Hardware-Aware Scoring

Each model variant is scored 0–100 against your specific hardware:

| Factor | Effect |
|--------|--------|
| Available RAM vs model RAM requirement | ±20 pts |
| GPU VRAM vs model VRAM requirement | ±20 pts |
| Free disk space | ±30 pts |
| CPU instruction sets (AVX2, AVX-512) | ±5 pts |
| Apple Silicon + Metal | +10 pts |
| Quantization suitability (q4_K_M sweet spot) | ±8 pts |
| Ollama-pullable (single command install) | +8 pts |
| HuggingFace-only (manual download required) | −25 pts |
| Community bug reports | −3 pts per issue |
| Popularity (pull count) | +2–5 pts |

### 4 — Install

Runs `ollama pull <model>` with live streaming output. Only models from the Ollama library are offered for auto-install — HuggingFace-only GGUF models are shown in the list but flagged as manual-download. If Ollama isn't installed, platform-specific install instructions are provided.

---

## CLI Reference

```
usage: ai-model-detector [options]

options:
  --import FILE        Import a macOS .spx system profile
  --category CAT       Filter: chat | code | vision | math | reasoning | embedding
  --top N              Number of recommendations to show (default: 5)
  --json               Output full results as JSON
  --installed          List already-installed Ollama models
  --pull MODEL         Pull a specific model (e.g. llama3.2:3b)
  --no-hf              Skip Hugging Face supplemental data
  --verbose / -v       Enable debug logging
  --version            Show version and exit
```

---

## macOS `.spx` Import

Export your system profile from the macOS System Information app:

1. Open **System Information** (`Cmd+Space` → "System Information")
2. **File → Save…** → choose **System Information (.spx)**
3. Run: `ai-model-detector --import ~/Desktop/MyMac.spx`

---

## Why Not Just Use GPU Data?

Tools that only look at GPU VRAM miss critical constraints:

- A model might fit in VRAM but not in RAM when layers spill to CPU
- CPU instruction sets (AVX2 vs AVX-512) drastically affect CPU-offload speed
- Free disk space at download time is often the real bottleneck
- Community bug reports reveal models that perform poorly on specific hardware regardless of specs

This tool checks all of these, not just VRAM.

---

## Project Structure

```
src/ai_model_detector/
├── scanner.py    — deep hardware profiler (live + .spx import)
├── registry.py   — live model registry fetcher (Ollama + HuggingFace)
├── scorer.py     — hardware-aware scoring and ranking engine
├── downloader.py — ollama pull with ANSI-stripped streaming output
├── display.py    — Rich terminal UI
└── cli.py        — CLI entry point
```

---

## Contributing

Issues, hardware reports, and PRs welcome at  
[github.com/eliekh05/AI-Model-Detector-Auto-Downloader](https://github.com/eliekh05/AI-Model-Detector-Auto-Downloader)

---

## License

MIT — see [LICENSE](LICENSE)
