Skip to contents

Fetches a GGUF model file over HTTPS into a local cache and returns its path. model is either a pinned alias from the package's model registry (see the Details section) or a full https:// URL. The download is fail-closed: for a registry alias the file's SHA256 must match the pinned value or the file is deleted and relm_error_download is raised. Nothing downloaded is ever executed — the file is only written to disk and checksummed.

Usage

llm_download(model, dir = NULL, quiet = FALSE)

Arguments

model

Single string: a registry alias (see Details) or a full https:// URL to a GGUF file.

dir

NULL (the user cache directory) or a single string naming the directory to download into (created recursively if missing). Use a directory only you can write to; downloading into a world-writable/shared directory is not supported.

quiet

Single logical. TRUE suppresses the download progress bar and the informational messages. Default FALSE.

Value

The local file path, returned invisibly. Errors: relm_error_argument (bad model/dir/quiet type), relm_error_download (non-HTTPS URL, unknown alias, network failure, checksum mismatch, or an unwritable directory).

Details

Registry aliases. The package ships a small registry (inst/models.csv) of license-clean, checksum-pinned models. The current aliases are:

  • "spark-x2.5-4b-q8_0" — Spark-X2.5 4B, Q8_0 (Apache-2.0); optional text model, requiring the b10828 engine. Activation tracing is unsupported; it is not a default CI download.

  • "qwen2.5-0.5b-instruct-q8_0" — Qwen2.5 0.5B Instruct, Q8_0 (Apache-2.0); the small CI-integration model.

  • "qwen2.5-1.5b-instruct-q4_k_m" — Qwen2.5 1.5B Instruct, Q4_K_M (Apache-2.0); the demo default.

  • "qwen2-vl-2b-instruct-q4_k_m" — Qwen2-VL 2B Instruct, Q4_K_M (Apache-2.0); the vision default. Pair it with the projector alias below: llm(path, projector = ).

  • "qwen2-vl-2b-instruct-mmproj-f16" — the mmproj (vision projector) companion of the alias above (Apache-2.0, same pinned revision); pass its path as llm()'s projector.

Passing an unknown alias raises relm_error_download and lists the known aliases. The registry contains only the pinned single-file entries above; it is not a catalog of every compatible GGUF. Other models can be supplied by local path to llm(), subject to engine compatibility and the model's license and access requirements. This downloader does not handle authenticated access.

Full URLs. A full https:// URL is downloaded as given. Only HTTPS is accepted (http://, ftp://, file://, ... are rejected). A bare URL has no pinned checksum, so the file cannot be verified; it is downloaded and its computed SHA256 is reported so you can pin it — the function never presents an unverifiable file as if it had been verified.

Caching. dir = NULL uses the per-user cache directory tools::R_user_dir("relm", "cache"); the directory is created if missing. The target file name is the URL's last path segment. If a registry model is already present and its checksum matches, the download is skipped (idempotent, offline-friendly); a present-but-mismatching file is treated as corrupt and re-downloaded. A bare URL has no pinned checksum, so a same-named cached file cannot be shown to have come from that URL and is never reused – a bare URL is always re-fetched. Verification happens on a temporary file that is only moved into place once it passes, so the final path never holds unverified bytes. Downloads follow HTTPS redirects; for a registry alias the pinned checksum still guards integrity end-to-end, so a redirect cannot substitute the bytes.

This is one of only two functions in the package that write outside a session temporary directory (the other is llm_trace() spill); see the package's side-effect contract.

See also

Examples

# The default download directory (dir = NULL); no network access is performed:
tools::R_user_dir("relm", "cache")
#> [1] "/home/runner/.cache/R/relm"

if (FALSE) { # \dontrun{
# Fetch a pinned, checksum-verified model and load it:
path <- llm_download("qwen2.5-0.5b-instruct-q8_0")
m <- llm(path)
} # }