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

qilisdk/speqtrum/speqtrum.py

@@ -14,19 +14,37 @@
 from __future__ import annotations
 
 import base64
+import binascii
 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, Generator, TypeAlias, TypeVar, cast, overload
 
 import httpx
 from loguru import logger
-from pydantic import TypeAdapter
-
-from qilisdk.functionals import Sampling, TimeEvolution, VariationalProgram
+from pydantic import TypeAdapter, ValidationError
+
+from qilisdk.experiments import (
+    RabiExperiment,
+    RabiExperimentResult,
+    T1Experiment,
+    T1ExperimentResult,
+    T2Experiment,
+    T2ExperimentResult,
+    TwoTonesExperiment,
+    TwoTonesExperimentResult,
+)
+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 .keyring import delete_credentials, load_credentials, store_credentials
 from .speqtrum_models import (
@@ -34,6 +52,7 @@ from .speqtrum_models import (
     ExecutePayload,
     ExecuteType,
     JobDetail,
+    JobHandle,
     JobId,
     JobInfo,
     JobStatus,
@@ -41,8 +60,11 @@ from .speqtrum_models import (
     RabiExperimentPayload,
     SamplingPayload,
     T1ExperimentPayload,
+    T2ExperimentPayload,
     TimeEvolutionPayload,
     Token,
+    TwoTonesExperimentPayload,
+    TypedJobDetail,
     VariationalProgramPayload,
 )
 
@@ -50,27 +72,199 @@ if TYPE_CHECKING:
     from qilisdk.functionals.functional import Functional, PrimitiveFunctional
 
 
+TFunctionalResult = TypeVar("TFunctionalResult", bound=FunctionalResult)
+JSONValue: TypeAlias = dict[str, "JSONValue"] | list["JSONValue"] | str | int | float | bool | None
+
+_SKIP_ENSURE_OK_EXTENSION = "qilisdk.skip_ensure_ok"
+_CONTEXT_EXTENSION = "qilisdk.request_context"
+
+
+class SpeQtrumAPIError(httpx.HTTPStatusError):
+    """Raised when the SpeQtrum API responds with a non-success HTTP status."""
+
+    def __init__(self, message: str, *, request: httpx.Request, response: httpx.Response) -> None:
+        super().__init__(message, request=request, response=response)
+
+
+def _safe_json_loads(value: str, *, context: str) -> JSONValue | None:
+    try:
+        result = json.loads(value)
+        return cast("JSONValue", result)
+    except json.JSONDecodeError as exc:
+        logger.warning("Failed to decode JSON for {}: {}", context, exc)
+        return None
+
+
+def _safe_b64_decode(value: str, *, context: str) -> str | None:
+    try:
+        decoded_bytes = base64.b64decode(value)
+    except (binascii.Error, ValueError) as exc:
+        logger.warning("Failed to base64 decode {}: {}", context, exc)
+        return None
+    try:
+        return decoded_bytes.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        logger.warning("Failed to UTF-8 decode {}: {}", context, exc)
+        return None
+
+
+def _safe_b64_json(value: str, *, context: str) -> JSONValue | None:
+    decoded_text = _safe_b64_decode(value, context=context)
+    if decoded_text is None:
+        return None
+    return _safe_json_loads(decoded_text, context=context)
+
+
+def _request_extensions(*, context: str | None = None, skip_ensure_ok: bool = False) -> dict[str, Any] | None:
+    extensions: dict[str, Any] = {}
+    if context:
+        extensions[_CONTEXT_EXTENSION] = context
+    if skip_ensure_ok:
+        extensions[_SKIP_ENSURE_OK_EXTENSION] = True
+    return extensions or None
+
+
+def _response_context(response: httpx.Response) -> str:
+    request = response.request
+    if request is None:
+        return "SpeQtrum API call"
+    context = request.extensions.get(_CONTEXT_EXTENSION)
+    if isinstance(context, str) and context.strip():
+        return context
+    return f"{request.method} {request.url}"
+
+
+def _stringify_payload(payload: JSONValue | None) -> str | None:
+    if payload is None:
+        return None
+    if isinstance(payload, dict):
+        for key in ("message", "detail", "error", "error_description", "title"):
+            value = payload.get(key)
+            if isinstance(value, str) and value.strip():
+                code = payload.get("code") or payload.get("error_code") or payload.get("errorCode")
+                code_suffix = f" (code={code})" if isinstance(code, (str, int)) else ""
+                return value.strip() + code_suffix
+        try:
+            return json.dumps(payload, sort_keys=True)
+        except (TypeError, ValueError):
+            return str(payload)
+    if isinstance(payload, list):
+        preview = ", ".join(str(item) for item in payload[:3])
+        return preview or str(payload)
+    if isinstance(payload, (str, int, float, bool)):
+        return str(payload)
+    return None
+
+
+def _summarize_error_payload(response: httpx.Response) -> str:
+    context = _response_context(response)
+    try:
+        body_text = response.text or ""
+    except httpx.ResponseNotRead:
+        try:
+            response.read()  # ensure body is buffered so we can reuse it later
+            body_text = response.text or ""
+        except Exception as exc:  # noqa: BLE001
+            logger.debug("Failed to read response body for {}: {}", context, exc)
+            body_text = ""
+    payload = _safe_json_loads(body_text, context=f"{context} error body") if body_text else None
+    detail = _stringify_payload(payload)
+    if detail:
+        return detail
+    if body_text.strip():
+        return body_text.strip()
+    return "no response body"
+
+
+def _ensure_ok(response: httpx.Response) -> None:
+    request = response.request
+    if request is not None and request.extensions.get(_SKIP_ENSURE_OK_EXTENSION):
+        return
+    if response.status_code == httpx.codes.UNAUTHORIZED:
+        return
+    try:
+        response.raise_for_status()
+    except httpx.HTTPStatusError:
+        context = _response_context(response)
+        detail = _summarize_error_payload(response)
+        logger.error(
+            "{} failed with status {} {}: {}",
+            context,
+            response.status_code,
+            response.reason_phrase,
+            detail,
+        )
+        message = f"{context} failed with status {response.status_code}: {detail}"
+        raise SpeQtrumAPIError(message, request=response.request, response=response) from None
+
+
+class _BearerAuth(httpx.Auth):
+    """Bearer token auth handler with automatic refresh support."""
+
+    requires_response_body = True
+
+    def __init__(self, client: SpeQtrum) -> None:
+        self._client = client
+
+    def auth_flow(self, request: httpx.Request) -> Generator[httpx.Request, httpx.Response, None]:
+        request.headers["Authorization"] = f"Bearer {self._client.token.access_token}"
+        response = yield request
+
+        if response.status_code == httpx.codes.UNAUTHORIZED:
+            settings = get_settings()
+            refresh_request = httpx.Request(
+                "POST",
+                settings.speqtrum_api_url + "/authorisation-tokens/refresh",
+                headers={"Authorization": f"Bearer {self._client.token.refresh_token}"},
+                extensions=_request_extensions(context="Refreshing SpeQtrum token", skip_ensure_ok=True),
+            )
+            refresh_response = yield refresh_request
+
+            try:
+                refresh_response.raise_for_status()
+            except httpx.HTTPStatusError as exc:
+                logger.error(
+                    "Token refresh failed with status {} {}",
+                    exc.response.status_code,
+                    exc.response.reason_phrase,
+                )
+                raise
+
+            try:
+                payload = refresh_response.json()
+            except json.JSONDecodeError as exc:
+                logger.error("Token refresh returned invalid JSON: {}", exc)
+                raise RuntimeError("SpeQtrum token refresh failed: invalid JSON payload") from exc
+
+            if not isinstance(payload, dict):
+                logger.error("Token refresh returned non-object payload: {}", type(payload).__name__)
+                raise RuntimeError("SpeQtrum token refresh failed: malformed token payload")
+
+            payload.pop("refreshToken", None)
+
+            try:
+                token = Token(**payload, refreshToken=self._client.token.refresh_token)
+            except (TypeError, ValidationError) as exc:
+                logger.error("Token refresh returned malformed payload: {}", exc)
+                raise RuntimeError("SpeQtrum token refresh failed: malformed token payload") from exc
+
+            self._client.token = token
+            store_credentials(self._client.username, self._client.token)
+            request.headers["Authorization"] = f"Bearer {self._client.token.access_token}"
+            yield request
+
+
 class SpeQtrum:
     """Synchronous client for the Qilimanjaro SpeQtrum API."""
 
     def __init__(self) -> None:
-        logger.debug("Initializing QaaS client")
+        logger.debug("Initializing SpeQtrum client")
         credentials = load_credentials()
         if credentials is None:
-            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
-            ),
-            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)
+            logger.error("No credentials found. Call `SpeQtrum.login()` before instantiation.")
+            raise RuntimeError("Missing credentials - invoke SpeQtrum.login() first.")
+        self.username, self.token = credentials
+        logger.success("SpeQtrum client initialised for user '{}'", self.username)
 
     @classmethod
     def _get_headers(cls) -> dict:
