Fugal

# Fugal Subnet

[![CI](https://github.com/fugal-ai/fugal-subnet/actions/workflows/ci.yml/badge.svg)](https://github.com/fugal-ai/fugal-subnet/actions/workflows/ci.yml)
[![Python 3.11–3.12](https://img.shields.io/badge/python-3.11%E2%80%933.12-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Release](https://img.shields.io/github/v/release/fugal-ai/fugal-subnet)](https://github.com/fugal-ai/fugal-subnet/releases)

A Bittensor subnet that finds the best cost-aware LLM router, and pays only
the router that is measurably the best.

A **router** reads a question and picks which model should answer it, so the
user gets the best answer the money can buy. **Miners** train routers and run
the benchmark themselves inside an Intel TDX confidential VM: the enclave
loads the miner's router head (a small linear layer on a frozen Qwen3-0.6B
backbone), routes each question to one of the 19 models in the pinned price
table, pays for the call, grades the reply with hash-pinned checkers, and
produces a hardware-attested proof. **Validators** never call a model: they
verify the proof, compare every head on the same questions, and pay the
champion.

The subnet's output is the champion head, and a continuously refreshed public
record of which model answered which question correctly and at what cost:
the data the next router is trained on.

This README describes **protocol v2**. The subnet runs the v1 rules until the
published activation block (`docs/VALIDATOR_GUIDE.md`, "Protocol v2: flip
procedure"); the differences a miner must act on are in
`docs/MINER_GUIDE.md`, "Moving from v1 to v2".

## Architecture

```
Question → Qwen3-0.6B (frozen) → hidden state → per-model success probability → subtract estimated dollars → select model → call model → answer
                                                        ↑
                                                trainable head (~14 KB .npz)
```

## Quick Start

```bash
# Clone and install (Linux/WSL2, Python 3.11-3.12). CI installs with uv:
git clone https://github.com/fugal-ai/fugal-subnet.git
cd fugal-subnet
uv sync --locked --extra dev          # or: python3 -m venv .venv && pip install -e ".[dev]"

# Full dress rehearsal: the shipped neurons, multi-miner, multi-validator,
# multi-epoch, against a real local chain (Docker), no API spend
uv run python scripts/dress_rehearsal.py --scenario all
# The v2 flip on that chain: v1 epochs, the activation boundary, the first
# seat, a take, a ghost and a resume
uv run python scripts/dress_rehearsal.py --scenario v2_flip

# Provision a subnet on a real network (test or finney) — idempotent
uv run python scripts/provision_subnet.py --network test --netuid <N> \
  --owner-wallet <wallet> --status

# Watch a live subnet and assert it is working, rather than reading logs
uv run python scripts/watch_subnet.py --network test --netuid <N> --epochs 3 \
  --miners m1=<hotkey> --validators v1=<hotkey>,v2=<hotkey>

# A deterministic OpenAI-compatible endpoint, so miners run with no spend
uv run python scripts/stub_upstream.py --pool <pool.json> --port 8799

# Train a v2 head over the v2 price table (test-only synthetic labels, no spend)
uv run python scripts/train_head.py --synthetic --n-questions 200 \
  --prices data/models_v2.json \
  --models anthropic/claude-haiku-5.5 deepseek/deepseek-v4.1-flash openai/gpt-6.1-terra \
  --output data/synthetic_head_test.npz

# Train a candidate from observed labels (see docs/MINER_GUIDE.md, Step 3)
uv run python scripts/train_head.py --matrix data/matrix.npz \
  --prices data/models_v2.json --manifest data/benchmark_tokens_protocol_v2.json \
  --models anthropic/claude-haiku-5.5 deepseek/deepseek-v4.1-flash openai/gpt-6.1-terra \
  --output data/my_head.npz

# Run the miner against a local or test chain (commits the head hash
# on-chain, benchmarks, serves proofs). Mock is the miner's default.
uv run python neurons/miner.py --network test --netuid <N> --head-path data/my_head.npz

# Run the validator in mock mode on a test chain (no API spend). The
# validator defaults to --live, and both neurons refuse --mock on finney.
uv run python neurons/validator.py --network test --netuid <N> --mock
```

The commands above do not call OpenRouter as long as `OPENROUTER_API_KEY` is
unset: `--mock` replaces the attestation, not the model upstream, so a mock
miner with a key in its environment spends real money. A validator has no API
key and no budget at all: it verifies proofs, it never calls a model. The only
paid path is a miner running `--live` with an OpenRouter key delivered over
the attested provisioning channel; see the [Miner Guide](docs/MINER_GUIDE.md).

### Requirements

- Linux or WSL2 and Python 3.11–3.12
- Docker for the full local-chain testnet
- CPU float32 for the shared embedding profile and reference trainer

## How It Works

1. **Epochs are aligned to chain blocks.** Every `EPOCH_INTERVAL/12` blocks
   is an epoch boundary (mainnet: tempo 360, so 360 blocks, 72 minutes). The boundary block's hash
   seeds a nonce that selects 300 questions from the pinned pool, filling the
   published category quotas (40% knowledge, 30% hard, 25% math, 5%
   instruction). Every honest validator derives the identical slice, and
   neither side can know it in advance.
2. **Miners run the benchmark themselves, inside an Intel TDX enclave.** The
   enclave loads the miner's `.npz` head, routes each question, calls the
   chosen model through a metering proxy, grades the reply with the
   hash-pinned graders, and produces a hardware-attested `BenchmarkProof`.
   Miners pay for their own inference. A head is only scoreable if its SHA256
   was **committed on-chain at or before the boundary block**: a head swapped
   after the nonce is knowable is rejected.
3. **Miners also answer a nonce-chosen 5% of extra questions using a model
   they do not pick.** These are never scored against them; they are the
   only unbiased samples of how good each model