Skip to main content

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); it installs the bosun command. ../spec.md is the spec implemented here and ../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).

Metadata

Release files for bosun-call 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bosun-call 0.1.0
File Size Uploaded Provenance Actions
bosun_call-0.1.0.tar.gz 49.7 kB Without provenance Details for bosun_call-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bosun-call 0.1.0
File Interpreter ABI Platform Actions
bosun_call-0.1.0-py3-none-any.whl Python 3 none any Details for bosun_call-0.1.0-py3-none-any.whl

Total release size: 103.8 kB

Release files / bosun_call-0.1.0.tar.gz

Download URL bosun_call-0.1.0.tar.gz
Size 49.7 kB
Tags Source
SHA-256 checksum
How to use checksums
98b835ea5a0aa58d0acbcd72e37cf0498cc122843af7e5078e99d31916399173
BLAKE2b-256 checksum
How to use checksums
fe257efa71cfb10730904bd1c91479673849058926d6fdf46c494e5151197c5e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.0

Release files / bosun_call-0.1.0-py3-none-any.whl

Download URL bosun_call-0.1.0-py3-none-any.whl
Size 54.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
77b8abc057dc0606017ca113e1d01d4693136483cce9684e86e5e11e73915ab0
BLAKE2b-256 checksum
How to use checksums
fc0bb12acf2f0853bd22f1d967b98cf8e18e6167d076294b710fecc0a7b9682b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.0

Security for bosun-call 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page