nqct 0.2.0__py3-none-any.whl

nqct/__init__.py

@@ -0,0 +1,42 @@
+"""NQCT Cloud Python client."""
+
+from nqct._version import __version__
+from nqct.client import NQCTClient
+from nqct.exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    ConflictError,
+    JobFailedError,
+    JobNotCompleteError,
+    JobTimeoutError,
+    NotFoundError,
+    NQCTError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from nqct.models import Backend, Function, Job
+
+Client = NQCTClient
+Runtime = NQCTClient
+
+__all__ = [
+    "NQCTClient",
+    "Client",
+    "Runtime",
+    "Backend",
+    "Function",
+    "Job",
+    "NQCTError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "NotFoundError",
+    "ValidationError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+    "JobFailedError",
+    "JobNotCompleteError",
+    "JobTimeoutError",
+    "__version__",
+]

nqct/_version.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "0.2.0"

nqct/auth/__init__.py

@@ -0,0 +1,21 @@
+"""Credential helpers."""
+
+from nqct.auth.credentials import (
+    CREDENTIALS_DIR,
+    CREDENTIALS_FILE,
+    DEFAULT_PROFILE,
+    credentials_path,
+    delete_profile,
+    load_profile,
+    save_profile,
+)
+
+__all__ = [
+    "CREDENTIALS_DIR",
+    "CREDENTIALS_FILE",
+    "DEFAULT_PROFILE",
+    "credentials_path",
+    "delete_profile",
+    "load_profile",
+    "save_profile",
+]

nqct/auth/credentials.py

