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.

9.8 KB
Raw Blame
# SPDX-License-Identifier: AGPL-3.0-only
# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved.

"""The shared estimate must still project two different weights_bytes meanings, one per legacy route."""

import sys
from pathlib import Path
from types import SimpleNamespace

_TESTS_DIR = str(Path(__file__).resolve().parent)
if _TESTS_DIR not in sys.path:
    sys.path.insert(0, _TESTS_DIR)

_BACKEND_DIR = str(Path(__file__).resolve().parent.parent)
if _BACKEND_DIR not in sys.path:
    sys.path.insert(0, _BACKEND_DIR)

# Imported for side effects: installs loggers/structlog/httpx stubs.
import test_kv_cache_estimation  # noqa: E402,F401

import pytest  # noqa: E402

from core.inference.memory_contract import (  # noqa: E402
    build_memory_estimate,
    project_estimate_memory_response,
    project_kv_cache_estimate,
)

# Distinct values per term so reading the wrong field cannot pass by coincidence.
_BREAKDOWN = SimpleNamespace(
    weights_bytes = 5_000_000_000,
    kv_bytes = 3_000_000_000,
    kv_checkpoint_bytes = 600_000_000,
    compute_bytes = 700_000_000,
    drafter_runtime_bytes = 400_000_000,
    drafter_runtime_gpu_bytes = 250_000_000,
    projector_runtime_bytes = 120_000_000,
    drafter_kv_unsized = False,
    adapters_unsized = False,
    total_bytes = 8_700_000_000,
    gpu_bytes = 8_100_000_000,
    kv_estimable = True,
    kv_on_gpu = True,
    n_ctx = 32768,
    cache_type_kv = "f16",
    n_parallel = 4,
    layer_count = 28,
    gpu_layers = 28,
)

_QUANT_FILE_BYTES = 4_100_000_000


@pytest.fixture
def estimate():
    return build_memory_estimate(
        _BREAKDOWN,
        quant_file_bytes = _QUANT_FILE_BYTES,
        native_context = 131072,
        gpu_floor_bytes = 900_000_000,
        context_is_pinned = False,
        inherited_device_pin = True,
        spec_unpriced = True,
    )


class TestTheCanonicalModel:
    def test_the_ambiguous_name_is_gone(self, estimate):
        assert not hasattr(estimate, "weights_bytes"), (
            "MemoryEstimate has grown a weights_bytes field. That name means two "
            "different things on the two legacy routes and belongs on neither the "
            "shared model nor any new caller."
        )

    def test_the_two_meanings_are_separate_and_ordered(self, estimate):
        assert estimate.quant_file_bytes == _QUANT_FILE_BYTES
        assert estimate.resident_files_bytes == _BREAKDOWN.weights_bytes
        assert estimate.quant_file_bytes < estimate.resident_files_bytes

    def test_the_planner_weights_field_is_the_resident_meaning(self, estimate):
        # Planner weights_bytes is the AGGREGATE; mapping it to quant_file_bytes is the trap.
        assert estimate.resident_files_bytes == _BREAKDOWN.weights_bytes
        assert estimate.quant_file_bytes != _BREAKDOWN.weights_bytes

    def test_the_two_figures_are_reported_as_given(self):
        """Quant and resident figures have separate sources, so neither is clamped to match."""
        out = build_memory_estimate(_BREAKDOWN, quant_file_bytes = 9_999_999_999)
        assert out.quant_file_bytes == 9_999_999_999
        assert out.resident_files_bytes == _BREAKDOWN.weights_bytes

    def test_optional_terms_default_without_being_invented(self):
        out = build_memory_estimate(_BREAKDOWN, quant_file_bytes = _QUANT_FILE_BYTES)
        # None means not computed; 0 is a real value.
        assert out.gpu_floor_bytes is None
        assert out.native_context is None


class TestTheRouteOverrides:
    """The figures /kv-cache-estimate computes itself, passed in not assigned on."""

    def test_gpu_bytes_carries_three_distinct_states(self):
        assert build_memory_estimate(_BREAKDOWN, quant_file_bytes = 1, gpu_bytes = 0).gpu_bytes == 0
        assert (
            build_memory_estimate(_BREAKDOWN, quant_file_bytes = 1, gpu_bytes = None).gpu_bytes is None
        )
        assert (
            build_memory_estimate(_BREAKDOWN, quant_file_bytes = 1).gpu_bytes == _BREAKDOWN.gpu_bytes
        )

    def test_the_other_overrides_apply(self):
        out = build_memory_estimate(
            _BREAKDOWN,
            quant_file_bytes = 1,
            compute_bytes = 11,
            total_bytes = 22,
            n_ctx = 33,
        )
        assert (out.compute_bytes, out.total_bytes, out.n_ctx) == (11, 22, 33)
        none_out = build_memory_estimate(
            _BREAKDOWN,
            quant_file_bytes = 1,
            compute_bytes = None,
            total_bytes = None,
            n_ctx = None,
        )
        assert (none_out.compute_bytes, none_out.total_bytes, none_out.n_ctx) == (0, 0, 0)

    def test_the_route_does_not_mutate_the_model_after_building_it(self):
        """Assignment skips validation, so the route must build a model rather than mutate it."""
        from pathlib import Path

        source = (Path(__file__).resolve().parent.parent / "routes" / "models.py").read_text(
            encoding = "utf-8"
        )
        for field in ("gpu_bytes", "compute_bytes", "total_bytes", "n_ctx"):
            assert f"_estimate.{field} =" not in source, (
                f"routes/models.py assigns {field} onto a built MemoryEstimate. "
                "Pass it to build_memory_estimate instead; assignment skips "
                "validation entirely."
            )

    def test_assignment_really_is_unvalidated(self):
        from models.inference import MemoryEstimate

        m = MemoryEstimate(available = True)
        m.gpu_bytes = "not an int"
        assert m.gpu_bytes == "not an int", (
            "assignment now validates; the no-mutation guard above is no longer "
            "load-bearing and its comment should be updated"
        )


