Module source_resolver

Expand description

CLI-level model source resolution.

Centralises the lookup chain that run / serve / bench were reinventing each in their own copy:

Curated GGUF alias — resolve an explicit quantized alias to one repository and filename.
GGUF file path — if the user passed an existing *.gguf file, build a ResolvedModelSource directly without HF lookup.
Local model dir — if the path is an existing directory with config.json + weights, treat it as a direct source.
HF cache hit — ~/.cache/huggingface/hub/models--<owner>--<repo>/snapshots/<rev>.
HF download — fall back to [HfDownloader] (run / serve only; bench callers may opt out).
GPU-memory autosizing — for GPU backends, run the chat autosizer once on the resolved snapshot so FERRUM_KV_MAX_BLOCKS etc. are populated before the engine starts.

Before this module each command had its own find_cached_model / detect_format (some forked, some pub fn-imported across files), its own GGUF early-return, and its own autosize call site. The duplication caused subtle drift (e.g. serve accepting a non-existent .gguf path because it didn’t call looks_like_gguf_path exactly the same way as run). All callers now go through resolve_model_source.

Structs§

ProductEngineInput: Atomic handoff from source resolution into a product engine composition. Keeping the original source inside the base config prevents entrypoints or architecture arms from retaining only the resolved cache path.
ProductSourceArgs: Explicit role-specific model metadata sources shared by run and serve. The physical weight source remains the positional MODEL argument.
Resolved: Resolution outcome — a fully-resolved local source plus a flag the caller can use to decide whether to apply GPU autosize.

Enums§

DownloadPolicy: Should the resolver attempt to download from HF if the model isn’t found locally? run / serve say yes; bench defaults to no (caller handles per-bench-flow download policy).

Constants§

CUDA_FIRST_SUCCESS_MODEL
METAL_FIRST_SUCCESS_MODEL: Small, release-supported starter models used by CLI guidance. These are intentionally not implicit defaults: users should see what will download.

Functions§

apply_chat_profile_env: Chat-profile runtime defaults for ferrum run. Sniffs the arch (dense vs MoE — works for both GGUF files and safetensors snapshot dirs) and materializes missing compatibility env vars for:
chat_profile_runtime_entries
detect_format: Detect the on-disk format of a model directory or file.
detect_model_family
detect_moe_arch: Detect whether path is a Mixture-of-Experts model. Handles both a .gguf file (peek general.architecture from GGUF metadata) and a safetensors snapshot directory (read config.json and match architectures / model_type against moe, case-insensitive).
find_cached_gguf: Locate one exact GGUF artifact in the Hugging Face cache.
find_cached_model: Look up model_id in the HF cache (hub/models--owner--repo/snapshots/<rev>). Returns the resolved snapshot path + detected format, or None if not cached.
first_success_model_help: Keep missing-model guidance identical for run and serve.
hf_cache_dir: Resolve the single Hugging Face cache root used by product entrypoints.
load_model_chat_template: Load a model-provided chat template, if the source carries one.
load_prepared_product_chat_template
load_product_chat_template: Load the chat template from bytes retained by the immutable tokenizer source lease. The legacy path-based loader remains for direct GGUF files.
looks_like_gguf_path: True iff model is a path to an existing *.gguf file.
metal_gguf_moe_correctness_entries: Correctness fallback for Metal GGUF MoE.
prepare_registered_product_model: Prepare a migrated typed family exactly once at the product composition boundary. Explicit legacy registrations return None; unknown metadata is rejected by the model registry instead of gaining an implicit fallback.
prepared_product_source_identity
public_model_id: Stable product-facing model id derived from one resolved source.
resolve_gguf_alias: Resolve a GGUF alias to its repository and exact quantized filename.
resolve_model_alias: Resolve an ergonomic model alias to its canonical Hugging Face model id.
resolve_model_source: One-stop model resolution. Caller passes the user’s model arg (alias / HF id / local dir / .gguf path), the HF cache dir, and a download policy + autosize profile. Returns a resolved source.
resolve_model_source_with_product_sources: Resolve one physical model and then replace only the explicitly selected semantic/tokenizer roles. This keeps the positional MODEL as the sole weight source while allowing quantized checkpoints to consume canonical base-model semantics without a model-name mapping or hidden environment.
serve_profile_runtime_entries: Product defaults for ferrum serve on GGUF LLMs.
serve_profile_runtime_entries_for_arch
tokenizer_sibling_repo: Resolve the tokenizer sidecar repository for a GGUF repository.