car-inference 0.53.0

//! Derive a [`ModelSchema`] from a HuggingFace repo, so adopting a new model
//! does not require shipping a CAR release.
//!
//! The built-in catalog is compiled in. That made *learning a model exists* a
//! release-gated operation, which is why it once went seven weeks without a new
//! text entry while the open-weight world moved through three Qwen generations.
//! Hand-authoring a `ModelSchema` JSON for `car models register` was the only
//! escape hatch, and it asked the user to know CAR's internal enum spellings.
//!
//! This module reads what the repo already declares — `config.json` plus the
//! file listing — and produces a registerable schema. The load-bearing decision
//! is the one the user cannot be expected to make: whether the checkpoint has an
//! in-process Rust backend ([`ModelSource::Mlx`]) or has to go through the
//! supervised external runtime ([`ModelSource::VllmMlx`]). That answer lives in
//! [`backend::local::native_backend_serves`](crate::backend::local::native_backend_serves)
//! and is applied here, so `qwen3_5`, `glm4_moe_lite`, and every family that
//! lands next month route correctly without anyone editing Rust. It considers
//! the quantization as well as the architecture: the native loader decodes
//! affine and `mxfp8` only, and finding that out after downloading the weights
//! is not a routing decision.
//!
//! Derived schemas are always [`TrustTier::Community`]: they are user-directed,
//! not project-vetted, and must never be eligible for background auto-apply.

use serde_json::Value;

use crate::schema::{
    CostModel, ModelCapability, ModelSchema, ModelSource, PerformanceEnvelope, Quantization,
    TrustTier,
};
use crate::InferenceError;

/// A schema derived from a repo, plus the facts that decided its shape.
#[derive(Debug, Clone)]
pub struct DerivedModel {
    pub schema: ModelSchema,
    /// The repo's declared `config.json` `model_type`.
    pub model_type: String,
    /// True when an in-process Rust backend services `model_type` on this
    /// build; false means the schema points at the external runtime.
    pub native: bool,
}

/// Build a registerable [`ModelSchema`] for `repo` (e.g.
/// `mlx-community/Qwen3.8-27B-4bit`) from what HuggingFace already publishes.
///
/// Two public endpoints are read: `config.json` for the architecture, and the
/// repo file listing for on-disk size. Nothing is downloaded.
pub async fn derive_from_hf_repo(repo: &str) -> Result<DerivedModel, InferenceError> {
    let repo = repo.trim().trim_matches('/');
    if repo.split('/').count() != 2 || repo.split('/').any(str::is_empty) {
        return Err(InferenceError::InferenceFailed(format!(
            "`{repo}` is not a HuggingFace repo id — expected `org/name`"
        )));
    }

    let config = fetch_config(repo).await?;
    let listing = fetch_repo_listing(repo).await.unwrap_or_default();
    let size_bytes = listing.total_bytes;

    // A repo that carries a config but no weights derives into a perfectly
    // well-formed schema that can never load. Catching it here costs one
    // already-fetched listing; catching it at inference time costs a confusing
    // runtime error, minutes later, inside whatever job was running.
    if listing.observed && !listing.has_weights {
        return Err(InferenceError::InferenceFailed(format!(
            "{repo}: no model weights found (no .safetensors, .bin, or .gguf files). \
             If this is a base repo that only holds a config, use one of its \
             quantized conversions instead."
        )));
    }

    let model_type = config
        .get("model_type")
        .and_then(Value::as_str)
        .unwrap_or_default()
        .to_ascii_lowercase();
    if model_type.is_empty() {
        return Err(InferenceError::InferenceFailed(format!(
            "{repo}: config.json declares no `model_type`, so CAR cannot tell \
             which backend should serve it"
        )));
    }

    // Which weight format the repo actually ships decides the source before the
    // architecture does. Neither MLX loader nor the vLLM-MLX runtime reads
    // GGUF, so a GGUF-only repo derived to either of those is a row that
    // downloads and then cannot load.
    let gguf_only = listing.observed && !listing.has_safetensors && !listing.gguf_files.is_empty();
    let gguf_weight_file = if gguf_only {
        Some(single_loadable_gguf(repo, &model_type, &listing)?)
    } else {
        None
    };

    let declared = quantization_of(&config);
    // A GGUF file names its quantization in its own filename; `config.json`
    // describes the unquantized parent and says nothing about it.
    let quantization = match &gguf_weight_file {
        Some(file) => Quantization::from_gguf_filename(file),
        None => declared.known().cloned(),
    };
    let bits = quantization.as_ref().and_then(|q| q.bits);
    // Architecture AND weight layout. `has_native_backend` alone would route an
    // `mxfp4` qwen3 to the in-process loader, which fetches the whole checkpoint
    // and then refuses it — the external runtime serves it today. A GGUF repo is
    // never native: those loaders read safetensors.
    let native = gguf_weight_file.is_none()
        && crate::backend::local::has_native_backend(&model_type)
        && declared.decodable();
    let size_mb = size_bytes / 1_000_000;

    let schema = ModelSchema {
        id: derive_id(repo, bits),
        name: basename(repo).to_string(),
        provider: org(repo).to_ascii_lowercase(),
        family: model_type.clone(),
        version: String::new(),
        capabilities: capabilities(&config),
        context_length: context_length(&config),
        max_output_tokens: None,
        param_count: String::new(),
        quantization,
        performance: PerformanceEnvelope::default(),
        cost: CostModel {
            size_mb: (size_mb > 0).then_some(size_mb),
            // Weights plus working set. Deliberately generous: under-declaring
            // makes the router pick a model the machine cannot hold.
            ram_mb: (size_mb > 0).then(|| size_mb + size_mb / 4),
            ..Default::default()
        },
        source: if let Some(file) = gguf_weight_file.clone() {
            // The Candle GGUF path. `tokenizer_repo` is this repo because the
            // listing showed a `tokenizer.json` in it — `single_loadable_gguf`
            // refuses rather than guess at a base repo's name.
            ModelSource::Local {
                hf_repo: repo.to_string(),
                hf_filename: file,
                tokenizer_repo: repo.to_string(),
            }
        } else if native {
            ModelSource::Mlx {
                hf_repo: repo.to_string(),
                hf_weight_file: None,
            }
        } else {
            // `ManagedVllmMlx`, not `VllmMlx`: the latter is operator-owned and
            // assumes a server someone else is running. Nothing provisions it
            // (`vllm_live_schema` passes it straight through), nothing fetches
            // its weights (`ensure_local_inner` answers "not local"), and it is
            // unavailable unless `VLLM_MLX_ENDPOINT` is set — so a derived
            // schema landing there is a model the user cannot run. Every
            // built-in catalog entry in this situation uses the managed source;
            // this was the one place that did not.
            ModelSource::ManagedVllmMlx {
                hf_repo: repo.to_string(),
                hf_weight_file: None,
            }
        },
        tags: {
            let mut t = vec![
                "derived".to_string(),
                "local".to_string(),
                model_type.clone(),
            ];
            t.push(
                if gguf_weight_file.is_some() {
                    "gguf"
                } else if native {
                    "native-mlx"
                } else {
                    "vllm-mlx"
                }
                .to_string(),
            );
            if is_moe(&config) {
                t.push("moe".to_string());
            }
            t
        },
        supported_params: Vec::new(),
        public_benchmarks: Vec::new(),
        trust_tier: TrustTier::Community,
        deprecated: false,
        available: false,
        weights_ready: false,
    };

    Ok(DerivedModel {
        schema,
        model_type,
        native,
    })
}

async fn fetch_config(repo: &str) -> Result<Value, InferenceError> {
    let url = format!("https://huggingface.co/{repo}/resolve/main/config.json");
    // `model_download_client`, not `Client::new()`: the latter panics when the
    // OS trust store yields zero valid certificates. huggingface.co is public,
    // so the public-CA rung serves this fully.
    crate::tls_client::model_download_client()
        .get(&url)
        .send()
        .await
        .map_err(|e| InferenceError::InferenceFailed(format!("fetch {repo} config.json: {e}")))?
        .error_for_status()
        .map_err(|e| {
            InferenceError::InferenceFailed(format!(
                "{repo}: no readable config.json ({e}) — check the repo id"
            ))
        })?
        .json()
        .await
        .map_err(|e| InferenceError::InferenceFailed(format!("parse {repo} config.json: {e}")))
}

/// What the repo's file listing tells us: total size, and whether any of it is
/// actually model weights.
#[derive(Debug, Default)]
struct RepoListing {
    total_bytes: u64,
    has_weights: bool,
    /// Safetensors are what the MLX loaders and the external runtime both read.
    /// A repo without them is not servable by either, whatever its `model_type`
    /// says.
    has_safetensors: bool,
    /// GGUF weight files, in listing order. A GGUF repo is servable, but by the
    /// Candle path (`ModelSource::Local`) — a different source entirely.
    gguf_files: Vec<String>,
    /// `ModelSource::Local` fetches `tokenizer.json` from a named repo. GGUF
    /// conversions usually carry their own; the ones that do not cannot be
    /// derived, because the base repo's name is a guess.
    has_tokenizer_json: bool,
    /// False when the listing could not be fetched at all, so callers do not
    /// mistake "we could not look" for "there is nothing there".
    observed: bool,
}

/// Fetch the repo's file listing. Best-effort for sizing: a failure degrades
/// the schema rather than failing the call, and leaves `observed` false so the
/// weights check does not fire on a network hiccup.
async fn fetch_repo_listing(repo: &str) -> Result<RepoListing, InferenceError> {
    let url = format!("https://huggingface.co/api/models/{repo}?blobs=true");
    let info: Value = crate::tls_client::model_download_client()
        .get(&url)
        .send()
        .await
        .map_err(|e| InferenceError::InferenceFailed(e.to_string()))?
        .error_for_status()
        .map_err(|e| InferenceError::InferenceFailed(e.to_string()))?
        .json()
        .await
        .map_err(|e| InferenceError::InferenceFailed(e.to_string()))?;

    let files = info.get("siblings").and_then(Value::as_array);
    let total_bytes = files
        .map(|f| {
            f.iter()
                .filter_map(|f| f.get("size").and_then(Value::as_u64))
                .sum()
        })
        .unwrap_or(0);
    let names: Vec<&str> = files
        .map(|f| {
            f.iter()
                .filter_map(|f| f.get("rfilename").and_then(Value::as_str))
                .collect()
        })
        .unwrap_or_default();
    let lower = |n: &str| n.to_ascii_lowercase();
    Ok(RepoListing {
        total_bytes,
        has_weights: names.iter().any(|n| is_weight_file(n)),
        has_safetensors: names.iter().any(|n| lower(n).ends_with(".safetensors")),
        gguf_files: names
            .iter()
            .filter(|n| lower(n).ends_with(".gguf"))
            .map(|n| (*n).to_string())
            .collect(),
        has_tokenizer_json: names
            .iter()
            .any(|n| lower(n).rsplit('/').next() == Some("tokenizer.json")),
        observed: true,
    })
}

/// The one GGUF file CAR can serve from this repo, or a refusal explaining why
/// it cannot.
///
/// Two things make a GGUF repo underivable, and both are better said now than
/// discovered mid-download:
///
/// - **No `tokenizer.json`.** `ModelSource::Local` fetches one by repo name,
///   and the base repo's name is not recoverable from a conversion's — the
///   `-GGUF` suffix convention is a convention, and a wrong guess is a 404
///   minutes into a fetch.
/// - **A split checkpoint.** `download_file` fetches a single blob into
///   `model.gguf`; taking part one of a shard set produces a truncated file
///   that fails to parse.
fn single_loadable_gguf(
    repo: &str,
    model_type: &str,
    listing: &RepoListing,
) -> Result<String, InferenceError> {
    // GGUF is not how a machine runs the best model it can, and CAR's GGUF path
    // is not a general one. On Apple Silicon `backend::candle` is not compiled
    // at all — MLX is the local path there and it reads safetensors — and
    // elsewhere the Candle loader implements Qwen3 and Qwen3-MoE. Deriving
    // anything else here hands the user a row with no backend behind it and
    // steers them off the runtime their hardware actually wants.
    if !crate::backend::local::gguf_backend_serves(model_type) {
        let alternative = if cfg!(all(
            target_os = "macos",
            target_arch = "aarch64",
            not(car_skip_mlx)
        )) {
            "this machine runs local models through MLX, which reads safetensors — \
             an `mlx-community` conversion of this model is the one you want"
        } else {
            "this machine runs local models through CUDA on safetensors, and CAR's \
             GGUF path implements only Qwen3"
        };
        return Err(InferenceError::InferenceFailed(format!(
            "{repo}: GGUF weights for '{model_type}', which no backend on this build \
             loads. {alternative}."
        )));
    }

    let shard = |name: &str| {
        let lower = name.to_ascii_lowercase();
        lower.contains("-of-") && lower.ends_with(".gguf")
    };
    let whole: Vec<&String> = listing.gguf_files.iter().filter(|f| !shard(f)).collect();

    let Some(file) = whole.first() else {
        return Err(InferenceError::InferenceFailed(format!(
            "{repo}: its GGUF weights are split across shards, which CAR cannot \
             assemble. Use a single-file quantization from the same repo."
        )));
    };
    if whole.len() > 1 {
        // Several independent quantizations in one repo — the usual layout for
        // a community conversion. Which one is the user's call, not a coin flip.
        let mut names: Vec<&str> = whole.iter().map(|f| f.as_str()).collect();
        names.sort_unstable();
        return Err(InferenceError::InferenceFailed(format!(
            "{repo}: carries {} GGUF quantizations ({}). CAR cannot pick one for \
             you — register the specific file you want.",
            names.len(),
            names.join(", ")
        )));
    }
    if !listing.has_tokenizer_json {
        return Err(InferenceError::InferenceFailed(format!(
            "{repo}: GGUF weights but no tokenizer.json, which the local loader \
             downloads by repo name. Point CAR at a repo that carries both, or \
             register a schema naming the tokenizer repo explicitly."
        )));
    }
    Ok((*file).clone())
}

