qdk_chemistry.ui.tools module

MCP tools for the qdk_chemistry toolkit.

qdk_chemistry.ui.tools.available_backends()

Return list of registered backend names.

Return type:: list[str]

qdk_chemistry.ui.tools.get_mcp_safe_config_options(name)

Return MCP-safe constructor options for a registered backend.

Unknown backends and those without a direct declaration expose no configurable options to MCP clients.

Parameters:: name (str) – Registered backend name.
Return type:: frozenset[str]
Returns:: The explicitly declared MCP-safe constructor options. Returns an empty set when the backend is unknown or has no direct declaration.

qdk_chemistry.ui.tools.available_caches()

Return list of registered cache backend names.

Return type:: list[str]

qdk_chemistry.ui.tools.resolve_cache(cache, **kwargs)

Normalise a user-supplied cache argument.

Accepts any of the following:

None returns None
A CacheBackend instance → returned as-is
A Path or path-like string → FolderCache(path=...)
A registered name string → looked up in the registry; extra kwargs are forwarded to the backend constructor.

Parameters:

cache (str | Path | CacheBackend | None) – Cache instance, registered backend name, filesystem path, or None.
**kwargs (Any) – Backend-specific configuration for a name or filesystem path.

Return type:

CacheBackend | None

class qdk_chemistry.ui.tools.FolderCache(path, *, is_shared=False, **_kwargs)

Bases: CacheBackend

Content-addressed folder cache.

Parameters:

path (str | Path) – Directory to use as the cache root. Created on first write.
is_shared (bool) – True when this directory is a network mount reachable from remote compute nodes.
_kwargs (Any)

name: str = 'folder'

__init__(path, *, is_shared=False, **_kwargs)

Initialise with the cache directory path.

Parameters:

path (str | Path)
is_shared (bool)
_kwargs (Any)

get_job(run_hash)

Retrieve job metadata by run_hash, or None on miss.

Return type:: Job | None
Parameters:: run_hash (str)

put_job(run_hash, job)

Store (or update) job metadata keyed by run_hash.

Return type:

None

Parameters:

run_hash (str)
job (Job)

get_data(content_hash)

Retrieve cached data by its content hash, or None.

Return type:: Any | None
Parameters:: content_hash (str)

put_data(content_hash, data, *, shared_only=False)

Store data by content hash unless shared storage is required but unavailable.

Return type:

None

Parameters:

content_hash (str)
data (Any)
shared_only (bool)

has_data(content_hash, *, shared_only=False)

Fast existence check via glob (no deserialization).

Return type:

bool

Parameters:

content_hash (str)
shared_only (bool)

to_config()

Return kwargs to reconstruct this FolderCache.

Return type:: dict

delete_job(run_hash)

Remove job metadata by run_hash.

Only the .job.json file is deleted. Data blobs are left intact because they may be referenced by other jobs.

Return type:: bool
Parameters:: run_hash (str)

delete_data(content_hash)

Remove a DataClass blob (or list manifest and its items) by content hash.

Return type:: bool
Parameters:: content_hash (str)

clear()

Remove all cached jobs and data blobs.

Return type:: None

class qdk_chemistry.ui.tools.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.

qdk_chemistry.ui.tools.compute_valence_space_parameters(wavefunction: qdk_chemistry.data.Wavefunction, charge: SupportsInt | SupportsIndex, include_double_d_shell: bool = False) → tuple[int, int]

Get the default number of active electrons and active orbitals, which are obtained from the valence electrons and orbitals of the atomic element types in the structure. The structure is automatically extracted from the wavefunction.

Parameters:

wavefunction – The input wavefunction (the molecular structure is taken from wavefunction.orbitals.basis_set.structure).
charge – The total charge of the molecular system. Should match the charge used in the upstream SCF calculation.
include_double_d_shell – When True, add 5 correlating d’ orbitals per d-block atom (Sc-Zn, Y-Cd, Hf-Hg) to capture the strong nd / (n+1)d’ radial correlation in transition metals (the “double d-shell” effect). Defaults to False to preserve the historical sizing.

Returns:

Pair of ( n_active_electrons, n_active_orbitals )

Return type:

tuple

Examples

>>> nele, norb = compute_valence_space_parameters(wavefunction, charge)
>>> nele, norb = compute_valence_space_parameters(wavefunction, charge, include_double_d_shell=True)

qdk_chemistry.ui.tools.check_output_exists(filename, data_class=None)

Check if an output file already exists with valid content.

Parameters:

filename (str) – The output filename to check
data_class (type | None) – Optional data class to validate file content. If provided, attempts to load the file to verify it contains valid data.

Returns:

A message if the file exists with valid content, None otherwise

Return type:

str | None

qdk_chemistry.ui.tools.check_output_path_exists(filename, data_class=None)

Check whether an exact output path already exists with valid content.

Parameters:

filename (str | PathLike[str]) – Exact output path to inspect.
data_class (type | None) – Optional data class used to validate existing content.

