# Installation

## Requirements

- Python >= 3.11
- For training: NVIDIA GPU with CUDA support, torch >= 2.10

## Install

```bash
# Base install (CLI, config, reports, model checks -- no GPU needed)
pip install poros-train

# With ML dependencies (torch, transformers, peft, bitsandbytes)
pip install "poros-train[ml]"

# With benchmark harness (adds matplotlib)
pip install "poros-train[ml,bench]"

# Development install
pip install "poros-train[ml,bench,dev]"
```

The base install (`typer`, `rich`, `pydantic`, `pyyaml`, `huggingface-hub`,
`jinja2`) works without torch or any GPU.  `poros --help`, `poros doctor`,
`poros check`, `poros report`, `poros leaderboard`, and `poros schema` all
function on CPU-only machines.  Commands that read/emit data support
`--json` for scripting and agents.

## Verify

```bash
poros --version       # prints the installed version, e.g. 0.3.0
poros doctor          # checks GPU, CUDA, torch, disk, dependencies
```

## What bitwise parity needs

Poros gives 0.00e+00 parity against the same run held fully in VRAM, on
a validated configuration (detected NF4, validated architecture, validated
PEFT LoRA topology, RNG preservation, zero non-adapter trainables,
deterministic mode — [auto.md](auto.md)'s guarantee label). Deterministic
mode contributes the two kernel conditions the recorded bitwise gates ran
under, both set for you when `deterministic: true` (the default):

- `torch.use_deterministic_algorithms(True)`
- math-only SDPA — flash and mem-efficient attention are disabled

Any supported stack works: torch 2.10+ with CUDA 12.8+.

## From source

```bash
git clone https://github.com/Caistro-Labs/poros.git
cd poros
pip install -e ".[ml,bench,dev]"
pytest
```