Jobs#

Job Definition#

A Job in Dioptra is a parameterized execution of an Entrypoint. While an Experiment defines the scope and available workflows, a Job represents the actual run of a workflow.

When a Job is created, it is sent to a specific Queue. A Worker listening to that queue claims the Job and executes the entrypoint code using the provided parameters, artifact inputs, and swap selections. Dioptra maintains a full history of every Job, including its logs, metrics, and any generated artifacts, creating a permanent record of the execution even if the underlying entrypoint or plugins are later modified.

Job Attributes#

This section describes the attributes used to define and track a Job.

Required Attributes#

  • Experiment: (integer ID) The unique identifier of the Experiment that serves as the namespace for this Job.

  • Entrypoint: (integer ID) The unique identifier of the Entrypoint resource defining the workflow to be executed. The Entrypoint must be associated with the selected Experiment.

  • Queue: (integer ID) The unique identifier of the Queue where the Job will be submitted for execution.

  • Values: (dictionary) A collection of parameter values (key-string pairs) passed to the Entrypoint to configure the workflow execution.

    • Name: (string) The input parameter name of the entrypoint parameter

    • Value: (any) The value for that entrypoint parameter

  • Artifact Values: (dictionary) A collection of Artifact IDs and Snapshot IDs passed as input parameters to the workflow.

    • Name: (string) The name of the artifact parameter defined in the entrypoint

    • Artifact ID: (integer ID) The unique identifier of the Artifact, which was created by another Job execution

    • Snapshot ID: (integer ID) The unique identifier of the specific Snapshot to load for this Artifact.

  • Swaps: (list, conditionally required) The task alias selected for each swap in the Entrypoint’s task graph. A selection is required for every swap when the selected Entrypoint contains swaps.

    • Swap Name: (string) The swap name without the leading ? used in the task graph.

    • Task Alias: (string) The task alias selected from the choices defined for the swap.

Optional Attributes#

  • Description: (string, optional) A text description providing context for this specific Job run.

  • Timeout: (string, optional) The maximum duration the Job is allowed to run before being automatically terminated by the system. Formatted using shorthand notation, i.e. 24h, 1d, 120m, etc.

  • Entrypoint Snapshot ID: (integer ID, optional) The specific snapshot of the entrypoint to use. If not provided, the latest snapshot is used.

System-Managed State#

  • ID: Unique identifier assigned to the Job upon registration.

  • Status: The current state of the Job. Valid states include:

    • queued: The Job is waiting in the queue for a worker.

    • started: A worker has claimed the Job and execution is underway.

    • deferred: The Job execution has been paused or delayed.

    • finished: The Job completed successfully.

    • failed: The Job encountered an error during execution.

  • Created On: Timestamp indicating when the Job was submitted.

  • Last Modified On: Timestamp indicating the last time the Job resource or status was updated.

  • Logs: A collection of log entries (severity, message, and timestamp) generated during the Job’s execution.

    • Severity: (string) The log level (e.g., INFO, ERROR, DEBUG).

    • Logger Name: (string) The name of the logger that produced the entry.

    • Timestamp: (timestamp) When the log was recorded

    • Message: (string) The actual log content

  • Metrics: Key-value pairs (e.g., accuracy, loss) recorded by the workflow during execution.

    • Name: (string) The name of the metric (e.g., “accuracy”).

    • Step: (integer) The execution step at which the metric was recorded.

    • Value: (float) The numerical value.

    • Special Value: (string, optional) Stores NaN, Infinity, or -Infinity if the metric value is non-finite.

    • Timestamp: (timestamp) When the metric was recorded.

  • Artifacts: A list of new Artifact resources created and registered as a result of the Job.

  • MLflow Run ID: The unique identifier for the associated MLflow run, used for tracking experiments and parameters.

Specifying Swaps#

If the selected Entrypoint contains swaps, the Job must provide exactly one task alias for every swap. Swap names and task aliases must match those defined in the Entrypoint’s task graph. The leading ? used to identify a swap in the task graph is not included in the Job selection.

The Python client accepts a dictionary that maps each swap name to its selected task alias:

swaps={"training_method": "training_method_A"}

When using the REST API directly, provide the selections as a list of objects:

{
  "swaps": [
    {
      "swap_name": "training_method",
      "task_alias": "training_method_A"
    }
  ]
}

Dioptra rejects a Job if a required swap is missing, a swap is specified more than once, or a swap name or task alias is not defined by the selected Entrypoint. The selections are used to render a task graph without swaps before the graph is passed to the task engine. For the task graph syntax, see Entrypoint swaps.

Registration Interfaces#

Jobs are typically created within the context of an Experiment.

Using Python Client#

Submit a Job through an Experiment

ExperimentJobsSubCollectionClient.create(experiment_id: str | int, entrypoint_id: int, queue_id: int, entrypoint_snapshot_id: int | None = None, values: dict[str, Any] | None = None, artifact_values: dict[str, Any] | None = None, timeout: str | None = None, description: str | None = None, swaps: list[dict[str, str]] | dict[str, str] | None = None) → dioptra.client.experiments.T[source]

Creates a job for an experiment.

Parameters

  • experiment_id – The experiment id, an integer.

  • entrypoint_id – The id for the entrypoint that the job will run.

  • queue_id – The id for the queue that will execute the job.

  • entrypoint_snapshot_id – The id for a snapshot associated with the entrypoint. If specified, the snapshotted version of the entrypoint will be used to run the job. If not specified, the job will use the latest version of the entrypoint. Defaults to None.

  • values – A dictionary of keyword arguments to pass to the entrypoint that parameterize the job. Default to None.

  • artifact_values – A dictionary of artifact input names associated with a value that is also a dictionary that contains the keys “id” and “snapshotId” whose values are the artifact resource id and the artifact resource snapshot id respectively. Defaults to None.

  • timeout – The maximum alloted time for a job before it times out and is stopped. If omitted, the job timeout will use the default set in the API.

  • description – The description for the job. Optional, defaults to None.

  • swaps – A list of swap choices. Each swap choice should contain two keys - the “swap_name” and the “task_alias” chosen for that swap name. Alternatively, if a single dictionary is provided, it will be assumed to be a mapping between swap names and choices and will be reformatted as a list.

Returns

The response from the Dioptra API.

Using REST API#

Jobs can be submitted directly via the HTTP API, usually via an experiment-specific endpoint.

Create Job

See the POST /api/v1/experiments/{experimentId}/jobs endpoint documentation for the required JSON payload, including parameters, artifact IDs, and swap selections.

See Also#

Additional reference pages: