cadaques 0.1.0

Cost-Aware Dual Architecture for QUery-Efficient diScovery: autonomous discovery campaigns — any oracle, any driver, one budget.

CADAQUES

Cost-Aware Dual Architecture for QUery-Efficient diScovery

An open-source framework for autonomous discovery campaigns: any oracle, any driver, one budget.

CADAQUES decouples autonomous discovery into two symmetric protocols. A metered Oracle abstracts anything that answers queries at a price — a simulator, a laboratory instrument, an analytic function. A Driver abstracts anything that decides what to ask next — random search, Bayesian optimization, gradient methods, LLM agents. Between them sits the framework's one structural commitment: cost is a first-class primitive. Every oracle query and every driver decision is priced in heterogeneous currencies (wall time, CPU hours, euros, tokens) and charged against a single campaign budget. Campaigns end when the budget is exhausted, not when an iteration counter runs out, and all results are reported as performance per unit cost. Every query counts.

Installation

pip install git+https://github.com/jorgebravoabad/cadaques.git

Or, for development:

git clone https://github.com/jorgebravoabad/cadaques.git
cd cadaques
pip install -e .

A PyPI release is planned; see the roadmap below.

Quickstart: a discovery campaign with an exact answer

Locate the critical temperature of the 2D Ising model by maximizing the magnetic susceptibility under a fixed compute budget. Onsager's exact result, T_c = 2/ln(1+√2) ≈ 2.269, provides the ground truth against which any driver can be validated.

from cadaques import Budget, Campaign, Cost
from cadaques.drivers import AnnealedLocalDriver
from cadaques.oracles import Ising2DOracle, T_C_EXACT

oracle = Ising2DOracle(seed=0)
driver = AnnealedLocalDriver(
    space={"T": (1.5, 3.5)},
    fidelity={"L": 24, "sweeps": 400},
    seed=0,
)
campaign = Campaign(oracle, driver, Budget(total=Cost(seconds=30.0)))

outcome = campaign.run()
print(f"Best T = {outcome.best.query.params['T']:.3f}  (exact: {T_C_EXACT:.3f})")
print(f"Queries: {outcome.n_queries}, stop reason: {outcome.stop_reason}")
print(f"Spent: {outcome.budget.spent}")

Design principles

• Dual agnosticism. Oracles and Drivers are typing.Protocol classes with two methods each. Anything that speaks the protocol plugs in.
• 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, and the discrepancy is itself an observable.
• 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?
• 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.

This is an early release: the API may evolve until 1.0. Planned next steps include a Bayesian-optimization driver, campaign replay, expanded documentation, a PyPI release, and an LLM-agent driver adapter.

Citation

If you use CADAQUES in academic work, please cite it (see CITATION.cff). A Zenodo DOI badge will appear here upon release.

License

MIT.