Metadata-Version: 2.5
Name: xtrax
Version: 0.4.1b9
Summary: High-performance composable JAX library
Project-URL: Homepage, https://github.com/maraxen/xtrax
Project-URL: Documentation, https://xtrax.readthedocs.io
Project-URL: Repository, https://github.com/maraxen/xtrax
Project-URL: Issues, https://github.com/maraxen/xtrax/issues
Project-URL: Changelog, https://github.com/maraxen/xtrax/blob/main/CHANGELOG.md
Author-email: Marielle Russo <67157875+maraxen@users.noreply.github.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: distributed,jax,pytree,training
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: jax<0.12,>=0.10.2
Requires-Dist: jaxlib<0.12,>=0.10.2
Requires-Dist: jaxtyping>=0.3.3
Requires-Dist: numpy>=2.1
Provides-Extra: all
Requires-Dist: absl-py>=2.0.0; extra == 'all'
Requires-Dist: beartype>=0.18.0; extra == 'all'
Requires-Dist: chex>=0.1.86; extra == 'all'
Requires-Dist: cisternal>=0.1.7; extra == 'all'
Requires-Dist: complexipy>=5.6.1; extra == 'all'
Requires-Dist: duckdb>=1.1; extra == 'all'
Requires-Dist: equinox>=0.13.1; extra == 'all'
Requires-Dist: flatbuffers>=2; extra == 'all'
Requires-Dist: grain>=0.2.0; extra == 'all'
Requires-Dist: huggingface-hub<2,>=1; extra == 'all'
Requires-Dist: import-linter>=2.1; extra == 'all'
Requires-Dist: interrogate>=1.7.0; extra == 'all'
Requires-Dist: iree-base-compiler<4,>=3.11; extra == 'all'
Requires-Dist: iree-base-runtime<4,>=3.11; extra == 'all'
Requires-Dist: jaxlint>=0.1.0a1; extra == 'all'
Requires-Dist: libcst>=1.5.0; extra == 'all'
Requires-Dist: matplotlib>=3.8; extra == 'all'
Requires-Dist: optax>=0.2.3; extra == 'all'
Requires-Dist: orbax-checkpoint>=0.11.17; extra == 'all'
Requires-Dist: pandas>=2.0; extra == 'all'
Requires-Dist: pyarrow>=14.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23; extra == 'all'
Requires-Dist: pytest-benchmark>=5.2.3; extra == 'all'
Requires-Dist: pytest-cov>=7.1.0; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: pyyaml>=6.0; extra == 'all'
Requires-Dist: ruff>=0.15.22; extra == 'all'
Requires-Dist: safetensors<1,>=0.4; extra == 'all'
Requires-Dist: seaborn>=0.13; extra == 'all'
Requires-Dist: ty>=0.0.60; extra == 'all'
Requires-Dist: tyro<2,>=0.9.1; extra == 'all'
Requires-Dist: vl-convert-python>=1.0.0; extra == 'all'
Requires-Dist: zarr>=3.0.8; extra == 'all'
Requires-Dist: zstandard>=0.23; extra == 'all'
Provides-Extra: authoring-smoke
Requires-Dist: outlines>=1.0; extra == 'authoring-smoke'
Requires-Dist: torch>=2.0; extra == 'authoring-smoke'
Requires-Dist: transformers>=4.40; extra == 'authoring-smoke'
Provides-Extra: cli
Requires-Dist: flatbuffers>=2; extra == 'cli'
Requires-Dist: tyro<2,>=0.9.1; extra == 'cli'
Provides-Extra: controller
Requires-Dist: bathos<0.14,>=0.13.0a7; extra == 'controller'
Provides-Extra: data
Requires-Dist: absl-py>=2.0.0; extra == 'data'
Requires-Dist: grain>=0.2.0; extra == 'data'
Provides-Extra: dev
Requires-Dist: beartype>=0.18.0; extra == 'dev'
Requires-Dist: chex>=0.1.86; extra == 'dev'
Requires-Dist: complexipy>=5.6.1; extra == 'dev'
Requires-Dist: equinox>=0.13.1; extra == 'dev'
Requires-Dist: flatbuffers>=2; extra == 'dev'
Requires-Dist: import-linter>=2.1; extra == 'dev'
Requires-Dist: interrogate>=1.7.0; extra == 'dev'
Requires-Dist: jaxlint>=0.1.0a1; extra == 'dev'
Requires-Dist: libcst>=1.5.0; extra == 'dev'
Requires-Dist: optax>=0.2.3; extra == 'dev'
Requires-Dist: orbax-checkpoint>=0.11.17; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-benchmark>=5.2.3; extra == 'dev'
Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.15.22; extra == 'dev'
Requires-Dist: ty>=0.0.60; extra == 'dev'
Requires-Dist: tyro<2,>=0.9.1; extra == 'dev'
Provides-Extra: eda
Requires-Dist: matplotlib>=3.8; extra == 'eda'
Requires-Dist: pandas>=2.0; extra == 'eda'
Requires-Dist: pyarrow>=14.0; extra == 'eda'
Requires-Dist: seaborn>=0.13; extra == 'eda'
Requires-Dist: vl-convert-python>=1.0.0; extra == 'eda'
Provides-Extra: eda-all
Requires-Dist: altair>=5.0.0; extra == 'eda-all'
Requires-Dist: duckdb>=1.0.0; extra == 'eda-all'
Requires-Dist: pyarrow>=14.0.0; extra == 'eda-all'
Requires-Dist: vl-convert-python>=1.3.0; extra == 'eda-all'
Provides-Extra: eda-campaign
Requires-Dist: duckdb>=1.0.0; extra == 'eda-campaign'
Requires-Dist: pyarrow>=14.0.0; extra == 'eda-campaign'
Provides-Extra: eda-matplotlib
Requires-Dist: matplotlib>=3.8; extra == 'eda-matplotlib'
Requires-Dist: pandas>=2.0; extra == 'eda-matplotlib'
Requires-Dist: seaborn>=0.13; extra == 'eda-matplotlib'
Provides-Extra: eda-parquet
Requires-Dist: pyarrow>=14.0; extra == 'eda-parquet'
Provides-Extra: eda-vega
Requires-Dist: vl-convert-python>=1.0.0; extra == 'eda-vega'
Provides-Extra: eda-viz
Requires-Dist: altair>=5.0.0; extra == 'eda-viz'
Requires-Dist: vl-convert-python>=1.3.0; extra == 'eda-viz'
Provides-Extra: export
Requires-Dist: huggingface-hub<2,>=1; extra == 'export'
Requires-Dist: iree-base-compiler<4,>=3.11; extra == 'export'
Requires-Dist: iree-base-runtime<4,>=3.11; extra == 'export'
Requires-Dist: safetensors<1,>=0.4; extra == 'export'
Provides-Extra: export-runtime
Requires-Dist: huggingface-hub<2,>=1; extra == 'export-runtime'
Requires-Dist: iree-base-runtime<4,>=3.11; extra == 'export-runtime'
Requires-Dist: safetensors<1,>=0.4; extra == 'export-runtime'
Provides-Extra: index
Requires-Dist: duckdb>=1.1; extra == 'index'
Provides-Extra: io
Requires-Dist: zarr>=3.0.8; extra == 'io'
Provides-Extra: onnx
Requires-Dist: jax2onnx<0.18,>=0.17.0; extra == 'onnx'
Requires-Dist: onnx<2,>=1.23; extra == 'onnx'
Requires-Dist: onnxruntime<2,>=1.30; extra == 'onnx'
Provides-Extra: pack
Requires-Dist: zstandard>=0.23; extra == 'pack'
Provides-Extra: plugin
Requires-Dist: cisternal>=0.1.7; extra == 'plugin'
Provides-Extra: training
Requires-Dist: optax>=0.2.3; extra == 'training'
Requires-Dist: orbax-checkpoint>=0.11.17; extra == 'training'
Description-Content-Type: text/markdown

