qdk_chemistry.remote.job module

Persistent job handle for QDK/Chemistry.

A Job records algorithm metadata, content hashes, and status for cached computations. Instances serialise to JSON so that results can be recovered across sessions.

class qdk_chemistry.remote.job.Job(*, job_id, backend, backend_config, backend_state, algorithm_info=None, status='submitted', submitted_at=None, file_path=None, run_hash=None, input_hashes=None, output_hashes=None, output_is_tuple=None, owner=None)

Bases: object

Persistent handle for a cached computation.

Instances serialise to a JSON file on disk, making them the canonical record of a cached algorithm run.

Parameters:

• job_id (str)

• backend (str)

• backend_config (dict[str, Any])

• backend_state (dict[str, Any])

• algorithm_info (dict[str, Any] | None)

• status (str)

• submitted_at (str | None)

• file_path (str | pathlib.Path | None)

• run_hash (str | None)

• input_hashes (dict[str, str] | None)

• output_hashes (list[dict[str, Any]] | None)

• output_is_tuple (bool | None)

• owner (dict[str, str | None] | None)

job_id

Short unique identifier for this job.

backend

Registered backend name (e.g. "local").

backend_config

Dict of configuration that was passed to the backend constructor (pool, gpus, host, …). Stored so the backend can be re-created from scratch.

backend_state

Opaque dict written by the backend during submit. Contains whatever the backend needs to poll / cancel / fetch (operation IDs, remote paths, PIDs, …).

algorithm_info

Dict with type, name, settings of the algorithm that was submitted.

status

Last-known status string.

submitted_at

ISO-8601 timestamp of submission.

file_path

Path to the job file on disk (None if not persisted yet).

run_hash

Deterministic hash of the algorithm, settings, and inputs. Used for cache lookups. None if not computed.

input_hashes

Per-item content hashes of the submitted inputs, keyed by namespaced argument name (e.g. "args.arg_0", "kwargs.charge"). None if not recorded.

output_hashes

Per-item result descriptors. Each entry is a dict with "hash" and "type" keys. Primitives also carry a "value" key so they can be reconstructed without a cache backend. Populated when results are fetched. None until results are retrieved.

output_is_tuple

Whether the retrieved result is a tuple. None until results are retrieved.

owner

Workspace and project permitted to manage the job through MCP. None for unowned SDK jobs.

__init__(*, job_id, backend, backend_config, backend_state, algorithm_info=None, status='submitted', submitted_at=None, file_path=None, run_hash=None, input_hashes=None, output_hashes=None, output_is_tuple=None, owner=None)

Initialise a Job from its constituent parts.

Parameters:

• job_id (str) – Unique identifier assigned by the backend.

• backend (str) – Registered backend name.

• backend_config (dict[str, Any]) – Configuration used to reconstruct the backend.

• backend_state (dict[str, Any]) – Persisted backend-specific job state.

• algorithm_info (dict[str, Any] | None) – Submitted algorithm type, name, and settings.

• status (str) – Initial job status.

• submitted_at (str | None) – ISO-8601 submission timestamp.

• file_path (str | Path | None) – Optional path for the persisted job record.

• run_hash (str | None) – Deterministic hash used for cache lookup.

• input_hashes (dict[str, str] | None) – Content hashes for submitted inputs.

• output_hashes (list[dict[str, Any]] | None) – Content-hash descriptors for retrieved outputs.

• output_is_tuple (bool | None) – Whether the retrieved result is a tuple.

• owner (dict[str, str | None] | None) – Workspace and project permitted to manage this job through MCP.

to_dict()

Return a JSON-safe dictionary representing this job.

Return type:

dict[str, Any]

save(path=None)

Write the job file to disk atomically.

Parameters:

path (str | Path | None) – Explicit file path. If None, uses file_path (which must have been set earlier, e.g. via job_dir at submit time).

Return type:

Path

Returns:

The path the file was written to.

Raises:

ValueError – If no path is available.

classmethod load(path)

Reconstruct a Job from a previously saved file.

Parameters:

path (str | Path) – Path to a *.job.json file.

Return type:

Job

Returns:

A fully re-hydrated Job.

classmethod discover(directory)

Find all job files in a directory.

Parameters:

directory (str | Path) – Folder to scan (non-recursively) for *.job.json files.

Return type:

list[Job]

Returns:

List of Job instances, sorted by submitted_at (oldest first).

attach_backend(backend)

Associate this in-memory job with its submitting backend.

Return type:

None

Parameters:

backend (RemoteBackend)

detach_backend()

Remove the non-persistent backend association.

Return type:

None

check()

Query the backend, persist the latest status, and return it.

Return type:

JobStatus

cancel()

Cancel the backend job and persist its canceled status.

Return type:

None

fetch(local_dir=None, *, cleanup=False)

Download and persist results, then optionally remove backend artifacts.

Parameters:

• local_dir (str | Path | None) – Optional directory to download result files into.

• cleanup (bool) – Whether to remove backend job artifacts after successful retrieval and persistence.

Return type:

Any

Returns:

The deserialized algorithm results.

cleanup()

Remove backend artifacts for this terminal job.

Repeated cleanup is safe when supported by the backend.

Raises:

RuntimeError – If the job has not reached a terminal state.

Return type:

None

wait()

Block until the job reaches a terminal state.

Return type:

JobStatus

Returns:

The final status reported by the backend.

Raises:

TimeoutError – If the configured timeout expires before completion.

property is_terminal: bool

Whether the job has reached a final state.

property is_successful: bool

Whether the job completed successfully.