/// Whether `name` is a model weight file in any format CAR's backends load.
fn is_weight_file(name: &str) -> bool {
    let lower = name.to_ascii_lowercase();
    [".safetensors", ".gguf", ".bin", ".npz"]
        .iter()
        .any(|ext| lower.ends_with(ext))
}

/// `config.json` may nest the language-model fields under `text_config` on
/// multimodal repos. Look in both places before giving up.
fn nested<'a>(config: &'a Value, key: &str) -> Option<&'a Value> {
    config.get(key).or_else(|| {
        config
            .get("text_config")
            .and_then(|t| t.get(key))
            .filter(|v| !v.is_null())
    })
}

fn context_length(config: &Value) -> usize {
    nested(config, "max_position_embeddings")
        .and_then(Value::as_u64)
        .unwrap_or(32_768) as usize
}

/// The full `quantization` block MLX writes into `config.json`:
/// `{bits, group_size, mode}`. All three matter — `bits` alone cannot
/// distinguish an affine group quant from an MX float at the same width, and
/// the group size is what a kernel has to match.
///
/// Returns `None` unless the block is an object carrying at least one of them.
/// `Value::get` yields `Some(Value::Null)` for an explicit `"quantization":
/// null` and the field is absent on unquantized checkpoints, so a laxer guard
/// here would report every full-precision model as affine group-quantized.
/// What a repo's `config.json` says about quantization.
///
/// The three cases are genuinely different and collapsing the last two into
/// `None` is what made an unreadable block route native: `Value::as_u64`
/// returns `None` for `"bits": 4.0` (a JSON float) and for `"bits": "4"`, so a
/// malformed block looked exactly like an unquantized checkpoint. It is not —
/// `backend::mlx` deserializes `bits` as `i32` and fails the whole config parse,
/// after the download.
#[derive(Debug, PartialEq, Eq)]
enum DeclaredQuantization {
    /// No block at all: a full-precision checkpoint on the dense path.
    Absent,
    /// A block CAR read.
    Known(Quantization),
    /// A block that is present and says nothing usable. Routes external, where
    /// a runtime that parses more shapes than CAR does can have a go.
    Unreadable,
}

impl DeclaredQuantization {
    fn known(&self) -> Option<&Quantization> {
        match self {
            Self::Known(q) => Some(q),
            _ => None,
        }
    }

    /// Whether the native loader can serve what was declared.
    fn decodable(&self) -> bool {
        match self {
            Self::Absent => true,
            Self::Known(q) => crate::backend::local::quantization_is_decodable(Some(q)),
            Self::Unreadable => false,
        }
    }
}

