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
Studio: size host RAM from the container's cgroup, and re-measure the MiniMax-H3 floor (#12854)
Daniel Han1fea7ed0eed2
diff --git a/studio/backend/core/inference/diffusion_memory.py b/studio/backend/core/inference/diffusion_memory.pyindex 03cc1b63853..31609f815e0 100644--- a/studio/backend/core/inference/diffusion_memory.py+++ b/studio/backend/core/inference/diffusion_memory.py@@ -299,19 +299,12 @@ def _pin_host_weights(left -= sizeneed = sum(chunks)if mode == "auto":- try:- import psutil- vm = psutil.virtual_memory()- except Exception: # noqa: BLE001 - no way to size it, so do not lock memory- return 0- # psutil reads the host; pinned pages are charged to an enforcing cgroup, so size from the container.- available, total = vm.available, vm.total- remainder = _cgroup_available_memory_mib()- if remainder is not None:- available = min(available, int(remainder) << 20)- limit = _cgroup_memory_limit_mib()- if limit is not None:- total = min(total, int(limit) << 20)+ # Pinned pages are charged to an enforcing cgroup: size from the cgroup-capped readings.+ available_mib = _available_system_memory_mib()+ total_mib = _host_ram_capacity_mib()+ if available_mib is None or total_mib is None:+ return 0 # no way to size it, so do not lock memory+ available, total = int(available_mib) << 20, int(total_mib) << 20reserve = max(_PIN_RESERVE_MIN_BYTES, int(total * _PIN_RESERVE_FRACTION))if available - need < reserve:if logger is not None:@@ -891,30 +884,45 @@ def _unified_reclaimable_memory_mib(free_mib: int, total_mib: int) -> tuple[int,def _available_system_memory_mib() -> Optional[int]:- """Available host RAM in MiB, capped by any enforcing cgroup limit."""+ """Usable host RAM in MiB: system available capped by any enforcing cgroup's headroom."""+ from utils import host_memorytry:from core.inference.llama_cpp import LlamaCppBackendreturn LlamaCppBackend._available_system_memory_mib()- except Exception: # noqa: BLE001 - the host reading still stands- return _system_memory_mib()[1]+ except Exception: # noqa: BLE001 - the shared reader still applies the cgroup cap+ return host_memory.usable_mib(_system_memory_mib()[1], _cgroup_available_memory_mib())def _cgroup_available_memory_mib() -> Optional[int]:"""What an enforcing cgroup will still let this process charge, else None."""+ from utils import host_memorytry:from core.inference.llama_cpp import LlamaCppBackendreturn LlamaCppBackend._cgroup_available_memory_mib()- except Exception: # noqa: BLE001 - no readable limit is the same answer as none- return None+ except Exception: # noqa: BLE001 - read the cgroup directly rather than drop the cap+ try:+ return host_memory.cgroup_headroom_mib()+ except Exception: # noqa: BLE001 - no readable limit is the same answer as none+ return Nonedef _cgroup_memory_limit_mib() -> Optional[int]:"""The capacity an enforcing cgroup allows, else None. Not the remainder above."""+ from utils import host_memorytry:from core.inference.llama_cpp import LlamaCppBackendreturn LlamaCppBackend._cgroup_memory_limit_mib()- except Exception: # noqa: BLE001 - no readable limit is the same answer as none- return None+ except Exception: # noqa: BLE001 - read the cgroup directly rather than drop the cap+ try:+ return host_memory.cgroup_limit_mib()+ except Exception: # noqa: BLE001 - no readable limit is the same answer as none+ return None+++def _host_ram_capacity_mib() -> Optional[int]:+ """Host RAM this process may ever charge, in MiB: system total capped by any cgroup limit."""+ from utils import host_memory+ return host_memory.usable_mib(_system_memory_mib()[0], _cgroup_memory_limit_mib())def _xpu_memory() -> tuple[Optional[int], Optional[int]]:@@ -3244,15 +3252,11 @@ def _storage_nbytes(tensor: Any, depth: int = 0) -> list[int]:def _pin_budget_mib() -> Optional[int]:- """Pinnable host MiB leaving ``max(4 GiB, 15%)`` free, or None if unreadable."""- total, _available = _system_memory_mib()+ """Pinnable host MiB leaving ``max(4 GiB, 15%)`` of the cgroup-capped total free, or None if unreadable."""+ total = _host_ram_capacity_mib()available = _available_system_memory_mib()if total is None or available is None:return None- # Same container sizing as _pin_host_weights: pinned pages are charged to an enforcing cgroup.- limit = _cgroup_memory_limit_mib()- if limit is not None:- total = min(int(total), int(limit))reserve = max(_PIN_RESERVE_MIN_MIB, int(int(total) * _PIN_RESERVE_FRACTION))return max(0, int(available) - reserve)diff --git a/studio/backend/core/inference/diffusion_small_host.py b/studio/backend/core/inference/diffusion_small_host.pyindex ac7f207dd8f..209b01d6e91 100644--- a/studio/backend/core/inference/diffusion_small_host.py+++ b/studio/backend/core/inference/diffusion_small_host.py@@ -149,18 +149,8 @@ def resolve_snapshot_dir(repo_or_dir: Any, cache_dir: Any = None) -> Optional[Padef host_ram_mib() -> tuple[Optional[int], Optional[int]]:"""(total, available) host MiB, both capped by an enforcing cgroup."""- from .diffusion_memory import (- _available_system_memory_mib,- _cgroup_memory_limit_mib,- _system_memory_mib,- )-- total, _ = _system_memory_mib()- available = _available_system_memory_mib()- limit = _cgroup_memory_limit_mib()- if total is not None and limit is not None:- total = min(int(total), int(limit))- return total, available+ from .diffusion_memory import _available_system_memory_mib, _host_ram_capacity_mib+ return _host_ram_capacity_mib(), _available_system_memory_mib()def host_reserve_mib(total_mib: Optional[int]) -> int:diff --git a/studio/backend/core/inference/llama_cpp.py b/studio/backend/core/inference/llama_cpp.pyindex 3abf5518dc5..53dabe57bbc 100644--- a/studio/backend/core/inference/llama_cpp.py+++ b/studio/backend/core/inference/llama_cpp.py@@ -24,6 +24,7 @@ import reimport structfrom loggers import get_loggerfrom utils.gpu_memory_events import invalidate_gpu_memory as _invalidate_gpu_memory+from utils import host_memory as _host_memoryfrom utils.gpu_memory_events import invalidates_gpu_memory as _invalidates_gpu_memoryimport shutilimport signal@@ -14322,123 +14323,14 @@ class LlamaCppBackend:def _cgroup_memory_budgets() -> list[tuple[int, int]]:"""Memory this process can still charge to an enforcing cgroup.- ``psutil`` and ``/proc/meminfo`` expose host-wide availability in many- containers. Walk the process's cgroup plus its ancestors and pair each- limit with that same directory's usage; an ancestor slice can be the- binding limit and includes sibling usage that a leaf does not see.- Supports cgroup v2 and the legacy v1 memory controller. ``None`` means- no finite readable limit, so callers retain their host reading.+ Delegates to ``utils.host_memory``; empty = no finite limit."""-- def _first_line(path: str) -> Optional[str]:- try:- with open(path, "r", encoding = "utf-8") as f:- return f.readline().strip()- except OSError:- return None-- def _integer(raw: Optional[str], *, limit: bool = False) -> Optional[int]:- if not raw or raw == "max":- return None- try:- value = int(raw)- except ValueError:- return None- # cgroup v1 spells unlimited as a near-2^63 sentinel.- if value < 0 or (limit and value >= 1 << 60):- return None- return value-- def _stat_integer(path: str, *keys: str) -> int:- """Read the first requested byte counter present in memory.stat."""- try:- with open(path, "r", encoding = "utf-8") as f:- values = {}- for line in f:- parts = line.split()- if len(parts) == 2 and parts[0] in keys:- value = _integer(parts[1])- if value is not None:- values[parts[0]] = value- except OSError:- return 0- return next((values[key] for key in keys if key in values), 0)-- def _directories(root: str, relative: Optional[str]) -> list[str]:- root = os.path.abspath(root)- current = os.path.normpath(os.path.join(root, (relative or "/").lstrip("/")))- try:- if os.path.commonpath((root, current)) != root:- return [root]- except ValueError:- return [root]- out = []- while True:- out.append(current)- if current == root:- return out- current = os.path.dirname(current)-- try:- with open(_PROC_SELF_CGROUP, "r", encoding = "utf-8") as f:- lines = [line.strip() for line in f if line.strip()]- except OSError:- lines = []-- budgets: list[tuple[int, int]] = []- v2_relative = next((line[3:] for line in lines if line.startswith("0::")), None)- for directory in _directories(_CGROUP_ROOT, v2_relative):- limit = _integer(_first_line(os.path.join(directory, "memory.max")), limit = True)- if limit is None:- continue- used = _integer(_first_line(os.path.join(directory, "memory.current")))- if used is not None:- # memory.current includes file-backed cache. Inactive file pages- # are reclaimable under pressure, so price the launch against the- # cgroup working set rather than charging cached GGUF pages twice.- used = max(- 0, used - _stat_integer(os.path.join(directory, "memory.stat"), "inactive_file")- )- budgets.append((limit if used is None else limit - used, limit))-- v1_root = os.path.join(_CGROUP_ROOT, "memory")- v1_relative = None- for line in lines:- parts = line.split(":", 2)- if len(parts) == 3 and "memory" in parts[1].split(","):- v1_relative = parts[2]- break- for directory in _directories(v1_root, v1_relative):- limit = _integer(- _first_line(os.path.join(directory, "memory.limit_in_bytes")), limit = True- )- if limit is None:- continue- used = _integer(_first_line(os.path.join(directory, "memory.usage_in_bytes")))- if used is not None:- # v1 usage is hierarchical when use_hierarchy is enabled, so its- # matching counter is total_inactive_file. Fall back to the local- # counter for non-hierarchical controllers.- used = max(- 0,- used- - _stat_integer(- os.path.join(directory, "memory.stat"),- "total_inactive_file",- "inactive_file",- ),- )- budgets.append((limit if used is None else limit - used, limit))-- return budgets+ return _host_memory.cgroup_memory_budgets(_CGROUP_ROOT, _PROC_SELF_CGROUP)@staticmethoddef _cgroup_available_memory_mib() -> Optional[int]:"""What this process can still charge, i.e. the tightest REMAINDER."""- budgets = LlamaCppBackend._cgroup_memory_budgets()- if not budgets:- return None- return max(min(remaining for remaining, _limit in budgets), 0) // (1024 * 1024)+ return _host_memory.cgroup_headroom_mib(LlamaCppBackend._cgroup_memory_budgets())@staticmethoddef _cgroup_memory_limit_mib() -> Optional[int]:@@ -14446,10 +14338,7 @@ class LlamaCppBackend:Not interchangeable with the remainder above, which shrinks as the containerfills and would price against memory that is merely busy rather than absent."""- budgets = LlamaCppBackend._cgroup_memory_budgets()- if not budgets:- return None- return min(limit for _remaining, limit in budgets) // (1024 * 1024)+ return _host_memory.cgroup_limit_mib(LlamaCppBackend._cgroup_memory_budgets())@staticmethoddef _available_system_memory_mib() -> Optional[int]:@@ -14457,25 +14346,9 @@ class LlamaCppBackend:neither is readable, capped by this process's cgroup remainder. On aunified-memory APU this, not the ROCm-reported VRAM, is the real ceiling:the weights load into shared system RAM."""- available = None- try:- import psutil- available = int(psutil.virtual_memory().available // (1024 * 1024))- except Exception:- pass- if available is None:- try:- with open("/proc/meminfo", encoding = "utf-8") as f:- for line in f:- if line.startswith("MemAvailable:"):- available = int(line.split()[1]) // 1024 # kB -> MiB- break- except Exception:- pass- cgroup_available = LlamaCppBackend._cgroup_available_memory_mib()- if available is None:- return cgroup_available- return min(available, cgroup_available) if cgroup_available is not None else available+ return _host_memory.usable_mib(+ _host_memory.system_available_mib(), LlamaCppBackend._cgroup_available_memory_mib()+ )@staticmethoddef _total_system_memory_mib() -> Optional[int]:@@ -14483,19 +14356,7 @@ class LlamaCppBackend:readable. The ceiling on what ``MemAvailable`` can ever become, so a preflight thatruns before the resident model and pipeline are torn down can price against itwithout charging for host memory that is about to come back."""- try:- import psutil- return int(psutil.virtual_memory().total // (1024 * 1024))- except Exception:- pass- try:- with open("/proc/meminfo", encoding = "utf-8") as f:- for line in f:- if line.startswith("MemTotal:"):- return int(line.split()[1]) // 1024 # kB -> MiB- except Exception:- pass- return None+ return _host_memory.system_total_mib()@staticmethoddef _host_memory_capacity_mib() -> Optional[int]:@@ -14505,11 +14366,9 @@ class LlamaCppBackend:/proc/meminfo does not show. The LIMIT, never the remainder, which shrinks asthe container fills and would price against memory that is merely busy."""- total = LlamaCppBackend._total_system_memory_mib()- limit = LlamaCppBackend._cgroup_memory_limit_mib()- if total is None:- return limit- return min(total, limit) if limit is not None else total+ return _host_memory.usable_mib(+ LlamaCppBackend._total_system_memory_mib(), LlamaCppBackend._cgroup_memory_limit_mib()+ )_ARGV_MODEL = frozenset({"-m", "--model"})_ARGV_RPC = frozenset({"--rpc"})diff --git a/studio/backend/core/inference/video.py b/studio/backend/core/inference/video.pyindex ef72e9d6d97..dc2f98b9286 100644--- a/studio/backend/core/inference/video.py+++ b/studio/backend/core/inference/video.py@@ -1336,20 +1336,13 @@ def _h3_card_free_bytes(device: Optional[str], ordinal: Optional[int]) -> Optiondef _h3_native_server_pressure(device: Optional[str], ordinal: Optional[int]) -> Optional[str]:"""Why the resident H3 sd-server should not outlive a render (``h3_native_server_pressure``), or None."""- from .diffusion_memory import (- _available_system_memory_mib,- _cgroup_memory_limit_mib,- _system_memory_mib,- )+ from .diffusion_memory import _available_system_memory_mib, _host_ram_capacity_mibfrom .video_minimax_h3 import h3_native_server_pressurevram_free, vram_total = _h3_card_memory_bytes(device, ordinal)try:- host_total_mib = _system_memory_mib()[0]# Available RAM is cgroup-capped, so the reserve must be a share of the same limit.- cgroup_limit_mib = _cgroup_memory_limit_mib()- if cgroup_limit_mib and (host_total_mib is None or cgroup_limit_mib < host_total_mib):- host_total_mib = cgroup_limit_mib+ host_total_mib = _host_ram_capacity_mib()host_avail_mib = _available_system_memory_mib()except Exception: # noqa: BLE001 -- unknown host memory decides nothinghost_total_mib = host_avail_mib = Nonediff --git a/studio/backend/core/inference/video_minimax_h3.py b/studio/backend/core/inference/video_minimax_h3.pyindex 8e3657471bc..15b94a0490c 100644--- a/studio/backend/core/inference/video_minimax_h3.py+++ b/studio/backend/core/inference/video_minimax_h3.py@@ -188,14 +188,28 @@ def h3_process_held_host_bytes() -> int:def h3_host_capacity_bytes() -> int:- """What the system can still hand out plus what this process already holds and the render reuses."""+ """Usable host RAM (cgroup-capped) plus what this process already holds and the render reuses,+ capped at the cgroup limit."""import psutil- return int(psutil.virtual_memory().available) + h3_process_held_host_bytes()+ from utils import host_memory+ available = int(psutil.virtual_memory().available)+ budgets = host_memory.cgroup_memory_budgets()+ headroom_mib = host_memory.cgroup_headroom_mib(budgets)+ if headroom_mib is not None:+ available = min(available, int(headroom_mib) << 20)+ capacity = available + h3_process_held_host_bytes()+ limit_mib = host_memory.cgroup_limit_mib(budgets)+ if limit_mib is not None:+ capacity = min(capacity, int(limit_mib) << 20)+ return capacity-# Host floor while the int8 conditioner streams too: measured ~66 GB process peak on a Colab G4 (12 / 16 / 24 GB-# budgets), above the 64.5 GB component sum; 70 keeps ~4 GB of margin.-H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB = 70.0++# Streamed int8 conditioner + int8 / fp8 denoiser floor, measured as non-reclaimable memory (not RSS, which counts+# mmap'd checkpoint pages the kernel reclaims under a limit): highest MemoryMax kill on main, 34 GiB, plus ~10% margin.+H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB = 40.0+# RSS-based floor for streamed sets larger than the measured one (not re-measured).+H3_DIFFUSERS_HOST_RAM_STREAMED_RSS_GB = 70.0def estimate_h3_diffusers_host_ram_gb(@@ -227,14 +241,30 @@ def estimate_h3_diffusers_host_ram_gb(return H3_DIFFUSERS_HOST_RAM_HIGH_VRAM_GBtext_encoder = H3_TEXT_ENCODER_BF16_GB if text_encoder_gb is None else float(text_encoder_gb)transformer = H3_TRANSFORMER_BF16_GB if transformer_gb is None else float(transformer_gb)+ if (+ text_encoder_streamed+ and not transformer_streamed+ and _within_measured_streamed_set(text_encoder, transformer)+ ):+ # Both stream from reclaimable page cache, so the component sum overstates the floor.+ return H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GBif transformer_streamed:transformer *= 2total = text_encoder + transformer + H3_VAE_RESIDENT_GB + H3_DIFFUSERS_HOST_RAM_HEADROOM_GBif text_encoder_streamed:- total = max(total, H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB)+ total = max(total, H3_DIFFUSERS_HOST_RAM_STREAMED_RSS_GB)return total+def _within_measured_streamed_set(text_encoder_gb: float, transformer_gb: float) -> bool:+ """Whether a streamed load is no larger than the set ``H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB`` was measured on."""+ from .video_minimax_h3_te import H3_TE_QUANT_RESIDENT_GB+ return (+ text_encoder_gb <= H3_TE_QUANT_RESIDENT_GB["int8"] + 1e-6+ and transformer_gb <= max(H3_TRANSFORMER_PREQUANT_GB.values()) + 1e-6+ )++def h3_host_ram_shortfall(available_vram_gb: float,*,@@ -266,7 +296,8 @@ def h3_host_ram_shortfall(# Picker units: total VRAM GiB, available RAM GiB. Each follows the kill switch of the behaviour it relies on:# - VRAM (UNSLOTH_H3_TE_STREAM): the generate guard's floor for the page's default request, so the selected row# renders it; 960x544 still renders on 12 GB when chosen. Without it, the catalog's 30.-# - RAM (UNSLOTH_DIFFUSION_PIN_ARENA): the single-copy host floor (64.5 GB, or 70 GB with the conditioner streamed).+# - RAM (UNSLOTH_DIFFUSION_PIN_ARENA): the single-copy host floor (64.5 GB, or the measured+# H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB with the conditioner streamed).# Without it, the catalog's 80.H3_DIFFUSERS_FIT_TIERS_ENV = "UNSLOTH_H3_DIFFUSERS_WIDE_TIERS"H3_DIFFUSERS_CATALOG_TIER_GPU_GIB = 30.0diff --git a/studio/backend/main.py b/studio/backend/main.pyindex 203b95df2d0..6fbdde90400 100644--- a/studio/backend/main.py+++ b/studio/backend/main.py@@ -2585,6 +2585,29 @@ def get_system_info()memory = psutil.virtual_memory()+ memory_total = memory.total+ memory_available = memory.available+ memory_percent = memory.percent+ # The picker's RAM tiers compare against available_gb: publish the cgroup-capped view.+ try:+ from utils import host_memory++ _budgets = host_memory.cgroup_memory_budgets()+ _headroom_mib = host_memory.cgroup_headroom_mib(_budgets)+ _limit_mib = host_memory.cgroup_limit_mib(_budgets)+ if _limit_mib is not None:+ memory_total = min(memory_total, _limit_mib * 1024**2)+ if _headroom_mib is not None:+ memory_available = min(memory_available, _headroom_mib * 1024**2)+ if _limit_mib is not None or _headroom_mib is not None:+ memory_available = min(memory_available, memory_total)+ memory_percent = (+ round((memory_total - memory_available) / memory_total * 100, 1)+ if memory_total+ else memory_percent+ )+ except Exception as e:+ logger.debug(f"Failed to read the cgroup memory limit: {e}")# Corrects psutil's 1000x-too-small Apple Silicon M4+ reading (issue #8519).cpu_freq_mhz = cpu_frequency_mhz()@@ -2638,9 +2661,9 @@ def get_system_info("frequency_mhz": cpu_freq_mhz,},"memory": {- "total_gb": round(memory.total / 1024**3, 2),- "available_gb": round(memory.available / 1024**3, 2),- "percent_used": memory.percent,+ "total_gb": round(memory_total / 1024**3, 2),+ "available_gb": round(memory_available / 1024**3, 2),+ "percent_used": memory_percent,"process_used_mb": process_used_mb,},"disk": {diff --git a/studio/backend/tests/test_diffusion_offload_keep_cpu.py b/studio/backend/tests/test_diffusion_offload_keep_cpu.pyindex 5573708eefe..5555cc01bb3 100644--- a/studio/backend/tests/test_diffusion_offload_keep_cpu.py+++ b/studio/backend/tests/test_diffusion_offload_keep_cpu.py@@ -332,23 +332,17 @@ def _host_of(module):@cudadef test_the_ram_gate_counts_the_chunks_really_allocated(monkeypatch):- psutil = pytest.importorskip("psutil")# Weight 256 B and bias 32 B (256 aligned) do not share a 384 B chunk: 384 + 256 B are allocated for 512.monkeypatch.setattr(dm, "_PIN_CHUNK_BYTES", 384)- reserve = 4 << 30+ # The gate reads MiB (system available capped by the cgroup headroom), so pin the readings and move the+ # reserve by bytes instead: 600 B of room is short of the 640 B allocated, 640 B is enough.+ monkeypatch.setattr(dm, "_available_system_memory_mib", lambda: 5 << 10)+ monkeypatch.setattr(dm, "_host_ram_capacity_mib", lambda: 16 << 10)lin = torch.nn.Linear(8, 8)- monkeypatch.setattr(- psutil,- "virtual_memory",- lambda: types.SimpleNamespace(total = 16 << 30, available = reserve + 600),- )+ monkeypatch.setattr(dm, "_PIN_RESERVE_MIN_BYTES", (5 << 30) - 600)assert dm._pin_host_weights(lin, _host_of(lin)) == 0assert not lin.weight.is_pinned()- monkeypatch.setattr(- psutil,- "virtual_memory",- lambda: types.SimpleNamespace(total = 16 << 30, available = reserve + 640),- )+ monkeypatch.setattr(dm, "_PIN_RESERVE_MIN_BYTES", (5 << 30) - 640)assert dm._pin_host_weights(lin, _host_of(lin)) == 640assert lin.weight.is_pinned() and lin.bias.is_pinned()diff --git a/studio/backend/tests/test_h3_host_ram_guard.py b/studio/backend/tests/test_h3_host_ram_guard.pyindex ea0bb0590c5..8b3fa3612ed 100644--- a/studio/backend/tests/test_h3_host_ram_guard.py+++ b/studio/backend/tests/test_h3_host_ram_guard.py@@ -155,6 +155,10 @@ def _host(file_gb = 0.0,):gb = 1_000_000_000+ # A host with no enforcing cgroup: the CI runner's own limit must not leak into these numbers.+ from utils import host_memory++ monkeypatch.setattr(host_memory, "cgroup_memory_budgets", lambda *a, **k: [])monkeypatch.setattr(vmh3,"_proc_status_kb",diff --git a/studio/backend/tests/test_h3_vs_comfy_default_route.py b/studio/backend/tests/test_h3_vs_comfy_default_route.pyindex 0c732a82bb6..e47b41e35c7 100644--- a/studio/backend/tests/test_h3_vs_comfy_default_route.py+++ b/studio/backend/tests/test_h3_vs_comfy_default_route.py@@ -111,13 +111,35 @@ def test_the_estimators_size_864x480_below_960x544(families):)+def _streamed_set_tier_gib() -> float:+ import math+ import sys+ from pathlib import Path++ backend = str(Path(__file__).resolve().parents[1])+ if backend not in sys.path:+ sys.path.insert(0, backend)+ from core.inference.video_minimax_h3 import H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB++ return float(math.ceil(H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB * 1e9 / 2**30))+++_STREAMED_SET_TIER_GIB = _streamed_set_tier_gib()++@pytest.mark.parametrize("te_stream, arena, expected",[(None,None,- [{"gpu_gb": 14.0, "system_ram_gb": 66.0, "requires_quantised_streaming": True}],+ [+ {+ "gpu_gb": 14.0,+ "system_ram_gb": _STREAMED_SET_TIER_GIB,+ "requires_quantised_streaming": True,+ }+ ],),("0",@@ -159,9 +181,9 @@ def test_the_ram_tier_is_the_single_count_host_floor_in_gib():assert 60.0 < floor_gb * 1e9 / 2**30 <= 61.0-def test_a_streamed_conditioner_raises_the_host_floor_to_the_measured_peak():- # Colab G4 at 24 / 16 / 12 GB budgets: ~66 GB process peak with the conditioner streamed, above the 64.5 GB sum.+def test_a_streamed_int8_set_is_priced_at_the_measured_floor_not_the_component_sum():from core.inference.video_minimax_h3 import (+ H3_DIFFUSERS_HOST_RAM_STREAMED_RSS_GB,H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB,estimate_h3_diffusers_host_ram_gb,)@@ -171,8 +193,13 @@ def test_a_streamed_conditioner_raises_the_host_floor_to_the_measured_peak():30.0, text_encoder_gb = 27.2, transformer_gb = 20.3, text_encoder_streamed = True)assert summed == pytest.approx(64.5)- assert streamed == H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB >= 66.0 + 3.0- # A double-counted denoiser is still larger than the streamed-set floor and wins.+ assert streamed == H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GB < summed+ # A 58 GiB cgroup (62.3 GB) holds the measured set: main renders it there.+ assert streamed < 58 * 2**30 / 1e9+ assert estimate_h3_diffusers_host_ram_gb(+ 30.0, text_encoder_gb = 66.7, transformer_gb = 20.3, text_encoder_streamed = True+ ) == pytest.approx(66.7 + 20.3 + 11.1 + 5.9)+ assert H3_DIFFUSERS_HOST_RAM_STREAMED_RSS_GB == 70.0assert estimate_h3_diffusers_host_ram_gb(30.0,text_encoder_gb = 27.2,@@ -185,11 +212,13 @@ def test_a_streamed_conditioner_raises_the_host_floor_to_the_measured_peak():def test_the_guard_prices_a_streamed_conditioner_at_the_streamed_set_floor(monkeypatch):import core.inference.video_minimax_h3 as h3- monkeypatch.setattr(h3, "h3_host_capacity_bytes", lambda: int(67e9))+ floor = h3.H3_DIFFUSERS_HOST_RAM_STREAMED_SET_GBkw = dict(text_encoder_gb = 27.2, transformer_gb = 20.3)- assert h3.h3_host_ram_shortfall(30.0, **kw) is None+ monkeypatch.setattr(h3, "h3_host_capacity_bytes", lambda: int((floor + 0.6) * 1e9))+ assert h3.h3_host_ram_shortfall(30.0, text_encoder_streamed = True, **kw) is None+ monkeypatch.setattr(h3, "h3_host_capacity_bytes", lambda: int((floor - 1.0) * 1e9))message = h3.h3_host_ram_shortfall(30.0, text_encoder_streamed = True, **kw)- assert message is not None and "70 GB" in message+ assert message is not None and f"{floor:.0f} GB" in messagedef test_the_vram_tier_admits_only_cards_that_render_the_default_request(monkeypatch):diff --git a/studio/backend/tests/test_host_memory_cgroup.py b/studio/backend/tests/test_host_memory_cgroup.pynew file mode 100644index 00000000000..98b2de79ccb--- /dev/null+++ b/studio/backend/tests/test_host_memory_cgroup.py@@ -0,0 +1,378 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""One cgroup-aware "usable host RAM" reader for every place Studio sizes host memory.++Fake cgroup trees (v2, v1, nested, unlimited, malformed) drive ``utils.host_memory`` and the three+consumers that must agree on it: the diffusion pin budget, the MiniMax-H3 host-RAM guard and the+``/api/system`` memory figures the model picker's RAM tiers compare against.+"""++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+++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)+++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+ "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.0diff --git a/studio/backend/utils/host_memory.py b/studio/backend/utils/host_memory.pynew file mode 100644index 00000000000..d711c493ffc--- /dev/null+++ b/studio/backend/utils/host_memory.py@@ -0,0 +1,188 @@+# SPDX-License-Identifier: AGPL-3.0-only+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0++"""Host RAM this process can use: psutil / meminfo capped by the tightest enforcing cgroup level.++psutil reads the whole machine, so under a container or systemd MemoryMax it admits work the cgroup+OOM-kills. Torch-free: the polled /api/system route calls it."""++from __future__ import annotations++import os+from typing import Optional++CGROUP_ROOT = "/sys/fs/cgroup"+PROC_SELF_CGROUP = "/proc/self/cgroup"+_MIB = 1024 * 1024+# cgroup v1 spells "unlimited" as a near-2^63 sentinel.+_UNLIMITED_FLOOR = 1 << 60+++def _first_line(path: str) -> Optional[str]:+ try:+ with open(path, "r", encoding = "utf-8") as f:+ return f.readline().strip()+ except (OSError, UnicodeDecodeError):+ return None+++def _integer(raw: Optional[str], *, limit: bool = False) -> Optional[int]:+ if not raw or raw == "max":+ return None+ try:+ value = int(raw)+ except ValueError:+ return None+ if value < 0 or (limit and value >= _UNLIMITED_FLOOR):+ return None+ return value+++def _stat_integer(path: str, *keys: str) -> int:+ """The first requested byte counter present in a ``memory.stat`` file, else 0."""+ values: dict[str, int] = {}+ try:+ with open(path, "r", encoding = "utf-8") as f:+ for line in f:+ parts = line.split()+ if len(parts) == 2 and parts[0] in keys:+ value = _integer(parts[1])+ if value is not None:+ values[parts[0]] = value+ except (OSError, UnicodeDecodeError):+ return 0+ return next((values[key] for key in keys if key in values), 0)+++def _directories(root: str, relative: Optional[str]) -> list[str]:+ """The process's cgroup directory under ``root`` and every ancestor up to ``root``."""+ root = os.path.abspath(root)+ current = os.path.normpath(os.path.join(root, (relative or "/").lstrip("/")))+ try:+ if os.path.commonpath((root, current)) != root:+ return [root]+ except ValueError:+ return [root]+ out = []+ while True:+ out.append(current)+ if current == root:+ return out+ current = os.path.dirname(current)+++def cgroup_memory_budgets(+ cgroup_root: Optional[str] = None, proc_self_cgroup: Optional[str] = None+) -> list[tuple[int, int]]:+ """``(remaining, limit)`` bytes per enforcing limit on this cgroup and its ancestors (an ancestor+ can bind through sibling usage). Usage excludes ``inactive_file``; empty = no finite limit."""+ cgroup_root = CGROUP_ROOT if cgroup_root is None else cgroup_root+ proc_self_cgroup = PROC_SELF_CGROUP if proc_self_cgroup is None else proc_self_cgroup+ try:+ with open(proc_self_cgroup, "r", encoding = "utf-8") as f:+ lines = [line.strip() for line in f if line.strip()]+ except (OSError, UnicodeDecodeError):+ lines = []++ budgets: list[tuple[int, int]] = []+ v2_relative = next((line[3:] for line in lines if line.startswith("0::")), None)+ for directory in _directories(cgroup_root, v2_relative):+ limit = _integer(_first_line(os.path.join(directory, "memory.max")), limit = True)+ if limit is None:+ continue+ used = _integer(_first_line(os.path.join(directory, "memory.current")))+ if used is not None:+ used = max(+ 0, used - _stat_integer(os.path.join(directory, "memory.stat"), "inactive_file")+ )+ budgets.append((limit if used is None else limit - used, limit))++ v1_root = os.path.join(cgroup_root, "memory")+ v1_relative = None+ for line in lines:+ parts = line.split(":", 2)+ if len(parts) == 3 and "memory" in parts[1].split(","):+ v1_relative = parts[2]+ break+ for directory in _directories(v1_root, v1_relative):+ limit = _integer(_first_line(os.path.join(directory, "memory.limit_in_bytes")), limit = True)+ if limit is None:+ continue+ used = _integer(_first_line(os.path.join(directory, "memory.usage_in_bytes")))+ if used is not None:+ # Hierarchical v1 usage pairs with total_inactive_file.+ used = max(+ 0,+ used+ - _stat_integer(+ os.path.join(directory, "memory.stat"), "total_inactive_file", "inactive_file"+ ),+ )+ budgets.append((limit if used is None else limit - used, limit))+ return budgets+++def cgroup_headroom_mib(budgets: Optional[list[tuple[int, int]]] = None) -> Optional[int]:+ """What an enforcing cgroup still lets this process charge (the tightest remainder), else None."""+ budgets = cgroup_memory_budgets() if budgets is None else budgets+ if not budgets:+ return None+ return max(min(remaining for remaining, _limit in budgets), 0) // _MIB+++def cgroup_limit_mib(budgets: Optional[list[tuple[int, int]]] = None) -> Optional[int]:+ """The tightest enforcing cgroup limit (not the headroom, which shrinks as it fills), else None."""+ budgets = cgroup_memory_budgets() if budgets is None else budgets+ if not budgets:+ return None+ return min(limit for _remaining, limit in budgets) // _MIB+++def _meminfo_mib(key: str) -> Optional[int]:+ try:+ with open("/proc/meminfo", encoding = "utf-8") as f:+ for line in f:+ if line.startswith(key + ":"):+ return int(line.split()[1]) // 1024 # kB -> MiB+ except (OSError, ValueError, IndexError):+ pass+ return None+++def system_available_mib() -> Optional[int]:+ """Host-wide available RAM in MiB (psutil, then /proc/meminfo), NOT cgroup-capped, or None."""+ try:+ import psutil+ return int(psutil.virtual_memory().available // _MIB)+ except Exception: # noqa: BLE001 - fall back to the kernel file+ pass+ return _meminfo_mib("MemAvailable")+++def system_total_mib() -> Optional[int]:+ """Host-wide total RAM in MiB (psutil, then /proc/meminfo), NOT cgroup-capped, or None."""+ try:+ import psutil+ return int(psutil.virtual_memory().total // _MIB)+ except Exception: # noqa: BLE001 - fall back to the kernel file+ pass+ return _meminfo_mib("MemTotal")+++def usable_mib(available_mib: Optional[int], headroom_mib: Optional[int]) -> Optional[int]:+ """min() of the two readings; either may be None."""+ if available_mib is None:+ return headroom_mib+ if headroom_mib is None:+ return int(available_mib)+ return min(int(available_mib), int(headroom_mib))+++def usable_host_ram_mib() -> Optional[int]:+ """Host RAM this process can still allocate, in MiB: min(system available, cgroup headroom)."""+ return usable_mib(system_available_mib(), cgroup_headroom_mib())+++def host_ram_capacity_mib() -> Optional[int]:+ """Host RAM this process may ever charge, in MiB: min(system total, cgroup limit)."""+ return usable_mib(system_total_mib(), cgroup_limit_mib())