Metadata-Version: 2.4
Name: lightrider-huggingface
Version: 0.1.1
Summary: Hugging Face datasets with a provable, reproducible origin, seeded from a named quantum entropy source through Light Rider.
Author: Light Rider
License-Expression: Apache-2.0
Project-URL: Homepage, https://entropy.lightriderinc.com
Project-URL: Documentation, https://entropy.lightriderinc.com/developers
Keywords: huggingface,datasets,quantum,entropy,provenance,reproducibility,quantum-circuits
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: lightrider>=1.6.0
Requires-Dist: huggingface_hub>=0.23
Requires-Dist: datasets>=2.19
Requires-Dist: pyarrow>=14
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"

# lightrider-huggingface

**Hugging Face datasets with a provable, reproducible origin.**

Each dataset is generated from a seed drawn from a named quantum entropy source through
[Light Rider](https://entropy.lightriderinc.com). The seed comes with a signed receipt. Anyone
can check that receipt, confirm the seed came from that draw, and regenerate the dataset exactly.

Two kinds of dataset:

- **Random quantum circuits**, for example 500 circuits for benchmarking.
- **Random evaluation subsets**: N rows sampled from an existing Hugging Face dataset, pinned to
  an exact revision so the same rows can always be fetched again.

## Install

```bash
pip install lightrider-huggingface
```

You need a Light Rider API key to create datasets (see
[entropy.lightriderinc.com/developers](https://entropy.lightriderinc.com/developers)). Each
dataset costs one draw, or 1 credit. Publishing needs a Hugging Face token with write access.
Verifying needs neither.

```bash
export LR_API_KEY=lr_live_...
export HF_TOKEN=hf_...
```

## Example

```python
import lightrider_huggingface as lrhf

# 500 random circuits: 5 qubits, depth 10
ds = lrhf.circuits(500, num_qubits=5, depth=10, source="anu")

# Or 200 random rows from the GSM8K test split
# ds = lrhf.eval_subset("openai/gsm8k", "test", n=200, config="main", source="anu")

print(ds)                   # rows, source and request id
df = ds.to_pandas()

# Push to the Hub: data, dataset card and signed receipt. Private unless private=False.
lrhf.publish(ds, "your-username/random-circuits-5q")
```

Circuit rows have `circuit_id`, `num_qubits`, `depth`, gate counts, `instructions` (JSON) and
`qasm` (OpenQASM 2.0). `gate_set=` picks the gates (default `h`, `x`, `sx`, `rz`, `cx`).
Subset rows are the source rows unchanged, plus `_lr_source_index`. Pass `fraction=0.1` in
place of `n=` to sample a share of the split.

## Verify a dataset

```python
import lightrider_huggingface as lrhf

report = lrhf.verify("your-username/random-circuits-5q")
print(report)               # each check, PASS or FAIL
assert report.ok
```

No Light Rider key is needed. For a private dataset, set `HF_TOKEN`. For a subset of a very large
dataset, `verify(..., indices_only=True)` skips re-downloading the source.

## How verification works

1. **The receipt is genuine.** Light Rider signs every draw's receipt (Ed25519). Its public key is
   at [entropy.lightriderinc.com/api/v1/public-key](https://entropy.lightriderinc.com/api/v1/public-key).
2. **The seed is that draw's output.** The signed receipt includes a hash of the exact bytes
   drawn, so a seed from any other draw doesn't match.
3. **The data follows from the seed.** Generation is deterministic and fully specified, so
   `verify` rebuilds the rows from the seed and compares them with the published ones.

Every published dataset includes its receipt and the full record (`lightrider_provenance.json`),
so all of this can be checked independently.

**What this doesn't claim:** that quantum randomness is better than a good classical generator.
It's an alternative source whose origin you can check. A receipt also can't show that the
publisher drew only once; its timestamp shows when the draw happened.

## License

Apache-2.0. Built by [Light Rider](https://lightriderinc.com).
