ModelDock

The lightweight, Python-first model manager for local AI models — the package manager for local LLMs.

ModelDock discovers, downloads, caches, verifies, and loads local LLMs through pluggable runtime adapters. It does not run inference itself; it orchestrates runtimes (starting with Ollama). No more manual ollama pull commands — just write md.load("llama3") and ModelDock handles the rest.

Features

• Python-first API — md.load("llama3") auto-installs if missing and returns a ready client.
• Searchable registry — browse models, categories, capabilities, and sizes without leaving Python.
• Bulk installation — md.install_category("coding") pulls recommended models at once.
• Smart caching — never re-download installed models; content-addressed offline cache.
• Extensible runtimes — Ollama ships first; LM Studio, llama.cpp, Jan AI, GPT4All, vLLM are drop-in adapters.
• Cross-platform — Windows, macOS, Linux via platformdirs.
• Zero-config, beginner-friendly — dynamic catalog from ollama.com with offline caching.

Quick Start

Prerequisites

• Python 3.9–3.12
• A local Ollama install (for the first runtime)

Installation

pip install modeldock
# with the Ollama backend helper (optional):
pip install modeldock[ollama]

Basic Usage

import modeldock as md

# Auto-installs if missing, then returns a ready-to-use client
client = md.load("llama3")

print(client.chat(model="llama3", messages=[{"role": "user", "content": "Hi!"}]))

Installation

From PyPI

pip install modeldock

From Source

git clone https://github.com/OpenAgentHQ/modeldock.git
cd modeldock
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev,ollama]"

Usage

Discover and manage models

import modeldock as md

md.list()                       # browse the catalog
md.search("coding")             # search by name / capability / category
md.installed()                  # what's already local
md.info("qwen3")                # sizes, capabilities, variants
md.recommend(task="vision")     # guided pick

md.install("llama3")            # explicit download
md.install_category("coding")   # bulk install
md.update("llama3")             # pull newer tag
md.remove("llama3")             # uninstall
md.verify("llama3")             # integrity check

Command line

modeldock load llama3
modeldock install-category coding
modeldock list
modeldock search vision
modeldock cache status

See QUICKSTART.md for the full CLI/SDK reference.

Architecture

ModelDock follows Clean Architecture with SOLID principles. Dependencies point inward: cli → core → ports ← adapters. The domain and ports layers are pure (no I/O); concrete runtimes implement the RuntimePort protocol.

Interface:   modeldock/__init__.py (SDK)  +  modeldock/cli (Typer)
Application: modeldock/core/   (services, LifecycleOrchestrator, ModelManager)
Domain:      modeldock/domain/ (pure entities, no I/O)
Ports:       modeldock/ports/  (typing.Protocol interfaces)
Adapters:    modeldock/adapters/ (runtimes, registry, downloaders, cache, progress)
Common:      modeldock/common/ (config, logging, platform, http, errors)

Catalog Source

ModelDock scrapes ollama.com/library for a live model catalog, cached locally for 24 hours. Set catalog_source in config or MODELDOCK_CATALOG_SOURCE env var:

See Architecture.md for the full design contract.

Configuration

Config lives at ~/.config/modeldock/config.toml (Linux/macOS) or %APPDATA%\modeldock\config.toml (Windows). Env vars MODELDOCK_* override.

default_backend = "ollama"
auto_install    = true
log_level       = "INFO"
progress_style  = "rich"

Supported Runtimes

Documentation

Contributing

Contributions are welcome! See CONTRIBUTING.md for setup, branch naming, coding standards, and the PR process.

You can claim an issue to work on by commenting /claim on it — a maintainer will assign it to you.

Support

• Issues: GitHub Issues
• Documentation: see the links above

See SUPPORT.md for more options.

Security

To report security vulnerabilities, see SECURITY.md. Do not open public issues for security problems.

Changelog

See CHANGELOG.md for a list of changes.

Author

ModelDock is created and maintained by Himanshu kumar (OpenAgentHQ).

License

ModelDock is licensed under the MIT License — see LICENSE for details.