luna-quantum 1.1.0__cp312-cp312-win_amd64.whl

luna_quantum/client/controllers/luna_q.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from luna_quantum.client.controllers.luna_platform_client import (
+    LunaPlatformClient,
+    LunaPrefixEnum,
+)
+from luna_quantum.client.interfaces.services.luna_q_i import ILunaQ
+from luna_quantum.client.rest_client import CircuitRestClient, QpuTokenRestClient
+
+if TYPE_CHECKING:
+    from luna_quantum.client.interfaces.clients import ICircuitRestClient
+    from luna_quantum.client.interfaces.clients.qpu_token_rest_client_i import (
+        IQpuTokenRestClient,
+    )
+
+
+class LunaQ(LunaPlatformClient, ILunaQ):
+    """Implementation of LunaQ service."""
+
+    qpu_token: IQpuTokenRestClient = None  # type: ignore[assignment]
+    circuit: ICircuitRestClient = None  # type: ignore[assignment]
+
+    def __init__(
+        self, api_key: str | None = None, timeout: float | None = 240.0
+    ) -> None:
+        """
+        LunaQ is the main entrypoint for all LunaQ related tasks.
+
+        Parameters
+        ----------
+        api_key: str
+            User's API key
+        timeout: float
+            Default timeout in seconds for the requests via the LunaQ client. `None`
+            means that the SDK uses no timeouts. Note that either way the Luna platform
+            itself will time out after 240 seconds.
+            Default: 240.0
+        """
+        super().__init__(api_key=api_key, timeout=timeout)
+
+        self.circuit = CircuitRestClient(self)
+        self.qpu_token = QpuTokenRestClient(self)
+
+    @classmethod
+    def get_api(cls) -> LunaPrefixEnum:
+        """Return the api of the client."""
+        return LunaPrefixEnum.LUNA_Q
+
+    @classmethod
+    def authenticate(cls, api_key: str) -> None:
+        """
+        Authenticate the client with the given API key.
+
+        Parameters
+        ----------
+        api_key : str
+            The API key used to authenticate the client.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+        """
+        cls(api_key=api_key)
+        cls._api_key = api_key

