Skip to content

quick

quick

Interactive job sessions for fresh runs, branching, and resumption.

Fresh job

with quick("/path/to/theseus") as q: q.build(MyTrainer, "experiment") # registered job names also work q.config.training.per_device_batch_size = 16 job = q.create() # construct and set up state once; ready to inspect job() # run the prepared job

Continue a saved job

with quick("/path/to/theseus") as q: q.find().spec(run="source").checkpoint().resume() # resume() loads the selected checkpoint's config immediately. q.config.optimization.lr = 1e-5 q.build() # from_node: saved job class + edited config; constructs now job = q.create() job() # continues with the prepared resume state

Branch from a saved job

with quick("/path/to/theseus") as q: q.find().spec(run="source").checkpoint().branch() q.config.optimization.lr = 3e-5 q.build(name="new-experiment") # constructs the saved class with a new name job = q.create() job() # runs the new branch

Time travel debugging (a checkpoint from a base trainer): import jax import matplotlib.pyplot as plt import seaborn as sns from theseus.model.attention.base import SelfAttention

with quick("/path/to/theseus") as q:
    q.find().spec(run="source").checkpoint().resume()
    q.build()
    job = q.create()

    paths = job.find(SelfAttention)
    with job.debug(paths[0]) as (layer, inputs):
        x = inputs.x
        print("Captured input:", x.shape, x[0, 0, :8])
        projected = layer.c_attn(x)  # GPT SelfAttention's existing projection
        ax = sns.heatmap(jax.device_get(projected[0]))
        ax.set(xlabel="QKV feature", ylabel="Token", title="Checkpoint projection")
        plt.show()
    # Debugger closes here, restoring JIT/config and discarding exploration.
    # find()/debug() replay the saved batch at the checkpoint sequence.
    # Training advances once before consuming the next batch.
    job()  # continue training after inspection
Selection and lifecycle

Each find() returns an independent query. Chain filters on that builder; separate find() calls never accumulate filters. build() leaves held query builders intact. all()/select() consume and reset their builder's filters.

Queries default to ascending sequence order; branch()/resume() take the last match (highest seq). Use latest() for the most recently written checkpoint, or sort(...) to override the order. branch()/resume() replace q.config with its saved configuration. Missing saved config raises immediately, leaving the previous selection/config intact. Select before create(), and make config edits AFTER selection, before job construction.

build(job, name) configures a fresh session and clears base/resume selection. To use an explicit class with a checkpoint, build it first, then select. build(job=None) requires a selected node and calls RestoreableJob.from_node with q.config plus any explicit config overrides. Resume restores saved job identity; branch accepts a new name/project/group (default name: "local"). create() sets up that instance's saved state without running training. Call job() on the returned instance to run with the prepared branch/resume mode and any interactive state edits. q() is shorthand for creating and running the cached job with the selected mode. setup() is idempotent: subsequent setup calls preserve prepared state. Config edits after construction do not reconfigure the instance. Repeating identical build() arguments preserves the session; changed arguments replace it.

q.shard(tp=2, fsdp=False, zero=True) configures the next job before create().

q.spec() snapshots a built session as a Combobulation without creating or running a job. Extend it with branch()/resume(), set resources with gpu() or cpu(), and pass it as DispatchSpec(job=...). DispatchSpec supplies the execution name/project/group and hardware; checkpoint bases must be accessible from the dispatch's root. Live in-memory job state is not exported.

To submit through the CLI's hardware solver and configured providers: OmegaConf.save(q.spec().gpu(2).serialize(), "train.yaml") # uv run theseus submit experiment train.yaml

init(root) opens the same session without a context manager; call close() afterward. close() finishes the live job and restores the prior config context. Root defaults to $THESEUS_ROOT or ".". Queries need no active job.

QuickJob(root_dir: str | Path | None = None)

Query a root and optionally configure and run one active job.

config: DictConfig property

Editable config from build() or the selected checkpoint.

build(job: Any | str = None, name: str | None = None, project: str | None = None, group: str | None = None, config: DictConfig | None = None) -> QuickJob

Configure a job; identical arguments preserve the active session.

New builds clear branch/resume selection but leave existing queries intact. Select a base after building. Argument comparison uses a detached snapshot of supplied overrides, so editing q.config does not rebuild the job.

Omit job after branch()/resume() to construct the saved job immediately. Pass config overrides here; create() returns the restored instance.

close() -> None

Finish the active job's resources and restore the prior config context.

spec() -> Combobulation

Snapshot the built job, config, lineage, and sharding for dispatch.

Call build() first. The returned execution is independent of this session and includes config edits made up to this call. It describes execution from the selected checkpoint, not the live instance's state.

shard(tp: int = 1, fsdp: bool = False, zero: bool = True, activation_checkpointing: bool = False) -> 'QuickJob'

Configure parallelism before creating the job.

create() -> Any

Create and set up the configured job without running it.

The node and lineage mode selected by :meth:find are applied to the instance. Repeated calls preserve the prepared state and run node.

find() -> 'QuickQuery'

Query the root, with or without an active job.

The query reads the object store rooted at this quick job's output path. Each call returns an independent builder with no accumulated filters. Use all()/select() for reads. To select an execution base, call branch() or resume() before create(). Selection loads checkpoint configuration; call build() without a job to construct the saved job after editing it.

__call__() -> Any

Create and run the job with the selected resume mode.

QuickQuery(quick_job: QuickJob, store: ObjectReader)

Bases: QueryBuilder

Select a checkpoint, ordered by sequence unless explicitly overridden.

branch() -> QuickJob

Select a branch base and load its saved configuration.

resume() -> QuickJob

Select a resume base and load its saved configuration.

quick(root_dir: str | Path | None = None) -> Generator[QuickJob, None, None]

Open a query/run session and close its active job on context exit.

init(root_dir: str | Path | None = None) -> QuickJob

Open a session at root_dir, defaulting to $THESEUS_ROOT or ".".

Queries are available immediately. Call build(job, name, ...) before editing config or executing a job, and close() when finished.