luna-quantum 1.1.0__cp312-cp312-win_amd64.whl

luna_quantum/client/rest_client/solve_job_rest_client.py

@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from pydantic import BaseModel
+
+from luna_quantum._core import Solution
+from luna_quantum.client.interfaces.clients.solve_job_rest_client_i import (
+    ISolveJobRestClient,
+)
+from luna_quantum.client.schemas import TokenProvider
+from luna_quantum.client.schemas.create.solve_job_create import SolveJobCreate
+from luna_quantum.client.schemas.enums.timeframe import TimeframeEnum
+from luna_quantum.client.schemas.qpu_token.token_provider import RestAPITokenProvider
+from luna_quantum.client.schemas.solution import (
+    UseCaseRepresentation,
+    UseCaseResult,
+)
+from luna_quantum.client.schemas.solve_job import SolveJobSchema
+from luna_quantum.client.utils.qpu_token_utils import QpuTokenUtils
+from luna_quantum.util.log_utils import Logging
+
+if TYPE_CHECKING:
+    from logging import Logger
+
+
+class SolveJobRestClient(ISolveJobRestClient):
+    """Impelentation of a solve job REST client."""
+
+    logger: ClassVar[Logger] = Logging.get_logger(__name__)
+
+    def get_solution(self, solve_job_id: str, **kwargs: Any) -> Solution:
+        """
+        Retrieve one solution by id.
+
+        Parameters
+        ----------
+        solve_job_id: str
+            Id of the solve job for which a solution should be retrieved.
+        **kwargs
+            Parameters to pass to `httpx.request`.
+
+        Returns
+        -------
+        Solution
+            Solution instance
+        """
+        response = self._client.get(f"{self._endpoint}/data/{solve_job_id}", **kwargs)
+
+        response.raise_for_status()
+
+        return Solution.deserialize(response.content)
+
+    def cancel(self, solve_job_id: str, **kwargs: Any) -> SolveJobSchema:
+        """
+        Cancel a solve job for an id.
+
+        Parameters
+        ----------
+        solve_job_id: str
+            The id of the solve job which should be canceled.
+        **kwargs
+            Parameters to pass to `httpx.request`.
+
+        Returns
+        -------
+        SolveJobSchema
+            The updated solve job, which can be used to retrieve the solution later.
+        """
+        response = self._client.post(
+            f"{self._endpoint}/metadata/{solve_job_id}/cancel", **kwargs
+        )
+
+        response.raise_for_status()
+
+        return SolveJobSchema.model_validate(response.json())
+
+    @property
+    def _endpoint(self) -> str:
+        return "/solve-jobs"
+
+    def get(self, solve_job_id: str, **kwargs: Any) -> SolveJobSchema:
+        """
+        Retrieve one SolveJob by id.
+
+        Parameters
+        ----------
+        solve_job_id: str
+            Id of the solve job that should be retrieved.
+        **kwargs
+            Parameters to pass to `httpx.request`.
+
+        Returns
+        -------
+        SolveJobSchema
+            Instance of SolveJob.
+        """
+        response = self._client.get(
+            f"{self._endpoint}/metadata/{solve_job_id}", **kwargs
+        )
+
+        response.raise_for_status()
+
+        return SolveJobSchema.model_validate(response.json())
+
+    def get_all(
+        self,
+        timeframe: TimeframeEnum | None = None,
+        limit: int = 50,
+        offset: int = 0,
+        model_id: str | None = None,
+        **kwargs: Any,
+    ) -> list[SolveJobSchema]:
+        """
+        Get list of available SolveJobs.
+
+        Parameters
+        ----------
+        timeframe: Optional[TimeframeEnum]
+            Only return SolveJobs created within a specified timeframe. Default None.
+        limit:
+            Limit the number of SolveJobs to be returned. Default value 10.
+        offset:
+            Offset the list of solve job by this amount. Default value 0.
+        model_id: Optional[str]
+            Show solve job for only this model id. Default None.
+        **kwargs
+            Parameters to pass to `httpx.request`.
+
+        Returns
+        -------
+        List[SolveJobSchema]
+            List of SolveJob instances.
+        """
+        params = {}
+        if timeframe and timeframe != TimeframeEnum.all_time:  # no value == all_time
+            params["timeframe"] = timeframe.value
+
+        limit = max(limit, 1)
+
+        if model_id is not None:
+            params["model_id"] = str(model_id)
+
+        params["limit"] = str(limit)
+        params["offset"] = str(offset)
+        response = self._client.get(
+            f"{self._endpoint}/metadata", params=params, **kwargs
+        )
+
+        response.raise_for_status()
+
+        return [SolveJobSchema.model_validate(i) for i in response.json()]
+
+    def delete(self, solve_job_id: str, **kwargs: Any) -> None:
+        """
+        Delete one solution by id.
+
+        Parameters
+        ----------
+        solve_job_id: str
+            Id of the solve job that should be deleted.
+        **kwargs
+            Parameters to pass to `httpx.request`.
+        """
+        self._client.delete(f"{self._endpoint}/{solve_job_id}", **kwargs)
+
+    def create(  # noqa: PLR0913
+        self,
+        model_id: str,
+        solver_name: str,
+        provider: str,
+        qpu_tokens: TokenProvider | None = None,
+        solver_parameters: dict[str, Any] | BaseModel | None = None,
+        name: str | None = None,
+        **kwargs: Any,
+    ) -> SolveJobSchema:
+        """
+        Create a solution for a model.
+
+        Parameters
+        ----------
+        model_id: str
+            The id of the model for which solution should be created.
+        solver_name: str
+            The name of the solver to use.
+        provider: str
+            The name of the provider to use.
+        qpu_tokens: Optional[TokenProvider]
+            The tokens to be used for the QPU.
+        solver_parameters: Optional[Union[Dict[str, Any], BaseModel]]
+            Parameters to be passed to the solver.
+        name: Optional[str]
+            Default: None, The name of the solution to create.
+        **kwargs
+            Parameters to pass to `httpx.request`.
+
+        Returns
+        -------
+        SolveJobSchema
+            The created solve job, which can be used to retrieve the solution later.
+        """
+        if qpu_tokens is not None:
+            rest_qpu_tokens = RestAPITokenProvider.from_sdk_token_provider(
+                TokenProvider.model_validate(qpu_tokens)
+            )
+        else:
+            rest_qpu_tokens = None
+        # try to retrieve qpu tokens from env variables
+
+        if rest_qpu_tokens is None:
+            qpu_tokens = QpuTokenUtils.patch_qpu_tokens_from_env()
+            if qpu_tokens is not None:
+                rest_qpu_tokens = RestAPITokenProvider.from_sdk_token_provider(
+                    qpu_tokens
+                )
+        params: dict[str, Any]
+
+        if isinstance(solver_parameters, BaseModel):
+            params = solver_parameters.model_dump()
+        elif isinstance(solver_parameters, dict):
+            params = solver_parameters
+        else:
+            params = {}
+
+        solve_job_create = SolveJobCreate(
+            model_id=model_id,
+            solver_name=solver_name,
+            provider=provider,
+            parameters=params,
+            qpu_tokens=rest_qpu_tokens,
+            name=name,
+        )
+        SolveJobRestClient.logger.debug(
+            solve_job_create.model_dump_json(exclude={"qpu_tokens"})
+        )
+        response = self._client.post(
+            self._endpoint, content=solve_job_create.model_dump_json(), **kwargs
+        )
+        response.raise_for_status()
+
+        return SolveJobSchema.model_validate(response.json())
+
+    def get_use_case_representation(
+        self, solve_job_id: str, **kwargs: Any
+    ) -> UseCaseRepresentation:
+        """
+        Get the use-case-specific representation of a solution.
+
+        Parameters
+        ----------
+        solve_job_id: str
+            Id of the solve job that should be retrieved.
+        **kwargs
+            Parameters to pass to `httpx.request`.
+
+        Returns
+        -------
+        UseCaseRepresentation
+            The use-case-specific representation
+        """
+        response = self._client.get(
+            f"{self._endpoint}/use-case/{solve_job_id}/representation", **kwargs
+        )
+        response.raise_for_status()
+        return UseCaseRepresentation.model_validate(response.json())
+
+    def get_best_use_case_result(
+        self,
+        use_case_representation: UseCaseRepresentation,  # noqa: ARG002
+    ) -> UseCaseResult | None:
+        """
+        Retrieve the best result from a solution's use case representation.
+
+        Parameters
+        ----------
+        use_case_representation : UseCaseRepresentation
+            A solution's use case representation.
+
+        Returns
+        -------
+        Optional[UseCaseResult]
+            The best result of the solution. If there are several best solve job with
+            the same objective value, return only the first. If the solution results are
+            not (yet) available or the solution sense is `None`, `None` is returned.
+        """
+        return None