luna_quantum/client/controllers/luna_solve.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from luna_quantum.client.controllers.luna_platform_client import (
+    LunaPlatformClient,
+    LunaPrefixEnum,
+)
+from luna_quantum.client.interfaces.services.luna_solve_i import ILunaSolve
+from luna_quantum.client.rest_client.info_rest_client import InfoRestClient
+from luna_quantum.client.rest_client.model_rest_client import (
+    ModelRestClient,
+)
+from luna_quantum.client.rest_client.qpu_token_rest_client import QpuTokenRestClient
+from luna_quantum.client.rest_client.solve_job_rest_client import SolveJobRestClient
+
+if TYPE_CHECKING:
+    from luna_quantum.client.interfaces.clients import ISolveJobRestClient
+    from luna_quantum.client.interfaces.clients.info_rest_client_i import (
+        IInfoRestClient,
+    )
+    from luna_quantum.client.interfaces.clients.model_rest_client_i import (
+        IModelRestClient,
+    )
+    from luna_quantum.client.interfaces.clients.qpu_token_rest_client_i import (
+        IQpuTokenRestClient,
+    )
+
+
+class LunaSolve(LunaPlatformClient, ILunaSolve):
+    """Implementation of LunaSolve service."""
+
+    _model: IModelRestClient
+    _solve_job: ISolveJobRestClient
+    _qpu_token: IQpuTokenRestClient
+    _info: IInfoRestClient
+
+    def __init__(
+        self, api_key: str | None = None, timeout: float | None = 240.0
+    ) -> None:
+        """
+        LunaSolve is the main entrypoint for all LunaSolve related tasks.
+
+        Parameters
+        ----------
+        api_key: str
+            User's API key
+        timeout: float
+            Default timeout in seconds for the requests via the LunaQ client. `None`
+            means that the SDK uses no timeouts. Note that either way the Luna platform
+            itself will time out after 240 seconds.
+            Default: 240.0
+        """
+        super().__init__(
+            api_key=api_key,
+            timeout=timeout,
+        )
+
+        self._model = ModelRestClient(self)
+        self._solve_job = SolveJobRestClient(self)
+        self._qpu_token = QpuTokenRestClient(self)
+        self._info = InfoRestClient(self)
+
+    @classmethod
+    def get_api(cls) -> LunaPrefixEnum:
+        """Return the api of the client."""
+        return LunaPrefixEnum.LUNA_SOLVE
+
+    @classmethod
+    def authenticate(cls, api_key: str) -> None:
+        """
+        Authenticate the client with the given API key.
+
+        Parameters
+        ----------
+        api_key : str
+            The API key used to authenticate the client.
+
+        Returns
+        -------
+        None
+            This method does not return any value.
+        """
+        cls(api_key=api_key)
+        cls._api_key = api_key
+
+    @property
+    def model(self) -> IModelRestClient:
+        """
+        Returns a model rest client.
+
+        Returns
+        -------
+        IModelRestClient
+        """
+        return self._model
+
+    @property
+    def solve_job(self) -> ISolveJobRestClient:
+        """
+        Returns a solve job rest client.
+
+        Returns
+        -------
+        ISolveJobRestClient
+        """
+        return self._solve_job
+
+    @property
+    def qpu_token(self) -> IQpuTokenRestClient:
+        """
+        Returns a qpu token rest client.
+
+        Returns
+        -------
+        IQpuTokenRestClient
+        """
+        return self._qpu_token
+
+    @property
+    def info(self) -> IInfoRestClient:
+        """
+        Returns an info rest client.
+
+        Returns
+        -------
+        IInfoRestClient
+        """
+        return self._info

luna_quantum/client/error/luna_api_key_invalid_error.py

@@ -0,0 +1,10 @@
+from luna_quantum.client.error.luna_error import LunaError
+
+
+class LunaApiKeyInvalidError(LunaError):
+    """Raised when the Luna API key is invalid."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Luna API key is invalid. Please provide a valid Luna API key."
+        )

luna_quantum/client/error/luna_api_key_missing_error.py

@@ -0,0 +1,10 @@
+from luna_quantum.client.error.luna_error import LunaError
+
+
+class LunaApiKeyMissingError(LunaError):
+    """Raised when the Luna API key is missing."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Luna API key is missing. Please set the LUNA_API_KEY environment variable."
+        )

luna_quantum/client/error/luna_error.py

@@ -0,0 +1,2 @@
+class LunaError(Exception):
+    """Base exception for all exceptions in the Luna SDK."""

luna_quantum/client/error/luna_server_error.py

@@ -0,0 +1,20 @@
+from luna_quantum.client.error.luna_error import LunaError
+from luna_quantum.client.schemas.error_message import ErrorMessage
+
+
+class LunaServerError(LunaError):
+    """Luna HTTP server error."""
+
+    http_status_code: int
+    error_message: ErrorMessage
+
+    def __init__(self, http_status_code: int, error_message: ErrorMessage) -> None:
+        self.http_status_code = http_status_code
+        self.error_message = error_message
+        super().__init__(error_message.message)
+
+    def __str__(self) -> str:  # noqa: D105
+        return (
+            f"The Luna-Server reported the error '{self.error_message.internal_code}' "
+            f"with the message:\n {self.error_message.message}"
+        )

luna_quantum/client/error/timeout_error.py

