commutator-sdk 0.1.0__tar.gz

commutator_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: commutator-sdk
+Version: 0.1.0
+Summary: Commutator Studios Python SDK
+Author-email: Hadi <hadi@commutatorstudios.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.32.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: mypy>=1.9.0; extra == "dev"
+Requires-Dist: rich>=13.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.5.0; extra == "dev"

commutator_sdk-0.1.0/commutator/__init__.py

@@ -0,0 +1,19 @@
+#  Copyright (c) 2026. Commutator Studios GmbH.
+
+from commutator.client import CommutatorClient
+from commutator.exceptions import (
+    APIError,
+    AuthenticationError,
+    CommutatorError,
+    NotFoundError,
+    ValidationError,
+)
+
+__all__ = [
+    "CommutatorClient",
+    "CommutatorError",
+    "APIError",
+    "AuthenticationError",
+    "ValidationError",
+    "NotFoundError",
+]

commutator_sdk-0.1.0/commutator/client.py

@@ -0,0 +1,155 @@
+#  Copyright (c) 2026. Commutator Studios GmbH.
+
+import os
+import typing
+from enum import Enum
+
+import requests
+from commutator.exceptions import raise_for_status
+from commutator.fleet import FleetModule
+from commutator.identity import IdentityModule
+from commutator.jobs import JobsModule
+from commutator.optimizer import OptimizerModule
+
+
+class Environment(str, Enum):
+    """The target environment for the Commutator SDK."""
+
+    PROD = "prod"
+    STAGE = "stage"
+    DEMO = "demo"
+    LOCAL = "local"
+
+
+class CommutatorClient:
+    """The central client for interacting with Commutator Studios Platform."""
+
+    def __init__(
+        self,
+        *,
+        api_key: typing.Optional[str] = None,
+        token: typing.Optional[str] = None,
+        organization_id: typing.Optional[str] = None,
+        _internal_base_url: typing.Optional[str] = None,
+    ):
+        """Initializes the Commutator SDK Client.
+
+        Args:
+            api_key: The user's API Key. If not provided, will look for the
+                     'COMMUTATOR_API_KEY' environment variable.
+            token: A JWT bearer token retrieved via login (if not using API Key).
+            organization_id: The organization ID. If not provided, will look for the
+                             'COMMUTATOR_ORGANIZATION_ID' environment variable.
+        """
+        self._api_key = api_key or os.environ.get("COMMUTATOR_API_KEY")
+        self._token = token
+        self._organization_id = organization_id or os.environ.get("COMMUTATOR_ORGANIZATION_ID")
+
+        if not self._api_key and not self._token:
+            raise ValueError(
+                "Either api_key or token must be provided, or "
+                "COMMUTATOR_API_KEY environment variable must be set."
+            )
+
+        if _internal_base_url:
+            self.base_url = _internal_base_url
+        elif self._api_key:
+            if self._api_key.startswith("cs_loc_"):
+                self.base_url = "http://localhost:3000"
+            elif self._api_key.startswith("cs_stage_"):
+                self.base_url = "https://commutatorstaging.com"
+            elif self._api_key.startswith("cs_demo_"):
+                self.base_url = "https://commutator.tech"
+            else:
+                self.base_url = "https://commutator.app"
+        else:
+            self.base_url = "https://commutator.app"
+
+        # Initialize submodules
+        self.identity = IdentityModule(client=self)
+        self.admin = self.identity  # Alias for documentation consistency
+        self.jobs = JobsModule(client=self)
+        self.fleet = FleetModule(client=self)
+        self.optimizer = OptimizerModule(client=self)
+
+    @classmethod
+    def login_with_api_key(cls, *, api_key: str) -> "CommutatorClient":
+        """Initialize the client using an explicit API key.
+
+        Args:
+            api_key: The user's API Key.
+        """
+        return cls(api_key=api_key)
+
+    @classmethod
+    def login_with_email(
+        cls,
+        *,
+        email: str,
+        password: str,
+        environment: Environment = Environment.PROD,
+    ) -> "CommutatorClient":
+        """Authenticate using email & password to retrieve a JWT token.
+
+        POST /api/v1/identity/login
+        """
+        env_map = {
+            Environment.PROD: "https://commutator.app",
+            Environment.STAGE: "https://commutatorstaging.com",
+            Environment.DEMO: "https://commutator.tech",
+            Environment.LOCAL: "http://localhost:3000",
+        }
+        target_url = env_map.get(environment, "https://commutator.app")
+
+        response = requests.post(
+            f"{target_url}/api/v1/identity/login",
+            json={"email": email, "password": password},
+            timeout=60,
+        )
+        raise_for_status(response)
+
+        auth_response = response.json()
+        data_block = auth_response.get("data", {})
+        token = data_block.get("token")
+
+        if not token:
+            raise ValueError("Authentication did not return a valid token.")
+
+        user_info = data_block.get("user", {})
+        org_id = user_info.get("organizationId") or user_info.get("organization_id")
+
+        return cls(token=token, organization_id=org_id, _internal_base_url=target_url)
+
+    def _request(
+        self,
+        *,
+        method: str,
+        path: str,
+        params: typing.Optional[typing.Dict[str, typing.Any]] = None,
+        json: typing.Optional[typing.Dict[str, typing.Any]] = None,
+        data: typing.Optional[typing.Dict[str, typing.Any]] = None,
+        files: typing.Optional[typing.Dict[str, typing.Any]] = None,
+        headers: typing.Optional[typing.Dict[str, typing.Any]] = None,
+    ) -> requests.Response:
+        """Sends an HTTP request with authenticating headers."""
+        url = f"{self.base_url}{path}"
+
+        request_headers = headers or {}
+        if self._token:
+            request_headers["Authorization"] = f"Bearer {self._token}"
+        elif self._api_key:
+            request_headers["X-API-Key"] = self._api_key
+
+        if self._organization_id:
+            request_headers["X-Organization-Id"] = self._organization_id
+
+        return requests.request(
+            method=method,
+            url=url,
+            params=params,
+            json=json,
+            data=data,
+            files=files,
+            headers=request_headers,
+            timeout=60,
+        )

