Text-only mlxk run against multimodal VLMs fails with cryptic loader error

[mzau]

Problem

mlxk run <model> "prompt" against certain multimodal VLMs fails late with a cryptic mlx-lm loader error instead of being rejected pre-execution or routed correctly.

Reproduction

mlxk run gemma-4-e4b-it-4bit "what is 2+2?"
# Error: Failed to load model from /path/gemma-4-e4b-it-4bit:
# Received 126 parameters not in model:
# language_model.model.layers.24.self_attn.k_norm.weight, ...

Same model with --image or --audio works correctly.

Affected (empirical)

Model	model_type	vision_config	audio_config	text-only
gemma-4-e4b-it-4bit	gemma4	dict	dict	❌ param mismatch
gemma-3n-E2B-{4bit,it-4bit}	gemma3n	dict	dict	❌ KeyError 'model'
Llama-3.2-Vision-* (mllama family)	mllama	dict	absent	❌ no text-tower loader

The discriminator is not purely model_type-based — empirically it depends on (model_type, audio_config-truthy) for gemma4, and on the architecture's text-tower-loader availability for mllama.

Workaround

For multimodal models, always pass media:

mlxk run gemma-4-e4b-it-4bit "describe" --image <file>.jpeg
mlxk run gemma-4-e4b-it-4bit --audio <file>.mp3

mllama / Llama-3.2-Vision: only --image works (no text-only mode at all).

Planned Fix (2.1)

Implement reachability layer 2 as a probe combining auto-discovered MLX_LM_TEXT_LOADER_TYPES (from pkgutil.iter_modules(mlx_lm.models.__path__) + MODEL_REMAPPING keys) with config-shape filters. Single source of truth for:

• Pre-execution routing in run.py
• Health-aggregator's text-load gate in common.py
• text capability label in detect_capabilities

Reference: docs/RUNTIME-FEATURES.md §5 Class C. ADR-024 (stub) carries the original Vision-only routing motivation; full content lands with the 2.1 reachability refactor.

Why not surgical in 2.0.6?

A hardcoded predicate per architecture (gemma4 + truthy audio_config, mllama always, etc.) would fragment into a maintenance liability — each new VLM would need a new hardcoded line. The principled fix (auto-discovery) generalises by construction.

The 2.0.6 surgical patch (Class A + B) addresses capability label correctness (the affected models are now correctly typed; audio_config: null false-positives are gone for the gemma4-31b family) — but text-only invocation against them still hits this cryptic error.