luna_quantum/client/rest_client/users_rest_client.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from luna_quantum.client.interfaces.clients import IUsersRestClient
+from luna_quantum.client.schemas.user import User
+
+if TYPE_CHECKING:
+    from httpx import Response
+
+
+class UsersRestClient(IUsersRestClient):
+    """UsersRestClient is a class for interacting with the Luna API's users endpoint."""
+
+    @property
+    def _endpoint(self) -> str:
+        return "/users"
+
+    def get_me(self, **kwargs: Any) -> User:
+        """
+        Retrieve information about user.
+
+        Parameters
+        ----------
+        **kwargs
+            Parameters to pass to `httpx.request`.
+
+        Returns
+        -------
+        User:
+            User data.
+        """
+        response: Response = self._client.get(f"{self._endpoint}/me", **kwargs)
+        response.raise_for_status()
+        return User.model_validate_json(response.text)

luna_quantum/client/schemas/__init__.py

@@ -0,0 +1,26 @@
+from luna_quantum.client.schemas.circuit import CircuitJob, CircuitResult
+from luna_quantum.client.schemas.qpu_token.qpu_token import (
+    QpuToken,
+    QpuTokenOut,
+    QpuTokenSource,
+    TokenProvider,
+)
+from luna_quantum.client.schemas.solution import (
+    Result,
+    Runtime,
+    UseCaseRepresentation,
+    UseCaseResult,
+)
+
+__all__ = [
+    "CircuitJob",
+    "CircuitResult",
+    "QpuToken",
+    "QpuTokenOut",
+    "QpuTokenSource",
+    "Result",
+    "Runtime",
+    "TokenProvider",
+    "UseCaseRepresentation",
+    "UseCaseResult",
+]

