ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.
Python ai-agentsamdcomfyuidockerllama-cppllmlocal-ain8nnvidiaopen-webuiragself-hostedspeech-to-textstrix-halotext-to-speechworkflow-automation
"""Pre-download facts about a Hugging Face GGUF (pure functions)."""
import json
import pytest
import model_preflight as preflight
from model_memory import estimate_model_memory
POLICY = {
"backendBuilds": {"nvidia": "b11429", "cpu": "b9014", "amd": "b9014",
"apple": "b9014", "windows-native": "b9014"},
"builds": {
"b9014": {"architectures": ["gemma2", "llama", "qwen3", "qwen35"]},
"b11429": {"architectures": ["gemma2", "llama", "nanbeige", "qwen3", "qwen35"]},
},
}
def _header(architecture="qwen3", template="{% if tools %}<tool_call>{% endif %}", **extra):
metadata = {"general.architecture": architecture}
if template is not None:
metadata["tokenizer.chat_template"] = template
metadata.update(extra.pop("metadata", {}))
header = {"architecture": architecture, "metadata": metadata}
header.update(extra)
return header
# --- runtime policy ---------------------------------------------------------
def test_load_runtime_policy_rejects_missing_or_malformed(tmp_path):
assert preflight.load_runtime_policy(tmp_path / "missing.json") is None
bad = tmp_path / "bad.json"
bad.write_text("{not json", encoding="utf-8")
assert preflight.load_runtime_policy(bad) is None
wrong = tmp_path / "wrong.json"
wrong.write_text(json.dumps({"builds": {}}), encoding="utf-8")
assert preflight.load_runtime_policy(wrong) is None
good = tmp_path / "good.json"
good.write_text(json.dumps(POLICY), encoding="utf-8")
assert preflight.load_runtime_policy(good) == POLICY
@pytest.mark.parametrize("backend,windows_hosted,key,build", [
("nvidia", False, "nvidia", "b11429"),
("NVIDIA", False, "nvidia", "b11429"),
("amd", False, "amd", "b9014"),
("apple", False, "apple", "b9014"),
("", False, "cpu", "b9014"),
("none", False, "cpu", "b9014"),
("amd", True, "windows-native", "b9014"),
("nvidia", True, "windows-native", "b9014"),
("jetson", False, "jetson", None),
])
def test_effective_build_follows_the_backend_policy(backend, windows_hosted, key, build):
assert preflight.effective_build(POLICY, backend, windows_hosted=windows_hosted) == (key, build)
def test_a_model_image_names_its_own_build():
image = "ghcr.io/ggml-org/llama.cpp:server-cuda-b9014@sha256:" + "f" * 64
assert preflight.effective_build(POLICY, "nvidia", windows_hosted=False, model_image=image) == ("nvidia", "b9014")
def test_effective_build_without_policy_is_unknown():
assert preflight.effective_build(None, "nvidia", windows_hosted=False) == ("nvidia", None)
@pytest.mark.parametrize("build,architecture,expected", [
("b11429", "nanbeige", True),
("b9014", "nanbeige", False),
("b9014", "qwen35", True),
("b9014", "", None),
(None, "qwen3", None),
("b1", "qwen3", None),
])
def test_architecture_support(build, architecture, expected):
assert preflight.architecture_supported(POLICY, build, architecture) is expected
# --- model kind -------------------------------------------------------------
@pytest.mark.parametrize("header,pipeline,tags,kind", [
(_header("clip", metadata={"clip.has_vision_encoder": True}), "", [], "projector"),
(_header("qwen3", metadata={"tokenizer.chat_template.rerank": "{{ query }}"}), "", [], "reranker"),
(_header("qwen3", metadata={"qwen3.classifier.output_labels": ["yes", "no"]}), "", [], "reranker"),
(_header("qwen3", metadata={"qwen3.pooling_type": 4}), "", [], "reranker"),
(_header("nomic-bert", metadata={"nomic-bert.pooling_type": 1}), "", [], "embedding"),
(_header("gemma3", metadata={"gemma3.attention.causal": False}), "", [], "embedding"),
(_header("qwen3tts"), "", [], "speech"),
(_header("qwen3"), "text-generation", [], "chat"),
(None, "text-ranking", [], "reranker"),
(None, "", ["text-ranking"], "reranker"),
(None, "sentence-similarity", [], "embedding"),
(None, "", ["sentence-transformers"], "embedding"),
(None, "automatic-speech-recognition", [], "speech"),
(None, "text-to-image", [], "image"),
(None, "", [], "chat"),
])
def test_model_kind(header, pipeline, tags, kind):
assert preflight.model_kind(header, pipeline, tags) == kind
def test_header_overrides_a_chat_pipeline_tag():
# The live Qwen3-Reranker GGUF is tagged conversational; its header says rerank.
header = _header("qwen3", metadata={"qwen3.pooling_type": 4})
assert preflight.model_kind(header, "text-generation", ["conversational"]) == "reranker"
# --- template signals -------------------------------------------------------
@pytest.mark.parametrize("template,tools,thinking", [
("{% if tools %}<tool_call>{% endif %}{% if enable_thinking %}<think>{% endif %}", True, "toggle"),
("<|start|>{{ reasoning_effort }}<|channel|>analysis", False, "effort"),
("{{ messages }}<think>\n", False, "tags"),
("{% for m in messages %}{{ m.content }}{% endfor %}", False, "none"),
("{% for call in message.tool_calls %}{% endfor %}", True, "none"),
])
def test_template_signals(template, tools, thinking):
signals = preflight.template_signals(_header(template=template))
assert signals == {"present": True, "tools": tools, "thinking": thinking}
def test_template_signals_without_template_or_header():
assert preflight.template_signals(_header(template=None)) == {
"present": False, "tools": False, "thinking": "none"}
assert preflight.template_signals(None) == {
"present": None, "tools": None, "thinking": "unknown"}
# --- memory layout ----------------------------------------------------------
def _dense_header():
return {
"architecture": "llama", "context_length": 131072, "block_count": 32,
"embedding_length": 4096, "attention_head_count": 32, "attention_head_count_kv": 8,
"attention_key_length": 128, "attention_value_length": 128,
"full_attention_interval": None, "ssm_conv_kernel": None, "ssm_inner_size": None,
"ssm_state_size": None, "ssm_group_count": None, "ssm_time_step_rank": None,
"metadata": {"general.architecture": "llama"},
}
def test_dense_layout_is_marked_reviewed_for_the_architecture_estimate():
fields = preflight.memory_fields(_dense_header())
assert fields["recurrent_state_bytes"] == 0
assert fields["max_context_length"] == 131072
model = {**fields, "size_bytes": 4 * 1024 ** 3, "context_length": 32768}
estimate = estimate_model_memory(model, context_length=32768)
assert estimate.method == "architecture"
# 32 layers x 8 KV heads x (128 + 128) x 2 bytes = 128 KiB per token.
assert estimate.kv_bytes_per_token == 32 * 8 * (128 + 128) * 2
@pytest.mark.parametrize("change", [
{"full_attention_interval": 4},
{"ssm_state_size": 128},
{"attention_head_count_kv": [8] * 32},
{"metadata": {"llama.attention.sliding_window": 4096}},
{"metadata": {"llama.attention.sliding_window_pattern": 6}},
])
def test_non_dense_layouts_keep_the_rough_estimate(change):
header = _dense_header()
header.update(change)
fields = preflight.memory_fields(header)
assert "recurrent_state_bytes" not in fields
model = {**fields, "size_bytes": 4 * 1024 ** 3, "size_mb": 4096, "context_length": 32768}
assert estimate_model_memory(model, context_length=32768).method == "legacy-heuristic"
def test_memory_fields_without_a_header():
assert preflight.memory_fields(None) == {}
# --- disk and refusals -------------------------------------------------------
@pytest.mark.parametrize("needed,storage,status", [
(10, {"freeBytes": 20, "marginBytes": 5}, "ok"),
(10, {"freeBytes": 15, "marginBytes": 5}, "ok"),
(10, {"freeBytes": 14, "marginBytes": 5}, "insufficient"),
(10, None, "unknown"),
(10, {"freeBytes": "x", "marginBytes": 5}, "unknown"),
])
def test_disk_status(needed, storage, status):
assert preflight.disk_status(needed, storage) == status
def test_refusals_need_positive_evidence():
assert preflight.refusal("chat", None, "qwen3", None) is None
assert preflight.refusal("chat", True, "qwen3", "b9014") is None
runtime = preflight.refusal("chat", False, "nanbeige", "b9014")
assert runtime["code"] == "runtime_architecture_unsupported"
assert runtime["overridable"] is True
assert "b9014" in runtime["message"] and "nanbeige" in runtime["message"]
kind = preflight.refusal("reranker", None, "qwen3", "b9014")
assert kind == {
"code": "not_a_chat_model:reranker",
"message": preflight.KIND_MESSAGES["reranker"],
"overridable": False,
}
def test_a_gated_repository_is_refused_before_the_runtime_check():
gated = preflight.refusal("chat", False, "nanbeige", "b9014", gated=True)
assert gated == {"code": "gated", "message": preflight.GATED_MESSAGE, "overridable": False}
# Not being a chat model outranks access: a token would not make an embedding model chat-capable.
assert preflight.refusal("embedding", None, "nomic-bert", "b9014", gated=True)["code"] == "not_a_chat_model:embedding"
TENSOR_POLICY = {
"backendBuilds": {"nvidia": "b11429", "amd": "b9014"},
"builds": {
"b9014": {"architectures": ["llama"], "tensorTypes": {"F32": 0, "F16": 1, "Q8_0": 8, "Q4_K": 12,
"Q6_K": 14, "IQ2_XXS": 16, "MXFP4": 39, "NVFP4": 40}},
"b11429": {"architectures": ["llama"], "tensorTypes": {"F32": 0, "F16": 1, "Q8_0": 8, "Q4_K": 12,
"Q6_K": 14, "IQ2_XXS": 16, "MXFP4": 39, "NVFP4": 40,
"Q2_0": 42}},
},
}
@pytest.mark.parametrize("build, header_types, status, unknown", [
("b9014", [0, 12, 14], "ok", []),
("b9014", [0, 42], "unsupported", ["Q2_0"]), # newer than this build
("b11429", [0, 42], "ok", []),
("b9014", [0, 77], "unsupported", ["type 77"]), # newer than any pinned build
])
def test_tensor_check_from_the_files_own_header(build, header_types, status, unknown):
check = preflight.artifact_tensor_check(TENSOR_POLICY, build, "Q4_K_M", header_types)
assert check == {"status": status, "unknown": unknown, "source": "header"}
@pytest.mark.parametrize("label, status, unknown", [
("Q2_0", "unsupported", ["Q2_0"]),
("UD-Q2_0", "unsupported", ["Q2_0"]),
("Q4_K_M", "ok", []), # Q4_K_M is stored as Q4_K
("IQ2_XXS", "ok", []), # an exact type name is not stripped to IQ2
("MXFP4", "ok", []),
("IQ2_M", "unknown", []), # no ggml type by that name: no claim
("Q4_K_M-imatrix", "unknown", []),
(None, "unknown", []),
])
def test_tensor_check_from_a_label_that_names_a_type(label, status, unknown):
check = preflight.artifact_tensor_check(TENSOR_POLICY, "b9014", label)
assert (check["status"], check["unknown"]) == (status, unknown)
def test_tensor_check_without_a_type_table_makes_no_claim():
assert preflight.artifact_tensor_check({"builds": {"b9014": {}}}, "b9014", "Q2_0", [42])["status"] == "unknown"
assert preflight.artifact_tensor_check(None, None, "Q2_0")["status"] == "unknown"
def test_tensor_refusal_names_the_types_and_build_and_can_be_overridden():
refusal = preflight.tensor_refusal("b9014", ["Q2_0"])
assert refusal["code"] == "runtime_tensor_type_unsupported"
assert refusal["overridable"] is True
assert "Q2_0" in refusal["message"] and "b9014" in refusal["message"]
def test_the_committed_policy_lists_tensor_types_for_every_build():
import json
from pathlib import Path
policy = json.loads((Path(__file__).resolve().parents[4] / "config" / "llama-cpp-architectures.json")
.read_text(encoding="utf-8"))
for build, entry in policy["builds"].items():
types = entry["tensorTypes"]
assert types["F32"] == 0 and types["Q4_K"] == 12, build
assert 4 not in types.values(), f"{build}: removed Q4_2 must not be listed"
assert "Q2_0" in policy["builds"]["b11429"]["tensorTypes"]
assert "Q2_0" not in policy["builds"]["b9014"]["tensorTypes"]
@pytest.mark.parametrize("metadata, layers", [
({"qwen35.nextn_predict_layers": 1}, 1),
({"qwen35.nextn_predict_layers": 0}, 0),
({"qwen35.nextn_predict_layers": True}, 0),
({"qwen35.nextn_predict_layers": "1"}, 0),
({}, 0),
])
def test_nextn_layers_reads_only_a_positive_integer(metadata, layers):
assert preflight.nextn_layers({"metadata": {"general.architecture": "qwen35", **metadata}}) == layers
assert preflight.nextn_layers(None) == 0
def test_nextn_support_is_known_only_from_the_policy():
policy = {"builds": {"b9014": {"nextnLoader": False, "nextnArchitectures": ["glm4moe"]}, "b11429": {"nextnLoader": True}, "b1": {"nextnLoader": False}}}
assert preflight.nextn_supported(policy, "b9014", "qwen35") is False
assert preflight.nextn_supported(policy, "b9014", "glm4moe") is True
assert preflight.nextn_supported(policy, "b9014") is None
assert preflight.nextn_supported(policy, "b11429") is True
assert preflight.nextn_supported(policy, "b1") is None
assert preflight.nextn_supported(policy, None) is None
assert preflight.nextn_supported(None, "b9014") is None
def test_the_shipped_policy_knows_which_builds_load_nextn():
from pathlib import Path
policy = json.loads((Path(__file__).resolve().parents[4] / "config" / "llama-cpp-architectures.json")
.read_text(encoding="utf-8"))
assert all(isinstance(entry.get("nextnLoader"), bool) for entry in policy["builds"].values())
assert policy["builds"]["b9014"]["nextnLoader"] is False
assert policy["builds"]["b11429"]["nextnLoader"] is True
assert policy['builds']['b9014']['nextnArchitectures'] == ['bailingmoe2', 'exaone-moe', 'glm-dsa', 'glm4', 'glm4moe']
def test_nextn_refusal_is_overridable_and_names_the_build():
refusal = preflight.nextn_refusal("b9014")
assert refusal["code"] == "runtime_nextn_unsupported"
assert refusal["overridable"] is True
assert "b9014" in refusal["message"]