qilisdk 0.1.5__py3-none-any.whl → 0.1.6__py3-none-any.whl

qilisdk/speqtrum/speqtrum.py

@@ -18,15 +18,28 @@ import json
 import time
 from base64 import urlsafe_b64encode
 from datetime import datetime, timezone
-from typing import TYPE_CHECKING, Callable, cast
+from typing import TYPE_CHECKING, Any, Callable, TypeVar, cast, overload
 
 import httpx
 from loguru import logger
 from pydantic import TypeAdapter
 
-from qilisdk.functionals import Sampling, TimeEvolution, VariationalProgram
+from qilisdk.functionals import (
+    Sampling,
+    SamplingResult,
+    TimeEvolution,
+    TimeEvolutionResult,
+    VariationalProgram,
+    VariationalProgramResult,
+)
+from qilisdk.functionals.functional_result import FunctionalResult
 from qilisdk.settings import get_settings
-from qilisdk.speqtrum.experiments import ExperimentFunctional, RabiExperiment, T1Experiment
+from qilisdk.speqtrum.experiments import (
+    RabiExperiment,
+    RabiExperimentResult,
+    T1Experiment,
+    T1ExperimentResult,
+)
 
 from .keyring import delete_credentials, load_credentials, store_credentials
 from .speqtrum_models import (
@@ -34,6 +47,7 @@ from .speqtrum_models import (
     ExecutePayload,
     ExecuteType,
     JobDetail,
+    JobHandle,
     JobId,
     JobInfo,
     JobStatus,
@@ -43,6 +57,7 @@ from .speqtrum_models import (
     T1ExperimentPayload,
     TimeEvolutionPayload,
     Token,
+    TypedJobDetail,
     VariationalProgramPayload,
 )
 
@@ -50,6 +65,9 @@ if TYPE_CHECKING:
     from qilisdk.functionals.functional import Functional, PrimitiveFunctional
 
 
+ResultT = TypeVar("ResultT", bound=FunctionalResult)
+
+
 class SpeQtrum:
     """Synchronous client for the Qilimanjaro SpeQtrum API."""
 
@@ -60,14 +78,17 @@ class SpeQtrum:
             logger.error("No QaaS credentials found. Call `.login()` or set env vars before instantiation.")
             raise RuntimeError("Missing QaaS credentials - invoke SpeQtrum.login() first.")
         self._username, self._token = credentials
-        self._handlers: dict[type[Functional], Callable[[Functional, str], int]] = {
-            Sampling: lambda f, device: self._submit_sampling(cast("Sampling", f), device),
-            TimeEvolution: lambda f, device: self._submit_time_evolution(cast("TimeEvolution", f), device),
-            VariationalProgram: lambda f, device: self._submit_variational_program(
-                cast("VariationalProgram", f), device
+        self._handlers: dict[type[Functional], Callable[[Functional, str, str | None], JobHandle[Any]]] = {
+            Sampling: lambda f, device, job_name: self._submit_sampling(cast("Sampling", f), device, job_name),
+            TimeEvolution: lambda f, device, job_name: self._submit_time_evolution(
+                cast("TimeEvolution", f), device, job_name
+            ),
+            RabiExperiment: lambda f, device, job_name: self._submit_rabi_program(
+                cast("RabiExperiment", f), device, job_name
+            ),
+            T1Experiment: lambda f, device, job_name: self._submit_t1_program(
+                cast("T1Experiment", f), device, job_name
             ),
-            RabiExperiment: lambda f, device: self._submit_rabi_program(cast("RabiExperiment", f), device),
-            T1Experiment: lambda f, device: self._submit_t1_program(cast("T1Experiment", f), device),
         }
         self._settings = get_settings()
         logger.success("QaaS client initialised for user '{}'", self._username)
@@ -191,20 +212,27 @@ class SpeQtrum:
         logger.success("{} jobs retrieved", len(jobs))
         return [j for j in jobs if where(j)] if where else jobs
 
-    def get_job_details(self, id: int) -> JobDetail:
-        """Fetch the complete record of *id*.
+    @overload
+    def get_job(self, job: JobHandle[ResultT]) -> TypedJobDetail[ResultT]: ...
+
+    @overload
+    def get_job(self, job: int) -> JobDetail: ...
+
+    def get_job(self, job: int | JobHandle[Any]) -> JobDetail | TypedJobDetail[Any]:
+        """Fetch the complete record of *job*.
 
         Args:
-            id: Identifier of the job.
+            job: Either the integer identifier or a previously returned `JobHandle`.
 
         Returns:
-            A :class:`~qilisdk.models.JobDetail` instance containing payload,
-            result, logs and error information.
+            A :class:`~qilisdk.models.JobDetail` snapshot. When a handle is supplied the
+            result is wrapped in :class:`~qilisdk.models.TypedJobDetail` to expose typed accessors.
         """
-        logger.debug("Retrieving job {} details", id)
+        job_id = job.id if isinstance(job, JobHandle) else job
+        logger.debug("Retrieving job {} details", job_id)
         with httpx.Client() as client:
             response = client.get(
-                f"{self._settings.speqtrum_api_url}/jobs/{id}",
+                f"{self._settings.speqtrum_api_url}/jobs/{job_id}",
                 headers=self._get_authorized_headers(),
                 params={
                     "payload": True,
@@ -238,30 +266,51 @@ class SpeQtrum:
             data["logs"] = decoded_logs.decode("utf-8")
 
         job_detail = TypeAdapter(JobDetail).validate_python(data)
-        logger.debug("Job {} details retrieved (status {})", id, job_detail.status.value)
+        logger.debug("Job {} details retrieved (status {})", job_id, job_detail.status.value)
+        if isinstance(job, JobHandle):
+            return job.bind(job_detail)
         return job_detail
 
+    @overload
+    def wait_for_job(
+        self,
+        job: JobHandle[ResultT],
+        *,
+        poll_interval: float = 5.0,
+        timeout: float | None = None,
+    ) -> TypedJobDetail[ResultT]: ...
+
+    @overload
     def wait_for_job(
         self,
-        id: int,
+        job: int,
         *,
         poll_interval: float = 5.0,
         timeout: float | None = None,
-    ) -> JobDetail:
-        """Block until *id* reaches a terminal state.
+    ) -> JobDetail: ...
+
+    def wait_for_job(
+        self,
+        job: int | JobHandle[Any],
+        *,
+        poll_interval: float = 5.0,
+        timeout: float | None = None,
+    ) -> JobDetail | TypedJobDetail[Any]:
+        """Block until the job referenced by *job* reaches a terminal state.
 
         Args:
-            id: Job identifier.
+            job: Either the integer job identifier or a previously returned `JobHandle`.
             poll_interval: Seconds between successive polls. Defaults to ``5``.
             timeout: Maximum wait time in seconds. ``None`` waits indefinitely.
 
         Returns:
-            Final :class:`~qilisdk.models.JobDetail` snapshot.
+            Final :class:`~qilisdk.models.JobDetail` snapshot, optionally wrapped with type-safe accessors.
 
         Raises:
             TimeoutError: If *timeout* elapses before the job finishes.
         """
-        logger.info("Waiting for job {} (poll={}s, timeout={}s)…", id, poll_interval, timeout)
+        job_id = job.id if isinstance(job, JobHandle) else job
+        logger.info("Waiting for job {} (poll={}s, timeout={}s)…", job_id, poll_interval, timeout)
         start_t = time.monotonic()
         terminal_states = {
             JobStatus.COMPLETED,
@@ -271,24 +320,62 @@ class SpeQtrum:
 
         # poll until we hit a terminal state or timeout
         while True:
-            current = self.get_job_details(id)
+            current = self.get_job(job_id)
 
             if current.status in terminal_states:
-                logger.success("Job {} reached terminal state {}", id, current.status.value)
+                logger.success("Job {} reached terminal state {}", job_id, current.status.value)
+                if isinstance(job, JobHandle):
+                    return job.bind(current)
                 return current
 
             if timeout is not None and (time.monotonic() - start_t) >= timeout:
                 logger.error(
-                    "Timeout while waiting for job {} after {}s (last status {})", id, timeout, current.status.value
+                    "Timeout while waiting for job {} after {}s (last status {})",
+                    job_id,
+                    timeout,
+                    current.status.value,
                 )
                 raise TimeoutError(
-                    f"Timed out after {timeout}s while waiting for job {id} (last status {current.status.value!r})"
+                    f"Timed out after {timeout}s while waiting for job {job_id} (last status {current.status.value!r})"
                 )
 
-            logger.debug("Job {} still {}, sleeping {}s", id, current.status.value, poll_interval)
+            logger.debug("Job {} still {}, sleeping {}s", job_id, current.status.value, poll_interval)
             time.sleep(poll_interval)
 
-    def submit(self, functional: PrimitiveFunctional | ExperimentFunctional, device: str) -> int:
+    @overload
+    def submit(self, functional: Sampling, device: str, job_name: str | None = None) -> JobHandle[SamplingResult]: ...
+
+    @overload
+    def submit(
+        self, functional: TimeEvolution, device: str, job_name: str | None = None
+    ) -> JobHandle[TimeEvolutionResult]: ...
+
+    @overload
+    def submit(
+        self, functional: VariationalProgram[Sampling], device: str, job_name: str | None = None
+    ) -> JobHandle[VariationalProgramResult[SamplingResult]]: ...
+
+    @overload
+    def submit(
+        self, functional: VariationalProgram[TimeEvolution], device: str, job_name: str | None = None
+    ) -> JobHandle[VariationalProgramResult[TimeEvolutionResult]]: ...
+
+    @overload
+    def submit(
+        self, functional: VariationalProgram[PrimitiveFunctional[ResultT]], device: str, job_name: str | None = None
+    ) -> JobHandle[VariationalProgramResult[ResultT]]: ...
+
+    @overload
+    def submit(
+        self, functional: RabiExperiment, device: str, job_name: str | None = None
+    ) -> JobHandle[RabiExperimentResult]: ...
+
+    @overload
+    def submit(
+        self, functional: T1Experiment, device: str, job_name: str | None = None
+    ) -> JobHandle[T1ExperimentResult]: ...
+
+    def submit(self, functional: Functional, device: str, job_name: str | None = None) -> JobHandle[FunctionalResult]:
         """
         Submit a quantum functional for execution on the selected device.
 
@@ -299,6 +386,9 @@ class SpeQtrum:
 
         * :class:`~qilisdk.functionals.sampling.Sampling`
         * :class:`~qilisdk.functionals.time_evolution.TimeEvolution`
+        * :class:`~qilisdk.functionals.variational_program.VariationalProgram`
+        * :class:`~qilisdk.speqtrum.experiments.experiment_functional.RabiExperiment`
+        * :class:`~qilisdk.speqtrum.experiments.experiment_functional.T1Experiment`
 
         A backend device must be selected beforehand with
         :py:meth:`set_device`.
@@ -308,14 +398,28 @@ class SpeQtrum:
                 ``Sampling`` or ``TimeEvolution``) that defines the quantum
                 workload to be executed.
             device: Device code returned by :py:meth:`list_devices`.
+            job_name (optional): The name of the job, this can help you identify different jobs easier. Default: None.
 
         Returns:
-            int: The numeric identifier of the created job on SpeQtrum.
+            JobHandle: A typed handle carrying the numeric job identifier and result type metadata.
 
         Raises:
             NotImplementedError: If *functional* is not of a supported type.
         """
         try:
+            if isinstance(functional, VariationalProgram):
+                inner = functional.functional
+                if isinstance(inner, Sampling):
+                    return self._submit_variational_program(cast("VariationalProgram[Sampling]", functional), device)
+                if isinstance(inner, TimeEvolution):
+                    return self._submit_variational_program(
+                        cast("VariationalProgram[TimeEvolution]", functional), device
+                    )
+
+                # Fallback to untyped handle for custom primitives.
+                job_handle = self._submit_variational_program(cast("VariationalProgram[Any]", functional), device)
+                return cast("JobHandle[FunctionalResult]", job_handle)
+
             handler = self._handlers[type(functional)]
         except KeyError as exc:
             logger.error("Unsupported functional type: {}", type(functional).__qualname__)
@@ -324,16 +428,25 @@ class SpeQtrum:
             ) from exc
 
         logger.info("Submitting {}", type(functional).__qualname__)
-        job_id = handler(functional, device)
-        logger.success("Submission complete - job {}", job_id)
-        return job_id
+        job_handle = handler(functional, device, job_name)
+        logger.success("Submission complete - job {}", job_handle.id)
+        return job_handle
 
-    def _submit_sampling(self, sampling: Sampling, device: str) -> int:
+    def _submit_sampling(
+        self, sampling: Sampling, device: str, job_name: str | None = None
+    ) -> JobHandle[SamplingResult]:
         payload = ExecutePayload(
             type=ExecuteType.SAMPLING,
             sampling_payload=SamplingPayload(sampling=sampling),
         )
-        json = {"device_code": device, "payload": payload.model_dump_json(), "job_type": JobType.DIGITAL, "meta": {}}
+        json = {
+            "device_code": device,
+            "payload": payload.model_dump_json(),
+            "job_type": JobType.DIGITAL,
+            "meta": {},
+        }
+        if job_name:
+            json["name"] = job_name
         logger.debug("Executing Sampling on device {}", device)
         with httpx.Client() as client:
             response = client.post(
@@ -343,14 +456,23 @@ class SpeQtrum:
             )
             response.raise_for_status()
             job = JobId(**response.json())
-        return job.id
+        return JobHandle.sampling(job.id)
 
-    def _submit_rabi_program(self, rabi_experiment: RabiExperiment, device: str) -> int:
+    def _submit_rabi_program(
+        self, rabi_experiment: RabiExperiment, device: str, job_name: str | None = None
+    ) -> JobHandle[RabiExperimentResult]:
         payload = ExecutePayload(
             type=ExecuteType.RABI_EXPERIMENT,
             rabi_experiment_payload=RabiExperimentPayload(rabi_experiment=rabi_experiment),
         )
-        json = {"device_code": device, "payload": payload.model_dump_json(), "job_type": JobType.PULSE, "meta": {}}
+        json = {
+            "device_code": device,
+            "payload": payload.model_dump_json(),
+            "job_type": JobType.PULSE,
+            "meta": {},
+        }
+        if job_name:
+            json["name"] = job_name
         logger.debug("Executing Rabi experiment on device {}", device)
         with httpx.Client() as client:
             response = client.post(
@@ -361,14 +483,23 @@ class SpeQtrum:
             response.raise_for_status()
             job = JobId(**response.json())
         logger.info("Rabi experiment job submitted: {}", job.id)
-        return job.id
+        return JobHandle.rabi_experiment(job.id)
 
-    def _submit_t1_program(self, t1_experiment: T1Experiment, device: str) -> int:
+    def _submit_t1_program(
+        self, t1_experiment: T1Experiment, device: str, job_name: str | None = None
+    ) -> JobHandle[T1ExperimentResult]:
         payload = ExecutePayload(
             type=ExecuteType.T1_EXPERIMENT,
             t1_experiment_payload=T1ExperimentPayload(t1_experiment=t1_experiment),
         )
-        json = {"device_code": device, "payload": payload.model_dump_json(), "job_type": JobType.PULSE, "meta": {}}
+        json = {
+            "device_code": device,
+            "payload": payload.model_dump_json(),
+            "job_type": JobType.PULSE,
+            "meta": {},
+        }
+        if job_name:
+            json["name"] = job_name
         logger.debug("Executing T1 experiment on device {}", device)
         with httpx.Client() as client:
             response = client.post(
@@ -379,14 +510,23 @@ class SpeQtrum:
             response.raise_for_status()
             job = JobId(**response.json())
         logger.info("T1 experiment job submitted: {}", job.id)
-        return job.id
+        return JobHandle.t1_experiment(job.id)
 
-    def _submit_time_evolution(self, time_evolution: TimeEvolution, device: str) -> int:
+    def _submit_time_evolution(
+        self, time_evolution: TimeEvolution, device: str, job_name: str | None = None
+    ) -> JobHandle[TimeEvolutionResult]:
         payload = ExecutePayload(
             type=ExecuteType.TIME_EVOLUTION,
             time_evolution_payload=TimeEvolutionPayload(time_evolution=time_evolution),
         )
-        json = {"device_code": device, "payload": payload.model_dump_json(), "job_type": JobType.ANALOG, "meta": {}}
+        json = {
+            "device_code": device,
+            "payload": payload.model_dump_json(),
+            "job_type": JobType.ANALOG,
+            "meta": {},
+        }
+        if job_name:
+            json["name"] = job_name
         logger.debug("Executing time evolution on device {}", device)
         with httpx.Client() as client:
             response = client.post(
@@ -397,23 +537,29 @@ class SpeQtrum:
             response.raise_for_status()
             job = JobId(**response.json())
         logger.info("Time evolution job submitted: {}", job.id)
-        return job.id
-
-    def _submit_variational_program(self, variational_program: VariationalProgram, device: str) -> int:
-        """Run a Variational Program on the selected device.
-
-        Args:
-            variational_program (VariationalProgram): Problem definition containing Hamiltonian and ansatz.
-            device (str): The SpeQtrum device's code to execute the variational program upon.
-
-        Returns:
-            The numeric identifier of the created job.
-        """
+        return JobHandle.time_evolution(job.id)
+
+    @overload
+    def _submit_variational_program(
+        self, variational_program: VariationalProgram[Sampling], device: str, job_name: str | None = None
+    ) -> JobHandle[VariationalProgramResult[SamplingResult]]: ...
+
+    @overload
+    def _submit_variational_program(
+        self, variational_program: VariationalProgram[TimeEvolution], device: str, job_name: str | None = None
+    ) -> JobHandle[VariationalProgramResult[TimeEvolutionResult]]: ...
+
+    @overload
+    def _submit_variational_program(
+        self, variational_program: VariationalProgram[Any], device: str, job_name: str | None = None
+    ) -> JobHandle[VariationalProgramResult]: ...
+
+    def _submit_variational_program(
+        self, variational_program: VariationalProgram[Any], device: str, job_name: str | None = None
+    ) -> JobHandle[VariationalProgramResult]:
         payload = ExecutePayload(
             type=ExecuteType.VARIATIONAL_PROGRAM,
-            variational_program_payload=VariationalProgramPayload(
-                variational_program=variational_program,
-            ),
+            variational_program_payload=VariationalProgramPayload(variational_program=variational_program),
         )
         json = {
             "device_code": device,
@@ -421,6 +567,9 @@ class SpeQtrum:
             "job_type": JobType.VARIATIONAL,
             "meta": {},
         }
+        if job_name:
+            json["name"] = job_name
+        logger.debug("Executing variational program on device {}", device)
         with httpx.Client() as client:
             response = client.post(
                 self._settings.speqtrum_api_url + "/execute",
@@ -429,4 +578,10 @@ class SpeQtrum:
             )
             response.raise_for_status()
             job = JobId(**response.json())
-            return job.id
+        logger.info("Variational program job submitted: {}", job.id)
+        inner = variational_program.functional
+        if isinstance(inner, Sampling):
+            return JobHandle.variational_program(job.id, result_type=SamplingResult)
+        if isinstance(inner, TimeEvolution):
+            return JobHandle.variational_program(job.id, result_type=TimeEvolutionResult)
+        return JobHandle.variational_program(job.id)

qilisdk/speqtrum/speqtrum_models.py

@@ -14,6 +14,7 @@
 # ruff: noqa: ANN001, ANN202, PLR6301
 from email.utils import parsedate_to_datetime
 from enum import Enum
+from typing import Any, Callable, Generic, TypeVar, cast, overload
 
 from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, field_serializer, field_validator
 
@@ -25,6 +26,7 @@ from qilisdk.functionals import (
     VariationalProgram,
     VariationalProgramResult,
 )
+from qilisdk.functionals.functional_result import FunctionalResult
 from qilisdk.speqtrum.experiments import RabiExperiment, RabiExperimentResult, T1Experiment, T1ExperimentResult
 from qilisdk.utils.serialization import deserialize, serialize
 
@@ -226,6 +228,142 @@ class ExecuteResult(SpeQtrumModel):
         return v
 
 
+ResultT_co = TypeVar("ResultT_co", bound=FunctionalResult, covariant=True)
+VariationalInnerResultT = TypeVar("VariationalInnerResultT", bound=FunctionalResult)
+
+
+ResultExtractor = Callable[[ExecuteResult], ResultT_co]
+
+
+# these helpers live outside the models so they can be referenced by default values
+def _require_sampling_result(result: ExecuteResult) -> SamplingResult:
+    if result.sampling_result is None:
+        raise RuntimeError("SpeQtrum did not return a sampling_result for a sampling execution.")
+    return result.sampling_result
+
+
+def _require_time_evolution_result(result: ExecuteResult) -> TimeEvolutionResult:
+    if result.time_evolution_result is None:
+        raise RuntimeError("SpeQtrum did not return a time_evolution_result for a time evolution execution.")
+    return result.time_evolution_result
+
+
+def _require_variational_program_result(result: ExecuteResult) -> VariationalProgramResult:
+    if result.variational_program_result is None:
+        raise RuntimeError("SpeQtrum did not return a variational_program_result for a variational program execution.")
+    return result.variational_program_result
+
+
+def _require_rabi_experiment_result(result: ExecuteResult) -> RabiExperimentResult:
+    if result.rabi_experiment_result is None:
+        raise RuntimeError("SpeQtrum did not return a rabi_experiment_result for a Rabi experiment execution.")
+    return result.rabi_experiment_result
+
+
+def _require_t1_experiment_result(result: ExecuteResult) -> T1ExperimentResult:
+    if result.t1_experiment_result is None:
+        raise RuntimeError("SpeQtrum did not return a t1_experiment_result for a T1 experiment execution.")
+    return result.t1_experiment_result
+
+
+def _require_variational_program_result_typed(
+    inner_result_type: type[VariationalInnerResultT],
+) -> ResultExtractor[VariationalProgramResult[VariationalInnerResultT]]:
+    def _extractor(result: ExecuteResult) -> VariationalProgramResult[VariationalInnerResultT]:
+        variational_result = _require_variational_program_result(result)
+        optimal_results = variational_result.optimal_execution_results
+        if not isinstance(optimal_results, inner_result_type):
+            raise RuntimeError(
+                "SpeQtrum returned a variational program result whose optimal execution result "
+                f"({type(optimal_results).__qualname__}) does not match the expected "
+                f"{inner_result_type.__qualname__}."
+            )
+        return cast("VariationalProgramResult[VariationalInnerResultT]", variational_result)
+
+    return _extractor
+
+
+class JobHandle(SpeQtrumModel, Generic[ResultT_co]):
+    """Strongly typed reference to a submitted SpeQtrum job."""
+
+    id: int
+    execute_type: ExecuteType
+    extractor: ResultExtractor[ResultT_co] = Field(repr=False, exclude=True)
+
+    @classmethod
+    def sampling(cls, job_id: int) -> "JobHandle[SamplingResult]":
+        return cls(id=job_id, execute_type=ExecuteType.SAMPLING, extractor=_require_sampling_result)  # type: ignore[return-value, arg-type]
+
+    @classmethod
+    def time_evolution(cls, job_id: int) -> "JobHandle[TimeEvolutionResult]":
+        return cls(id=job_id, execute_type=ExecuteType.TIME_EVOLUTION, extractor=_require_time_evolution_result)  # type: ignore[return-value, arg-type]
+
+    @overload
+    @classmethod
+    def variational_program(cls, job_id: int) -> "JobHandle[VariationalProgramResult]": ...
+
+    @overload
+    @classmethod
+    def variational_program(
+        cls, job_id: int, *, result_type: type[VariationalInnerResultT]
+    ) -> "JobHandle[VariationalProgramResult[VariationalInnerResultT]]": ...
+
+    @classmethod
+    def variational_program(
+        cls, job_id: int, *, result_type: type[VariationalInnerResultT] | None = None
+    ) -> "JobHandle[Any]":
+        """Create a variational-program handle for an existing job identifier.
+
+        Args:
+            job_id: Numeric identifier returned by the SpeQtrum service.
+            result_type: Optional functional result type expected within the
+                variational program payload. When provided the returned handle
+                enforces that the optimiser output matches this type.
+
+        Returns:
+            JobHandle: A handle whose ``get_results`` invocation yields a
+            ``VariationalProgramResult`` preserving the requested inner result
+            type when supplied.
+        """
+        if result_type is None:
+            handle = cls(
+                id=job_id,
+                execute_type=ExecuteType.VARIATIONAL_PROGRAM,
+                extractor=_require_variational_program_result,  # type: ignore[arg-type]
+            )
+            return cast("JobHandle[VariationalProgramResult]", handle)
+
+        extractor = _require_variational_program_result_typed(result_type)
+        handle = cls(id=job_id, execute_type=ExecuteType.VARIATIONAL_PROGRAM, extractor=extractor)  # type: ignore[arg-type]
+        return cast("JobHandle[VariationalProgramResult[VariationalInnerResultT]]", handle)
+
+    @classmethod
+    def rabi_experiment(cls, job_id: int) -> "JobHandle[RabiExperimentResult]":
+        return cls(id=job_id, execute_type=ExecuteType.RABI_EXPERIMENT, extractor=_require_rabi_experiment_result)  # type: ignore[return-value, arg-type]
+
+    @classmethod
+    def t1_experiment(cls, job_id: int) -> "JobHandle[T1ExperimentResult]":
+        return cls(id=job_id, execute_type=ExecuteType.T1_EXPERIMENT, extractor=_require_t1_experiment_result)  # type: ignore[return-value, arg-type]
+
+    def bind(self, detail: "JobDetail") -> "TypedJobDetail[ResultT_co]":
+        """Attach this handle's typing information to a concrete job detail.
+
+        Args:
+            detail: Un-typed job detail payload returned by the SpeQtrum API.
+
+        Returns:
+            TypedJobDetail: Wrapper exposing ``get_results`` with the typing
+            captured when the handle was created.
+        """
+        return TypedJobDetail.model_validate(
+            {
+                **detail.model_dump(),
+                "expected_type": self.execute_type,
+                "extractor": self.extractor,
+            }
+        )
+
+
 class JobStatus(str, Enum):
     "Job has not been submitted to the Lab api"
 
@@ -298,3 +436,32 @@ class JobDetail(JobInfo):
     logs: str | None = None
     error: str | None = None
     error_logs: str | None = None
+
+
+class TypedJobDetail(JobDetail, Generic[ResultT_co]):
+    """`JobDetail` subclass that exposes a strongly typed `get_results` method."""
+
+    expected_type: ExecuteType = Field(repr=False)
+    extractor: ResultExtractor[ResultT_co] = Field(repr=False, exclude=True)
+
+    def get_results(self) -> ResultT_co:
+        """Return the strongly typed execution result.
+
+        Returns:
+            ResultT_co: Result payload associated with the completed job,
+            respecting the type information carried by the originating
+            ``JobHandle``.
+
+        Raises:
+            RuntimeError: If SpeQtrum has not populated the result payload or
+                the execute type disagrees with the handle.
+        """
+        if self.result is None:
+            raise RuntimeError("The job completed without a result payload; inspect `error` or `logs` for details.")
+
+        if self.result.type != self.expected_type:
+            raise RuntimeError(
+                f"Expected a result of type '{self.expected_type.value}' but received '{self.result.type.value}'."
+            )
+
+        return self.extractor(self.result)

qilisdk/utils/visualization/schedule_renderers.py

@@ -21,7 +21,7 @@ import matplotlib.pyplot as plt
 
 if TYPE_CHECKING:
     from qilisdk.analog.schedule import Schedule
-    from qilisdk.common.variables import Number
+    from qilisdk.core.variables import Number
 
 from qilisdk.utils.visualization.style import ScheduleStyle
 
@@ -146,6 +146,11 @@ class MatplotlibScheduleRenderer:
 
         self.ax.figure.savefig(filename, bbox_inches="tight")  # type: ignore[union-attr]
 
+    def show(self) -> None:  # noqa: PLR6301
+        """Show the current figure."""
+
+        plt.show()
+
     @staticmethod
     def _make_axes(dpi: int, style: ScheduleStyle) -> plt.Axes:
         """