commutator_sdk-0.1.0/commutator/exceptions.py

@@ -0,0 +1,106 @@
+#  Copyright (c) 2026. Commutator Studios GmbH.
+
+import typing
+
+
+class CommutatorError(Exception):
+    """Base exception for all Commutator SDK errors."""
+
+    def __init__(self, *, message: str):
+        super().__init__(message)
+        self.message = message
+
+
+class APIError(CommutatorError):
+    """Exception raised when the API returns an error status code."""
+
+    def __init__(
+        self,
+        *,
+        status_code: int,
+        code: str,
+        message: str,
+        details: typing.Optional[typing.List[typing.Dict[str, typing.Any]]] = None,
+        request_id: typing.Optional[str] = None,
+        documentation_url: typing.Optional[str] = None,
+    ):
+        super().__init__(message=message)
+        self.status_code = status_code
+        self.code = code
+        self.details = details or []
+        self.request_id = request_id
+        self.documentation_url = documentation_url
+
+    def __str__(self) -> str:
+        err_str = f"[{self.status_code} {self.code}] {self.message}"
+        if self.request_id:
+            err_str += f" (Request ID: {self.request_id})"
+        return err_str
+
+
+class AuthenticationError(APIError):
+    """Raised on authentication failure (e.g. invalid API key or login)."""
+
+
+class ValidationError(APIError):
+    """Raised when the API returns validation issues."""
+
+
+class NotFoundError(APIError):
+    """Raised when a resource (e.g., job) does not exist."""
+
+
+def raise_for_status(response: typing.Any) -> None:
+    """Helper to parse error JSON and raise appropriate APIError."""
+    if response.status_code >= 400:
+        try:
+            err_data = response.json()
+            status_code = err_data.get("status", response.status_code)
+            code = err_data.get("code", "API_ERROR")
+            message = err_data.get("message", response.text)
+            details = err_data.get("details", [])
+            request_id = err_data.get("requestId")
+            documentation_url = err_data.get("documentationUrl")
+        except ValueError:
+            status_code = response.status_code
+            code = "API_ERROR"
+            message = response.text
+            details = []
+            request_id = None
+            documentation_url = None
+
+        if status_code == 401:
+            raise AuthenticationError(
+                status_code=status_code,
+                code=code,
+                message=message,
+                details=details,
+                request_id=request_id,
+                documentation_url=documentation_url,
+            )
+        if status_code == 400:
+            raise ValidationError(
+                status_code=status_code,
+                code=code,
+                message=message,
+                details=details,
+                request_id=request_id,
+                documentation_url=documentation_url,
+            )
+        if status_code == 404:
+            raise NotFoundError(
+                status_code=status_code,
+                code=code,
+                message=message,
+                details=details,
+                request_id=request_id,
+                documentation_url=documentation_url,
+            )
+        raise APIError(
+            status_code=status_code,
+            code=code,
+            message=message,
+            details=details,
+            request_id=request_id,
+            documentation_url=documentation_url,
+        )

commutator_sdk-0.1.0/commutator/fleet.py