@@ -0,0 +1,12 @@
+from luna_quantum.client.error.luna_error import LunaError
+
+
+class LunaTimeoutError(LunaError):
+    """Luna timeout error."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            "Luna Timeout. The request took too long to complete."
+            " Please increase timeout value or try again later."
+            " If the problem persists, please contact our support team."
+        )

luna_quantum/client/error/transformation_error.py

@@ -0,0 +1,18 @@
+from luna_quantum.client.error.luna_error import LunaError
+
+
+class TransformationError(LunaError):
+    """Luna transformation error."""
+
+    def __str__(self) -> str:  # noqa: D105
+        return (
+            "An unexpected error occurred during transformation,"
+            " please contact support or open an issue."
+        )
+
+
+class WeightedConstraintError(LunaError):
+    """Error if weighted constraints provided in CQM."""
+
+    def __str__(self) -> str:  # noqa: D105
+        return "Weighted constraints for CQM are not supported"

luna_quantum/client/error/utils/http_error_utils.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from http import HTTPStatus
+
+import httpx
+from httpx import RequestError, Response
+
+from luna_quantum.client.error.luna_server_error import LunaServerError
+from luna_quantum.client.schemas.error_message import ErrorMessage
+from luna_quantum.util.log_utils import Logging
+
+logger = Logging.get_logger(__name__)
+
+
+class HttpErrorUtils:
+    """Class for handling Luna HTTP errors."""
+
+    @staticmethod
+    def __sdk_custom_request_errors(
+        response: Response,
+    ) -> LunaServerError | None:
+        """
+        Check if the response needs a custom error message from the SDK.
+
+        This is the place to add other custom error messages.
+        It's helpful then the default http error messages are not enough for the user.
+
+        Parameters
+        ----------
+        response:
+            Response object from the request
+
+        Returns
+        -------
+        Optional[LunaServerError]
+            If the response needs a custom error message, return the exception.
+            Otherwise, return None.
+        """
+        exception: LunaServerError | None = None
+
+        def create_error_message(internal_code: str, message: str) -> LunaServerError:
+            return LunaServerError(
+                response.status_code,
+                ErrorMessage(
+                    internal_code=f"SDK-{internal_code}",
+                    message=message,
+                ),
+            )
+
+        if response.status_code == HTTPStatus.BAD_GATEWAY:
+            # Catch error when upload was too long
+            exception = create_error_message(
+                "LUNA_GATEWAY_TIMEOUT",
+                "The Luna server did not respond within time,"
+                " leading to a timeout. Try reducing the size of the model.",
+            )
+
+        elif response.status_code == HTTPStatus.FORBIDDEN:
+            exception = create_error_message(
+                "FORBIDDEN",
+                response.text,
+            )
+
+        return exception
+
+    @staticmethod
+    def check_for_error(response: Response) -> None:
+        """
+        Check if an error occurred and rais the error if so.
+
+        Parameters
+        ----------
+        response: Response
+            Response object from the request
+
+        Raises
+        ------
+        LunaServerException
+            If an error occurred with the request.
+            The error message is in the exception.
+        RequestError
+            If an error occurred with the request outside the http status codes
+             4xx and 5xx.
+        """
+        try:
+            response.read()
+            response.raise_for_status()
+        except httpx.HTTPStatusError:
+            exception: LunaServerError | None
+
+            try:
+                error_msg: ErrorMessage = ErrorMessage.model_validate_json(
+                    response.text
+                )
+                # Convert the error message to the correct exception
+                exception = LunaServerError(response.status_code, error_msg)
+
+            except ValueError:
+                # The server can generate errors that are in a different format, and we
+                # have less to no control how they look like.
+                # In this case, we will try to create a custom error messages.
+                exception = HttpErrorUtils.__sdk_custom_request_errors(response)
+
+            if exception:
+                logger.exception(exception, exc_info=False)
+                raise exception from None
+            logger.error(exception, exc_info=True)
+            raise
+
+        except RequestError as e:
+            logger.error(e, exc_info=True)
+            raise

luna_quantum/client/interfaces/__init__.py

@@ -0,0 +1,4 @@
+from luna_quantum.client.interfaces.clients.rest_client_i import IRestClient
+from luna_quantum.client.interfaces.services.service_i import IService
+
+__all__ = ["IRestClient", "IService"]

luna_quantum/client/interfaces/clients/__init__.py

@@ -0,0 +1,25 @@
+from luna_quantum.client.interfaces.clients.circuit_rest_client_i import (
+    ICircuitRestClient,
+)
+from luna_quantum.client.interfaces.clients.info_rest_client_i import IInfoRestClient
+from luna_quantum.client.interfaces.clients.model_rest_client_i import (
+    IModelRestClient,
+)
+from luna_quantum.client.interfaces.clients.qpu_token_rest_client_i import (
+    IQpuTokenRestClient,
+)
+from luna_quantum.client.interfaces.clients.rest_client_i import IRestClient
+from luna_quantum.client.interfaces.clients.solve_job_rest_client_i import (
+    ISolveJobRestClient,
+)
+from luna_quantum.client.interfaces.clients.users_rest_client_i import IUsersRestClient
+
+__all__ = [
+    "ICircuitRestClient",
+    "IInfoRestClient",
+    "IModelRestClient",
+    "IQpuTokenRestClient",
+    "IRestClient",
+    "ISolveJobRestClient",
+    "IUsersRestClient",
+]

luna_quantum/client/interfaces/clients/circuit_rest_client_i.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from luna_quantum.client.interfaces.clients.rest_client_i import IRestClient
+
+if TYPE_CHECKING:
+    from luna_quantum.client.schemas.circuit import CircuitJob, CircuitResult
+    from luna_quantum.client.schemas.enums.circuit import CircuitProviderEnum
+    from luna_quantum.client.schemas.qpu_token.qpu_token import TokenProvider
+
+
+class ICircuitRestClient(IRestClient, ABC):
+    """Interface for circuit rest client."""
+
+    @abstractmethod
+    def create(
+        self,
+        circuit: str,
+        provider: CircuitProviderEnum,
+        params: dict[str, Any] | None = None,
+        qpu_tokens: TokenProvider | None = None,
+        **kwargs: Any,
+    ) -> CircuitJob:
+        """
+        Create a circuit solution.
+
+        Parameters
+        ----------
+        circuit: str
+            The circuit which to create a solution for.
+        provider: CircuitProviderEnum
+            Which provider to use to solve the circuit.
+        params: Dict[str, Any]
+            Additional parameters of the circuit.
+        qpu_tokens: Optional[TokenProvider]
+            The tokens to be used for the QPU.
+        **kwargs
+            Parameters to pass to `httpx.request`.
+
+        Returns
+        -------
+        CircuitJob
+            The created circuit job.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def get(
+        self,
+        job: CircuitJob,
+        **kwargs: Any,
+    ) -> CircuitResult:
+        """
+        Get the result of a circuit.
+
+        Parameters
+        ----------
+        **kwargs
+            Parameters to pass to `httpx.request`.
+
+        Returns
+        -------
+        CircuitResult
+            The result of solving the circuit.
+        """
+        raise NotImplementedError

