strategies.run_adaptive_sweep

strategies.run_adaptive_sweep(
    cli,
    config,
    *,
    registry,
    session_id,
    objective=None,
    remote=False,
    api_key=None,
    endpoint=None,
    quiet=False,
    load_config=None,
    stop_on_failure=True,
    jfr=None,
    enable_profiler=False,
    stream_output=False,
)

Run an adaptive sweep using Optuna.

Unlike run_sweep(), this generates jobs on-demand based on Optuna’s suggestions, loading results after each run to inform the next trial.

The lifecycle for each trial: 1. Sample parameters from Optuna trial 2. Create and register job for these params 3. Execute CLI for all replicates 4. Wait briefly for export writes to settle 5. Load CSV results with retries 6. Evaluate objective function 7. Report metric back to Optuna and store in registry

Note: Optuna runs trials serially (one at a time). Josh maintains parallel replicate execution internally. Metrics wait for all replicates to finish before evaluation.

Parameters

Name	Type	Description	Default
cli	Any	JoshCLI instance to use for execution.	required
config	Any	JobConfig with OptunaStrategy configured.	required
registry	RunRegistry	RunRegistry for tracking (required).	required
session_id	str	Session ID in registry (required).	required
objective	ObjectiveFn | None	Optional objective function override. If not provided, uses the objective from the strategy.	None
remote	bool	If True, use run_remote() for cloud execution.	False
api_key	str | None	API key for remote execution (optional for local servers).	None
endpoint	str | None	Custom endpoint URL for remote execution.	None
quiet	bool	If True, suppress progress output.	False
load_config	Any | None	LoadConfig for result loading behavior.	None
stop_on_failure	bool	If True (default), raise SweepExecutionError on first trial failure. If False, continue with remaining trials and report failures in the result.	True

Returns

Name	Type	Description
	Any	AdaptiveSweepResult with trial outcomes and best params.

Raises

Name	Type	Description
	TypeError	If config.sweep.strategy is not OptunaStrategy.
	ValueError	If no objective function is configured.
	ImportError	If optuna is not installed.
	SweepExecutionError	If stop_on_failure=True and a trial fails.

Examples

>>> from joshpy.strategies import run_adaptive_sweep, OptunaStrategy
>>> from joshpy.jobs import JobConfig, SweepConfig, ConfigSweepParameter
>>> from joshpy.registry import RunRegistry
>>> from joshpy.cli import JoshCLI
>>>
>>> def stability_metric(registry, run_hash, job):
...     # Lower = more stable
...     df = queries.get_timeseries("population", run_hash=run_hash)
...     return df["value"].std() / df["value"].mean()
>>>
>>> config = JobConfig(
...     template_path=Path("template.jshc.j2"),
...     source_path=Path("simulation.josh"),
...     sweep=SweepConfig(
...         config_parameters=[
...             ConfigSweepParameter(name="maxGrowth", values=[10, 50, 100]),
...         ],
...         strategy=OptunaStrategy(n_trials=50, direction="minimize"),
...     ),
... )
>>>
>>> registry = RunRegistry("experiment.duckdb")
>>> session_id = registry.create_session(config=config)
>>> cli = JoshCLI()
>>>
>>> result = run_adaptive_sweep(
...     cli, config,
...     registry=registry,
...     session_id=session_id,
...     objective=stability_metric,
... )
>>> print(f"Best params: {result.best_params}")
>>> print(f"Best value: {result.best_value}")