Metadata-Version: 2.4
Name: rundra
Version: 0.1.5
Summary: Portable experiment execution for scientific computing
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Dist: pyyaml>=6.0.2,<7
Requires-Dist: tqdm>=4.67,<5
Requires-Dist: mcp>=2,<3 ; extra == 'mcp'
Requires-Python: >=3.12, <3.13
Provides-Extra: mcp
Description-Content-Type: text/markdown

# Rundra

Rundra is a portable experiment-execution framework for reproducible scientific
computing. It provides stable run and task identities, explicit stochastic
seeds, structured JSON output, immutable staged inputs, scheduler integration,
and result retrieval through one command-line interface.

## Installation

Rundra requires Python 3.12. Install the command as an isolated user tool:

```bash
uv tool install rundra
rundr --version
rundr help
```

Install the optional MCP interface with:

```bash
uv tool install 'rundra[mcp]'
rundr-mcp --help
```

## Basic workflow

An experiment combines an executable command, a YAML configuration, explicit
resources, and one or more integer seeds:

```bash
rundr validate experiment.yaml --json
rundr plan experiment.yaml --seeds 0:3 --json
rundr submit experiment.yaml --seeds 0:3
rundr wait --last --progress
rundr fetch --last
```

`rundr run` performs submission, waiting, and retrieval synchronously. Remote
targets can combine SSH transport, a Slurm or OpenPBS scheduler, rsync or shared
staging, and an Apptainer container runtime. Site connection, account, queue,
workspace, and authentication policy remain explicit operator configuration.

If an asynchronous submission is interrupted, `rundr resume RUN_ID` recovers
its durable scheduler outcome without creating a duplicate Run. `rundr list`
returns compact paginated summaries, while `rundr tasks RUN_ID` pages through
Task details. Automatic fetch can avoid redundant bulk transfer when client and
target paths are safely visible through the same filesystem.

## Automation

All important lifecycle commands support structured JSON. The optional MCP
server exposes the same operation layer over stdio or authenticated Streamable
HTTP, including submission recovery and paginated discovery. Network transport
requires an environment-sourced bearer token and an explicit host policy; TLS
should terminate at an operator-managed reverse proxy.

Rundra does not store SSH keys, passwords, registry credentials, or scheduler
credentials. Run only experiment definitions and source trees that you trust,
because their declared commands execute with the configured user's privileges.

The source repository contains development documentation, examples, schemas,
and the complete test suite.
