Skip to content

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.

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.py
index 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 -= size
need = 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) << 20
reserve = 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_memory
try:
from core.inference.llama_cpp import LlamaCppBackend
return 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_memory
try:
from core.inference.llama_cpp import LlamaCppBackend
return 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 None
def _cgroup_memory_limit_mib() -> Optional[int]:
"""The capacity an enforcing cgroup allows, else None. Not the remainder above."""
+ from utils import host_memory
try:
from core.inference.llama_cpp import LlamaCppBackend
return 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.py
index 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[Pa
def 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.py
index 3abf5518dc5..53dabe57bbc 100644
--- a/studio/backend/core/inference/llama_cpp.py
+++ b/studio/backend/core/inference/llama_cpp.py
@@ -24,6 +24,7 @@ import re
import struct
from loggers import get_logger
from utils.gpu_memory_events import invalidate_gpu_memory as _invalidate_gpu_memory
+from utils import host_memory as _host_memory
from utils.gpu_memory_events import invalidates_gpu_memory as _invalidates_gpu_memory
import shutil
import 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)
@staticmethod
def _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())
@staticmethod
def _cgroup_memory_limit_mib() -> Optional[int]:
@@ -14446,10 +14338,7 @@ class LlamaCppBackend:
Not interchangeable with the remainder above, which shrinks as the container
fills 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())
@staticmethod
def _available_system_memory_mib() -> Optional[int]:
@@ -14457,25 +14346,9 @@ class LlamaCppBackend:
neither is readable, capped by this process's cgroup remainder. On a
unified-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()
+ )
@staticmethod
def _total_system_memory_mib() -> Optional[int]:
@@ -14483,19 +14356,7 @@ class LlamaCppBackend:
readable. The ceiling on what ``MemAvailable`` can ever become, so a preflight that
runs before the resident model and pipeline are torn down can price against it
without 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()
@staticmethod
def _host_memory_capacity_mib() -> Optional[int]:
@@ -14505,11 +14366,9 @@ class LlamaCppBackend:
/proc/meminfo does not show. The LIMIT, never the remainder, which shrinks as
the 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.py
index 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]) -> Option
def _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_mib
from .video_minimax_h3 import h3_native_server_pressure
vram_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 nothing
host_total_mib = host_avail_mib = None
diff --git a/studio/backend/core/inference/video_minimax_h3.py b/studio/backend/core/inference/video_minimax_h3.py
index 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.0
def estimate_h3_diffusers_host_ram_gb(
@@ -227,14 +241,30 @@ def estimate_h3_diffusers_host_ram_gb(
return H3_DIFFUSERS_HOST_RAM_HIGH_VRAM_GB
text_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_GB
if transformer_streamed:
transformer *= 2
total = text_encoder + transformer + H3_VAE_RESIDENT_GB + H3_DIFFUSERS_HOST_RAM_HEADROOM_GB
if 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.0
diff --git a/studio/backend/main.py b/studio/backend/main.py
index 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.py
index 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):
@cuda
def 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)) == 0
assert 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)) == 640
assert 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.py
index 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.py
index 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.0
assert 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_GB
kw = 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 message
def 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.py
new file mode 100644
index 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.0
diff --git a/studio/backend/utils/host_memory.py b/studio/backend/utils/host_memory.py
new file mode 100644
index 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())