---

name: maestro description: "Use Maestro for vision-language model fine-tuning, dataset validation, model-specific CLI/API workflows, checkpoints, inference, and troubleshooting." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

Maestro repo skill

Use this skill when a task involves Maestro, the Python package for streamlined vision-language model (VLM) fine-tuning with Florence-2, PaliGemma 2, and Qwen2.5-VL.

Read first

• Repository provenance: read before deciding whether this skill matches a current checkout or package version.
• Installation and CLI: install commands, package extras, CLI command map, and environment variables.
• Root troubleshooting: package-wide import, optional dependency, backend, CLI warning, and training-output issues.
• check_maestro_environment.py: safe installed-package import/version/backend probe.
• maestro_cli_probe.py: safe CLI route probe that does not train or download models.

Choose a route

User task	Open
Validate JSONL/COCO data, parse Roboflow identifiers, create DataLoaders, select metrics, or handle device/reproducibility helpers	datasets-and-metrics
Build Florence-2 train commands/API calls, load or save Florence checkpoints, run Florence inference, or format Florence <OD> detections	florence-2
Fine-tune or infer with PaliGemma 2 for JSON extraction, VQA, OCR-style prompts, LoRA/QLoRA/freeze choices, or PaliGemma checkpoints	paligemma-2
Fine-tune or infer with Qwen2.5-VL, build Qwen chat conversations, control pixel bounds, or format Qwen COCO detection JSON	qwen-2-5-vl

Install decision points

Maestro's model extras can pull different optional dependencies. Prefer one environment per model family for real training, especially when mixing QLoRA, bitsandbytes, flash-attn, or experimental Qwen support.

pip install maestro
pip install "maestro[florence_2]"
pip install "maestro[paligemma_2]"
pip install "maestro[qwen_2_5_vl]"

For safe package inspection, import checks, dataset validation, formatter checks, and CLI help do not require model downloads. Full fine-tuning and inference may require Hugging Face model access, Roboflow credentials, GPU memory, and large downloads.

Minimal import and CLI checks

python - <<'PY'
from importlib.metadata import version
import maestro
print(version("maestro"))
PY

maestro --help
maestro version
maestro info

Or use bundled diagnostics from this skill tree:

python scripts/check_maestro_environment.py --models all --json
python scripts/maestro_cli_probe.py --include-model-help --json

Common cross-skill rules

• Validate dataset shape before building a training command. Maestro's common loader expects train, valid, and test splits for training.
• Use local dataset paths for reproducible runs. Roboflow identifiers require ROBOFLOW_API_KEY and may download data.
• Use device="auto" unless the user has a specific visible backend requirement.
• Use model-specific formatter callbacks for COCO object-detection datasets. Florence-2 and Qwen2.5-VL expose formatter helpers; PaliGemma 2 in this Maestro version does not expose a dedicated detection formatter API.
• CLI options use underscores in this repo (--batch_size, --optimization_strategy, --max_new_tokens). Some bundled config helpers use hyphenated helper flags but emit Maestro-compatible underscore CLI flags.
• Do not treat safe import/formatter checks as proof that a full GPU fine-tuning run, model download, or Roboflow download will succeed.