fix: voxtralprocessor broken

[NanoCode012]

Description

Due to the Mistral3Processor addition, it broke Voxtral loading. This PR fixes that.

The patch also fixes the potential bug when we upgrade to transformers v5. https://github.com/huggingface/transformers/pull/41633/files

Motivation and Context

How has this been tested?

Manual runs across Magistral, Voxtral, Mistral3 to ensure running normally.

Screenshots (if appropriate)

Types of changes

Social Handles (Optional)

Summary by CodeRabbit

• New Features

  • Added VoxtralProcessor support for Voxtral model configurations.

• Documentation

  • Updated example configurations to use VoxtralProcessor.
  • Updated multimodal documentation with VoxtralProcessor configuration details.

[coderabbitai]

📝 Walkthrough

Walkthrough

The pull request adds VoxtralProcessor support to the axolotl framework. Changes include updating documentation and configuration examples to specify VoxtralProcessor, implementing early-return logic in the processor loader for VoxtralProcessor instantiation, and adding a comment to the Mistral3Processor class regarding planned removal.

Changes

Cohort / File(s)	Summary
Documentation and Configuration Updates docs/multimodal.qmd, examples/voxtral/voxtral-mini-audio-qlora.yml	Added processor_type configuration example in documentation and updated configuration to use VoxtralProcessor instead of AutoProcessor
Processor Loading Implementation src/axolotl/loaders/processor.py	Imported VoxtralProcessor and added conditional early-return logic to instantiate VoxtralProcessor directly; added function-local tokenizer patching for Mistral common tokenization; removed unused processor_kwargs dictionary
Mistral Processor Utilities src/axolotl/utils/mistral/mistral3_processor.py	Added comment noting planned removal in transformers V5

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Areas requiring attention:
  • Verify that VoxtralProcessor.from_pretrained() properly handles the cfg.processor_config parameter and returns the expected processor type
  • Confirm the early-return path for VoxtralProcessor doesn't bypass necessary tokenizer initialization that other processor types depend on
  • Validate that the conditional tokenizer patching logic (_patch_mistralcommontokenizer) is correctly applied when needed

Possibly related PRs

• models.py -> loaders/ module refactor #2680: Introduced the refactor to the processor loading path that this PR extends, directly modifying the same loaders.processor module with conditional processor instantiation logic.

Suggested reviewers

• winglian
• SalmanMohammadi

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix: voxtralprocessor broken' directly addresses the main change - fixing a broken Voxtral processor loading that was caused by Mistral3Processor changes, as evidenced by the VoxtralProcessor imports and early returns in the processor loader.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/voxtral

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

📖 Documentation Preview: https://6912c1bad2f283313408d456--resonant-treacle-0fd729.netlify.app

Deployed on Netlify from commit 766b69f

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between dd78f2e and 766b69f.

📒 Files selected for processing (4)

• docs/multimodal.qmd (1 hunks)
• examples/voxtral/voxtral-mini-audio-qlora.yml (1 hunks)
• src/axolotl/loaders/processor.py (1 hunks)
• src/axolotl/utils/mistral/mistral3_processor.py (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-08-07T01:12:27.280Z

Learnt from: winglian
Repo: axolotl-ai-cloud/axolotl PR: 3019
File: src/axolotl/core/trainers/base.py:610-669
Timestamp: 2025-08-07T01:12:27.280Z
Learning: When a method has a TODO comment indicating it's a temporary override from upstream (like "TODO(wing): remove once https://github.com/huggingface/transformers/pull/39866/files is merged"), extensive refactoring suggestions may not be worthwhile since the code will be removed once the upstream changes are available.

Applied to files:

• src/axolotl/utils/mistral/mistral3_processor.py

🧬 Code graph analysis (1)

src/axolotl/loaders/processor.py (1)

src/axolotl/utils/mistral/mistral_tokenizer.py (1)

• HFMistralTokenizer (14-220)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)

• GitHub Check: PyTest (3.11, 2.9.0)
• GitHub Check: PyTest from Source Dist (3.11, 2.8.0)
• GitHub Check: PyTest from Source Dist (3.11, 2.9.0)
• GitHub Check: PyTest (3.11, 2.8.0)
• GitHub Check: PyTest from Source Dist (3.11, 2.7.1)
• GitHub Check: PyTest (3.11, 2.7.1)
• GitHub Check: preview

🔇 Additional comments (5)

examples/voxtral/voxtral-mini-audio-qlora.yml (1)

2-2: LGTM! Explicit processor specification for Voxtral.

This change correctly specifies VoxtralProcessor to ensure proper loading of the Voxtral model, aligning with the corresponding loader logic changes.

src/axolotl/utils/mistral/mistral3_processor.py (1)

33-33: LGTM! Helpful context about temporary code.

The comment appropriately documents that this processor is temporary and will be removed once transformers V5 changes are available upstream.

Based on learnings.

src/axolotl/loaders/processor.py (2)

49-53: LGTM! Cleaned up unused processor_kwargs.

The removal of the unused processor_kwargs simplifies the code while maintaining the necessary tokenizer and trust_remote_code parameters.

---

21-34: No issues found with the monkey patch implementation.

The global replacement of MistralCommonTokenizer with HFMistralTokenizer is safe because HFMistralTokenizer is a permanent subclass that maintains the parent interface. All code throughout the codebase either:

• Imports dynamically after the patch opportunity, or
• Expects HFMistralTokenizer explicitly (e.g., Mistral3Processor)

No strict type identity checks exist, and the Liskov substitution principle is preserved. The patch is properly scoped within load_processor() and only applied when cfg.tokenizer_use_mistral_common is enabled.

docs/multimodal.qmd (1)

127-128: LGTM! Documentation updated to reflect VoxtralProcessor requirement.

The documentation correctly shows users how to configure Voxtral models with the explicit processor_type specification, consistent with the code changes and example configuration.

[codecov]

Codecov Report

❌ Patch coverage is 0% with 8 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/axolotl/loaders/processor.py	0.00%	8 Missing ⚠️

📢 Thoughts on this report? Let us know!