@@ -0,0 +1,72 @@
+#  Copyright (c) 2026. Commutator Studios GmbH.
+
+import typing
+
+from commutator.exceptions import raise_for_status
+
+if typing.TYPE_CHECKING:
+    from commutator.client import CommutatorClient
+
+
+class FleetModule:
+    """Module for querying active quantum hardware backends."""
+
+    def __init__(self, *, client: "CommutatorClient"):
+        self._client = client
+
+    def list_backends(self) -> typing.List[typing.Dict[str, typing.Any]]:
+        """Get available quantum backends and fleet status.
+
+        GET /api/v1/fleet
+        """
+        response = self._client._request(method="GET", path="/api/v1/backends")
+        raise_for_status(response)
+        return typing.cast(
+            typing.List[typing.Dict[str, typing.Any]], response.json().get("data", [])
+        )
+
+    def update_backend(self, *, backend_id: str, enabled: bool) -> typing.Dict[str, typing.Any]:
+        """Update fleet configurations or backend preferences.
+
+        PATCH /api/v1/fleet
+        """
+        payload = {"id": backend_id, "enabled": enabled}
+        response = self._client._request(method="PATCH", path="/api/v1/backends", json=payload)
+        raise_for_status(response)
+        return typing.cast(typing.Dict[str, typing.Any], response.json().get("data", {}))
+
+    def discover(self) -> typing.List[typing.Dict[str, typing.Any]]:
+        """Discover detailed topology and calibration data.
+
+        POST /api/v1/backends/discovery
+        """
+        response = self._client._request(method="POST", path="/api/v1/backends/discovery")
+        raise_for_status(response)
+        # Fetch and return the newly synchronized detailed list
+        return self.list_backends()
+
+    def activate(self, *, backend_id: str) -> bool:
+        """Request exclusive access or activation of a specific reserved backend.
+
+        PATCH /api/v1/backend/[id]/activate
+        """
+        response = self._client._request(
+            method="PATCH", path=f"/api/v1/backend/{backend_id}/activate", json={"isActive": True}
+        )
+        if response.status_code in (200, 204):
+            return True
+        raise_for_status(response)
+        return False
+
+    def deactivate(self, *, backend_id: str) -> bool:
+        """Deactivate a specific reserved backend.
+
+        PATCH /api/v1/backend/[id]/activate
+        """
+        response = self._client._request(
+            method="PATCH", path=f"/api/v1/backend/{backend_id}/activate", json={"isActive": False}
+        )
+        if response.status_code in (200, 204):
+            return True
+        raise_for_status(response)
+        return False

commutator_sdk-0.1.0/commutator/identity.py

@@ -0,0 +1,91 @@
+#  Copyright (c) 2026. Commutator Studios GmbH.
+
+import typing
+
+from commutator.exceptions import raise_for_status
+
+if typing.TYPE_CHECKING:
+    from commutator.client import CommutatorClient
+
+
+class IdentityModule:
+    """Module for identity and authentication-related APIs."""
+
+    def __init__(self, *, client: "CommutatorClient"):
+        self._client = client
+
+    def list_api_keys(self) -> typing.List[typing.Dict[str, typing.Any]]:
+        """Retrieve a list of the user's API keys.
+
+        GET /api/v1/identity/keys
+        """
+        response = self._client._request(method="GET", path="/api/v1/identity/keys")
+        raise_for_status(response)
+        return typing.cast(
+            typing.List[typing.Dict[str, typing.Any]], response.json().get("data", [])
+        )
+
+    def create_api_key(
+        self, *, name: str, expires_in_days: int = 30
+    ) -> typing.Dict[str, typing.Any]:
+        """Generate a new API key.
+
+        POST /api/v1/identity/keys
+        """
+        payload = {"name": name, "expiresInDays": expires_in_days}
+        response = self._client._request(method="POST", path="/api/v1/identity/keys", json=payload)
+        raise_for_status(response)
+        return typing.cast(typing.Dict[str, typing.Any], response.json().get("data", {}))
+
+    def revoke_api_key(self, *, key_id: str) -> bool:
+        """Revoke an active API key immediately.
+
+        DELETE /api/v1/identity/keys/[id]
+        """
+        response = self._client._request(method="DELETE", path=f"/api/v1/identity/keys/{key_id}")
+        if response.status_code in (200, 204):
+            return True
+        raise_for_status(response)
+        return False
+
+    def get_team(self) -> typing.List[typing.Dict[str, typing.Any]]:
+        """Get details about the user's team.
+
+        GET /api/v1/identity/team
+        """
+        response = self._client._request(method="GET", path="/api/v1/identity/team")
+        raise_for_status(response)
+        return typing.cast(
+            typing.List[typing.Dict[str, typing.Any]], response.json().get("data", [])
+        )
+
+    def get_audit_logs(self, *, limit: int = 50) -> typing.List[typing.Dict[str, typing.Any]]:
+        """Retrieve recent security and access audit logs for the team.
+
+        GET /api/v1/audit/logs
+        """
+        response = self._client._request(
+            method="GET", path="/api/v1/audit/logs", params={"limit": limit}
+        )
+        raise_for_status(response)
+        return typing.cast(
+            typing.List[typing.Dict[str, typing.Any]], response.json().get("data", [])
+        )
+
+    def add_ibm_key(
+        self, *, api_key: str, name: str = "IBM API Key"
+    ) -> typing.Union[typing.Dict[str, typing.Any], str]:
+        """Set your IBM API key for quantum simulations.
+
+        POST /api/v1/identity/credentials
+        """
+        payload = {"provider": "IBM", "name": name, "config": {"apiToken": api_key, "crns": []}}
+        response = self._client._request(
+            method="POST", path="/api/v1/identity/credentials", json=payload
+        )
+
+        if response.status_code == 409:
+            return "this key is already set"
+
+        raise_for_status(response)
+        return typing.cast(typing.Dict[str, typing.Any], response.json().get("data", {}))

commutator_sdk-0.1.0/commutator/jobs.py

