Metadata-Version: 2.4
Name: bolero-ai
Version: 0.1.6
Summary: Bolero — a governed autonomous-research platform: the exploration harness, the Bolero Code SDK, and the World viewer in one distribution
Author: Northwestern-CSSI
License-Expression: MIT
Project-URL: Homepage, https://github.com/Northwestern-CSSI/Bolero
Project-URL: Repository, https://github.com/Northwestern-CSSI/Bolero
Project-URL: Issues, https://github.com/Northwestern-CSSI/Bolero/issues
Keywords: bolero,autonomous-research,agent,llm,scientific-discovery
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: <3.12,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: code
Requires-Dist: hydra-core<1.4,>=1.3; extra == "code"
Requires-Dist: jinja2<4,>=3.1; extra == "code"
Requires-Dist: omegaconf<3,>=2.3; extra == "code"
Requires-Dist: pydantic<3,>=2.9; extra == "code"
Requires-Dist: PyYAML<7,>=6; extra == "code"
Provides-Extra: harness
Requires-Dist: bolero-ai[code]; extra == "harness"
Requires-Dist: httpx~=0.28.1; extra == "harness"
Requires-Dist: hydra-core~=1.3; extra == "harness"
Requires-Dist: kuzu~=0.11; extra == "harness"
Requires-Dist: markdown-it-py~=4.2.0; extra == "harness"
Requires-Dist: networkit~=11.1; extra == "harness"
Requires-Dist: networkx~=3.4; extra == "harness"
Requires-Dist: numpy~=2.1; extra == "harness"
Requires-Dist: omegaconf~=2.3; extra == "harness"
Requires-Dist: pydantic~=2.9.0; extra == "harness"
Requires-Dist: python-frontmatter~=1.3.0; extra == "harness"
Requires-Dist: PyYAML~=6.0.3; extra == "harness"
Requires-Dist: rich~=15.0; extra == "harness"
Requires-Dist: scipy~=1.14; extra == "harness"
Requires-Dist: textual~=8.2; extra == "harness"
Provides-Extra: world
Provides-Extra: embedding
Requires-Dist: torch<=2.13.0,>=2.5; extra == "embedding"
Requires-Dist: transformers<=4.57.6,>=4.45; extra == "embedding"
Requires-Dist: adapters<=1.3.0,>=1.1; extra == "embedding"
Requires-Dist: huggingface_hub<=0.36.2; extra == "embedding"
Provides-Extra: all
Requires-Dist: bolero-ai[code,embedding,harness,world]; extra == "all"
Dynamic: license-file

# 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/`:

```bash
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`](envs/llm/SERVING.md) for the quickstart and
[`envs/llm/DEPLOYMENT_INSTRUCT.md`](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:

```bash
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`](environment.yml)):

```bash
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):

```bash
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):

```bash
bolero-harness setup
```

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

```bash
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:

```bash
bolero-harness demo penguins && cd penguins
```

Start the exploration campaign:

```bash
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:

```bash
bolero-harness status
```

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

```bash
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

| Path | Purpose |
|---|---|
| `bolero-harness/` | exploration driver, typed stage contracts, TUI, and demo |
| `bolero-code/` | agent CLI, router, SDK, and sealed-container launcher |
| `bolero-world/` | local World graph viewer |
| `envs/` | scientific runtime-image and model-serving environment kits |

Detailed operator and configuration documentation lives in
[`bolero-harness/README.md`](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.
