Metadata-Version: 2.4
Name: xrtm-train
Version: 0.2.5
Summary: The Learning/Optimization layer for XRTM.
Author-email: XRTM Team <moy@xrtm.org>
License-Expression: Apache-2.0
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: xrtm-data>=0.2.2
Requires-Dist: xrtm-eval>=0.2.3
Requires-Dist: xrtm-forecast>=0.6.3
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: gpu
Requires-Dist: torch>=2.0.0; extra == "gpu"
Requires-Dist: transformers>=4.35.0; extra == "gpu"
Requires-Dist: peft>=0.7.0; extra == "gpu"
Requires-Dist: accelerate>=0.25.0; extra == "gpu"
Dynamic: license-file

# xrtm-train

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/xrtm-train.svg)](https://pypi.org/project/xrtm-train/)

**The Optimization Layer for XRTM.**

`xrtm-train` is the engine that closes the loop. It simulates history by replaying agents against past "Ground Truth" snapshots stored in `xrtm-data`, scoring them with `xrtm-eval`, and optimizing their reasoning parameters.

## Part of the XRTM Ecosystem

```
Layer 4: xrtm-train    → (imports all) ← YOU ARE HERE
Layer 3: xrtm-forecast → (imports eval, data)
Layer 2: xrtm-eval     → (imports data)
Layer 1: xrtm-data     → (zero dependencies)
```

`xrtm-train` sits at the top of the stack and can import from ALL other packages. **Installing `xrtm-train` gives you the full XRTM stack.**

## Installation

```bash
pip install xrtm-train
```

> This automatically installs `xrtm-forecast`, `xrtm-eval`, and `xrtm-data`.

## Core Primitives

### The Simulation Loop
The `Backtester` orchestrates the simulation. It ensures strict temporal isolation—agents are never exposed to data from the future.

```python
from xrtm.train import Backtester

# Initialize components
backtester = Backtester(agent=my_agent, evaluator=my_evaluator)

# Run simulation
results = await backtester.run(dataset=historical_questions)
print(f"Mean Brier Score: {results.mean_score}")
```

### Examples (v0.1.2+)
With the v0.6.0 architecture split, calibration and replay examples now live here:

*   **[Calibration Demo](examples/kit/run_calibration_demo.py)**: Adjusting confidence intervals to match reality.
*   **[Trace Replay](examples/kit/run_trace_replay.py)**: Re-running a saved execution for debugging.
*   **[Evaluation Harness](examples/kit/run_evaluation_harness.py)**: End-to-end backtest with metrics.

## Project Structure

```
src/xrtm/train/
├── core/            # Interfaces & Schemas
│   └── eval/            # Calibration (PlattScaler, BetaScaler)
├── kit/             # Training utilities
│   ├── memory/          # Replay buffers
│   └── optimization/    # Training strategies
├── simulation/      # Backtester, TraceReplayer
└── providers/       # Remote training backends (future)
```

## Development

Prerequisites:
- [uv](https://github.com/astral-sh/uv)

```bash
# Install dependencies
uv sync

# Run tests
uv run pytest
```
