Leoma Subnet

Leoma is an AI video subnet on Bittensor. Miners run Text-Image to Video (TI2V) models; validators evaluate miner outputs and set winner-take-all weights on-chain. The best miner earns subnet alpha each round.

Supported model type (current): Text-Image to Video (TI2V) only.

Roadmap: Support for Text-to-Video (T2V) and Image-to-Video (I2V) is planned.

---

Contents

• What is Leoma?
• Workflow
• Validator setup
• Miner setup
• Storage and API
• Security and production
• Documentation
• License

---

What is Leoma?

Leoma is a Bittensor subnet for AI-generated video:

• Current support: Text-Image to Video (TI2V) — validators send a first frame (image) and a text prompt; miners return a short video. Validators score generated videos with a strict multi-aspect benchmark prompt (first-frame fidelity, prompt adherence, temporal quality, visual artifacts) and record pass/fail wins. Ranking is winner-take-all; the top miner gets full weight each round.
• Roadmap: Text-to-Video (T2V) and Image-to-Video (I2V) support are planned.

Workflow

1. Subnet owner runs the owner-sampler: creates tasks (first frame + prompt from one-shot 5s clips in Hippius S3), calls miners via Chutes, uploads task artifacts to the samples bucket, and sets the latest task id on the API.
2. Validators run the evaluator and weight-setter: poll the API for the latest task, download task data from S3, run GPT-4o evaluation, POST results to the Leoma API; each epoch, call GET /weights and set on-chain weights (winner-take-all).
3. The API (subnet owner) computes rank (dominance rule) and exposes GET /weights. Validators use this to set weights on-chain.
4. Miners register a Hugging Face model (naming: leoma prefix, hotkey suffix) and Chute endpoint via on-chain commit. They receive challenges; the best performer earns subnet alpha.

Role	In Leoma
Miner	Upload a TI2V model to Hugging Face (name: leoma... + your hotkey), deploy to Chutes, commit on-chain. Earn subnet alpha when your outputs win.
Validator	Run evaluator + weight-setter (e.g. leoma serve). Requires API URL, Hippius S3 read (samples bucket), OpenAI API key, and Bittensor wallet.

---

Validator setup

Validators run the evaluator and the weight-setter. Task creation and miner calls are done by the subnet owner (owner-sampler), not validators.

Prerequisites

• Bittensor wallet (coldkey + hotkey) registered as a validator on the Leoma subnet.
• Leoma API URL (the deployed owner API).
• Hippius S3 access: read-only to the samples bucket (evaluator downloads task data from S3; evaluation results are submitted to the Leoma API with hotkey signature). Use access keys from the Hippius console.
• OpenAI API key (for GPT-4o evaluation in the evaluator).
• Validator registration in API DB: An admin must add your validator hotkey (and UID, stake) so the API includes you in stake-weighted scoring (e.g. leoma db add-validator --uid <uid> --hotkey <ss58>).

Environment variables

Set these in .env (copy from env.example):

