Examples#

Runnable scripts for the flows the guides describe, in two variants: hosted without the TauOpt package (the closed beta’s path) and local, in-process. Every flow comes in both: the quickstart loop, Branin, parallel workers, exhaustion, a mixed space, multiple metrics, an outcome constraint, an experimental-design run, one per model-tuning use case (XGBoost, scikit-learn, PyTorch), an ODE calibration, and a convergence plot; replay is local-only during the beta (it re-runs the engine in-process). Each takes --help.

The hosted, package-free scripts (*_rest.py) drive the hosted service over plain HTTP from Python’s standard library with TAUOPT_BASE_URL (the API, https://api.tauopt.com) and TAUOPT_TOKEN (a token minted at app.tauopt.com/settings/tokens): nothing of TauOpt to install, since the package is not distributed until the public release (five of the thirteen need their objective’s libraries; The hosted examples below names them). The MCP server is the hosted variant for agents: Use the MCP server.

The local scripts need the package and no server (maintainers and collaborators: from a clone of the repository, pip install "./python[all]"; pip install tauopt installs a placeholder during the beta; the model-tuning and plotting scripts also need the libraries listed under Optional dependencies). The two client-driven hosted scripts (branin_hosted.py, parallel_workers.py) need the package too and take --base-url and --token for a running TauOpt service, or the same two environment variables (preferred on shared machines: argv is world-readable).

Docs: the documentation index (quickstart, how-to, reference, explanation). The guide behind each example:

Example

Shows

quickstart_rest.py

The quickstart page’s loop against the hosted service with nothing installed: five REST calls from the standard library (create; per round a suggestion and an observation; the best; the archive), the service’s answers handled (a 429 waited out by Retry-After, space_exhausted as completion, redirects refused, a connection that fails before sending retried)

branin_rest.py

branin_hosted.py with no package: the same loop over plain HTTP, the provenance identity triple, the < 1.0 smoke assert; archives at the end unless --keep

parallel_workers_rest.py

parallel_workers.py with no package: N threads on one experiment over plain HTTP, bandwidth_full 429s as backpressure, quota 429s waited out until --deadline-s, --experiment-id reuse, the duplicate and bandwidth checks

exhaustion_rest.py

exhaustion_local.py with no package: drain the eight-point space over plain HTTP, read the proof receipt from the 409’s details (api.last_exhaustion), then the best

multimetric_rest.py

multimetric_local.py with no package: two minimized metrics with a threshold reported through values, the frontier from best_assignments; the seed as a config with timebox_mode: "caps"

mixed_space_rest.py

mixed_space_local.py with no package: the categorical + log-scale + grid + conditional + linear-constraint space over plain HTTP

experimental_design_rest.py

experimental_design.py with no package: value_stddev on every observation, num_solutions: 3 on the create

outcome_constraints_rest.py

outcome_constraints_local.py with no package: a strategy: "constraint" metric under a threshold, the feasibility check from the observations route

sklearn_cross_validation_rest.py

sklearn_cross_validation.py with no package: the RandomForest cross-validation objective, the loop over plain HTTP (scikit-learn installed, nothing else)

xgboost_tuning_rest.py

xgboost_tuning.py with no package: the XGBoost holdout objective over plain HTTP (scikit-learn and xgboost installed, nothing else)

pytorch_mlp_rest.py

pytorch_mlp.py with no package: the PyTorch MLP objective with the conditional momentum over plain HTTP (torch and scikit-learn installed, nothing else)

ode_calibration_rest.py

ode_calibration.py with no package: the oscillator calibration over plain HTTP (numpy and scipy installed, nothing else)

convergence_plot_rest.py

convergence_plot.py with no package: one experiment per seed over plain HTTP, the best-so-far PNG (matplotlib installed, nothing else)

branin_local.py

The whole loop, single objective: policy-routed asks, per-suggestion strategy provenance, best

mixed_space_local.py

Categorical + log-scale double + integer grid + a conditional parameter + a linear constraint; seeded determinism (run twice with the same seed, diff clean)

multimetric_local.py

Two minimized metrics with a threshold: gp_nehvi (noisy expected hypervolume improvement) via the default policy, Pareto frontier from best_assignments

exhaustion_local.py

Proven exhaustion is COMPLETION (default since 0.3.0): drain a tiny finite space, catch SpaceExhausted, read the proof receipt

quickstart-branin.ipynb

The notebook walkthrough: local half, then the hosted half over plain HTTP with no package, which reads TAUOPT_BASE_URL/TAUOPT_TOKEN from the environment and prints a skip line when either variable is unset

branin_hosted.py

The same Branin loop against a hosted service, plus the provenance identity triple (engine_version, engine_sha, deps_fingerprint)

parallel_workers.py

N workers sharing one experiment (--experiment-id reuses one, so a batch job array shares a single id): bandwidth_full 429s as EXPECTED backpressure, quota 429s waited out with retry_after until --deadline-s, duplicate-assignment and bandwidth-violation checks

sklearn_cross_validation.py

A scikit-learn RandomForest on a digits subsample, 3-fold cross-validated accuracy as the objective; an integer + a log-scale double + a categorical parameter

xgboost_tuning.py

XGBoost on the breast-cancer holdout, log-loss minimized; an integer, a log-scale double, an integer grid, and a plain double

pytorch_mlp.py

A two-hidden-layer PyTorch MLP on make_moons (CPU, one thread), validation accuracy maximized; momentum is conditional on optimizer == "sgd"

ode_calibration.py

Calibrating a damped oscillator (scipy solve_ivp) to noisy synthetic data: log10 MSE minimized, recovered vs true parameters printed

experimental_design.py

A noisy lab response surface: measurement noise reported through value_stddev on every observation, num_solutions=3 for three diverse good settings

outcome_constraints_local.py

Metrics mode with one optimized metric and one strategy: "constraint" metric under a threshold: best returns feasible points only

replay_suggestion.py

Record a suggestion’s provenance and the state it read, then re-derive it with ExperimentState.from_json + ask and assert equal assignments

convergence_plot.py

Best-so-far curves for two seeds saved to a PNG with matplotlib (Agg backend, no display)

The hosted examples (no package)#

Each hosted script is one file. On the docs site the names below link to the files themselves (save one into the directory you run python from); in the repository they sit beside this page: quickstart_rest.py, branin_rest.py, parallel_workers_rest.py, exhaustion_rest.py, multimetric_rest.py, mixed_space_rest.py, experimental_design_rest.py, outcome_constraints_rest.py, sklearn_cross_validation_rest.py, xgboost_tuning_rest.py, pytorch_mlp_rest.py, ode_calibration_rest.py, convergence_plot_rest.py.

With the two variables exported (the token minted at app.tauopt.com/settings/tokens), each script is one command in any Python 3.10 or newer, from this directory or a copy of the file anywhere. Eight of the thirteen need the standard library alone; the five that evaluate a model or draw a plot also need the library their table row names (one line installs them all: pip install numpy scipy scikit-learn xgboost-cpu matplotlib, and for pytorch_mlp_rest.py the CPU wheel, pip install torch --index-url https://download.pytorch.org/whl/cpu):

export TAUOPT_BASE_URL="https://api.tauopt.com"
export TAUOPT_TOKEN="tau_<the-value-the-tokens-page-showed>"
python quickstart_rest.py
python branin_rest.py
python parallel_workers_rest.py --workers 4
python exhaustion_rest.py
python multimetric_rest.py
python mixed_space_rest.py
python experimental_design_rest.py
python outcome_constraints_rest.py
python sklearn_cross_validation_rest.py
python xgboost_tuning_rest.py
python pytorch_mlp_rest.py
python ode_calibration_rest.py
python convergence_plot_rest.py

Without the variables each prints one line and exits 0 (that is how CI runs them). The helper the thirteen share (Api, ask, archive) is the same text in each file, so one script is a complete copy-paste start; python/tests/test_rest_examples.py pins the copies identical and runs all thirteen against a fake service over the local engine. The ten use-case twins carry the objective code of their local scripts (the libraries named above, and nothing else); nine of them pass the seed as an explicit config with timebox_mode: "caps", the load-independent mode a hosted user may set, and exhaustion_rest.py enumerates a finite eight-point space to proof and sends no config. replay_suggestion.py has no twin: replaying a suggestion re-runs the engine in-process, which the hosted service does not expose, so it stays local-only during the beta. The quickstart page walks the loop with a shorter inline version, and Run against the hosted service lists the calls one by one with curl.

The local examples#

Run one (dev checkout):

cd python && uv run python examples/branin_local.py

or, from this directory, python branin_local.py in any environment with tauopt[all] installed.

Optional dependencies#

The model-tuning and plotting scripts import scikit-learn, xgboost, and matplotlib inside main() and raise an ImportError naming the install line when one is missing; none of them is a dependency of the package. The root pyproject.toml lists them as the examples dependency group, or install them directly:

pip install scikit-learn xgboost-cpu matplotlib

pytorch_mlp.py runs on the CPU torch that tauopt[all] installs, and ode_calibration.py on the scipy that tauopt[local] installs.