ollama-advisor

A Python library that recommends Ollama models you can run on your machine, based on system specs (RAM, GPU VRAM) and use case (coding, reasoning, vision, embedding, audio, general). It also supports downloading, running, and stopping models.

Works on Mac, Windows, Linux, and Google Colab.

Korean documentation: README.ko.md

pip install ollama-advisor

Local development install:

git clone https://github.com/dschloe/ollama-advisor.git
cd ollama-advisor
pip install -e ".[dev]"

import ollama_advisor as oa

oa.recommend()                       # Full recommendations (returns a DataFrame)
oa.recommend(purpose="coding")       # Filter for coding models only
oa.pull_model("qwen2.5-coder:7b")    # Download a model
oa.run_model("qwen2.5-coder:7b", prompt="hello")  # Single-shot (non-interactive) run
oa.stop_model("qwen2.5-coder:7b")    # Stop / unload a running model
oa.list_installed()                  # List locally installed models

# Top 5 coding models that fit this machine
oa.recommend(purpose="coding", top_n=5)

# Reasoning models, return as a plain list instead of DataFrame
oa.recommend(purpose="reasoning", as_dataframe=False)

# Refresh catalog from ollama.com, then filter for vision
oa.recommend(purpose="vision", force_refresh=True)

# Embedding-only models (excludes general chat models)
oa.recommend(purpose="embedding")

CLI:

ollama-advisor recommend --purpose coding
ollama-advisor pull qwen2.5-coder:7b
ollama-advisor run qwen2.5-coder:7b --prompt "hello"
ollama-advisor stop qwen2.5-coder:7b
ollama-advisor list
ollama-advisor ps
ollama-advisor specs
ollama-advisor snapshot --force-refresh

GitHub Actions (catalog-daily.yml) crawls ollama.com/library once per day and commits CSV/JSON under data/catalog/.

ollama-advisor snapshot --output data/catalog --force-refresh

recommend() and get_system_specs() work without Ollama installed.
pull_model, run_model, stop_model, list_installed, and related commands require a local Ollama server.

• Download: https://ollama.com/download
• macOS: brew install ollama, then ollama serve (or launch the app)
• Windows: run the installer, then start the tray app
• Linux: curl -fsSL https://ollama.com/install.sh | sh

If the Ollama server is not running, an OllamaError is raised with platform-specific setup instructions (error messages in the library may be localized).

recommend() works without Ollama. For pull_model / run_model / list_installed, call setup_colab_ollama() once per runtime:

!pip install -q ollama-advisor

import ollama_advisor as oa

# Recommendations — no Ollama server needed
oa.recommend(purpose="coding", top_n=5)

# Install + start Ollama in this Colab VM (installs zstd, then Ollama, then serve)
oa.setup_colab_ollama()

# Then pull / run (small models work best on free Colab RAM)
oa.pull_model("qwen2.5-coder:0.5b")
print(oa.run_model("qwen2.5-coder:0.5b", prompt="hello"))

Colab does not keep Ollama running after the runtime disconnects — models and server state reset.

In notebooks and Colab, recommend() automatically displays a scrollable HTML table.

Memory estimate (approx. 4-bit quantization): required_gb = billions × 0.6 + 1.0

pip install -e ".[dev]"
pytest tests/ -v

CI (test.yml) runs on Ubuntu / Windows / macOS with Python 3.9 and 3.11. Network crawling is mocked in tests.

1. Create an account at pypi.org
2. Confirm the name ollama-advisor is available (alternatives: ollama-model-advisor)
3. The project is created on first upload, or when using Trusted Publisher

1. PyPI → Account settings → Publishing → Add a new pending publisher
2. Configure (add two publishers — PyPI Trusted Publishing does not support reusable workflows):
   • Publisher A (manual): Workflow name publish.yml, Environment pypi
   • Publisher B (auto): Workflow name release-on-version.yml, Environment pypi
   • Shared fields: PyPI project ollama-advisor, Owner/Repo dschloe/ollama-advisor
3. Optionally add deployment protection rules under GitHub → Settings → Environments → pypi

OIDC publish uses pypa/gh-action-pypi-publish—no API token required in CI.

Automatic (preferred): bump version in pyproject.toml (and __version__), merge to main.
Workflow release-on-version.yml creates tag vX.Y.Z + GitHub Release and uploads to PyPI.

Manual fallback:

git tag v0.1.2
git push origin v0.1.2

Publish a GitHub Release for that tag (or let the automation create it). Then:

1. publish.yml runs pytest as a gate
2. On success, uploads wheel/sdist to PyPI

Manual local upload (debugging only):

python -m build
twine upload dist/*

Updated daily via GitHub Actions

MIT — see LICENSE