sweep.SweepManagerBuilder

sweep.SweepManagerBuilder(config)

Builder for SweepManager with flexible configuration.

The builder pattern allows for fluent configuration of SweepManager with sensible defaults and resource ownership tracking.

Examples

>>> manager = (
...     SweepManagerBuilder(config)
...     .with_registry("experiment.duckdb", experiment_name="my_sweep")
...     .with_cli(jar_path=Path("josh.jar"))
...     .build()
... )

Methods

Name	Description
build	Build the SweepManager instance.
with_catalog	Configure an optional ProjectCatalog for cross-experiment tracking.
with_cli	Configure the CLI.
with_defaults	Apply default configuration for simple cases.
with_label	Set a label for this run (single-job configs only).
with_registry	Configure the registry.

build

sweep.SweepManagerBuilder.build()

Build the SweepManager instance.

Expands jobs, creates or verifies session, and registers runs.

For adaptive strategies (OptunaStrategy), job expansion is deferred to run time - the JobSet will be empty initially.

Returns

Name	Type	Description
	SweepManager	Configured SweepManager ready for use.

Raises

Name	Type	Description
	ValueError	If session_id provided but hashes don’t match registered runs.

Examples

>>> manager = (
...     SweepManager.builder(config)
...     .with_registry("experiment.duckdb")
...     .with_cli()
...     .build()
... )

with_catalog

sweep.SweepManagerBuilder.with_catalog(catalog, *, experiment_name=None)

Configure an optional ProjectCatalog for cross-experiment tracking.

When a catalog is configured, the experiment is automatically registered on build() and its status is updated after run().

Parameters

Name	Type	Description	Default
catalog	Any	A ProjectCatalog instance.	required
experiment_name	str | None	Human-readable name for the experiment in the catalog.	None

Returns

Name	Type	Description
	SweepManagerBuilder	Self for chaining.

Examples

>>> from joshpy.catalog import ProjectCatalog
>>> catalog = ProjectCatalog("project.duckdb")
>>> manager = (
...     SweepManager.builder(config)
...     .with_registry("experiment.duckdb")
...     .with_catalog(catalog, experiment_name="baseline_dev_fine")
...     .build()
... )

with_cli

sweep.SweepManagerBuilder.with_cli(cli=None, *, jar_path=None, java_path='java')

Configure the CLI.

Parameters

Name	Type	Description	Default
cli	JoshCLI | None	Existing JoshCLI instance.	None
jar_path	Path | None	Path to josh jar (creates new CLI).	None
java_path	str	Path to java executable (default: “java”).	'java'

Returns

Name	Type	Description
	SweepManagerBuilder	Self for chaining.

Examples

>>> # Use existing CLI
>>> builder.with_cli(existing_cli)

>>> # Create new CLI with custom jar path
>>> builder.with_cli(jar_path=Path("josh.jar"))

with_defaults

sweep.SweepManagerBuilder.with_defaults(
    registry=':memory:',
    experiment_name=None,
    jar_path=None,
)

Apply default configuration for simple cases.

Convenience method that sets up both registry and CLI with defaults.

Parameters

Name	Type	Description	Default
registry	str | Path | RunRegistry	Registry path or instance (default: in-memory).	':memory:'
experiment_name	str | None	Name for the experiment session.	None
jar_path	Path | None	Path to josh jar file.	None

Returns

Name	Type	Description
	SweepManagerBuilder	Self for chaining.

Examples

>>> manager = (
...     SweepManager.builder(config)
...     .with_defaults(registry=":memory:")
...     .build()
... )

with_label

sweep.SweepManagerBuilder.with_label(label, force=False, on_collision=None)

Set a label for this run (single-job configs only).

The label is applied at build() time when the job is registered. For multi-job sweeps, raises ValueError at build() time.

Parameters

Name	Type	Description	Default
label	str	Human-readable label for this run.	required
force	bool	If True, reassign the label even if already taken (drops the old label).	False
on_collision	str | None	Collision strategy. "timestamp" archives the old label with a timestamp suffix so the bare label always points to the latest run. Mutually exclusive with force.	None

Returns

Name	Type	Description
	SweepManagerBuilder	Self for chaining.

Examples

>>> manager = (
...     SweepManager.builder(config)
...     .with_registry("experiment.duckdb")
...     .with_label("baseline")
...     .build()
... )

>>> # Re-run with same label, archive the old one
>>> manager = (
...     SweepManager.builder(config)
...     .with_registry("experiment.duckdb")
...     .with_label("baseline", on_collision="timestamp")
...     .build()
... )

with_registry

sweep.SweepManagerBuilder.with_registry(
    registry_or_path,
    *,
    experiment_name=None,
    session_id=None,
)

Configure the registry.

Parameters

Name	Type	Description	Default
registry_or_path	str | Path | RunRegistry	Path to create new registry, or existing instance.	required
experiment_name	str | None	Name for new session (when creating registry).	None
session_id	str | None	Use existing session ID (to resume a previous session).	None

Returns

Name	Type	Description
	SweepManagerBuilder	Self for chaining.

Examples

>>> # Create new registry from path
>>> builder.with_registry("experiment.duckdb", experiment_name="my_sweep")

>>> # Use existing registry
>>> builder.with_registry(existing_registry, session_id="abc-123")