Skip to content

Core API

The lifecycle-facing classes used by nearly every molq application.

Cluster 

Cluster(name, scheduler='local', *, host=None, transport=None, scheduler_options=None, _scheduler_impl=None)

A submission destination — scheduler + transport bound together.

Parameters:

Name Type Description Default
name str

Cluster label used to scope persisted records.

 required
scheduler str

One of "local", "slurm", "pbs", "lsf". "local" is the no-batch-system backend; pair it with a non-default transport (or pass host= for SSH) to run jobs on a remote workstation without a queue manager.

 'local'
host str | None

SSH shortcut. If provided, builds an :class:~molq.transport.SshTransport from :class:~molq.options.SshTransportOptions(host=host). Mutually exclusive with transport.

 None
transport Transport | None

Explicit Transport. Mutually exclusive with host.

 None
scheduler_options SchedulerOptions | None

Backend-specific options dataclass. When omitted, defaults are used.

 None

get_queue 

get_queue(*, user=None)

Return the scheduler's current queue snapshot.

Backed by squeue --me (SLURM), qstat -u $USER (PBS), or bjobs (LSF). Local-style schedulers return an empty list.

get_workspace 

get_workspace(name, *, path)

Return a :class:~molq.workspace.Workspace rooted at path.

path is the absolute path on the cluster's filesystem (i.e., on the Transport). No remote I/O is performed by this call — invoke workspace.ensure() if you need to create the directory.

get_project 

get_project(name, *, workspace)

Return a :class:~molq.workspace.Project under workspace.

workspace must be supplied explicitly — the cluster's filesystem layout is unknown to molq, and silently defaulting to the driver's cwd would point to the wrong place on a remote cluster.

from_profile classmethod 

from_profile(profile_name, *, config_path=None)

Load destination half of a profile (scheduler, host, scheduler_options).

A profile carrying host builds an :class:~molq.transport.SshTransport; without one the cluster runs on the current machine.

from_ssh_alias classmethod 

from_ssh_alias(alias, *, scheduler='slurm', name=None, scheduler_options=None, config_path=None)

Build a Cluster from a Host alias in ~/.ssh/config.

alias is resolved through ssh -G so the resulting :class:~molq.transport.SshTransport carries the effective hostname/user/port/identityfile. name defaults to alias; pass an explicit value when the cluster name should differ from the SSH alias (e.g., when persisting records under a stable label).

Submitor 

Submitor(target, *, defaults=None, store=None, jobs_dir=None, default_retry_policy=None, retention_policy=None, profile_name=None, event_bus=None, plugins=None, plugin_configs=None)

Lifecycle engine for submitted jobs.

A Submitor holds the persistence + monitoring half of molq's two-axis model (the destination half is :class:~molq.cluster.Cluster). Each Submitor is bound to a single :class:~molq.cluster.Cluster as its target at construction; submission, listing, cancellation, and watching are all implicitly scoped to that target's name.

Multi-cluster on one process: instantiate one Submitor per Cluster. They share a :class:~molq.store.JobStore by default and filter their queries by target.name so they do not see each other's records.

Parameters:

Name Type Description Default
target Cluster

The destination Cluster.

 required
defaults SubmitorDefaults | None

Default resource/scheduling/execution parameters.

 None
store JobStore | None

Custom JobStore. When None, auto-bootstraps a JobStore at the molcrafts-standard location via :func:molq.store.default_jobs_db_path (which delegates to :func:molcfg.paths.project_config_dir).

 None
jobs_dir str | Path | None

Optional override for per-job artifacts. When omitted, materialized scripts and default logs are written under the submission working directory at .molq/jobs/<job-id>/.

 None
plugins list[str] | None

Official or third-party plugin names to attach (e.g. ["nerve"]). Empty/omitted means no plugins.

 None
plugin_configs dict[str, dict[str, Any]] | None

Per-plugin config dicts (from [plugins.<name>]).

 None

from_profile classmethod 

from_profile(profile_name, *, target=None, config_path=None, store=None)

Load lifecycle parameters from a profile, bind to target.

If target is omitted, builds one via :meth:Cluster.from_profile.

submit_job 

submit_job(*, argv=None, command=None, script=None, resources=None, scheduling=None, execution=None, metadata=None, retry=None, after_started=None, after=None, after_failure=None, after_success=None, job_dir_name=None)

Submit a job.

Exactly one of argv, command, or script must be provided.

Parameters:

Name Type Description Default
job_dir_name str | None

Optional name for the job directory under jobs_dir. When provided, the directory is named job_dir_name instead of the auto-generated UUID. Useful when callers want log files to live alongside other per-execution artifacts under a meaningful name (e.g. exec-<run_id>). When jobs_dir is not set, the base directory is the resolved submission cwd.

 None

Returns:

Type Description
JobHandle

JobHandle for the submitted job.

get_job 

get_job(job_id)

Get a job record by ID.

Raises:

Type Description
JobNotFoundError

If job doesn't exist.

list_jobs 

list_jobs(include_terminal=False)

List jobs for this cluster.

remembered_allocations 

remembered_allocations(*, limit=None)

Return scheduling configs previously used to submit to this cluster.

Ordered most-recently-used first. Pure local recall — no cluster query.

get_transitions 

get_transitions(job_id)

Return the persisted transition timeline for a job.

watch_jobs 

watch_jobs(job_ids=None, *, timeout=None)

Block until specified jobs (or all active) reach terminal state.

cancel_job 

cancel_job(job_id)

Cancel a job.

refresh_jobs 

refresh_jobs()

Reconcile all active jobs with the scheduler.

cleanup_jobs 

cleanup_jobs(*, dry_run=False, retention_policy=None)

Delete expired job directories and terminal records.

Returns {"job_dirs": [...], "records": [...]} — what was removed, or what would be under dry_run.

fetch_logs 

fetch_logs(job_id, *, dest_dir=None, streams=('stdout', 'stderr'))

Pull captured log files from the cluster's filesystem to local.

Parameters:

Name Type Description Default
job_id str

Job to fetch logs for.

 required
dest_dir str | Path | None

Local directory. Defaults to a per-job folder under the local jobs_dir.

 None
streams tuple[str, ...]

Subset of ("stdout", "stderr").

 ('stdout', 'stderr')

Returns:

Type Description
dict[str, Path]

Mapping stream_name -> local_path for streams that existed on
dict[str, Path]

the cluster. Missing streams are silently skipped.

Raises:

Type Description
JobNotFoundError

When job_id is unknown.

fetch_artifacts 

fetch_artifacts(job_id, *, dest_dir=None, exclude=())

Mirror the job's working directory back to a local folder.

Behaves like rsync -a <job_dir>/ <dest_dir>/ over the cluster's transport — useful when the job emitted output files alongside its scripts and you want the whole bundle locally.

Returns the local destination directory.

close 

close()

Release plugins and this Submitor's :class:JobStore connection.

The store connection is closed only when this Submitor opened it. A store passed in via store= belongs to the caller and stays open for whoever else is using it.

Safe to call multiple times. After close() no further methods should be invoked on this Submitor.

JobHandle dataclass 

JobHandle(job_id, cluster_name, scheduler, scheduler_job_id, _state, _submitor)

Lightweight handle for a submitted job.

Returned by Submitor.submit(). Provides single-job operations.

status 

status()

Return cached job state (no I/O).

refresh 

refresh()

Reconcile with scheduler and return updated handle.

wait 

wait(timeout=None)

Block until this job reaches a terminal state.

cancel 

cancel()

Cancel this job.