K092203 · K092203 · Jun 10, 2026 · Jun 10, 2026
diff --git a/.github/ISSUE_TEMPLATE/benchmark_report.yml b/.github/ISSUE_TEMPLATE/benchmark_report.yml
@@ -0,0 +1,25 @@
+name: Benchmark / real-world result
+description: Share results from using TRust-BO on a real problem (good or bad!)
+labels: [benchmark]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem description
+      description: What did you optimize? Dimensions, budget, constraints.
+    validations:
+      required: true
+  - type: textarea
+    id: results
+    attributes:
+      label: Results
+      description: Best value found, wall-clock time, comparison with other tools if any.
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      placeholder: "Ubuntu 24.04, Python 3.11, laptop CPU (no GPU)"
+    validations:
+      required: false
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,34 @@
+name: Bug report
+description: Something doesn't work as expected
+labels: [bug]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug, and what you expected instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal reproduction
+      description: The smallest script that reproduces the problem.
+      render: python
+    validations:
+      required: false
+  - type: input
+    id: version
+    attributes:
+      label: TRust-BO version / commit
+      placeholder: "0.1.0 / abc1234"
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Python version, Rust version (if building from source).
+      placeholder: "Ubuntu 24.04, Python 3.11, rustc 1.85"
+    validations:
+      required: true
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,18 @@
+name: Feature request
+description: Suggest an idea or improvement
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the use case — e.g. the optimization problem you're trying to run.
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: What you'd like to happen. API sketches welcome.
+    validations:
+      required: false
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,10 @@
+## Summary
+
+<!-- What does this PR change, and why? -->
+
+## Checklist
+
+- [ ] Tests added/updated (`pytest` for Python-facing behavior, `cargo test` for Rust internals)
+- [ ] `cargo test --release` passes
+- [ ] `maturin develop --release && pytest tests/ -q` passes
+- [ ] CHANGELOG.md updated (for user-facing changes)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -5,6 +5,7 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+  workflow_dispatch:
 
 jobs:
   test:
@@ -28,11 +29,15 @@ jobs:
       - name: Rust tests
         run: cargo test --release
 
+      # scipy / scikit-learn are required to import trust_bo while the
+      # deprecated TandemEngine (legacy-tandem extra) is still bundled
       - name: Install Python deps
-        run: pip install maturin numpy pytest
+        run: pip install pytest scipy scikit-learn
 
-      - name: Build extension
-        run: maturin develop --release
+      # `maturin develop` requires a virtualenv; `pip install .` builds the
+      # same wheel via the maturin build backend and works anywhere
+      - name: Build and install package
+        run: pip install .
 
       - name: Python tests
         run: pytest tests/ -q
diff --git a/.gitignore b/.gitignore
@@ -9,7 +9,14 @@ __pycache__/
 dist/
 .pytest_cache/
 
-# Artifacts
+# Build artifacts (built by `maturin develop`)
+*.so
+*.pyd
+
+# Generated outputs (benchmarks, CFD runs, reports)
+*.csv
 *.zip
 *.log
 results/
+final_report.txt
+task_log.txt
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,7 +3,7 @@
 All notable changes to this project will be documented in this file.
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [0.1.0] - 2026-06-11
+## [Unreleased]
 
 ### Added
 
@@ -19,7 +19,7 @@ Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **CFD-oriented examples**: NACA airfoil and F1 wing optimization pipelines
   with a mock CFD solver, drop-in replaceable with real OpenFOAM runs.
 - **Save/resume**: `engine.save("study.zip")` / `TRustBOEngine.load(...)`.
-- 71 tests passing (Python + Rust), CPU-only.
+- 83 tests passing (71 Python + 12 Rust), CPU-only.
 
 ### Deprecated
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -15,10 +15,13 @@ PRs are welcome. Start small — a typo fix or a single bug fix is a great first
 3. **Add tests** — `pytest` for Python-facing behavior, `cargo test` for Rust internals
 4. Make sure everything passes:
    ```bash
+   pip install maturin numpy pytest scipy scikit-learn
    cargo test --release
    maturin develop --release
    pytest tests/ -q
    ```
+   (`scipy` / `scikit-learn` are only needed while the deprecated
+   `TandemEngine` is still bundled — it will be removed in v0.2.)
 
 ## Code style
 

diff --git a/Cargo.toml b/Cargo.toml
@@ -2,13 +2,20 @@
 name = "trust-bo"
 version = "0.1.0"
 edition = "2021"
+description = "Trust Region Bayesian Optimization engine (TuRBO-style) with a CPU-only Rust core, exposed to Python via PyO3"
+license = "MIT"
+repository = "https://github.com/K092203/TRust-BO"
+authors = ["Kotaro Ozawa"]
 
 [lib]
 name = "trust_bo"
 crate-type = ["cdylib"]
 
 [dependencies]
-pyo3       = { version = "0.22", features = ["extension-module", "abi3-py39"] }
+# pyo3/extension-module is enabled by maturin (see [tool.maturin] in
+# pyproject.toml), not here — having it on by default breaks `cargo test`
+# linking: https://pyo3.rs/latest/faq#i-cant-run-cargo-test
+pyo3       = { version = "0.22", features = ["abi3-py39"] }
 serde      = { version = "1", features = ["derive"] }
 serde_json = "1"
 rand       = { version = "0.8", features = ["std_rng"] }

diff --git a/README.md b/README.md
@@ -2,8 +2,8 @@
 
 **Bayesian optimization that runs on the hardware you already have.**
 