@@ -78,8 +272,15 @@ class SpeQtrum:
 
         return {"User-Agent": f"qilisdk/{__version__}"}
 
-    def _get_authorized_headers(self) -> dict:
-        return {**self._get_headers(), "Authorization": f"Bearer {self._token.access_token}"}
+    def _create_client(self) -> httpx.Client:
+        """Return a freshly configured HTTP client for SpeQtrum interactions."""
+        settings = get_settings()
+        return httpx.Client(
+            base_url=settings.speqtrum_api_url,
+            headers=self._get_headers(),
+            auth=_BearerAuth(self),
+            event_hooks={"response": [_ensure_ok]},
+        )
 
     @classmethod
     def login(
@@ -108,7 +309,7 @@ class SpeQtrum:
         apikey = apikey or settings.speqtrum_apikey
 
         if not username or not apikey:
-            logger.warning("Login called without credentials - aborting")
+            logger.error("Login called without credentials.")
             return False
 
         # Send login request to QaaS
@@ -121,23 +322,24 @@ class SpeQtrum:
                 "iat": int(datetime.now(timezone.utc).timestamp()),
             }
             encoded_assertion = urlsafe_b64encode(json.dumps(assertion, indent=2).encode("utf-8")).decode("utf-8")
-            with httpx.Client(timeout=10.0) as client:
+            with httpx.Client(
+                base_url=settings.speqtrum_api_url,
+                headers=cls._get_headers(),
+                timeout=10.0,
+                event_hooks={"response": [_ensure_ok]},
+            ) as client:
                 response = client.post(
-                    settings.speqtrum_api_url + "/authorisation-tokens",
+                    "/authorisation-tokens",
                     json={
                         "grantType": "urn:ietf:params:oauth:grant-type:jwt-bearer",
                         "assertion": encoded_assertion,
                         "scope": "user profile",
                     },
-                    headers=cls._get_headers(),
+                    extensions=_request_extensions(context="Authenticating user"),
                 )
                 response.raise_for_status()
                 token = Token(**response.json())
