Metadata-Version: 2.5
Name: rigsolve
Version: 1.0.0
Summary: Resolve torch, CUDA, and native extension compatibility from sourced evidence.
Project-URL: Homepage, https://github.com/satwiksps/rigsolve
Project-URL: Documentation, https://rigsolve.readthedocs.io/
Project-URL: Issues, https://github.com/satwiksps/rigsolve/issues
Project-URL: Source, https://github.com/satwiksps/rigsolve
Author: rigsolve contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: cuda,dependency-resolution,developer-tools,flash-attention,gpu,mlops,pytorch
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: packaging>=24.2
Requires-Dist: tomli>=2.2; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: build==1.5.0; extra == 'dev'
Requires-Dist: mypy>=1.14; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: tomli>=2.2; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/satwiksps/rigsolve/main/docs/assets/rigsolve-banner.svg" alt="rigsolve turns a GPU target into a compatible torch, CUDA, and extension plan." width="100%">
</p>

# rigsolve

[![CI](https://github.com/satwiksps/rigsolve/actions/workflows/ci.yml/badge.svg)](https://github.com/satwiksps/rigsolve/actions/workflows/ci.yml)
[![Codecov](https://codecov.io/gh/satwiksps/rigsolve/graph/badge.svg)](https://codecov.io/gh/satwiksps/rigsolve)
[![Documentation](https://readthedocs.org/projects/rigsolve/badge/?version=latest)](https://rigsolve.readthedocs.io/en/latest/)
[![PyPI](https://img.shields.io/pypi/v/rigsolve.svg)](https://pypi.org/project/rigsolve/)
[![Python](https://img.shields.io/pypi/pyversions/rigsolve.svg)](https://pypi.org/project/rigsolve/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

**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

```bash
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

```bash
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

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

Selected plan lines:

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

```bash
rigsolve solve --want torch --execute
```

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

### Diagnose and explain failures

```bash
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:

```bash
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](docs/cli.md) 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:

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

Read the [trust model](docs/trust-model.md), [matrix schema](docs/matrix-schema.md), and [harvesting guide](docs/harvesting.md) 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](https://rigsolve.readthedocs.io/en/latest/)
- [Installation](https://rigsolve.readthedocs.io/en/latest/getting-started/installation/)
- [Quickstart](https://rigsolve.readthedocs.io/en/latest/getting-started/quickstart/)
- [CLI reference](https://rigsolve.readthedocs.io/en/latest/cli/)
- [Python API](https://rigsolve.readthedocs.io/en/latest/reference/python-api/)
- [Trust and evidence model](https://rigsolve.readthedocs.io/en/latest/trust-model/)
- [Contribution guide](CONTRIBUTING.md)
- [Security policy](SECURITY.md)

## Contributing

Compatibility reports are most useful when they include an exact artifact, environment, command, result, and reproducible source. Start with the [contribution guide](CONTRIBUTING.md), submit verification evidence through the [verification report form](https://github.com/satwiksps/rigsolve/issues/new?template=verification.yml), and report vulnerabilities privately as described in the [security policy](SECURITY.md).

## License

Licensed under the [Apache License 2.0](LICENSE).
