# RANGE CUDA preview

This preview publishes the **retained Phase60 CUDA pipeline**, previously installed
and measured in Phase61. Its CUDA binary and private exact CPU fallback are
byte-identical to that installation. The current integration changes package imports
and connects the pipeline to the maintained RANGE API.

**Public Python package release is coming soon.** These are preview wheels, not a
PyPI release. The hosted app runs on CPU; downloading its CUDA preview gives you a
separate local GPU execution path.

## Install the preview

Use **64-bit Windows, CPython 3.10, and an NVIDIA sm75 GPU** with a compatible CUDA
12 driver/runtime. The original qualification used an RTX 2070 Max-Q. Other GPU
architectures and Linux CUDA execution are not supported by this preview. CPU-only
users can install the CPU wheel without the CUDA companion.

Download both matching files from the Space's `downloads` folder:

- [RANGE CPU wheel](https://huggingface.co/spaces/Brianferrell787/range/resolve/main/downloads/range_curate-0.1.0a3-cp310-cp310-win_amd64.whl)
- [RANGE CUDA companion](https://huggingface.co/spaces/Brianferrell787/range/resolve/main/downloads/range_curate_cuda-0.1.0a3-cp310-cp310-win_amd64.whl)

From the folder containing both downloads, create a Python 3.10 environment and
install both files together:

```powershell
py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install .\range_curate-0.1.0a3-cp310-cp310-win_amd64.whl .\range_curate_cuda-0.1.0a3-cp310-cp310-win_amd64.whl
```

Pip installs the companion's pinned CuPy, NumPy, PyArrow and CUDA-pathfinder
dependencies. No RANGE Rust or CUDA compilation is needed to install these wheels.
A compatible NVIDIA driver/runtime is still required. The port was checked with
existing installed dependencies; a fresh dependency download on another machine
has not been qualified.

## Run bulk Arrow screening

```python
from datetime import datetime, timezone
import pyarrow as pa
from range_curate.examples.general_economy import RelevanceEngine

engine = RelevanceEngine(backend="cuda", workers=10)
data = pa.table({
    "text": ["The Federal Reserve cut interest rates."],
    "timestamp": pa.array(
        [datetime(2025, 1, 15, tzinfo=timezone.utc)],
        type=pa.timestamp("us", tz="UTC"),
    ),
})
facts = engine.screen_arrow(data).to_pyarrow()
```

CUDA applies to **bulk `screen_arrow`**. Rich predictions, explanations, list
screening, and the domain-neutral `CurationEngine` continue to run on CPU. A tiny
example demonstrates the API, not GPU throughput. The CUDA input is a materialized
Arrow Table or RecordBatch with non-null text and timezone-aware timestamps.

You can pass a supported custom `Taxonomy` using `taxonomy=...`. The pipeline uses
exact CPU fallback for unsupported rules and rows that exceed its GPU bounds.
Missing or incompatible CUDA raises a clear error; it does not silently substitute
a CPU run for a failed GPU runtime. Choose `backend="cpu"` explicitly for CPU use.

## What the speed record means

Phase60 measured **1,833,059 articles/s** and the Phase61 installation measured
**1,809,133 articles/s** on their recorded General Economy workload. This preview
contains that retained pipeline. Six finite installed correctness checks passed
for the current API port. **No performance experiment was rerun**, at the
maintainer's request; this is not a new timing claim for the renamed wheel.

The kernel SHA-256 is
`dd943d9adac702e41c2bb0a2b58f78698498edd8a3dfab16cf9d224c8c6a83fa`.
The private CPU fallback SHA-256 is
`8b1dddd69ccc13380cced1f2df4977f2ecb750805c9d127b0c8046fef812563f`.

See [the integration record](INTEGRATION_RECORD.json), [source provenance](provenance.json),
and [benchmark conditions](https://huggingface.co/spaces/Brianferrell787/range/blob/main/BENCHMARKS.md). The source tree includes the retained
orchestration and CUDA kernels. `build_wheel.py` assembles the companion from the
hash-bound Phase61 reference wheel and the matching current CPU wheel; it preserves
third-party notices and records all packaged file hashes.