cadaques 0.2.0__tar.gz → 0.3.0__tar.gz

{cadaques-0.2.0 → cadaques-0.3.0}/.github/workflows/ci.yml

@@ -1,6 +1,6 @@
 name: CI
 on:
-  push: { branches: [main] }
+  push: { branches: ["**"] }
   pull_request:
 jobs:
   test:
@@ -12,5 +12,5 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with: { python-version: "${{ matrix.python-version }}" }
-      - run: pip install -e ".[dev]"
+      - run: pip install -e ".[dev,bo]"
       - run: python -m pytest tests/ -q --cov=cadaques

{cadaques-0.2.0 → cadaques-0.3.0}/.gitignore

@@ -10,3 +10,5 @@ docs/_build/
 docs/_build/
 .DS_Store
 demo_campaign.jsonl # opcional: y ckpt_demo/ si quieres
+examples/next_experiments.csv
+studies/results/

{cadaques-0.2.0 → cadaques-0.3.0}/CHANGELOG.md

@@ -5,7 +5,52 @@ the pre-1.0 stability policy. The claim of record is the latest tag.
 
 ## [Unreleased]
 
-## [0.2.0] — 2026-08
+## [0.3.0] — 2026-08 — DOI: [10.5281/zenodo.22028069](https://doi.org/10.5281/zenodo.22028069) 
+
+The generality proof: retrospective campaigns over real data, cost-aware
+intelligence, audited statistics, recommendation mode, and the first
+domain vertical — on the unchanged 0.2 kernel.
+
+### Added
+- **DatasetOracle** (`oracles/dataset.py`): a measured table as an Oracle —
+  declared miss policy (`nearest` within normalized tolerance, or FAILED
+  `dataset_miss` settling the tariff: a miss consumes budget), deterministic
+  economics with optional per-row recorded cost columns, `from_csv`,
+  data-derived `.bounds`, and `.as_history()` for recommendation mode.
+- **BayesianDriver** (`drivers/bo.py`, extra `cadaques[bo]`): Matérn GP +
+  Expected Improvement per predicted unit cost (cost surrogate fitted on the
+  driver's own settled history), budget-annealed exploration via
+  `fraction_used`, cost-aware flat-EI fallback, `rank()` for batch scoring;
+  scikit-learn stays out of core (lazy import).
+- **cadaques.stats**: paired bootstrap CI and Wilcoxon signed-rank on NumPy
+  alone (exact null to n=25, tie/continuity-corrected approximation beyond),
+  `compare()`/`Comparison.summary()`, and seed-paired `paired_campaigns()`.
+- **Recommendation mode** (`runtime/recommend.py`): `recommend()` →
+  `RankedCandidates` — seeded bit-for-bit reproducible, provenanced (driver
+  spec, history sha256, schema `cadaques.recommendation/1`), metered thinking
+  time, `to_csv`/`to_json`; task constraints filter the candidate pool
+  *before* ranking.
+- **Chemistry vertical** (`verticals/chemistry.py`): `ReactionTable` — column
+  roles (composition, conditions, objective, cost) compiled to kernel
+  objects; `recommend_next()` and `campaign()` frontends; end-to-end
+  `examples/chemistry_recommend.py`.
+- **Studies package** (`studies/`): frozen protocol v1 for the vertical paper
+  — pinned quartet (Ising, OCM-291 featurized, Olympus snar/fullerenes with
+  real per-row costs), 20 paired seeds × 4 drivers, pre-registered honesty
+  notes, `run_study.py --smoke` verified on all four.
+
+### Changed
+- Reference drivers consume rng in **sorted parameter order** (ADR-0012), so
+  canonical-JSON spec round-trips and dict orderings cannot alter a seeded
+  campaign. Seeded sequences differ from 0.2 in multi-parameter spaces; the
+  paper reproduction stays pinned at `v0.1.0-paper`.
+- CI runs on all branches and installs `[dev,bo]`.
+
+### Compatibility
+- No interface changes; all 0.2 and 0.1 imports and constructor calls
+  unchanged; 107 tests.
+
+## [0.2.0] — 2026-08 — DOI: [10.5281/zenodo.21915298](https://doi.org/10.5281/zenodo.21915298)
 
 The campaign becomes a durable object: the twelve-object kernel of the
 campaign architecture, event-sourced and replayable, with full 0.1

{cadaques-0.2.0 → cadaques-0.3.0}/CITATION.cff

@@ -8,7 +8,7 @@ authors:
     given-names: "Jorge"
     affiliation: "Universidad Autónoma de Madrid, IFIMAC"
     orcid: "https://orcid.org/0000-0001-6876-8022"
-version: 0.2.0
+version: 0.3.0
 date-released: 2026-08-07
 license: MIT
 repository-code: "https://github.com/jorgebravoabad/cadaques"

{cadaques-0.2.0 → cadaques-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cadaques
-Version: 0.2.0
+Version: 0.3.0
 Summary: Cost-Aware Dual Architecture for QUery-Efficient diScovery: autonomous discovery campaigns — any oracle, any driver, one budget.
 Project-URL: Repository, https://github.com/jorgebravoabad/cadaques
 Author-email: Jorge Bravo-Abad <jorge.bravo@uam.es>
@@ -14,6 +14,8 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Physics
 Requires-Python: >=3.10
 Requires-Dist: numpy>=1.24
+Provides-Extra: bo
+Requires-Dist: scikit-learn>=1.3; extra == 'bo'
 Provides-Extra: dev
 Requires-Dist: mypy; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
@@ -47,7 +49,8 @@ per unit cost. *Every query counts.*
 ## Installation
 
 ```bash
-pip install cadaques
+pip install cadaques          # core: NumPy only
+pip install "cadaques[bo]"    # + the Gaussian-process driver (scikit-learn)
 ```
 
 Or, for development, install the latest version from source:
@@ -84,7 +87,7 @@ print(f"Queries: {outcome.n_queries}, stop reason: {outcome.stop_reason}")
 print(f"Spent: {outcome.budget.spent}")
 ```
 
-## The campaign is a durable object (0.2)
+## The campaign is a durable object (since 0.2)
 
 Since 0.2 a campaign is not a script you ran once — it is a declarative,
 inspectable, replayable object:
@@ -131,10 +134,62 @@ What this buys, concretely:
 - **Conformance suites.** `cadaques.testing` ships the Oracle/Driver/
   Resource contract checks; external adapters are encouraged to run them.
 
+## From a spreadsheet to the next experiments (0.3)
+
+The first domain vertical. A chemist declares column roles once — composition
+descriptors, reaction conditions, an objective, a recorded cost per run — and
+the table compiles to kernel objects:
+
+```python
+from cadaques.verticals import ReactionTable
+
+table = ReactionTable.from_csv(
+    "reactions.csv",
+    objective="c2_yield",
+    composition=("x_Mn", "x_Ce"),
+    conditions=("T", "P"),
+    cost_columns={"seconds": "run_s"},
+)
+
+# Recommendation mode: which experiments should the lab run next?
+ranking = table.recommend_next(k=5, seed=42)     # requires: pip install "cadaques[bo]"
+print(ranking.summary())
+ranking.to_csv("next_experiments.csv")           # for the lab notebook
+
+# Campaign mode: would Bayesian optimization have beaten random on this table?
+from cadaques import Budget, Cost
+from cadaques.drivers import BayesianDriver, RandomDriver
+from cadaques.stats import paired_campaigns
+
+result = paired_campaigns(
+    lambda seed: table.campaign(BayesianDriver(space=table.oracle().bounds),
+                                Budget(total=Cost(seconds=25000)), seed=seed),
+    lambda seed: table.campaign(RandomDriver(space=table.oracle().bounds),
+                                Budget(total=Cost(seconds=25000)), seed=seed),
+    seeds=range(20), metric=lambda o: o.best.value, alternative="greater",
+)
+print(result.summary())   # paired bootstrap CI + Wilcoxon, quotable as-is
+```
+
+Behind this sit the 0.3 components: **`DatasetOracle`** (a measured table as a
+hidden oracle, with a *declared* miss policy — a dataset miss is a FAILED result
+that settles its declared cost — and deterministic economics that can replay
+recorded per-row costs); **`BayesianDriver`** (Matérn GP with Expected
+Improvement *per predicted unit cost*, learned from the driver's own settled
+history, exploration annealed with `fraction_used`); **`cadaques.stats`** (paired
+bootstrap and Wilcoxon on NumPy alone, exact null to n=25); and **recommendation
+mode** (`recommend()` → a ranked, seeded, bit-for-bit reproducible object whose
+provenance records the driver's declaration, a fingerprint of the history, and
+the measured *thinking time* — the price of intelligence, attached to the advice
+it produced). A frozen retrospective-benchmark protocol over four public
+datasets lives in `studies/`.
+
 ## Design principles
 
 - **Dual agnosticism.** Oracles and Drivers are `typing.Protocol` classes with
-  two methods each. Anything that speaks the protocol plugs in.
+  two methods each. Anything that speaks the protocol plugs in. Since 0.2 the
+  dual architecture has an operational counterpart: `Resource`
+  (submit/status/collect) with an `OracleResource` adapter.
 - **Declared vs. settled cost.** Oracles declare a price *ex ante*
   (`oracle.price(query)`); the actual cost is settled *ex post* inside each
   `Result`. Real oracles deviate from their estimates — the ledger records both,
@@ -142,31 +197,15 @@ What this buys, concretely:
 - **Both sides are metered.** Driver decisions cost wall time — and tokens, if the
   driver is an LLM agent. A campaign's economics include the price of intelligence,
   enabling the question: *when does an expensive smart driver beat a cheap dumb one?*
+- **Failure is a result.** A failed evaluation — an oracle exception, a dataset
+  miss — settles its declared cost and stays on the record, exactly like a wasted
+  experiment.
 - **Budget-aware strategies.** Drivers receive a read-only `BudgetView` and may
   adapt: the reference `AnnealedLocalDriver` explores while rich and exploits
-  while poor.
-- **The ledger is the provenance.** Every transaction (declared, settled,
-  timestamped) exports to JSONL: a complete, replayable trace of the campaign.
-
-## Status and roadmap
-
-`0.1.0` — core protocols, campaign runner, multi-currency budget and ledger,
-reference drivers, and a canonical Ising-2D oracle with fidelity-dependent cost.
-Available on [PyPI](https://pypi.org/project/cadaques/) and archived on
-[Zenodo](https://doi.org/10.5281/zenodo.21293589).
-
-This is an early release: the API may evolve until `1.0`. Planned next steps
-include a Bayesian-optimization driver, campaign replay, expanded documentation,
-and an LLM-agent driver adapter.
-
-## Citation
-
-If you use CADAQUES in academic work, please cite it (see `CITATION.cff`).
-DOI: [10.5281/zenodo.21293589](https://doi.org/10.5281/zenodo.21293589)
-
-## License
-
-MIT.
+  while poor; `BayesianDriver` anneals its exploration margin the same way.
+- **The event log is the provenance.** Every transition (declared, settled,
+  timestamped, schema-versioned) exports to JSONL: a complete, replayable trace
+  of the campaign, from which the accounting ledger is derived.
 
 ## Status, stability and roadmap
 
@@ -176,22 +215,40 @@ roadmap below is a plan, not a feature list.
 
 *Stability policy (ADR-0010).* Semantic versioning; nothing public breaks
 without a deprecation shim spanning at least two minor releases. The exact
-implementation accompanying the arXiv paper is permanently tagged
-(`v0.1.0`) and its imports run against every release via compatibility
-shims (`cadaques.core.protocols`, `cadaques.core.campaign`,
-`CampaignResult`). Durable design decisions live in `docs/adr/`.
+implementation accompanying v1 of the arXiv paper is permanently tagged
+(`v0.1.0-paper`), and its imports run against every release via compatibility
+shims (`cadaques.core.protocols`, `cadaques.core.campaign`, `CampaignResult`).
+Durable design decisions live in `docs/adr/`.
 
 *Kernel (shipped in 0.2).* Task · Query/Result and the general
 Action/Observation envelopes · Driver · Oracle · Resource (with the
 `OracleResource` adapter) · Campaign · Budget · Event · Artifact ·
 Outcome · CampaignSpec — the twelve objects of the campaign
 architecture, with event-sourced state, seed streams, replay,
-checkpoint/resume and public conformance suites.
-
-*Roadmap (not yet shipped).* A Bayesian-optimization driver and a
-hidden-dataset oracle for retrospective studies; a statistics module for
-paired driver comparisons; asynchronous executors and a Slurm-backed
-workflow resource behind the frozen Resource lifecycle (ADR-0007);
-declarative constraint vocabulary for specs; plugin entry points for
-external drivers and oracles. See `ARCHITECTURE.md` and
-`docs/adr/` for boundaries and decision gates.
+checkpoint/resume and public conformance suites (`cadaques.testing`).
+
+*Generality proof (shipped in 0.3).* `DatasetOracle` for retrospective
+campaigns over measured tables; the cost-aware `BayesianDriver` (extra
+`cadaques[bo]`); the audited `cadaques.stats` module; recommendation mode
+(`recommend()`, `RankedCandidates`); the chemistry vertical
+(`ReactionTable`); and the frozen study protocol in `studies/`.
+
+*Roadmap (not yet shipped).* Asynchronous executors and a Slurm-backed
+workflow resource behind the frozen Resource lifecycle (ADR-0007); a
+portfolio Driver allocating budget across strategies as a cost-aware
+bandit; native categorical and mixed search spaces; declarative
+constraint vocabulary for specs; plugin entry points for external
+drivers and oracles; an LLM-agent driver adapter with token metering.
+See `ARCHITECTURE.md` and `docs/adr/` for boundaries and decision gates.
+
+## Citation
+
+If you use CADAQUES in academic work, please cite it (see `CITATION.cff`).
+Concept DOI (always resolves to the latest version):
+[10.5281/zenodo.21293589](https://doi.org/10.5281/zenodo.21293589).
+Version DOIs are listed per release in [`CHANGELOG.md`](CHANGELOG.md).
+Paper: [arXiv:2607.16127](https://arxiv.org/abs/2607.16127).
+
+## License
+
+MIT.

{cadaques-0.2.0 → cadaques-0.3.0}/README.md

@@ -21,7 +21,8 @@ per unit cost. *Every query counts.*
 ## Installation
 
 ```bash
-pip install cadaques
+pip install cadaques          # core: NumPy only
+pip install "cadaques[bo]"    # + the Gaussian-process driver (scikit-learn)
 ```
 
 Or, for development, install the latest version from source:
@@ -58,7 +59,7 @@ print(f"Queries: {outcome.n_queries}, stop reason: {outcome.stop_reason}")
 print(f"Spent: {outcome.budget.spent}")
 ```
 
-## The campaign is a durable object (0.2)
+## The campaign is a durable object (since 0.2)
 
 Since 0.2 a campaign is not a script you ran once — it is a declarative,
 inspectable, replayable object:
@@ -105,10 +106,62 @@ What this buys, concretely:
 - **Conformance suites.** `cadaques.testing` ships the Oracle/Driver/
   Resource contract checks; external adapters are encouraged to run them.
 
+## From a spreadsheet to the next experiments (0.3)
+
+The first domain vertical. A chemist declares column roles once — composition
+descriptors, reaction conditions, an objective, a recorded cost per run — and
+the table compiles to kernel objects:
+
+```python
+from cadaques.verticals import ReactionTable
+
+table = ReactionTable.from_csv(
+    "reactions.csv",
+    objective="c2_yield",
+    composition=("x_Mn", "x_Ce"),
+    conditions=("T", "P"),
+    cost_columns={"seconds": "run_s"},
+)
+
+# Recommendation mode: which experiments should the lab run next?
+ranking = table.recommend_next(k=5, seed=42)     # requires: pip install "cadaques[bo]"
+print(ranking.summary())
+ranking.to_csv("next_experiments.csv")           # for the lab notebook
+
+# Campaign mode: would Bayesian optimization have beaten random on this table?
+from cadaques import Budget, Cost
+from cadaques.drivers import BayesianDriver, RandomDriver
+from cadaques.stats import paired_campaigns
+
+result = paired_campaigns(
+    lambda seed: table.campaign(BayesianDriver(space=table.oracle().bounds),
+                                Budget(total=Cost(seconds=25000)), seed=seed),
+    lambda seed: table.campaign(RandomDriver(space=table.oracle().bounds),
+                                Budget(total=Cost(seconds=25000)), seed=seed),
+    seeds=range(20), metric=lambda o: o.best.value, alternative="greater",
+)
+print(result.summary())   # paired bootstrap CI + Wilcoxon, quotable as-is
+```
+
+Behind this sit the 0.3 components: **`DatasetOracle`** (a measured table as a
+hidden oracle, with a *declared* miss policy — a dataset miss is a FAILED result
+that settles its declared cost — and deterministic economics that can replay
+recorded per-row costs); **`BayesianDriver`** (Matérn GP with Expected
+Improvement *per predicted unit cost*, learned from the driver's own settled
+history, exploration annealed with `fraction_used`); **`cadaques.stats`** (paired
+bootstrap and Wilcoxon on NumPy alone, exact null to n=25); and **recommendation
+mode** (`recommend()` → a ranked, seeded, bit-for-bit reproducible object whose
+provenance records the driver's declaration, a fingerprint of the history, and
+the measured *thinking time* — the price of intelligence, attached to the advice
+it produced). A frozen retrospective-benchmark protocol over four public
+datasets lives in `studies/`.
+
 ## Design principles
 
 - **Dual agnosticism.** Oracles and Drivers are `typing.Protocol` classes with
-  two methods each. Anything that speaks the protocol plugs in.
+  two methods each. Anything that speaks the protocol plugs in. Since 0.2 the
+  dual architecture has an operational counterpart: `Resource`
+  (submit/status/collect) with an `OracleResource` adapter.
 - **Declared vs. settled cost.** Oracles declare a price *ex ante*
   (`oracle.price(query)`); the actual cost is settled *ex post* inside each
   `Result`. Real oracles deviate from their estimates — the ledger records both,
@@ -116,31 +169,15 @@ What this buys, concretely:
 - **Both sides are metered.** Driver decisions cost wall time — and tokens, if the
   driver is an LLM agent. A campaign's economics include the price of intelligence,
   enabling the question: *when does an expensive smart driver beat a cheap dumb one?*
+- **Failure is a result.** A failed evaluation — an oracle exception, a dataset
+  miss — settles its declared cost and stays on the record, exactly like a wasted
+  experiment.
 - **Budget-aware strategies.** Drivers receive a read-only `BudgetView` and may
   adapt: the reference `AnnealedLocalDriver` explores while rich and exploits
-  while poor.
-- **The ledger is the provenance.** Every transaction (declared, settled,
-  timestamped) exports to JSONL: a complete, replayable trace of the campaign.
-
-## Status and roadmap
-
-`0.1.0` — core protocols, campaign runner, multi-currency budget and ledger,
-reference drivers, and a canonical Ising-2D oracle with fidelity-dependent cost.
-Available on [PyPI](https://pypi.org/project/cadaques/) and archived on
-[Zenodo](https://doi.org/10.5281/zenodo.21293589).
-
-This is an early release: the API may evolve until `1.0`. Planned next steps
-include a Bayesian-optimization driver, campaign replay, expanded documentation,
-and an LLM-agent driver adapter.
-
-## Citation
-
-If you use CADAQUES in academic work, please cite it (see `CITATION.cff`).
-DOI: [10.5281/zenodo.21293589](https://doi.org/10.5281/zenodo.21293589)
-
-## License
-
-MIT.
+  while poor; `BayesianDriver` anneals its exploration margin the same way.
+- **The event log is the provenance.** Every transition (declared, settled,
+  timestamped, schema-versioned) exports to JSONL: a complete, replayable trace
+  of the campaign, from which the accounting ledger is derived.
 
 ## Status, stability and roadmap
 
@@ -150,22 +187,40 @@ roadmap below is a plan, not a feature list.
 
 *Stability policy (ADR-0010).* Semantic versioning; nothing public breaks
 without a deprecation shim spanning at least two minor releases. The exact
-implementation accompanying the arXiv paper is permanently tagged
-(`v0.1.0`) and its imports run against every release via compatibility
-shims (`cadaques.core.protocols`, `cadaques.core.campaign`,
-`CampaignResult`). Durable design decisions live in `docs/adr/`.
+implementation accompanying v1 of the arXiv paper is permanently tagged
+(`v0.1.0-paper`), and its imports run against every release via compatibility
+shims (`cadaques.core.protocols`, `cadaques.core.campaign`, `CampaignResult`).
+Durable design decisions live in `docs/adr/`.
 
 *Kernel (shipped in 0.2).* Task · Query/Result and the general
 Action/Observation envelopes · Driver · Oracle · Resource (with the
 `OracleResource` adapter) · Campaign · Budget · Event · Artifact ·
 Outcome · CampaignSpec — the twelve objects of the campaign
 architecture, with event-sourced state, seed streams, replay,
-checkpoint/resume and public conformance suites.
-
-*Roadmap (not yet shipped).* A Bayesian-optimization driver and a
-hidden-dataset oracle for retrospective studies; a statistics module for
-paired driver comparisons; asynchronous executors and a Slurm-backed
-workflow resource behind the frozen Resource lifecycle (ADR-0007);
-declarative constraint vocabulary for specs; plugin entry points for
-external drivers and oracles. See `ARCHITECTURE.md` and
-`docs/adr/` for boundaries and decision gates.
+checkpoint/resume and public conformance suites (`cadaques.testing`).
+
+*Generality proof (shipped in 0.3).* `DatasetOracle` for retrospective
+campaigns over measured tables; the cost-aware `BayesianDriver` (extra
+`cadaques[bo]`); the audited `cadaques.stats` module; recommendation mode
+(`recommend()`, `RankedCandidates`); the chemistry vertical
+(`ReactionTable`); and the frozen study protocol in `studies/`.
+
+*Roadmap (not yet shipped).* Asynchronous executors and a Slurm-backed
+workflow resource behind the frozen Resource lifecycle (ADR-0007); a
+portfolio Driver allocating budget across strategies as a cost-aware
+bandit; native categorical and mixed search spaces; declarative
+constraint vocabulary for specs; plugin entry points for external
+drivers and oracles; an LLM-agent driver adapter with token metering.
+See `ARCHITECTURE.md` and `docs/adr/` for boundaries and decision gates.
+
+## Citation
+
+If you use CADAQUES in academic work, please cite it (see `CITATION.cff`).
+Concept DOI (always resolves to the latest version):
+[10.5281/zenodo.21293589](https://doi.org/10.5281/zenodo.21293589).
+Version DOIs are listed per release in [`CHANGELOG.md`](CHANGELOG.md).
+Paper: [arXiv:2607.16127](https://arxiv.org/abs/2607.16127).
+
+## License
+
+MIT.

cadaques-0.3.0/examples/chemistry_recommend.py

@@ -0,0 +1,68 @@
+"""The first vertical, end to end: a reaction CSV in, ranked experiments out.
+
+A chemist's table — composition descriptors, reaction conditions, a
+target property, a cost per run — becomes, with one role declaration:
+(a) a ranked, reproducible, provenanced recommendation for the next
+experiments, and (b) a budgeted retrospective campaign for method
+comparison. Run:
+
+    pip install "cadaques[bo]"
+    python examples/chemistry_recommend.py
+"""
+
+from pathlib import Path
+
+from cadaques import Budget, Cost
+from cadaques.drivers import BayesianDriver, RandomDriver
+from cadaques.stats import paired_campaigns
+from cadaques.verticals import ReactionTable
+
+HERE = Path(__file__).parent
+
+# --- a small synthetic OCM-style table (replace with your CSV) -----------
+ROWS = [
+    {"x_Mn": 0.10, "x_Ce": 0.05, "T": 700, "P": 1.0, "c2_yield": 0.18, "run_s": 3600},
+    {"x_Mn": 0.20, "x_Ce": 0.05, "T": 750, "P": 1.0, "c2_yield": 0.29, "run_s": 3650},
+    {"x_Mn": 0.20, "x_Ce": 0.10, "T": 800, "P": 1.5, "c2_yield": 0.43, "run_s": 3800},
+    {"x_Mn": 0.25, "x_Ce": 0.10, "T": 820, "P": 1.6, "c2_yield": 0.47, "run_s": 3850},
+    {"x_Mn": 0.30, "x_Ce": 0.15, "T": 850, "P": 2.0, "c2_yield": 0.44, "run_s": 4000},
+    {"x_Mn": 0.15, "x_Ce": 0.20, "T": 760, "P": 1.8, "c2_yield": 0.33, "run_s": 3700},
+    {"x_Mn": 0.28, "x_Ce": 0.08, "T": 840, "P": 1.4, "c2_yield": 0.45, "run_s": 3900},
+]
+
+table = ReactionTable(
+    rows=ROWS,
+    objective="c2_yield",
+    composition=("x_Mn", "x_Ce"),
+    conditions=("T", "P"),
+    cost_columns={"seconds": "run_s"},
+    tariff={"seconds": 3800.0},
+    name="ocm_demo",
+)
+
+# --- (a) recommendation mode: what should the lab try next? ---------------
+ranking = table.recommend_next(k=5, seed=42)
+print(ranking.summary())
+out_csv = HERE / "next_experiments.csv"
+ranking.to_csv(out_csv)
+print(f"\nExported for the lab notebook: {out_csv}")
+
+# --- (b) campaign mode: would BO have beaten random on this table? ---------
+def make(driver_cls):
+    def factory(seed: int):
+        t = ReactionTable(**{**table.__dict__, "tolerance": 0.8})
+        drv = (BayesianDriver(space=t.oracle().bounds, n_initial=3)
+               if driver_cls is BayesianDriver
+               else RandomDriver(space=t.oracle().bounds))
+        return t.campaign(drv, Budget(total=Cost(seconds=25000.0)),
+                          seed=seed, meter_driver=False)
+    return factory
+
+comparison = paired_campaigns(
+    make(BayesianDriver), make(RandomDriver),
+    seeds=range(8),
+    metric=lambda o: o.best.value,
+    metric_name="best c2_yield under equal budget",
+    alternative="greater",
+)
+print("\n" + comparison.summary())

{cadaques-0.2.0 → cadaques-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cadaques"
-version = "0.2.0"
+version = "0.3.0"
 description = "Cost-Aware Dual Architecture for QUery-Efficient diScovery: autonomous discovery campaigns — any oracle, any driver, one budget."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -22,6 +22,7 @@ dependencies = ["numpy>=1.24"]
 
 [project.optional-dependencies]
 dev = ["pytest>=7", "pytest-cov", "mypy", "ruff"]
+bo = ["scikit-learn>=1.3"]
 docs = ["sphinx>=8", "furo"]
 
 [project.urls]

{cadaques-0.2.0 → cadaques-0.3.0}/src/cadaques/__init__.py

@@ -5,6 +5,8 @@ any oracle, any driver, one budget. Every query counts.
 """
 
 from .runtime.campaign import Campaign, CampaignResult, DriverStopped, Outcome
+from . import stats
+from .runtime.recommend import Candidate, RankedCandidates, recommend
 from .runtime.replay import checkpoint, replay, resume
 from .runtime.state import CampaignState, reduce
 from .core.cost import Budget, BudgetExceeded, BudgetView, Cost
@@ -19,10 +21,10 @@ from .protocols.driver import Driver
 from .protocols.oracle import Oracle
 from .protocols.resource import JobHandle, JobStatus, OracleResource, Resource
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "Budget", "BudgetExceeded", "BudgetView", "Campaign", "CampaignResult", "CampaignSpec", "SpecError",
     "Cost", "Driver", "Event", "EventLog", "DriverStopped", "Ledger", "Oracle", "OracleResource", "Query", "Resource",
-    "Action", "FailureRecord", "Observation", "ObservationStatus", "Outcome", "CampaignState", "Result", "SearchSpace", "store_artifact", "checkpoint", "replay", "resume", "Task", "InvalidQuery", "Transaction", "__version__",
+    "Action", "FailureRecord", "Observation", "ObservationStatus", "Outcome", "CampaignState", "Result", "SearchSpace", "store_artifact", "Candidate", "RankedCandidates", "checkpoint", "recommend", "replay", "resume", "Task", "InvalidQuery", "Transaction", "__version__",
 ]

cadaques-0.3.0/src/cadaques/drivers/__init__.py

@@ -0,0 +1,14 @@
+"""Reference drivers. BayesianDriver requires the [bo] extra and is
+imported lazily so core installs stay light (ADR-0008)."""
+
+from .reference import AnnealedLocalDriver, RandomDriver
+
+__all__ = ["AnnealedLocalDriver", "BayesianDriver", "RandomDriver"]
+
+
+def __getattr__(name: str):
+    if name == "BayesianDriver":
+        from .bo import BayesianDriver
+
+        return BayesianDriver
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")