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):

# 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:

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:

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

from mobius._flags import list_flags

print(list_flags())

Adding new flags

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

   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:

   python docs/_generate_flags_docs.py
   

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