-        except httpx.HTTPStatusError as exc:
-            logger.error("Login failed - server returned {} {}", exc.response.status_code, exc.response.reason_phrase)
-            return False
-        except httpx.RequestError:
-            logger.exception("Network error while logging in to QaaS")
+        except httpx.HTTPError:
             return False
 
         store_credentials(username=username, token=token)
@@ -161,12 +363,9 @@ class SpeQtrum:
             A list of :class:`~qilisdk.models.Device` objects.
         """
         logger.debug("Fetching device list from server…")
-        with httpx.Client() as client:
-            response = client.get(self._settings.speqtrum_api_url + "/devices", headers=self._get_authorized_headers())
-            response.raise_for_status()
-
-            devices = TypeAdapter(list[Device]).validate_python(response.json()["items"])
-
+        with self._create_client() as client:
+            response = client.get("/devices", extensions=_request_extensions(context="Fetching device list"))
+        devices = TypeAdapter(list[Device]).validate_python(response.json()["items"])
         logger.success("{} devices retrieved", len(devices))
         return [d for d in devices if where(d)] if where else devices
 
@@ -182,30 +381,33 @@ class SpeQtrum:
             A list of :class:`~qilisdk.models.JobInfo` objects.
         """
         logger.debug("Fetching job list…")
-        with httpx.Client() as client:
-            response = client.get(self._settings.speqtrum_api_url + "/jobs", headers=self._get_authorized_headers())
-            response.raise_for_status()
-
-            jobs = TypeAdapter(list[JobInfo]).validate_python(response.json()["items"])
-
+        with self._create_client() as client:
+            response = client.get("/jobs", extensions=_request_extensions(context="Fetching job list"))
+        jobs = TypeAdapter(list[JobInfo]).validate_python(response.json()["items"])
         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[TFunctionalResult]) -> TypedJobDetail[TFunctionalResult]: ...
+
+    @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)
-        with httpx.Client() as client:
+        job_id = job.id if isinstance(job, JobHandle) else job
+        logger.debug("Retrieving job {} details", job_id)
+        with self._create_client() as client:
             response = client.get(
-                f"{self._settings.speqtrum_api_url}/jobs/{id}",
-                headers=self._get_authorized_headers(),
+                f"/jobs/{job_id}",
                 params={
                     "payload": True,
                     "result": True,
@@ -213,55 +415,75 @@ class SpeQtrum:
                     "error_logs": True,
                     "error": True,
                 },
+                extensions=_request_extensions(context=f"Fetching job {job_id}"),
             )
