feat: MLX provider family — mlx_image + mlx_video + mlx_caption (shared env)

[ziyu4huang]

Bridges the sibling mlx-movie-director Apple-Silicon runtime into OpenMontage as the $0, offline, MPS-native option where existing local tools need CUDA. Three providers, one shared env module.

The trio

Provider	Capability	Bridges	Fills
mlx_image (graphics)	image_generation	run.py image t2i/i2i/controlnet/faceswap/LoRA	the ControlNet/i2i/LoRA/faceswap surface no cloud provider fully covers
mlx_video (video)	video_generation	run.py video generate/t2i2v (LTX-2.3)	the Apple-Silicon MPS-native i2v/t2v path (wan/hunyuan/ltx/cogvideo need CUDA)
mlx_caption (analysis)	analysis	run.py caption (Qwen3-VL via LM Studio localhost:1234)	the local LM-Studio VLM path (video_understand is a direct-transformers VLM that downloads+loads a model each run)

Shared env module (tools/_mlx/env.py)

Factors the duplicated _resolve_env() out of mlx_image + mlx_video (the TODO both files carried: “if a third MLX provider appears, factor into tools/_mlx/env.py”). resolve_mlx_env(need_models, need_lm_studio) serves all three; mlx_caption uses need_models=False, need_lm_studio=True (socket-probes localhost:1234 so the menu shows ANALYZE::mlx unavailable when LM Studio isn't running).

Env contract

• MLX_MOVIE_DIRECTOR_DIR — repo root with python/mlx-movie-director/run.py
• MLX_VENV_PYTHON — the MLX venv interpreter (per-machine, not auto-created)
• LM Studio at http://localhost:1234/v1 with a vision model (caption only)

Tests

• All spawn-free (no runtime/LM-Studio dependency in CI): 70 mlx-family tests + 228 broader tests/tools/ pass, 0 regressions.
• mlx_caption: capability surface, env gates (incl. LM-Studio-down → UNAVAILABLE), arg-mapping for all --style/--lang/--model/--api-url combos, output parsing (styles-map + flat-legacy + dict-with-text).
• Auto-discovered by the registry (mlx_caption is the 13th analysis tool; zero selector edits).

Known follow-ups (tracked in the repo's next-goal-md)

• mlx_image doesn't yet expose restore/quality/expansion; mlx_video doesn't expose relay/segment.
• An opt-in live integration smoke test (LM Studio + staged models) is deferred.
• The install-instructions gap (opencv-python/mflux/ltx-2-mlx members not in the mlx repo's requirements.txt) is documented but not yet upstreamed.

[calesthio]

Thank you for this contribution. The MLX provider family is directionally valuable for OpenMontage, especially as a $0 Apple-Silicon-native path for image/video generation and local VLM analysis, and the provider metadata/skill linkage looks generally aligned with the registry model.

I need to request changes because the advertised spawn-free test set is not currently portable: on this Windows/AMD64 review machine, the focused MLX tests fail before merge.

Verification I ran:

python -m py_compile tools/_mlx/env.py tools/analysis/mlx_caption.py tools/graphics/mlx_image.py tools/video/mlx_video.py tests/tools/test_mlx_caption.py tests/tools/test_mlx_image.py tests/tools/test_mlx_video.py
# passed

python -m pytest tests/tools/test_mlx_caption.py tests/tools/test_mlx_image.py tests/tools/test_mlx_video.py -q
# 64 passed, 4 skipped, 2 failed

The failing tests are:

tests/tools/test_mlx_image.py::test_status_available_with_full_env
tests/tools/test_mlx_video.py::test_status_available_with_full_env

Both build a fake complete MLX env and then assert env["ok"] is True, but resolve_mlx_env() correctly rejects non-Apple-Silicon hosts with MLX runs on Apple Silicon only (got AMD64). Please make these tests explicitly mock the platform/architecture when asserting the arm64-available path, or otherwise skip/branch the ok=True assertion on non-arm64 CI while still testing the unavailable path.

I did confirm the registry sees mlx_image, mlx_video, and mlx_caption in their intended capability buckets. I did not find an actionable security issue in the reviewed diff, but the focused test suite needs to be green before merge.

[ziyu4huang]

Thanks for the careful review @calesthio — you're right, the production resolve_mlx_env() arch guard was correct and the two _with_full_env tests weren't portable. Fixed in 491efaf using your first suggested shape.

Change (test-only; tools/_mlx/env.py untouched). Both test_status_available_with_full_env tests now mock the platform to Apple Silicon:

# Mock Apple Silicon so the full available-path (incl. the arch guard in
# resolve_mlx_env) runs on ANY CI host, not just native arm64 reviewers.
monkeypatch.setattr("tools._mlx.env.platform.machine", lambda: "arm64")

…then assert env["ok"] is True, env["arm64"] is True, and get_status() == AVAILABLE directly. The stale if env["arm64"]: skip-guard is removed — with the mock, the available-path runs everywhere. The unavailable-path tests (..._when_env_unset, ..._when_venv_missing) stay honest: they don't force the arch, so they still exercise the ok=False branch on every host.

I went with mocking rather than skipUnless(platform.machine()=="arm64") so the available-path is actually exercised on x86_64 CI, not silently skipped.

Verification. This Mac is arm64, so I couldn't natively reproduce your AMD64 failure — I simulated the review host by rebindng platform.machine process-wide to "AMD64" and re-ran:

# real arm64 host
.venv/bin/python -m pytest tests/tools/test_mlx_image.py tests/tools/test_mlx_video.py tests/tools/test_mlx_caption.py -q
→ 70 passed

# simulated AMD64 review host (platform.machine forced to "AMD64" process-wide)
→ 66 passed, 4 skipped (unrelated caption/LM Studio), 0 failed
→ tests/tools/test_mlx_image.py::test_status_available_with_full_env  PASSED
→ tests/tools/test_mlx_video.py::test_status_available_with_full_env   PASSED

The previously-failing tests are green under the simulated non-arm64 host; the focused suite is clean. CI (ubuntu x86_64, platform.machine()=="x86_64") will hit the same mocked path. Re-requesting your review.