model-download-dev

# Model Download Developer Skill Help developers extend, test, debug, and integrate the Model Download microservice. > Codebase root: `microservices/model-download/` ## When to Use - Adding a new download or conversion plugin - Writing unit tests for a plugin (subprocess mocking, async fixtures) - Debugging a job stuck in `downloading` or `converting` - Understanding how `ModelManager`, `PluginRegistry`, or `PluginVenv` work - Extending the `ModelHub` enum or `Config` schema - Tracing plugin activation and `ACTIVATED_PLUGINS` env flow - Integrating model-download into a backend, gateway, Compose stack, Helm deployment, or CI/CD path - Designing app-side download/conversion workflows around `/models/download` and `/jobs/{job_id}` - Wiring model storage, health checks, plugin activation, and failure handling into a wider system - Adding or modifying MCP tools/resources/prompts in `src/mcp/` ## Reference Lookup | Reference | When to read | |-----------|-------------| | [plugin-architecture.md](./references/plugin-architecture.md) | Plugin interface contract, PluginRegistry, ModelManager, PluginVenv | | [testing-patterns.md](./references/testing-patterns.md) | Subprocess mocking, async fixtures, conftest patterns, parametrize | | [integration-patterns.md](./references/integration-patterns.md) | App-side architecture, request flow, polling, error handling, storage wiring | | [../../../docs/user-guide/get-started/using-mcp-server.md](../../../docs/user-guide/get-started/using-mcp-server.md) | MCP transports, client config (Claude Desktop, Copilot), tool/resource list | ## Example Prompts | File | Covers | |------|--------| | [examples-prompts/plugin-blueprint.md](./examples-prompts/plugin-blueprint.md) | Reusable skeleton for new downloader and converter plugins | | [examples-prompts/new-downloader-plugin.md](./examples-prompts/new-downloader-plugin.md) | Wire a new downloader plugin end-to-end | | [examples-prompts/writing-tests.md](./examples-prompts/writing-tests.md) | Unit test patterns for plugins with subprocess and async mocks | --- ## Plugin Architecture Summary ``` src/ ├── api/ │ ├── main.py ← FastAPI app, endpoints, job dispatch │ └── models.py ← Pydantic models, ModelHub enum, ModelType, Config ├── core/ │ ├── interfaces.py ← ModelDownloadPlugin ABC (plugin_name, plugin_type, can_handle, download) │ ├── model_manager.py ← Job lifecycle, ThreadPoolExecutor, status tracking │ ├── plugin_registry.py ← Auto-discovery, activation check, find_plugin_for_model │ └── plugin_venv.py ← Per-plugin venv management ├── mcp/ │ ├── server.py ← FastMCP app: tools (health_check, download_model, ...), │ │ resources (models://jobs, ...); reuses the same │ │ PluginRegistry/ModelManager as the REST API │ ├── __main__.py ← `python -m src.mcp` entrypoint (stdio/http transports) │ └── prompts.py ← Registers MCP prompts by reading the │ model-download-user skill's SKILL.md hub table and │ example-prompts/*.md at runtime └── plugins/ ├── __init__.py ← PLUGINS tuple mapping — register module path + class name here ├── huggingface_plugin.py ├── ollama_plugin.py ├── openvino_plugin.py ├── ultralytics_plugin.py ├── geti_plugin.py ├── hls_plugin.py └── pipeline_zoo_models_plugin.py ``` --- ## Procedure: Adding a New Plugin Read [plugin-architecture.md](./references/plugin-architecture.md) first, then use the example prompts in this order: 1. [examples-prompts/plugin-blueprint.md](./examples-prompts/plugin-blueprint.md) for the reusable class skeleton 2. [examples-prompts/new-downloader-plugin.md](./examples-prompts/new-downloader-plugin.md) for the end-to-end wiring 3. [examples-prompts/writing-tests.md](./examples-prompts/writing-tests.md) for the unit-test shape The minimum set of surfaces that must stay aligned is: 1. `plugin_name` in the class 2. the key in `src/plugins/__init__.py` 3. the `ModelHub` enum value in `src/api/models.py` 4. the optional dependency extra in `pyproject.toml` 5. activation support in `docker/entrypoint.sh` Use the current tuple-based plugin registration format: ```python PLUGINS = { # ... existing entries ... "myhub": ("src.plugins.myhub_plugin", "MyHubPlugin"), } ``` > [!IMPORTANT] > > - `ENABLED_PLUGINS` controls which modules are imported by `src/plugins/__init__.py` > - `ACTIVATED_PLUGINS` in `/opt/activated_plugins.env` is what `PluginRegistry` checks later > > If the plugin is implemented but does not appear in `/api/v1/plugins`, assume one of those > registration or activation surfaces is out of sync before you assume the core plugin logic is wrong. --- ## Procedure: Integrating into an Application or Platform Read [integration-patterns.md](./references/integration-patterns.md) first when the user is embedding model-download into another service or deployment stack. Start by identifying the integration role: - **Provisioning service**: pre-download models during deployment or CI/CD - **Runtime dependency**: app calls model-download on demand when a model is missing - **Ops/admin service**: internal tooling triggers downloads and exposes status to operators Prefer the public REST API as the integration boundary: 1. Check readiness with `GET /api/v1/health` 2. Submit work with `POST /api/v1/models/download?download_path=<subdir>` 3. Store the returned `job_id` 4. Poll `GET /api/v1/jobs/{job_id}` until `completed` or `failed` 5. Use the reported `download_path` or `conversion_path` Before proposing code or deployment changes, capture these decisions: | Concern | Decide | |---------|--------| | Trigger point | deploy time, app startup, first request, or admin action | | Model source | huggingface, ollama, ultralytics, openvino, geti, pipeline-zoo-models, hls | | Needed plugins | minimal `--plugins` list | | Persistence | where `MODEL_PATH` lives and which services mount it | | Completion model | synchronous wait in caller, async background job, or external orchestrator | | Failure behavior | retry, fail startup, partial availability, or operator intervention | Expected integration outputs include one or more of: - an application architecture recommendation - Docker Compose or Helm changes - app-side client code for submit + poll + result handling - env var, plugin, and storage/mount checklists - a failure-handling and retry strategy Ground recommendations in the current API, deployment scripts, and plugin activation flow. --- ## Procedure: Working with the MCP Server `src/mcp/server.py` is a FastMCP app mounted at `/mcp` in `src/api/main.py` (`mcp.http_app(path="/mcp", ...)` mounted onto the FastAPI app). It shares the same module-level `PluginRegistry` and `ModelManager` as the REST API — there is no separate job store or plugin state to keep in sync. Key points when changing MCP behavior: - **Adding/changing a tool**: add a `@mcp.tool` function in `server.py`. Mirror the equivalent REST endpoint's behavior (reuse `submit_models`, `model_manager`, `plugin_registry` — don't duplicate business logic). - **Adding/changing a resource**: add a `@mcp.resource("models://...")` function; return JSON strings (`json.dumps(..., default=str)`). - **Prompts are dynamic, not hard-coded**: `src/mcp/prompts.py` reads `.github/skills/model-download-user/example-prompts/*.md` and the `## Supported Hubs at a Glance` section of that skill's `SKILL.md` at server startup to register MCP prompts. If you rename that heading, rename or remove an example-prompt file, or move the skill directory, prompt registration breaks or silently drops prompts — check `register_skill_prompts()` after touching those files. - **Standalone vs mounted runtime**: `python -m src.mcp` builds its own `PluginRegistry`/`ModelManager` at import time (module-level globals in `server.py`). When mounted inside the FastAPI app, `main.py` calls `configure_runtime(...)` to swap in the app's shared instances instead — keep any new global runtime state wired through `configure_runtime` so both modes stay consistent. - **Testing**: `tests/test_mcp_server.py` patches `src.mcp.server.plugin_registry` and `src.mcp.server.model_manager` with `MagicMock`s via an autouse fixture, then imports and calls the tool functions directly (not through an MCP client). Follow that pattern for new tools. See [testing-patterns.md](./references/testing-patterns.md) for the full example. --- ## Procedure: Debugging a Stuck Job Read [plugin-architecture.md](./references/plugin-architecture.md) → "Job Lifecycle" section. **Quick diagnosis checklist:** ```bash # 1. Check service logs for exceptions docker logs model-download 2>&1 | tail -100 # 2. Inspect the job status curl -s http://localhost:8200/api/v1/jobs/<job-id> # 3. Verify the plugin was activated and discovered curl -s http://localhost:8200/api/v1/plugins # Or via MCP: call the `list_plugins` tool / read the `models://plugins` resource # 4. Test the plugin in isolation python3 -c " import asyncio from src.plugins.myhub_plugin import MyHubPlugin p = MyHubPlugin() result = asyncio.run(p.download('my-model', '/tmp/test')) print(result) " ``` Common causes of stuck jobs: - Plugin raised an exception that was swallowed — check logs - Plugin is blocking the event loop (use `asyncio.to_thread` for sync I/O) - Lock held by a crashed previous job (Ollama `_ollama_download_lock`) — restart container - Plugin was implemented but not activated — verify `docker/entrypoint.sh`, `ENABLED_PLUGINS`, and `ACTIVATED_PLUGINS` - Job submitted via MCP behaves like REST (same `ModelManager`) — if only the MCP path is stuck, check that `main.py` called `configure_runtime(...)` so `src/mcp/server.py` isn't using its own separate module-level instances