[ToluClassics]

Summary

This PR establishes a trustworthy inference baseline for MLX Transformers 0.3.0 on Apple silicon.

It adds bounded CI and tests, makes checkpoint loading strict and offline-capable, replaces duplicated/unbounded generation loops with a finite batched contract, fixes compatibility defects exposed by real checkpoints and the minimum dependency matrix, and makes package/release metadata match the tested support contract.

Why

The existing package could silently retain randomly initialized parameters when checkpoint keys did not match, could not reliably load cached Hub models offline, and had broken or unbounded generation behavior across several causal families. The default test suite could initiate large checkpoint downloads without an explicit resource gate.

Packaging also declared MIT despite an Apache-2.0 license, reused an already-published version, installed UI/test dependencies as core requirements, and rebuilt unverified artifacts during publication.

What changed

• add Apple-silicon CI with pinned actions, Ruff, offline tests, package build, wheel-version verification, Twine checks, and retained release artifacts
• gate Hub integration tests behind MLX_TRANSFORMERS_RUN_HUB_TESTS=1
• implement strict safetensors resolution/loading with offline, revision, token, shard-index, tied-weight, derived-buffer, and dtype handling
• add shared finite max_new_tokens generation with batching, mixed padding, EOS/pad handling, cache updates, and caller-input immutability
• migrate Llama, Phi, Phi-3, Qwen3, Qwen3-VL, Gemma 3, OpenELM, Persimmon, and Fuyu generation
• fix dtype-safe attention masks and compatibility issues in OpenELM, Persimmon, Fuyu, Gemma 3, M2M100, BERT task heads, RoBERTa, and XLM-R
• make pyproject.toml the canonical package definition for version 0.3.0 and Apache-2.0
• split core, tokenizer, vision, example, chat, and test dependencies
• require PyPI publication to reuse a successful main CI artifact for the exact release commit and matching version tag
• add an evidence-backed verified/experimental support contract
• make Fuyu's example safe to inspect without starting a model download
• update examples and contributor documentation to match the tested contract

Validation

Local host: Apple M2 Max, macOS 26.0.

Dependency matrices:

• MLX 0.31.0 + Transformers 4.57.6: 98 tests, 76 passed, 22 gated Hub tests skipped
• MLX 0.32.0 + Transformers 5.14.1: 98 tests, 76 passed, 22 gated Hub tests skipped

Release-candidate gates:

• Ruff lint and format: passed
• pre-commit hooks: passed
• workflow YAML parse: passed
• source distribution and wheel build: passed
• package metadata: version 0.3.0, Apache-2.0, Python >=3.10,<3.14
• Twine checks: passed
• separate clean wheel installation and pip check: passed
• installed-package imports, version, and Metal execution: passed
• CLI example import/help sweep: passed
• Streamlit server startup: passed
• GitGuardian: passed

Real cached-checkpoint checks passed for MiniLM/BERT task heads, Llama 3.2 1B, Phi-2, Phi-3 Mini, Qwen3 0.6B, Gemma 3 1B and 4B multimodal, Qwen3-VL 2B text generation, NLLB 600M, and 4-bit MLX Phi-3.

Support boundaries

• OpenELM, Persimmon, and Fuyu are maintenance-only: bounded compatibility/security fixes remain, while proactive feature-parity and performance work prioritizes active families
• actual RoBERTa, XLM-R, OpenELM, Persimmon, and Fuyu checkpoints were not cached and therefore remain experimental with synthetic coverage
• Qwen3-VL's real image path remains experimental
• Gemma 3 4B multimodal is verified in float32/bfloat16; float16 produced NaNs and is explicitly excluded
• training, Transformers AutoModel registration, PyTorch .bin loading, remote model code, non-Metal execution, and unbounded generation are unsupported
• GitHub reports existing dependency alerts on the default branch; this PR removes stale core pins, while unrelated alert remediation should be handled separately

All required CI checks pass. The PR is ready for review and awaits the repository's required human approval.