Variable	Description
API_URL	Leoma API base URL (e.g. https://api.leoma.ai)
NETUID	Subnet ID (e.g. 99)
NETWORK	Bittensor network (finney for mainnet)
WALLET_NAME	Bittensor wallet name (e.g. default)
HOTKEY_NAME	Bittensor hotkey name (e.g. default)
OPENAI_API_KEY	OpenAI API key for GPT-4o (evaluator)
EPOCH_LEN	Blocks per epoch (e.g. 180); optional
HIPPIUS_ENDPOINT	e.g. s3.hippius.com
HIPPIUS_REGION	e.g. decentralized
HIPPIUS_SAMPLES_BUCKET	Samples bucket (e.g. samples)
HIPPIUS_SAMPLES_READ_ACCESS_KEY / HIPPIUS_SAMPLES_READ_SECRET_KEY	Read access to samples bucket (evaluator downloads tasks only; no write needed)

Quick start (Docker, recommended)

This repo’s docker-compose.yml runs the validator (evaluator + weight-setter in one container) and optionally Watchtower for auto-updates.

# 1. Clone the repo
git clone https://github.com/RendixNetwork/leoma.git
cd leoma

# 2. Create .env from example
cp env.example .env
# Edit .env: API_URL, OPENAI_API_KEY, HIPPIUS_SAMPLES_READ_*, WALLET_NAME, HOTKEY_NAME, NETUID, NETWORK

# 3. Run
docker compose up -d

This starts leoma-validator (leoma serve: evaluator + weight-setter) and leoma-watchtower. Mount your Bittensor wallets so the container can sign weight-setting transactions; the compose file uses ~/.bittensor/wallets:/root/.bittensor/wallets:ro.

Auto-update with Watchtower: Build and push the image on subnet code updates; Watchtower will pull and restart the validator container. See env.example for WATCHTOWER_POLL_INTERVAL and related options.

Manual installation

# Requires Python 3.12+
pip install -e .   # or: uv pip install -e .

# Run validator (evaluator + weight-setter in one process)
leoma serve

Split processes (advanced)

You can run evaluator and weight-setter as separate processes:

leoma servers evaluator   # Polls GET /tasks/latest, downloads from S3, GPT-4o, POSTs to API
leoma servers validator   # Every epoch: GET /weights, set on-chain

API authentication

Endpoints that require validator identity (e.g. POST /samples/batch) use signature auth. Send headers: X-Validator-Hotkey, X-Signature, X-Timestamp. Message to sign: SHA256(request_body):timestamp (UTF-8), with your validator keypair. See the API reference in the docs.

---

Miner setup

To run a miner on the Leoma subnet: upload your Text-Image to Video (TI2V) model to Hugging Face, deploy to Chutes, and commit on-chain.

1. Upload your model to Hugging Face

• Fine-tune or adapt a TI2V model, then upload it to Hugging Face as a model repository.
• Model naming (required): The repository name must start with leoma and end with your miner hotkey (SS58 address).
  Example: your_username/leoma-5F3sa2TJAWMqDhxG6jhV4N8ko9SxwGy8TpaNS1repo5DvT9.
• Revision (required): Use a specific revision — the full Git commit SHA of the model version you deploy. Do not use branch names like main.

2. Deploy to Chutes and commit on-chain

1. Deploy to Chutes (so validators can call your model):

   leoma miner push --model-name <your-hf-repo> --model-revision <full-commit-sha> --chutes-api-key <api-key> --chute-user <chutes-username>

   Use the full commit SHA as --model-revision. Note the Chute ID from the output.

2. Commit on-chain (register model + Chute for validators):

   leoma miner commit --model-name <your-hf-repo> --model-revision <full-commit-sha> --chute-id <chute-id> --coldkey <wallet-name> --hotkey <ss58-address>

   Your wallet (coldkey/hotkey) must be registered on the subnet.

3. Monitor your miner

• Network page (app): View leaderboard, valid miners, and recent evaluations. Confirm your hotkey appears and is valid.
• CLI: Fetch the current rank list (same data as the dashboard):

  leoma get-rank

• API: GET /miners/list, GET /miners/{hotkey}, GET /scores/rank — check is_valid, invalid_reason, and eligible (completeness ≥ 80%).

---

Storage and API

• Storage (Hippius S3): Source videos live in the source bucket; task artifacts (first frame, original clip, generated videos) and evaluation results live in the samples bucket. Validators need read-only access to the samples bucket. See the Storage doc.
• API: The Leoma API provides health, miners, samples, scores, tasks, weights, and blacklist endpoints. Validators use GET /tasks/latest, POST /samples/batch, and GET /weights. See the API reference.

---

Security and production

• Dependencies: Critical packages are pinned in pyproject.toml. Before production, run pip audit (or use Dependabot/Snyk) for known vulnerabilities.
• Production env: Set LEOMA_ENV=production (or ENVIRONMENT=production) so the API enforces non-default DB credentials and exception logs omit full tracebacks.
• CORS: Set CORS_ORIGINS to a comma-separated list of allowed frontend origins. Leave unset for development (allows *).
• API auth: Validator requests use hotkey signature auth; admin-only actions require hotkeys listed in ADMIN_HOTKEYS. See env.example for SIGNATURE_EXPIRY_SECONDS and related options.

---

Documentation

Full documentation (getting started, miner setup, validator setup, storage, API reference):

• Docs site: https://docs.leoma.ai

Resources:

• App / dashboard: Leoma frontend (Overview, Product, Network, Docs, Help)
• Whitepaper: Protocol details and incentives
• Community: Discord, Twitter, GitHub (see the app Help page)

---

License

MIT