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 · `16.38 GB` at bf16 → `1.75 GB` at ternary · [netuid 40](https://taostats.io/subnets/40)

This is not a smaller model trained to imitate a bigger one. It is the model you already know,
stored differently — smaller, not dumber. A submission whose shape does not match the parent is
refused before any weights load.

---

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

# 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 no bond outside your free evaluation |
| 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 you earn

Each tier's emission is split between its king and the best challenger who **provably beat them**.

| | |
|---|---|
| **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. The paired lower bound above zero is what pays the runner-up.

**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 is what protects the original author. What protects everyone is that a *copy* earns
nothing: 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 bits/weight achieved | ≈ size at 8B |
|---|---|---|
| `binary` | 1.15 | 1.18 GB |
| `ternary` | 1.75 | 1.79 GB |
| `sub2` | 2.0 | 2.05 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 bytes not being the committed ones. Nearly every time, the cause is hashing the wrong
thing on your side: `content_hash` covers the whole directory (paths, sizes, bytes of `.gguf`,
`.json`, and friends), so a hash of your local pre-upload file misses whatever the repo actually
serves. Two miners lost round entries to this.

Do what the validator does: download your own repo at the revision you will commit, hash that
directory with the same rule, and commit that. Credit to the miner who diagnosed this after being
rejected for it.

### Formats that can win

**The crown has to run on a phone.** That is the product, so a format mainline `llama.cpp` cannot
execute on Apple GPU is rejected at intake no matter how good its retention would have been — we
score on an H100 where it might run perfectly well, and reject it anyway.

| | |
|---|---|
| **use** | `Q1_0`, `Q2_0`, `IQ1_S`, `IQ1_M`, `IQ2_XXS`, and the `Q*_K` family |
| **rejected** | **`TQ1_0`, `TQ2_0`** — mainline has no Metal kernel for eit