+[![CI](https://github.com/K092203/TRust-BO/actions/workflows/ci.yml/badge.svg)](https://github.com/K092203/TRust-BO/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Tests](https://img.shields.io/badge/tests-83%20passed-brightgreen)]()
 [![Python](https://img.shields.io/badge/python-%3E%3D3.9-blue)]()
 [![Rust](https://img.shields.io/badge/built%20with-Rust-orange)]()
 
@@ -38,17 +38,16 @@ No GPU required. No cloud required. Just `pip install` and go.
 
 ## Installation
 
+TRust-BO is not on PyPI yet (it's on the roadmap). Build from source — all you need is a [Rust toolchain](https://rustup.rs/) and `pip`:
+
 ```bash
-pip install trust-bo
+git clone https://github.com/K092203/TRust-BO
+cd TRust-BO
+python -m venv .venv && source .venv/bin/activate
+pip install .
 ```
 
-> **Note:** The package is currently in active development. For the latest version, build from source:
-> ```bash
-> git clone https://github.com/K092203/TRust-BO
-> cd TRust-BO
-> pip install maturin
-> maturin develop --release
-> ```
+For development, use [maturin](https://github.com/PyO3/maturin) for fast rebuilds: `pip install maturin && maturin develop --release`.
 
 ---
 
@@ -93,6 +92,18 @@ engine.save("study.zip")
 engine = TRustBOEngine.load("study.zip")
 ```
 
+### Optuna integration
+
+Use TRust-BO as a drop-in [Optuna](https://optuna.org/) sampler:
+
+```python
+import optuna
+from trust_bo.integrations.optuna import TrustBoOptunaSampler
+
+study = optuna.create_study(sampler=TrustBoOptunaSampler(seed=42))
+study.optimize(objective, n_trials=100)
+```
+
 ---
 
 ## Benchmark
@@ -163,7 +174,7 @@ Key design choices:
 - [x] Single Trust Region (exploitation-focused)
 - [x] MLP Bootstrap Ensemble surrogate with warm start
 - [x] Constraint handling (feasibility surrogate)
-- [x] 47-test suite, CPU-only, PyO3 Python bindings
+- [x] 83-test suite (71 Python + 12 Rust), CPU-only, PyO3 Python bindings
 - [x] Benchmark vs BoTorch / HEBO / Random (Setting A/B complete)
 - [x] OSS release prep — MIT license, class name unified, known limitations documented
 - [x] Native Phase 2 (Rust Tandem Residual-GP): +32% at 50D, +55% at 10D, zero extra deps
@@ -187,6 +198,12 @@ Key design choices:
 
 ---
 
+## Development log
+
+The full development history — design decisions, phase-by-phase experiments, and benchmark notes — is kept in [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) (Japanese).
+
+---
+
 ## Contributing
 
 Contributions are welcome. This is a one-person project so far, and any help — bug reports, benchmark results on real problems, documentation, or code — is genuinely appreciated.

diff --git a/benchmark_phase2.csv b/benchmark_phase2.csv
diff --git a/benchmarks/README.md b/benchmarks/README.md
@@ -0,0 +1,16 @@
+# Benchmarks
+
+Scripts used to produce the numbers in the main [README](../README.md) and
+[docs/DEVELOPMENT.md](../docs/DEVELOPMENT.md). All scripts write their CSV
+output to the current directory (gitignored).
+
+| Script | Compares |
+|---|---|
+| `benchmark.py` / `benchmark_v2.py` | TRust-BO vs BoTorch (TuRBO-1) vs HEBO vs Random |
+| `benchmark_50d.py` | 50D Ackley: TRust-BO vs Random vs GP |
+| `benchmark_native.py` | Native Phase 2 (Rust) vs TandemEngineV2 (sklearn) vs TRust-BO |
+| `benchmark_multi_tr.py` / `_v2.py` | Multi Trust Region (TuRBO-M, experimental) |
+| `benchmark_tandem.py` / `_v2.py` | Deprecated sklearn TandemEngine |
+
+Comparison baselines require extra dependencies not used by TRust-BO itself
+(`botorch`, `hebo`, `scikit-learn`); install them as needed per script.
diff --git a/benchmark.py → benchmarks/benchmark.py b/benchmark.py → benchmarks/benchmark.py
diff --git a/benchmark_50d.py → benchmarks/benchmark_50d.py b/benchmark_50d.py → benchmarks/benchmark_50d.py
diff --git a/benchmark_multi_tr.py → benchmarks/benchmark_multi_tr.py b/benchmark_multi_tr.py → benchmarks/benchmark_multi_tr.py
diff --git a/benchmark_multi_tr_v2.py → benchmarks/benchmark_multi_tr_v2.py b/benchmark_multi_tr_v2.py → benchmarks/benchmark_multi_tr_v2.py
diff --git a/benchmark_native.py → benchmarks/benchmark_native.py b/benchmark_native.py → benchmarks/benchmark_native.py
diff --git a/benchmark_tandem.py → benchmarks/benchmark_tandem.py b/benchmark_tandem.py → benchmarks/benchmark_tandem.py
diff --git a/benchmark_tandem_v2.py → benchmarks/benchmark_tandem_v2.py b/benchmark_tandem_v2.py → benchmarks/benchmark_tandem_v2.py
diff --git a/benchmark_v2.py → benchmarks/benchmark_v2.py b/benchmark_v2.py → benchmarks/benchmark_v2.py
diff --git a/benchmarks/phase3_eval.csv b/benchmarks/phase3_eval.csv
diff --git a/cfd/f1wing_results.csv b/cfd/f1wing_results.csv
diff --git a/cfd/naca_results.csv b/cfd/naca_results.csv
diff --git a/DEVELOPMENT.md → docs/DEVELOPMENT.md b/DEVELOPMENT.md → docs/DEVELOPMENT.md