-            response.raise_for_status()
-            data = response.json()
-
-        raw_payload = data["payload"]
-        if raw_payload is not None:
-            data["payload"] = json.loads(raw_payload)
+        data = response.json()
+        raw_payload = data.get("payload")
+        if isinstance(raw_payload, str):
+            data["payload"] = _safe_json_loads(raw_payload, context=f"job {job_id} payload")
 
         raw_result = data.get("result")
-        if raw_result is not None:
-            decoded_result: bytes = base64.b64decode(raw_result)
-            text_result = decoded_result.decode("utf-8")
-            data["result"] = json.loads(text_result)
+        if isinstance(raw_result, str):
+            data["result"] = _safe_b64_json(raw_result, context=f"job {job_id} result")
 
         raw_error = data.get("error")
-        if raw_error is not None:
-            decoded_error: bytes = base64.b64decode(raw_error)
-            data["error"] = decoded_error.decode("utf-8")
+        if isinstance(raw_error, str):
+            data["error"] = _safe_b64_decode(raw_error, context=f"job {job_id} error")
 
         raw_logs = data.get("logs")
-        if raw_logs is not None:
-            decoded_logs: bytes = base64.b64decode(raw_logs)
-            data["logs"] = decoded_logs.decode("utf-8")
+        if isinstance(raw_logs, str):
+            data["logs"] = _safe_b64_decode(raw_logs, context=f"job {job_id} logs")
+
+        raw_error_logs = data.get("error_logs")
+        if isinstance(raw_error_logs, str):
+            data["error_logs"] = _safe_b64_decode(raw_error_logs, context=f"job {job_id} error logs")
 
         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[TFunctionalResult],
