mcp-modelmanager 0.1.0__py3-none-any.whl

mcp_modelmanager/__init__.py

@@ -0,0 +1 @@
+"""MCP server to manage a local Ollama/vLLM model machine."""

mcp_modelmanager/connection.py

@@ -0,0 +1,501 @@
+"""The two channels to the model machine.
+
+Data channel (key A): an SSH tunnel that brings the VM's two service ports to
+the own machine. The key must get no shell on the VM and forward only these two
+targets.
+
+Control channel (key B): runs exactly one operation from the catalog. On the VM
+the key is bound firmly to the wrapper; here the same catalog is validated
+before sending.
+
+Both channels talk only to the local network, see
+validation.check_local_target.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import socket
+import subprocess
+import threading
+import time
+from dataclasses import dataclass
+
+from mcp_modelmanager import operations
+from mcp_modelmanager import protocol
+from mcp_modelmanager.validation import (
+    ValidationError,
+    check_local_target,
+    _configured_int,
+)
+
+# ---------------------------------------------------------------------------
+# Configuration, exclusively from environment variables
+# ---------------------------------------------------------------------------
+#
+# There are NO default values for the target machine here. Every user has their
+# own machine; a built-in default would be either wrong or would point at
+# someone else's machine. If a required field is missing, the server exits at
+# startup with a clear message instead of silently falling back on something.
+# How to set the fields is described in SETUP.md.
+
+
+def _required(name: str, hint: str) -> str:
+    value = os.environ.get(name, "").strip()
+    if not value:
+        raise SystemExit(
+            f"{name} is not set. {hint} "
+            f"Without this value the server does not start. See SETUP.md."
+        )
+    return value
+
+
+# Address of the own model machine. Three cases are foreseen and all valid, as
+# long as the address is on the own machine or the local network (see
+# check_local_target below):
+#   - the same machine as this server:   127.0.0.1
+#   - a machine on the same network:     the LAN IP (e.g. 192.168.1.10)
+#   - reached over a tunnel/VPN:         the address at the tunnel/VPN end
+VM_HOST = _required(
+    "MM_VM_HOST",
+    "Enter the address of your model machine (127.0.0.1 for the same machine, "
+    "otherwise your LAN or tunnel/VPN address).",
+)
+# SSH user on the model machine. Only the control channel (management: pulling
+# models, switching the service, training) needs it; plain queries run over HTTP
+# without SSH.
+VM_USER = _required(
+    "MM_VM_USER",
+    "Enter the SSH user name on your model machine.",
+)
+# Optional: a SECOND machine that may currently hold the shared GPU. Only there
+# to interpret an unreachability of the first machine ("GPU probably on the
+# second machine right now"). Whoever has only one machine leaves this empty;
+# the interpretation then drops entirely.
+VM2_HOST = os.environ.get("MM_VM2_HOST", "").strip()
+
+_KEY_DIR = os.environ.get(
+    "MM_KEY_DIR", os.path.expanduser("~/.ssh/modelmanager")
+)
+KEY_DATA = os.environ.get(
+    "MM_KEY_DATA", os.path.join(_KEY_DIR, "datachannel")
+)
+KEY_CONTROL = os.environ.get(
+    "MM_KEY_CONTROL", os.path.join(_KEY_DIR, "controlchannel")
+)
+# Pinned host key of the model machine. Written once by setup/install.sh (via
+# ssh-keyscan plus explicit operator confirmation of the fingerprint), never by
+# this program. Checking against a fixed file instead of the trust-on-first-use
+# default (accept-new) means a machine-in-the-middle at connect time is
+# rejected instead of silently pinned.
+KNOWN_HOSTS = os.environ.get(
+    "MM_KNOWN_HOSTS", os.path.join(_KEY_DIR, "known_hosts")
+)
+
+# Ports of the services on the VM (in future only on 127.0.0.1 there). Reuses
+# validation.py's _configured_int so a non-numeric value gets a clear
+# SystemExit naming the variable instead of a raw ValueError; the 1-65535
+# bound is the natural range of a port, not an added restriction.
+REMOTE_VLLM = _configured_int("MM_REMOTE_PORT_VLLM", 8000, 1, 65535)
+REMOTE_OLLAMA = _configured_int("MM_REMOTE_PORT_OLLAMA", 11434, 1, 65535)
+# Ports under which the tunnel exposes them here. Default to the same
+# well-known ports as the remote side; override if those are already taken
+# locally.
+LOCAL_VLLM = _configured_int("MM_LOCAL_PORT_VLLM", 8000, 1, 65535)
+LOCAL_OLLAMA = _configured_int("MM_LOCAL_PORT_OLLAMA", 11434, 1, 65535)
+
+# "tunnel" is the target state. "direct" is only the transition, while the
+# services still listen on the LAN.
+ACCESS = os.environ.get("MM_ACCESS", "tunnel").strip().lower()
+if ACCESS not in ("tunnel", "direct"):
+    raise SystemExit(f"MM_ACCESS must be 'tunnel' or 'direct', not '{ACCESS}'.")
+
+check_local_target(VM_HOST)
+# The second machine, if configured, is also addressed by this tool, so it must
+# clear the same local-network gate at start-up. An empty MM_VM2_HOST means no
+# second machine and is checked nowhere.
+if VM2_HOST:
+    check_local_target(VM2_HOST)
+
+# Forced key selection. "ssh -i" is only a SUGGESTION: without the following
+# bolts the client additionally offers all agent keys, all default files and
+# everything from ~/.ssh/config, and the far side takes the FIRST that matches.
+# If an unrestricted old key sits there too, the control channel slips past its
+# command= binding without anything noticing anywhere: the allowlist in the
+# wrapper is then never reached. Exactly that happened in a real setup run.
+#   IdentitiesOnly=yes  only the identity given here is offered
+#   IdentityAgent=none  the agent is not even asked
+#   -F /dev/null        ~/.ssh/config cannot contribute another key
+#   PreferredAuthentications=publickey  no fallback to other methods
+# Note: if the file behind -i is missing, ssh silently drops it and falls back
+# on the default files. So the existence is checked before every build
+# (control_channel_ready, Tunnel.ensure); without that check the forcing would
+# not be watertight.
+SSH_FORCE_KEY = [
+    "-F", "/dev/null",
+    "-o", "IdentitiesOnly=yes",
+    "-o", "IdentityAgent=none",
+    "-o", "PreferredAuthentications=publickey",
+]
+
+# Absolute path to the ssh program, resolved once from PATH at import. The
+# control and data channels are security boundaries; a bare "ssh" would let a
+# PATH manipulated at call time substitute a different binary for the one that
+# carries the bound keys. Pinning the resolved path here closes that. If ssh is
+# not on PATH at import, fall back to the usual location; a wrong path fails
+# loudly at connect time rather than running an unexpected program.
+SSH_BIN = shutil.which("ssh") or "/usr/bin/ssh"
+
+# StrictHostKeyChecking=yes against a fixed UserKnownHostsFile (set up once by
+# setup/install.sh, see KNOWN_HOSTS above) instead of accept-new: the host key
+# is pinned deliberately with operator confirmation, not trusted on first use.
+_SSH_BASE_OPTS = [
+    *SSH_FORCE_KEY,
+    "-o", "BatchMode=yes",
+    "-o", "StrictHostKeyChecking=yes",
+    "-o", f"UserKnownHostsFile={KNOWN_HOSTS}",
+    "-o", "ConnectTimeout=8",
+]
+
+
+class AccessMissing(RuntimeError):
+    """The key is not present or the VM does not accept it."""
+
+
+class MachineUnreachable(RuntimeError):
+    """The model machine does not answer. That is a state of its own, not an
+    error.
+
+    One possible reason: if a second, optional host shares the GPU with this
+    machine, that second host may currently hold the card while this one is
+    off. This interpretation only applies if a second machine has been made
+    known via MM_VM2_HOST.
+    """
+
+
+# ---------------------------------------------------------------------------
+# Reachability
+# ---------------------------------------------------------------------------
+
+
+def port_open(host: str, port: int, timeout: float = 2.0) -> bool:
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except OSError:
+        return False
+
+
+@dataclass
+class Reachability:
+    machine_reachable: bool
+    vm2_reachable: bool
+    state: str
+    explanation: str
+
+
+def reachability() -> Reachability:
+    # SSH port 22 is assumed hard: the tool exposes no port parameter and the
+    # channels force -F /dev/null, so a non-standard Port from ~/.ssh/config is
+    # ignored too. A model machine that only listens on a different SSH port
+    # would read here as unreachable. Standard-port setups are unaffected.
+    first_up = port_open(VM_HOST, 22)
+    if first_up:
+        return Reachability(
+            True, False, "machine_running",
+            "The model machine is reachable.",
+        )
+    if VM2_HOST:
+        vm2 = port_open(VM2_HOST, 22, 1.5)
+        if vm2:
+            return Reachability(
+                False, True, "gpu_probably_on_second_machine",
+                "The model machine does not answer, but the second machine does. "
+                "Very likely the second machine currently holds the GPU while "
+                "this one is off. That is not an error; switch back on the "
+                "GPU-holding machine.",
+            )
+        return Reachability(
+            False, False, "machine_unreachable",
+            "Neither the model machine nor the second machine answer. Possible: a "
+            "switchover is in progress, both machines are off, or a network "
+            "problem. Not a fault of this tool.",
+        )
+    return Reachability(
+        False, False, "machine_unreachable",
+        "The model machine does not answer. Possible: the machine is off, or a "
+        "network problem. Not a fault of this tool.",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Data channel: the tunnel
+# ---------------------------------------------------------------------------
+
+
+class Tunnel:
+    """Holds the SSH tunnel and rebuilds it on demand.
+
+    The build happens on demand, not in advance: before every service access it
+    is checked whether the local port answers, and otherwise reconnected. A tool
+    call should not fail just because the tunnel dropped in between.
+    """
+
+    def __init__(self) -> None:
+        self._process: subprocess.Popen[bytes] | None = None
+        self._lock = threading.Lock()
+        self.last_error: str | None = None
+        self.builds = 0
+
+    def _running(self) -> bool:
+        return self._process is not None and self._process.poll() is None
+
+    def _ready(self) -> bool:
+        # Both ports, not one: a half-standing tunnel is no tunnel.
+        return port_open("127.0.0.1", LOCAL_VLLM, 1.0) and port_open(
+            "127.0.0.1", LOCAL_OLLAMA, 1.0
+        )
+
+    def command(self) -> list[str]:
+        return [
+            SSH_BIN,
+            *_SSH_BASE_OPTS,
+            "-i", KEY_DATA,
+            "-N", "-T",
+            "-o", "ExitOnForwardFailure=yes",
+            "-o", "ServerAliveInterval=5",
+            "-o", "ServerAliveCountMax=2",
+            "-L", f"127.0.0.1:{LOCAL_VLLM}:127.0.0.1:{REMOTE_VLLM}",
+            "-L", f"127.0.0.1:{LOCAL_OLLAMA}:127.0.0.1:{REMOTE_OLLAMA}",
+            f"{VM_USER}@{VM_HOST}",
+        ]
+
+    def _tear_down_locked(self) -> None:
+        # Caller MUST already hold self._lock. Split out so ensure() can reuse it
+        # from inside the lock it already holds: self._lock is a plain (non
+        # reentrant) Lock, so calling tear_down() there would deadlock and the
+        # lock would stay held forever.
+        if self._process is not None:
+            self._process.terminate()
+            try:
+                self._process.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                self._process.kill()
+            self._process = None
+
+    def tear_down(self) -> None:
+        with self._lock:
+            self._tear_down_locked()
+
+    def ensure(self, wait_time: float = 12.0) -> None:
+        """Ensures the tunnel is up. Otherwise raises with a clear cause."""
+        if ACCESS == "direct":
+            return
+        # First the question whether the ports RESPOND, regardless of who holds
+        # the tunnel. If a system service holds it (see README, so a query
+        # bridge can share it), a second tunnel of our own on the same ports
+        # would not only be superfluous, it would fail on the occupied port and
+        # report an error where everything is fine.
+        # By design this only proves a port is open, not that it is OUR tunnel:
+        # an unrelated local service already listening on LOCAL_VLLM/LOCAL_OLLAMA
+        # would be taken as ready. Accepted as an edge case; the caller is
+        # expected to own these ports.
+        if self._ready():
+            return
+
+        with self._lock:
+            if self._ready():
+                return
+            if self._process is not None:  # dead or half-dead, get rid of it
+                try:
+                    self._process.kill()
+                except OSError:
+                    pass
+                self._process = None
+
+            if not os.path.exists(KEY_DATA):
+                raise AccessMissing(
+                    f"The data-channel key {KEY_DATA} is missing. Without it there "
+                    f"is no tunnel and hence no access to the services. Setup: see "
+                    f"README, section Isolation."
+                )
+            state = reachability()
+            if not state.machine_reachable:
+                raise MachineUnreachable(state.explanation)
+
+            # stdout/stderr are captured so a failed build can quote SSH's
+            # message (read below via .read() on the dead process). For a
+            # long-lived tunnel that stays up, nobody drains these pipes, so a
+            # very chatty ssh could in theory fill the pipe buffer and block. In
+            # practice a -N -T tunnel is silent once established; left as is
+            # rather than lose the error message on the failure path.
+            self._process = subprocess.Popen(
+                self.command(),
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            )
+            self.builds += 1
+
+            deadline = time.monotonic() + wait_time
+            while time.monotonic() < deadline:
+                if self._process.poll() is not None:
+                    error = (self._process.stderr.read() or b"").decode(
+                        "utf-8", "replace"
+                    ).strip()
+                    self.last_error = error
+                    self._process = None
+                    raise AccessMissing(
+                        "The tunnel could not be built. Message from SSH: "
+                        + (error or "none")
+                    )
+                if self._ready():
+                    self.last_error = None
+                    return
+                time.sleep(0.3)
+
+            self._tear_down_locked()
+            raise AccessMissing(
+                f"The tunnel was not up after {wait_time:.0f} seconds. "
+                f"Check: is key A registered on the VM and does it permitopen "
+                f"127.0.0.1:{REMOTE_VLLM} and 127.0.0.1:{REMOTE_OLLAMA}."
+            )
+
+    def base_vllm(self) -> str:
+        if ACCESS == "direct":
+            # Re-check at use time: the import-time check_local_target(VM_HOST)
+            # only saw one resolution. A hostname that resolved locally then
+            # could since have been rebound to an external address (DNS
+            # rebinding). Re-resolve and re-validate before egressing plain HTTP.
+            check_local_target(VM_HOST)
+            return f"http://{VM_HOST}:{REMOTE_VLLM}"
+        self.ensure()
+        return f"http://127.0.0.1:{LOCAL_VLLM}"
+
+    def base_ollama(self) -> str:
+        if ACCESS == "direct":
+            # Re-check at use time against DNS rebinding (see base_vllm).
+            check_local_target(VM_HOST)
+            return f"http://{VM_HOST}:{REMOTE_OLLAMA}"
+        self.ensure()
+        return f"http://127.0.0.1:{LOCAL_OLLAMA}"
+
+
+TUNNEL = Tunnel()
+
+
+# ---------------------------------------------------------------------------
+# Control channel
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Result:
+    operation: str
+    returncode: int
+    output: str
+    error: str
+
+    @property
+    def succeeded(self) -> bool:
+        return self.returncode == 0
+
+
+def control_channel_ready() -> tuple[bool, str]:
+    if not os.path.exists(KEY_CONTROL):
+        return False, (
+            f"The control-channel key {KEY_CONTROL} is missing. As long as it is "
+            f"not registered in the VM's authorized_keys, all tools that read VM "
+            f"state or steer services are non-functional."
+        )
+    return True, "Control-channel key present."
+
+
+def control_command(line: str) -> list[str]:
+    """The SSH call of the control channel. Factored out so the selftest can
+    check it for the forced key selection without a connection."""
+    # Defense in depth: VM_USER goes into the user@host argument unvalidated. A
+    # leading "-" could in principle be read by ssh as an option. Only the
+    # operator sets MM_VM_USER (a normal SSH login name), so this is not gated
+    # here; noted so a future change does not treat it as trusted input.
+    return [
+        SSH_BIN,
+        *_SSH_BASE_OPTS,
+        "-i", KEY_CONTROL,
+        "-o", "ClearAllForwardings=yes",
+        "-n",
+        f"{VM_USER}@{VM_HOST}",
+        line,
+    ]
+
+
+def call(operation_name: str, **parameters: object) -> Result:
+    """Runs exactly one catalog operation on the VM.
+
+    The parameters are validated HERE against the catalog already, even though
+    the wrapper on the VM does the same again. Two independent checks are by
+    design: the one here catches errors early and with a better message, the one
+    on the VM holds even if this machine were compromised.
+    """
+    operation = operations.get(operation_name)
+    operation.render(**parameters)  # pre-check, result deliberately discarded
+
+    ready, message = control_channel_ready()
+    if not ready:
+        raise AccessMissing(message)
+
+    line = protocol.build(operation_name, parameters)
+    command = control_command(line)
+    try:
+        run = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            timeout=operation.timeout + 20.0,
+        )
+    except subprocess.TimeoutExpired:
+        raise TimeoutError(
+            f"The operation '{operation_name}' exceeded the time limit of "
+            f"{operation.timeout:.0f} seconds."
+        ) from None
+
+    error_text = (run.stderr or "").strip()
+    if run.returncode == 255:
+        state = reachability()
+        if not state.machine_reachable:
+            raise MachineUnreachable(state.explanation)
+        raise AccessMissing(
+            "The VM did not accept the control-channel key. Message from SSH: "
+            + (error_text or "none") + ". Check: is the public part of key B "
+            "registered in /home/" + VM_USER + "/.ssh/authorized_keys, with "
+            "command= on /usr/local/sbin/modelmanager."
+        )
+    return Result(operation_name, run.returncode, run.stdout or "", error_text)
+
+
+def call_strict(operation_name: str, **parameters: object) -> str:
+    result = call(operation_name, **parameters)
+    if not result.succeeded:
+        raise RuntimeError(
+            f"Operation '{operation_name}' ended with return code "
+            f"{result.returncode}. Message: {result.error or result.output or 'none'}"
+        )
+    return result.output
+
+
+__all__ = [
+    "Result",
+    "Reachability",
+    "MachineUnreachable",
+    "ValidationError",
+    "SSH_FORCE_KEY",
+    "TUNNEL",
+    "AccessMissing",
+    "reachability",
+    "port_open",
+    "call",
+    "call_strict",
+    "control_command",
+    "control_channel_ready",
+]

mcp_modelmanager/estimation.py

@@ -0,0 +1,161 @@
+"""Memory estimate for a model switch.
+
+If the card has, say, 12 GB, only one large model fits. A switch that only
+surfaces on load costs several minutes and leaves the service broken. So it is
+computed beforehand.
+
+Computed, not guessed: weight size from the actual file sizes on the VM, the
+key-value cache from the model's config.json. Only if both are missing does it
+fall back to a rough estimate from the name, and the result then says
+explicitly that it is uncertain.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+GB = 2 ** 30
+
+# Fixed allowance for the CUDA context, intermediate results and the service
+# itself. Empirical value for vLLM on a single card.
+BASE_LOAD_GB = 1.0
+
+_DTYPE_BYTES = {
+    "float32": 4.0, "float16": 2.0, "bfloat16": 2.0,
+    "float8_e4m3fn": 1.0, "int8": 1.0, "int4": 0.5,
+}
+
+
+def parse_specs(text: str) -> dict[str, Any]:
+    """Reads the output of the 'hf_model_specs' operation."""
+    if "NOT_PRESENT" in text:
+        return {"present": False}
+    result: dict[str, Any] = {"present": True, "location": None,
+                              "weights_bytes": None, "config": None}
+    head, _, config_part = text.partition("===CONFIG")
+    for line in head.splitlines():
+        if line.startswith("LOCATION\t"):
+            result["location"] = line.split("\t", 1)[1].strip()
+        elif line.startswith("WEIGHTS\t"):
+            raw = line.split("\t", 1)[1].strip()
+            if raw.isdigit():
+                result["weights_bytes"] = int(raw)
+    if config_part.strip():
+        try:
+            result["config"] = json.loads(config_part.strip())
+        except ValueError:
+            result["config"] = None
+    return result
+
+
+def params_from_name(name: str) -> float | None:
+    """Rough parameter count in billions from the model name, e.g. '7B'.
+
+    For mixture-of-experts names such as 'mixtral-8x7b' this only picks up the
+    per-expert count ('7b'), not the far larger total parameter count. Treat
+    the result as a lower bound for such models.
+    """
+    match = re.search(r"(\d+(?:[.,]\d+)?)\s*[bB](?![a-zA-Z])", name)
+    if not match:
+        return None
+    try:
+        return float(match.group(1).replace(",", "."))
+    except ValueError:
+        return None
+
+
+def kv_per_token_bytes(config: dict[str, Any]) -> float | None:
+    """Bytes per token in the key-value cache, from config.json."""
+    try:
+        layers = int(config["num_hidden_layers"])
+    except (KeyError, TypeError, ValueError):
+        return None
+    head_dim = config.get("head_dim")
+    if not head_dim:
+        try:
+            head_dim = int(config["hidden_size"]) // int(config["num_attention_heads"])
+        except (KeyError, TypeError, ValueError, ZeroDivisionError):
+            return None
+    kv_heads = config.get("num_key_value_heads") or config.get("num_attention_heads")
+    try:
+        kv_heads = int(kv_heads)
+    except (TypeError, ValueError):
+        return None
+    dbytes = _DTYPE_BYTES.get(str(config.get("torch_dtype", "bfloat16")).lower(), 2.0)
+    # Key and value, per layer, per head, per dimension.
+    return 2.0 * layers * kv_heads * float(head_dim) * dbytes
+
+
+def estimate(specs: dict[str, Any], model_name: str, context: int,
+             fraction: float, gpu_total_gb: float) -> dict[str, Any]:
+    """Does the model with this context fit into the allotted memory."""
+    uncertain: list[str] = []
+
+    weights_gb: float | None = None
+    if specs.get("weights_bytes"):
+        weights_gb = specs["weights_bytes"] / GB
+    else:
+        billions = params_from_name(model_name)
+        if billions is not None:
+            weights_gb = billions * 2.0  # assume 16 bit
+            uncertain.append(
+                "The weight size was derived from the name and 16 bit was "
+                "assumed, because the files on the VM were not measurable."
+            )
+
+    kv_gb: float | None = None
+    config = specs.get("config")
+    if isinstance(config, dict):
+        per_token = kv_per_token_bytes(config)
+        if per_token:
+            kv_gb = per_token * context / GB
+    if kv_gb is None and weights_gb is not None:
+        kv_gb = 0.06 * (weights_gb / 2.0) * (context / 8192)
+        uncertain.append(
+            "The key-value cache was estimated roughly, because no config.json "
+            "could be read. The deviation can be large."
+        )
+
+    if weights_gb is None:
+        return {
+            "assessable": False,
+            "reason": (
+                "Neither file size nor parameter count could be determined. "
+                "Without either it cannot be said whether the model fits into "
+                "the allotted memory. The switch is therefore not attempted blindly."
+            ),
+        }
+
+    budget_gb = gpu_total_gb * fraction
+    need_gb = weights_gb + (kv_gb or 0.0) + BASE_LOAD_GB
+    fits = need_gb <= budget_gb
+
+    reason = (
+        f"Weights {weights_gb:.2f} GB, key-value cache for {context} tokens "
+        f"{(kv_gb or 0.0):.2f} GB, base load {BASE_LOAD_GB:.2f} GB, together "
+        f"{need_gb:.2f} GB. Allotted are {fraction:.2f} of {gpu_total_gb:.1f} GB, "
+        f"so {budget_gb:.2f} GB."
+    )
+    if not fits:
+        possible = max(
+            0,
+            int((budget_gb - weights_gb - BASE_LOAD_GB) / (kv_gb / context))
+        ) if kv_gb else 0
+        reason += (
+            f" That does not fit. Options: a smaller model, a quantized version, "
+            f"or lowering the context to at most about {possible} tokens."
+        )
+
+    return {
+        "assessable": True,
+        "fits": fits,
+        "weights_gb": round(weights_gb, 2),
+        "kv_cache_gb": round(kv_gb or 0.0, 2),
+        "base_load_gb": BASE_LOAD_GB,
+        "need_gb": round(need_gb, 2),
+        "budget_gb": round(budget_gb, 2),
+        "reason": reason,
+        "uncertainties": uncertain,
+    }