@@ -0,0 +1,159 @@
+#  Copyright (c) 2026. Commutator Studios GmbH.
+
+import typing
+
+from commutator.exceptions import raise_for_status
+
+if typing.TYPE_CHECKING:
+    from commutator.client import CommutatorClient
+
+
+class JobsModule:
+    """Module for job-related APIs."""
+
+    def __init__(self, *, client: "CommutatorClient"):
+        self._client = client
+
+    def list(self) -> typing.List[typing.Dict[str, typing.Any]]:
+        """List job history.
+
+        GET /api/v1/jobs
+        """
+        response = self._client._request(method="GET", path="/api/v1/jobs")
+        raise_for_status(response)
+        return typing.cast(
+            typing.List[typing.Dict[str, typing.Any]], response.json().get("data", [])
+        )
+
+    def create(
+        self,
+        *,
+        name: str,
+        algorithm: str,
+        file_path: str,
+        organization_id: typing.Optional[str] = None,
+    ) -> typing.Dict[str, typing.Any]:
+        """Submit a new quantum job via file configuration.
+
+        POST /api/v1/job
+        """
+        data = {
+            "name": name,
+            "algorithm": algorithm,
+        }
+        if organization_id:
+            data["organization_id"] = organization_id
+        with open(file_path, "rb") as f:
+            files = {"file": (file_path, f, "application/json")}
+            response = self._client._request(
+                method="POST", path="/api/v1/job", data=data, files=files
+            )
+        raise_for_status(response)
+        return typing.cast(typing.Dict[str, typing.Any], response.json().get("data", {}))
+
+    def get(self, *, job_id: str) -> typing.Dict[str, typing.Any]:
+        """Get details for a specific job by its ID.
+
+        GET /api/v1/job/[id]
+        """
+        response = self._client._request(method="GET", path=f"/api/v1/job/{job_id}")
+        raise_for_status(response)
+        return typing.cast(typing.Dict[str, typing.Any], response.json().get("data", {}))
+
+    def update(self, *, job_id: str, **kwargs: typing.Any) -> typing.Dict[str, typing.Any]:
+        """Updates the job details.
+
+        PATCH /api/v1/jobs/[id]
+        """
+        payload = {}
+        for k, v in kwargs.items():
+            camel_k = "".join(x.capitalize() or "_" for x in k.split("_"))
+            camel_k = camel_k[0].lower() + camel_k[1:]
+            payload[camel_k] = v
+
+        response = self._client._request(method="PATCH", path=f"/api/v1/job/{job_id}", json=payload)
+        raise_for_status(response)
+        return typing.cast(typing.Dict[str, typing.Any], response.json().get("data", {}))
+
+    def list_algorithms(self) -> typing.List[typing.Dict[str, typing.Any]]:
+        """Retrieve the list of supported quantum algorithms available for execution.
+
+        GET /api/v1/job/algorithms
+        """
+        response = self._client._request(method="GET", path="/api/v1/job/algorithms")
+        raise_for_status(response)
+        return typing.cast(
+            typing.List[typing.Dict[str, typing.Any]], response.json().get("data", [])
+        )
+
+    def execute(
+        self,
+        *,
+        job_id: str,
+        backend: str,
+        optimization_level: int = 3,
+        dynamic_decoupling: bool = False,
+        max_iterations: typing.Optional[int] = None,
+        convergence: typing.Optional[float] = None,
+        predicted_shots: typing.Optional[int] = None,
+        **kwargs: typing.Any,
+    ) -> typing.Dict[str, typing.Any]:
+        """Executes a previously created quantum job on target hardware.
+
+        PATCH /api/v1/job/[id]
+        """
+        payload: typing.Dict[str, typing.Any] = {
+            "status": "Pending",
+            "hardware": backend,
+            "optimizationLevel": optimization_level,
+            "dynamicDecoupling": dynamic_decoupling,
+        }
+        if max_iterations is not None:
+            payload["maxIterations"] = max_iterations
+        if convergence is not None:
+            payload["convergence"] = convergence
+        if predicted_shots is not None:
+            payload["predictedShots"] = predicted_shots
+
+        for k, v in kwargs.items():
+            camel_k = "".join(x.capitalize() or "_" for x in k.split("_"))
+            camel_k = camel_k[0].lower() + camel_k[1:]
+            if camel_k not in payload:
+                payload[camel_k] = v
+
+        response = self._client._request(method="PATCH", path=f"/api/v1/job/{job_id}", json=payload)
+        raise_for_status(response)
+        return typing.cast(typing.Dict[str, typing.Any], response.json().get("data", {}))
+
+    def cancel(self, *, job_id: str) -> bool:
+        """Attempt to cancel a pending or queued job.
+
+        DELETE /api/v1/job/[id]
+        """
+        response = self._client._request(method="DELETE", path=f"/api/v1/job/{job_id}")
+        if response.status_code in (200, 204):
+            return True
+        raise_for_status(response)
+        return False
+
+    def get_download_url(self, *, job_id: str) -> str:
+        """Retrieves a presigned URL to download the job results.
+
+        GET /api/v1/jobs/download-url?jobId=[id]
+        """
+        response = self._client._request(
+            method="GET", path="/api/v1/jobs/download-url", params={"jobId": job_id}
+        )
+        raise_for_status(response)
+        return typing.cast(str, response.json().get("url", ""))
+
+    def download_results(self, *, job_id: str) -> typing.Dict[str, typing.Any]:
+        """Downloads the job results data.
+
+        GET /api/v1/jobs/download-data?jobId=[id]
+        """
+        response = self._client._request(
+            method="GET", path="/api/v1/jobs/download-data", params={"jobId": job_id}
+        )
+        raise_for_status(response)
+        return typing.cast(typing.Dict[str, typing.Any], response.json())

