qamomile.braket.execution

Adapt Amazon Braket task lifecycles to Qamomile execution handles.

Overview¶

Classes¶

BraketExecutionHandle [source]¶

class BraketExecutionHandle(ExecutionHandle[ResultT], Generic[ResultT])

Wrap one Braket task or a task batch without blocking submission.

Parameters:

Constructor¶

def __init__(
    self,
    *,
    tasks: Sequence[Any],
    result_loader: Callable[[], Sequence[Any]],
    decoder: Callable[[Sequence[Any]], ResultT],
    reference: ExecutionReference | None,
    reference_factory: Callable[[], ExecutionReference | None] | None = None,
    native: object,
    poll_interval_seconds: float = 1.0,
    default_timeout_seconds: float | None = None,
    allow_unsuccessful_loader: bool = False,
) -> None

Initialize a Braket-backed execution handle.

Parameters:

Raises:

• ValueError — If the polling interval or default timeout is invalid.

Attributes¶

• native: object | None Return the native Braket task or batch.

Methods¶

cancel¶

def cancel(self) -> None

Request best-effort cancellation of every unfinished task.

metadata¶

def metadata(self) -> Mapping[str, Any]

Return cached-or-provider metadata for every task.

Returns:

Mapping[str, Any] — Mapping[str, Any]: Child task metadata in submission order.

raw_status¶

def raw_status(self) -> object

Return raw task states in stable order.

Returns:

object — One state string or a tuple of state strings.

references¶

def references(self) -> tuple[ExecutionReference, ...]

Return the logical Braket execution reference.

Returns:

tuple[ExecutionReference, ...] — tuple[ExecutionReference, ...]: Empty for local tasks, otherwise one reference containing every task ARN.

result¶

def result(self, timeout: float | None = None) -> ResultT

Wait for and decode all Braket task results.

Parameters:

Returns:

ResultT — Decoded engine-neutral result.

Raises:

• TimeoutError — If timeout expires before terminal state.

• ValueError — If timeout is negative or not finite.

• ExecutionError — If a task fails, is cancelled, or omits a result.

snapshot¶

def snapshot(self) -> ExecutionSnapshot

Capture an AWS reference or an already retrieved local result.

AWS tasks retain their provider references after result retrieval. Local tasks require a successful result() call first; this method never retrieves results or waits for another result caller.

Returns:

ExecutionSnapshot — One remote reference or a detached local value.

Raises:

• TypeError — If a cached local result contains unsupported objects.

• ValueError — If no reference or cached result exists, or the cached value is nonfinite, cyclic, or nested too deeply.

status¶

def status(self) -> JobStatus

Return the aggregate Braket task status.

Returns:

JobStatus — Provider-independent aggregate status.

BraketExecutionOptions [source]¶

class BraketExecutionOptions

Configure Braket task and batch submission without flat kwargs.

Parameters:

Raises:

• ValueError — If options contain executor-owned argument names or an invalid numeric value.

Constructor¶

def __init__(
    self,
    s3_destination_folder: tuple[str, str] | None = None,
    reservation_arn: str | None = None,
    max_parallel: int | None = None,
    poll_timeout_seconds: float | None = None,
    poll_interval_seconds: float | None = None,
    batch_max_retries: int = 0,
    task_options: Mapping[str, Any] = dict(),
    batch_options: Mapping[str, Any] = dict(),
) -> None

Attributes¶

• batch_max_retries: int

• batch_options: Mapping[str, Any]

• max_parallel: int | None

• poll_interval_seconds: float | None

• poll_timeout_seconds: float | None

• reservation_arn: str | None

• s3_destination_folder: tuple[str, str] | None

• task_options: Mapping[str, Any]

Methods¶

batch_kwargs¶

def batch_kwargs(self) -> dict[str, Any]

Build keyword arguments for a Braket task batch.

Returns:

dict[str, Any] — dict[str, Any]: Validated device.run_batch keyword arguments.

task_kwargs¶

def task_kwargs(self) -> dict[str, Any]

Build keyword arguments for one Braket task.

Returns:

dict[str, Any] — dict[str, Any]: Validated device.run keyword arguments.

ExecutionError [source]¶

class ExecutionError(QamomileCompileError)

Error during program execution.

ExecutionHandle [source]¶

class ExecutionHandle(ABC, Generic[ResultT])

Expose an engine execution without forcing immediate result retrieval.

Attributes¶

• native: object | None Return the wrapped provider-native task when available.

Methods¶

cancel¶

def cancel(self) -> None

Request best-effort cancellation.

Cancellation is intentionally not reported as a boolean because providers may accept a request after execution has already started. Call :meth:status to observe the eventual state.

metadata¶

def metadata(self) -> Mapping[str, Any]

Return optional provider execution metadata.

Returns:

Mapping[str, Any] — Mapping[str, Any]: Provider metadata such as timestamps or usage.

raw_status¶

def raw_status(self) -> object

Return provider-specific status information.

Returns:

object — Provider status value, or the normalized status when no richer value exists.

references¶

def references(self) -> tuple[ExecutionReference, ...]

Return serializable remote execution references.

Returns:

tuple[ExecutionReference, ...] — tuple[ExecutionReference, ...]: Secret-free provider references.

result¶

def result(self, timeout: float | None = None) -> ResultT

Wait for and return the engine-neutral raw result.

Parameters:

Returns:

ResultT — Raw result normalized by the engine executor.

Raises:

• TimeoutError — If the local wait expires before completion.

result_async¶

def result_async(self, timeout: float | None = None) -> ResultT

Wait asynchronously for the engine-neutral raw result.

Parameters:

Returns:

ResultT — Raw result normalized by the engine executor.

Raises:

• TimeoutError — If the local wait expires before completion.

snapshot¶

def snapshot(self) -> ExecutionSnapshot

Capture one remote execution without fetching its result.

Adapters exposing several logical references must override this method with an explicit reconstruction structure. A provider reference may itself contain multiple physical job IDs.

Returns:

ExecutionSnapshot — One opaque provider execution.

Raises:

• ValueError — If references are absent or their grouping is unknown.

status¶

def status(self) -> JobStatus

Return the current provider-independent execution status.

Returns:

JobStatus — Current normalized status.

ExecutionReference [source]¶

class ExecutionReference

Store secret-free identifiers needed to restore remote execution.

Parameters:

Raises:

• ValueError — If the provider name or any job identifier is empty.

• TypeError — If identifiers or context have incompatible types.

Constructor¶

def __init__(
    self,
    provider: str,
    job_ids: tuple[str, ...],
    target: str | None = None,
    group_id: str | None = None,
    context: Mapping[str, str] = dict(),
) -> None

Attributes¶

• context: Mapping[str, str]

• group_id: str | None

• job_ids: tuple[str, ...]

• provider: str

• target: str | None

Methods¶

from_dict¶

@classmethod
def from_dict(cls, data: Mapping[str, Any]) -> ExecutionReference

Reconstruct a provider reference from JSON-compatible data.

Parameters:

Returns:

ExecutionReference — Validated provider execution reference.

Raises:

• KeyError — If a required provider or job identifier field is absent.

• TypeError — If a field has an incompatible type.

• ValueError — If provider or job identifiers are empty.

to_dict¶

def to_dict(self) -> dict[str, Any]

Convert the provider reference to JSON-compatible data.

Returns:

dict[str, Any] — dict[str, Any]: Provider identifiers and decoding context without credentials or SDK objects.

ExecutionSnapshot [source]¶

class ExecutionSnapshot

Store a remote leaf, a local value, or an ordered execution group.

Provider leaves may identify several physical jobs or produce native batch results. Composite children retain their result boundaries independently of the number of provider identifiers. Local values contain raw engine-neutral results, before the executable applies its public result conversion. Trees and local values support at most 100 levels of nesting.

Parameters:

Raises:

• TypeError — If fields or local result types are unsupported.

• ValueError — If fields conflict with the node kind or values are invalid.

Constructor¶

def __init__(
    self,
    kind: str | ExecutionSnapshotKind,
    reference: ExecutionReference | None = None,
    value: Any = None,
    children: tuple[ExecutionSnapshot, ...] = (),
) -> None

Attributes¶

• children: tuple[ExecutionSnapshot, ...]

• kind: str | ExecutionSnapshotKind

• reference: ExecutionReference | None

• value: Any

Methods¶

from_dict¶

@classmethod
def from_dict(cls, data: Mapping[str, Any]) -> ExecutionSnapshot

Reconstruct an execution tree with strict node and value validation.

Parameters:

Returns:

ExecutionSnapshot — Validated execution structure.

Raises:

• TypeError — If node fields have incompatible types.

• ValueError — If kinds, fields, references, or local values are invalid.

references¶

def references(self) -> tuple[ExecutionReference, ...]

Collect provider leaves in order without discarding tree structure.

This list supports diagnostics; restoration uses the complete tree.

Returns:

tuple[ExecutionReference, ...] — tuple[ExecutionReference, ...]: Detached remote references in order.

Raises:

• TypeError — If mutable reference fields became incompatible.

• ValueError — If mutable reference fields became invalid.

restore¶

def restore(
    self,
    restore_reference: Callable[[ExecutionReference], ExecutionHandle[Any]],
) -> ExecutionHandle[Any]

Reattach remote leaves and rebuild local values and ordered groups.

The callback must reattach an existing provider execution. This method neither retrieves remote results nor submits any execution.

Parameters:

Returns:

ExecutionHandle[Any] — ExecutionHandle[Any]: Reconstructed raw execution lifecycle.

Raises:

• TypeError — If local data is unsupported or the callback returns an incompatible handle.

• ValueError — If local values or references became invalid.

• Exception — If the provider restoration callback fails.

to_dict¶

def to_dict(self) -> dict[str, Any]

Serialize the execution tree and type-preserving local values.

Returns:

dict[str, Any] — dict[str, Any]: JSON-compatible execution tree.

Raises:

• TypeError — If mutable local data was changed to unsupported types.

• ValueError — If mutable local data or references became invalid.

ExecutionSnapshotKind [source]¶

class ExecutionSnapshotKind(StrEnum)

Identify the reconstruction contract of an execution snapshot node.

Attributes¶

• COMPOSITE

• LOCAL

• REMOTE

JobStatus [source]¶

class JobStatus(Enum)

Describe a provider-independent execution state.

The numeric values of the original four states remain stable for serialization compatibility.

Attributes¶

• CANCELLED

• CANCELLING

• COMPLETED

• FAILED

• PARTIAL

• PENDING

• QUEUED

• RUNNING

• UNKNOWN