Model Download User

<!--
SPDX-FileCopyrightText: (C) 2026 Intel Corporation
SPDX-License-Identifier: Apache-2.0
-->

Model Download Agent

Set up the Model Download microservice and walk the user through downloading or converting any supported model using the REST API or the MCP server.

Preview: This skill is in preview — share feedback to help improve it.

When to Use

• User wants to download a model from HuggingFace, Ollama, Ultralytics, Geti, Pipeline Zoo, or HLS
• User wants to convert a HuggingFace model to OpenVINO IR format for OVMS deployment
• User asks about model precision conversion (INT4/INT8/FP16/FP32)
• User needs to target a specific device (CPU, GPU, NPU, or HETERO combinations like HETERO:GPU,CPU)
• User wants to download healthcare AI models (3D Pose, rPPG, AI-ECG)
• User is integrating model downloads into a Docker Compose workflow

MCP Server (Alternative to REST)

Every Model Download deployment also exposes an MCP server at /mcp alongside the REST API, so agents like Claude Desktop, GitHub Copilot, and custom MCP clients can call the service directly as tools instead of issuing raw curl requests.

• Same service, same port (8200) — no separate process required for the container deployment; uv run python -m src.mcp runs it standalone (stdio) for local/agent-only use.
• Tools mirror the REST surface: health_check, download_model, get_job_status, list_jobs, cancel_job, get_model_jobs, get_model_results, list_plugins, list_hub_models.
• Resources: models://jobs, models://jobs/{job_id}, models://results, models://plugins.
• If the user's request comes through an MCP client (Claude Desktop, Copilot with the model-download MCP server connected, etc.), prefer calling the matching MCP tool directly instead of constructing a curl command — the tool signatures accept the same fields (name, hub, type, is_ovms, config, revision, download_path), and download_model additionally accepts top-level override_credentials (a dict such as {"HF_TOKEN": "<base64-encoded-token>"}) and validate_credentials (bool) — the same per-request, base64-encoded auth override available on the REST endpoint. list_hub_models also accepts override_credentials for listing models on a gated/private hub.
• Full client setup (Claude Desktop / Copilot config, HTTP client example, verification steps) lives in docs/user-guide/get-started/using-mcp-server.md — read it when the user asks to configure or troubleshoot an MCP client.

Note: this skill's "Supported Hubs at a Glance" table and the example-prompts/ files are also served live as MCP prompts by src/mcp/prompts.py. Keep the heading text and file names stable when editing them.

Supported Hubs at a Glance

Gated HuggingFace Models — Token Handling

Applies to both hub: "huggingface" and hub: "openvino" (the OpenVINO converter downloads the source weights from HuggingFace before converting, so gated-model auth works identically for conversion requests).

There are two distinct ways to supply an HF token, and they use different encodings — mixing them up is the most common gated-model failure:

Encode a token before putting it in override_credentials:

echo -n 'hf_xxx' | base64

If the user's request arrives through the MCP client and the model is gated, prefer override_credentials with a base64-encoded HF_TOKEN over asking them to restart the whole service with a new environment variable — it avoids a container restart. For is_ovms conversion requests, also set validate_credentials: true so a bad/wrongly-encoded token is caught before the (often multi-minute) conversion runs, instead of failing only after it completes.

CLI failure scenario: If a base64-encoded token is exported for get_model.sh (or passed as HUGGINGFACEHUB_API_TOKEN/HF_TOKEN to run_service.sh up), authentication fails with 401 Unauthorized / Repository ... is gated even though the token looks "set" — the CLI and compose startup path send the value through unmodified, so a base64 string is not a valid HF token. This applies to --hub huggingface and --hub openvino CLI invocations alike. See troubleshooting.md for the fix.

Ollama Quick-Reference

Always use these exact field names for Ollama requests — the API differs from what generic model-download documentation implies.

{
  "models": [
    {
      "hub": "ollama",
      "name": "<model-family>",
      "revision": "<tag>"
    }
  ]
}

• hub must be "ollama" (not model_hub, not type)
• name is the base model family: "llama3.2", "mistral", "gemma2" (no tag suffix)
• revision is the tag: "3b", "7b", "latest" (separate field, not model_name)
• Port is always 8200 (not 8080, not 8000)
• Plugin flag: source scripts/run_service.sh up --plugins ollama

Example — download llama3.2:3b:

curl -s -X POST "http://localhost:8200/api/v1/models/download?download_path=ollama-models" \
  -H "Content-Type: application/json" \
  -d '{"models": [{"hub": "ollama", "name": "llama3.2", "revision": "3b"}]}'

Common Mistakes to Avoid