commutator_sdk-0.1.0/commutator/optimizer.py

@@ -0,0 +1,66 @@
+#  Copyright (c) 2026. Commutator Studios GmbH.
+
+import typing
+
+from commutator.exceptions import raise_for_status
+
+if typing.TYPE_CHECKING:
+    from commutator.client import CommutatorClient
+
+
+class OptimizerModule:
+    """Module for mathematical optimization and hardware recommendation engines."""
+
+    def __init__(self, *, client: "CommutatorClient"):
+        self._client = client
+
+    def get_metadata(self) -> typing.List[typing.Dict[str, typing.Any]]:
+        """Get current optimizer algorithm metadata.
+
+        GET /api/v1/optimizer
+        """
+        response = self._client._request(method="GET", path="/api/v1/optimizer")
+        raise_for_status(response)
+        return typing.cast(
+            typing.List[typing.Dict[str, typing.Any]], response.json().get("data", [])
+        )
+
+    def run(
+        self, *, algorithm: str, qubits: int, circuit_depth: int, **kwargs: typing.Any
+    ) -> typing.Dict[str, typing.Any]:
+        """Configure or create a new optimizer run.
+
+        POST /api/v1/optimizer
+        """
+        payload = {"algorithm": algorithm, "qubits": qubits, "circuit_depth": circuit_depth}
+        payload.update(kwargs)
+        response = self._client._request(method="POST", path="/api/v1/optimizer", json=payload)
+        raise_for_status(response)
+        return typing.cast(typing.Dict[str, typing.Any], response.json().get("data", {}))
+
+    def recommend(
+        self,
+        *,
+        execution_id: str,
+        target_backend: typing.Optional[str] = None,
+        target_dd: bool = True,
+        plan_only: bool = True,
+    ) -> typing.List[typing.Dict[str, typing.Any]]:
+        """Request optimization and hardware recommendations.
+
+        POST /api/v1/optimizer/recommendations
+        """
+        payload = {
+            "executionId": execution_id,
+            "targetBackend": target_backend,
+            "targetDD": target_dd,
+            "planOnly": plan_only,
+        }
+        response = self._client._request(
+            method="POST", path="/api/v1/optimizer/recommendations", json=payload
+        )
+        raise_for_status(response)
+        return typing.cast(
+            typing.List[typing.Dict[str, typing.Any]],
+            response.json().get("data", {}).get("recommendations", []),
+        )

commutator_sdk-0.1.0/commutator_sdk.egg-info/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: commutator-sdk
+Version: 0.1.0
+Summary: Commutator Studios Python SDK
+Author-email: Hadi <hadi@commutatorstudios.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.32.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: mypy>=1.9.0; extra == "dev"
+Requires-Dist: rich>=13.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.5.0; extra == "dev"

commutator_sdk-0.1.0/commutator_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+pyproject.toml
+commutator/__init__.py
+commutator/client.py
+commutator/exceptions.py
+commutator/fleet.py
+commutator/identity.py
+commutator/jobs.py
+commutator/optimizer.py
+commutator_sdk.egg-info/PKG-INFO
+commutator_sdk.egg-info/SOURCES.txt
+commutator_sdk.egg-info/dependency_links.txt
+commutator_sdk.egg-info/requires.txt
+commutator_sdk.egg-info/top_level.txt
+tests/test_client.py
+tests/test_exceptions.py
+tests/test_fleet.py
+tests/test_identity.py
+tests/test_jobs.py
+tests/test_optimizer.py

commutator_sdk-0.1.0/commutator_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

commutator_sdk-0.1.0/commutator_sdk.egg-info/requires.txt

@@ -0,0 +1,10 @@
+requests>=2.32.0
+
+[dev]
+pytest>=8.0.0
+pytest-cov>=4.0.0
+responses>=0.23.0
+black>=24.0.0
+mypy>=1.9.0
+rich>=13.0.0
+pre-commit>=3.5.0

commutator_sdk-0.1.0/commutator_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+commutator

commutator_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "commutator-sdk"
+version = "0.1.0"
+description = "Commutator Studios Python SDK"
+readme = "README.md"
+authors = [
+    {name = "Hadi", email = "hadi@commutatorstudios.com"}
+]
+dependencies = [
+    "requests>=2.32.0",
+]
+requires-python = ">=3.11"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.0.0",
+    "responses>=0.23.0",
+    "black>=24.0.0",
+    "mypy>=1.9.0",
+    "rich>=13.0.0",
+    "pre-commit>=3.5.0",
+]
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.black]
+line-length = 100
+target-version = ['py311']
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]

commutator_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

commutator_sdk-0.1.0/tests/test_client.py

