Metadata-Version: 2.5
Name: bosun_call
Version: 0.1.0
Summary: A unified experiment runner for robot simulation
Project-URL: Homepage, https://git.whoi.edu/cthierauf/bosun_call
Project-URL: Repository, https://git.whoi.edu/cthierauf/bosun_call.git
Project-URL: Issues, https://git.whoi.edu/cthierauf/bosun_call/-/issues
Author-email: Chris Thierauf <christopher.thierauf@whoi.edu>
License: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.0
Requires-Dist: tomli>=1.1.0; python_version < '3.11'
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# bosun

A unified experiment runner for robot simulation. One configuration file, the `Bosunfile`,
composes a simulator, robot code, experiment code, and logging, the goal is that the same file runs on
whichever simulator a machine has. This is inspired by cross-compilation build systems: each
simulator is a build target, we're trying to deploy each experiment/test.

The distribution is `bosun_call` (after the boatswain's [call](https://en.wikipedia.org/wiki/Boatswain%27s_call));
it installs the `bosun` command. [`../spec.md`](../spec.md) is the spec implemented here and [`../demo`](../demo)
shows a working demonstration.

## Install

This implementation of the spec is available on PyPi:

```
pip install bosun_call
```

Requires Python >= 3.10. This provides you with a CLI tool to acquire simulators and run experiments
using a universal Bosunfile. No simulator is provided by default, any executable can be used as a simulator
but some simulators are popular enough to have built-in pull/build targets.

## `bosun` Commands

- `bosun run [task] [path=value ...] [-- args]`: Run a task confiugred in the Bosunfile. Exits with the worst leaf result.
- `bosun show <task> [path=value ...]`: View a task configuration with no side effects.
- `bosun list [--suite]`: List tasks.
- `bosun build [task]`: If conversion required (e.g., URDF->other), convert it and place it in the cache.
- `bosun targets`: Every simulator bosun has an install recipe for, with install readiness and tags.
- `bosun pull <sim> [--dry-run] [--force]`: Install a simulator on this machine using its recipe for this platform.

## `bosun` Architecture

```
src/bosun/
├── model.py         # pydantic models; placement is at_xyz / at_rpy / at_q
├── geometry.py      # world frame (ENU) + orientation (rpy or quat) normalization
├── loader/          # merge layers -> resolve inheritance/seeds/instances -> validate
├── drivers/
│   ├── base.py      # the driver stdin/stdout JSON protocol (spec)
│   ├── proxy.py     # SubprocessDriver: run a driver executable and speak the protocol
│   └── registry.py  # load a target's driver command; discover bosun.converters
├── convert/         # model conversion, content-hash cached per target
├── install.py       # bosun pull / bosun targets: recipes that acquire simulators
├── runner/
│   ├── lifecycle.py # target -> build -> launch -> spawn -> programs -> run -> after -> check
│   ├── process.py   # env assembly, process groups, timeouts, {python} substitution
│   ├── monitor.py   # poll the driver's poses() -> poses.jsonl
│   └── manifest.py  # write bosun.toml (resolved config, env, exit codes, git sha)
└── cli.py
```

## Adding new simulators

A simulator target is any executable: `[target.mysim] driver = "<command>"`. Bosun launches it in
the project directory and interfaces with a line-delimited JSON protocol (resolve/version/launch/ready/
spawn/poses/stop) over its stdin/stdout as described in the spec. Optionally
register a converter in the `bosun.converters` entry-point group (keyed `"<source_format>:<target>"`)
and add an install recipe so `bosun pull` can acquire the sim. See the spec's driver protocol and
the `demo/sim` drivers.

## License

Apache-2.0 (see [LICENSE](LICENSE)).