Metadata-Version: 2.4
Name: mac-ai-doctor
Version: 0.2.0
Summary: Transparent unified-memory fit estimates for local AI models
Project-URL: Homepage, https://github.com/barvhaim/mac-ai-doctor
Project-URL: Repository, https://github.com/barvhaim/mac-ai-doctor
Project-URL: Issues, https://github.com/barvhaim/mac-ai-doctor/issues
Author-email: barvhaim <barvhaim@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: apple-silicon,cli,gguf,llm,mlx,unified-memory
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.27
Requires-Dist: rich<15,>=13
Requires-Dist: typer<1,>=0.12
Provides-Extra: web
Requires-Dist: streamlit<2,>=1.30; extra == 'web'
Description-Content-Type: text/markdown

# 🩺 Mac AI Doctor

**Will this AI model fit in your Apple Silicon Mac's unified memory?**

`maid` reads small metadata files—never model weights—and estimates weight, KV-cache, and runtime
memory as a range, then gives a plain verdict.

```text
$ maid check ibm-granite/granite-switch-4.1-3b-preview --memory-gb 16

     ibm-granite/granite-switch-4.1-3b-preview
┌────────────┬────────────────┐
│ Weights    │        8.80 GB │
│ KV cache   │        0.34 GB │
│ Runtime    │        1.31 GB │
│ Peak range │ 11.49–13.06 GB │
│ Available  │        16.0 GB │
└────────────┴────────────────┘
╭───────────────────── TIGHT · high confidence ──────────────────────╮
│ May fit, but close memory-heavy apps or reduce context/concurrency. │
╰─────────────────────────────────────────────────────────────────────╯
```

## Install

Requires [uv](https://docs.astral.sh/uv/).

```bash
uv tool install mac-ai-doctor          # CLI only
uv tool install 'mac-ai-doctor[web]'    # also enables `maid web`
```

## Use

```bash
maid web                                                 # interactive web UI (needs the 'web' extra)
maid system                                              # your chip and memory
maid check meta-llama/Llama-3.1-8B-Instruct              # a Hugging Face model
maid check ~/Models/model-q4.gguf --context 8192         # a local GGUF
maid compare org/model-a org/model-b --concurrency 2     # side by side
maid recommend --memory-gb 16 --task coding              # a starting point
maid check MODEL --json                                  # machine-readable
```

Accepts a Hugging Face ID, a local `.gguf` file, or a local/MLX directory with `config.json`.

**Options:** `--memory-gb N` (required off macOS), `--context`, `--concurrency`,
`--kv-dtype` (`fp32`/`fp16`/`bf16`/`int8`/`q8`), `--json`. Tasks: `coding`, `chat`, `vision`.

## Verdicts

| Verdict | Meaning |
| --- | --- |
| **COMFORTABLE** | High estimate ≤ 80% of memory. |
| **TIGHT** | Fits, but leaves < 20% headroom. |
| **UNLIKELY** | Exceeds memory. |
| **UNKNOWN** | Weight size unavailable. |

Confidence reflects metadata completeness, not prediction accuracy.

## What it reads

Only bounded metadata: `config.json`, the safetensors index, and the model API's file-size
listing—or the 24-byte header of a local GGUF. **Weight contents are never downloaded.** No
credentials are collected.

## How it estimates

Decimal GB. This is screening, not a benchmark—verify with your actual runtime. **No tokens/second
prediction is made.**

```text
weights = stored_weight_bytes × 1.06
KV      = 2 × layers × KV_heads × head_dim × context × concurrency × dtype_bytes
runtime = max(1 GB, weights × 12%) + 0.25 GB × concurrency
range   = subtotal × 1.10 .. subtotal × 1.25
```

Unified memory is shared with macOS, apps, and the GPU. Memory mapping can help; multimodal image
encoders may add memory not shown in text config metadata.

## Troubleshooting

- **Can't detect memory** — pass `--memory-gb N` (auto-detection needs macOS).
- **401/403 or gated** — authenticate, or point at a downloaded `config.json`.
- **No weight size** — use a repo with a safetensors index/API sizes, or a local GGUF (v2/v3).

## Develop

```bash
git clone https://github.com/barvhaim/mac-ai-doctor.git && cd mac-ai-doctor
uv sync --group dev
uv run ruff check . && uv run mypy src && uv run pytest
```

See [CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed.
