quantufai 0.1.0__py3-none-any.whl

quantufai/__init__.py

@@ -0,0 +1,68 @@
+"""quantufai — the official QuantufAI Python SDK.
+
+Quantum compute a program can PRICE and READ, but never SPEND: quotes before
+any spend, job status/results with receipts and error bars verbatim, signed
+receipt verification, circuit export, and a free sandbox simulator. There is
+no dispatch or approval method — spending stays with a human in the dashboard
+(see ``quantufai.client`` for the full contract).
+
+This package intentionally replaces the repo's former SDK stubs, which called
+endpoints that did not exist and fabricated job statuses from pattern-matched
+text. Everything here calls the real, mounted, scope-gated API — and what the
+API refuses, this SDK reports as a typed ``REFUSED``, never a made-up answer.
+"""
+from ._version import __version__
+from .client import FREE_SIMULATOR_PROVIDER, Client, ReceiptVerification
+from .types import (
+    FAILED,
+    QUEUED,
+    REFUSED,
+    RUNNING,
+    SUCCEEDED,
+    CircuitExport,
+    GovernedReceipt,
+    JobResult,
+    JobStatus,
+    Me,
+    PlatformError,
+    Quote,
+    QuoteResponse,
+    ReceiptBundle,
+    Refusal,
+    ResultExport,
+    SandboxRun,
+    TransportError,
+    is_terminal,
+    normalize_state,
+)
+from .verify import ChainCheck, OfflineVerification, verify_receipt_offline
+
+__all__ = [
+    "__version__",
+    "Client",
+    "FREE_SIMULATOR_PROVIDER",
+    "ReceiptVerification",
+    "Refusal",
+    "REFUSED",
+    "QUEUED",
+    "RUNNING",
+    "SUCCEEDED",
+    "FAILED",
+    "Quote",
+    "QuoteResponse",
+    "JobStatus",
+    "JobResult",
+    "ReceiptBundle",
+    "GovernedReceipt",
+    "CircuitExport",
+    "ResultExport",
+    "SandboxRun",
+    "Me",
+    "TransportError",
+    "PlatformError",
+    "normalize_state",
+    "is_terminal",
+    "OfflineVerification",
+    "ChainCheck",
+    "verify_receipt_offline",
+]

quantufai/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

quantufai/canonical.py

