Bolero

Bolero is a governed AI-scientist platform that turns empirical evidence into human-owned, peer-reviewable scientific claims. This repository contains the exploration harness, the Bolero Code agent runtime, the World viewer, and the environment kits used by sealed scientific runs.

Deploy Qwen3.8-Flash-Next with SGLang

Bolero expects an OpenAI-compatible model endpoint serving the model the harness is configured for — the packaged default is qwen3.8-flash-next (bolero-harness/bolero/conf/llm/default.yaml). On the GPU serving host, clone this repository and use the production reference under envs/llm/:

gh auth login && gh auth setup-git
gh repo clone Northwestern-CSSI/Bolero && cd Bolero/envs/llm
bash serve-qwen38fn-sglang.sh start      # health-wait built in
bash serve-qwen38fn-sglang.sh status && bash serve-qwen38fn-sglang.sh test

This recipe serves Qwen3.8-Flash-Next-FP8 with SGLang on four H100 GPUs at http://127.0.0.1:30000 with a 262,144-token context. Its model, cache, and SIF paths are deliberately host-specific; adapt those variables before launch. The DeepSeek V4 Flash recipes (serve-dsv4-flash.sh, serve-vllm-dsv4-flash.sh) remain as the rollback lane; serving them means overriding llm.bolero_code.model, display_name, context_window, and reasoning_effort together on every launch. See envs/llm/SERVING.md for the quickstart and envs/llm/DEPLOYMENT_INSTRUCT.md for the full deployment contract. If Bolero runs on another machine, expose this loopback endpoint to it through an SSH tunnel.

Requirements

• Linux with Conda, Git, and the GitHub CLI (gh)
• 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
• an OpenAI-compatible model endpoint; the demo defaults to http://127.0.0.1:30000

The repository is currently private. On the machine that will run Bolero, authenticate once and let Git use the GitHub CLI credential helper:

gh auth login && gh auth setup-git

Install 0.1.6

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). The bolero conda environment declared at the repository root carries that interpreter plus the host-side gate binaries the publication drivers shell out to (pdftotext, pandoc; see environment.yml):

conda env create -f environment.yml && conda activate bolero

Install everything (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):

pip install "bolero-ai[all]==0.1.6"

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, with bolero-code linked into ~/.local/bin (set GH_TOKEN first while the release is private):

bolero-harness setup

Then check the machine end to end — interpreter, packages, bolero-code, container engine, runtime image, LLM endpoint, embedding extra:

bolero-harness doctor

The runtime container image is not installed: 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.

Run the Palmer Penguins demo

Scaffold the complete demo and enter it:

bolero-harness demo penguins && cd penguins

Start the exploration campaign:

bash bolero-explore.sh

The script checks the Bolero Code runtime, detects the available container engine, and launches the campaign. 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 with:

bolero-harness status

Once the session exists, open another terminal in the penguins/ directory and serve its current World:

conda activate bolero && bolero-harness world

Open http://127.0.0.1:3000/. Stop the viewer with Ctrl-C; this does not stop the campaign.

Repository layout

Detailed operator and configuration documentation lives in bolero-harness/README.md.

Session resume

Every sealed stage call records a resumable agent session inside its campaign directory (.bolero/projects/). 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") for the full contract.