Pareton

<div align="center">

# Pareton (SN10)

**Workload-Specific Inference Optimization. Every Improvement Raises the Baseline.**

[![Discord](https://img.shields.io/discord/308323056592486420.svg)](https://discord.gg/bittensor)
[![Docs](https://img.shields.io/badge/docs-pareton.ai-blue)](https://pareton.ai)
[![X](https://img.shields.io/badge/X-@pareton__ai-000000?logo=x&logoColor=white)](https://x.com/pareton_ai)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

[Website](https://pareton.ai) | [GitHub](https://github.com/pareton-ai) | [Discord](https://discord.gg/bittensor)

---

</div>

Pareton is a Bittensor subnet (SN10) that runs **inference-optimization campaigns**. Miners submit git (code) patches against a pinned vLLM or SGLang baseline. Pareton validates patch integrity and allowed changes, builds patches in a reproducible container environment, and benchmarks real performance gains. Improvements that pass become the new floor for the next campaign.

The [campaign launch guide](docs/campaign_launch_skill.md) covers framework-specific
patch paths, image builds and launch arguments, including a SGLang campaign for
Qwen/Qwen3.8-27B-FP8 on four RTX 5090 GPUs with 262K context.
The updated workload still requires GPU calibration before launch.

## How It Works

1. **Campaigns** pin a baseline commit, base image digest, allowed/denied path globs, and an `hf_rows` sampling rule. Once open, the manifest is frozen. Each round draws a prompt set from that pin.
2. **Miners** author a git patch against that baseline, upload it via Pareton-presigned S3, and commit `campaign_id`, `baseline_commit`, `patch_hash`, and `retrieval_url` on-chain.
3. **The watcher** (`python -m worker.watcher`) scans SN10 for new commitments and writes submissions to Postgres. **The worker** (`python -m worker`) claims jobs and runs validation gates (identity, integrity, base-apply, surface).
4. **Hermetic build** applies the patch inside the pinned base image and pushes a content-addressed engine image to GHCR.
5. **Rounds** batch queued submissions. One round rents one pod, draws one prompt set, and runs the baseline, the current leader, and every challenger against that set. The best image takes the crown. Scores compare inside one round only. On-chain scoring is still design-only.

## Patch visibility

For newly ingested submissions, the API and dashboard withhold the patch download
link until two days after the first finalized `scored` or `disqualified`
evaluation. `PARETON_PATCH_REVEAL_DELAY_S` configures that delay. Submissions
ingested before rollout keep their existing links. Hashes, status, scores, and
logs remain public.

The miner signs its upload request locally. New patches use private S3 objects
with independently random UUIDv4 filenames. The on-chain URL identifies the
private object; it does not grant download access. The watcher and worker read
it with S3 credentials. After the reveal deadline, the first API request copies
the diff to public storage and returns a permanent URL without an expiry.
See [patch visibility](docs/patch-visibility.md) for the upload contract,
deployment prerequisites, and a local patch-hash command.

## Dev submission fee exemptions

Validators can exempt specific dev hotkeys from the TAO submission fee in
`/opt/pareton/.env`:

```dotenv
PARETON_SUBMISSION_FEE_EXEMPT_HOTKEYS=HOTKEY_SS58_1,HOTKEY_SS58_2
```

Use full, case-sensitive hotkey addresses, not coldkeys or wallet names.
Whitespace around entries is ignored; an empty list exempts nobody. Restart
`pareton-watcher` after changing it. Keep `PARETON_SUBMISSION_FEE_TAO` at the
normal fee on the validator; all other submission checks still apply to devs.

An allowlisted dev skips the miner CLI's transfer using its existing fee setting:

```sh
PARETON_SUBMISSION_FEE_TAO=0 python miner/commit_patch.py <your usual arguments>
```

This submits without a payment proof. Setting the miner's fee to zero does not
grant an exemption: the validator checks its own configured list against the
on-chain submitting hotkey. Exempt submissions do not consume payment references.

## Layout

| Path                    | Role                                          |
| ----------------------- | --------------------------------------------- |
| `campaign/`             | Profiles, manifests, seed CLI                 |
| `chain/`                | Patch commitment parse + chain watcher/RPC    |
| `gate/`                 | Patch validation gates a–d                    |
| `builder/`              | Hermetic build + GHCR tagging; [cache backup/restore](docs/build-cache.md) |
| `bench/`                | Correctness / SLA harness                     |
| `gpu/`                  | GPU pod rent/provision/destroy + remote bench |
| `storage/`              | Pareton-presigned S3 uploads                  |
| `db/`                   | Neon schema + connection                      |
| `worker/`               | Job loop + chain watcher (`python -m worker.watcher`) |
| `api/`                  | HTTP API (campaigns, submissions, presign)    |
| `miner/commit_patch.py` | Miner commit CLI                              |
| `miner/hash_patch.py`   | Compute a patch's commitment hash locally      |
| `fixtures/`             | Synthetic campaign fixtures                   |
| `images/baseline/`      | Baseline Dockerfile                           |
| `ops/`                  | Deploy helpers (Vector, Axiom, GPU scripts)   |

## License

Apache License 2.0 — see [LICENSE](LICENSE).