Fix YaRN RoPE bugs in model builder and add parity tests

[titaiwangms]

Summary

Fixes four bugs in the ModelBuilder's YaRN RoPE configuration resolution that caused completely wrong cos/sin caches, producing garbage output for ALL YaRN-based models (Ministral-3-3B, OpenAI OS-minier, and any model using beta_fast/beta_slow in rope_scaling).

Also adds comprehensive parity tests and addresses review feedback.

Bugs Fixed

Bug 1: hasattr on dict for original_max_position_embeddings

hasattr(config.rope_scaling, 'original_max_position_embeddings') always returns False for dicts. Fixed to use isinstance(Mapping) + in operator.

Bug 2: rope_theta fallback

Models that store rope_theta only in rope_scaling dict (not as a top-level config attribute) fell through to default theta=10000. Added fallback chain: config.rope_theta → config.rope_embedding_base → config.rope_scaling["rope_theta"] → 10000.

Bug 3: YaRN mscale override

Always computed mscale from factor via make_mscale(), ignoring explicit mscale=1.0 in config. Ministral-3-3B sets mscale=1.0 but was getting mscale≈1.277. Now respects the config value when > 0.

Bug 4: inv_freq double-inversion

make_inv_freq_rescaled_with_ntk computed 1/(factor * inv_freq) which double-inverts since inv_freq is already 1/pos_freqs, giving pos_freqs/factor (wrong). Fixed to inv_freq / factor.

Review Feedback Addressed

• Changed isinstance(rope_scaling, dict) → isinstance(rope_scaling, Mapping) in 2 locations (handles FrozenDict, MappingProxyType, dict subclasses)
• Added Mapping import from collections.abc
• Added documentation comment for mscale_all_dim handling

Tests Added

Added test/python/test_yarn_rope_parity.py with 8 tests verifying cos/sin cache parity against HuggingFace transformers reference:

1. test_ministral_3b_cos_sin_match — end-to-end parity (128 positions)
2. test_bug_a_hasattr_on_dict — regression test for dict key access
3. test_bug_b_rope_theta_fallback — regression test for theta resolution
4. test_bug_c_mscale_override — regression test for explicit mscale
5. test_mscale_fallback_when_absent — tests .get("mscale", 0) fallback path
6. test_bug_d_inv_freq_no_double_inversion — regression test for NTK scaling
7. test_full_cache_length — parity at 2048 positions
8. test_mapping_isinstance_with_frozen_dict — validates Mapping check with MappingProxyType

Impact

• Fixes ALL models using YaRN RoPE (beta_fast/beta_slow in rope_scaling)
• Verified: cos/sin caches match HF transformers reference (atol=1e-5)
• Verified: Ministral-3-3B generates correct output ("The capital of France is Paris.")

Files Changed

• src/python/py/models/builders/base.py — 4 bug fixes + Mapping import + mscale docs
• test/python/test_yarn_rope_parity.py — 8 new parity tests (new file)

[Copilot]

Pull request overview

Fixes YaRN RoPE configuration resolution in the Python ModelBuilder to prevent incorrect rotary cos/sin cache generation (which can produce unusable outputs for YaRN-based models).

Changes:

• Fixes original_max_position_embeddings detection when rope_scaling is stored as a dict-like object.
• Adds rope_theta fallback to read from rope_scaling when not present as a top-level config field.
• Respects explicit YaRN mscale from config and corrects NTK rescaling math to avoid double-inversion.