@@ -0,0 +1,98 @@
+#  Copyright (c) 2026. Commutator Studios GmbH.
+
+import pytest
+import responses
+from commutator.client import CommutatorClient, Environment
+from commutator.exceptions import AuthenticationError
+
+
+def test_client_init_prefixes():
+    client_prod = CommutatorClient(api_key="cs_prod_123")
+    assert client_prod.base_url == "https://commutator.app"
+
+    client_stage = CommutatorClient(api_key="cs_stage_123")
+    assert client_stage.base_url == "https://commutatorstaging.com"
+
+    client_demo = CommutatorClient(api_key="cs_demo_123")
+    assert client_demo.base_url == "https://commutator.tech"
+
+    client_loc = CommutatorClient(api_key="cs_loc_123")
+    assert client_loc.base_url == "http://localhost:3000"
+
+    client_legacy = CommutatorClient(api_key="legacy_key_123")
+    assert client_legacy.base_url == "https://commutator.app"
+
+
+def test_client_missing_creds():
+    with pytest.raises(ValueError):
+        CommutatorClient()
+
+
+def test_client_env_vars(monkeypatch):
+    monkeypatch.setenv("COMMUTATOR_API_KEY", "cs_loc_123")
+    monkeypatch.setenv("COMMUTATOR_ORGANIZATION_ID", "org_123")
+
+    client = CommutatorClient()
+    assert client._api_key == "cs_loc_123"
+    assert client._organization_id == "org_123"
+
+
+def test_login_api_key_cls():
+    client = CommutatorClient.login_with_api_key(api_key="cs_loc_123")
+    assert client._api_key == "cs_loc_123"
+
+
+@responses.activate
+def test_client_login_success_prod():
+    responses.add(
+        responses.POST,
+        "https://commutator.app/api/v1/identity/login",
+        json={"data": {"token": "mocked_jwt_token", "user": {"organizationId": "123"}}},
+        status=200,
+    )
+
+    client = CommutatorClient.login_with_email(email="test@example.com", password="password123")
+    assert client._token == "mocked_jwt_token"
+    assert client.base_url == "https://commutator.app"
+    assert client._organization_id == "123"
+
+
+@responses.activate
+def test_client_login_success_local():
+    responses.add(
+        responses.POST,
+        "http://localhost:3000/api/v1/identity/login",
+        json={"data": {"token": "mocked_local_token", "user": {"id": "123"}}},
+        status=200,
+    )
+
+    client = CommutatorClient.login_with_email(
+        email="test@example.com", password="password123", environment=Environment.LOCAL
+    )
+    assert client._token == "mocked_local_token"
+    assert client.base_url == "http://localhost:3000"
+
+
+@responses.activate
+def test_client_login_no_token():
+    responses.add(
+        responses.POST,
+        "https://commutator.app/api/v1/identity/login",
+        json={"data": {}},
+        status=200,
+    )
+    with pytest.raises(ValueError):
+        CommutatorClient.login_with_email(email="test@example.com", password="password123")
+
+
+@responses.activate
+def test_client_login_failure():
+    responses.add(
+        responses.POST,
+        "https://commutator.app/api/v1/identity/login",
+        json={"detail": "Invalid credentials"},
+        status=401,
+    )
+
+    with pytest.raises(AuthenticationError):
+        CommutatorClient.login_with_email(email="test@example.com", password="wrongpassword")

commutator_sdk-0.1.0/tests/test_exceptions.py

@@ -0,0 +1,67 @@
+#  Copyright (c) 2026. Commutator Studios GmbH.
+
+import pytest
+import requests
+from commutator.exceptions import (
+    APIError,
+    AuthenticationError,
+    CommutatorError,
+    NotFoundError,
+    ValidationError,
+    raise_for_status,
+)
+
+
+def test_commutator_error():
+    err = CommutatorError(message="test")
+    assert str(err) == "test"
+
+
+def test_api_error_str():
+    err = APIError(status_code=500, code="ERR", message="Oops", request_id="req123")
+    assert str(err) == "[500 ERR] Oops (Request ID: req123)"
+
+
+def test_raise_for_status_auth():
+    resp = requests.Response()
+    resp.status_code = 401
+    resp._content = b'{"status": 401, "code": "AUTH", "message": "unauth"}'
+
+    with pytest.raises(AuthenticationError):
+        raise_for_status(resp)
+
+
+def test_raise_for_status_valid():
+    resp = requests.Response()
+    resp.status_code = 400
+    resp._content = b'{"status": 400, "code": "VAL", "message": "bad"}'
+
+    with pytest.raises(ValidationError):
+        raise_for_status(resp)
+
+
+def test_raise_for_status_not_found():
+    resp = requests.Response()
+    resp.status_code = 404
+    resp._content = b'{"status": 404, "code": "NOT_FOUND", "message": "missing"}'
+
+    with pytest.raises(NotFoundError):
+        raise_for_status(resp)
+
+
+def test_raise_for_status_api():
+    resp = requests.Response()
+    resp.status_code = 500
+    resp._content = b'{"status": 500, "code": "API", "message": "server err"}'
+
+    with pytest.raises(APIError):
+        raise_for_status(resp)
+
+
+def test_raise_for_status_bad_json():
+    resp = requests.Response()
+    resp.status_code = 500
+    resp._content = b"not json"
+
+    with pytest.raises(APIError):
+        raise_for_status(resp)

