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
"""Fake cgroup trees drive the single usable-host-RAM reader that all memory sizing consumers share."""
import os
import sys
import types
from pathlib import Path
import pytest
BACKEND_ROOT = Path(__file__).resolve().parents[1]
if str(BACKEND_ROOT) not in sys.path:
sys.path.insert(0, str(BACKEND_ROOT))
try:
from utils import host_memory # noqa: E402
except ImportError: # a tree without the shared reader: only the consumer contract tests apply
host_memory = None
reader = pytest.mark.skipif(host_memory is None, reason = "utils.host_memory not in this tree")
GIB = 1024**3
MIB = 1024**2
# What the kernel writes to memory.limit_in_bytes for an unlimited v1 group on 4 KiB pages.
V1_UNLIMITED = 9223372036854771712
def _write(path: Path, text: str) -> None:
path.parent.mkdir(parents = True, exist_ok = True)
path.write_text(text, encoding = "utf-8")
def _v2(
root: Path,
relative: str,
*,
limit,
current = None,
inactive_file = None,
) -> Path:
d = root / relative.strip("/") if relative.strip("/") else root
d.mkdir(parents = True, exist_ok = True)
if limit is not None:
_write(d / "memory.max", limit if isinstance(limit, str) else str(limit))
if current is not None:
_write(d / "memory.current", current if isinstance(current, str) else str(current))
if inactive_file is not None:
_write(d / "memory.stat", f"anon 1\nfile 2\ninactive_file {inactive_file}\nactive_file 3\n")
return d
@pytest.fixture
def fake_cgroup(tmp_path, monkeypatch):
"""Point every cgroup reader (the shared one and llama.cpp's patch points) at a fake tree."""
root = tmp_path / "cgroup"
root.mkdir()
proc = tmp_path / "proc_self_cgroup"
if host_memory is not None:
monkeypatch.setattr(host_memory, "CGROUP_ROOT", str(root))
monkeypatch.setattr(host_memory, "PROC_SELF_CGROUP", str(proc))
from core.inference import llama_cpp
monkeypatch.setattr(llama_cpp, "_CGROUP_ROOT", str(root))
monkeypatch.setattr(llama_cpp, "_PROC_SELF_CGROUP", str(proc))
def membership(text: str) -> None:
proc.write_text(text, encoding = "utf-8")
return types.SimpleNamespace(root = root, membership = membership)
@pytest.fixture
def host(monkeypatch):
"""A fixed host-wide psutil reading: 1.5 TiB total, 1.2 TiB available."""
import psutil
state = {"total": 1536 * GIB, "available": 1229 * GIB}
monkeypatch.setattr(
psutil,
"virtual_memory",
lambda: types.SimpleNamespace(
total = state["total"], available = state["available"], percent = 20.0
),
)
return state
@reader
def test_no_cgroup_keeps_the_host_reading(fake_cgroup, host):
fake_cgroup.membership("0::/\n")
assert host_memory.cgroup_memory_budgets() == []
assert host_memory.cgroup_headroom_mib() is None
assert host_memory.cgroup_limit_mib() is None
assert host_memory.usable_host_ram_mib() == host["available"] // MIB
assert host_memory.host_ram_capacity_mib() == host["total"] // MIB
@reader
def test_unlimited_v2_and_v1_levels_are_no_limit(fake_cgroup, host):
fake_cgroup.membership("0::/user.slice/app.scope\n5:memory:/docker/abc\n")
_v2(fake_cgroup.root, "user.slice/app.scope", limit = "max", current = 10 * GIB)
_v2(fake_cgroup.root, "user.slice", limit = "max", current = 20 * GIB)
v1 = fake_cgroup.root / "memory" / "docker" / "abc"
_write(v1 / "memory.limit_in_bytes", str(V1_UNLIMITED))
_write(v1 / "memory.usage_in_bytes", str(5 * GIB))
assert host_memory.cgroup_memory_budgets() == []
assert host_memory.usable_host_ram_mib() == host["available"] // MIB
@reader
def test_v2_headroom_is_limit_minus_working_set(fake_cgroup, host):
fake_cgroup.membership("0::/user.slice/run-x.scope\n")
_v2(
fake_cgroup.root,
"user.slice/run-x.scope",
limit = 58 * GIB,
current = 30 * GIB,
inactive_file = 6 * GIB,
)
# 58 - (30 - 6 reclaimable inactive file) = 34 GiB.
assert host_memory.cgroup_headroom_mib() == 34 * 1024
assert host_memory.cgroup_limit_mib() == 58 * 1024
assert host_memory.usable_host_ram_mib() == 34 * 1024
assert host_memory.host_ram_capacity_mib() == 58 * 1024
@reader
def test_v1_headroom_uses_hierarchical_inactive_file(fake_cgroup, host):
fake_cgroup.membership("12:memory:/docker/abc\n11:cpu,cpuacct:/docker/abc\n")
d = fake_cgroup.root / "memory" / "docker" / "abc"
_write(d / "memory.limit_in_bytes", str(16 * GIB))
_write(d / "memory.usage_in_bytes", str(10 * GIB))
_write(d / "memory.stat", f"inactive_file {1 * GIB}\ntotal_inactive_file {2 * GIB}\n")
assert host_memory.cgroup_headroom_mib() == 8 * 1024
assert host_memory.cgroup_limit_mib() == 16 * 1024
assert host_memory.usable_host_ram_mib() == 8 * 1024
@reader
def test_v1_container_root_mount(fake_cgroup, host):
# A v1 container sees its own group at the mount root while /proc/self/cgroup names the host path.
fake_cgroup.membership("12:memory:/docker/abc\n")
d = fake_cgroup.root / "memory"
_write(d / "memory.limit_in_bytes", str(8 * GIB))
_write(d / "memory.usage_in_bytes", str(3 * GIB))
assert host_memory.cgroup_headroom_mib() == 5 * 1024
assert host_memory.cgroup_limit_mib() == 8 * 1024
@reader
def test_nested_parent_slice_binds_with_sibling_usage(fake_cgroup, host):
# The leaf scope allows 70 GiB but its parent slice caps at 64 GiB and siblings already use 40.
fake_cgroup.membership("0::/workload.slice/studio.scope\n")
_v2(fake_cgroup.root, "workload.slice/studio.scope", limit = 70 * GIB, current = 10 * GIB)
_v2(fake_cgroup.root, "workload.slice", limit = 64 * GIB, current = 50 * GIB)
assert host_memory.cgroup_headroom_mib() == 14 * 1024 # parent remainder, not the leaf's 60
assert host_memory.cgroup_limit_mib() == 64 * 1024 # tightest limit
assert host_memory.usable_host_ram_mib() == 14 * 1024
@reader
def test_nested_unlimited_leaf_under_limited_ancestor(fake_cgroup, host):
fake_cgroup.membership("0::/a.slice/b.slice/c.scope\n")
_v2(fake_cgroup.root, "a.slice/b.slice/c.scope", limit = "max", current = 5 * GIB)
_v2(fake_cgroup.root, "a.slice/b.slice", limit = "max", current = 6 * GIB)
_v2(fake_cgroup.root, "a.slice", limit = 32 * GIB, current = 12 * GIB)
assert host_memory.cgroup_headroom_mib() == 20 * 1024
assert host_memory.cgroup_limit_mib() == 32 * 1024
@reader
def test_host_reading_wins_when_it_is_tighter(fake_cgroup, host):
host["available"] = 10 * GIB
fake_cgroup.membership("0::/s.scope\n")
_v2(fake_cgroup.root, "s.scope", limit = 58 * GIB, current = 1 * GIB)
assert host_memory.usable_host_ram_mib() == 10 * 1024
@reader
def test_over_limit_usage_clamps_headroom_to_zero(fake_cgroup, host):
fake_cgroup.membership("0::/s.scope\n")
_v2(fake_cgroup.root, "s.scope", limit = 8 * GIB, current = 9 * GIB)
assert host_memory.cgroup_headroom_mib() == 0
assert host_memory.usable_host_ram_mib() == 0
@reader
@pytest.mark.parametrize(
"limit, current, expect_headroom_mib",
[
("garbage", str(GIB), None), # unparsable limit: level skipped
("", str(GIB), None), # empty limit file
("-5", str(GIB), None), # negative limit
(str(4 * GIB), "garbage", 4 * 1024), # unparsable usage: whole limit is the remainder
(str(4 * GIB), "-1", 4 * 1024), # negative usage: same
],
)
@reader
def test_malformed_files_never_raise(fake_cgroup, host, limit, current, expect_headroom_mib):
fake_cgroup.membership("0::/s.scope\n")
_v2(fake_cgroup.root, "s.scope", limit = limit, current = current)
assert host_memory.cgroup_headroom_mib() == expect_headroom_mib
usable = host_memory.usable_host_ram_mib()
expected = host["available"] // MIB if expect_headroom_mib is None else expect_headroom_mib
assert usable == expected
@reader
def test_malformed_stat_and_binary_files_never_raise(fake_cgroup, host):
fake_cgroup.membership("0::/s.scope\n")
d = _v2(fake_cgroup.root, "s.scope", limit = 8 * GIB, current = 2 * GIB)
(d / "memory.stat").write_bytes(b"inactive_file \xff\xfe\nnot a stat line at all\n")
assert host_memory.cgroup_headroom_mib() == 6 * 1024
(d / "memory.max").write_bytes(b"\xff\xfe\x00")
assert host_memory.cgroup_headroom_mib() is None
@reader
def test_unreadable_proc_self_cgroup_reads_the_root_only(fake_cgroup, host):
# No /proc/self/cgroup (e.g. a sandbox): only the mount root is consulted.
_v2(fake_cgroup.root, "", limit = 12 * GIB, current = 2 * GIB)
assert host_memory.cgroup_headroom_mib() == 10 * 1024
@reader
def test_escaping_relative_path_falls_back_to_the_root(fake_cgroup, host):
fake_cgroup.membership("0::/../../etc\n")
_v2(fake_cgroup.root, "", limit = 12 * GIB, current = 2 * GIB)
assert host_memory.cgroup_headroom_mib() == 10 * 1024
@reader
def test_psutil_missing_falls_back_to_proc_meminfo(fake_cgroup, monkeypatch):
fake_cgroup.membership("0::/\n")
monkeypatch.setitem(sys.modules, "psutil", None)
if os.path.exists("/proc/meminfo"):
assert host_memory.system_available_mib() is not None
assert host_memory.system_total_mib() is not None
@reader
def test_llama_cpp_readers_delegate_to_the_shared_one(fake_cgroup, host):
from core.inference.llama_cpp import LlamaCppBackend
fake_cgroup.membership("0::/s.scope\n")
_v2(fake_cgroup.root, "s.scope", limit = 58 * GIB, current = 20 * GIB)
assert LlamaCppBackend._cgroup_available_memory_mib() == host_memory.cgroup_headroom_mib()
assert LlamaCppBackend._cgroup_memory_limit_mib() == host_memory.cgroup_limit_mib()
assert LlamaCppBackend._available_system_memory_mib() == host_memory.usable_host_ram_mib()
assert LlamaCppBackend._host_memory_capacity_mib() == host_memory.host_ram_capacity_mib()
def test_pin_budget_sizes_from_the_cgroup_headroom(fake_cgroup, host):
from core.inference import diffusion_memory as dm
fake_cgroup.membership("0::/s.scope\n")
_v2(fake_cgroup.root, "s.scope", limit = 58 * GIB, current = 30 * GIB)
reserve = max(dm._PIN_RESERVE_MIN_MIB, int(58 * 1024 * dm._PIN_RESERVE_FRACTION))
assert dm._pin_budget_mib() == 28 * 1024 - reserve
_v2(fake_cgroup.root, "s.scope", limit = 58 * GIB, current = 52 * GIB)
assert dm._pin_budget_mib() == 0
def test_pin_budget_without_a_limit_is_unchanged(fake_cgroup, host):
from core.inference import diffusion_memory as dm
fake_cgroup.membership("0::/\n")
total_mib, available_mib = host["total"] // MIB, host["available"] // MIB
reserve = max(dm._PIN_RESERVE_MIN_MIB, int(total_mib * dm._PIN_RESERVE_FRACTION))
assert dm._pin_budget_mib() == available_mib - reserve
def _h3_held(monkeypatch, held_gb: float) -> None:
from core.inference import video_minimax_h3 as vmh3
kb = int(held_gb * 1e9 / 1024)
monkeypatch.setattr(vmh3, "_proc_status_kb", lambda fields: {"RssAnon": kb, "RssShmem": 0})
def test_h3_guard_capacity_is_capped_by_the_cgroup(fake_cgroup, host, monkeypatch):
from core.inference import video_minimax_h3 as vmh3
_h3_held(monkeypatch, 30.0)
fake_cgroup.membership("0::/s.scope\n")
# 58 GiB limit, the server already charges 35 GiB (30 GB of it the reusable model).
_v2(fake_cgroup.root, "s.scope", limit = 58 * GIB, current = 35 * GIB)
capacity = vmh3.h3_host_capacity_bytes()
assert capacity == 23 * GIB + int(30.0 * 1e9 / 1024) * 1024
assert capacity <= 58 * GIB
kw = dict(text_encoder_gb = 27.2, transformer_gb = 20.3, text_encoder_streamed = True)
assert vmh3.h3_host_ram_shortfall(11.0, **kw) is None
# Below the measured floor the cgroup is what refuses, not the 1.2 TiB the host reports.
floor = vmh3.H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB
small = int((floor - 2.0) * 1e9)
_v2(fake_cgroup.root, "s.scope", limit = small, current = 35 * GIB)
message = vmh3.h3_host_ram_shortfall(11.0, **kw)
assert message is not None and f"{floor:.0f} GB" in message
def test_h3_guard_capacity_never_exceeds_the_limit(fake_cgroup, host, monkeypatch):
from core.inference import video_minimax_h3 as vmh3
# Held anon charged to ANOTHER cgroup (or counted twice) still cannot lift capacity past the limit.
_h3_held(monkeypatch, 60.0)
fake_cgroup.membership("0::/s.scope\n")
_v2(fake_cgroup.root, "s.scope", limit = 58 * GIB, current = 1 * GIB)
assert vmh3.h3_host_capacity_bytes() == 58 * GIB
def test_h3_guard_without_a_limit_is_unchanged(fake_cgroup, host, monkeypatch):
from core.inference import video_minimax_h3 as vmh3
_h3_held(monkeypatch, 40.0)
fake_cgroup.membership("0::/\n")
assert vmh3.h3_host_capacity_bytes() == host["available"] + int(40.0 * 1e9 / 1024) * 1024
assert (
vmh3.h3_host_ram_shortfall(
11.0, text_encoder_gb = 27.2, transformer_gb = 20.3, text_encoder_streamed = True
)
is None
)
def test_h3_guard_admits_the_tier_under_a_limit_that_fits(fake_cgroup, host, monkeypatch):
from core.inference import video_minimax_h3 as vmh3
_h3_held(monkeypatch, 40.0)
fake_cgroup.membership("0::/s.scope\n")
_v2(fake_cgroup.root, "s.scope", limit = 80 * GIB, current = 42 * GIB)
assert (
vmh3.h3_host_ram_shortfall(
11.0, text_encoder_gb = 27.2, transformer_gb = 20.3, text_encoder_streamed = True
)
is None
)
def _system_memory(monkeypatch):
import main
monkeypatch.setattr(
main,
"_get_cached_system_gpu_info",
lambda logger, refresh_memory = False: ({"available": False}, {"available": False}),
)
return main.get_system_info(current_subject = "test")["memory"]
def test_api_system_memory_reports_the_cgroup_view(fake_cgroup, host, monkeypatch):
from core.inference import video_minimax_h3 as vmh3
fake_cgroup.membership("0::/s.scope\n")
_v2(fake_cgroup.root, "s.scope", limit = 58 * GIB, current = 2 * GIB)
memory = _system_memory(monkeypatch)
assert memory["total_gb"] == 58.0
assert memory["available_gb"] == 56.0
assert memory["percent_used"] == pytest.approx(3.4, abs = 0.05)
tiers = vmh3.h3_diffusers_fit_tiers()
if tiers:
# The picker's RAM tier is the guard's floor: 58 GiB admits the H3 row, as the guard admits the render.
assert memory["available_gb"] >= tiers[0]["system_ram_gb"]
floor_gib = tiers[0]["system_ram_gb"]
_v2(fake_cgroup.root, "s.scope", limit = int((floor_gib - 1) * GIB), current = 0)
# A limit under the floor withdraws the row, while the host still reports 1.2 TiB free.
assert _system_memory(monkeypatch)["available_gb"] < floor_gib
def test_api_system_memory_without_a_limit_is_unchanged(fake_cgroup, host, monkeypatch):
fake_cgroup.membership("0::/\n")
memory = _system_memory(monkeypatch)
assert memory["total_gb"] == round(host["total"] / GIB, 2)
assert memory["available_gb"] == round(host["available"] / GIB, 2)
assert memory["percent_used"] == 20.0
def _stat(directory: Path, **counters) -> None:
_write(directory / "memory.stat", "".join(f"{k} {v}\n" for k, v in counters.items()))
@reader
def test_v2_active_file_cache_is_reclaimable(fake_cgroup, host):
"""Kaggle: twice-read model files sit on active_file; counting them as used shrank headroom 17 -> 3 GiB."""
fake_cgroup.membership("0::/\n")
_v2(fake_cgroup.root, "/", limit = 32 * GIB, current = 30 * GIB)
_stat(
fake_cgroup.root,
anon = 15 * GIB,
file = 15 * GIB,
inactive_file = 1 * GIB,
active_file = 14 * GIB,
shmem = 0,
)
# 32 - (30 - 1 inactive - 14 active) = 17 GiB, not 32 - (30 - 1) = 3 GiB.
assert host_memory.cgroup_headroom_mib() == 17 * 1024
assert host_memory.usable_host_ram_mib() == 17 * 1024
assert host_memory.cgroup_limit_mib() == 32 * 1024
@reader
def test_v2_shmem_is_never_counted_as_free(fake_cgroup, host):
"""shmem/tmpfs is in ``file`` but on the anon LRU: not droppable."""
fake_cgroup.membership("0::/\n")
_v2(fake_cgroup.root, "/", limit = 32 * GIB, current = 28 * GIB)
_stat(
fake_cgroup.root,
anon = 8 * GIB,
file = 20 * GIB,
shmem = 12 * GIB,
inactive_anon = 4 * GIB,
active_anon = 16 * GIB,
inactive_file = 2 * GIB,
active_file = 6 * GIB,
)
headroom = host_memory.cgroup_headroom_mib()
# 32 - (28 - 2 - 6) = 12 GiB; crediting ``file`` (incl. the 12 GiB shmem) would claim 24 GiB.
assert headroom == 12 * 1024
assert headroom < (32 - (28 - 20)) * 1024
@reader
def test_v2_mapped_dirty_and_writeback_active_pages_are_not_credited(fake_cgroup, host):
fake_cgroup.membership("0::/\n")
_v2(fake_cgroup.root, "/", limit = 32 * GIB, current = 30 * GIB)
_stat(
fake_cgroup.root,
inactive_file = 2 * GIB,
active_file = 10 * GIB,
file_mapped = 4 * GIB,
file_dirty = 1 * GIB,
file_writeback = 1 * GIB,
)
# Active credit = 10 - 4 - 1 - 1 = 4 GiB: 32 - (30 - 2 - 4) = 8 GiB.
assert host_memory.cgroup_headroom_mib() == 8 * 1024
@reader
def test_v2_never_below_the_inactive_only_reading(fake_cgroup, host):
"""Over-subtraction clamps at zero."""
fake_cgroup.membership("0::/\n")
_v2(fake_cgroup.root, "/", limit = 32 * GIB, current = 30 * GIB)
_stat(fake_cgroup.root, inactive_file = 2 * GIB, active_file = 3 * GIB, file_mapped = 9 * GIB)
assert host_memory.cgroup_headroom_mib() == 4 * 1024
@reader
def test_v2_host_meminfo_still_bounds_the_reading(fake_cgroup, host):
fake_cgroup.membership("0::/\n")
host["available"] = 5 * GIB
_v2(fake_cgroup.root, "/", limit = 32 * GIB, current = 30 * GIB)
_stat(fake_cgroup.root, inactive_file = 1 * GIB, active_file = 14 * GIB)
assert host_memory.cgroup_headroom_mib() == 17 * 1024
assert host_memory.usable_host_ram_mib() == 5 * 1024
@reader
def test_v2_ancestor_level_uses_its_own_file_cache(fake_cgroup, host):
fake_cgroup.membership("0::/kaggle.slice/run.scope\n")
leaf = _v2(fake_cgroup.root, "kaggle.slice/run.scope", limit = "max", current = 10 * GIB)
parent = _v2(fake_cgroup.root, "kaggle.slice", limit = 20 * GIB, current = 19 * GIB)
_stat(leaf, inactive_file = 0, active_file = 9 * GIB)
_stat(parent, inactive_file = 1 * GIB, active_file = 10 * GIB)
assert host_memory.cgroup_headroom_mib() == 12 * 1024
@reader
def test_v1_hierarchical_active_file_is_reclaimable_and_shmem_is_not(fake_cgroup, host):
fake_cgroup.membership("12:memory:/docker/abc\n")
d = fake_cgroup.root / "memory" / "docker" / "abc"
_write(d / "memory.limit_in_bytes", str(16 * GIB))
_write(d / "memory.usage_in_bytes", str(14 * GIB))
_stat(
d,
inactive_file = 50 * GIB,
active_file = 50 * GIB,
total_cache = 9 * GIB,
total_shmem = 2 * GIB,
total_inactive_file = 1 * GIB,
total_active_file = 6 * GIB,
total_mapped_file = 1 * GIB,
total_dirty = 0,
total_writeback = 0,
)
# 16 - (14 - 1 - (6 - 1)) = 8 GiB; total_cache (incl. 2 GiB shmem) would claim 11 GiB.
assert host_memory.cgroup_headroom_mib() == 8 * 1024
@reader
def test_v1_without_total_counters_uses_the_level_ones(fake_cgroup, host):
fake_cgroup.membership("12:memory:/docker/abc\n")
d = fake_cgroup.root / "memory" / "docker" / "abc"
_write(d / "memory.limit_in_bytes", str(16 * GIB))
_write(d / "memory.usage_in_bytes", str(14 * GIB))
_stat(d, cache = 8 * GIB, inactive_file = 1 * GIB, active_file = 6 * GIB, mapped_file = 2 * GIB)
assert host_memory.cgroup_headroom_mib() == 7 * 1024
@reader
def test_v1_memsw_headroom_credits_active_file_cache(fake_cgroup, host):
fake_cgroup.membership("12:memory:/docker/abc\n")
d = fake_cgroup.root / "memory" / "docker" / "abc"
_write(d / "memory.limit_in_bytes", str(16 * GIB))
_write(d / "memory.usage_in_bytes", str(14 * GIB))
_write(d / "memory.memsw.limit_in_bytes", str(24 * GIB))
_write(d / "memory.memsw.usage_in_bytes", str(15 * GIB))
_stat(d, total_inactive_file = 1 * GIB, total_active_file = 6 * GIB)
assert host_memory.cgroup_v1_memsw_headroom_bytes() == (24 - (15 - 7)) * GIB
# RAM room 16 - (14 - 7) = 9, combined room 16: 7 GiB of swap left.
assert host_memory.cgroup_swap_allowance_bytes(100 * GIB) == 7 * GIB