Harmonia

Check PyTorch, Transformers, and CUDA compatibility. Detect GPU, driver mismatches, and version conflicts in ML environments. Use when the user sets up ML/AI tools, installs torch or transformers, hits dependency errors, or asks about compatible versions.

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)

pip install harmonia-ml

Step 2: Choose the right command based on the user's need

Full environment scan — use when diagnosing issues:

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:

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:

# 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:

harmonia matrix pytorch
harmonia matrix transformers

List known conflicts — use when the user hit a specific error:

harmonia conflicts

Shows known bug patterns with exact error messages and fixes.

JSON output — use for programmatic processing:

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