skip to content

Getting started

Installation

copy markdown

Requirements

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

Install

# 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

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'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

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