rigsolve

rigsolve is an offline-first compatibility resolver for PyTorch, CUDA, and native GPU extensions. It profiles a machine without importing torch, evaluates the relevant compatibility constraints together, and produces a sourced install or repair plan.

Why rigsolve

GPU package failures rarely come from one version mismatch. A working environment can depend on the NVIDIA driver, CUDA runtime, local toolkit, GPU architecture, Python ABI, Linux platform, glibc, torch build, extension build, and C++ ABI agreeing at the same time.

rigsolve handles those dimensions as one deterministic resolution problem. Its answers come from a versioned compatibility matrix in which every fact carries provenance and an explicit evidence level. Missing information remains unknown rather than being treated as proof of compatibility.

Install

python -m pip install rigsolve

Python 3.10 or newer is required. The current bundled data focuses on Linux x86_64 systems with NVIDIA CUDA GPUs.

Quick start

Inspect the current machine

rigsolve detect
rigsolve doctor

Detection reads command output, files, and installed distribution metadata. It does not import torch, so it can still inspect an environment whose native packages no longer load.

Resolve a compatible stack

rigsolve solve \
  --want 'flash-attn==2.8.3' \
  --target 'RTX 4090,driver=580.65,python=3.12,linux'

Selected plan lines:

# Generated by rigsolve; review before running.
# Matrix 2026.08.15 (1e066bd53f01); evidence: metadata-backed.
# WARNING: selected versions are metadata-backed; use --execute to install and verify them on this machine
python -m pip install --index-url https://download.pytorch.org/whl/cu126 torch==2.9.0
python -m pip install 'https://github.com/Dao-AILab/flash-attention/releases/download/v2.8.3/flash_attn-2.8.3%2Bcu12torch2.9cxx11abiTRUE-cp312-cp312-linux_x86_64.whl#sha256=4e2f9e39313266b1544b68138b15b91ee6221eccf14f7902b7c6620351340810'

Resolution does not install packages. To install the selected packages on the detected machine and run the available verification probes, opt in explicitly:

rigsolve solve --want torch --execute

Hypothetical --target and --python plans cannot be executed against the current host.

Diagnose and explain failures

rigsolve check
rigsolve check --fix

rigsolve why 'flash-attn==2.8.3' \
  --target 'RTX 4090,driver=580.65,python=3.12,linux'

check --fix prints a minimal-change repair plan but does not install it. When a request cannot be satisfied, why reduces the active constraints to a smaller conflict and retains citations from the facts that produced it.

What gets checked

Reproducible outputs

The same resolved plan can be rendered as reviewable pip commands, a uv project snippet, a deterministic TOML lockfile, a Dockerfile, JSON, or a Colab bootstrap:

rigsolve solve --want torch --output docker \
  --target 'A100,driver=570.00,python=3.12,linux'

rigsolve solve --want torch --output toml \
  --write-lockfile rigsolve.toml

Plans record the matrix version and SHA-256 digest so the evidence snapshot can be identified later.

Commands

See the complete CLI reference for options, output behavior, and exit codes.

Evidence model

Evidence depth is not a probability or a universal compatibility claim. For example, a GPU-tested result on one architecture does not establish support for every GPU.

The bundled matrix currently contains 114 sourced facts, including one scoped known_broken entry for the flash-attn 2.8.3.post1 filename mismatch. Inspect the exact contents locally:

rigsolve matrix stats
rigsolve matrix show --package flash-attn

Read the trust model, matrix schema, and harvesting guide for the data contract and review process.

Safety and privacy

• Detection, solving, diagnosis, and matrix inspection are offline by default.
• Verification runs installed package code without a network sandbox.
• No telemetry or automatic report upload is included.
• Native imports run in child processes so a loader abort does not crash the diagnostic parent.
• verify --contribute writes a local JSON file for review and uploads nothing.
• Remote matrix updates validate the complete payload before atomically replacing the cache.
• Package installation requires the explicit solve --execute option.

Current scope

rigsolve 1.0 has a deliberately narrow support scope: Linux x86_64, NVIDIA CUDA, PyTorch, and selected native extensions. A clean check means that no applicable known violation was found; it does not prove that an unrecorded combination works.

Documentation

• Complete documentation
• Installation
• Quickstart
• CLI reference
• Python API
• Trust and evidence model
• Contribution guide
• Security policy

Contributing

Compatibility reports are most useful when they include an exact artifact, environment, command, result, and reproducible source. Start with the contribution guide, submit verification evidence through the verification report form, and report vulnerabilities privately as described in the security policy.

License

Licensed under the Apache License 2.0.