Bolero runs complete research campaigns: autonomous agents propose research questions, execute governed analyses against a real dataset and literature corpus, integrate what they learn into an explicit knowledge graph, and write the result up as a manuscript that stands to independent review. Every scientific action happens inside a sealed container under typed contracts, so the evidence trail behind every claim is inspectable end to end. This repository contains the whole platform: the exploration harness, the Bolero Code agent runtime, the World viewer, and the environment kits used by sealed scientific runs.

Highlights

• Sealed execution — every agent call runs in a container with exactly one writable workspace; the dataset, the literature corpus, and the knowledge store are read-only mounts, and the model is reached through a harness-provided socket, not the open network.
• Typed contracts, not vibes — every artifact an agent leaves behind is validated against pydantic contracts by in-container stop gates and again by the host before it can advance the campaign.
• An explicit World — what the campaign knows lives in an epistemic graph of Atoms (evidence-backed claims with typed, weighted bonds) and Molecules (publication storylines over them), browsable live in the bundled viewer.
• All-or-nothing knowledge integration — each exploration loop commits its findings to the World as one validated transaction; a failed wave leaves the canonical store untouched.
• Human-owned publication — sending a storyline to the publication lane is the operator's readiness decision; an independent in-lane review gates the manuscript, and a request for new evidence hands control back to the operator instead of papering over it.
• Reproducible by construction — frozen campaign configuration, a Git history inside every session, and (under Singularity or Apptainer) a runtime image resolved once at campaign birth to its content digest and never changed mid-run; Docker resolves references at each call, so pin a dated tag or digest there yourself.

How it works

flowchart LR
    subgraph s1["Stage 1 — exploration, one loop per pass"]
        A["allocation"] --> P["proposals"] --> T["tournament"]
        T --> L["plan → execute → review<br/>(parallel lanes)"]
        L --> W["world integration"]
    end
    W -->|one transaction per loop| WORLD[("the World<br/>Atoms + Molecules")]
    WORLD --> A
    WORLD --> B
    subgraph s2["Stage 2 — publication, operator-triggered"]
        B["blueprint"] --> D["draft"] --> R["independent review"]
    end
    R --> M["manuscript"]

Stage 1 — exploration. Each loop allocates frontier regions to parallel proposers, holds a tournament over their candidate research questions, and runs one plan → execute → review lane per accepted proposal against the governed dataset. Accepted results are minted into Atoms, and one world-integration wave restructures the Molecule layer over them — applied to the World as a single all-or-nothing transaction before the next loop begins.

Stage 2 — publication. For one operator-selected Molecule, the lane turns the storyline into a blueprint, drafts the manuscript with its figures, and submits it to an independent review stage that either accepts, directs bounded in-place repairs, or ends the run asking the operator for new evidence.

Quickstart

Prerequisites

• Linux on x86_64 with Conda and Git ≥ 2.28 (a campaign session records its history in its own Git repository, created with git init -b)
• Node.js 22.x for host-side interactive use of Bolero Code (the shipped router addon is built for that line; sealed calls use the image's own Node)
• Singularity, Apptainer, or Docker
• CPUs for the configured parallelism: the packaged default (campaign.max_parallelism=8, two governed threads per call) requires 16 available logical CPUs at launch; on a smaller machine lower campaign.max_parallelism on the launch command
• an already-deployed OpenAI-compatible model endpoint serving the model the harness is configured for — the packaged default is qwen3.8-flash-next at http://127.0.0.1:30000 (bolero-harness/bolero/conf/llm/default.yaml). This README assumes that deployment (SGLang in production) is already up; the serving recipes live in envs/llm/. If the endpoint runs on another machine, expose it to this one through an SSH tunnel.

Install

Bolero is one Python distribution, bolero-ai, carrying three import packages — the exploration harness (bolero), the Bolero Code SDK (bolero_code_sdk), and the World viewer (bolero_world) — plus one non-Python runtime bundle that the harness provisions itself. The wheel always ships all of the code; the extras are dependency groups: [harness] the Stage-1 driver's stack, [code] the SDK's, [world] nothing (the viewer is standard library only), [offline] the runtime bundle as a PyPI distribution, [all] the union of the three functional groups, [test] the host test suite's own tools on top of [all]. Python 3.11 or newer on Linux is required (requires-python = ">=3.11"; the suite is proven on 3.11 and 3.13, and every compiled dependency — kuzu, networkit, numpy, scipy — ships wheels for both). Create an environment carrying such an interpreter plus the host-side gate binaries the publication drivers shell out to (pdftotext, pandoc; tectonic rides along for parity with the baked runtime), and install from PyPI:

conda create -n bolero -c conda-forge python=3.11 pip poppler poppler-data pandoc tectonic
conda activate bolero
pip install "bolero-ai[all]==0.1.9"

(From a checkout, conda env create -f environment.yml builds the same environment, and pip install -e '.[harness]' installs the tree editably.)

(Production installs use [all]; a bare pip install bolero-ai ships all of the code but none of the third-party stacks, so pick at least the groups you will run.)

Provision the Bolero Code runtime — the compiled CLI, its pinned claude-code-router, the launcher and the container wrappers — into ~/.local/share/bolero-code, then run the prerequisite diagnostic — interpreter, packages, bolero-code, container engine, image reference, endpoint reachability:

bolero-harness setup
export PATH="$HOME/.local/bin:$PATH"   # where setup links bolero-code
bolero-harness doctor

Hosts that reach PyPI and not GitHub

setup downloads the runtime bundle from the matching GitHub Release. A host without GitHub takes the same bundle through PyPI instead, and gets the repository itself the same way:

pip install "bolero-ai[all,offline]==0.1.9"
bolero-harness setup      # reads the bundle from the installed distribution
bolero-harness download   # writes the repository into the current directory

download unpacks the source tree the release wheel carries — the same tree a clone would give, minus its Git history — and works on a bare pip install bolero-ai. The Danish register corpus travels the same road as its own distribution: bolero-harness denmark [dir] fetches the newest bolero-denmark release from PyPI and unpacks it, falling back to an installed copy only when PyPI cannot be fetched or serves no usable release. What pip cannot carry is the runtime container image: it is ~13 GB, lives at ghcr.io, and must reach such a host by other means, addressed with runtime_images.<engine>=/absolute/path.sif.

The runtime container image is not installed. Under Singularity or Apptainer, at every campaign's birth the driver pulls oras://ghcr.io/northwestern-cssi/bolero-runtime:sif-latest once into ~/.cache/bolero/images/ under its SHA-256 and freezes that file for the session, so the newest published image starts each new campaign and no running campaign ever changes image; a local SIF path is frozen as the real file behind its symlinks. Docker references are resolved by the engine at each call — pin one yourself by naming a dated tag or digest (runtime_images.docker=ghcr.io/northwestern-cssi/bolero-runtime:<date>).

Run the Palmer Penguins demo

Install the Bolero Code project profile, scaffold the complete demo, and let the bolero-demo Skill check, run, monitor, and audit it:

bolero demo penguins

The generated Harness launcher can also be run directly:

cd penguins
bash run-explore.sh

The script checks the Bolero Code runtime, detects the available container engine, and launches the campaign. First use pulls the runtime image from ghcr.io. On a terminal it opens the live TUI. Ctrl-C closes only the TUI; the campaign continues in its detached driver. Reattach from the demo directory, and serve the session's current World from another terminal, with:

bolero-harness status
conda activate bolero && bolero-harness world   # http://127.0.0.1:3000/

Stage 2 — publication — is a separate, operator-triggered lane, and sending a Molecule to it is the readiness decision: the driver stamps it draft: true and runs the in-place blueprint → manuscript → independent-review lane on the World in hand — it never re-enters exploration. It also takes the session's exclusive driver lock, so it runs after exploration ends: wait for the stop target, or stop the driver from the TUI (the space gesture, behind a confirm). When exploration has built a storyline worth writing, pick its id in the World viewer and run from the penguins/ directory:

bolero-harness publish \
  --session outputs/<YYYY-MM-DD>/penguins-demo \
  --molecule molecule-NNNNNN

--mode defaults to the session's frozen mode, bolero-harness status attaches to it like the exploration run, and a reviewer request for new evidence ends the run with exit code 2 for the operator to act on.

The CLI at a glance

Bolero Code is the project-level entrypoint; the Harness CLI remains the exact runtime and pipeline surface:

bolero-explore and bolero-publish remain direct entry points for the two stage drivers, and every campaign tunable is a Hydra override on the launch command. Every sealed stage call also records a resumable agent session inside its campaign directory: from that directory, bolero -r lists and continues those sessions in their original container environment, and bolero -r <stage-label> -p "question" asks a one-shot follow-up (see bolero-code/README.md, "Resuming agent sessions").

Repository layout

Documentation

• bolero-harness/README.md — the operator guide: configuration, scenarios, campaign control, progress and resuming
• bolero-code/README.md — the agent runtime: CLI, router, sealed sessions, and session resume
• envs/llm/SERVING.md — the model-serving recipes behind the endpoint prerequisite
• envs/container/ — how the scientific runtime image is built and published

License

MIT © Northwestern-CSSI