Almanac

<div align="center">

```
   CORVUS LABS PRESENTS
--------------------------------------------------------------------------------------------------
   █████████   █████       ██████   ██████   █████████   ██████   █████   █████████     █████████ 
  ███▒▒▒▒▒███ ▒▒███       ▒▒██████ ██████   ███▒▒▒▒▒███ ▒▒██████ ▒▒███   ███▒▒▒▒▒███   ███▒▒▒▒▒███
 ▒███    ▒███  ▒███        ▒███▒█████▒███  ▒███    ▒███  ▒███▒███ ▒███  ▒███    ▒███  ███     ▒▒▒ 
 ▒███████████  ▒███        ▒███▒▒███ ▒███  ▒███████████  ▒███▒▒███▒███  ▒███████████ ▒███         
 ▒███▒▒▒▒▒███  ▒███        ▒███ ▒▒▒  ▒███  ▒███▒▒▒▒▒███  ▒███ ▒▒██████  ▒███▒▒▒▒▒███ ▒███         
 ▒███    ▒███  ▒███      █ ▒███      ▒███  ▒███    ▒███  ▒███  ▒▒█████  ▒███    ▒███ ▒▒███     ███
 █████   █████ ███████████ █████     █████ █████   █████ █████  ▒▒█████ █████   █████ ▒▒█████████ 
▒▒▒▒▒   ▒▒▒▒▒ ▒▒▒▒▒▒▒▒▒▒▒ ▒▒▒▒▒     ▒▒▒▒▒ ▒▒▒▒▒   ▒▒▒▒▒ ▒▒▒▒▒    ▒▒▒▒▒ ▒▒▒▒▒   ▒▒▒▒▒   ▒▒▒▒▒▒▒▒▒  
```                                                                                                                                         

</div>

- [Introduction](#introduction)
- [Miner and Validator Functionality](#miner-and-validator-functionality)
  - [Miner](#miner)
  - [Validator](#validator)
- [Running a Validator](#running-a-validator)
- [For Miners](#for-miners)
  - [Shared prerequisites](#shared-prerequisites)
  - [Almanac Market miners](#almanac-market-miners)
  - [Almanac Forecasting miners](#almanac-forecasting-miners)
- [Repository Structure](#repository-structure)
- [Environments](#environments)
- [Community](#community)
- [License](#license)

## Introduction

Almanac is a validator stack for decentralized agentic forecasting and market prediction performance on Bittensor. It combines two incentive mechanisms, both geared toward improving prediction accuracy.

IM1 — **Almanac Market** (`almanac.market`): a prediction-market terminal that makes competing and submitting predictions through trading more accessible.

IM2 — **Almanac Forecasting**: miners submit forecasting agents that predict events while validators build reasoning traces for our data pipeline.

Both incentive mechanisms generate scores and publish blended weights on-chain.

## Miner and Validator Functionality

### Miner

There are two tracks for miners to participate in:
1. Almanac Market 
- Participate through trading on `beta.almanac.market`.
- Requires metadata registration and connecting UID/hotkey to Almanac Market account
- 1% fee is collected from every buy trade and used towards the daily reward pool
- Scoring mechanism largely favors sustained edge, substantial volume, and winning over the competition

2. Almanac Forecasting
- Participate by creating an Almanac Portal account and funding credits on `portal.almnc.ai`
- Build and submit forecasting agents through `miner/cli.py`.
- Validators will execute agent's to forecast event predictions.
- Scoring mechanism largely favors sustained accuracy, calibrated confidence, and beating the market
- Miner onboarding and CLI flows are documented in `miner/README.md`.

### Validator

The validator's high-level, continuously looping execution:

- Sync miner metadata and market activity.
- Execute miner agents in locked down docker environment using Almanac's portal
- Posts agent predictions and reasoning chain metadata to Almanac's portal
- Score miners under multiple mechanisms.
- Blend scores into final validator weights.

## Running a Validator

### Requirements

- Python 3.10+
- `pip`
- Docker Engine + Docker Compose plugin
```bash
sudo apt update
sudo apt install docker.io docker-compose-v2
```
- A registered Bittensor validator wallet/hotkey setup (via `btcli`)
- `WANDB_API_KEY` in `.env` for W&B logging (or use `--wandb.off`)
- Linux **amd64** host for production (agent-runner siblings must match host arch)

#### Hardware

No GPU is required — LLM inference is remote via the central gateway. Peak load
comes from Docker agent sandboxes (defaults: up to 8 concurrent × 1 GB RAM /
1 CPU each; see `src/core/constants.py`).

| Resource | Minimum | Recommended |
|---|---|---|
| **CPU** | 4 vCPU | 8–16 vCPU |
| **RAM** | 8 GB | 16–32 GB |
| **Disk** | 50 GB SSD | 100 GB SSD |
| **Network** | Stable outbound HTTPS (~100 Mbps) | 1 Gbps, low latency to chain + `api.almnc.ai` |
| **GPU** | None | None |

`bittensor==11.0.1` in `requirements.txt` includes both the Python SDK and
`btcli`; do not install the legacy separate `bittensor-cli` package. In v11,
create keys with `btcli wallet create --wallet <coldkey-name> --wallet-hotkey
<hotkey-name>` and register with `btcli subnets register --netuid 41 --wallet
<coldkey-name> --wallet-hotkey <hotkey-name> --network finney`.
The dotted flags in the validator examples below belong to Almanac's scripts,
not to `btcli`.

### Production: Docker required

When Almanac Forecasting is enabled, the validator must spawn sandboxed agent-runner
child containers. In this repo, that means running the validator with Docker
access (`docker.sock`) via Compose.

```bash
# Build both images once (runner + validator)
docker compose build agent-runner validator
```

> **Build for the architecture the validator will run on.** The validator
> spawns the `agent-runner` image as sibling containers, and container images
> are architecture-specific. An image built on an Apple Silicon (arm64) laptop
> will not start on an amd64 Linux server, and vice versa. `docker compose
> build` only builds for the builder's native arch. To target a specific
> platform (e.g. building on a Mac for an amd64 server), use the arch-aware
> wrappers, which set `--platform` explicitly and warn on cross-arch builds:
>
> ```bash
> # Linux / macOS / WSL / Git-Bash
> PLATFORM=linux/amd64 scripts/build_images.sh all
> # Windows PowerShell
> ./scripts/build_images.ps1 -Target all -Platform linux/amd64
> ```
>
> Or pin Compose builds with `export DOCKER_DEFAULT_PLATFORM=linux/amd64`.

```bash
docker compose run --rm validator \
  python scripts/run