qdk_chemistry.plugins.discovery.backend module

Microsoft Discovery backend for QDK/Chemistry remote execution.

qdk_chemistry.plugins.discovery.backend.create_credential(credential_mode)

Create the configured Azure credential.

Return type:: Any
Parameters:: credential_mode (str)

qdk_chemistry.plugins.discovery.backend.create_workspace_client(endpoint, credential)

Create a Microsoft Discovery workspace client.

Return type:

Any

Parameters:

endpoint (str)
credential (Any)

qdk_chemistry.plugins.discovery.backend.response_mapping(value)

Convert an Azure SDK response to a plain mapping.

Return type:: dict[str, Any]
Parameters:: value (Any)

class qdk_chemistry.plugins.discovery.backend.JobStatus(job_id, status, logs='', error=None, elapsed_seconds=None, metadata=<factory>)

Bases: object

Status of a remote job.

Returned by RemoteBackend.check() and related helpers.

Parameters:

job_id (str)
status (str)
logs (str)
error (str | None)
elapsed_seconds (float | None)
metadata (dict[str, Any])

TERMINAL_STATUSES: ClassVar[frozenset[str]] = frozenset({JobState.CANCELED, JobState.CANCELLED, JobState.FAILED, JobState.RETRIEVED, JobState.SUCCEEDED})

logs: str = ''

error: str | None = None

elapsed_seconds: float | None = None

static normalize_status(status)

Return the canonical form of a status string.

Parameters:: status (str | None) – Status string to normalize. If None, it is treated as an empty string.
Return type:: str
Returns:: The case-folded status string.

classmethod is_terminal_status(status)

Return whether a status string represents a terminal state.

Parameters:: status (str | None) – Status string to check.
Return type:: bool
Returns:: True if the status represents a terminal state; otherwise, False.

classmethod is_successful_status(status)

Return whether a status string represents successful execution.

Parameters:: status (str | None) – Status string to check.
Return type:: bool
Returns:: True if the status represents successful execution; otherwise, False.

property is_terminal: bool

Whether the job has reached a terminal state.

Returns:: True if the job has reached a terminal state; otherwise, False.

property is_successful: bool

Whether the job completed successfully.

Returns:: True if the job completed successfully; otherwise, False.

__init__(job_id, status, logs='', error=None, elapsed_seconds=None, metadata=<factory>)

Parameters:

job_id (str)
status (str)
logs (str)
error (str | None)
elapsed_seconds (float | None)
metadata (dict[str, Any])

Return type:

None

class qdk_chemistry.plugins.discovery.backend.RemoteBackend(**backend_args)

Bases: ABC

Abstract base class for remote execution backends.

Backends must implement these core operations:

connect / disconnect: lifecycle management
upload / download: default file transfer to/from the remote system
_submit: launch a job asynchronously (returns job_id + state)
check: poll job status
fetch: download and deserialize results

Backends may optionally implement:

cancel: cancel a running or queued job
cleanup_job: remove artifacts for a terminal job

upload() and download() are the normal transport for serialized job files. A backend with access to a cache shared by the client and compute node may use it instead for cache-backed artifacts, avoiding redundant file transfers. Files unavailable through that cache still use the default transport.

The remote node executes python -m qdk_chemistry.remote.worker which handles input deserialization, algorithm execution, caching, and output serialization.

Backend artifacts are retained after a job reaches a terminal state. Callers are responsible for removing them with cleanup() or fetch() with cleanup=True. Backend cleanup does not remove caller-owned local job records or result directories.

To create a custom backend:

Subclass RemoteBackend
Implement the methods above
Register it from a QdkChemistryPlugin
Optionally declare mcp_safe_config_options for constructor options that MCP clients may control. The default is deny-all.

Example

>>> from qdk_chemistry.plugins import PluginRegistrar, QdkChemistryPlugin
>>> class SlurmBackend(RemoteBackend):
...     name = "slurm"
...     mcp_safe_config_options = frozenset({"poll_interval", "timeout"})
...
...     def __init__(self, *, host, partition="default", poll_interval=5.0, timeout=3600.0):
...         super().__init__(
...             host=host,
...             partition=partition,
...             poll_interval=poll_interval,
...             timeout=timeout,
...         )
...         self.host = host
...         self.partition = partition
...
...     def connect(self):
...         self._client = SlurmClient(self.host)
...
...     def upload(self, local_path, remote_path):
...         self._client.sftp_put(local_path, remote_path)
...
...     def download(self, remote_path, local_path):
...         self._client.sftp_get(remote_path, local_path)
...
...     def disconnect(self):
...         self._client.close()
...
>>> class SlurmPlugin(QdkChemistryPlugin):
...     def register(self, registrar: PluginRegistrar):
...         registrar.register_remote_backend("slurm", SlurmBackend)