# xtrax

[![PyPI - Version](https://img.shields.io/pypi/v/xtrax.svg)](https://pypi.org/project/xtrax/)
[![Tests](https://github.com/maraxen/xtrax/actions/workflows/ci.yml/badge.svg)](https://github.com/maraxen/xtrax/actions)
[![Docs](https://img.shields.io/readthedocs/xtrax.svg)](https://xtrax.readthedocs.io)
[![Coverage](https://img.shields.io/badge/coverage-tier1%2095%25-brightgreen)](https://github.com/maraxen/xtrax)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/maraxen/xtrax/blob/main/LICENSE)

A set of composable building blocks for JAX training loops — engine + trainer orchestration, axis tiling strategies, distributed/sharding helpers, streaming output callbacks, and orbax checkpointing — extracted from the author's research code.

## Status

**xtrax is alpha, experimental software** built primarily for the author's personal research use. APIs may change without notice between releases; no backward-compatibility guarantees pre-1.0. Issues and pull requests are welcome, but support is best-effort — the project exists first to serve the author's own JAX training workflows.

## Why xtrax?

`jax.jit` specializes and freezes: it traces your function into a program where every shape is a compile-time constant, and XLA plans all memory for that program up front. The compiler makes the program you gave it fast, but it never restructures it — it cannot narrow a `vmap` that doesn't fit in memory, cannot batch ragged inputs without a recompile per shape, and cannot notice that most of a batch is duplicates. Those decisions happen in Python, before tracing — and the code that makes them is exactly what gets copy-pasted between research projects.

xtrax packages that pre-trace layer, plus the conveniences that surround it:

- **Axis tiling** — declare axes with `AxisSpec`; `BatchPlanner` selects `Vmap`, `ChunkedMap` (chunked via `jax.lax.map`), `Scan`, bucketing, or dedup-gather per axis, and `xtrax explain` reports why
- **Composable training steps** — `Trainer` with your own loss functions and optimizers
- **Safe arithmetic** — `safe_norm` and `safe_reciprocal`
- **Distributed helpers** — `LogicalMesh` and sharding utilities over JAX's native machinery

For the full rationale — why this layer has to live above the JIT boundary — see [Why xtrax exists](https://xtrax.readthedocs.io/en/latest/why-xtrax.html).

## Installation

```bash
pip install xtrax
# For `xtrax run` provenance persistence (zarr metrics stores), also:
pip install "xtrax[io]"
```

xtrax depends on JAX, optax and orbax, not on Equinox. Equinox models still work: they are
plain pytrees to xtrax. Install `equinox` yourself if you train one.

Requires Python 3.13 or later. The `xtrax run` CLI persists a provenance
store (`.xtrax/runs/<run_id>/metrics.zarr`) for every invocation by default
and fails loud before training if the `[io]` extra is missing. Add `.xtrax/`
to your project's `.gitignore`: run artifacts (manifests, checkpoints,
stores) should never dirty your tree — sink git-provenance capture reads
`git status`, and an un-ignored run dir would flip `git_dirty=True`.

## Quick Start

```python
import jax.numpy as jnp
import optax
from xtrax import Trainer, ResumableState, Engine, save_checkpoint, load_checkpoint

# 1. Create a simple loss function
def loss_fn(model, batch):
    predictions = model(batch["inputs"])
    return jnp.mean((predictions - batch["targets"]) ** 2)

# 2. Set up trainer with optimizer
optimizer = optax.adam(1e-3)
trainer = Trainer(loss_fn=loss_fn, optimizer=optimizer)

# 3. Initialize training state
model = ...  # Any pytree of arrays: a dict of arrays, an Equinox module, ...
opt_state = optimizer.init(...)
state = ResumableState(model=model, opt_state=opt_state, step=0)

# 4. Run a training step
new_state, metrics = trainer.step(state, batch={"inputs": x, "targets": y})
print(f"Loss: {metrics['loss']}")
```

For a complete training loop with callbacks and checkpointing, use the `Engine`:

```python
from xtrax import Engine, DataModule

# Create or load a DataModule (must implement train_iter())
data = DataModule(...)

# Create an engine with trainer and optional callbacks
engine = Engine(trainer=trainer)

# Run multi-epoch training with checkpoint saving
final_state = engine.fit_sync(
    state=state,
    data=data,
    num_epochs=10,
    checkpoint_dir="./checkpoints"
)
```

## Getting Results Out

### Streaming Callbacks

Log metrics asynchronously to files or external services:

```python
from xtrax.engine.io import BoundedCallbackHandler, async_indexed_stream

# Create a custom async callback
class LogCallback:
    async def on_step_end(self, state, metrics):
        print(f"Step {state.step}: {metrics}")

# Use in your Engine
engine = Engine(
    trainer=trainer,
    callbacks=[LogCallback()]
)
```

### Checkpoint Save and Load

Save model state and restore for inference or resumption:

```python
from xtrax import save_checkpoint, load_checkpoint

# After training
save_checkpoint(checkpoint_dir="./checkpoints/final", state=final_state)

# Load for inference
restored_state = load_checkpoint(checkpoint_dir="./checkpoints/final")
model = restored_state.model

# Run inference
predictions = model(test_inputs)
```

## Persistent Compilation Cache

Call `xtrax.jax_cache.configure()` once at process entry, before the first `jax.jit`, so
every process of a campaign reuses executables an earlier one compiled. `xtrax run` and
`xtrax campaign run` (every executor, including each Slurm array task) do this for you and
take `--compilation-cache PATH|off`.

Where the cache lives is a fact about the machine; whether a project uses it is a fact about
the project. They are configured separately:

- **Directory** (first match wins): the `path` argument, `$XTRAX_JAX_CACHE_DIR`,
  `$JAX_COMPILATION_CACHE_DIR`, then `${XDG_CONFIG_HOME:-~/.config}/xtrax/config.toml`.
  `none`, `off` or empty in any of them disables. xtrax carries no default path, and a
  directory in `pyproject.toml` is refused: a committed file is pushed to other machines.
- **On/off** (first match wins): `$XTRAX_JAX_CACHE`, then `jax_compilation_cache` under
  `[tool.xtrax]` in the nearest `pyproject.toml`, then the user config, else `on`. A
  project's `off` holds even when a cluster profile injects `$JAX_COMPILATION_CACHE_DIR`.

```toml
# once per machine: ~/.config/xtrax/config.toml (laptop, workstation, cluster login node)
jax_compilation_cache_dir = "/path/to/flash/jax_cache"
```

```toml
# the consuming project's pyproject.toml: policy and knobs only, never a path
[tool.xtrax]
jax_compilation_cache = "on"                     # or "off" to opt this project out
jax_cache_min_compile_time_secs = 2.0            # store only compiles that cost something
jax_cache_max_size_bytes = 5_000_000_000         # LRU eviction (needs filelock)
```

```python
from xtrax import jax_cache

setting = jax_cache.configure()   # CacheSetting(dir, source, enabled, policy, ...)
```

`setting.source` and `setting.policy_source` name the deciding layers. With nothing
configured anywhere, xtrax leaves JAX's own settings alone. A configured off clears JAX's flag
(JAX would otherwise read `JAX_COMPILATION_CACHE_DIR=none` as a directory named `none`).
On a Slurm cluster, put the directory on a flash tier without a file-count cap, writable only
by you. JAX treats cache entries as trusted code. Entries go under `jaxlib-<version>/` inside the
directory (JAX's key already includes the version, so this only makes pruning easy);
`jax_cache_namespace = "cpu-flags"` adds a host-CPU-ISA segment for CPU executables shared
across mixed nodes, and `"none"` uses the directory as given. JAX writes entries
non-atomically, so a preempted write can leave a truncated entry; run
`jax_cache.prune_corrupt()` between attempts. See the `xtrax.jax_cache` docstring for the
knobs and file-count caveats.

## Documentation

Full API docs, architecture guides, and advanced examples at [xtrax.readthedocs.io](https://xtrax.readthedocs.io).

## Project links

- [GitHub repository](https://github.com/maraxen/xtrax)
- [Issue tracker](https://github.com/maraxen/xtrax/issues)
- [Changelog](CHANGELOG.md)
- [Contributing guide](CONTRIBUTING.md)
- [Citation metadata](CITATION.cff)

## License

Licensed under the [Apache License 2.0](https://github.com/maraxen/xtrax/blob/main/LICENSE).

## Citation

If you use xtrax in research, please cite it:

```bibtex
@software{xtrax,
  title = {xtrax: High-Performance Composable JAX Training},
  author = {Russo, Marielle},
  version = {0.4.0a6},
  year = {2026},
  url = {https://github.com/maraxen/xtrax}
}
```
