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.

$ rigsolve check
[FAIL] torch was built for CUDA 12.4, but flash-attn expects CUDA 11
  fix: re-resolve torch and the extension on one CUDA line

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'

Planning is read-only. 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

Dimension	Examples
Host	Linux platform, architecture, glibc, Python version and ABI
NVIDIA stack	GPU compute capability, driver floor, CUDA runtime, local toolkit
PyTorch	Release, CUDA build, package index, C++11 ABI
Native extensions	Python and platform tags, torch coupling, CUDA line, wheel architecture
Policy and evidence	Known-broken combinations, source-build permission, evidence depth

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

Command	Purpose
rigsolve detect	Profile GPU, driver, toolkit, Python, platform, and installed packages
rigsolve solve	Resolve a compatible stack and render an install plan
rigsolve check	Diagnose known problems in an installed environment
rigsolve why	Explain a solution or a reduced compatibility conflict
rigsolve verify	Run crash-isolated imports and available GPU probes
rigsolve matrix	Inspect, validate, update, or extend compatibility evidence
rigsolve doctor	Check rigsolve, its matrix, and available NVIDIA tooling

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

Evidence model

Level	What it establishes
Metadata-backed	An artifact or documented build axis was published upstream
Install-tested	The exact artifact installed in a recorded environment
Import-tested	The package imported and available build metadata was recorded
GPU-tested	A minimal real kernel ran on the recorded GPU architecture

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, verification, and matrix inspection are offline by default.
• 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 is an alpha project. Its current matrix is intentionally narrower than the full GPU package ecosystem: it prioritizes 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

• CLI reference
• Architecture
• Trust and evidence model
• Compatibility matrix schema
• Evidence harvesting
• 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.