fn quantization_of(config: &Value) -> DeclaredQuantization {
    // Both spellings, because `backend::mlx_gemma4` reads both and a checkpoint
    // publishing only `quantization_config` is invisible under the first name.
    let Some(block) = config
        .get("quantization")
        .filter(|v| v.is_object())
        .or_else(|| config.get("quantization_config").filter(|v| v.is_object()))
    else {
        // Absent, or present as something other than an object — a scalar or
        // null is not a declaration CAR can act on, and there is nothing to
        // read either way.
        return match config
            .get("quantization")
            .or_else(|| config.get("quantization_config"))
        {
            Some(v) if !v.is_null() => DeclaredQuantization::Unreadable,
            _ => DeclaredQuantization::Absent,
        };
    };

    // A HuggingFace `quant_method` block (awq, gptq, bitsandbytes) is a format
    // the native loader has no path for at all. It does not merely fail: with
    // no `quantization` block to key on, `build_qlinear` skips the quantized
    // branch entirely and builds a dense layer from the packed weight, which is
    // the silent garbage-output bug in car-releases#61. Classify it so
    // admission routes it to the external runtime, which does transform it.
    if let Some(method) = block.get("quant_method").and_then(Value::as_str) {
        let bits = block
            .get("bits")
            .and_then(Value::as_u64)
            .and_then(|b| u8::try_from(b).ok());
        return DeclaredQuantization::Known(Quantization {
            bits,
            scheme: crate::schema::QuantScheme::Unknown,
            group_size: block
                .get("group_size")
                .and_then(Value::as_u64)
                .and_then(|g| u32::try_from(g).ok()),
            label: method.to_ascii_lowercase(),
        });
    }
    // Widths and group sizes are small; a value that does not fit is bad
    // metadata, not something to truncate into a plausible-looking number.
    let bits = block
        .get("bits")
        .and_then(Value::as_u64)
        .and_then(|b| u8::try_from(b).ok());
    let group_size = block
        .get("group_size")
        .and_then(Value::as_u64)
        .and_then(|g| u32::try_from(g).ok());
    let mode = block.get("mode").and_then(Value::as_str);
    match Quantization::from_mlx_config(bits, group_size, mode) {
        Some(q) => DeclaredQuantization::Known(q),
        // An object was published and none of its fields parsed.
        None => DeclaredQuantization::Unreadable,
    }
}

fn is_moe(config: &Value) -> bool {
    nested(config, "num_experts")
        .and_then(Value::as_u64)
        .is_some_and(|n| n > 1)
}

/// Capabilities a text LLM is assumed to have, plus vision when the repo
/// declares a vision tower.
///
/// Deliberately conservative about vision — claiming it wrongly makes the
/// router send images to a model that cannot see them — and deliberately
/// generous about the text set, which every instruct-tuned LLM services.
fn capabilities(config: &Value) -> Vec<ModelCapability> {
    let mut caps = vec![
        ModelCapability::Generate,
        ModelCapability::Code,
        ModelCapability::Reasoning,
        ModelCapability::Summarize,
        ModelCapability::ToolUse,
        ModelCapability::MultiToolCall,
    ];
    // `language_model_only` is authoritative when present: the Qwen3.5+ line
    // unified vision into the base config, so a text-only *conversion* still
    // carries `vision_config` and the image token ids from its parent. Trusting
    // the tower's presence alone would claim vision for a checkpoint whose
    // vision weights were stripped.
    let text_only = config
        .get("language_model_only")
        .and_then(Value::as_bool)
        .unwrap_or(false);
    let has_vision_tower = config.get("vision_config").is_some()
        || config.get("image_token_id").is_some()
        || config.get("image_token_index").is_some();
    if has_vision_tower && !text_only {
        caps.push(ModelCapability::Vision);
    }
    caps
}

fn org(repo: &str) -> &str {
    repo.split('/').next().unwrap_or("custom")
}

fn basename(repo: &str) -> &str {
    repo.rsplit('/').next().unwrap_or(repo)
}

