feat(cli): remove deprecated boolean build-mode flags

Co-authored-by: justinchuby <11205048+justinchuby@users.noreply.github.com>

Author: Copilot

CHANGELOG.md

@@ -20,9 +20,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 #### Changed
 
-- The boolean flags `--static-cache`, `--fp8-kv-cache`, and `--text-only` are now
-  **deprecated aliases** for the matching `--features` value. They still work and
-  set the same behaviour, but print a deprecation notice on stderr. Companion
+- The boolean flags `--static-cache`, `--fp8-kv-cache`, and `--text-only` have
+  been **removed** in favor of the equivalent `--features` value. Companion
   value args (`--max-seq-len`, `--kv-cache-scale-file`) are unchanged.
 
 ### FP8 (E4M3) KV-cache export (`--features fp8-kv-cache`)

docs/cli_reference.md

@@ -187,8 +187,7 @@ Available features:
 | `text-only` | Export the text backbone of a multimodal checkpoint as a standalone decoder-only LLM (see below). |
 
 The legacy boolean flags `--static-cache`, `--fp8-kv-cache`, and
-`--text-only` still work but are **deprecated** aliases for the matching
-feature and print a warning. Prefer `--features`.
+`--text-only` have been removed in favor of `--features`.
 
 ```bash
 mobius build --model meta-llama/Llama-3.2-1B output/ \
@@ -237,7 +236,7 @@ mobius build --model meta-llama/Llama-3.2-1B output/ \
 | `--max-shard-size SIZE` | Maximum shard size for safetensors external data (e.g. `5GB`). Only used with `--external-data safetensors`. |
 | `--trust-remote-code` | Trust remote code when loading the HuggingFace model config. |
 | `--component NAME` | Build only one component from a diffusers pipeline (e.g. `--component vae_decoder`). |
-| `--text-only` | **Deprecated** alias for `--features text-only`. Export the text backbone of a multimodal checkpoint as a standalone decoder-only LLM. Strips vision/audio routing so the decoder uses `GroupQueryAttention` on GQA-capable EPs (build with `--ep cuda`/`dml`). Currently supported for `gemma4_unified` (`google/gemma-4-12B`). Not compatible with `--config` or `--component`. |
+| `--kv-cache-scale-file PATH` | Optional JSON file of calibrated per-layer FP8 KV-cache scales (onnxruntime-genai format). Only used with the `fp8-kv-cache` feature; without it all layers use a unit scale of 1.0. |
 | `--kv-cache-scale-file PATH` | Optional JSON file of calibrated per-layer FP8 KV-cache scales (onnxruntime-genai format). Only used with the `fp8-kv-cache` feature; without it all layers use a unit scale of 1.0. |
 
 #### Text-only example

examples/gemma4_12b_text_ort_genai.py

@@ -56,7 +56,7 @@
 
 The equivalent raw-ONNX (no genai_config) build is::
 
-    mobius build --model google/gemma-4-12B --text-only --ep cuda --dtype f16 \
+    mobius build --model google/gemma-4-12B --features text-only --ep cuda --dtype f16 \
         out/gemma4_12b_text_onnx/
 """
 

src/mobius/__main__.py

@@ -10,7 +10,6 @@
 import json
 import logging
 import os
-import sys
 from typing import TYPE_CHECKING
 
 import tqdm
@@ -36,9 +35,7 @@
 
 # Rust/cargo-style build features. Each feature name (kebab-case) maps to the
 # boolean attribute on the parsed args that it enables. `--features a,b` (or a
-# repeated `--features`) is the canonical way to toggle these build modes; the
-# legacy per-feature boolean flags remain as deprecated aliases that set the
-# same attributes.
+# repeated `--features`) is the canonical way to toggle these build modes.
 _BUILD_FEATURES: dict[str, str] = {
     "static-cache": "static_cache",
     "fp8-kv-cache": "fp8_kv_cache",
@@ -53,18 +50,11 @@ def _resolve_build_features(args: argparse.Namespace) -> None:
     style), e.g. ``--features fp8-kv-cache,static-cache`` or
     ``--features fp8-kv-cache --features static-cache``. Each recognised feature
     sets its corresponding attribute (``fp8-kv-cache`` -> ``args.fp8_kv_cache``).
-
-    The legacy boolean flags (``--static-cache``, ``--text-only``,
-    ``--fp8-kv-cache``) still work but are deprecated: using one prints a notice
-    and sets the same attribute. Unknown feature names raise ``SystemExit``.
+    Unknown feature names raise ``SystemExit``.
     """
-    # Warn when a caller uses a deprecated boolean alias directly.
-    for feature, dest in _BUILD_FEATURES.items():
-        if getattr(args, dest, False):
-            print(
-                f"Warning: --{feature} is deprecated; use --features {feature} instead.",
-                file=sys.stderr,
-            )
+    for dest in _BUILD_FEATURES.values():
+        if not hasattr(args, dest):
+            setattr(args, dest, False)
 
     raw = getattr(args, "features", None) or []
     requested: list[str] = []
@@ -184,7 +174,7 @@ def _resolve_static_cache_task(model_type: str) -> ModelTask:
         return CausalLMTask(static_cache=True, max_seq_len=args.max_seq_len)
 
     # Fold --features into the boolean build-mode attributes before any
-    # validation reads them (and warn on deprecated boolean aliases).
+    # validation reads them.
     _resolve_build_features(args)
 
     # Validate --max-seq-len requires --static-cache
@@ -725,17 +715,9 @@ def main(argv: list[str] | None = None) -> None:
             "may be repeated). Available: "
             + ", ".join(sorted(_BUILD_FEATURES))
             + ". Example: --features fp8-kv-cache,static-cache. This is the "
-            "canonical replacement for the individual --static-cache / "
-            "--text-only / --fp8-kv-cache flags."
+            "canonical way to enable these build modes."
         ),
     )
-    build_parser.add_argument(
-        "--static-cache",
-        action="store_true",
-        help="[deprecated: use --features static-cache] "
-        "Use static KV cache (pre-allocated buffers with TensorScatter). "
-        "Requires models using DecoderLayer or MoEDecoderLayer.",
-    )
     build_parser.add_argument(
         "--max-seq-len",
         type=int,
@@ -771,31 +753,6 @@ def main(argv: list[str] | None = None) -> None:
             "with --config (local directory), they are copied from that directory."
         ),
     )
-    build_parser.add_argument(
-        "--text-only",
-        dest="text_only",
-        action="store_true",
-        help=(
-            "[deprecated: use --features text-only] "
-            "Export the text backbone of a multimodal checkpoint as a "
-            "standalone decoder-only LLM. Strips vision/audio routing so the "
-            "decoder uses GroupQueryAttention on GQA-capable EPs. Currently "
-            "supported for gemma4_unified (google/gemma-4-12B). Not compatible "
-            "with --config or --component (use --model <hf-id>)."
-        ),
-    )
-    build_parser.add_argument(
-        "--fp8-kv-cache",
-        dest="fp8_kv_cache",
-        action="store_true",
-        help=(
-            "[deprecated: use --features fp8-kv-cache] "
-            "Store the GroupQueryAttention KV cache as FLOAT8E4M3FN (per-tensor "
-            "E4M3), halving KV-cache memory at long context. Requires a "
-            "GQA-capable build (e.g. --execution-provider cuda with --dtype "
-            "f16/bf16) and an ORT runtime with the FP8 KV-cache kernel (SM89+)."
-        ),
-    )
     build_parser.add_argument(
         "--kv-cache-scale-file",
         dest="kv_cache_scale_file",

tests/cli_test.py

@@ -78,7 +78,17 @@ def test_build_missing_model_errors(self):
     def test_text_only_with_config_errors(self):
         """--text-only is rejected on the --config (local dir) path."""
         with tempfile.TemporaryDirectory() as tmpdir, pytest.raises(SystemExit):
-            main(["build", "--config", tmpdir, tmpdir, "--text-only", "--no-weights"])
+            main(
+                [
+                    "build",
+                    "--config",
+                    tmpdir,
+                    tmpdir,
+                    "--features",
+                    "text-only",
+                    "--no-weights",
+                ]
+            )
 
     def test_text_only_with_component_errors(self):
         """--text-only is rejected when combined with --component."""
@@ -89,7 +99,8 @@ def test_text_only_with_component_errors(self):
                     "--model",
                     "google/gemma-4-12B",
                     tmpdir,
-                    "--text-only",
+                    "--features",
+                    "text-only",
                     "--component",
                     "vision_encoder",
                     "--no-weights",
@@ -116,7 +127,8 @@ def test_text_only_skips_diffusers_autodetect(self):
                     "--model",
                     "some/diffusion-repo",
                     tmpdir,
-                    "--text-only",
+                    "--features",
+                    "text-only",
                     "--no-weights",
                 ]
             )
@@ -134,7 +146,8 @@ def test_build_static_cache(self):
                     "Qwen/Qwen2.5-0.5B",
                     tmpdir,
                     "--no-weights",
-                    "--static-cache",
+                    "--features",
+                    "static-cache",
                 ]
             )
             assert os.path.isfile(os.path.join(tmpdir, "model.onnx"))
@@ -269,21 +282,6 @@ def test_features_unknown_errors(self):
                 ]
             )
 
-    def test_deprecated_static_cache_flag_warns(self, capsys):
-        """The legacy --static-cache flag still works but warns."""
-        with tempfile.TemporaryDirectory() as tmpdir:
-            main(
-                [
-                    "build",
-                    "--model",
-                    "Qwen/Qwen2.5-0.5B",
-                    tmpdir,
-                    "--no-weights",
-                    "--static-cache",
-                ]
-            )
-        assert "--static-cache is deprecated" in capsys.readouterr().err
-
     def test_max_seq_len_without_static_cache_errors(self):
         with tempfile.TemporaryDirectory() as tmpdir, pytest.raises(SystemExit):
             main(
@@ -308,7 +306,8 @@ def test_static_cache_with_task_errors(self):
                     "Qwen/Qwen2.5-0.5B",
                     tmpdir,
                     "--no-weights",
-                    "--static-cache",
+                    "--features",
+                    "static-cache",
                     "--task",
                     "text-generation",
                 ]
@@ -323,7 +322,8 @@ def test_non_positive_max_seq_len_errors(self):
                     "Qwen/Qwen2.5-0.5B",
                     tmpdir,
                     "--no-weights",
-                    "--static-cache",
+                    "--features",
+                    "static-cache",
                     "--max-seq-len",
                     "0",
                 ]
@@ -340,7 +340,8 @@ def test_static_cache_with_max_seq_len(self):
                     "Qwen/Qwen2.5-0.5B",
                     tmpdir,
                     "--no-weights",
-                    "--static-cache",
+                    "--features",
+                    "static-cache",
                     "--max-seq-len",
                     str(max_seq_len),
                 ]