harmonia

# Harmonia — ML Dependency Harmony Harmonia detects GPU, CUDA, driver, OS, Python, and installed ML packages — then reports exactly what's compatible with what. Zero dependencies, works offline. ## When To Use This Skill - User asks to **set up a PyTorch or ML environment** - User hits a **dependency error** with torch, transformers, torchaudio, torchvision, accelerate, or CUDA - User asks **"what version of X works with Y"** for ML packages - User asks to **check their GPU, CUDA, or driver setup** - User says something like "my torch is broken", "CUDA error", "version mismatch", "which torch for my Python" - User is installing **local models via Ollama** or setting up training ## Instructions ### Step 1: Install harmonia (if not already installed) ```bash pip install harmonia-ml ``` ### Step 2: Choose the right command based on the user's need **Full environment scan** — use when diagnosing issues: ```bash harmonia check ``` This scans OS, Python, GPU, CUDA driver chain, torch, transformers, and known conflicts all at once. **Deep system diagnostics** — use when the user asks specifically about GPU, CUDA, or driver: ```bash harmonia doctor ``` Shows GPU model, VRAM, driver version, CUDA (nvidia-smi vs nvcc vs torch), glibc, virtualenv status. **Suggest compatible versions** — use when the user wants to know what works together: ```bash # What works with a specific torch version? harmonia suggest torch==2.5.1 # What works with a specific transformers version? harmonia suggest transformers==4.44.2 # Best stack for specific Python + CUDA? harmonia suggest transformers --python 3.11 --cuda 12.1 ``` **Show compatibility matrix** — use when the user wants to see all options: ```bash harmonia matrix pytorch harmonia matrix transformers ``` **List known conflicts** — use when the user hit a specific error: ```bash harmonia conflicts ``` Shows known bug patterns with exact error messages and fixes. **JSON output** — use for programmatic processing: ```bash harmonia check --json ``` ### Step 3: Interpret the output for the user - Lines starting with `❌` are **errors** that must be fixed - Lines starting with `⚠️` are **warnings** worth noting - Lines starting with `✅` mean everything is fine - The `📦 Recommended compatible set` section gives the exact versions to install - The `Install command` at the bottom can be copied and run directly ### Step 4: Help the user fix issues When harmonia reports errors, help the user fix them by running the suggested commands. Common fixes: - **Wrong companion version**: `pip install torchaudio==2.5.1` (use the version harmonia suggests) - **CUDA mismatch**: Install torch with the correct CUDA index URL from the recommendation - **torch too old for transformers**: `pip install torch>=2.4.0` - **No virtualenv**: `python -m venv .venv && source .venv/bin/activate` ## Rules - Always run `harmonia check` FIRST when a user reports any ML dependency issue — do not guess - Always show the full output to the user — do not summarize away important details - If harmonia is not installed, install it with `pip install harmonia-ml` before running commands - Do NOT try to manually diagnose version compatibility — let harmonia do it - When harmonia suggests a fix, offer to run the fix command for the user - If the user asks about versions not in harmonia's database, say so and suggest checking the official docs ## Constraints - This skill only checks compatibility — it does not install or modify packages unless the user asks - harmonia works offline with a local database — it does not make API calls - The database covers PyTorch 2.0–2.5 and Transformers 4.24–5.x — very old versions may not be covered