class TestTheLegacyProjections:
    def test_estimate_memory_gets_the_resident_total(self, estimate):
        out = project_estimate_memory_response(estimate)
        assert (
            out["weights_bytes"] == _BREAKDOWN.weights_bytes
        ), "the Load Model panel itemizes weights_bytes as every resident file"

    def test_estimate_memory_carries_the_checkpoint_share(self, estimate):
        out = project_estimate_memory_response(estimate)
        assert out["kv_checkpoint_bytes"] == _BREAKDOWN.kv_checkpoint_bytes
        assert out["kv_bytes"] == _BREAKDOWN.kv_bytes

    def test_kv_cache_estimate_gets_the_quant_file(self, estimate):
        out = project_kv_cache_estimate(estimate)
        assert out["weights_bytes"] == _QUANT_FILE_BYTES, (
            "the Hub bar draws its weights segment from weights_bytes and prints it "
            "beside the download size on the same row"
        )

    def test_the_two_projections_disagree_about_weights_bytes(self, estimate):
        """The two routes must keep differing on weights_bytes, since their meanings were never shared."""
        panel = project_estimate_memory_response(estimate)
        bar = project_kv_cache_estimate(estimate)
        assert panel["weights_bytes"] != bar["weights_bytes"], (
            "both routes now report the same weights_bytes. See the module "
            "docstring: these two meanings are different by design."
        )

    def test_the_kv_projection_keeps_none_rather_than_zero(self):
        # Frontend estimateIsUnsized() distinguishes null from 0.
        empty = SimpleNamespace(**{**_BREAKDOWN.__dict__, "kv_bytes": 0})
        out = project_kv_cache_estimate(
            build_memory_estimate(empty, quant_file_bytes = 0), kv_bytes = 0
        )
        assert out["kv_bytes"] is None
        assert out["weights_bytes"] is None

    def test_a_zero_gpu_share_survives_as_zero(self):
        """A zero GPU share must stay 0, not become None, or CPU-only loads get priced as VRAM pressure."""
        cpu_only = SimpleNamespace(**{**_BREAKDOWN.__dict__, "gpu_bytes": 0})
        out = project_kv_cache_estimate(
            build_memory_estimate(cpu_only, quant_file_bytes = _QUANT_FILE_BYTES),
            kv_bytes = _BREAKDOWN.kv_bytes,
        )
        assert out["gpu_bytes"] == 0, "a real zero GPU share was folded into 'no answer'"

    def test_a_missing_planner_leaves_the_gpu_share_null(self):
        absent = SimpleNamespace(**{**_BREAKDOWN.__dict__, "gpu_bytes": None})
        out = project_kv_cache_estimate(
            build_memory_estimate(absent, quant_file_bytes = _QUANT_FILE_BYTES),
            kv_bytes = _BREAKDOWN.kv_bytes,
        )
        assert out["gpu_bytes"] is None

    def test_the_mlx_offload_the_breakdown_priced_is_reported(self):
        mlx = {"ple_offload": None, "expert_offload": 0.6, "offloadable": ("experts",)}
        offloaded = SimpleNamespace(**{**_BREAKDOWN.__dict__, **mlx})
        panel = project_estimate_memory_response(
            build_memory_estimate(offloaded, quant_file_bytes = 0)
        )
        assert panel["mlx_offload"].model_dump() == {
            "ple": None,
            "experts": 0.6,
            "offloadable": ["experts"],
        }
        assert build_memory_estimate(_BREAKDOWN, quant_file_bytes = 0).mlx_offload is None

    def test_the_kv_projection_does_not_borrow_the_planners_kv(self, estimate):
        assert project_kv_cache_estimate(estimate)["kv_bytes"] is None

    def test_the_kv_projection_passes_its_own_itemization_through(self, estimate):
        out = project_kv_cache_estimate(
            estimate,
            spec_bytes = 111,
            spec_fixed_bytes = 22,
            projector_bytes = 333,
            kv_checkpoint_bytes = 44,
        )
        assert (out["spec_bytes"], out["spec_fixed_bytes"]) == (111, 22)
        assert (out["projector_bytes"], out["kv_checkpoint_bytes"]) == (333, 44)

    def test_both_projections_carry_every_key_their_route_promises(self, estimate):
        from test_memory_estimate_contract_freeze import _KV_CACHE_ESTIMATE_KEYS

        assert set(project_kv_cache_estimate(estimate)) == set(_KV_CACHE_ESTIMATE_KEYS)

        from models.inference import EstimateMemoryResponse

        assert set(project_estimate_memory_response(estimate)) == set(
            EstimateMemoryResponse.model_fields
        )