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), [embedding] the verified SPECTER2 stack, [all] the union. Python 3.11 on Linux is required (requires-python = ">=3.11,<3.12": the kuzu and networkit wheels the World graph depends on ship for 3.11). Create an environment carrying that 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.7"

(From a checkout, conda env create -f environment.yml builds the same environment, and pip install -e '.[harness,embedding]' 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 — from the matching GitHub Release into ~/.local/share/bolero-code, then run the prerequisite diagnostic — interpreter, packages, bolero-code, container engine, image reference, endpoint reachability, embedding extra:

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

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

Scaffold the complete demo — dataset, literature corpus, seed molecules, configuration, and launcher — and start the exploration campaign:

bolero-harness demo penguins && cd penguins
bash bolero-explore.sh

The script checks the Bolero Code runtime, detects the available container engine, and launches the campaign. First use provisions two downloads: the runtime image from ghcr.io, and the ~450 MB SPECTER2 encoder from huggingface.co into ~/.cache/bolero/specter2 (offline hosts point BOLERO_SPECTER2_ROOT at a pre-provisioned snapshot instead). 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

Everything operational stands behind one umbrella command:

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