@@ -0,0 +1,100 @@
+"""Canonical JSON — a byte-exact Python port of the platform's stableStringify.
+
+Receipt signatures cover ``stableStringify(receipt minus signature fields)``:
+deterministic JSON with lexicographically sorted object keys, serialized the
+way JavaScript's ``JSON.stringify`` serializes scalars. Verification in Python
+therefore needs the SAME bytes — including JavaScript's number formatting
+(``1e21`` -> ``"1e+21"``, ``1e-7`` -> ``"1e-7"``, ``1.0`` -> ``"1"``), which
+differs from Python's ``json.dumps`` in the corners.
+
+Parity is pinned by shared test vectors (tests/fixtures/canonical_vectors.json)
+asserted against both this module and the Node implementation.
+"""
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+
+def _js_number(value: float) -> str:
+    """Format a float exactly as ECMAScript Number::toString(10) would.
+
+    JSON.stringify emits non-finite numbers as ``null``; integral values
+    without a fractional part; exponential notation only for |exponent|
+    outside [-6, 21); exponents unpadded with an explicit sign.
+    """
+    if math.isnan(value) or math.isinf(value):
+        return "null"  # JSON.stringify(NaN) === "null"
+    if value == 0:
+        return "0"
+    # Shortest round-trip decimal digits (repr is shortest in Python >= 3.1,
+    # same guarantee V8 uses).
+    rep = repr(abs(value))
+    if "e" in rep or "E" in rep:
+        mantissa, _, exp_part = rep.lower().partition("e")
+        exp10 = int(exp_part)
+    else:
+        mantissa, exp10 = rep, 0
+    int_part, _, frac_part = mantissa.partition(".")
+    digits = (int_part + frac_part).lstrip("0")
+    # Decimal point position: value = 0.<digits> * 10**point
+    point = len(int_part.lstrip("0")) + exp10 if int_part.strip("0") else (
+        exp10 - (len(frac_part) - len(frac_part.lstrip("0")))
+    )
+    digits = digits.rstrip("0") or "0"
+    sign = "-" if value < 0 else ""
+
+    k = len(digits)
+    if k <= point <= 21:  # integral, printed in full
+        return sign + digits + "0" * (point - k)
+    if 0 < point <= 21:  # decimal point inside the digits
+        return sign + digits[:point] + "." + digits[point:]
+    if -6 < point <= 0:  # small: leading zeros after "0."
+        return sign + "0." + "0" * (-point) + digits
+    # Exponential: d[.ddd]e±e  (exponent = point - 1, unpadded, signed)
+    exponent = point - 1
+    exp_str = ("+" if exponent >= 0 else "-") + str(abs(exponent))
+    if k == 1:
+        return sign + digits + "e" + exp_str
+    return sign + digits[0] + "." + digits[1:] + "e" + exp_str
+
+
+def stable_stringify(value: Any) -> str:
+    """Deterministic JSON with sorted object keys — parity with the platform."""
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, str):
+        # ensure_ascii=False matches JSON.stringify (raw UTF-8, control chars
+        # escaped); Python and JS agree on the mandatory escape set.
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        # JS has one number type: 1.0 serializes as "1" (handled in _js_number).
+        return _js_number(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(stable_stringify(v) for v in value) + "]"
+    if isinstance(value, dict):
+        # JavaScript's Array.prototype.sort() compares strings by UTF-16 code
+        # units; utf-16-be byte order reproduces that exactly (receipt keys are
+        # ASCII in practice, but parity should not depend on practice).
+        items = sorted(
+            ((str(k), v) for k, v in value.items()),
+            key=lambda kv: kv[0].encode("utf-16-be"),
+        )
+        return "{" + ",".join(
+            json.dumps(k, ensure_ascii=False) + ":" + stable_stringify(v) for k, v in items
+        ) + "}"
+    raise TypeError(f"stable_stringify: unsupported type {type(value).__name__}")
+
+
+def unsigned_canonical(receipt: dict) -> str:
+    """The exact bytes both platform signatures cover: the receipt minus its
+    ``signature`` and ``publicSignature`` fields."""
+    clone = {k: v for k, v in receipt.items() if k not in ("signature", "publicSignature")}
+    return stable_stringify(clone)

quantufai/client.py

@@ -0,0 +1,409 @@
+"""The QuantufAI client — quantum compute you can price and read, never spend.
+
+THE DESIGN, STATED LOUDLY (this is not a missing feature)
+=========================================================
+This SDK has NO dispatch method, NO approval method, NO billing method.
+A program holding an API key can:
+
+  - ask what a run would cost (``quote`` — estimates only, nothing reserved,
+    charged, or dispatched),
+  - follow runs it owns (``job_status``/``job_result``/``wait``),
+  - fetch and verify signed receipts (``receipt``/``governed_receipt``/
+    ``verify_receipt``),
+  - take the exact circuit home (``export_circuit``/``export_result``),
+  - execute on the FREE local simulator (``sandbox_simulate`` — $0 by
+    construction; the request pins the free simulator on every call).
+
+Spending money on quantum hardware requires a human approving a signed quote
+in the QuantufAI dashboard. That is enforced SERVER-side (quote-before-spend;
+scoped keys cannot approve), and this SDK's surface simply omits spending on
+top of it. An AI agent driving this client cannot buy anything.
+
+Every deliberate platform refusal is returned as a typed
+:class:`~quantufai.types.Refusal` (status ``REFUSED``) — codes, messages, and
+details verbatim. Exceptions are reserved for transport failures and
+unexpected 5xx answers.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+
+from ._version import __version__
+from .types import (
+    CircuitExport,
+    GovernedReceipt,
+    JobResult,
+    JobStatus,
+    Me,
+    PlatformError,
+    QuoteResponse,
+    ReceiptBundle,
+    Refusal,
+    ResultExport,
+    SandboxRun,
+    TransportError,
+)
+from .verify import OfflineVerification, verify_receipt_offline
+
+#: The one provider the SDK will ever execute on: the platform's free local
+#: statevector simulator. ``sandbox_simulate`` pins this on EVERY request, so
+#: even a key that carries the paid ``runs:execute`` scope cannot reach
+#: billable hardware through this SDK. (Sandbox keys are additionally clamped
+#: server-side; naming any other provider gets a typed refusal, never a
+#: silent reroute.)
+FREE_SIMULATOR_PROVIDER = "classical"
+
+_ENV_API_KEY = "QUANTUFAI_API_KEY"
+_ENV_BASE_URL = "QUANTUFAI_BASE_URL"
+
+
+@dataclass(frozen=True)
+class ReceiptVerification:
+    """Combined offline + platform verification report.
+
+    ``offline`` is a pure function of the pasted bytes (Ed25519 tier).
+    ``platform`` is the platform's own check of its HMAC server attestation
+    (requires the key's owner to own the receipt), or ``None`` when skipped,
+    or a :class:`Refusal` when the platform declined to answer.
+    """
+
+    offline: OfflineVerification
+    platform: Optional[Union[Dict[str, Any], Refusal]] = None
+    notes: List[str] = field(default_factory=list)
+
+    @property
+    def verified(self) -> bool:
+        """True when ANY tier produced a positive verdict. Check the tiers
+        individually when you need to know WHICH guarantee you got."""
+        if self.offline.verified:
+            return True
+        return isinstance(self.platform, dict) and self.platform.get("valid") is True
+
+
+class Client:
+    """Key-authenticated QuantufAI API client (see module docstring for the
+    can/can't-do contract — the short version: price and read, never spend).
+
+    Args:
+        api_key: a ``qfai_sk_...`` API key (default: ``$QUANTUFAI_API_KEY``).
+        base_url: the platform origin, e.g. ``https://<your-host>``
+            (default: ``$QUANTUFAI_BASE_URL``). Required — the SDK does not
+            guess a host.
+        timeout: per-request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+    ):
+        self.api_key = api_key or os.environ.get(_ENV_API_KEY) or ""
+        raw_base = base_url or os.environ.get(_ENV_BASE_URL) or ""
+        if not self.api_key:
+            raise ValueError(
+                f"An API key is required (pass api_key= or set ${_ENV_API_KEY}). "
+                "Mint one in the QuantufAI dashboard — a sandbox-tier key runs the "
+                "free simulator with no card."
+            )
+        if not raw_base:
+            raise ValueError(
+                f"A base URL is required (pass base_url= or set ${_ENV_BASE_URL})."
+            )
+        self.base_url = raw_base.rstrip("/")
+        self.timeout = timeout
+
+    # ------------------------------------------------------------------
+    # Transport
+    # ------------------------------------------------------------------
+
+    def _headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": f"quantufai-python/{__version__}",
+        }
+
+    @staticmethod
+    def _parse_error(status: int, body: Any) -> Refusal:
+        """Shape the platform's two error envelopes into one typed Refusal:
+        ``{error: {code, message, details}}`` and ``{error: "code", ...}``."""
+        if isinstance(body, dict):
+            err = body.get("error")
+            if isinstance(err, dict):
+                details = err.get("details")
+                return Refusal(
+                    code=str(err.get("code", "unknown")),
+                    message=str(err.get("message", err.get("code", ""))),
+                    http_status=status,
+                    details=details if isinstance(details, dict) else {},
+                )
+            if isinstance(err, str):
+                rest = {k: v for k, v in body.items() if k not in ("error", "message")}
+                return Refusal(
+                    code=err,
+                    message=str(body.get("message", err)),
+                    http_status=status,
+                    details=rest,
+                )
+        return Refusal(
+            code=f"http_{status}",
+            message=str(body)[:500] if body is not None else f"HTTP {status}",
+            http_status=status,
+            details={},
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Optional[Dict[str, Any]] = None,
+        query: Optional[Dict[str, str]] = None,
+    ) -> Union[Any, Refusal]:
+        """Perform one request. 2xx -> parsed JSON (or raw text for non-JSON
+        bodies); 4xx -> :class:`Refusal`; 5xx -> :class:`PlatformError`;
+        network trouble -> :class:`TransportError`."""
+        url = self.base_url + path
+        if query:
+            url += "?" + urllib.parse.urlencode({k: v for k, v in query.items() if v is not None})
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        req = urllib.request.Request(url, data=data, headers=self._headers(), method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                raw = resp.read()
+                content_type = resp.headers.get("Content-Type", "")
+                if "json" in content_type:
+                    return json.loads(raw.decode("utf-8")) if raw else {}
+                return raw.decode("utf-8")
+        except urllib.error.HTTPError as err:
+            raw = err.read()
+            try:
+                parsed = json.loads(raw.decode("utf-8")) if raw else None
+            except (ValueError, UnicodeDecodeError):
+                parsed = raw.decode("utf-8", "replace") if raw else None
+            if 400 <= err.code < 500:
+                return self._parse_error(err.code, parsed)
+            refusal_shaped = self._parse_error(err.code, parsed)
+            raise PlatformError(err.code, refusal_shaped.code, refusal_shaped.message, parsed)
+        except urllib.error.URLError as err:
+            raise TransportError(f"{method} {url}: {err.reason}") from err
+        except TimeoutError as err:
+            raise TransportError(f"{method} {url}: timed out after {self.timeout}s") from err
+
+    # ------------------------------------------------------------------
+    # Quote before spend (quotes:read)
+    # ------------------------------------------------------------------
+
+    def quote(
+        self,
+        circuit: str,
+        *,
+        shots: int = 1000,
+        qubits: Optional[int] = None,
+        max_cost_usd: Optional[float] = None,
+        max_latency_ms: Optional[int] = None,
+        min_fidelity: Optional[float] = None,
+    ) -> Union[QuoteResponse, Refusal]:
+        """Ask what this run WOULD cost, per provider. A quote never reserves,
+        charges, or dispatches anything — and neither can any other method
+        here. Requires the ``quotes:read`` scope."""
+        intent: Dict[str, Any] = {"type": "circuit", "shots": shots}
+        if max_cost_usd is not None:
+            intent["maxCostUsd"] = max_cost_usd
+        if max_latency_ms is not None:
+            intent["maxLatencyMs"] = max_latency_ms
+        if min_fidelity is not None:
+            intent["minFidelity"] = min_fidelity
+        params: Dict[str, Any] = {"shots": shots}
+        if qubits is not None:
+            params["qubits"] = qubits
+        raw = self._request(
+            "POST", "/api/v1/quotes",
+            body={"intent": intent, "payload": {"circuit": circuit, "params": params}},
+        )
+        if isinstance(raw, Refusal):
+            return raw
+        return QuoteResponse.from_raw(raw)
+
+    # ------------------------------------------------------------------
+    # Follow your runs (jobs:read)
+    # ------------------------------------------------------------------
+
+    def job_status(self, job_id: str) -> Union[JobStatus, Refusal]:
+        """"Is it done yet?" — status poll. Requires ``jobs:read``. You see
+        only your own runs; someone else's job answers ``job_not_found``."""
+        raw = self._request("GET", f"/api/v1/jobs/{urllib.parse.quote(job_id)}")
+        return raw if isinstance(raw, Refusal) else JobStatus.from_raw(raw)
+
+    def job_result(self, job_id: str) -> Union[JobResult, Refusal]:
+        """Status + counts + operational ledger. Still-running hardware jobs
+        are refreshed from the provider at read time. Requires ``jobs:read``."""
+        raw = self._request("GET", f"/api/v1/jobs/{urllib.parse.quote(job_id)}/result")
+        return raw if isinstance(raw, Refusal) else JobResult.from_raw(raw)
+
+    def wait(
+        self,
+        job_id: str,
+        *,
+        timeout: float = 600.0,
+        poll_interval: float = 2.0,
+    ) -> Union[JobResult, Refusal]:
+        """Poll ``job_result`` until the run reaches a terminal state.
+
+        Raises :class:`TransportError` when ``timeout`` elapses first (the
+        run itself is NOT cancelled — this SDK cannot mutate runs)."""
+        deadline = time.monotonic() + timeout
+        while True:
+            result = self.job_result(job_id)
+            if isinstance(result, Refusal) or result.done:
+                return result
+            if time.monotonic() >= deadline:
+                raise TransportError(
+                    f"wait({job_id!r}): still {result.state} after {timeout}s "
+                    "(the run keeps going; poll again or raise the timeout)"
+                )
+            time.sleep(poll_interval)
+
+    # ------------------------------------------------------------------
+    # Receipts (jobs:read)
+    # ------------------------------------------------------------------
+
+    def receipt(self, job_id: str) -> Union[ReceiptBundle, Refusal]:
+        """The run's ledger receipts + artifacts summary. Requires ``jobs:read``."""
+        raw = self._request("GET", f"/api/v1/jobs/{urllib.parse.quote(job_id)}/receipt")
+        return raw if isinstance(raw, Refusal) else ReceiptBundle.from_raw(raw)
+
+    def governed_receipt(self, job_id: str) -> Union[GovernedReceipt, Refusal]:
+        """The signed, downloadable Governed Run Receipt — the tamper-evident
+        artifact the dashboard serves, byte-for-byte. Requires ``jobs:read``."""
+        raw = self._request(
+            "GET", f"/api/v1/jobs/{urllib.parse.quote(job_id)}/governed-receipt"
+        )
+        return raw if isinstance(raw, Refusal) else GovernedReceipt(data=raw)
+
+    def verify_receipt(
+        self,
+        receipt: Union[Dict[str, Any], GovernedReceipt],
+        *,
+        public_key: Optional[str] = None,
+        offline_only: bool = False,
+    ) -> ReceiptVerification:
+        """Verify a receipt you hold. Two independent tiers, reported honestly:
+
+        - OFFLINE (Ed25519 ``publicSignature``): pure function of the pasted
+          bytes + QuantufAI's published public key. Needs ``public_key`` and
+          the ``quantufai[verify]`` extra.
+        - PLATFORM (HMAC server attestation): asks the platform to confirm
+          the signature is one IT issued (``POST /api/v1/jobs/verify-receipt``,
+          ``jobs:read``; the receipt must be your own).
+
+        Neither tier is silently substituted for the other."""
+        data = receipt.data if isinstance(receipt, GovernedReceipt) else receipt
+        offline = verify_receipt_offline(data, public_key=public_key)
+        platform: Optional[Union[Dict[str, Any], Refusal]] = None
+        notes: List[str] = []
+        if not offline_only:
+            answer = self._request(
+                "POST", "/api/v1/jobs/verify-receipt", body={"receipt": data}
+            )
+            platform = answer
+            if isinstance(answer, Refusal):
+                notes.append(
+                    f"platform check refused ({answer.code}): {answer.message}"
+                )
+        return ReceiptVerification(offline=offline, platform=platform, notes=notes)
+
+    # ------------------------------------------------------------------
+    # Take the circuit home (results:export)
+    # ------------------------------------------------------------------
+
+    def export_circuit(
+        self,
+        job_id: str,
+        *,
+        format: str,
+        which: str,
+    ) -> Union[CircuitExport, Refusal]:
+        """Export the exact stored circuit of a run as ready-to-run source
+        (``qiskit``/``cirq``/``braket``/``pytket``/``qasm``). ``which`` is
+        REQUIRED — ``"original"`` (as authored) or ``"as-dispatched"`` (the
+        exact program handed to the executor); the platform refuses to guess.
+        Untranslatable circuits get a typed refusal, never a lossy guess.
+        Requires ``results:export``."""
+        raw = self._request(
+            "GET",
+            f"/api/v1/jobs/{urllib.parse.quote(job_id)}/circuit",
+            query={"format": format, "which": which, "envelope": "json"},
+        )
+        return raw if isinstance(raw, Refusal) else CircuitExport.from_raw(raw)
+
+    def export_result(
+        self, job_id: str, *, format: str = "json"
+    ) -> Union[ResultExport, Refusal]:
+        """Download the run's result artifact (the Jobs-page "Download
+        Result"). Incomplete runs answer a typed refusal. Requires
+        ``results:export``."""
+        raw = self._request(
+            "GET",
+            f"/api/v1/jobs/{urllib.parse.quote(job_id)}/export",
+            query={"format": format},
+        )
+        if isinstance(raw, Refusal):
+            return raw
+        content = raw if isinstance(raw, str) else json.dumps(raw)
+        return ResultExport(content=content, format=format)
+
+    # ------------------------------------------------------------------
+    # Sandbox execution (runs:simulate) — the ONLY execution here, $0
+    # ------------------------------------------------------------------
+
+    def sandbox_simulate(
+        self,
+        circuit: str,
+        *,
+        shots: int = 1000,
+        qubits: Optional[int] = None,
+    ) -> Union[SandboxRun, Refusal]:
+        """Run the circuit on the FREE local statevector simulator.
+
+        The request pins ``preferredProviders=["classical"]`` — the free
+        simulator — on EVERY call, so no key, whatever its scopes, can reach
+        billable hardware through this method (zero eligible providers is a
+        typed failure server-side, never a silent reroute). Sandbox-tier keys
+        (``runs:simulate``) are additionally clamped and daily-quota'd by the
+        platform. Real statevector physics, real counts, $0."""
+        params: Dict[str, Any] = {"shots": shots}
+        if qubits is not None:
+            params["qubits"] = qubits
+        raw = self._request(
+            "POST",
+            "/api/v1/execute",
+            body={
+                "intent": {"type": "circuit", "shots": shots},
+                "payload": {"circuit": circuit, "params": params},
+                # THE CLAMP. Do not remove, do not parameterize: this constant
+                # is what makes the SDK's "can never spend" claim true even
+                # for keys that carry runs:execute.
+                "preferredProviders": [FREE_SIMULATOR_PROVIDER],
+            },
+        )
+        return raw if isinstance(raw, Refusal) else SandboxRun.from_raw(raw)
+
+    # ------------------------------------------------------------------
+    # Account awareness (account:read)
+    # ------------------------------------------------------------------
+
+    def me(self) -> Union[Me, Refusal]:
+        """Who is this key? Tier, credits, granted scopes, rate limits.
+        Requires ``account:read``."""
+        raw = self._request("GET", "/api/v1/me")
+        return raw if isinstance(raw, Refusal) else Me.from_raw(raw)