Claims

# Claims Subnet

Claims is a Bittensor subnet for extracting scientific contribution claims from
papers and linking each claim to grounded evidence in the source text.

This repository contains the runnable miner, validator, protocol, schemas, and
operator documentation for the Claims subnet.

## What It Does

- Miners receive paper-extraction tasks and return structured claim-evidence
  packets.
- Validators audit miner outputs for source grounding, valid claim-evidence
  links, and coverage of the task scope.
- The neuron entry points expose the miner and validator through Bittensor.

The canonical miner pipeline is `agent_v1`: a skill-capable agent miner that
uses the [ARA](https://github.com/ARA-Labs/Agent-Native-Research-Artifact)
compiler skill and writes Claims-owned structured agent artifacts derived from
the ARA markdown artifact model.
The older `v0` direct model pipeline remains available only as a legacy
compatibility path while the validator and network envelope continue to support
existing Claims v0 tasks.

## Repository Layout

```text
Claims/
├── miner/agent_v1/    # canonical skill-capable agent miner pipeline
├── miner/v0/          # legacy direct claim extraction pipeline
├── validator/agent_v1/# canonical agent artifact validation pipeline
├── validator/v0/      # audit and scoring pipeline
├── neurons/           # Bittensor miner, validator, and protocol
├── schemas/           # shared data contracts
├── docs/              # design notes and operator runbooks
├── examples/          # example papers and inputs
├── requirements.txt
└── .env.example
```

## Service URLs

| Service | URL | Used by |
|---|---|---|
| Claims dashboard | [dashboard.claims111.ai](https://dashboard.claims111.ai) | Public network and miner views |
| Validator/backend API | [api.claims111.ai](https://api.claims111.ai) | Validators, dashboard, and administrative data |
| Validator/backend API docs | [api.claims111.ai/docs](https://api.claims111.ai/docs) | Interactive OpenAPI documentation |
| Miner artifact-upload API | [artifacts.claims111.ai](https://artifacts.claims111.ai) | Signed miner artifact uploads |
| Miner upload API docs | [artifacts.claims111.ai/docs](https://artifacts.claims111.ai/docs) | Interactive OpenAPI documentation |

Set the role-specific backend URL as follows:

```env
# Validator
CLAIMS_BACKEND_URL=https://api.claims111.ai

# Miner
CLAIMS_BACKEND_URL=https://artifacts.claims111.ai
```

## System Prerequisites

The default production validator profile processes 50 papers across 15 miners
and runs diagnostic, reference, and Silver work concurrently. The smaller
requirements below are suitable for installation checks and reduced-concurrency
testing; use the production recommendation for sustained subnet operation.

| Component | Requirement | Notes |
|---|---|---|
| OS | Ubuntu 22.04+ recommended; macOS 13+ for manual development | The Ubuntu installers support Debian-family Linux. Published containers use Ubuntu 24.04. |
| Validator CPU/RAM | 8 cores / 32 GB minimum; 16 cores / 64 GB recommended | The production 50-paper, 15-miner profile runs multiple agent and PDF-processing subprocesses. Reduce worker counts on the minimum configuration. |
| Miner CPU/RAM | 4 cores / 16 GB minimum; 8 cores / 32 GB recommended | Higher paper concurrency starts additional agent and PDF-processing subprocesses. The example miner profile uses two paper workers. |
| Persistent disk | 50 GB miner; 100 GB validator | Allow additional space when retaining many outputs, Bronze references, PDFs, model caches, or logs. Container deployments must persist `/data`. |
| Docker | Docker Engine 24.0+ recommended | Required only for the published container workflow; manual and Ubuntu-installer deployments do not require Docker. |
| Python | 3.12 recommended; 3.11+ minimum | Python 3.10 is unsupported because current validator dependencies use Python 3.11 typing APIs. Published Ubuntu 24.04 images and the verified Ubuntu setup use Python 3.12. |
| Bittensor SDK | `10.5.0` | Installed from `requirements.txt`. Other SDK versions are not supported unless the repository pin is updated and tested. |
| Network | Stable broadband; public TCP port for miners | Miners must expose a reachable Axon. Both roles need outbound access to Bittensor, Claims APIs, PDF storage, and configured inference providers. |
| GPU | Not required with hosted inference providers | Operators using local models must size GPU memory and runtime dependencies for those models separately. |

## Installation

Choose one installation path: manual Python setup, the Ubuntu installers, or
the published Docker images.

### Manual Installation

On Ubuntu or Debian, install the native build and PDF tools first:

```bash
sudo apt-get update
sudo apt-get install -y \
  build-essential ca-certificates curl git \
  libgl1 libglib2.0-0 poppler-utils \
  python3 python3-dev python3-pip python3-venv
```

On macOS, install Python 3.12 or newer and Poppler before continuing. The
Ubuntu installer is the supported automated path for production Linux hosts.

Clone Claims and create its Python environment:

```bash
git clone https://github.com/DeSciClaims/Claims.git
cd Claims
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements.txt
python -m pip install --no-deps -e .
```

For a miner, start with the miner environment template:

```bash
cp examples/miner.env.example .env
```

For a validator, install the public reference miner at a reviewed commit and
use the profile for the network you will validate. Install the reference miner
with the same interpreter that will run the validator:

```bash
git clone https://github.com/DeSciClaims/claims-reference-miner.git ../claims-reference-miner
git -C ../claims-reference-miner checkout <PINNED_COMMIT>
.venv/bin/python -m pip install ../claims-reference-miner

# SN111 mainnet profile. Use validator.testnet.env.example for testnet instead.