Minos

```
  A---T
 { \ / }
  \ X /
  / X \     __  __ _
 { / \ }   |  \/  (_)_ __   ___  ___
  G---C    | |\/| | | '_ \ / _ \/ __|
 { \ / }   | |  | | | | | | (_) \__ \
  \ X /    |_|  |_|_|_| |_|\___/|___/
  / X \
 { / \ }
  T---A
```

# Minos – Decentralized Genomic Variant Calling & Benchmarking Platform

Minos (SN107) is a subnet for genomic variant calling and benchmarking powered by Bittensor. Every 72 minutes, the platform generates a fresh challenge genome (BAM file) containing hidden synthetic mutations injected using HelixForge at read level. Miners are rewarded for performing hyperparameter search and providing configurations for state-of-the-art variant calling tools that can accurately identify these hidden mutations in the genome. Once the hyperparameter space has been saturated, miners will compete to provide their own custom algorithms to identify mutations. Validators are responsible for downloading miner's hyperparam config and they will run each miner's submitted config, and evaluate the results using industry standard tools and approaches such as hap.py. Miners will never be asked to upload outputs, they submit their variant-calling configuration (and pipelines in later stages), which the validator executes independently.

> **Subnet 107** on Bittensor mainnet (finney).

## Table of Contents

- [Architecture Overview](#architecture-overview)
- [Repository Layout](#repository-layout)
- [System Prerequisites](#system-prerequisites)
- [Quick Start](#quick-start)
- [Optional Minos Miner AI Assistant](#optional-minos-miner-ai-assistant)
- [Running with PM2 (optional)](#running-with-pm2-optional)
- [Validator Setup](#validator-setup)
- [Miner Setup](#miner-setup)
- [Platform Service](#platform-service)
- [Scoring System](#scoring-system)
- [Monitoring & Troubleshooting](#monitoring--troubleshooting)
- [Additional Documentation](#additional-documentation)

---

## Architecture Overview

```
┌────────────────────────────────────────────────────────────-─┐
│                    MINOS PLATFORM                            │
│              (Task Coordination & File Conveyance)           │
├────────────────────────────────────────────────────────────-─┤
│  • Prepares BAMs with synthetic mutations using HelixForge   │
│  • Presigned URL generation for BAM transfer                 │
│    (Hippius SN75 + Cloudflare R2 + AWS S3 fallback)          │
│  • Continuous 72-minute rounds aligned to Bittensor tempo    │
│  • Lag scoring: miners submit in cycle N, validators score   │
│    cycle N while miners work on cycle N+1                    │
│  • Miner registration & status tracking                      │
└──────────────┬──────────────────────────────┬────────────────┘
               │                              │
    ┌───────────▼────────────────┐      ┌──────▼─────────────────────-------------------┐
    │     VALIDATOR              │      │      MINER                                    │
    │  • Downloads BAMs          │      │  • Download and run variant caller on BAM     │
    │  • Runs miner config       │      │ • Submits hyperparam config from their run    │
    │  • Scores with hap.py      │      │  • Top performer wins                         │
    │  • Sets blockchain weights │      └────────────────────────────-------------------┘
    └────────────────────────────┘
               │
    ┌──────────▼──────────┐
    │     BITTENSOR       │
    │    BLOCKCHAIN       │
    │  • Weight storage   │
    │  • Emission calc    │
    │  • Alpha emissions  │
    └─────────────────────┘
```

---

## Repository Layout

```
minos_subnet/
├── neurons/                  # Bittensor neuron entrypoints
│   ├── miner.py              # Miner loop: poll, download, call variants, submit config
│   ├── validator.py          # Validator loop: subset scoring, set chain weights
│   ├── status.py             # Health checks and system status
│   └── README.md             # Neurons documentation
├── templates/                # Variant-calling tool templates
│   ├── gatk.py               # GATK HaplotypeCaller template
│   ├── deepvariant.py        # Google DeepVariant template
│   ├── freebayes.py          # FreeBayes template (DEPRECATED 2026-05-09; retained so in-flight pre-cutover rounds can still be scored; will be removed in a follow-up release)
│   ├── bcftools.py           # BCFtools mpileup/call template
│   ├── _common.py            # Shared template utilities
│   └── tool_params.py        # Parameter definitions and validation
├── utils/                    # Genomics utility modules
│   ├── scoring.py            # hap.py Docker runner + AdvancedScorer
│   ├── weight_tracking.py    # Round score tracker + winner-heavy pruning dust weights
│   ├── platform_client.py    # Authenticated API client (miner + validator)
│   ├── subset_scoring.py     # Subset scoring helpers (assignments, deadlines)
│   ├── config_loader.py      # Tool config file parser
│   ├── path_utils.py         # Safe filesystem paths
│   ├── file_utils.py         # File download + caching; SHA256 checked, with MINOS_ENFORCE_DOWNLOAD_SHA256 to reject a mismatching download
│   └── README.md             # Utils documentation
├── base/                     # Core subnet config
│   └── genomics_config.py    # Central config (Docker images, timeouts, scoring params)
├── configs/                  # Miner-tunable quality parameters
│   ├── gatk.conf
│   ├── deepvariant.conf
│   ├── freebayes.conf        # DEPRECATED 2026-05-09; retained for legacy parsing
│   └── bcftools.conf
├── docs/                     # Architecture and integration docs
│   ├── architecture.md       # System architecture deep dive
│   ├── tuning_guide.md       # Miner tuning reference (scoring, parameters, strategy)
│   ├── parameter_ranges.md   # Accepted parameters and valid ranges per tool
│   ├── hap_py_docker.md      # hap.py Docker image reference
│   └── ai-assistant/         # AI assistant knowledge graph, runtime skills, and persona assets
├── scripts/