rigsolve

Finds torch, CUDA, and native-extension combinations supported by sourced evidence — and explains every constraint.

ImportError: libcudart.so.11.0: cannot open shared object file: No such file or directory

$ rigsolve check
[FAIL] torch was built for CUDA 12.4, but flash-attn expects CUDA 11
  This commonly surfaces as a missing libcudart.so.11 error.
  fix: re-resolve torch and the extension on one CUDA line

rigsolve inspects a broken environment without importing torch, applies a sourced compatibility matrix, and emits an ordered repair or install plan. It does not install anything unless you add --execute. Executed plans run isolated import and GPU checks after installation by default.

Why this exists

Python package resolvers understand requirements and wheel tags. GPU environments add compatibility axes that are often outside package metadata: the NVIDIA driver floor, CUDA runtime line, GPU architecture, the torch build an extension targets, C++ ABI mode, and sometimes glibc. A perfectly valid pip install can therefore end in a loader error, an undefined symbol, or a wheel with no kernel for the installed GPU.

rigsolve models those axes directly and keeps the evidence attached:

flowchart LR
  A["machine profile\ndriver · GPU · Python · glibc"] --> S["constraint solver"]
  M["compatibility matrix\nfacts · provenance · evidence"] --> S
  W["requested packages and pins"] --> S
  S --> P["reviewable install plan"]
  S --> E["cited conflict explanation"]

The name is literal: a rig is the workstation, server, container, or future target; solve is the constraint problem that connects it to compatible artifacts.

The architecture guide traces detection, matrix validation, constraint search, diagnosis, and plan emission.

Install

rigsolve requires Python 3.10 or newer. The supported target data is currently focused on Linux x86_64 and NVIDIA CUDA stacks. Install the current release from PyPI:

python -m pip install rigsolve

For development, clone the repository and install the contributor tools:

git clone https://github.com/satwiksps/rigsolve.git
cd rigsolve
python -m pip install -e ".[dev]"

Website

The project landing site lives in site/. It uses Next.js, TypeScript, and Tailwind CSS. Run it locally with cd site, npm ci, and npm run dev. For Vercel, import this repository, set the project Root Directory to site, and keep the auto-detected Next.js build settings. See site/README.md for website-specific development and deployment notes.

Quick start

Inspect the current machine. Detection tolerates missing nvidia-smi, missing CUDA toolkit, and missing or broken torch installations:

rigsolve detect
rigsolve doctor

Ask for a plan for a real or hypothetical target:

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

With the bundled seed, that currently emits a reviewable shell plan like this:

# 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
# WARNING: flash-attn's wheel filename does not establish GPU kernel coverage for sm_89
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'

For a hypothetical target, the result stays plan-only. On the detected machine, --execute installs the plan and immediately runs the available isolated import and GPU probes:

rigsolve solve --want torch --execute

Use --skip-verify only when you intentionally want installation without the automatic post-install checks.

Explain whether a set of pins can coexist:

rigsolve why 'flash-attn==2.8.3' \
  --target 'RTX 4090,driver=580.65,python=3.12,linux'
# A solution exists (evidence: metadata-backed): torch==2.9.0, flash-attn==2.8.3

Diagnose first and request a minimal-change repair plan second:

rigsolve check
rigsolve check --fix

Commands

Use rigsolve COMMAND --help for every option. The complete reference is in the CLI documentation.

Evidence labels

Evidence labels describe how a package combination was checked; they are not product-readiness scores.

The bundled matrix starts from upstream package and build metadata. When you use --execute, rigsolve verifies the resulting local environment instead of pretending that one recorded GPU test applies to every machine. Numeric levels 0 through 3 remain in TOML and JSON for stable automation. See the trust model and matrix schema.

The current seed mentions artifact or coupling facts for torch, torchvision, torchaudio, flash-attn, xformers, bitsandbytes, triton, vLLM, transformers, and flashinfer-python. Its audited official torch build facts record the C++ ABI values supported by the encoded release/index pairs. That list is not a promise of complete version, platform, or solve coverage.

How it relates to pip, uv, and conda

Privacy and safety

• Detection and diagnosis run locally. There is no telemetry.
• Package smoke tests run in child Python processes so a crashing extension does not take down the diagnostic process.
• verify --contribute writes rigsolve-verification.json locally and uploads nothing. Review the file before attaching it to an issue.
• matrix update is the normal command that contacts the network. It fetches the configured URL, validates the whole payload, and replaces the cache atomically.
• Harvesting is an opt-in contributor workflow and contacts GitHub, PyPI, PyTorch, and NVIDIA sources.
• Generated plans may contain third-party URLs and shell commands. Review them before running; --execute is explicit for this reason.

You found the next broken combination we need

The bundled matrix starts with one known_broken entry: a narrowly sourced flash-attn 2.8.3.post1 filename mismatch. Real users will find the failures upstream metadata cannot reveal, and those are uniquely valuable.

If a CUDA combination cost you three hours, spend two minutes making sure it costs nobody else three hours:

1. Open a known-broken report.
2. Include the exact package versions and rigsolve detect --json output, after checking it for anything you do not want to share.
3. Include the complete error and a source or reproducible procedure.
4. If you have a fixed environment, run rigsolve verify --contribute, review the local JSON, and attach it.

For a matrix PR, start with the known-broken template and follow the contribution guide. Negative facts require a useful workaround and auditable provenance.

Current scope

rigsolve 0.1.1 includes the CLI, offline detector, constraint solver, matrix validation, pip/uv/TOML/Docker/JSON/Colab emitters, diagnostics, isolated verification, and source harvesters. Target data is currently focused on Linux x86_64 and NVIDIA CUDA stacks. Conda output is not included.

The daily harvester is read-only with respect to the repository. When upstream facts change, it uploads a validated candidate matrix and deterministic diff as a short-lived workflow artifact; it never creates a branch, pull request, commit, or merge. See the harvesting guide.

Contributing and governance

Bug reports, source citations, detection fixtures, matrix facts, and verification results are welcome. Start with CONTRIBUTING.md and read the Code of Conduct.

Security issues should follow SECURITY.md, not a public compatibility report.

License

Apache License 2.0