<!-- This file is AUTO-GENERATED by docs/_generate_flags_docs.py.
     Do NOT edit it by hand — run the script instead. -->

# Feature Flags

mobius exposes runtime feature flags that control experimental or
environment-specific behaviour. Flags live in `mobius._flags` and are
for **internal use only** — external callers configure them via environment
variables (see below).

## Available flags

| Flag | Environment variable | Default | Description |
|------|---------------------|---------|-------------|
| `suppress_dedup_warning` | `MOBIUS_SUPPRESS_DEDUP_WARNING` | `true` | Suppress "has no constant value" warnings from the initializer-deduplication pass. These warnings are expected noise when optimisation passes run before weights are loaded. Set ``MOBIUS_SUPPRESS_DEDUP_WARNING=0`` to see all warnings. |
| `ort_cuda_grouped_rmsnorm_workaround` | `MOBIUS_ORT_CUDA_GROUPED_RMSNORM_WORKAROUND` | `false` | Decompose grouped RMSNormalization into basic ops to work around an ORT <=1.24.4 CUDA kernel bug that produces wrong results when scale is 2D. Set ``MOBIUS_ORT_CUDA_GROUPED_RMSNORM_WORKAROUND=1`` when targeting CUDA. |
| `ort_lower_opset_for_ep` | `MOBIUS_ORT_LOWER_OPSET_FOR_EP` | `false` | Lower the ONNX default-domain opset declaration to 23 when creating ORT sessions on non-CPU execution providers (CUDA, TRT, etc.). ORT <=1.24.x EPs didn't register kernels for opset 24 standard ops (Squeeze, Reshape, etc.) even though the semantics are unchanged. Lowering the import declaration lets the EP find its existing kernels. Set ``MOBIUS_ORT_LOWER_OPSET_FOR_EP=1`` to re-enable if running on an older ORT build without opset 24 kernel registration. |
| `tencent_q1_0_use_native_2bit` | `MOBIUS_TENCENT_Q1_0_USE_NATIVE_2BIT` | `false` | Emit Tencent custom Q1_0 (2-bit SEQ) tensors using native ``MatMulNBits bits=2`` + float ``zero_point = 1.5`` instead of the ``bits=4`` inflation that defaults today. Pros (when set to ``True``): Halves the on-disk weight bytes (2 bpw vs 4 bpw inflated). Semantically faithful to the source quantization layout. Cons (default ``False``): ORT's CPU ``bits=2`` + float-zp dequant path is currently a naive scalar fallback (~20x slower than the ``bits=4`` packed path on the same weights). See `microsoft/onnxruntime#28552 <https://github.com/microsoft/onnxruntime/issues/28552>`_. Also requires ORT >=1.27 (the float-zp path was added in `microsoft/onnxruntime#28354 <https://github.com/microsoft/onnxruntime/pull/28354>`_). The ``bits=4`` default inflates each 2-bit code ``c in {0..3}`` to a 4-bit slot ``2c in {0,2,4,6}`` paired with integer ``zero_point=3``; dequant gives the same SEQ codebook values, just at twice the weight storage. Set ``MOBIUS_TENCENT_Q1_0_USE_NATIVE_2BIT=1`` to opt in to the smaller native form once kernel performance lands. |
| `static_cache_bias` | `MOBIUS_STATIC_CACHE_BIAS` | `false` | Emit a float additive attention bias on the external-KV static-cache ``Attention`` path instead of the maskless ``is_causal=1`` default. When ``True`` (and the model declares a bias need, e.g. a sliding window or a block-overlay hook), :class:`~mobius.models.base.TextModel` builds a ``(B, 1, S_q, max_seq)`` additive bias via :func:`~mobius.components.create_static_cache_attention_bias` (causal + sliding window + block overlay + padding, keyed on absolute query positions with KV validity ``slot < nonpad_kv_seqlen``) and threads it into the static-cache ``Attention`` op with ``is_causal=0``. This lets a single standard-``Attention`` graph carry an arbitrary additive bias that ``com.microsoft.GroupQueryAttention`` cannot express, while still using the opset-24 external KV cache (``TensorScatter`` + ``nonpad_kv_seqlen``). Default ``False``: the maskless ``is_causal=1`` static-cache emission is unchanged, so no shipped model's graph changes unless this flag is set. |

## Setting flags via environment variables

Environment variables are read when the global `flags` singleton is constructed
at import time. Set them before importing mobius (e.g., in a shell or `.env`):

```bash
# Example: disable warning suppression to see all deduplication warnings
export MOBIUS_SUPPRESS_DEDUP_WARNING=0

python -c "import mobius; mobius.build('Qwen/Qwen2.5-0.5B-Instruct')"
```

Accepted truthy values: `1`, `true`, `yes` (case-insensitive).\
Accepted falsy values: `0`, `false`, `no` (case-insensitive).\
Any other value falls back to the field default.

## Setting flags programmatically (internal code only)

Internal modules can import `flags` directly and assign to it:

```python
from mobius._flags import flags

flags.suppress_dedup_warning = False  # disable
flags.suppress_dedup_warning = True   # re-enable
```

## Using `override_flags()` in tests

For tests that need a temporary flag value, use the `override_flags` context
manager. It restores the original values on exit, even if the test raises:

```python
from mobius._flags import override_flags

def test_build_with_warnings(tmp_path):
    with override_flags(suppress_dedup_warning=False):
        pkg = mobius.build("Qwen/Qwen2.5-0.5B-Instruct")
    # suppress_dedup_warning is restored here
```

`override_flags` raises `ValueError` for unknown flag names, catching typos early.

> **Thread safety:** `override_flags` is not thread-safe — concurrent calls
> in different threads may interleave the save/restore cycle (TOCTOU).  For
> pytest, this is safe with `pytest -n auto` because xdist workers run in
> separate processes with independent flag singletons.

## Listing all flags

```python
from mobius._flags import list_flags

print(list_flags())
```

## Adding new flags

1. Add a field to `_Flags` in `src/mobius/_flags.py`:

   ```python
   my_new_flag: bool = dataclasses.field(
       default_factory=lambda: _env_bool("MOBIUS_MY_NEW_FLAG", False)
   )
   """Short description of what my_new_flag controls."""
   ```

2. Wire the flag into the code path it controls.

3. Regenerate this page:

   ```bash
   python docs/_generate_flags_docs.py
   ```

4. Add tests in `src/mobius/_flags_test.py` following existing patterns.