Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.
Python agentaichatgptdeepseekfine-tuninggemmaimage-generationllamallmllmsopenaipythonqwenreinforcement-learningself-hostedstable-diffusiontext-to-speechttsuiunsloth
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
"""Unit tests for the llama-server pass-through args validator, pinning denylist behaviour."""
from __future__ import annotations
import importlib.util
import re
from pathlib import Path
import pytest
# Load directly to avoid importing the full backend via core/inference/__init__.py.
_LSA_PATH = Path(__file__).resolve().parent.parent / "core" / "inference" / "llama_server_args.py"
_spec = importlib.util.spec_from_file_location("_lsa_test_only", _LSA_PATH)
_lsa = importlib.util.module_from_spec(_spec)
_spec.loader.exec_module(_lsa)
is_managed_flag = _lsa.is_managed_flag
parse_cache_override = _lsa.parse_cache_override
parse_cache_override_per_axis = _lsa.parse_cache_override_per_axis
parse_ctx_override = _lsa.parse_ctx_override
parse_gpu_layers_override = _lsa.parse_gpu_layers_override
parse_reasoning_budget_message_override = _lsa.parse_reasoning_budget_message_override
parse_reasoning_budget_override = _lsa.parse_reasoning_budget_override
parse_split_mode_override = _lsa.parse_split_mode_override
parse_tensor_split_override = _lsa.parse_tensor_split_override
resolve_cache_type_kv = _lsa.resolve_cache_type_kv
resolve_reasoning_budget = _lsa.resolve_reasoning_budget
resolve_reasoning_budget_message = _lsa.resolve_reasoning_budget_message
resolve_reasoning_budget_message_with_env = _lsa.resolve_reasoning_budget_message_with_env
resolve_reasoning_budget_with_env = _lsa.resolve_reasoning_budget_with_env
resolve_tensor_parallel = _lsa.resolve_tensor_parallel
strip_shadowing_flags = _lsa.strip_shadowing_flags
strip_split_mode_only = _lsa.strip_split_mode_only
strip_context_only = _lsa.strip_context_only
extra_args_disable_mmproj = _lsa.extra_args_disable_mmproj
validate_extra_args = _lsa.validate_extra_args
@pytest.mark.parametrize(
"args",
[
["--top-k", "20"],
["--top-p", "0.9", "--min-p", "0.05"],
["--seed", "-1"], # negative value, not a flag
["--temp", "0.0"],
["--repeat-penalty", "1.05"],
["--mirostat", "2", "--mirostat-lr", "0.1"],
["--xtc-probability", "0.05", "--xtc-threshold", "0.1"],
["--dry-multiplier", "0.5"],
["--cache-type-k", "q8_0"],
["--cache-type-v", "q8_0"],
["--chat-template-file", "/tmp/tpl.jinja"],
["--chat-template-kwargs", '{"reasoning_effort":"high"}'],
["--spec-type", "ngram-mod"],
["--spec-default"],
["--spec-type", "draft-mtp"],
["--spec-type", "draft-mtp", "--spec-draft-n-max", "6"],
[
"--spec-type",
"ngram-mod,draft-mtp",
"--spec-draft-n-max",
"3",
"--spec-ngram-mod-n-match",
"24",
"--spec-ngram-mod-n-min",
"48",
"--spec-ngram-mod-n-max",
"64",
],
["--reasoning-format", "deepseek"],
["-rea", "auto"],
["-c", "131072"],
["--ctx-size", "8192"],
["--flash-attn", "off"],
["-fa", "on"],
["--no-context-shift"],
["--context-shift"],
["--jinja"],
["--no-jinja"],
["-ngl", "-1"],
["--gpu-layers", "32"],
["-t", "16"],
["--threads", "32"],
["-fit", "off"],
["--fit", "on"],
["--fit-ctx", "8192"],
["--mlock"],
["--no-mmap", "--mlock"],
],
)
def test_pass_through_allowed(args):
assert validate_extra_args(args) == args
def test_none_returns_empty_list():
assert validate_extra_args(None) == []
def test_empty_list_returns_empty_list():
assert validate_extra_args([]) == []
def test_the_attached_value_form_is_refused():
# llama.cpp does not accept --flag=value (only underscore folding).
with pytest.raises(ValueError, match = "two separate arguments"):
validate_extra_args(["--top-k=20"])
assert validate_extra_args(["--top-k", "20"]) == ["--top-k", "20"]
assert validate_extra_args(["--ctx_size", "4096"]) == ["--ctx_size", "4096"]
with pytest.raises(ValueError, match = "managed by Unsloth Studio"):
validate_extra_args(["--parallel=8"])
assert validate_extra_args(["--override-kv", "a=int:2"]) == ["--override-kv", "a=int:2"]
def test_managed_long_flag_underscore_alias_is_rejected():
with pytest.raises(ValueError, match = "slot-save-path"):
validate_extra_args(["--slot_save_path", "/tmp/slots"])
def test_a_bare_positional_is_rejected():
# A positional could be read as the model path, which denying -m prevents.
with pytest.raises(ValueError, match = "bare value"):
validate_extra_args(["foo"])
assert validate_extra_args(["--numa", "distribute"]) == ["--numa", "distribute"]
@pytest.mark.parametrize(
"denied",
[
"-np",
"--parallel",
"--n-parallel",
"-m",
"--model",
"-mu",
"--model-url",
"-dr",
"--docker-repo",
"-hf",
"-hfr",
"--hf-repo",
"-hff",
"--hf-file",
"-hfv",
"-hfrv",
"--hf-repo-v",
"-hffv",
"--hf-file-v",
"-hft",
"--hf-token",
"-mmu",
"--mmproj-url",
"--host",
"--port",
"--path",
"--api-prefix",
"--reuse-port",
"--api-key",
"--api-key-file",
"--ssl-key-file",
"--ssl-cert-file",
"--webui",
"--no-webui",
"--ui",
"--no-ui",
"--ui-config",
"--ui-config-file",
"--ui-mcp-proxy",
"--no-ui-mcp-proxy",
"--models-dir",
"--models-preset",
"--models-max",
"--models-autoload",
"--no-models-autoload",
"--embedding",
"--embeddings",
"--rerank",
"--reranking",
"--pooling",
"--tools",
# --agent enables all built-in tools incl. exec_shell_command.
"-ag",
"--agent",
"-no-ag",
"--no-agent",
"--tools-runtime",
"--mcp-servers-config",
"--mcp-servers-json",
"--cors-origins",
"--cors-headers",
"--cors-methods",
"--cors-credentials",
"--no-cors-credentials",
"--media-path",
"--log-file",
"--log-disable",
"--slot-save-path",
"-h",
"--help",
"--usage",
"--version",
"--list-devices",
"-cl",
"--cache-list",
"--completion-bash",
"--webui-config",
"--webui-config-file",
"--webui-mcp-proxy",
"--no-webui-mcp-proxy",
],
)
def test_denylist_rejects_all_aliases(denied):
with pytest.raises(ValueError, match = denied):
validate_extra_args([denied, "value"])
@pytest.mark.parametrize(
"args,offending",
[
# Pass-through --parallel would override slots while KV fit uses the resolved value.
(["--parallel", "8"], "--parallel"),
(["--parallel=8"], "--parallel"),
(["--n-parallel", "16"], "--n-parallel"),
(["--n-parallel=16"], "--n-parallel"),
(["-np", "32"], "-np"),
(["-np8"], "-np"),
(["-np64"], "-np"),
(["--parallel", "999"], "--parallel"),
(["-np", "0"], "-np"),
(["-np999"], "-np"),
(["-np-1"], "-np"),
(["-np+1"], "-np"),
],
)
def test_parallel_flags_are_managed(args, offending):
with pytest.raises(ValueError, match = re.escape(offending)):
validate_extra_args(args)
def test_denylist_rejects_equals_form():
with pytest.raises(ValueError, match = "--port"):
validate_extra_args(["--port=9000"])
def test_slot_save_path_is_managed_in_all_forms():
for args in (["--slot-save-path", "/tmp/x"], ["--slot-save-path=/tmp/x"], ["--slot-save-path"]):
with pytest.raises(ValueError, match = "--slot-save-path"):
validate_extra_args(args)
assert is_managed_flag("--slot-save-path") is True
assert is_managed_flag("--slot-save-path=/tmp/x") is True
assert is_managed_flag("--slots") is False
assert is_managed_flag("--no-slots") is False
assert is_managed_flag("--props") is False
@pytest.mark.parametrize(
"padded",
[" --parallel", "--parallel ", "\t--parallel", " -np", "-np \n", "-np\t"],
)
def test_denylist_rejects_whitespace_padded_forms(padded):
with pytest.raises(ValueError, match = "parallel|np"):
validate_extra_args([padded, "8"])
@pytest.mark.parametrize(
"attached",
["-np8x", "-np-1foo", "-np+1bar", "-np9zzz"],
)
def test_denylist_rejects_np_with_digit_prefix_and_junk(attached):
# Must classify the same forms the CLI rewriter expands.
with pytest.raises(ValueError, match = "np"):
validate_extra_args([attached])
def test_denylist_rejects_short_form_when_long_is_denied():
with pytest.raises(ValueError, match = "-m"):
validate_extra_args(["-m", "/some/other/path.gguf"])
def test_denylist_message_names_offending_flag():
with pytest.raises(ValueError) as excinfo:
validate_extra_args(["--top-k", "20", "--api-key", "secret"])
assert "--api-key" in str(excinfo.value)
def test_first_denied_flag_short_circuits():
with pytest.raises(ValueError, match = "--port"):
validate_extra_args(["--port", "1", "--host", "x"])
@pytest.mark.parametrize("value", ["-1", "-0.5", "-42", "-.5"])
def test_negative_number_value_is_not_flag(value):
assert validate_extra_args(["--seed", value]) == ["--seed", value]
def test_is_managed_flag_true_for_denied():
assert is_managed_flag("--port") is True
assert is_managed_flag("--api-key") is True
assert is_managed_flag("-m") is True
assert is_managed_flag("--model") is True
assert is_managed_flag("--parallel") is True
assert is_managed_flag("--n-parallel") is True
assert is_managed_flag("-np") is True
# Must stay in sync with validate_extra_args.
assert is_managed_flag("-np8") is True
assert is_managed_flag("--parallel=8") is True
assert is_managed_flag("--port=9000") is True
def test_is_managed_flag_false_for_pass_through():
assert is_managed_flag("--top-k") is False
assert is_managed_flag("--cache-type-k") is False
assert is_managed_flag("--chat-template-file") is False
assert is_managed_flag("-c") is False
assert is_managed_flag("--ctx-size") is False
assert is_managed_flag("--flash-attn") is False
assert is_managed_flag("-ngl") is False
assert is_managed_flag("--threads") is False
assert is_managed_flag("--mlock") is False
assert is_managed_flag("--no-mmap") is False
def test_strip_shadowing_flags_drops_context_when_requested():
out = strip_shadowing_flags(
["-c", "4096", "--top-k", "20"],
strip_context = True,
strip_cache = False,
strip_spec = False,
strip_template = False,
)
assert out == ["--top-k", "20"]
def test_strip_shadowing_flags_keeps_context_when_not_requested():
out = strip_shadowing_flags(
["-c", "4096", "--top-k", "20"],
strip_context = False,
strip_cache = False,
strip_spec = False,
strip_template = False,
)
assert out == ["-c", "4096", "--top-k", "20"]
def test_strip_shadowing_flags_keeps_chat_template_when_template_disabled():
out = strip_shadowing_flags(
["--chat-template-file", "/tmp/custom.jinja", "--top-k", "20"],
strip_context = True,
strip_cache = True,
strip_spec = True,
strip_template = False,
)
assert out == ["--chat-template-file", "/tmp/custom.jinja", "--top-k", "20"]
def test_strip_shadowing_flags_drops_template_when_requested():
out = strip_shadowing_flags(
["--chat-template-file", "/tmp/custom.jinja", "--top-k", "20"],
strip_template = True,
)
assert out == ["--top-k", "20"]
def test_strip_shadowing_flags_keeps_cache_when_cache_disabled():
out = strip_shadowing_flags(
["--cache-type-k", "q8_0", "--cache-type-v", "q8_0", "--top-k", "20"],
strip_cache = False,
)
assert out == ["--cache-type-k", "q8_0", "--cache-type-v", "q8_0", "--top-k", "20"]
def test_strip_shadowing_flags_keeps_spec_when_spec_disabled():
out = strip_shadowing_flags(
["--spec-type", "ngram-mod", "--draft-min", "48", "--top-k", "20"],
strip_spec = False,
)
assert out == ["--spec-type", "ngram-mod", "--draft-min", "48", "--top-k", "20"]
def test_strip_shadowing_flags_keeps_device_by_default():
out = strip_shadowing_flags(
["--device", "Vulkan1", "--top-k", "20"],
strip_context = False,
strip_cache = False,
strip_spec = False,
strip_template = False,
strip_split_mode = False,
)
assert out == ["--device", "Vulkan1", "--top-k", "20"]
def test_strip_shadowing_flags_drops_device_when_requested():
for flag in ("--device", "-dev", "--main-gpu", "-mg"):
out = strip_shadowing_flags(
[flag, "Vulkan1", "--top-k", "20"],
strip_context = False,
strip_cache = False,
strip_spec = False,
strip_template = False,
strip_split_mode = False,
strip_device = True,
)
assert out == ["--top-k", "20"], flag
def test_strip_shadowing_flags_drops_mtp_flags_when_requested():
out = strip_shadowing_flags(
[
"--spec-type",
"draft-mtp",
"--spec-draft-n-max",
"6",
"--spec-ngram-mod-n-match",
"24",
"--spec-ngram-mod-n-min",
"48",
"--spec-ngram-mod-n-max",
"6",
"--top-k",
"20",
],
strip_spec = True,
)
assert out == ["--top-k", "20"]
def test_is_managed_flag_false_for_mtp_pass_through():
assert is_managed_flag("--spec-draft-n-max") is False
assert is_managed_flag("--spec-ngram-mod-n-match") is False
assert is_managed_flag("--spec-ngram-mod-n-min") is False
assert is_managed_flag("--spec-ngram-mod-n-max") is False
@pytest.mark.parametrize(
"args,expected",
[
(None, None),
([], None),
(["--top-k", "20"], None),
(["--ctx-size", "128000"], 128000),
(["--ctx-size=128000"], 128000),
(["-c", "128000"], 128000),
(["-c=128000"], 128000),
(["-c", "4096", "--ctx-size", "128000"], 128000),
],
)
def test_parse_ctx_override(args, expected):
assert parse_ctx_override(args) == expected
@pytest.mark.parametrize(
"args",
[
["--ctx-size"],
["--ctx-size", "--top-k"],
["--ctx-size", "abc"],
["--ctx-size=abc"],
["-c", "-1"],
],
)
def test_parse_ctx_override_rejects_malformed_values(args):
with pytest.raises(ValueError, match = "ctx-size|'-c'"):
parse_ctx_override(args)
def test_validate_extra_args_rejects_malformed_ctx_override():
with pytest.raises(ValueError, match = "ctx-size"):
validate_extra_args(["--ctx-size", "abc"])
@pytest.mark.parametrize(
"args,expected",
[
(None, None),
([], None),
(["--top-k", "20"], None),
(["--gpu-layers", "20"], 20),
(["--gpu-layers=20"], 20),
(["--n-gpu-layers", "0"], 0),
(["-ngl", "-1"], -1),
(["-ngl", "12", "--gpu-layers", "20"], 20),
],
)
def test_parse_gpu_layers_override(args, expected):
assert parse_gpu_layers_override(args) == expected
@pytest.mark.parametrize("flag", ["-ngl", "--gpu-layers", "--n-gpu-layers"])
@pytest.mark.parametrize("value,expected", [("auto", -1), ("all", 2**31 - 1)])
def test_gpu_layer_keywords_are_preserved_and_resolved(flag, value, expected):
args = [flag, value]
assert validate_extra_args(args) == args
assert parse_gpu_layers_override(args) == expected
@pytest.mark.parametrize(
"args,expected",
[
(["-ngl", "all", "--gpu-layers", "auto"], -1),
(["-ngl", "auto", "--n-gpu-layers", "all"], 2**31 - 1),
(["-ngl", "all", "--gpu-layers", "0"], 0),
(["-ngl", "12", "--gpu-layers", "all"], 2**31 - 1),
],
)
def test_gpu_layer_keywords_respect_last_override(args, expected):
assert validate_extra_args(args) == args
assert parse_gpu_layers_override(args) == expected
@pytest.mark.parametrize(
"args",
[
["--gpu-layers"],
["--gpu-layers", "--top-k"],
["--gpu-layers", "abc"],
["--gpu-layers=-2"],
],
)
def test_parse_gpu_layers_override_rejects_malformed_values(args):
with pytest.raises(ValueError, match = "gpu-layers|GPU layers"):
parse_gpu_layers_override(args)
def test_validate_extra_args_rejects_malformed_gpu_layers_override():
with pytest.raises(ValueError, match = "GPU layers"):
validate_extra_args(["-ngl", "abc"])
@pytest.mark.parametrize(
"args,expected",
[
(None, None),
([], None),
(["--top-k", "20"], None),
(["--tensor-split", "2.2,1"], [2.2, 1.0]),
(["-ts", "3,1"], [3.0, 1.0]),
(["-ts", "3/1"], [3.0, 1.0]),
(["--tensor-split=1,1"], [1.0, 1.0]),
(["-ts", "1,1", "--tensor-split", "2.2,1"], [2.2, 1.0]),
],
)
def test_parse_tensor_split_override(args, expected):
assert parse_tensor_split_override(args) == expected
@pytest.mark.parametrize(
"args",
[
["--tensor-split"],
["--tensor-split", "--top-k"],
["--tensor-split", "abc"],
["--tensor-split", "1,-1"],
["--tensor-split", "0,0"],
["--tensor-split", "nan,1"],
["--tensor-split", "inf,1"],
],
)
def test_parse_tensor_split_override_rejects_malformed_values(args):
with pytest.raises(ValueError, match = "tensor-split"):
parse_tensor_split_override(args)
@pytest.mark.parametrize(
"value,expected",
[
("1_0,1", [10.0, 1.0]),
("1_000.5,1", [1000.5, 1.0]),
("1e1_0,1", [1e10, 1.0]),
("1.,1", [1.0, 1.0]),
(".5,1", [0.5, 1.0]),
("+1.5,1", [1.5, 1.0]),
],
)
def test_parse_tensor_split_override_reads_python_float_syntax(value, expected):
assert parse_tensor_split_override(["-ts", value]) == expected
@pytest.mark.parametrize("value", ["0x10,1", "0b10,1", "0o17,1", "1__0,1", "_1,1", "1_,1", "1e,1"])
def test_parse_tensor_split_override_rejects_non_float_syntax(value):
# JS Number() reads 0x/0b/0o, so the mirror must refuse them too.
with pytest.raises(ValueError, match = "tensor-split"):
parse_tensor_split_override(["-ts", value])
def test_parse_tensor_split_override_rejects_a_share_float32_cannot_hold():
# std::stof throws above FLT_MAX, killing llama-server at startup.
with pytest.raises(ValueError, match = "32-bit float"):
parse_tensor_split_override(["-ts", "1e39,1"])
assert parse_tensor_split_override(["-ts", "3.4e38,1"]) == [3.4e38, 1.0]
@pytest.mark.parametrize("value", ["1e-50,1", "1e-45,1", "1e-40,1", "1e-38,1"])
def test_parse_tensor_split_override_rejects_a_share_that_underflows_stof(value):
# libstdc++ stof also throws on subnormals (1e-38, 1e-45).
with pytest.raises(ValueError, match = "at least"):
parse_tensor_split_override(["-ts", value])
@pytest.mark.parametrize("value", ["0,1", "1.2e-38,1", "1e-30,1"])
def test_parse_tensor_split_override_keeps_what_stof_accepts(value):
# Exact zero and anything from FLT_MIN up survive the emit round trip.
assert parse_tensor_split_override(["-ts", value]) is not None
def test_parse_tensor_split_override_only_rounds_what_gets_reserialized():
# Pass-through keeps the user's text, which stof accepts; rounding is manual-only.
assert parse_tensor_split_override(["-ts", "1.1754943508222874e-38,1"]) is not None
with pytest.raises(ValueError, match = "at least"):
parse_tensor_split_override(["-ts", "1.1754943508222874e-38,1"], reserialized = True)
def test_parse_tensor_split_override_rounds_each_share_before_adding():
# llama.cpp sums float shares, so the total can overflow to inf.
for reserialized in (False, True):
with pytest.raises(ValueError, match = "adds up past"):
parse_tensor_split_override(
["-ts", "3.17817e38,1.54601e37,7.00525e36"], reserialized = reserialized
)
def test_parse_tensor_split_override_judges_the_share_it_will_emit():
# Manual launcher emits f'{x:g}'; the emitted text must survive stof.
with pytest.raises(ValueError, match = "at least"):
parse_tensor_split_override(["-ts", "1.1754943508222874e-38,1"], reserialized = True)
assert parse_tensor_split_override(["-ts", "1.2e-38,1"], reserialized = True) == [1.2e-38, 1.0]
def test_parse_tensor_split_override_totals_the_emitted_shares():
# Total is accumulated over the emitted values, as llama.cpp does.
assert (
parse_tensor_split_override(
["-ts", "2.0829609943909916e38,7.170581961838338e37,6.028042758104631e37"],
reserialized = True,
)
is not None
)
with pytest.raises(ValueError, match = "adds up past"):
parse_tensor_split_override(["-ts", "3e38,3e38"])
def test_parse_tensor_split_override_rejects_a_total_float32_cannot_hold():
with pytest.raises(ValueError, match = "adds up past"):
parse_tensor_split_override(["-ts", "3e38,3e38"])
def test_validate_extra_args_rejects_malformed_tensor_split_override():
with pytest.raises(ValueError, match = "tensor-split"):
validate_extra_args(["-ts", "abc"])
def test_reasoning_budget_overrides_are_last_wins():
args = [
"--reasoning-budget",
"32",
"--reasoning-budget=64",
"--reasoning-budget-message",
"first",
"--reasoning-budget-message=limit reached",
]
assert parse_reasoning_budget_override(args) == 64
assert parse_reasoning_budget_message_override(args) == "limit reached"
assert resolve_reasoning_budget(args, -1) == 64
assert resolve_reasoning_budget_message(args, "") == "limit reached"
@pytest.mark.parametrize(
"args",
[
["--reasoning-budget-message", " PAD "],
["--reasoning-budget-message= PAD "],
],
)
def test_reasoning_budget_message_preserves_verbatim_whitespace(args):
assert parse_reasoning_budget_message_override(args) == " PAD "
assert resolve_reasoning_budget_message(args, "fallback") == " PAD "
def test_reasoning_budget_defaults_inherit_env_but_passthrough_still_wins():
env = {
"LLAMA_ARG_THINK_BUDGET": "512",
"LLAMA_ARG_THINK_BUDGET_MESSAGE": "from env",
}
assert resolve_reasoning_budget_with_env(None, -1, env) == 512
assert resolve_reasoning_budget_message_with_env(None, "", env) == "from env"
assert resolve_reasoning_budget_with_env(["--reasoning-budget", "-1"], -1, env) == -1
assert (
resolve_reasoning_budget_message_with_env(
["--reasoning-budget-message", " CLI "], "", env
)
== " CLI "
)
# A NUL trips the list-wide control-character check first.
@pytest.mark.parametrize(
"unsafe, message",
[("😀" * 2_049, "reasoning-budget-message"), ("bad\0message", "control characters")],
)
def test_reasoning_budget_message_validates_every_occurrence(unsafe, message):
with pytest.raises(ValueError, match = message):
validate_extra_args(
[
"--reasoning-budget-message",
unsafe,
"--reasoning-budget-message",
"safe final value",
]
)
@pytest.mark.parametrize(
"args",
[
["--reasoning-budget"],
["--reasoning-budget", "nope"],
["--reasoning-budget=-2"],
["--reasoning-budget=2147483648"],
["--reasoning-budget-message"],
["--reasoning-budget-message", "😀" * 2_049],
["--reasoning-budget-message", "bad\0message"],
],
)
def test_validate_extra_args_rejects_malformed_reasoning_overrides(args):
with pytest.raises(ValueError, match = "reasoning-budget|control characters"):
validate_extra_args(args)
def test_strip_reasoning_shadows_is_granular():
args = [
"--reasoning-budget",
"64",
"--reasoning-budget-message",
"limit reached",
"--top-k",
"20",
]
assert strip_shadowing_flags(
args,
strip_context = False,
strip_cache = False,
strip_spec = False,
strip_template = False,
strip_split_mode = False,
strip_reasoning_budget = True,
) == ["--reasoning-budget-message", "limit reached", "--top-k", "20"]
assert strip_shadowing_flags(
args,
strip_context = False,
strip_cache = False,
strip_spec = False,
strip_template = False,
strip_split_mode = False,
strip_reasoning_budget_message = True,
) == ["--reasoning-budget", "64", "--top-k", "20"]
@pytest.mark.parametrize(
"args,expected",
[
(None, None),
([], None),
(["--top-k", "20"], None),
(["--cache-type-k", "q8_0"], "q8_0"),
(["-ctk", "q4_0"], "q4_0"),
(["-ctv", "q4_0"], "q4_0"),
(["--cache-type-k=q4_0"], "q4_0"),
(["-ctk", "f16", "-ctk", "q8_0"], "q8_0"),
],
)
def test_parse_cache_override(args, expected):
assert parse_cache_override(args) == expected
@pytest.mark.parametrize(
"args",
[
["-ctk"],
["-ctk", "-c", "4096"],
],
)
def test_parse_cache_override_rejects_malformed_values(args):
with pytest.raises(ValueError, match = "cache-type|'-ctk'"):
parse_cache_override(args)
@pytest.mark.parametrize(
"args, expected",
[
(["--cache-type-k", "f32", "--cache-type-v", "f16"], ("f32", "f16")),
(["-ctk", "q8_0", "-ctv", "q4_0"], ("q8_0", "q4_0")),
(["--cache-type-k=f32"], ("f32", None)),
(["--cache-type-v", "f16"], (None, "f16")),
(["-c", "4096"], (None, None)),
(None, (None, None)),
(["-ctk", "f16", "-ctk", "f32"], ("f32", None)),
],
)
def test_parse_cache_override_per_axis(args, expected):
# Keeps K and V apart, unlike parse_cache_override.
assert parse_cache_override_per_axis(args) == expected
def test_resolve_cache_type_kv_uses_override_when_present():
assert resolve_cache_type_kv(["--cache-type-k", "q8_0"], "f16") == "q8_0"
def test_resolve_cache_type_kv_uses_fallback_without_override():
assert resolve_cache_type_kv(["--top-k", "20"], "f16") == "f16"
def test_strip_shadowing_flags_boolean_does_not_consume_next_token():
out = strip_shadowing_flags(["--spec-default", "ngram-mod"], strip_spec = True)
assert out == ["ngram-mod"]
def test_strip_shadowing_flags_jinja_boolean_preserves_positional():
out = strip_shadowing_flags(["--jinja", "trailing-positional"], strip_template = True)
assert out == ["trailing-positional"]
def test_strip_shadowing_flags_no_jinja_boolean_preserves_positional():
out = strip_shadowing_flags(["--no-jinja", "trailing-positional"], strip_template = True)
assert out == ["trailing-positional"]
def test_strip_shadowing_flags_equals_form_drops_only_the_flag():
out = strip_shadowing_flags(["--ctx-size=4096", "--seed", "-1"], strip_context = True)
assert out == ["--seed", "-1"]
def test_strip_shadowing_flags_handles_none_input():
assert strip_shadowing_flags(None) == []
def test_strip_shadowing_flags_handles_empty_input():
assert strip_shadowing_flags([]) == []
def test_strip_shadowing_flags_defaults_strip_everything():
out = strip_shadowing_flags(
["-c", "4096", "--cache-type-k", "q8_0", "--spec-default", "--jinja"]
)
assert out == []
# --split-mode: soft-shadowed like --cache-type-*, stripped on inherit.
@pytest.mark.parametrize(
"args",
[
["--split-mode", "tensor"],
["--split-mode", "row"],
["--split-mode", "none"],
["--split-mode", "layer"],
["-sm", "tensor"],
],
)
def test_split_mode_passes_through(args):
assert validate_extra_args(args) == args
@pytest.mark.parametrize("args", [["--split-mode=row"], ["-sm=tensor"]])
def test_the_attached_split_mode_spelling_is_refused(args):
with pytest.raises(ValueError, match = "two separate arguments"):
validate_extra_args(args)
def test_split_mode_is_not_managed():
assert is_managed_flag("--split-mode") is False
assert is_managed_flag("-sm") is False
@pytest.mark.parametrize(
"args,expected",
[
(None, None),
([], None),
(["--top-k", "20"], None),
(["--split-mode", "tensor"], "tensor"),
(["--split-mode", "row"], "row"),
(["-sm", "none"], "none"),
(["--split-mode=layer"], "layer"),
(["-sm=tensor"], "tensor"),
(["-sm", "row", "--split-mode", "tensor"], "tensor"),
],
)
def test_parse_split_mode_override(args, expected):
assert parse_split_mode_override(args) == expected
@pytest.mark.parametrize(
"args",
[
["--split-mode"],
["-sm"],
["--split-mode", "-c", "4096"], # next token is a flag, not a value
],
)
def test_parse_split_mode_override_rejects_malformed_values(args):
with pytest.raises(ValueError, match = "split-mode|'-sm'"):
parse_split_mode_override(args)
def test_validate_extra_args_rejects_malformed_split_mode():
with pytest.raises(ValueError, match = "split-mode"):
validate_extra_args(["--split-mode"])
@pytest.mark.parametrize(
"args,fallback,expected",
[
(["--top-k", "20"], True, True),
(["--top-k", "20"], False, False),
(None, True, True),
([], False, False),
(["--split-mode", "tensor"], False, True),
(["-sm", "tensor"], False, True),
(["--split-mode", "row"], True, False),
(["--split-mode", "none"], True, False),
(["--split-mode", "layer"], True, False),
(["--split-mode=tensor"], False, True),
(["--split-mode", "TENSOR"], False, True),
(["-sm", "tensor", "--split-mode", "row"], True, False),
],
)
def test_resolve_tensor_parallel(args, fallback, expected):
assert resolve_tensor_parallel(args, fallback) is expected
def test_strip_shadowing_flags_drops_split_mode_when_requested():
out = strip_shadowing_flags(
["--split-mode", "row", "--top-k", "20"],
strip_context = False,
strip_cache = False,
strip_spec = False,
strip_template = False,
strip_split_mode = True,
)
assert out == ["--top-k", "20"]
def test_extra_args_disable_mmproj_detects_flag():
assert extra_args_disable_mmproj(["--no-mmproj"]) is True
assert extra_args_disable_mmproj(["--threads", "12", "--no-mmproj"]) is True
assert extra_args_disable_mmproj(["--no-mmproj-auto"]) is True
def test_extra_args_disable_mmproj_false_when_absent():
assert extra_args_disable_mmproj(None) is False
assert extra_args_disable_mmproj(["--threads", "12"]) is False
def test_extra_args_disable_mmproj_last_wins():
assert extra_args_disable_mmproj(["--no-mmproj", "--mmproj-auto"]) is False
assert extra_args_disable_mmproj(["--mmproj-auto", "--no-mmproj-auto"]) is True
def test_strip_shadowing_flags_drops_model_draft_with_spec():
# --model-draft is managed: an inherited copy must not override the drafter.
out = strip_shadowing_flags(
["--model-draft", "/old/mtp.gguf", "-md", "/old2.gguf", "--top-k", "20"],
strip_context = False,
strip_cache = False,
strip_spec = True,
strip_template = False,
)
assert out == ["--top-k", "20"]
@pytest.mark.parametrize(
"selector",
[
["--spec-draft-hf", "org/repo"],
["-hfd", "org/repo"],
["-hfrd", "org/repo"],
["--hf-repo-draft", "org/repo"],
["--spec-draft-hf=org/repo"],
],
)
def test_strip_shadowing_flags_drops_hf_drafter_selectors_with_spec(selector):
out = strip_shadowing_flags(
selector + ["--top-k", "20"],
strip_context = False,
strip_cache = False,
strip_spec = True,
strip_template = False,
)
assert out == ["--top-k", "20"]
def test_strip_shadowing_flags_keeps_draft_tuning_with_spec():
# Drafter tuning knobs are kept; stripping --spec-draft-ngl moves a CPU drafter to GPU.
keep = [
"--spec-draft-type-k",
"q4_0",
"--spec-draft-type-v",
"q4_0",
"--spec-draft-ngl",
"0",
"--spec-draft-device",
"cpu",
]
out = strip_shadowing_flags(
list(keep),
strip_context = False,
strip_cache = False,
strip_spec = True,
strip_template = False,
)
assert out == keep
def test_strip_shadowing_flags_keeps_split_mode_when_not_requested():
out = strip_shadowing_flags(
["--split-mode", "row", "--top-k", "20"],
strip_context = True,
strip_cache = True,
strip_spec = True,
strip_template = True,
strip_split_mode = False,
)
assert out == ["--split-mode", "row", "--top-k", "20"]
def test_strip_shadowing_flags_drops_split_mode_short_alias_and_equals():
assert strip_shadowing_flags(["-sm", "tensor", "--top-k", "20"], strip_split_mode = True) == [
"--top-k",
"20",
]
assert strip_shadowing_flags(["--split-mode=row", "--seed", "-1"], strip_split_mode = True) == [
"--seed",
"-1",
]
def test_strip_shadowing_flags_defaults_strip_split_mode_too():
assert strip_shadowing_flags(["--split-mode", "tensor"]) == []
def test_strip_offload_is_opt_in_and_covers_moe():
base = dict(
strip_context = False,
strip_cache = False,
strip_spec = False,
strip_template = False,
strip_split_mode = False,
)
assert strip_shadowing_flags(["--n-cpu-moe", "8", "--top-k", "20"], **base) == [
"--n-cpu-moe",
"8",
"--top-k",
"20",
]
assert strip_shadowing_flags(
["--n-cpu-moe", "8", "--gpu-layers", "33", "--fit", "off", "--top-k", "20"],
**base,
strip_offload = True,
) == ["--top-k", "20"]
assert strip_shadowing_flags(["--cpu-moe", "--seed", "-1"], **base, strip_offload = True) == [
"--seed",
"-1",
]
@pytest.mark.parametrize(
"args",
[
["--split-mode", "tensor", "-c", "4096"],
["-sm", "tensor", "-c", "4096"],
["--split-mode=tensor", "-c", "4096"],
["-sm=tensor", "-c", "4096"],
],
)
def test_strip_split_mode_only_keeps_other_shadow_flags(args):
assert strip_split_mode_only(args) == ["-c", "4096"]
def test_strip_split_mode_only_preserves_none_and_empty():
# None means inherit; [] means explicit empty.
assert strip_split_mode_only(None) is None
assert strip_split_mode_only([]) == []
@pytest.mark.parametrize(
"args",
[
["-c", "0", "--top-k", "20"],
["--ctx-size", "0", "--top-k", "20"],
["-c=0", "--top-k", "20"],
["--ctx-size=0", "--top-k", "20"],
],
)
def test_strip_context_only_drops_every_context_form(args):
assert strip_context_only(args) == ["--top-k", "20"]
def test_strip_context_only_keeps_other_shadow_flags():
assert strip_context_only(["-c", "0", "--split-mode", "row", "--cache-type-k", "q8_0"]) == [
"--split-mode",
"row",
"--cache-type-k",
"q8_0",
]
def test_strip_context_only_preserves_none_and_empty():
assert strip_context_only(None) is None
assert strip_context_only([]) == []
def test_strip_shadowing_flags_drops_tensor_split_with_split_mode():
out = strip_shadowing_flags(
["--split-mode", "row", "--tensor-split", "1,1", "--top-k", "20"],
strip_context = False,
strip_cache = False,
strip_spec = False,
strip_template = False,
strip_split_mode = True,
)
assert out == ["--top-k", "20"]
def test_strip_shadowing_flags_keeps_tensor_split_when_not_requested():
assert strip_shadowing_flags(
["--tensor-split", "1,1", "--top-k", "20"], strip_split_mode = False
) == ["--tensor-split", "1,1", "--top-k", "20"]
def test_strip_split_mode_only_drops_tensor_split_too():
assert strip_split_mode_only(
["--split-mode", "tensor", "--tensor-split", "1,1", "-c", "4096"]
) == ["-c", "4096"]
assert strip_split_mode_only(["-sm=tensor", "-ts=3,1"]) == []
def test_strip_tensor_split_alone_preserves_split_mode():
# strip_tensor_split drops only the ratio; the user's split mode survives.
out = strip_shadowing_flags(
["--split-mode", "row", "--tensor-split", "1,1", "--top-k", "20"],
strip_context = False,
strip_cache = False,
strip_spec = False,
strip_template = False,
strip_split_mode = False,
strip_tensor_split = True,
)
assert out == ["--split-mode", "row", "--top-k", "20"]
def test_strip_shadowing_flags_keeps_model_draft_without_spec():
out = strip_shadowing_flags(
["--model-draft", "/custom/mtp.gguf"],
strip_context = True,
strip_cache = False,
strip_spec = False,
strip_template = False,
)
assert out == ["--model-draft", "/custom/mtp.gguf"]
# Not the security boundary (the denylist is), just a size cap before execve.
def test_token_count_is_capped():
with pytest.raises(ValueError, match = "too many"):
validate_extra_args(["--verbose"] * (_lsa.MAX_EXTRA_ARG_TOKENS + 1))
assert len(validate_extra_args(["--verbose"] * _lsa.MAX_EXTRA_ARG_TOKENS)) == (
_lsa.MAX_EXTRA_ARG_TOKENS
)
def test_total_size_is_capped():
with pytest.raises(ValueError, match = "too large"):
validate_extra_args(["--grammar", "x" * (_lsa.MAX_EXTRA_ARGS_BYTES + 1)])
def test_a_long_single_token_is_allowed_under_the_total():
# Grammars can be one long token, so the cap is on the list.
schema = "x" * (_lsa.MAX_EXTRA_ARGS_BYTES // 2)
assert validate_extra_args(["--grammar", schema]) == ["--grammar", schema]
def test_the_size_cap_counts_bytes_not_characters():
# Astral chars are 4 bytes; a char-counted cap would undercount.
big = "\U0001f600" * (_lsa.MAX_EXTRA_ARGS_BYTES // 4)
with pytest.raises(ValueError, match = "too large"):
validate_extra_args(["--grammar", big])
@pytest.mark.parametrize("token", ["a\x00b", "a\x07b", "\x1b[31m"])
def test_control_characters_are_rejected(token):
with pytest.raises(ValueError, match = "control characters"):
validate_extra_args([token])
@pytest.mark.parametrize("token", ["line\nbreak", "tab\there"])
def test_tab_and_newline_survive(token):
assert validate_extra_args(["--grammar", token]) == ["--grammar", token]
def test_denied_env_twins_are_scrubbed():
env = {
"LLAMA_ARG_AGENT": "1",
"LLAMA_ARG_TOOLS": "all",
"LLAMA_ARG_MCP_SERVERS_JSON": "{}",
"PATH": "/usr/bin",
}
removed = _lsa.scrub_denied_env(env)
assert set(removed) == {"LLAMA_ARG_AGENT", "LLAMA_ARG_TOOLS", "LLAMA_ARG_MCP_SERVERS_JSON"}
assert env == {"PATH": "/usr/bin"}
def test_scrubbing_is_a_no_op_without_the_twins():
env = {"PATH": "/usr/bin", "LLAMA_ARG_MLOCK": "1"}
assert _lsa.scrub_denied_env(env) == []
assert env == {"PATH": "/usr/bin", "LLAMA_ARG_MLOCK": "1"}
def test_every_denied_env_var_names_a_denied_flag():
# Both prefixes: llama.cpp uses LLAMA_ and LLAMA_ARG_ depending on flag/release.
for name in _lsa.DENIED_ENV_VARS:
stem = name.removeprefix("LLAMA_ARG_").removeprefix("LLAMA_")
flag = _lsa.DENIED_ENV_TWIN_FLAGS.get(name) or "--" + stem.lower().replace("_", "-")
assert is_managed_flag(flag), f"{name} has no denied flag ({flag})"
def test_every_denied_flag_with_a_twin_in_the_help_is_scrubbed():
# Enumerated from b10342 --help; llama.cpp applies env BEFORE argv.
for env_var, flag in (
("LLAMA_ARG_UI_MCP_PROXY", "--ui-mcp-proxy"),
("LLAMA_ARG_UI", "--ui"),
("LLAMA_ARG_STATIC_PATH", "--path"),
("LLAMA_ARG_MODELS_DIR", "--models-dir"),
("LLAMA_ARG_MODELS_AUTOLOAD", "--models-autoload"),
("LLAMA_ARG_EMBEDDINGS", "--embeddings"),
("LLAMA_ARG_RERANKING", "--reranking"),
("LLAMA_ARG_MODEL", "--model"),
("LLAMA_ARG_HF_REPO", "--hf-repo"),
("LLAMA_ARG_HOST", "--host"),
("LLAMA_ARG_PORT", "--port"),
("LLAMA_ARG_N_PARALLEL", "--parallel"),
("LLAMA_ARG_SSL_KEY_FILE", "--ssl-key-file"),
("LLAMA_ARG_SSL_CERT_FILE", "--ssl-cert-file"),
):
assert is_managed_flag(flag), flag
assert env_var in _lsa.DENIED_ENV_VARS, env_var
env = {name: "1" for name in _lsa.DENIED_ENV_VARS}
env["PATH"] = "/usr/bin"
# Projector twins are an input: _launch_has_mmproj reads them for vision/audio state.
for kept in ("LLAMA_ARG_MMPROJ", "LLAMA_ARG_MMPROJ_URL"):
assert kept not in _lsa.DENIED_ENV_VARS, kept
# HF_TOKEN is not scrubbed: Unsloth's own downloads use it.
assert "HF_TOKEN" not in _lsa.DENIED_ENV_VARS
_lsa.scrub_denied_env(env)
assert env == {"PATH": "/usr/bin"}
def test_the_projector_env_twins_survive_the_scrub():
# Env twin is an input for _launch_has_mmproj; scrubbing made loads text-only.
env = {
"LLAMA_ARG_MMPROJ": "/models/mmproj-F16.gguf",
"LLAMA_ARG_MMPROJ_URL": "https://example.invalid/mmproj-F16.gguf",
"LLAMA_ARG_AGENT": "1",
}
removed = _lsa.scrub_denied_env(env)
assert removed == ["LLAMA_ARG_AGENT"]
assert env == {
"LLAMA_ARG_MMPROJ": "/models/mmproj-F16.gguf",
"LLAMA_ARG_MMPROJ_URL": "https://example.invalid/mmproj-F16.gguf",
}
assert "LLAMA_ARG_MMPROJ" not in _lsa.DENIED_ENV_VARS
assert "LLAMA_ARG_MMPROJ_URL" not in _lsa.DENIED_ENV_VARS
@pytest.mark.parametrize(
"env,expected",
[
({}, False),
(None, False),
({"LLAMA_ARG_LOAD_MODE": "mmap"}, True),
({"LLAMA_ARG_LOAD_MODE": "dio"}, True),
({"LLAMA_ARG_LOAD_MODE": " "}, False),
({"LLAMA_ARG_MLOCK": "1"}, True),
({"LLAMA_ARG_MLOCK": "0"}, False),
({"LLAMA_ARG_MMAP": "on"}, True),
({"LLAMA_ARG_MMAP": "off"}, True),
({"LLAMA_ARG_DIO": "1"}, True),
# Negative aliases count by presence: get_value_from_env forces '0'.
({"LLAMA_ARG_NO_MMAP": "0"}, True),
({"LLAMA_ARG_NO_DIO": ""}, True),
({"LLAMA_ARG_FIT": "off", "LLAMA_ARG_DEVICE": "none"}, False),
],
)
def test_memory_env_selects_load_mode(env, expected):
assert _lsa.memory_env_selects_load_mode(env) is expected
# Both strip paths share this test so a value survives either reload.
def test_matching_ctx_override_confirms_only_an_exact_positive_int():
assert _lsa.matches_explicit_ctx_override(["--ctx-size", "100352"], 100352)
assert _lsa.matches_explicit_ctx_override(["-c", "100352"], 100352)
assert _lsa.matches_explicit_ctx_override(["--ctx_size", "100352"], 100352)
assert _lsa.matches_explicit_ctx_override(
["--ctx-size", "8192", "--ctx-size", "100352"], 100352
)
assert not _lsa.matches_explicit_ctx_override(
["--ctx-size", "100352", "--ctx-size", "8192"], 100352
)
assert not _lsa.matches_explicit_ctx_override(["--ctx-size", "8192"], 100352)
assert not _lsa.matches_explicit_ctx_override(["--top-k", "40"], 100352)
assert not _lsa.matches_explicit_ctx_override(None, 100352)
def test_matching_ctx_override_is_total_over_stored_junk():
# Rows are returned verbatim on read, so any legacy JSON must not raise.
for n_ctx in (None, 0, -1, "100352", "", "x", 100352.0, True, False, [100352], {"v": 1}):
assert not _lsa.matches_explicit_ctx_override(["--ctx-size", "100352"], n_ctx), n_ctx
assert not _lsa.matches_explicit_ctx_override(["--ctx-size", "--top-k"], 100352)
# llama.cpp is last-wins: strip must read the EFFECTIVE mlock/mmap state.
def _rewritten_state(argv, env = None):
"""``((mlock, reserves_ram), argv, env)`` after the pageable rewrite."""
env = dict(env or {})
out, overridden = _lsa.force_pageable_load(list(argv), env)
return _lsa.resolve_effective_memory_state(out, env), out, env, overridden
@pytest.mark.parametrize(
"argv",
[
["--mlock", "--no-mmap"],
["--mlock", "--no-direct-io"],
["--mlock", "--load-mode", "none"],
["--load-mode", "mlock", "--no-mmap"],
["--load-mode=mlock", "--no-mmap"],
["--load-mode", "mmap+mlock", "--no-mmap"],
["--load-mode=mmap+mlock", "--no-mmap"],
["--load-mode", "mmap+mlock", "--no-direct-io"],
],
ids = [
"no-mmap",
"no-dio",
"load-mode-none",
"load-mode-mlock",
"load-mode-mlock-equals",
"load-mode-mmap-mlock",
"load-mode-mmap-mlock-equals",
"load-mode-mmap-mlock-no-dio",
],
)
def test_a_shadowed_lock_is_not_resurrected_by_the_pageable_rewrite(argv):
assert _lsa.resolve_effective_memory_state(argv) == (False, True)
(mlock, reserves), out, _env, overridden = _rewritten_state(argv)
assert overridden, f"the unmapped launch was not rewritten at all: {out}"
assert not reserves, f"the child still holds a full unmapped copy: {out}"
assert not mlock, f"the rewrite page-locked the oversized mapping: {out}"
@pytest.mark.parametrize(
"argv, expect_tokens",
[
(["--no-mmap", "--mlock"], ["--mlock"]),
(["--load-mode", "mlock"], ["--load-mode", "mmap+mlock"]),
(["--load-mode=mlock"], ["--load-mode", "mmap+mlock"]),
],
ids = ["no-mmap-then-mlock", "load-mode-mlock", "load-mode-mlock-equals"],
)
def test_an_effective_lock_survives_the_pageable_rewrite(argv, expect_tokens):
"""Control: a keep-in-RAM request is mmap+mlock unless a flag shadows it, not discarded."""
assert _lsa.resolve_effective_memory_state(argv) == (True, True)
(mlock, reserves), out, _env, overridden = _rewritten_state(argv)
assert overridden, f"the unmapped launch was not rewritten at all: {out}"
assert (mlock, reserves) == (True, False), f"the lock was dropped or kept unmapped: {out}"
assert out == expect_tokens, out
def test_the_env_twin_of_a_shadowed_lock_goes_too():
"""An env LLAMA_ARG_MLOCK beside LLAMA_ARG_NO_MMAP is shadowed like its argv pair, so strip it too."""
env = {"LLAMA_ARG_MLOCK": "1", "LLAMA_ARG_NO_MMAP": "1"}
assert _lsa.resolve_effective_memory_state([], env) == (False, True)
(mlock, reserves), _out, out_env, overridden = _rewritten_state([], env)
assert "LLAMA_ARG_NO_MMAP" not in out_env
assert "LLAMA_ARG_MLOCK" not in out_env, out_env
assert "LLAMA_ARG_MLOCK" in overridden, overridden
assert (mlock, reserves) == (False, False)
def test_the_env_mapped_lock_mode_shadowed_by_an_argv_selector_goes_too():
"""An env LLAMA_ARG_LOAD_MODE shadowed by an argv --no-mmap still locks the child; strip it too."""
env = {"LLAMA_ARG_LOAD_MODE": "mmap+mlock"}
assert _lsa.resolve_effective_memory_state(["--no-mmap"], env) == (False, True)
(mlock, reserves), _out, out_env, overridden = _rewritten_state(["--no-mmap"], env)
assert "LLAMA_ARG_LOAD_MODE" not in out_env, out_env
assert overridden, "the unmapped launch was not rewritten at all"
assert (mlock, reserves) == (
False,
False,
), f"the rewrite page-locked the oversized mapping: {out_env}"
def test_an_unshadowed_mapped_lock_is_left_entirely_alone():
"""An unshadowed mmap+mlock already maps, so it must be left untouched and reported as no override."""
argv = ["--load-mode", "mmap+mlock"]
assert _lsa.resolve_effective_memory_state(argv) == (True, False)
(mlock, reserves), out, _env, overridden = _rewritten_state(argv)
assert out == argv, out
assert not overridden, f"an already-mapped launch was reported as overridden: {overridden}"
assert (mlock, reserves) == (True, False)
def test_the_env_mlock_mode_that_is_not_shadowed_keeps_its_lock():
"""The control for the env half: LLAMA_ARG_LOAD_MODE=mlock with nothing after it
really is locked, so it becomes the mapped twin instead of being dropped."""
env = {"LLAMA_ARG_LOAD_MODE": "mlock"}
assert _lsa.resolve_effective_memory_state([], env) == (True, True)
(mlock, reserves), _out, out_env, _overridden = _rewritten_state([], env)
assert out_env["LLAMA_ARG_LOAD_MODE"] == "mmap+mlock"
assert (mlock, reserves) == (True, False)
def test_an_argv_lock_that_overrides_an_inherited_selector_survives():
"""The cross case, and the reason the rewrite cannot read either side alone: argv
is resolved after the environment, so --mlock beats an inherited LLAMA_ARG_NO_MMAP
and the lock is the user's live request."""
env = {"LLAMA_ARG_NO_MMAP": "1"}
argv = ["--mlock"]
assert _lsa.resolve_effective_memory_state(argv, env) == (True, True)
(mlock, reserves), out, out_env, _overridden = _rewritten_state(argv, env)
assert "LLAMA_ARG_NO_MMAP" not in out_env
assert out == ["--mlock"], out
assert (mlock, reserves) == (True, False)
def test_a_pageable_launch_keeps_every_token_including_its_lock():
"""Nothing here reserves RAM, so the override does not apply and the launch comes
back byte for byte -- the mlock strip is scoped to a rewrite, not to any --mlock."""
argv = ["--mlock", "--load-mode", "dio"]
assert _lsa.resolve_effective_memory_state(argv) == (False, False)
out, overridden = _lsa.force_pageable_load(list(argv), {})
assert out == argv and overridden == []
@pytest.mark.parametrize("flag", ["--mmproj", "-mm"])
def test_custom_projector_is_allowed(flag):
args = [flag, "/models/custom projector.gguf"]
assert validate_extra_args(args) == args
def test_ngram_mod_extras_are_respelled_for_a_legacy_build():
from core.inference.llama_server_args import translate_ngram_mod_args
knobs = [
"--spec-ngram-mod-n-match",
"16",
"--spec-ngram-mod-n-min=8",
"--spec-ngram-mod-n-max",
"64",
"--top-k",
"20",
]
assert translate_ngram_mod_args(knobs, "new") == knobs
assert translate_ngram_mod_args(knobs, None) == knobs
assert translate_ngram_mod_args(knobs, "legacy") == [
"--spec-ngram-size-n",
"16",
"--draft-min",
"8",
"--draft-max",
"64",
"--top-k",
"20",
]
assert translate_ngram_mod_args(knobs, "legacy", chain_with_mtp = True) == [
"--spec-ngram-size-n",
"16",
"--top-k",
"20",
]
# A trailing flag with no value is left for llama-server to reject.
assert translate_ngram_mod_args(["--spec-ngram-mod-n-max"], "legacy") == [
"--spec-ngram-mod-n-max"
]
def test_the_launch_respells_user_ngram_mod_extras_last():
"""Source check: reaching the emit point needs a real binary."""
import inspect
from core.inference.llama_cpp import LlamaCppBackend
src = inspect.getsource(LlamaCppBackend.load_model)
emit = src[src.index("_emit_extra_args = self._strip_mmproj_args(") :]
emit = emit[: emit.index("cmd.extend(str(a) for a in _emit_extra_args)")]
assert "translate_ngram_mod_args(" in emit
assert '_caps.get("ngram_mod_flavor")' in emit
assert emit.index("_strip_device_extra_args") < emit.index("translate_ngram_mod_args(")
assert "_extra_args_requests_mtp(" in emit[emit.index("translate_ngram_mod_args(") :]
def test_ngram_mod_underscore_spelling_is_respelled_too():
from core.inference.llama_server_args import translate_ngram_mod_args
assert translate_ngram_mod_args(
["--spec_ngram_mod_n_min", "8", "--spec_ngram_mod_n_match=4"], "legacy"
) == ["--draft-min", "8", "--spec-ngram-size-n", "4"]
def test_user_spec_type_with_mtp_counts_as_chained():
from core.inference.llama_cpp import _child_spec_env, _extra_args_requests_mtp
extras = ["--spec-type", "ngram-mod,draft-mtp", "--spec-ngram-mod-n-min", "48"]
assert _extra_args_requests_mtp(extras, env = _child_spec_env(extras))
assert not _extra_args_requests_mtp(["--spec-ngram-mod-n-min", "48"], env = {})
def test_owner_only_path_flags_names_each_file_option_once():
args = [
"--ctx-size",
"4096",
"--lora",
"/a.gguf",
"--lora",
"/b.gguf",
"--chat_template_file",
"/t.jinja",
"-jf",
"/s.json",
"--temp",
"0.7",
]
assert _lsa.owner_only_path_flags(args) == ["--lora", "--chat-template-file", "-jf"]
assert _lsa.owner_only_path_flags(["--ctx-size", "4096", "-ngl", "99"]) == []
assert _lsa.owner_only_path_flags(None) == []
assert validate_extra_args(args) == args
@pytest.mark.parametrize("chain_with_mtp", [False, True])
def test_translate_ngram_mod_does_not_consume_a_following_flag(chain_with_mtp):
# Under MTP the swallowed pair is dropped, leaving the next flag's value as a bare positional.
from core.inference.llama_server_args import translate_ngram_mod_args, validate_extra_args
args = validate_extra_args(
["--spec-type", "draft-mtp", "--spec-ngram-mod-n-min", "--top-k", "/restricted/model.gguf"]
)
out = translate_ngram_mod_args(args, "legacy", chain_with_mtp = chain_with_mtp)
assert out[-2:] == ["--top-k", "/restricted/model.gguf"]
validate_extra_args(out)
@pytest.mark.parametrize(
"argv, env, auto",
[
([], {}, True),
(["--load-mode", "auto"], {}, True),
(["--load-mode=auto"], {}, True),
(["--load-mode", "none", "--load-mode", "auto"], {}, True),
([], {"LLAMA_ARG_LOAD_MODE": "auto"}, True),
(["--load-mode", "auto"], {"LLAMA_ARG_LOAD_MODE": "mmap"}, True),
(["--load-mode", "mmap"], {}, False),
(["--load-mode", "none"], {}, False),
([], {"LLAMA_ARG_LOAD_MODE": "mmap"}, False),
(["--mlock"], {}, False),
(["--mmap"], {}, False),
(["--no-mmap"], {}, False),
([], {"LLAMA_ARG_NO_MMAP": "0"}, False),
([], {"LLAMA_ARG_DIO": "1"}, False),
(["--load-mode"], {}, True),
],
)
def test_load_mode_left_auto(argv, env, auto):
assert _lsa.load_mode_left_auto(argv, env) is auto
def test_auto_reserves_ram_only_where_llama_cpp_resolves_it_to_none():
assert _lsa.resolve_effective_load_state([], {}) == (False, False, False)
assert _lsa.resolve_effective_load_state([], {}, auto_unmapped = True) == (False, True, False)
assert _lsa.resolve_effective_memory_state(["--load-mode", "auto"], {}, auto_unmapped = True) == (
False,
True,
)
assert _lsa.resolve_effective_load_state(["--load-mode", "mmap"], {}, auto_unmapped = True) == (
False,
False,
False,
)
assert _lsa.resolve_effective_load_state(["--load-mode", "dio"], {}, auto_unmapped = True) == (
False,
False,
True,
)
def test_the_pageable_rewrite_maps_an_unselected_mode_on_an_igpu():
out, overridden = _lsa.force_pageable_load(["--fit", "on"], {}, auto_unmapped = True)
assert out == ["--fit", "on", "--load-mode", "mmap"] and overridden
assert _lsa.resolve_effective_memory_state(out, {}, auto_unmapped = True) == (False, False)
# An inherited LLAMA_ARG_LOAD_MODE=auto loses to the appended argv.
env = {"LLAMA_ARG_LOAD_MODE": "auto"}
out, _ = _lsa.force_pageable_load([], env, auto_unmapped = True)
assert _lsa.resolve_effective_memory_state(out, env, auto_unmapped = True) == (False, False)
for argv, env in (
(["--load-mode", "none"], {}),
(["--no-mmap"], {}),
([], {"LLAMA_ARG_NO_MMAP": "1"}),
):
out, overridden = _lsa.force_pageable_load(argv, env, auto_unmapped = True)
assert overridden and out[-2:] == ["--load-mode", "mmap"], (argv, env, out)
assert _lsa.resolve_effective_memory_state(out, env, auto_unmapped = True) == (False, False)
assert _lsa.force_pageable_load(["--load-mode", "mlock"], {}, auto_unmapped = True)[0] == [
"--load-mode",
"mmap+mlock",
]
assert _lsa.force_pageable_load([], {}) == ([], [])
assert _lsa.force_pageable_load(["--load-mode", "mmap"], {}, auto_unmapped = True) == (
["--load-mode", "mmap"],
[],
)