luna_quantum/client/interfaces/clients/info_rest_client_i.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from luna_quantum.client.interfaces.clients.rest_client_i import IRestClient
+
+if TYPE_CHECKING:
+    from luna_quantum.client.schemas.solver_info import SolverInfo
+
+
+class IInfoRestClient(IRestClient, ABC):
+    """Interface of the info rest client."""
+
+    @abstractmethod
+    def solvers_available(
+        self, solver_name: str | None = None, **kwargs: dict[str, Any]
+    ) -> dict[str, dict[str, SolverInfo]]:
+        """
+        Get list of available solvers.
+
+        Parameters
+        ----------
+        solver_name: Optional[str]
+            Name of the solver that should be retrieved. If not specified, all solvers
+            will be returned.
+        **kwargs
+            Parameters to pass to `httpx.request`.
+
+        Returns
+        -------
+        Dict[str, Dict[str, SolverInfo]]
+            Dictionary containing the provider name as the key, and a dictionary of
+            the solver name and solver-specific information as the value.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    def providers_available(self, **kwargs: dict[str, Any]) -> list[str]:
+        """
+        Get list of available providers.
+
+        Parameters
+        ----------
+        **kwargs
+            Parameters to pass to `httpx.request`.
+
+        Returns
+        -------
+        List[str]
+            List of available QPU providers.
+        """
+        raise NotImplementedError

luna_quantum/client/interfaces/clients/model_rest_client_i.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from luna_quantum.client.interfaces.clients.rest_client_i import IRestClient
+
+if TYPE_CHECKING:
+    from luna_quantum.aqm_overwrites.model import Model
+    from luna_quantum.client.schemas.enums.timeframe import TimeframeEnum
+    from luna_quantum.client.schemas.model_metadata import ModelMetadataSchema
+    from luna_quantum.solve.use_cases import UseCase
+
+
+class IModelRestClient(IRestClient, ABC):
+    """Interface for model rest client."""
+
+    @abstractmethod
+    def get(self, model_id: str, **kwargs: dict[str, Any]) -> ModelMetadataSchema:
+        """
+        Retrieve the model metadata by its id.
+
+        Parameters
+        ----------
+        model_id: str
+            Id of the model to be retrieved.
+        **kwargs
+            Parameters to pass to `httpx.request`.
+
+        Returns
+        -------
+        ModelMetadataSchema:
+            Metadata of the model.
+        """
+
+    @abstractmethod
+    def get_model(self, model_id: str, **kwargs: dict[str, Any]) -> Model:
+        """
+        Retrieve a model by the id.
+
+        Parameters
+        ----------
+        model_id: str
+            Id of the model to be retrieved.
+        **kwargs
+            Parameters to pass to `httpx.request`.
+
+        Returns
+        -------
+        Model:
+            The model.
+
+        """
+
+    @abstractmethod
+    def get_metadata_by_hash(self, model_hash: int) -> ModelMetadataSchema:
+        """
+        Retrieve metadata for a model using its hash.
+
+        This method fetches metadata associated with a given model hash.
+
+        Parameters
+        ----------
+        model_hash : int
+            The hash identifier of the model.
+
+        Returns
+        -------
+        ModelMetadataSchema
+            Metadata information of the model.
+        """
+
+    @abstractmethod
+    def get_all(
+        self,
+        timeframe: TimeframeEnum | None = None,
+        limit: int = 50,
+        offset: int = 0,
+        **kwargs: dict[str, Any],
+    ) -> list[ModelMetadataSchema]:
+        """
+        Retrieve a list of model metadata.
+
+        Parameters
+        ----------
+        timeframe: Optional[TimeframeEnum]
+            Only return optimizations created within a specified timeframe.
+            Default None.
+        limit:
+            Limit the number of optimizations to be returned. Default value 50.
+        offset:
+            Offset the list of optimizations by this amount. Default value 0.
+        **kwargs
+            Parameters to pass to `httpx.request`.
+
+        Returns
+        -------
+        List[ModelMetadataSchema]:
+            List of model metadata.
+        """
+
+    @abstractmethod
+    def create(self, model: Model) -> ModelMetadataSchema:
+        """
+        Create a model based on the provided Model instance.
+
+        This function saves the model and returns metadata about it.
+
+        Parameters
+        ----------
+        model : Model
+            Instance of the Model which should be saved.
+
+        Returns
+        -------
+        ModelMetadataSchema
+            Metadata of the created model containing information about its
+            configuration and properties.
+
+        """
+
+    @abstractmethod
+    def create_from_use_case(
+        self, name: str, use_case: UseCase, **kwargs: Any
+    ) -> ModelMetadataSchema:
+        """Create a model from a use case."""
+
+    @abstractmethod
+    def delete(self, model_id: str, **kwargs: dict[str, Any]) -> None:
+        """
+        Delete a model and the model metadata by its id.
+
+        Parameters
+        ----------
+        model_id: str
+            Id of the model to be deleted.
+        **kwargs
+            Parameters to pass to `httpx.request`.
+        """