Metadata-Version: 2.5
Name: mlxwhich
Version: 0.1.0
Summary: One-command Apple Silicon MLX model advisor
Author: mlxwhich contributors
License-Expression: MIT
License-File: LICENSE
Keywords: ai,apple-silicon,benchmark,llm,mac,machine-learning,mlx
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: huggingface-hub>=0.20.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: test
Requires-Dist: pytest-mock>=3.12.0; extra == 'test'
Requires-Dist: pytest>=7.4.0; extra == 'test'
Description-Content-Type: text/markdown

# MLXWHICH 🍏⚡

> **One-command Apple Silicon MLX model advisor**  
> Discover which local LLMs fit and run best on your exact Mac — **before downloading gigabytes of weights**.

Inspired by [`whichllm`](https://github.com/Andyyyy64/whichllm), but built from the ground up for **Apple Silicon Macs** (M1 through M5) and **MLX-optimized models**.

---

## Key Features

- 🔍 **Zero Weight Downloads**: Queries Hugging Face metadata and file headers without downloading model weights.
- 💻 **Exact Apple Silicon Detection**: Auto-detects M-series chip family, variant, CPU P/E cores, GPU cores, unified memory, memory bandwidth (GB/s), and Neural Accelerators.
- 🧠 **MoE (Mixture of Experts) Aware**: Accurately differentiates active parameters (e.g. Qwen 30B-A3B with 3B active) from total parameters for memory and speed calculations.
- 📊 **Dynamic Unified Memory Modeling**: Computes weights + KV cache scaling (at 4k, 8k, 32k, 64k+ context) + MLX runtime overhead + macOS safety headroom.
- 📈 **Traceable Benchmark Evidence**: Clear evidence labels (`EXACT`, `CLOSE`, `ESTIMATED`, `UNKNOWN`) sourced from Apple ML Research, `mac-llm-bench`, and memory bandwidth roofline models.
- ⚡ **Multi-Profile Ranking**: Choose ranking priorities (`--priority balanced | speed | quality | memory`) and task filters (`--task general | coding | reasoning | creative`).
- 🤖 **Developer & Pipeline Friendly**: Clean terminal UI with Rich, plus `--json` and `--markdown` outputs for automation.
- 📴 **Offline & Cache First**: Caches Hub metadata in `~/.cache/mlxwhich` with offline fallback capabilities.

---

## Quick Start

### ⚡ One-Command Instant Run (Zero Setup via `uvx`)

Run immediately without installing anything permanently:

```bash
uvx --from git+https://github.com/ashnimethe/mlxwhich.git mlxwhich
```

---

### 📦 Global Installation

```bash
# Using uv tool (recommended)
uv tool install git+https://github.com/ashnimethe/mlxwhich.git

# Or using pipx
pipx install git+https://github.com/ashnimethe/mlxwhich.git

# Or standard pip
pip install git+https://github.com/ashnimethe/mlxwhich.git
```

Once installed, run `mlxwhich` from any terminal!

```bash
mlxwhich
```

# Inspect your Mac's detected hardware profile
mlxwhich hardware

# Explain exact memory breakdown for a specific model at 32k context
mlxwhich estimate mlx-community/Qwen3-14B-4bit --context 32k
```

---

## Command Options & Examples

### Filter by Task

```bash
# Discover best coding models (e.g. Qwen2.5-Coder)
mlxwhich --task coding

# Discover best reasoning models (e.g. DeepSeek-R1 Distills)
mlxwhich --task reasoning
```

### Customize Context & Priority

```bash
# Evaluate memory and ranking at 32k context with speed priority
mlxwhich --context 32k --priority speed --top 5

# Conservative memory profile reserving 5 GB headroom for other apps
mlxwhich --fit safe --memory-headroom 5
```

### JSON & Markdown Output

```bash
# Output structured JSON for automation or scripting
mlxwhich --json

# Generate Markdown report
mlxwhich --markdown > mlx_recommendations.md
```

### Inspect Benchmark Provenance & Sources

```bash
mlxwhich sources
```

---

## Example Output

```text
MLXWHICH — Apple Silicon Model Advisor

  Apple M5 | CPU: 10 cores | GPU: 10 cores | RAM: 24 GB unified | Bandwidth: 153 GB/s

Top MLX Models for this Mac (Context: 4k | Priority: Balanced | Task: General)
╭──────┬────────────────────────────────┬──────┬──────────┬──────────┬──────────┬───────┬───────────╮
│    # │ Model                          │ Fit  │ Required │ Headroom │ Speed    │ Score │ Evidence  │
├──────┼────────────────────────────────┼──────┼──────────┼──────────┼──────────┼───────┼───────────┤
│    1 │ Qwen3-30B-A3B-4bit             │ SAFE │ 20.8 GB  │ +3.2 GB  │ 58 tok/s │  93   │ EXACT     │
│    2 │ Qwen3-8B-4bit                  │ SAFE │ 6.8 GB   │ +17.2 GB │ 68 tok/s │  91   │ EXACT     │
│    3 │ GPT-OSS-20B-MXFP4              │ SAFE │ 15.1 GB  │ +8.9 GB  │ 51 tok/s │  90   │ EXACT     │
│    4 │ Qwen3-14B-4bit                 │ SAFE │ 10.5 GB  │ +13.5 GB │ 42 tok/s │  89   │ EXACT     │
│    5 │ Qwen2.5-Coder-7B-Instruct-4bit │ SAFE │ 6.2 GB   │ +17.8 GB │ ~52 tok/s│  88   │ CLOSE     │
╰──────┴────────────────────────────────┴──────┴──────────┴──────────┴──────────┴───────┴───────────╯

🏆 Best Overall: mlx-community/Qwen3-30B-A3B-4bit (Score: 93/100)
   ✓ Fits comfortably in unified memory (3.2 GB headroom)
   ✓ Fast 58 tok/s generation throughput
   ✓ Efficient MoE design (3.0B active / 30.0B total)
   ✓ Large native context window (32k tokens)
   ✓ Exact Apple Silicon MLX benchmark measurement
```

---

## Documentation

- [Architecture Overview](docs/ARCHITECTURE.md)
- [Benchmark Data Sources & Attribution](docs/DATA_SOURCES.md)
- [Benchmark Methodology & Memory Modeling](docs/BENCHMARK_METHODOLOGY.md)

---

## License

[MIT License](LICENSE)
