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.
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.
TRUEsuppresses the download progress bar and the informational messages. DefaultFALSE.
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 asllm()'sprojector.
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.
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)
} # }