upstream-mlx-vlm-contributing

Prepares and tests upstream mlx-vlm fixes from an editable conda checkout.

1|1|Updated Apr 21, 2025
One-click install
npx skills add https://github.com/jrp2014/check_models --skill upstream-mlx-vlm-contributing-jrp2014
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: upstream-mlx-vlm-contributing
Source: https://github.com/jrp2014/check_models/tree/main/.agents/skills/upstream-mlx-vlm-contributing
Command: npx skills add https://github.com/jrp2014/check_models --skill upstream-mlx-vlm-contributing-jrp2014

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When a check_models harness finding turns out to be a bug in upstream mlx-vlm, this Skill guides turning that finding into a clean, mergeable upstream fix instead of just an issue report, covering code placement, tests, formatting, and PR expectations. ## Core Features & Use Cases - Code Placement Guidance: Directs changes to the right locations in the editable mlx-vlm checkout, including model code under mlx_vlm/models/<model_type>/, processor clean_output hooks, and backward-compatible ModelConfig arguments. - Focused Test Execution: Runs targeted pytest classes in test_models.py and test_processors.py using conda + pip (never uv), then validates the fix on the real checkpoint with a native repro. - Formatting Alignment: Matches upstream's black/isort/autoflake hooks (88-column layout) using the ruff already installed in this repository, without installing extra tools. - Use Case: A check_models run shows a model emitting leftover special tokens; use this Skill to add a clean_output hook in the model's processor, write a TestOutputControlTokens-style test, format the diff to upstream's 88-column standard, and prepare the PR branch. ## Quick Start Turn my confirmed check_models finding about the glm4v processor output into an upstream mlx-vlm fix with tests and a prepared PR branch.

Frequently Asked Questions about upstream-mlx-vlm-contributing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I contribute a fix to upstream mlx-vlm?▼

Work on a branch in the existing editable mlx-vlm checkout located via pip show mlx-vlm. Place model code in mlx_vlm/models/<model_type>/, add focused tests in test_models.py or test_processors.py, format to upstream's 88-column black style, and open a scoped PR against upstream main.

How do I run mlx-vlm tests with conda and pip?▼

Activate the mlx-vlm conda environment, cd into the editable checkout, and run python -m pytest mlx_vlm/tests/test_processors.py -q -k "<ClassName>". This project uses conda plus pip exclusively; never use uv run or uv pip.

Does mlx-vlm use black or ruff for formatting?▼

Upstream mlx-vlm uses black at 88 columns with isort and autoflake pre-commit hooks. This repository's ruff rules are a superset, so write to this repo's standard and verify the 88-column layout with ruff format --isolated --line-length 88 instead of installing black.

Where do processor output fixes go in mlx-vlm?▼

Post-generation cleanup belongs in the processor's optional clean_output hook in processing*.py within the model directory. Special tokens such as answer delimiters are registered there, and both upstream generate() and the harness call this hook.

When should I file an issue instead of an upstream fix?▼

File an issue when the finding is not yet confirmed natively or the change is out of scope for a small opt-in fix. Use the upstream-mlx-vlm-issues skill for issue filing; this skill is only for confirmed findings that become code changes.