luna_quantum/client/schemas/circuit.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from luna_quantum.client.schemas.enums.circuit import (
+    CircuitProviderEnum,
+    CircuitStatusEnum,
+)
+
+
+class CircuitJob(BaseModel):
+    """
+    Object responsible of retrieving a circuit solution.
+
+    Attributes
+    ----------
+    id: str
+        Id of the circuit job.
+    provider: CircuitProviderEnum
+        The provider used to solve this circuit.
+    params: Dict[str, Any]
+        Additional parameters that were used to create the circuit.
+    """
+
+    id: str
+    provider: CircuitProviderEnum
+    params: dict[str, Any] | None = None
+
+
+class CircuitResult(BaseModel):
+    """
+    The result of solving the circuit.
+
+    Attributes
+    ----------
+    result: Optional[Dict[str, Any]]
+        The result if the job succeeded. Otherwise None
+    error: Optional[str]
+        The error message if the job failed. Otherwise None
+    status: CircuitStatusEnum
+        The job status.
+    """
+
+    status: CircuitStatusEnum
+    result: dict[str, Any] | None = None
+    error_message: str | None = None

luna_quantum/client/schemas/create/__init__.py

@@ -0,0 +1,15 @@
+from luna_quantum.client.schemas.create.circuit import CircuitIn
+from luna_quantum.client.schemas.create.qpu_token import QpuTokenIn
+from luna_quantum.client.schemas.create.qpu_token_time_quota import QpuTokenTimeQuotaIn
+from luna_quantum.client.schemas.create.qpu_token_time_quota_update import (
+    QpuTokenTimeQuotaUpdate,
+)
+from luna_quantum.client.schemas.create.qubo import QUBOIn
+
+__all__ = [
+    "CircuitIn",
+    "QUBOIn",
+    "QpuTokenIn",
+    "QpuTokenTimeQuotaIn",
+    "QpuTokenTimeQuotaUpdate",
+]

luna_quantum/client/schemas/create/circuit.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from luna_quantum.client.schemas.enums.circuit import CircuitProviderEnum
+from luna_quantum.client.schemas.qpu_token.token_provider import (
+    RestAPITokenProvider,
+)
+
+
+class CircuitIn(BaseModel):
+    """
+    Pydantic model for creation of circuits.
+
+    Attributes
+    ----------
+    provider: str
+        The provider for circuit solving
+    provider: ProviderEnum
+        The QASM circuit
+    params: Dict[str, Any]
+        Additional parameters
+    """
+
+    provider: CircuitProviderEnum
+    circuit: str
+    params: dict[str, Any] = {}
+    qpu_tokens: RestAPITokenProvider | None = None

luna_quantum/client/schemas/create/optimization.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Any, Generic, TypeVar
+
+from pydantic import BaseModel
+
+from luna_quantum.solve.use_cases import UseCase
+
+# This works but is kind of ugly.
+# In the future, we should find another solution for "dumping" a child of UseCase
+# with the name and params.
+# OptimizationUseCaseIn can still be created like this:
+# `opt = optimizationusecasein(name=name, use_case=use_case)`
+# Somehow this tricks pydantic into accepting the child of UseCase and adding
+# it to the model_dump_json. Without the Generic[UseCase] only the name will be
+# added to the model_dump_json
+
+_UseCase = TypeVar("_UseCase", bound=UseCase)
+
+
+class OptimizationUseCaseIn(BaseModel, Generic[_UseCase]):
+    """
+    Input schema for creating an optimization use case.
+
+    Attributes
+    ----------
+    name : str
+        A name for the optimization use case.
+
+    use_case : _UseCase
+        The actual use case object containing the problem definition.
+
+    params : dict[str, Any] | None
+        Optional dictionary of additional parameters for the optimization.
+    """
+
+    name: str
+    use_case: _UseCase
+    params: dict[str, Any] | None

luna_quantum/client/schemas/create/qpu_token.py

@@ -0,0 +1,22 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class QpuTokenIn(BaseModel):
+    """
+    Pydantic model for creation QPU token.
+
+    Attributes
+    ----------
+    name: str
+        Name of the QPU token
+    provider: ProviderEnum
+        Name of provider
+    token: str
+        Token
+    """
+
+    name: str
+    provider: str
+    token: str
+
+    model_config = ConfigDict(extra="forbid")

luna_quantum/client/schemas/create/qpu_token_time_quota.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import BaseModel, Field, model_validator
+
+from luna_quantum.client.schemas.wrappers import PydanticDatetimeWrapper
+
+
+class QpuTokenTimeQuotaIn(BaseModel):
+    """
+    Pydantic model for creating a time quota on a qpu token.
+
+    Attributes
+    ----------
+    quota: int
+        The amount of quota.
+    start: datetime | None
+        Effective start date of the time quota policy.
+        If None, policy will be in effect immediately.
+    end: datetime | None
+        Effective end date of the time quota policy.
+        If None, policy will be in effect until 365 days after the start date.
+    """
+
+    quota: int = Field(ge=0)
+    start: PydanticDatetimeWrapper | None
+    end: PydanticDatetimeWrapper | None
+
+    @model_validator(mode="after")
+    def check_start_end_dates(self) -> Self:
+        """Cheks that start date is befor end date if both provided."""
+        if self.start is not None and self.end is not None and self.start > self.end:
+            raise ValueError("Start date cannot be after end date.")  # noqa: TRY003
+        return self

luna_quantum/client/schemas/create/qpu_token_time_quota_update.py

@@ -0,0 +1,24 @@
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from luna_quantum.client.schemas.wrappers.datetime_wrapper import (
+    PydanticDatetimeWrapper,
+)
+
+
+class QpuTokenTimeQuotaUpdate(BaseModel):
+    """Data structure to update the time quota of a qpu token."""
+
+    quota: int | None = Field(ge=0, default=None)
+    start: PydanticDatetimeWrapper | None = None
+    end: PydanticDatetimeWrapper | None = None
+
+    model_config = ConfigDict(extra="forbid")
+
+    @model_validator(mode="after")
+    def check_start_end_dates(self) -> Self:
+        """Cheks that start date is befor end date if both provided."""
+        if self.start is not None and self.end is not None and self.start > self.end:
+            raise ValueError("Start date cannot be after end date.")  # noqa: TRY003
+        return self

luna_quantum/client/schemas/create/qubo.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class QUBOIn(BaseModel):
+    """
+    Pydantic model for QUBO.
+
+    Attributes
+    ----------
+    name: str
+        Name of the Model
+    matrix: List[List[float]]
+        QUBO matrix
+    """
+
+    name: str
+    matrix: list[list[float]]

luna_quantum/client/schemas/create/solve_job_create.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+from luna_quantum.client.schemas.qpu_token.token_provider import (
+    RestAPITokenProvider,
+)
+
+
+class SolveJobCreate(BaseModel):
+    """
+    Schema for creating a new solve job.
+
+    Attributes
+    ----------
+    model_id : str
+        Unique identifier of the model to be solved.
+
+    solver_name : str
+        Name of the solver algorithm to be used for the computation.
+
+    provider : str
+        Name of the provider that will execute the job.
+
+    parameters : dict[str, Any]
+        Dictionary of solver-specific parameters options.
+
+    qpu_tokens : RestAPITokenProvider | None, optional
+        Authentication tokens for accessing QPU providers.
+        Contains provider-specific authentication credentials.
+
+    name : str | None, optional
+        Optional user-defined name for the solve job.
+    """
+
+    model_id: str  # id of the model
+    solver_name: str
+    provider: str
+    parameters: dict[str, Any]
+    qpu_tokens: RestAPITokenProvider | None = None
+    name: str | None = None

luna_quantum/client/schemas/enums/call_style.py

@@ -0,0 +1,13 @@
+from enum import Enum
+
+
+class CallStyle(str, Enum):
+    """
+    Enumeration of all supported call styles.
+
+    This enumeration is used to prevent FBT001.
+    https://docs.astral.sh/ruff/rules/boolean-type-hint-positional-argument/
+    """
+
+    ACTIVE_WAITING = "active_waiting"
+    SINGLE_FETCH = "single_fetch"

luna_quantum/client/schemas/enums/circuit.py

@@ -0,0 +1,42 @@
+from enum import Enum
+
+
+class CircuitProviderEnum(str, Enum):
+    """
+    Enumeration of supported quantum circuit execution providers.
+
+    Enum Values
+    ----------
+    IBM
+        IBM quantum computing services.
+    QCTRL
+        Q-CTRL quantum computing services.
+    AWS
+        AWS quantum computing services.
+    """
+
+    IBM = "ibm"
+    QCTRL = "qctrl"
+    AWS = "aws"
+
+
+class CircuitStatusEnum(str, Enum):
+    """
+    Enumeration of possible status states for a circuit job.
+
+    Enum Values
+    ----------
+    IN_PROGRESS
+        The circuit job is currently being executed.
+    DONE
+        The circuit job has completed successfully.
+    FAILED
+        The circuit job encountered an error during execution.
+    CANCELED
+        The circuit job was explicitly canceled.
+    """
+
+    IN_PROGRESS = "IN_PROGRESS"
+    DONE = "DONE"
+    FAILED = "FAILED"
+    CANCELLED = "CANCELLED"