Fix eager import cascade causing platform fallback in platform.py + add GPT-OSS mlx_lm ground truth (#221)

Author: sshkhr

tests/test_platform.py

@@ -2,7 +2,8 @@
 """Tests for Metal platform."""
 
 import platform
-from types import SimpleNamespace
+import sys
+from types import ModuleType, SimpleNamespace
 
 import pytest
 import torch
@@ -24,10 +25,12 @@ def _patch_stt_resolution(
         is_stt: bool,
     ) -> None:
         monkeypatch.setattr(
-            "vllm_metal.platform.get_model_download_path",
+            "vllm_metal.utils.get_model_download_path",
             lambda model: model,
         )
-        monkeypatch.setattr("vllm_metal.platform.is_stt_model", lambda _model: is_stt)
+        monkeypatch.setattr(
+            "vllm_metal.stt.detection.is_stt_model", lambda _model: is_stt
+        )
 
     def test_device_name(self) -> None:
         """Test device name retrieval."""
@@ -123,6 +126,29 @@ def test_is_available_does_not_mutate_default_device(self) -> None:
 
         assert before == after
 
+    def test_is_available_propagates_unexpected_mlx_errors(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Unexpected MLX errors should surface instead of looking unavailable."""
+        monkeypatch.setattr("vllm_metal.platform.py_platform.machine", lambda: "arm64")
+        monkeypatch.setattr("vllm_metal.platform.py_platform.system", lambda: "Darwin")
+
+        mlx_module = ModuleType("mlx")
+        mlx_core = ModuleType("mlx.core")
+
+        class _BrokenMetal:
+            @staticmethod
+            def is_available() -> bool:
+                raise ValueError("unexpected mlx regression")
+
+        mlx_core.metal = _BrokenMetal()
+        mlx_module.core = mlx_core
+        monkeypatch.setitem(sys.modules, "mlx", mlx_module)
+        monkeypatch.setitem(sys.modules, "mlx.core", mlx_core)
+
+        with pytest.raises(ValueError, match="unexpected mlx regression"):
+            MetalPlatform.is_available()
+
     def test_torch_device(self) -> None:
         """Test PyTorch device retrieval."""
 

tools/gen_golden_token_ids_for_deterministics.py

@@ -1,14 +1,18 @@
 #!/usr/bin/env python3
 # SPDX-License-Identifier: Apache-2.0
-"""Generate golden token IDs for the deterministic smoke test.
+"""Generate golden token IDs for deterministic smoke tests.
 
 Runs vLLM offline inference (greedy, max_num_seqs=1) and prints golden
-token-ID dicts to paste into test_paged_deterministic.py.
+token-ID dicts to paste into test files or smoke scripts.
 
 Usage:
-    # MLX inline cache (default):
+    # Qwen3 (default, MLX inline cache):
     VLLM_ENABLE_V1_MULTIPROCESSING=0 python tools/gen_golden_token_ids_for_deterministics.py
 
+    # GPT-OSS (requires chat template):
+    VLLM_ENABLE_V1_MULTIPROCESSING=0 python tools/gen_golden_token_ids_for_deterministics.py \
+        --model openai/gpt-oss-20b --max-tokens 100 --chat-template
+
     # Paged KV cache:
     VLLM_METAL_USE_PAGED_ATTENTION=1 VLLM_METAL_MEMORY_FRACTION=0.3 \
         VLLM_ENABLE_V1_MULTIPROCESSING=0 python tools/gen_golden_token_ids_for_deterministics.py
@@ -17,14 +21,12 @@
       Numeric fractions are only valid for the paged attention path.
 """
 
+import argparse
 import os
 
 os.environ.setdefault("VLLM_ENABLE_V1_MULTIPROCESSING", "0")
 
-from vllm import LLM, SamplingParams
-
-MODEL = "Qwen/Qwen3-0.6B"
-MAX_TOKENS = 10
+from vllm import LLM, SamplingParams  # noqa: E402
 
 PROMPTS = [
     "The capital of France is",
@@ -35,21 +37,54 @@
     "Machine learning is",
 ]
 
+
+def _apply_chat_template(model_name, prompts):
+    """Apply chat template and return (formatted_prompts, reverse_map)."""
+    from transformers import AutoTokenizer
+
+    tokenizer = AutoTokenizer.from_pretrained(model_name)
+    formatted = []
+    reverse_map = {}
+    for prompt in prompts:
+        messages = [{"role": "user", "content": prompt}]
+        fmt = tokenizer.apply_chat_template(
+            messages, add_generation_prompt=True, tokenize=False
+        )
+        formatted.append(fmt)
+        reverse_map[fmt] = prompt
+    return formatted, reverse_map
+
+
 if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--model", default="Qwen/Qwen3-0.6B")
+    parser.add_argument("--max-tokens", type=int, default=10)
+    parser.add_argument(
+        "--chat-template",
+        action="store_true",
+        help="Apply chat template before inference (required for GPT-OSS)",
+    )
+    args = parser.parse_args()
+
     paged = os.environ.get("VLLM_METAL_USE_PAGED_ATTENTION", "0") == "1"
     label = "PAGED" if paged else "MLX"
-    print(f"\n--- Generating golden values for {label} path ---\n")
+    print(f"\n--- Generating golden values for {label} path ({args.model}) ---\n")
+
+    prompts = PROMPTS
+    reverse_map = None
+    if args.chat_template:
+        prompts, reverse_map = _apply_chat_template(args.model, PROMPTS)
 
-    llm = LLM(model=MODEL, max_model_len=512, max_num_seqs=1)
-    sp = SamplingParams(temperature=0, max_tokens=MAX_TOKENS)
-    outputs = llm.generate(PROMPTS, sp)
+    llm = LLM(model=args.model, max_model_len=512, max_num_seqs=1)
+    sp = SamplingParams(temperature=0, max_tokens=args.max_tokens)
+    outputs = llm.generate(prompts, sp)
 
     print(f"\nGOLDEN_{label} = {{")
     for o in outputs:
-        prompt = o.prompt
+        display = reverse_map[o.prompt] if reverse_map else o.prompt
         ids = list(o.outputs[0].token_ids)
         text = o.outputs[0].text
-        pad = 45 - len(prompt)
-        print(f"    {prompt!r}:{' ' * pad}{ids},")
+        pad = 50 - len(display)
+        print(f"    {display!r}:{' ' * max(pad, 1)}{ids},")
         print(f"        # → {text!r}")
     print("}")

tools/test_gpt_oss_smoke.py

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+"""GPT-OSS 20B smoke test: mlx_lm ground truth for sink attention work (#148).
+
+Loads openai/gpt-oss-20b, generates with greedy decoding, and compares
+output against golden token IDs.  Not in CI since it requires ~21.5 GB model.
+
+Run:
+    VLLM_ENABLE_V1_MULTIPROCESSING=0 python tools/test_gpt_oss_smoke.py
+"""
+
+import os
+import sys
+
+os.environ.setdefault("VLLM_ENABLE_V1_MULTIPROCESSING", "0")
+
+from transformers import AutoTokenizer  # noqa: E402
+from vllm import LLM, SamplingParams  # noqa: E402
+
+MODEL_NAME = "openai/gpt-oss-20b"
+MAX_TOKENS = 100
+
+PROMPTS = [
+    "The capital of France is",
+    "The weather today is not",
+    "One plus one equals",
+    "The largest planet in our solar system is",
+    "Water boils at a temperature of",
+]
+
+# fmt: off
+# Golden token IDs from MLX inline cache, greedy decoding (openai/gpt-oss-20b).
+# Generated via:
+#   VLLM_ENABLE_V1_MULTIPROCESSING=0 python tools/gen_golden_token_ids_for_deterministics.py \
+#       --model openai/gpt-oss-20b --max-tokens 100 --chat-template
+#
+# Note: FP non-determinism at longer sequences may cause 2-3 prompts to diverge
+# after ~25 tokens across runs.  Regenerate with the command above if needed.
+GOLDEN_MLX = {
+    "The capital of France is": [200005, 35644, 200008, 976, 1825, 5003, 25, 392, 976, 9029, 328, 10128, 382, 4050, 3164, 6960, 1682, 290, 6052, 25, 392, 72782, 4050, 2632, 9570, 483, 392, 72782, 4050, 63659, 1327, 6052, 13, 200007, 200006, 173781, 200005, 17196, 200008, 72782, 200002],
+    "The weather today is not": [200005, 35644, 200008, 976, 1825, 5003, 25, 392, 976, 11122, 4044, 382, 625, 4050, 4569, 7890, 60592, 13, 3164, 3572, 413, 8601, 261, 21872, 25, 392, 976, 11122, 4044, 382, 625, 723, 64493, 49706, 889, 1023, 9289, 9115, 13, 3164, 3572, 413, 16054, 395, 3543, 30, 2604, 10112, 1023, 1682, 316, 1761, 290, 11122, 30, 623, 1825, 5003, 392, 976, 11122, 4044, 382, 625, 4050, 4569, 382, 60592, 13, 1416, 1309, 316, 9570, 54286, 13, 1416, 2023, 3810, 395, 108041, 25, 392, 4827, 1481, 481, 1299, 316, 1761, 1078, 290, 11122, 16842, 2604, 581, 2023, 18135, 484, 1023, 1682, 316],
+    "One plus one equals": [200005, 35644, 200008, 976, 1825, 5003, 25, 392, 5045, 2932, 1001, 29702, 4050, 3164, 6960, 1682, 290, 6052, 25, 220, 17, 13, 3072, 10112, 1023, 1682, 261, 945, 65742, 6052, 30, 623, 1825, 3572, 413, 11493, 13, 623, 63122, 6052, 25, 220, 17, 13, 3072, 10112, 1023, 1682, 261, 15681, 30, 623, 21179, 25, 392, 3575, 553, 17554, 162016, 11, 261, 4410, 6439, 2359, 22203, 656, 7788, 17527, 3692, 32711, 860, 3582, 21179, 13, 2632, 6052, 25, 220, 17, 13, 200007, 200006, 173781, 200005, 17196, 200008, 5045, 2932, 1001, 29702, 6240, 17, 410, 13, 200002],
+    "The largest planet in our solar system is": [200005, 35644, 200008, 976, 1825, 31064, 25, 392, 976, 10574, 17921, 306, 1039, 17624, 2420, 382, 4050, 3164, 6960, 1682, 290, 6052, 25, 79575, 13, 3164, 3572, 1682, 261, 18128, 13, 2632, 6052, 25, 79575, 13, 138743, 8633, 4275, 290, 10574, 13, 2632, 9570, 25, 79575, 13, 200007, 200006, 173781, 200005, 17196, 200008, 976, 10574, 17921, 306, 1039, 17624, 2420, 382, 6240, 41, 26451, 410, 13, 200002],
+    "Water boils at a temperature of": [200005, 35644, 200008, 976, 1825, 5003, 25, 392, 27874, 165683, 540, 261, 12088, 328, 4050, 3164, 6960, 1682, 290, 79667, 2438, 328, 3411, 13, 3072, 290, 4928, 382, 60592, 25, 392, 27874, 165683, 540, 261, 12088, 328, 4050, 3164, 3572, 1682, 290, 6052, 25, 220, 1353, 26557, 540, 220, 16, 83327, 11, 503, 220, 19584, 68854, 13, 3072, 10112, 1023, 1682, 290, 12088, 306, 181775, 25, 220, 33797, 13, 1055, 658, 13, 623, 1825, 3572, 413, 35885, 261, 52077, 6052, 13, 623, 4928, 382, 60592, 889, 6960, 1023, 1682, 290, 79667, 2438, 13, 2632, 6052, 25, 220, 1353, 26557, 350],
+}
+# fmt: on
+
+
+def _apply_chat_template(model_name, prompts):
+    """Apply chat template and return (formatted_prompts, reverse_map)."""
+    tokenizer = AutoTokenizer.from_pretrained(model_name)
+    formatted = []
+    reverse_map = {}
+    for prompt in prompts:
+        messages = [{"role": "user", "content": prompt}]
+        fmt = tokenizer.apply_chat_template(
+            messages, add_generation_prompt=True, tokenize=False
+        )
+        formatted.append(fmt)
+        reverse_map[fmt] = prompt
+    return formatted, reverse_map
+
+
+if __name__ == "__main__":
+    formatted_prompts, reverse_map = _apply_chat_template(MODEL_NAME, PROMPTS)
+
+    llm = LLM(model=MODEL_NAME, max_model_len=512, max_num_seqs=1)
+    sp = SamplingParams(temperature=0, max_tokens=MAX_TOKENS)
+    outputs = llm.generate(formatted_prompts, sp)
+
+    passed = 0
+    failed = 0
+    for o in outputs:
+        prompt = reverse_map[o.prompt]
+        token_ids = list(o.outputs[0].token_ids)
+        text = o.outputs[0].text
+        expected = GOLDEN_MLX[prompt]
+        matched = token_ids == expected
+
+        status = "PASS" if matched else "FAIL"
+        print(f"  [{status}] {prompt!r}")
+        print(f"         output: {text!r}")
+        if not matched:
+            print(f"         got:      {token_ids}")
+            print(f"         expected: {expected}")
+            failed += 1
+        else:
+            passed += 1
+
+    print(f"\n{passed} passed, {failed} failed")
+    sys.exit(1 if failed else 0)

vllm_metal/platform.py

@@ -11,9 +11,6 @@
 from vllm.v1.attention.backends.registry import AttentionBackendEnum
 
 from vllm_metal.config import get_config
-from vllm_metal.stt.detection import is_stt_model
-from vllm_metal.stt.policy import apply_stt_scheduler_policy
-from vllm_metal.utils import get_model_download_path
 
 if TYPE_CHECKING:
     from vllm.config import VllmConfig
@@ -273,6 +270,12 @@ def check_and_update_config(cls, vllm_config: "VllmConfig") -> None:
             model_config.disable_cascade_attn = True
 
         # STT model detection — set tokenizer fallback if not already configured.
+        # Lazy imports to avoid circular import: platform.py is loaded during
+        # vllm.config init, and stt.detection imports from vllm.config.
+        from vllm_metal.stt.detection import is_stt_model
+        from vllm_metal.stt.policy import apply_stt_scheduler_policy
+        from vllm_metal.utils import get_model_download_path
+
         resolved_model = (
             get_model_download_path(model_config.model)
             if model_config is not None