commutator_sdk-0.1.0/tests/test_fleet.py

@@ -0,0 +1,74 @@
+#  Copyright (c) 2026. Commutator Studios GmbH.
+
+import responses
+
+
+@responses.activate
+def test_fleet_list_backends(mock_client):
+    responses.add(
+        responses.GET,
+        "https://commutatorstaging.com/api/v1/backends",
+        json={"data": [{"name": "ibm_kyiv", "status": "online"}]},
+        status=200,
+    )
+
+    backends = mock_client.fleet.list_backends()
+    assert backends is not None
+
+
+@responses.activate
+def test_fleet_update_backend(mock_client):
+    responses.add(
+        responses.PATCH,
+        "https://commutatorstaging.com/api/v1/backends",
+        json={"data": {"id": "backend_1", "enabled": False}},
+        status=200,
+    )
+
+    result = mock_client.fleet.update_backend(backend_id="backend_1", enabled=False)
+    assert result["enabled"] is False
+
+
+@responses.activate
+def test_fleet_discover(mock_client):
+    responses.add(
+        responses.POST,
+        "https://commutatorstaging.com/api/v1/backends/discovery",
+        status=204,
+        body="",
+    )
+    responses.add(
+        responses.GET,
+        "https://commutatorstaging.com/api/v1/backends",
+        json={"data": [{"name": "ibm_kyiv", "status": "online"}]},
+        status=200,
+    )
+
+    result = mock_client.fleet.discover()
+    assert len(result) == 1
+
+
+@responses.activate
+def test_fleet_activate(mock_client):
+    responses.add(
+        responses.PATCH,
+        "https://commutatorstaging.com/api/v1/backend/backend_1/activate",
+        status=204,
+        body="",
+    )
+
+    result = mock_client.fleet.activate(backend_id="backend_1")
+    assert result is True
+
+
+@responses.activate
+def test_fleet_deactivate(mock_client):
+    responses.add(
+        responses.PATCH,
+        "https://commutatorstaging.com/api/v1/backend/backend_1/activate",
+        status=204,
+        body="",
+    )
+
+    result = mock_client.fleet.deactivate(backend_id="backend_1")
+    assert result is True

commutator_sdk-0.1.0/tests/test_identity.py

@@ -0,0 +1,95 @@
+#  Copyright (c) 2026. Commutator Studios GmbH.
+
+import responses
+
+
+@responses.activate
+def test_identity_get_keys(mock_client):
+    responses.add(
+        responses.GET,
+        "https://commutatorstaging.com/api/v1/identity/keys",
+        json={"data": []},
+        status=200,
+    )
+
+    profile = mock_client.identity.list_api_keys()
+    assert profile is not None
+
+
+@responses.activate
+def test_identity_create_api_key(mock_client):
+    responses.add(
+        responses.POST,
+        "https://commutatorstaging.com/api/v1/identity/keys",
+        json={"data": {"id": "key_123"}},
+        status=200,
+    )
+
+    result = mock_client.identity.create_api_key(name="Test Key")
+    assert result["id"] == "key_123"
+
+
+@responses.activate
+def test_identity_revoke_api_key(mock_client):
+    responses.add(
+        responses.DELETE,
+        "https://commutatorstaging.com/api/v1/identity/keys/key_123",
+        status=204,
+        body="",
+    )
+
+    result = mock_client.identity.revoke_api_key(key_id="key_123")
+    assert result is True
+
+
+@responses.activate
+def test_identity_get_team(mock_client):
+    responses.add(
+        responses.GET,
+        "https://commutatorstaging.com/api/v1/identity/team",
+        json={"data": [{"id": "team_1"}]},
+        status=200,
+    )
+
+    team = mock_client.identity.get_team()
+    assert len(team) == 1
+
+
+@responses.activate
+def test_identity_get_audit_logs(mock_client):
+    responses.add(
+        responses.GET,
+        "https://commutatorstaging.com/api/v1/audit/logs?limit=50",
+        json={"data": [{"action": "login"}]},
+        status=200,
+        match=[responses.matchers.query_param_matcher({"limit": "50"})],
+    )
+
+    logs = mock_client.identity.get_audit_logs()
+    assert len(logs) == 1
+
+
+@responses.activate
+def test_identity_add_ibm_key(mock_client):
+    responses.add(
+        responses.POST,
+        "https://commutatorstaging.com/api/v1/identity/credentials",
+        json={"data": {"id": "cred_123"}},
+        status=200,
+    )
+
+    result = mock_client.identity.add_ibm_key(api_key="ibm_123")
+    assert isinstance(result, dict)
+    assert result["id"] == "cred_123"
+
+
+@responses.activate
+def test_identity_add_ibm_key_conf(mock_client):
+    responses.add(
+        responses.POST,
+        "https://commutatorstaging.com/api/v1/identity/credentials",
+        status=409,
+    )
+
+    result = mock_client.identity.add_ibm_key(api_key="ibm_123")
+    assert result == "this key is already set"

commutator_sdk-0.1.0/tests/test_jobs.py