Parameters:: backend_args (Any)

mcp_safe_config_options: ClassVar[frozenset[str]] = frozenset({})

Constructor options that MCP clients may control.

Concrete backends must declare this attribute directly on the class to expose any options through MCP. The default is deny-all.

__init__(**backend_args)

Store the arguments needed to recreate the concrete backend.

Parameters:: **backend_args (Any) – Constructor arguments supplied by the concrete backend. Persisted jobs normalize path-like values to strings and require every remaining value to be JSON-serializable.
Return type:: None

abstractmethod connect()

Establish connection to the remote system.

This is called once before any upload/execute/download operations. Use this to set up network connections, authenticate with cloud services, etc.

Return type:: None

abstractmethod disconnect()

Close the connection to the remote system.

Called after connection-scoped operations are complete. This must not cancel submitted jobs or remove artifacts referenced by persisted jobs.

Return type:: None

abstractmethod upload(local_path, remote_path)

Upload a file from local system to remote system.

Backend implementations normally call this while staging the files produced by input serialization. Cache-backed files may be omitted when the compute node can read them from a shared cache.

Parameters:

local_path (str | Path) – Path to the local file.
remote_path (str) – Destination path on the remote system.

Return type:

None

abstractmethod download(remote_path, local_path)

Download a file from remote system to local system.

Backend implementations normally call this from fetch() for serialized outputs that were not retrieved through a shared cache.

Parameters:

remote_path (str) – Path to the file on the remote system.
local_path (str | Path) – Destination path on the local system.

Return type:

None

submit(payload, *, job_dir=None)

Submit a job and return immediately with a Job.

This method does not block. The returned Job is self-contained: it can be saved to disk, loaded in a different process, and used to Job.check(), Job.cancel(), or Job.fetch() results.

Subclasses must override _submit() to provide the backend-specific implementation.

Parameters:

payload (dict) – Execution request containing algorithm metadata and inputs.
job_dir (str | Path | None) – Optional directory where the job file is saved automatically (as <id>.job.json). If None the job is returned in-memory only.

Return type:

Job

Returns:

A Job that tracks this submission.

abstractmethod check(backend_state)

Query the current status of a previously submitted job.

Parameters:: backend_state (dict) – The opaque state dict produced by _submit().
Return type:: JobStatus
Returns:: A JobStatus describing the job’s current state.

cancel(backend_state)

Cancel a running or queued job.

This operation is optional. The default implementation raises NotImplementedError.

Parameters:: backend_state (dict) – The opaque state dict produced by _submit().
Return type:: None

abstractmethod fetch(backend_state, local_dir=None)

Download and deserialize results for a completed job.

Parameters:

backend_state (dict) – The opaque state dict produced by _submit().
local_dir (str | Path | None) – Optional directory to download result files into. If None, a temporary directory is used and cleaned up after deserialization.

Return type:

Any

Returns:

The deserialized algorithm results (same format as the return value of the completed algorithm run).

cleanup_job(backend_state)

Remove artifacts owned by a terminal job.

This operation is optional. Implementations must make repeated calls safe and must not remove shared backend work directories. The default implementation raises NotImplementedError.

Parameters:: backend_state (dict) – The opaque state dict produced by _submit().
Return type:: None

qdk_chemistry.plugins.discovery.backend.deserialize_outputs(directory, *, cache=None)

Deserialize algorithm outputs from a directory.

Parameters:

directory (str | Path) – Directory containing the output files.
cache (CacheBackend | None) – Optional cache backend used to resolve or reuse cacheable result values.

Return type:

Any

Returns:

The deserialized result (tuple or single value).

qdk_chemistry.plugins.discovery.backend.get_serialized_file_names(entry)

Return every file referenced by a serialized manifest entry.

Parameters:: entry (dict[str, Any]) – Serialized value entry from an input or output manifest.
Return type:: list[str]
Returns:: Artifact file names in manifest order; primitive and cached entries contribute no names.

qdk_chemistry.plugins.discovery.backend.serialize_inputs(directory, args, kwargs, algorithm_type, algorithm_name, settings, *, run_hash=None, job_cache_key=None, owner=None, input_hashes=None, force_rerun=False, remote_cache=None, remote_cache_backend=None, remote_cache_transport=False)

Serialize algorithm inputs to a directory of files.

Parameters:

directory (str | Path) – Directory to write files to.
args (tuple) – Positional arguments for the algorithm.
kwargs (dict) – Keyword arguments for the algorithm.
algorithm_type (str) – Type of algorithm (e.g., “scf_solver”).
algorithm_name (str) – Name of algorithm implementation.
settings (dict) – Algorithm settings dictionary.
run_hash (str | None) – Optional pre-computed algorithm run hash.
job_cache_key (str | None) – Optional cache key for the remote job record.
owner (dict[str, str | None] | None) – Optional workspace and project permitted to manage the job.
input_hashes (dict[str, str] | None) – Optional dict mapping input names to their content hashes.
force_rerun (bool) – Whether the compute node must skip its cache lookup.
remote_cache (dict[str, Any] | None) – Optional coordinates passed to the remote cache factory, get_cache().
remote_cache_backend (CacheBackend | None) – Shared cache backend; existing cacheable values become "cached" manifest references.
remote_cache_transport (bool) – Whether to seed shared-cache misses and use the cache as artifact transport.

Return type:

list[Path]

Returns:

List of all files created (for upload).

class qdk_chemistry.plugins.discovery.backend.DiscoveryBackend(*, workspace_endpoint=None, project_name=None, tool_id=None, node_pool_id=None, transport=None, storage_uri=None, storage_account_url=None, storage_container=None, storage_blob_prefix=None, storage_prefix=None, auth_mode=None, image=None, python_path=None, cpus=None, gpus=None, memory=None, artifact_retry_attempts=None, artifact_retry_delay=None, poll_interval=None, timeout=None)[source]

Bases: RemoteBackend

Run QDK/Chemistry jobs through Microsoft Discovery.

Parameters:

workspace_endpoint (str | None)
project_name (str | None)
tool_id (str | None)
node_pool_id (str | None)
transport (str | None)
storage_uri (str | None)
storage_account_url (str | None)
storage_container (str | None)
storage_blob_prefix (str | None)
storage_prefix (str | None)
auth_mode (str | None)
image (str | None)
python_path (str | None)
cpus (int | str | None)
gpus (int | str | None)
memory (str | None)
artifact_retry_attempts (int | None)
artifact_retry_delay (float | None)
poll_interval (float | None)
timeout (float | None)

name: str = 'discovery'

mcp_safe_config_options: ClassVar[frozenset[str]] = frozenset({'artifact_retry_attempts', 'artifact_retry_delay', 'poll_interval', 'timeout'})

Constructor options that MCP clients may control.

Concrete backends must declare this attribute directly on the class to expose any options through MCP. The default is deny-all.

__init__(*, workspace_endpoint=None, project_name=None, tool_id=None, node_pool_id=None, transport=None, storage_uri=None, storage_account_url=None, storage_container=None, storage_blob_prefix=None, storage_prefix=None, auth_mode=None, image=None, python_path=None, cpus=None, gpus=None, memory=None, artifact_retry_attempts=None, artifact_retry_delay=None, poll_interval=None, timeout=None)[source]

Initialize the Microsoft Discovery backend.

Parameters:

workspace_endpoint (str | None)
project_name (str | None)
tool_id (str | None)
node_pool_id (str | None)
transport (str | None)
storage_uri (str | None)
storage_account_url (str | None)
storage_container (str | None)
storage_blob_prefix (str | None)
storage_prefix (str | None)
auth_mode (str | None)
image (str | None)
python_path (str | None)
cpus (int | str | None)
gpus (int | str | None)
memory (str | None)
artifact_retry_attempts (int | None)
artifact_retry_delay (float | None)
poll_interval (float | None)
timeout (float | None)

connect()[source]

Create authenticated Microsoft Discovery and optional Blob Storage clients.

Return type:: None

disconnect()[source]

Close SDK clients.

Return type:: None

upload(local_path, remote_path)[source]

Upload a file to the linked Azure Blob Storage container.

Return type:

None

Parameters:

local_path (str | Path)
remote_path (str)

download(remote_path, local_path)[source]

Download a file from the linked Azure Blob Storage container.

Return type:

None

Parameters:

remote_path (str)
local_path (str | Path)

cleanup_job(backend_state)[source]

Remove Blob artifacts for one completed Microsoft Discovery job.

Return type:: None
Parameters:: backend_state (dict[str, Any])

check(backend_state)[source]

Query the current status of a Microsoft Discovery job.

Return type:: JobStatus
Parameters:: backend_state (dict[str, Any])

cancel(backend_state)[source]

Cancel a Microsoft Discovery job.

Return type:: None
Parameters:: backend_state (dict[str, Any])

fetch(backend_state, local_dir=None)[source]

Download and deserialize completed Microsoft Discovery output.

Return type:

Any

Parameters:

backend_state (dict[str, Any])
local_dir (str | Path | None)