Ralph

<p align="center">
  <img src="docs/assets/ralph-banner.png" alt="Ralph Labs — open model compression" width="100%">
</p>

# Ralph — open model compression on Bittensor SN40

**Compress one pinned open model into fewer bits, without touching its architecture. Best
compression per bit tier wears the crown, and every crown ships as downloadable weights.**

`Qwen/Qwen3-8B` pinned · four bit-budget tiers · [netuid 40](https://taostats.io/subnets/40)

This is not distillation into a smaller architecture. It is the same architecture stored at a
lower bit budget. A submission whose shape does not match the parent is refused before any weights
load. Ralph's score measures retention by downstream effect; it is **not** a standalone capability
benchmark.

**Public status:** seven signed, hash-chained rounds are published and anchored.
[Round 7](https://huggingface.co/datasets/RalphLabsAI/ralph-v2-rounds/blob/main/rounds/round-00000007-f42ae20c6ed2a796.json)
scored every submission with all three judges, changed the `binary`, `sub2`, and `sub4` crowns, and
held `ternary` on the floor rule. The four crown artifacts are mirrored in
[`RalphLabsAI/ralph-crowns`](https://huggingface.co/RalphLabsAI/ralph-crowns). Emission follows
the signed records: a validator sets a round's weight vector after its own audit accepts the
record (see *Running as an auditor validator*).

---

## For miners

You compress privately, however you like. The subnet never inspects your method, only your artifact.

```bash
git clone https://github.com/RalphLabsAI/ralph && cd ralph
pip install -r requirements.txt -r requirements-chain.txt

# 1. compress Qwen/Qwen3-8B however you want — GPTQ, AWQ, bitsandbytes, your own scheme.
#    safetensors or GGUF, architecture unchanged.

# 2. COMMIT FIRST — this seals a hash of your exact bytes on chain before the round exists
python -m miner.submit commit \
    --ckpt ./my-compressed-qwen3 --tier ternary \
    --uri hf://<you>/<repo>@<rev> \
    --wallet <your-wallet> --hotkey <your-hotkey> --netuid 40
#   add --dry-run first; it prints what would be committed without touching the chain

# 3. reveal after the round opens
python -m miner.submit reveal --ckpt ./my-compressed-qwen3 \
    --wallet <your-wallet> --hotkey <your-hotkey> --netuid 40
```

Full walkthrough: [`miner/QUICKSTART.md`](miner/QUICKSTART.md).

### What you have to clear

Six gates, in order. Nothing loads your weights until all six pass.

| # | gate | fails if |
|---|---|---|
| 1 | economics | not registered, or the coldkey already entered this tier in this round |
| 2 | safety | pickles, remote code, or files that are not weights |
| 3 | tier fit | parameter count or dtype headers inconsistent |
| 4 | **bit budget** | measured bits/weight over the tier cap — read from tensor DATA, not the dtype header |
| 5 | **pinned parent** | architecture or weight-element count does not match `Qwen/Qwen3-8B` |
| 6 | commit-reveal | bytes do not hash to what you committed before the nonce existed |

### What the tournament allocates

The signed record computes the weight vector for each tier: a tier is split between its king and
the best challenger who **provably beat them**. Validators pay that vector once their own audit
accepts the record — a vector in a record is the rule applied, not proof of payment; the chain is.

| | |
|---|---|
| **king** | 80% of the tier |
| **best challenger with a strictly positive paired margin** | 20% of the tier |
| everyone else | nothing |

The crown changes hands on the **displayed metric itself**, on the same exam as the re-scored king: a lead of **0.02** in one round, or **0.01 in two consecutive rounds** — the best challenger of a round stays in as the tier's *contender* and is re-scored on the next exam, so a small real edge accumulates instead of being lost to one draw. One rule on top: no slice of the challenger may sit below the king's worst slice — reshaping is allowed, the worst case getting worse is not. A tied pair false-dethrones ~2% of contests at 288-item exams; a copy leads by exactly 0 and a copy with English polish by ~0.008, under both margins. Every round is scored by **all three judges**, and the crown metric is the average of their worst-slice scores — which judge a round happens to draw no longer decides a crown, and fitting one judge moves a third of your score, not all of it. A king that has held **three rounds running** defends against half the margins (0.01 in one round, or 0.005 twice), so a throne nobody has beaten gets easier to take, not harder. A paired lower bound above zero allocates the runner-up share in the candidate vector.

**Start from the reigning crown if you want to.** Every one is published, and improving a published
artifact is the compounding this trail exists for — not an attack on it. The king keeping 80% and
the 0.02 margin in the candidate allocation is what protects the original author. What protects
everyone is that a *copy* earns nothing in that allocation: an unchanged artifact is not re-scored
at all, and a near-copy scores what the original scores, which puts its paired margin at zero.

**One artifact has one owner.** If two hotkeys commit the same bytes, the earlier commitment wins
and the later is refused, with a row in the signed record naming the block that beat it. Submit
your own work, or someone else's made genuinely better.

### Bit tiers

| tier | max code bits/weight | ≈ code size at 8B |
|---|---|---|
| `binary` | 1.15 | 1.18 GB |
| `ternary` | 1.75 | 1.79 GB |
| `sub2` | 2.3 | 2.35 GB |
| `sub4` | 4.0 | 4.10 GB |

A 4-bit model shipped inside a 16-bit container is credited for the compression it achieved and
rejected as an unshippable artifact — both budgets bind.

### Commit the hash of what will be SERVED, not what you uploaded

The most common self-inflicted rejection is a commit-reveal mismatch: the validator fetches your
repo and its recomputed hash does not equal what you revealed, which reads — and is recorded — as
the served byte