+        *,
+        poll_interval: float = 5.0,
+        timeout: float | None = None,
+    ) -> TypedJobDetail[TFunctionalResult]: ...
+
+    @overload
+    def wait_for_job(
+        self,
+        job: int,
+        *,
+        poll_interval: float = 5.0,
+        timeout: float | None = None,
+    ) -> JobDetail: ...
+
     def wait_for_job(
         self,
-        id: int,
+        job: int | JobHandle[Any],
         *,
         poll_interval: float = 5.0,
         timeout: float | None = None,
-    ) -> JobDetail:
-        """Block until *id* reaches a terminal state.
+    ) -> 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 +493,65 @@ 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[TFunctionalResult]],
+        device: str,
+        job_name: str | None = None,
+    ) -> JobHandle[VariationalProgramResult[TFunctionalResult]]: ...
+
+    @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 +562,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,112 +574,223 @@ 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:
-            handler = self._handlers[type(functional)]
-        except KeyError as exc:
-            logger.error("Unsupported functional type: {}", type(functional).__qualname__)
-            raise NotImplementedError(
-                f"{type(self).__qualname__} does not support {type(functional).__qualname__}"
-            ) from exc
-
-        logger.info("Submitting {}", type(functional).__qualname__)
-        job_id = handler(functional, device)
-        logger.success("Submission complete - job {}", job_id)
-        return job_id
-
-    def _submit_sampling(self, sampling: Sampling, device: str) -> int:
+        if isinstance(functional, VariationalProgram):
+            inner = functional.functional
+            if isinstance(inner, Sampling):
+                return self._submit_variational_program(
+                    cast("VariationalProgram[Sampling]", functional), device, job_name
+                )
+            if isinstance(inner, TimeEvolution):
+                return self._submit_variational_program(
+                    cast("VariationalProgram[TimeEvolution]", functional), device, job_name
+                )
+
+            # Fallback to untyped handle for custom primitives.
+            job_handle = self._submit_variational_program(cast("VariationalProgram[Any]", functional), device, job_name)
+            return cast("JobHandle[FunctionalResult]", job_handle)
+
+        if isinstance(functional, Sampling):
+            return self._submit_sampling(functional, device, job_name)
+
+        if isinstance(functional, TimeEvolution):
+            return self._submit_time_evolution(functional, device, job_name)
+
+        if isinstance(functional, RabiExperiment):
+            return self._submit_rabi(functional, device, job_name)
+
+        if isinstance(functional, T1Experiment):
+            return self._submit_t1(functional, device, job_name)
+
+        if isinstance(functional, T2Experiment):
+            return self._submit_t2(functional, device, job_name)
+
+        if isinstance(functional, TwoTonesExperiment):
+            return self._submit_two_tones(functional, device, job_name)
+
+        logger.error("Unsupported functional type: {}", type(functional).__qualname__)
+        raise NotImplementedError(f"{type(self).__qualname__} does not support {type(functional).__qualname__}")
+
+    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(
-                self._settings.speqtrum_api_url + "/execute",
-                headers=self._get_authorized_headers(),
-                json=json,
-            )
-            response.raise_for_status()
-            job = JobId(**response.json())
-        return job.id
-
-    def _submit_rabi_program(self, rabi_experiment: RabiExperiment, device: str) -> int:
+        with self._create_client() as client:
+            response = client.post("/execute", json=json, extensions=_request_extensions(context="Executing Sampling"))
+        job = JobId(**response.json())
+        logger.info("Sampling job submitted: {}", job.id)
+        return JobHandle.sampling(job.id)
+
+    def _submit_rabi(
+        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:
+        with self._create_client() as client:
             response = client.post(
-                self._settings.speqtrum_api_url + "/execute",
-                headers=self._get_authorized_headers(),
+                "/execute",
                 json=json,
+                extensions=_request_extensions(context="Executing Rabi experiment"),
             )
-            response.raise_for_status()
-            job = JobId(**response.json())
+        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(
+        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:
+        with self._create_client() as client:
             response = client.post(
-                self._settings.speqtrum_api_url + "/execute",
-                headers=self._get_authorized_headers(),
+                "/execute",
                 json=json,
+                extensions=_request_extensions(context="Executing T1 experiment"),
             )
-            response.raise_for_status()
-            job = JobId(**response.json())
+        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_t2(
+        self, t2_experiment: T2Experiment, device: str, job_name: str | None = None
+    ) -> JobHandle[T2ExperimentResult]:
+        payload = ExecutePayload(
+            type=ExecuteType.T2_EXPERIMENT,
+            t2_experiment_payload=T2ExperimentPayload(t2_experiment=t2_experiment),
+        )
+        json = {
+            "device_code": device,
+            "payload": payload.model_dump_json(),
+            "job_type": JobType.PULSE,
+            "meta": {},
+        }
+        if job_name:
+            json["name"] = job_name
+        logger.debug("Executing T2 experiment on device {}", device)
+        with self._create_client() as client:
+            response = client.post(
+                "/execute",
+                json=json,
+                extensions=_request_extensions(context="Executing T2 experiment"),
+            )
+        job = JobId(**response.json())
+        logger.info("T2 experiment job submitted: {}", job.id)
+        return JobHandle.t2_experiment(job.id)
+
+    def _submit_two_tones(
+        self, two_tones_experiment: TwoTonesExperiment, device: str, job_name: str | None = None
+    ) -> JobHandle[TwoTonesExperimentResult]:
+        payload = ExecutePayload(
+            type=ExecuteType.TWO_TONES_EXPERIMENT,
+            two_tones_experiment_payload=TwoTonesExperimentPayload(two_tones_experiment=two_tones_experiment),
+        )
+        json = {
+            "device_code": device,
+            "payload": payload.model_dump_json(),
+            "job_type": JobType.PULSE,
+            "meta": {},
+        }
+        if job_name:
+            json["name"] = job_name
+        logger.debug("Executing Two-Tones experiment on device {}", device)
+        with self._create_client() as client:
+            response = client.post(
+                "/execute",
+                json=json,
+                extensions=_request_extensions(context="Executing Two-Tones experiment"),
+            )
+        job = JobId(**response.json())
+        logger.info("Two-Tones experiment job submitted: {}", job.id)
+        return JobHandle.two_tones_experiment(job.id)
+
+    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:
+        with self._create_client() as client:
             response = client.post(
-                self._settings.speqtrum_api_url + "/execute",
-                headers=self._get_authorized_headers(),
+                "/execute",
                 json=json,
+                extensions=_request_extensions(context="Executing time evolution"),
             )
-            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.
-        """
+        job = JobId(**response.json())
+        logger.info("Time Evolution job submitted: {}", job.id)
+        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,12 +798,20 @@ class SpeQtrum:
             "job_type": JobType.VARIATIONAL,
             "meta": {},
         }
-        with httpx.Client() as client:
+        if job_name:
+            json["name"] = job_name
+        logger.debug("Executing variational program on device {}", device)
+        with self._create_client() as client:
             response = client.post(
-                self._settings.speqtrum_api_url + "/execute",
-                headers=self._get_authorized_headers(),
+                "/execute",
                 json=json,
+                extensions=_request_extensions(context="Executing variational program"),
             )
-            response.raise_for_status()
-            job = JobId(**response.json())
-            return job.id
+        job = JobId(**response.json())
+        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)