Return type:

str | None

Returns:

A message when valid output exists, otherwise None.

qdk_chemistry.ui.tools.load_data_object(filename, data_class)

Load a data object from either json or hdf5 file based on extension.

Parameters:

filename (str | PathLike[str]) – Path to a file with extension (.json or .hdf5/.h5).
data_class – The qdk_chemistry.data class to instantiate

Returns:

The loaded data object

Raises:

ValueError – If file extension is not supported

qdk_chemistry.ui.tools.save_data_object(data_obj, filename)

Save a data object to either json or hdf5 file based on extension.

Parameters:

data_obj – The qdk_chemistry data object to save
filename (str | PathLike[str]) – Path to a file with extension (.json or .hdf5/.h5).

Returns:

The filename where data was saved

Return type:

str

Raises:

ValueError – If file extension is not supported

exception qdk_chemistry.ui.tools.FilenameFormatError

Bases: Exception

Raised when a filename has an invalid format for the expected data type.

qdk_chemistry.ui.tools.current_project_name()

Return the project currently validated for this execution context.

Return type:: str | None

qdk_chemistry.ui.tools.ensure_filename_format(filename, data_type)

Ensure filename contains the correct type marker for the given data type.

Parameters:

filename (str) – The filename to check/correct
data_type (str) – The data type name (e.g., “Wavefunction”, “QubitHamiltonian”)

Return type:

str

Returns:

The corrected filename with proper type marker

Raises:

FilenameFormatError – If the data type is unrecognized or the file extension is invalid

qdk_chemistry.ui.tools.resolve_project_file(filename, *, allow_nested=False, allow_absolute=False)

Resolve a client-provided filename inside the current project sandbox.

Absolute paths, traversal components, Windows drive or UNC paths, and symlinks that resolve outside the project are rejected.

Parameters:

filename (str | Path) – Project-relative filename to resolve.
allow_nested (bool) – Whether ordinary nested path components are accepted.
allow_absolute (bool) – Whether an internal absolute path may be revalidated.

Return type:

Path

Returns:

An absolute path contained by the current project directory.

Raises:

RuntimeError – If called outside a validated project context.
ValueError – If the filename is invalid or escapes the project.

qdk_chemistry.ui.tools.resolve_project_path(project_name, projects_dir)

Resolve a single-component project name beneath the projects directory.

Parameters:

project_name (str) – Name of the project directory.
projects_dir (str | Path) – Root directory containing projects.

Return type:

tuple[Path | None, str]

Returns:

The resolved project path and an empty error message, or None and an explanation when the path is invalid.

qdk_chemistry.ui.tools.strip_filename_path(filename)

Return only the filename, accepting both POSIX and Windows separators.

Return type:: str
Parameters:: filename (str | Path)

qdk_chemistry.ui.tools.validate_project(func)

Decorator to validate project before executing the function.

Validates that a project exists and exposes its absolute directory through the current execution context. The process working directory is unchanged.

It expects the decorated function to have project_name as its first parameter after self (if applicable).

Parameters:: func (TypeVar(F, bound= Callable[..., Any])) – The function to decorate. Must have project_name: str as a parameter.
Returns:: The decorated function with project validation logic, or str: a JSON string with error information.
Return type:: TypeVar(F, bound= Callable[..., Any])

Example:

@validate_project
@app.tool()
def my_function(project_name: str, other_param: int) -> str:
    # This function will only execute if project_name is valid
    return "success"

qdk_chemistry.ui.tools.current_workspace_root()

Return the immutable workspace binding for this MCP process.

Return type:: Path | None

async qdk_chemistry.ui.tools.workspace_binding_middleware(context, call_next)

Require a workspace binding before plugin tools resolve relative paths.

Parameters:

context (ServerRequestContext[Any, Any]) – Incoming MCP request context.
call_next (Callable[[ServerRequestContext[Any, Any]], Awaitable[BaseModel | dict[str, Any] | None]]) – Handler that receives the request after binding succeeds.

Return type:

BaseModel | dict[str, Any] | None

Returns:

The downstream handler result.

Raises:

RuntimeError – If binding is required but neither an existing binding nor a single client workspace root is available.

qdk_chemistry.ui.tools.register_visualization_tools(app)

Register interactive widget-based visualization tools on an MCP server.

Tools are registered only when qsharp_widgets is installed. Otherwise, this function is a no-op.

Parameters:: app – MCP server application that receives the widget resources and tools.
Return type:: None

async qdk_chemistry.ui.tools.bind_workspace(ctx, workspace_root=None)[source]

Bind this MCP process to a workspace root.

Return type:

dict[str, object]

Parameters:

ctx (Context)
workspace_root (str | None)

qdk_chemistry.ui.tools.list_algorithms(algorithm_type=None)[source]

List registered algorithm implementations and defaults.

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

qdk_chemistry.ui.tools.describe_algorithm(algorithm_type, algorithm_name=None)[source]

Describe a registered algorithm implementation and its settings.

Return type: