🧪 BO Forge v1.1.4

BO Forge is a practical Bayesian optimisation campaign tool with notebook, CLI, and local Streamlit workflows. The reusable BO logic lives in the bo_forge Python package, while notebooks, the CLI, and the app wrap that package.

v1.1.4 builds on the first stable public release with coupled multi-objective qLogEHVI campaigns, Pareto-front reporting, hypervolume progress, noisy replicate-aware GP fitting, review/replicate metadata support, and deterministic cost-aware multi-objective batch ranking while keeping the same YAML/CSV/session/CLI foundation.

v1.1.4 also closes the v1.1.x line with a faster local Streamlit workbench: active-panel rendering, less redundant raw data display, coupled multi-objective observation entry, lazy reports/plots, and Forge Suite UI performance polish.

BO Forge deliberately supports only:

• continuous, integer, discrete, and categorical variables
• single-objective campaigns, plus coupled multi-objective campaigns with m >= 2 objectives
• maximize or minimize direction
• Sobol or random initial suggestions
• BoTorch SingleTaskGP
• LogEI/qLogEI for single-objective campaigns and qLogEHVI for coupled multi-objective campaigns
• CSV campaign logs
• optional feasibility constraints
• optional cost-aware ranking and human review
• optional replicate tracking, replicate-derived observation variance, and replicate-aware aggregation
• resume from existing logs
• basic diagnostics, Pareto-front plots, and hypervolume progress
• a notebook-first CampaignSession workflow
• a small bo-forge CLI workflow
• a local Streamlit workbench

It intentionally does not yet cover qLogNEI/qLogNEHVI, learned noise models, decoupled or asynchronous multi-objective evaluation, learned cost models, cost-as-objective optimization, database-backed storage, or a production multi-user web backend. The primary tested multi-objective range is 2 <= m <= 4; larger objective counts are advanced usage because qLogEHVI, non-dominated partitioning, hypervolume, and visualization become more expensive.

---

🧰 Install

Install the backend package and CLI:

pip install bo-forge

Install the local Streamlit workbench:

pip install "bo-forge[app]"

For local development from a clone:

python3 -m venv .venv
./.venv/bin/pip install -e ".[dev]"

Check the installed version and environment:

bo-forge --version
bo-forge doctor

Launch the packaged local app:

bo-forge-app

The module entrypoint is also supported:

python -m bo_forge --version

---

🔁 Workflow

flowchart LR
    A["YAML config"] --> B["Load CSV log"]
    B --> C["Validate campaign data"]
    C --> D{"Enough observations?"}
    D -- "No" --> E["Sobol/random suggestion"]
    D -- "Yes" --> F["Fit SingleTaskGP"]
    F --> G["Score LogEI / qLogEI"]
    G --> H["Suggest candidate(s)"]
    E --> H
    H --> I["Append status=suggested"]
    I --> J["Run experiment"]
    J --> K["mark_observed()"]
    K --> B

Loading

The Streamlit app is intentionally a thin wrapper.

Future interfaces should keep wrapping this backend package rather than moving BO logic into notebooks, CLI commands, or app code.

---

🗂️ Repository Structure

bo-forge/
├── bo_forge/       # reusable backend package
├── bo_forge_app/   # local Streamlit wrapper
├── configs/        # YAML campaign configs
├── examples/       # seed CSV logs and runnable scripts
├── notebooks/      # notebook-first campaign workflows and deeper simulated demos
├── reports/        # generated local reports and figures
├── docs/           # quickstart, CLI, schema, troubleshooting, repo guide
└── tests/          # pytest coverage

---

📚 Documentation

• docs/QUICKSTART.md: setup, quickstart commands, session API example, notebooks, and diagnostics.
• docs/INSTALLATION.md: pip install tutorial for core, app, development, wheel, and sdist installs.
• docs/CLI.md: terminal workflow and command reference.
• docs/STREAMLIT_APP.md: local Streamlit app setup and workflow.
• docs/09_APP_CREATED_CAMPAIGN_TUTORIAL.md: step-by-step tutorial for creating a new campaign inside the app.
• docs/CLI_ERROR_EXAMPLES.md: intentional CLI failures with expected error and hint output.
• docs/CSV_SCHEMA.md: canonical CSV columns, allowed values, blanks, and status transitions.
• docs/COMMON_ERRORS.md: troubleshooting guide for common YAML and CSV errors.
• docs/PUBLIC_API.md: stable public imports supported by the bo_forge package.
• docs/RELEASE_CHECKLIST.md: GitHub and PyPI release checklist.
• docs/REPOSITORY_STRUCTURE.md: detailed package layout and development workflow.
• CHANGELOG.md: release history.
• ROADMAP_V0_TO_V1.md: completed milestones through v1.0.0.
• ROADMAP_V1_X.md: v1.x direction.

---

📌 Tested Versions

The primary dependency source is pyproject.toml.

A direct-dependency snapshot from the v1.1.4 environment is recorded in requirements-lock.txt.

---

👤 Author

Angze Li