Hyperparameter sweeps

Cursus sweeps orchestrate grid and random hyperparameter searches across parallel workers with transactional trial claiming.

Create a sweep

sweep = cursus.create_sweep(
    "demo",
    {
        "lr": {"min": 1e-5, "max": 1e-1, "scale": "log"},
        "batch": {"values": [16, 32]},
    },
    name="lr-search",
)

project — the project name (must exist)
space — the hyperparameter search space:
- Grid: {"values": [...]} (2–50 entries) on every dimension (≤10k combinations, ≤8 dims)
- Random: also takes {"min": .., "max": .., "scale": "linear"|"log"}
name — optional human-readable name
method — "random" (default) or "grid"

Like init(), creation may raise — sweeps are control calls, not logging.

Claim trials

while (trial := cursus.next_trial(sweep["id"])) is not None:
    run = cursus.init(
        project="demo",
        config=trial["config"],
        name=f"sweep-{trial['trial']}",
        sweep_id=trial["sweep_id"],
    )
    try:
        train(trial["config"])
        cursus.finish()
    except Exception:
        cursus.finish("crashed")
        raise

next_trial(sweep_id) claims the next config — transactionally for grid, so concurrent workers never share a cell
Returns None when the grid is exhausted or the sweep finished/cancelled: clean loop exit
Transport errors raise (retry or abort the worker loop as you see fit)

Linking runs to sweeps

Pass sweep_id to init() — validated same-project and still running. Trials appear on the sweep's page with configs. Launch one worker process per machine for parallel search.

Group projects and named runs

import sagea_cursus as cursus
 
# Log inside a group project (you must belong to the group).
run = cursus.init(project="detection", group="vision-team", name="baseline-a", tags=["v2-data"])
print("view at:", run.url)
cursus.log({"map50": 0.61}, step=1)
cursus.finish()

Group projects require membership — the server rejects non-members with 404
Without group, the project is org-wide and visible to every member
API keys are per-user; create one per machine
Keys owned by viewers are read-scoped: they authenticate reads, but every write answers 403
Deactivated users' keys are revoked automatically; deleted users' keys vanish with the account

What's next