/// `custom/<repo-basename>` lowercased, with the quantization as the variant
/// tag so two quantizations of one model do not collide.
fn derive_id(repo: &str, bits: Option<u8>) -> String {
    let base = basename(repo).to_ascii_lowercase();
    match bits {
        Some(b) => format!("custom/{base}:{b}bit"),
        None => format!("custom/{base}"),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    #[test]
    fn rejects_a_non_repo_id() {
        let err = tokio::runtime::Runtime::new()
            .unwrap()
            .block_on(derive_from_hf_repo("Qwen3.8-27B"))
            .unwrap_err();
        assert!(err.to_string().contains("org/name"), "got {err}");
    }

    #[test]
    fn context_falls_back_to_text_config() {
        let c = json!({ "text_config": { "max_position_embeddings": 262144 } });
        assert_eq!(context_length(&c), 262_144);
    }

    #[test]
    fn vision_is_claimed_only_when_declared() {
        let text_only = json!({ "model_type": "qwen3" });
        assert!(!capabilities(&text_only).contains(&ModelCapability::Vision));

        let vlm = json!({ "model_type": "qwen3_vl", "vision_config": {} });
        assert!(capabilities(&vlm).contains(&ModelCapability::Vision));

        // A text-only conversion of a multimodal base keeps the parent's
        // `vision_config`; `language_model_only` is what distinguishes it.
        let stripped = json!({
            "model_type": "qwen3_5",
            "vision_config": { "depth": 27 },
            "image_token_id": 248056,
            "language_model_only": true
        });
        assert!(
            !capabilities(&stripped).contains(&ModelCapability::Vision),
            "a language_model_only conversion must not claim vision"
        );
    }

    #[test]
    fn quantization_block_is_read_whole_or_not_at_all() {
        let full = json!({
            "quantization": { "bits": 8, "group_size": 32, "mode": "mxfp8" }
        });
        let q = quantization_of(&full)
            .known()
            .cloned()
            .expect("a real block must parse");
        assert_eq!(q.bits, Some(8));
        assert_eq!(q.group_size, Some(32), "group size must not be dropped");
        assert_eq!(q.scheme, crate::schema::QuantScheme::BlockScaledFloat);

        // `Value::get` returns `Some(Null)` for an explicit null, and the key
        // is simply absent on full-precision checkpoints. Neither is a claim
        // that the weights are affine group-quantized.
        // Absent, or explicitly null: a full-precision checkpoint. Native is
        // the right answer and the dense path serves it.
        for absent in [json!({ "quantization": null }), json!({})] {
            assert_eq!(
                quantization_of(&absent),
                DeclaredQuantization::Absent,
                "must not invent a scheme from {absent}"
            );
            assert!(quantization_of(&absent).decodable());
        }

        // Present and unusable is NOT the same as absent. `as_u64` yields None
        // for a JSON float and for a string, so these once looked exactly like
        // an unquantized checkpoint — routed native, downloaded, and then
        // failed `backend::mlx`'s `bits: i32` parse.
        for unreadable in [
            json!({ "quantization": "Q4_K_M" }),
            json!({ "quantization": {} }),
            json!({ "quantization": { "bits": 4.0 } }),
            json!({ "quantization": { "bits": "4" } }),
        ] {
            assert_eq!(
                quantization_of(&unreadable),
                DeclaredQuantization::Unreadable,
                "a present-but-unreadable block is not an unquantized model: {unreadable}"
            );
            assert!(
                !quantization_of(&unreadable).decodable(),
                "must not route native on a block it could not read: {unreadable}"
            );
        }
    }

    /// The native loader decodes affine and `mxfp8`; anything else microscaling
    /// it refuses while reading weights, which is after the download. The
    /// admission gate has to reach the same answer from `config.json` alone.
    ///
    /// (Asserts the predicate, not the derived `source` — building a schema
    /// requires network I/O. The source mapping is exercised in
    /// `backend::local::native_admission_tests`.)
    #[test]
    fn an_undecodable_layout_fails_admission_not_weight_loading() {
        use crate::backend::local::native_backend_serves;

        let affine = quantization_of(&json!({
            "quantization": { "bits": 4, "group_size": 64 }
        }))
        .known()
        .cloned();
        let mxfp4 = quantization_of(&json!({
            "quantization": { "bits": 4, "group_size": 32, "mode": "mxfp4" }
        }))
        .known()
        .cloned();

        // Same architecture, same width — only the layout differs.
        assert_eq!(
            native_backend_serves("qwen3", affine.as_ref()),
            crate::backend::local::has_native_backend("qwen3")
        );
        assert!(!native_backend_serves("qwen3", mxfp4.as_ref()));
    }

    /// `backend::mlx_gemma4` reads either spelling, so a checkpoint declaring
    /// only `quantization_config` must not look unquantized here.
    #[test]
    fn both_spellings_of_the_quantization_block_are_read() {
        let q = quantization_of(&json!({
            "quantization_config": { "bits": 4, "group_size": 32, "mode": "mxfp4" }
        }))
        .known()
        .cloned()
        .expect("quantization_config must be read");
        assert_eq!(q.scheme, crate::schema::QuantScheme::BlockScaledFloat);
        assert!(!crate::backend::local::quantization_is_decodable(Some(&q)));
    }

    /// An `awq`/`gptq`/`bitsandbytes` block is the dangerous case: the native
    /// loader has no path for it AND does not refuse it — with no MLX
    /// `quantization` block to key on it builds a dense layer straight from the
    /// packed weight and emits garbage. Admission has to catch it.
    #[test]
    fn huggingface_quant_methods_are_refused() {
        for method in ["awq", "gptq", "bitsandbytes"] {
            let q = quantization_of(&json!({
                "quantization_config": { "quant_method": method, "bits": 4, "group_size": 128 }
            }))
            .known()
            .cloned()
            .unwrap_or_else(|| panic!("{method} block must be recognized as quantized"));
            assert_eq!(q.label, method);
            assert_eq!(q.bits, Some(4));
            assert_eq!(q.group_size, Some(128));
            assert!(
                !crate::backend::local::quantization_is_decodable(Some(&q)),
                "{method} has no native path and must not be admitted"
            );
        }
    }

    /// Mirrors `fetch_repo_listing`'s classification: `gguf_files` holds only
    /// `.gguf` entries, so a fixture passes a whole file listing.
    fn gguf_listing(files: &[&str], tokenizer: bool) -> RepoListing {
        RepoListing {
            total_bytes: 1,
            has_weights: files.iter().any(|f| is_weight_file(f)),
            has_safetensors: files
                .iter()
                .any(|f| f.to_ascii_lowercase().ends_with(".safetensors")),
            gguf_files: files
                .iter()
                .filter(|f| f.to_ascii_lowercase().ends_with(".gguf"))
                .map(|f| (*f).to_string())
                .collect(),
            has_tokenizer_json: tokenizer,
            observed: true,
        }
    }

    /// Neither MLX loader nor vLLM-MLX reads GGUF, so a GGUF-only repo has to
    /// take the Candle path. Deriving it to an MLX source produced a row that
    /// downloaded and then could not load.
    /// Where a GGUF backend exists, a single-file Qwen3 repo with a tokenizer
    /// derives — and its quantization comes from the filename, not from
    /// `config.json`, which describes the unquantized parent.
    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    #[test]
    fn a_single_gguf_with_a_tokenizer_is_derivable() {
        let listing = gguf_listing(&["Qwen3-8B-Q4_K_M.gguf", "tokenizer.json"], true);
        let file =
            single_loadable_gguf("Qwen/Qwen3-8B-GGUF", "qwen3", &listing).expect("derivable");
        assert_eq!(file, "Qwen3-8B-Q4_K_M.gguf");

        let q = Quantization::from_gguf_filename(&file).unwrap();
        assert_eq!(q.label, "Q4_K_M");
        assert_eq!(q.scheme, crate::schema::QuantScheme::KQuantMixed);
    }

    /// The rule the reviewer-facing bug was: GGUF is not how a machine runs the
    /// best model it can. On Apple Silicon `backend::candle` is not compiled at
    /// all, so every GGUF repo is refused with a pointer at MLX; elsewhere only
    /// the architectures the Candle loader implements get through, and the rest
    /// are pointed at safetensors on CUDA.
    #[test]
    fn gguf_is_refused_where_no_backend_reads_it() {
        let listing = gguf_listing(&["m-Q4_K_M.gguf", "tokenizer.json"], true);

        let err = single_loadable_gguf("acme/Llama-3-8B-GGUF", "llama", &listing)
            .unwrap_err()
            .to_string();
        assert!(err.contains("llama"), "must name the architecture: {err}");
        assert!(
            err.contains("safetensors"),
            "must point at the format the machine's real backend reads: {err}"
        );

        // On a Mac that applies to Qwen3 too — there is no GGUF loader there.
        let qwen3 = single_loadable_gguf("Qwen/Qwen3-8B-GGUF", "qwen3", &listing);
        if cfg!(all(
            target_os = "macos",
            target_arch = "aarch64",
            not(car_skip_mlx)
        )) {
            let err = qwen3.unwrap_err().to_string();
            assert!(err.contains("MLX"), "a Mac must be steered to MLX: {err}");
        } else {
            assert!(qwen3.is_ok(), "Qwen3 GGUF is served off Apple Silicon");
        }
    }

    /// The three layout refusals, each said before a download rather than
    /// during one. Only reachable where a GGUF backend exists at all — on
    /// Apple Silicon the platform check refuses first, which
    /// `gguf_is_refused_where_no_backend_reads_it` covers.
    #[cfg(not(all(target_os = "macos", target_arch = "aarch64", not(car_skip_mlx))))]
    #[test]
    fn underivable_gguf_repos_are_refused_with_the_reason() {
        // No tokenizer: `ModelSource::Local` fetches one by repo name and the
        // base repo's name is a guess.
        let err = single_loadable_gguf(
            "acme/model-GGUF",
            "qwen3",
            &gguf_listing(&["m-Q4_K_M.gguf"], false),
        )
        .unwrap_err()
        .to_string();
        assert!(err.contains("tokenizer.json"), "got {err}");

        // Several quantizations: picking one is the user's call.
        let err = single_loadable_gguf(
            "acme/model-GGUF",
            "qwen3",
            &gguf_listing(&["m-Q4_K_M.gguf", "m-Q8_0.gguf"], true),
        )
        .unwrap_err()
        .to_string();
        assert!(err.contains("Q4_K_M") && err.contains("Q8_0"), "got {err}");

        // Sharded: `download_file` fetches one blob, so part one alone is a
        // truncated file that fails to parse.
        let err = single_loadable_gguf(
            "acme/model-GGUF",
            "qwen3",
            &gguf_listing(
                &[
                    "m-Q4_K_M-00001-of-00002.gguf",
                    "m-Q4_K_M-00002-of-00002.gguf",
                ],
                true,
            ),
        )
        .unwrap_err()
        .to_string();
        assert!(err.contains("split across shards"), "got {err}");
    }

    /// A repo with both formats is not a GGUF repo — safetensors win, and the
    /// MLX/external decision proceeds as before.
    #[test]
    fn safetensors_alongside_gguf_is_not_a_gguf_repo() {
        let listing = gguf_listing(&["model.safetensors", "m-Q4_K_M.gguf"], true);
        assert!(
            !(listing.observed && !listing.has_safetensors && !listing.gguf_files.is_empty()),
            "safetensors must take precedence"
        );
    }

    #[test]
    fn id_keeps_quantizations_distinct() {
        assert_eq!(
            derive_id("mlx-community/Qwen3.8-27B-4bit", Some(4)),
            "custom/qwen3.8-27b-4bit:4bit"
        );
        assert_ne!(
            derive_id("mlx-community/Qwen3.8-27B-4bit", Some(4)),
            derive_id("mlx-community/Qwen3.8-27B-8bit", Some(8))
        );
    }

    #[test]
    fn weight_files_are_recognized_across_formats() {
        for name in [
            "model-00001-of-00003.safetensors",
            "model.gguf",
            "pytorch_model.bin",
            "weights.npz",
            "MODEL.SAFETENSORS",
        ] {
            assert!(is_weight_file(name), "{name} should count as weights");
        }
        for name in [
            "config.json",
            "tokenizer.json",
            "README.md",
            "chat_template.jinja",
            ".gitattributes",
        ] {
            assert!(!is_weight_file(name), "{name} is not weights");
        }
    }

    /// A repo that carries a config but no weights derives into a well-formed
    /// schema that can never load. "Could not look" must not be confused with
    /// "there is nothing there", so the check only fires on an observed listing.
    #[test]
    fn an_unobserved_listing_does_not_trigger_the_weights_check() {
        let unobserved = RepoListing::default();
        assert!(!unobserved.observed);
        assert!(!unobserved.has_weights);
        // The guard is `observed && !has_weights`; with `observed` false a
        // network hiccup must not be reported as an empty repo.
        assert!(
            !(unobserved.observed && !unobserved.has_weights),
            "a failed listing must not be reported as a weightless repo"
        );
    }

    #[test]
    fn moe_needs_more_than_one_expert() {
        assert!(is_moe(&json!({ "num_experts": 128 })));
        assert!(!is_moe(&json!({ "num_experts": 1 })));
        assert!(!is_moe(&json!({})));
    }

    /// The decision this module exists to make: an architecture with no Rust
    /// backend must route to the external runtime rather than being rejected.
    #[test]
    fn unknown_architectures_are_not_native() {
        assert!(!crate::backend::local::has_native_backend("qwen3_5"));
        assert!(!crate::backend::local::has_native_backend("qwen3_5_moe"));
        assert!(!crate::backend::local::has_native_backend("glm4_moe_lite"));
    }

    #[test]
    fn known_architectures_are_native_on_apple_silicon() {
        let expected = cfg!(all(
            target_os = "macos",
            target_arch = "aarch64",
            not(car_skip_mlx)
        ));
        assert_eq!(
            crate::backend::local::has_native_backend("qwen3_moe"),
            expected
        );
        assert_eq!(
            crate::backend::local::has_native_backend("gemma4_unified"),
            expected
        );
    }
}