reproducible-github-issues

# Reproducible GitHub Issues Use this workflow to turn a failure into a concise, actionable MLX-VLM issue. Do not open a GitHub issue unless the user explicitly asks; otherwise produce issue-ready Markdown. ## Required Information Collect or infer: - MLX-VLM version or git commit. - Install method: PyPI, editable checkout, branch, or wheel. - Python version, OS version, machine/chip, and whether MLX Metal or MLX CUDA is in use. - Exact model ID or local path. - Whether the model is from Hugging Face cache, a local conversion, or a custom checkpoint. - Exact `uv run` CLI command or server startup command. - Exact request body for server issues. - Input media facts: image dimensions, audio duration/sample rate, video duration/frame count, and whether the input can be shared. - Expected behavior, actual behavior, and full error/traceback. ## Collect the Environment Automatically Instead of hand-filling versions, run and paste the output into the Environment section: ```bash uv run python - <<'PY' import platform, mlx.core as mx try: import mlx_vlm v = getattr(mlx_vlm, "__version__", "unknown") except Exception as e: v = f"import failed: {e}" print("mlx-vlm:", v) print("mlx:", mx.__version__, "| default device:", mx.default_device()) print("python:", platform.python_version(), "| platform:", platform.platform()) PY ``` ## Repro Minimization 1. Reduce to the smallest command or request that still fails. 2. Remove private paths, tokens, and unrelated environment variables. 3. Prefer `curl` over client SDKs for server repros. 4. Prefer one image/audio/video file before multi-input repros. 5. Use small public media or synthetic inputs when possible. 6. State whether the bug reproduces with a public model or only a private/local checkpoint. ## Issue Template ````markdown ### Summary <One sentence describing the failure.> ### Environment - MLX-VLM: - Python: - OS: - Hardware: - Install method: ### Model - Model: - Source: <HF cache | local path | converted checkpoint> - Trust remote code: <yes/no> ### Reproduction ```bash uv run mlx_vlm.generate <args> ``` For server issues: ```bash uv run mlx_vlm.server <args> ``` ```bash <curl request> ``` ### Expected Behavior <What should have happened.> ### Actual Behavior <What happened instead.> ### Logs / Traceback ```text <trimmed traceback or relevant logs> ``` ### Inputs <Describe attached or shareable inputs. Include dimensions/duration when relevant.> ```` ## Classification - CLI inference: use `Skill("mlx-vlm-skills:cli-inference")` if a repro command is still missing. - Server inference: use `Skill("mlx-vlm-skills:server-inference")` if a minimal request is still missing. - Model-specific failures: include `config.json` `model_type`, processor class, and whether the family has a README in `mlx_vlm/models/`. ## Quality Bar The issue is ready when a maintainer can run one command or one server command plus one request and see the same failure without asking for basic environment or model details.