@@ -0,0 +1,83 @@
+"""Load and save ~/.nqct/credentials.json profiles."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+CREDENTIALS_DIR = Path.home() / ".nqct"
+CREDENTIALS_FILE = CREDENTIALS_DIR / "credentials.json"
+DEFAULT_PROFILE = "default"
+
+
+def credentials_path() -> Path:
+    return CREDENTIALS_FILE
+
+
+def load_profile(name: str = DEFAULT_PROFILE) -> dict[str, str]:
+    """Return a named credentials profile or raise ``FileNotFoundError``."""
+    path = credentials_path()
+    if path.is_file() and path.stat().st_mode & 0o077:
+        import warnings
+
+        warnings.warn(f"Credentials file {path} is world/group accessible", stacklevel=2)
+    if not path.is_file():
+        raise FileNotFoundError(
+            f"No credentials file at {path}. Call NQCTClient.save_account() or set NQCT_API_KEY."
+        )
+    data: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
+    if name not in data:
+        raise KeyError(f"Profile {name!r} not found in {path}")
+    profile = data[name]
+    if not isinstance(profile, dict):
+        raise ValueError(f"Profile {name!r} is not an object")
+    return {str(k): str(v) for k, v in profile.items()}
+
+
+def save_profile(
+    *,
+    url: str,
+    api_key: str | None = None,
+    token: str | None = None,
+    refresh_token: str | None = None,
+    name: str = DEFAULT_PROFILE,
+) -> Path:
+    """Persist a credentials profile with file mode ``0600``."""
+    CREDENTIALS_DIR.mkdir(parents=True, exist_ok=True)
+    path = credentials_path()
+
+    existing: dict[str, Any] = {}
+    if path.is_file():
+        existing = json.loads(path.read_text(encoding="utf-8"))
+
+    profile: dict[str, str] = {"url": url.rstrip("/")}
+    if api_key is not None:
+        profile["api_key"] = api_key
+    if token is not None:
+        profile["token"] = token
+    if refresh_token is not None:
+        profile["refresh_token"] = refresh_token
+
+    existing[name] = profile
+    path.write_text(json.dumps(existing, indent=2) + "\n", encoding="utf-8")
+    os.chmod(path, 0o600)
+    if path.stat().st_mode & 0o077:
+        import warnings
+
+        warnings.warn(f"Credentials file {path} is world/group accessible", stacklevel=2)
+    return path
+
+
+def delete_profile(name: str = DEFAULT_PROFILE) -> None:
+    path = credentials_path()
+    if not path.is_file():
+        return
+    data: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
+    data.pop(name, None)
+    if data:
+        path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+        os.chmod(path, 0o600)
+    else:
+        path.unlink(missing_ok=True)

nqct/client.py

@@ -0,0 +1,296 @@
+"""NQCT Cloud client entry point."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+from uuid import UUID
+
+from nqct.auth.credentials import DEFAULT_PROFILE, delete_profile, load_profile, save_profile
+from nqct.exceptions import AuthenticationError
+from nqct.httpss.session import HTTPSession
+from nqct.models.backend import Backend
+from nqct.models.function import Function
+from nqct.models.job import Job
+from nqct.resources.backends import BackendsManager
+from nqct.resources.functions import FunctionsManager
+from nqct.resources.jobs import JobsManager, JobSubmitSource, QubitMapping
+
+_ENV_URL = "NQCT_URL"
+_ENV_API_KEY = "NQCT_API_KEY"
+_ENV_TOKEN = "NQCT_TOKEN"
+_ENV_REFRESH_TOKEN = "NQCT_REFRESH_TOKEN"
+_ENV_ACCOUNT_NAME = "NQCT_ACCOUNT_NAME"
+_ENV_VERIFY_SSL = "NQCT_VERIFY_SSL"
+
+DEFAULT_API_URL = "https://api.nqct.org/api/v1"
+
+
+class NQCTClient:
+    """Client for the NQCT Cloud REST API.
+
+    Maps to platform routes under ``/api/v1``. See the product spec in the
+    sibling ``nqct-cloud`` repo: ``references/specs/14-python-sdk.md``.
+
+    Args:
+        url: API base URL including ``/api/v1``. Defaults to production
+            (``https://api.nqct.org/api/v1``). Override for local ``nqct start``
+            (``http://localhost:8000/api/v1``) or via ``NQCT_URL``.
+        api_key: ``X-API-Key`` value (``nqct_`` prefix). Preferred for automation.
+        token: JWT access token (optional; notebook use).
+        refresh_token: JWT refresh token (optional).
+        account_name: Named profile in ``~/.nqct/credentials.json``.
+        verify_ssl: Verify TLS certificates (default ``True``).
+            Set env ``NQCT_VERIFY_SSL=false`` to disable.
+    """
+
+    def __init__(
+        self,
+        *,
+        url: str | None = None,
+        api_key: str | None = None,
+        token: str | None = None,
+        refresh_token: str | None = None,
+        account_name: str | None = None,
+        verify_ssl: bool | None = None,
+    ) -> None:
+        self._refresh_token = refresh_token
+        resolved = _resolve_credentials(
+            url=url,
+            api_key=api_key,
+            token=token,
+            refresh_token=refresh_token,
+            account_name=account_name,
+        )
+        self.url = resolved["url"]
+        self.api_key = resolved.get("api_key")
+        self.token = resolved.get("token")
+        self._refresh_token = resolved.get("refresh_token") or self._refresh_token
+        if not self.api_key and not self.token:
+            raise AuthenticationError(
+                "No credentials provided. Set NQCT_API_KEY, pass api_key=, or call save_account()."
+            )
+        verify = verify_ssl if verify_ssl is not None else _env_verify_ssl()
+        self._http = HTTPSession(
+            self.url,
+            api_key=self.api_key,
+            token=self.token,
+            verify_ssl=verify,
+        )
+        self._backends = BackendsManager(self._http)
+        self._jobs = JobsManager(self._http)
+        self._functions = FunctionsManager(self._http)
+
+    @classmethod
+    def save_account(
+        cls,
+        *,
+        api_key: str | None = None,
+        url: str | None = None,
+        token: str | None = None,
+        refresh_token: str | None = None,
+        name: str = DEFAULT_PROFILE,
+    ) -> None:
+        """Save credentials to ``~/.nqct/credentials.json`` (mode ``0600``).
+
+        ``url`` defaults to production (``DEFAULT_API_URL``). Pass a different
+        URL for local development.
+        """
+        save_profile(
+            url=url or DEFAULT_API_URL,
+            api_key=api_key,
+            token=token,
+            refresh_token=refresh_token,
+            name=name,
+        )
+
+    @classmethod
+    def delete_account(cls, *, name: str = DEFAULT_PROFILE) -> None:
+        """Remove a named profile from the credentials file."""
+        delete_profile(name=name)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> NQCTClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def me(self) -> dict[str, Any]:
+        """``GET /auth/me`` — current user profile."""
+        payload: dict[str, Any] = self._http.get("/auth/me").json()
+        return payload
+
+    def backends(
+        self,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        type: str | None = None,
+        status: str | None = None,
+        provider: str | None = None,
+        search: str | None = None,
+    ) -> list[Backend]:
+        """``GET /backends`` — list backends with optional filters."""
+        return self._backends.list(
+            skip=skip,
+            limit=limit,
+            type=type,
+            status=status,
+            provider=provider,
+            search=search,
+        )
+
+    def backend(self, backend_id: str) -> Backend:
+        """``GET /backends/{id}`` — fetch a single backend."""
+        return self._backends.get(backend_id)
+
+    def least_busy(self, *, type: str = "simulator") -> Backend:
+        """Return the online backend with the lowest queue depth."""
+        return self._backends.least_busy(type=type)
+
+    def jobs(
+        self,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        status: str | None = None,
+        function_id: str | None = None,
+        backend_id: str | None = None,
+        source: str | None = None,
+        user_id: UUID | str | None = None,
+    ) -> list[Job]:
+        """``GET /jobs`` — list jobs with optional filters."""
+        return self._jobs.list(
+            skip=skip,
+            limit=limit,
+            status=status,
+            function_id=function_id,
+            backend_id=backend_id,
+            source=source,
+            user_id=user_id,
+        )
+
+    def submit_job(
+        self,
+        *,
+        qasm: str,
+        backend_id: str,
+        shots: int = 1024,
+        priority: int = 5,
+        source: JobSubmitSource = "direct_qasm",
+        execution_config: dict[str, Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+        fake_backend_name: str | None = None,
+        optimization_level: int = 1,
+        custom_noise_model: dict[str, Any] | None = None,
+        qubit_mapping: QubitMapping | None = None,
+        gate_substitutions: dict[str, Any] | None = None,
+        acquisition_type: str | None = None,
+        averaging: str | None = None,
+        shot_repeat: int | None = None,
+        readout_mapping: dict[str, Any] | None = None,
+        pulse_calibration_id: str | None = None,
+    ) -> Job:
+        """``POST /jobs`` — submit OpenQASM 3 for async execution on a managed backend.
+
+        Use ``source="api"`` for automation clients that distinguish SDK submits.
+        Use ``source="pulse_designer"`` when submitting regenerated OpenPulse QASM
+        for hardware execution. If ``execution_config`` is passed explicitly, it is
+        sent as-is and the hardware/simulator kwargs (``fake_backend_name``,
+        ``optimization_level``, ``custom_noise_model``, ``qubit_mapping``,
+        ``gate_substitutions``, ``acquisition_type``, ``averaging``,
+        ``shot_repeat``, ``readout_mapping``, ``pulse_calibration_id``) are ignored.
+        """
+        return self._jobs.submit(
+            qasm=qasm,
+            backend_id=backend_id,
+            shots=shots,
+            priority=priority,
+            source=source,
+            execution_config=execution_config,
+            metadata=metadata,
+            fake_backend_name=fake_backend_name,
+            optimization_level=optimization_level,
+            custom_noise_model=custom_noise_model,
+            qubit_mapping=qubit_mapping,
+            gate_substitutions=gate_substitutions,
+            acquisition_type=acquisition_type,
+            averaging=averaging,
+            shot_repeat=shot_repeat,
+            readout_mapping=readout_mapping,
+            pulse_calibration_id=pulse_calibration_id,
+        )
+
+    def job(self, job_id: UUID | str) -> Job:
+        """``GET /jobs/{id}`` — fetch a single job."""
+        return self._jobs.get(job_id)
+
+    def functions(
+        self,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        status: str | None = None,
+        sdk_type: str | None = None,
+        search: str | None = None,
+    ) -> list[Function]:
+        """``GET /functions`` — list own and public functions."""
+        return self._functions.list(
+            skip=skip,
+            limit=limit,
+            status=status,
+            sdk_type=sdk_type,
+            search=search,
+        )
+
+    def function(self, function_id: UUID | str) -> Function:
+        """``GET /functions/{id}`` — fetch a single function."""
+        return self._functions.get(function_id)
+
+    @property
+    def http(self) -> HTTPSession:
+        """Low-level HTTP session (advanced use)."""
+        return self._http
+
+
+def _resolve_credentials(
+    *,
+    url: str | None,
+    api_key: str | None,
+    token: str | None,
+    refresh_token: str | None,
+    account_name: str | None,
+) -> dict[str, str]:
+    profile_name = account_name or os.environ.get(_ENV_ACCOUNT_NAME, DEFAULT_PROFILE)
+
+    if url is None and api_key is None and token is None:
+        try:
+            profile = load_profile(profile_name)
+            url = profile.get("url")
+            api_key = api_key or profile.get("api_key")
+            token = token or profile.get("token")
+            refresh_token = refresh_token or profile.get("refresh_token")
+        except (FileNotFoundError, KeyError):
+            pass
+
+    url = url or os.environ.get(_ENV_URL) or DEFAULT_API_URL
+    api_key = api_key or os.environ.get(_ENV_API_KEY)
+    token = token or os.environ.get(_ENV_TOKEN)
+    refresh_token = refresh_token or os.environ.get(_ENV_REFRESH_TOKEN)
+
+    result: dict[str, str] = {"url": url}
+    if api_key:
+        result["api_key"] = api_key
+    if token:
+        result["token"] = token
+    if refresh_token:
+        result["refresh_token"] = refresh_token
+    return result
+
+
+def _env_verify_ssl() -> bool:
+    raw = os.environ.get(_ENV_VERIFY_SSL, "true").lower()
+    return raw not in {"0", "false", "no"}

nqct/exceptions.py

@@ -0,0 +1,55 @@
+"""NQCT SDK exception hierarchy."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class NQCTError(Exception):
+    """Base error for all NQCT SDK failures."""
+
+    def __init__(self, message: str, *, status_code: int | None = None, detail: Any = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.detail = detail
+
+
+class AuthenticationError(NQCTError):
+    """Raised when credentials are missing, invalid, or expired (HTTP 401)."""
+
+
+class AuthorizationError(NQCTError):
+    """Raised when the user lacks permission (HTTP 403)."""
+
+
+class NotFoundError(NQCTError):
+    """Raised when a resource does not exist (HTTP 404)."""
+
+
+class ValidationError(NQCTError):
+    """Raised when request validation fails (HTTP 422)."""
+
+
+class ConflictError(NQCTError):
+    """Raised on resource conflicts such as booking overlap (HTTP 409)."""
+
+
+class RateLimitError(NQCTError):
+    """Raised when the API rate limit is exceeded (HTTP 429)."""
+
+
+class ServerError(NQCTError):
+    """Raised on server-side failures (HTTP 5xx)."""
+
+
+class JobFailedError(NQCTError):
+    """Raised when a job reaches ``failed`` status."""
+
+
+class JobNotCompleteError(NQCTError):
+    """Raised when results are requested before a job is ``done``."""
+
+
+class JobTimeoutError(NQCTError):
+    """Raised when ``job.wait()`` exceeds the timeout."""

nqct/execution/__init__.py

@@ -0,0 +1 @@
+"""Sync circuit execution and job polling (Phase 1–2)."""

nqct/execution/polling.py

@@ -0,0 +1,37 @@
+"""Job polling helpers."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+from nqct.exceptions import JobFailedError, JobTimeoutError
+
+if TYPE_CHECKING:
+    from nqct.models.job import Job
+
+
+def wait_for_terminal_status(
+    job: Job,
+    *,
+    timeout: float | None,
+    interval: float,
+) -> Job:
+    """Poll until the job reaches a terminal status or times out."""
+    deadline = time.monotonic() + timeout if timeout is not None else None
+    current = job
+
+    while not current.is_terminal:
+        if deadline is not None and time.monotonic() >= deadline:
+            raise JobTimeoutError(
+                f"Job {current.id} did not complete within {timeout} seconds "
+                f"(last status: {current.status!r})."
+            )
+        time.sleep(interval)
+        current = current.refresh()
+
+    if current.status == "failed":
+        message = current.error_message or f"Job {current.id} failed."
+        raise JobFailedError(message)
+
+    return current

nqct/httpss/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP transport for NQCT Cloud REST API."""
+
+from nqct.httpss.session import HTTPSession
+
+__all__ = ["HTTPSession"]

nqct/httpss/pagination.py

@@ -0,0 +1,29 @@
+"""Pagination helpers for list endpoints (Phase 1)."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class PageIterator(Generic[T]):
+    """Iterate paginated API list responses.
+
+    Concrete resource managers will populate this in Phase 1.
+    """
+
+    def __init__(self, items: list[T]) -> None:
+        self._items = items
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self._items)
+
+    @classmethod
+    def from_payload(cls, payload: Any) -> PageIterator[Any]:
+        if isinstance(payload, list):
+            return cls(payload)
+        if isinstance(payload, dict) and isinstance(payload.get("items"), list):
+            return cls(payload["items"])
+        return cls([])