Metadata-Version: 2.4
Name: ollama-doctor
Version: 0.1.0
Summary: Pre-flight checker for local Ollama models
Author: Randy Christehusz
Project-URL: Homepage, https://github.com/onederlnd/ollama-doctor.git
Project-URL: Repository, https://github.com/onederlnd/ollama-doctor.git
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests
Requires-Dist: psutil

# Ollama Doctor

A lightweight command-line utility for checking local Ollama models — RAM fit, side-by-side comparisons, and real response-time benchmarks — before you build anything around them.

## Overview

Ollama Doctor helps you understand your local Ollama environment by:

* Listing installed Ollama models with estimated RAM needs and download size
* Comparing multiple models' RAM requirements side by side
* Checking whether a specific model fits your available system memory
* Benchmarking a model's real response time and suggesting a timeout value
* Showing what's currently loaded in memory right now

The goal is to catch problems — like a model needing more RAM than you have — in seconds, instead of discovering it partway through building something around it.

## Features

### `list` — installed models

```
MODEL                      EST. RAM   DOWNLOAD    STATUS
--------------------------------------------------------
llama3.1:8b                  6.0 GB     4.6 GB    Fits
deepseek-r1:14b              10.5 GB    9.0 GB    Fits
```

### `check` — does one model fit?

```
$ ollama-doctor check llama3.1:8b
PASS - llama3.1:8b (4.6GB) fits in available RAM (23.4GB)
```

### `compare` — multiple models side by side

```
$ ollama-doctor compare llama3.1:8b deepseek-r1:14b llama3.1:70b
PASS - llama3.1:8b (4.6GB) fits in available RAM (23.4GB)
PASS - deepseek-r1:14b (9.0GB) fits in available RAM (23.4GB)
FAIL - llama3.1:70b (42.0GB) needs 18.6GB more RAM than available (23.4GB)
```

### `bench` — real response time

```
$ ollama-doctor bench llama3.1:8b
llama3.1:8b: 0.19s response time — suggested timeout: 0.57s
```

### `status` — what's loaded right now

Shows currently loaded models (from Ollama's `/api/ps`) plus current available RAM.

## RAM Estimation

For models without a known downloaded size (or for quick comparison), estimation uses a simple heuristic based on parameter count:

```
Estimated RAM = Model Parameters (B) × 0.75 GB
```

Examples:

```
8B model  → ~6 GB RAM
14B model → ~10.5 GB RAM
70B model → ~52.5 GB RAM
```

This is a rough estimate tuned for typical 4-bit quantized Ollama models — actual usage varies by quantization level. For installed models, `list` also shows real download size, which is a more accurate fit signal than the estimate alone.

## Project Structure

```
ollama-doctor/
│
├── ollama_doctor/
│   ├── cli.py              # argparse entrypoint, wires up all subcommands
│   ├── ollama_api.py       # local Ollama client — /api/tags, /api/ps, /api/generate
│   ├── system.py           # available RAM check (psutil)
│   ├── catalog.py          # ollamadb.dev client (planned — not yet wired in)
│   ├── estimate.py         # parameter-size → RAM estimate heuristic
│   │
│   └── commands/
│       ├── check.py        # ollama-doctor check <model>
│       ├── compare.py      # ollama-doctor compare <model1> <model2> ...
│       ├── list.py         # ollama-doctor list
│       ├── bench.py        # ollama-doctor bench <model>
│       └── status.py       # ollama-doctor status
│
├── README.md
└── pyproject.toml
```

## Installation

```bash
git clone <repository-url>
cd ollama-doctor
pip install -e .
```

This registers the `ollama-doctor` command via the project's entry point — no need to invoke modules directly.

## Usage

```bash
ollama-doctor list
ollama-doctor check llama3.1:8b
ollama-doctor compare llama3.1:8b deepseek-r1:14b llama3.1:70b
ollama-doctor bench llama3.1:8b
ollama-doctor status
```

## Requirements

* Python 3.9+
* Ollama installed and running locally
* `requests`, `psutil`

## Current Limitations

Model name parsing (`estimate.py`) is currently optimized for simple `parameter_size` labels as returned by Ollama's API (e.g. `"8.0B"`).

Not yet handling variation in quantization suffixes within model tags themselves, e.g.:

```
deepseek-r1:70b-q4_K_M
gemma3:27b-it
```

## Future Improvements

Planned features:

* `list --fits` / `--role draft|review` / `--search` filters
* Colored terminal output
* More accurate RAM estimates based on quantization level
* GPU/VRAM detection
* Automatic Ollama health diagnostics
* Support for more complex model tag formats

## License

MIT License