@@ -0,0 +1,125 @@
+#  Copyright (c) 2026. Commutator Studios GmbH.
+
+
+import responses
+
+
+@responses.activate
+def test_jobs_list(mock_client):
+    responses.add(
+        responses.GET,
+        "https://commutatorstaging.com/api/v1/jobs",
+        json={"data": [{"id": "job_1", "status": "COMPLETED"}]},
+        status=200,
+    )
+    jobs = mock_client.jobs.list()
+    assert len(jobs) == 1
+
+
+@responses.activate
+def test_jobs_create(mock_client, tmp_path):
+    responses.add(
+        responses.POST,
+        "https://commutatorstaging.com/api/v1/job",
+        json={"data": {"id": "job_1"}},
+        status=200,
+    )
+
+    file_path = tmp_path / "test.json"
+    file_path.write_text("{}")
+
+    job = mock_client.jobs.create(
+        name="test", algorithm="QAOA", file_path=str(file_path), organization_id="org_1"
+    )
+    assert job["id"] == "job_1"
+
+
+@responses.activate
+def test_jobs_get(mock_client):
+    responses.add(
+        responses.GET,
+        "https://commutatorstaging.com/api/v1/job/job_1",
+        json={"data": {"id": "job_1"}},
+        status=200,
+    )
+    job = mock_client.jobs.get(job_id="job_1")
+    assert job["id"] == "job_1"
+
+
+@responses.activate
+def test_jobs_update(mock_client):
+    responses.add(
+        responses.PATCH,
+        "https://commutatorstaging.com/api/v1/job/job_1",
+        json={"data": {"id": "job_1", "name": "updated"}},
+        status=200,
+    )
+    job = mock_client.jobs.update(job_id="job_1", name="updated", test_key="val")
+    assert job["name"] == "updated"
+
+
+@responses.activate
+def test_jobs_list_algorithms(mock_client):
+    responses.add(
+        responses.GET,
+        "https://commutatorstaging.com/api/v1/job/algorithms",
+        json={"data": [{"name": "QAOA"}]},
+        status=200,
+    )
+    algs = mock_client.jobs.list_algorithms()
+    assert len(algs) == 1
+
+
+@responses.activate
+def test_jobs_execute(mock_client):
+    responses.add(
+        responses.PATCH,
+        "https://commutatorstaging.com/api/v1/job/job_1",
+        json={"data": {"id": "job_1", "status": "Pending"}},
+        status=200,
+    )
+
+    job = mock_client.jobs.execute(
+        job_id="job_1",
+        backend="ibm_kyiv",
+        dynamic_decoupling=True,
+        optimization_level=3,
+        extra_arg=True,
+    )
+    assert job["id"] == "job_1"
+    assert job["status"] == "Pending"
+
+
+@responses.activate
+def test_jobs_cancel_success(mock_client):
+    responses.add(
+        responses.DELETE,
+        "https://commutatorstaging.com/api/v1/job/job_1",
+        status=200,
+    )
+    result = mock_client.jobs.cancel(job_id="job_1")
+    assert result is True
+
+
+@responses.activate
+def test_jobs_get_download_url(mock_client):
+    responses.add(
+        responses.GET,
+        "https://commutatorstaging.com/api/v1/jobs/download-url?jobId=job_1",
+        json={"url": "https://example.com/download"},
+        status=200,
+    )
+    url = mock_client.jobs.get_download_url(job_id="job_1")
+    assert url == "https://example.com/download"
+
+
+@responses.activate
+def test_jobs_download_results(mock_client):
+    responses.add(
+        responses.GET,
+        "https://commutatorstaging.com/api/v1/jobs/download-data?jobId=job_1",
+        json={"result": "data"},
+        status=200,
+    )
+    data = mock_client.jobs.download_results(job_id="job_1")
+    assert data["result"] == "data"

commutator_sdk-0.1.0/tests/test_optimizer.py

@@ -0,0 +1,43 @@
+#  Copyright (c) 2026. Commutator Studios GmbH.
+
+import responses
+
+
+@responses.activate
+def test_optimizer_get_metadata(mock_client):
+    responses.add(
+        responses.GET,
+        "https://commutatorstaging.com/api/v1/optimizer",
+        json={"data": [{"name": "QAOA"}]},
+        status=200,
+    )
+
+    metadata = mock_client.optimizer.get_metadata()
+    assert len(metadata) == 1
+
+
+@responses.activate
+def test_optimizer_run(mock_client):
+    responses.add(
+        responses.POST,
+        "https://commutatorstaging.com/api/v1/optimizer",
+        json={"data": {"id": "opt_run_1"}},
+        status=200,
+    )
+
+    result = mock_client.optimizer.run(algorithm="QAOA", qubits=4, circuit_depth=10)
+    assert result["id"] == "opt_run_1"
+
+
+@responses.activate
+def test_optimizer_recommend(mock_client):
+    responses.add(
+        responses.POST,
+        "https://commutatorstaging.com/api/v1/optimizer/recommendations",
+        json={"data": {"recommendations": [{"backend": "ibm_kyiv"}]}},
+        status=200,
+    )
+
+    config = mock_client.optimizer.recommend(execution_id="circ_1")
+    assert len(config) == 1
+    assert config[0]["backend"] == "ibm_kyiv"