Prometheon

<p align="center">
  <img src="Prometheon_Logo.svg" width="120" alt="Prometheon" />
</p>

# Prometheon V2

A Bittensor subnet that develops, benchmarks, and continuously improves **open-source content-moderation models**.

> **Phase scope.** This repository is Phase 2 and replaces the Phase 1 activity-reward mechanism entirely. Phase 1 lives in `prometheon_v1` and is no longer the reward path.

---

## What this subnet does

Miners compete to build the best moderation model, and they supply the data it is measured on.

1. **A miner grows a BitFan Fan Group.** Its members write posts and replies they believe violate the platform's content policy, marked as **test content**. Those are recorded, never published.
2. **The subnet collects a day of content**: that test content, plus a sample of real production content.
3. **Validators label it** against [`content_policy.md`](./content_policy.md), producing the day's ground truth.
4. **Miners publish a moderation model** to Hugging Face, committing `(hf_repo, revision_sha)` on chain. Nothing is deployed and nothing is served: weights are the whole submission.
5. **Validators run every model themselves**, on their own GPUs, over the labelled corpus, and set one weight vector.

Two things are rewarded, in equal measure: **contributing usable evaluation data**, and **building the model that judges it best**.

```text
BitFan users write test content   →   subnet DB layer   →   validators label it
                                                              ↓
miners publish models to HF  →  validators download and run them  →  set_weights
```

---

## What makes the measurement trustworthy

Code in this repository enforces each of these. There is no rule anyone has to remember to follow.

**A miner is never scored on content its own users wrote.** Test items carry their contributing miner, and each model's accuracy is computed only over other miners' items. Watermarking your own submissions buys nothing.

Miners also cannot see the corpus they are measured on. A day's test content is released to miners two days later, after the evaluation that used it has finished. Memorisation is not a strategy.

Every model runs identical code. Miners supply weights and nothing else. The inference path is one subnet-authored script, hash-pinned, running inside one subnet-built container image, and validators check both from outside, against the deployment itself. A hash proves which bytes are on disk; pinning the image is what makes them run somewhere the miner did not assemble. A score difference is a model difference.

**Verdicts cannot be malformed, and a model cannot refuse.** Decoding is forced-choice: the engine compares probability mass on `YES` against `NO` and takes the larger. Nothing is generated freely, so there is no output to parse and no refusal to interpret.

The corpus contains text written to violate policy, some of it written to manipulate a classifier. Items are therefore judged one at a time, never concatenated, so an instruction buried in one post cannot reach the verdict on another.

Validators verify eligibility themselves, from chain commitments and Hugging Face. The subnet's own database is not trusted for it.

---

## Repository layout

```text
src/prometheon/chain/       commitments, metagraph, weight submission
src/prometheon/registry/    model eligibility: manifest, hashes, provenance, duplicates
src/prometheon/dbclient/    the /v2 client, its contract, and an in-memory fake
src/prometheon/labelling/   ground-truth labelling with injection-hardened batching
src/prometheon/evaluation/  corpus assembly and model execution
src/prometheon/scoring/     dataset and model rewards, allocation, burn
src/prometheon/security/    canonical JSON encoding and hotkey signatures
src/prometheon/cli/         the miner and validator command surface
content_policy.md           the authority for every verdict
configs/                    pre-pinned example configuration
docs/                       operator guides and the contracts other teams build against
```

---

## Installation

Requires Python `>=3.10,<3.15` and a `btcli`-managed Bittensor wallet.

```bash
git clone https://github.com/BitSpaceorganization/prometheon_v2
cd prometheon_v2
uv sync
```

Every command below assumes `uv run` in front of `prometheon`. To drop the prefix, `source .venv/bin/activate` once.

---

## Miners

You need a Fan Group that clears **both** floors: **at least 50 registered members**, accounts that have joined your group, **and at least 25 active members**, members whose 7-day activity score clears the platform's active threshold. Both gates apply to both reward streams; the active floor is the anti-farming half a sign-up farm fails.

Register your Fan Group, then connect your **Talisman** wallet (or another Substrate wallet, polkadot-js, SubWallet, Nova) with the **Connect Wallet** button in the bitfan.ai site header and sign the ownership proof, which binds your mining hotkey to your leader account. That is a platform step, not a subnet command, and nothing else works until it is done.

```bash
# 1. Commit the model on chain; this is the submission
uv run prometheon model commit --config ~/prometheon-mainnet.toml

# 2. Check what a validator will conclude about your deployment
uv run prometheon model verify --config ~/prometheon-mainnet.toml

# 3. Pull released datasets to train against
uv run prometheon dataset pull --config ~/prometheon-mainnet.toml --date 2026-08-05
```

Your Hugging Face repository holds **weights, config and tokenizer, no executable code at all**. Any other file and your deployment is not scored. See [`docs/miner.md`](./docs/miner.md).


---

## Validators

There are two ways to run one, and they cost very different things:

| | `score_source = "local"` (default) | `score_source = "endpoint"` |
|---|---|---|
| Hardware | **8 × RTX 5090 (256 GB) or better** | **CPU only, no GPU** |
| Labelling key | yours to pay for | none |
| Cycle | hours | secon