spinorio 1.1.0__py3-none-any.whl

spinorio/__init__.py

@@ -0,0 +1,6 @@
+"""Spinorio: one client for Workflow, Compile and Solvers, locally and in Lab."""
+
+from .client import Spinorio, APIError, SubmissionUncertain
+
+__version__ = "1.1.0"
+__all__ = ["Spinorio", "APIError", "SubmissionUncertain"]

spinorio/_credentials.py

@@ -0,0 +1,112 @@
+"""Credential resolution for local Python and authenticated Spinorio Lab kernels."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from urllib.parse import urlsplit
+
+PUBLIC_API = "https://api.spinorio.com/api/v1"
+
+
+def _url(value, *, internal=False):
+    value = value.rstrip("/")
+    parsed = urlsplit(value)
+    cluster_http = (
+        internal and parsed.scheme == "http"
+        and (parsed.hostname or "").endswith(".svc.cluster.local")
+    )
+    if (parsed.scheme != "https" and not cluster_http) or not parsed.netloc or any(
+        (parsed.username, parsed.password, parsed.query, parsed.fragment)
+    ):
+        raise ValueError("Use an HTTPS API URL without credentials, query or fragment")
+    return value
+
+
+def _profile_token(base_url, profile):
+    import keyring
+
+    try:
+        return keyring.get_password("spinorio:" + base_url, profile)
+    except keyring.errors.KeyringError:
+        return None
+
+
+class PersonalCredential:
+    kind = "api-token"
+
+    def __init__(self, token):
+        if not isinstance(token, str) or not token.strip():
+            raise ValueError("The API token must be a nonempty string")
+        self._token = token.strip()
+
+    def exchange(self, client):
+        return client._checked(client._http.post(
+            client.base_url + "/auth/token",
+            headers={"Authorization": "Bearer " + self._token},
+            json={"session_id": client.session_id},
+        )).json()
+
+
+class LabCredential:
+    kind = "lab"
+
+    def __init__(self, base, path):
+        self.base = base
+        self.path = path
+
+    def exchange(self, client):
+        from filelock import FileLock
+
+        # Multiple kernels share the workspace credential. Rotate atomically and
+        # always reread it, including after another kernel refreshed the session.
+        with FileLock(str(self.path) + ".sdk.lock", timeout=30):
+            try:
+                token = self.path.read_text(encoding="utf-8").strip()
+            except OSError as exc:
+                raise RuntimeError("Lab credentials are unavailable. Restart your Lab session.") from exc
+            if not token:
+                raise ValueError("Lab credentials are empty. Restart your Lab session.")
+            data = client._checked(client._http.post(
+                self.base + "/v1/auth/sdk-token",
+                headers={"Authorization": "Bearer " + token},
+                json={"session_id": client.session_id},
+            )).json()
+            refresh = data.pop("refresh_token")
+            temporary = None
+            try:
+                with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=self.path.parent, delete=False) as out:
+                    temporary = Path(out.name)
+                    os.chmod(temporary, 0o600)
+                    out.write(refresh)
+                temporary.replace(self.path)
+            finally:
+                if temporary is not None and temporary.exists():
+                    temporary.unlink()
+            return data
+
+
+def resolve(token, base_url, profile):
+    """Explicit token, explicit profile, environment token, Lab, default profile."""
+    public = _url(base_url or os.getenv("SPINORIO_API_BASE_URL") or PUBLIC_API)
+    if token is not None:
+        return public, PersonalCredential(token)
+    if profile is not None:
+        value = _profile_token(public, profile)
+        if not value:
+            raise ValueError(f"No API token saved for profile {profile!r} at this API URL")
+        return public, PersonalCredential(value)
+    if "SPINORIO_API_TOKEN" in os.environ:
+        return public, PersonalCredential(os.environ["SPINORIO_API_TOKEN"])
+    if os.getenv("SPINORIO_SDK_LAB_MODE") == "1" and base_url is None and not os.getenv("SPINORIO_API_BASE_URL"):
+        base = os.getenv("SPINORIO_CONTROL_PLANE_BASE_URL", "").rstrip("/")
+        path = os.getenv("SPINORIO_SENSOR_REFRESH_TOKEN_PATH", "")
+        if not base or not path:
+            raise ValueError("Lab connection settings are unavailable. Restart your Lab session.")
+        base = _url(base, internal=True)
+        return base + "/api/v1", LabCredential(base, Path(path))
+    value = _profile_token(public, "default")
+    if not value:
+        raise ValueError("Supply token=, set SPINORIO_API_TOKEN, or save a profile with spinorio auth save")
+    return public, PersonalCredential(value)

spinorio/cli.py

@@ -0,0 +1,78 @@
+import argparse
+import getpass
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(prog="spinorio")
+    parser.add_argument("--profile")
+    commands = parser.add_subparsers(dest="command", required=True)
+    auth = commands.add_parser("auth").add_subparsers(dest="action", required=True)
+    auth.add_parser("save")
+    auth.add_parser("remove")
+    commands.add_parser("usage")
+    commands.add_parser("engines")
+    wf = commands.add_parser("workflow").add_subparsers(dest="action", required=True)
+    run = wf.add_parser("run")
+    run.add_argument("script", nargs="?")
+    run.add_argument("args", nargs=argparse.REMAINDER)
+    wf.add_parser("enable-autostart")
+    wf.add_parser("disable-autostart")
+    args = parser.parse_args()
+    from . import Spinorio
+
+    if args.command == "auth":
+        import keyring, os
+
+        service = "spinorio:" + os.getenv(
+            "SPINORIO_API_BASE_URL", "https://api.spinorio.com/api/v1"
+        ).rstrip("/")
+        profile = args.profile or "default"
+        if args.action == "remove":
+            keyring.delete_password(service, profile)
+        else:
+            token = getpass.getpass("Spinorio API token (hidden): ")
+            with Spinorio(token) as client:
+                client.sensor_token()
+            keyring.set_password(service, profile, token)
+        print("Profile updated in the operating system credential store.")
+        return
+    with Spinorio(profile=args.profile) as client:
+        if args.command in {"usage", "engines"}:
+            import json
+
+            print(json.dumps(getattr(client, args.command)(), indent=2))
+            return
+        if args.action == "enable-autostart":
+            print(client.workflow.enable_autostart(profile=args.profile))
+            return
+        if args.action == "disable-autostart":
+            client.workflow.disable_autostart()
+            return
+        from IPython.terminal.interactiveshell import TerminalInteractiveShell
+
+        shell = TerminalInteractiveShell.instance()
+        client.workflow.run(ipython=shell)
+        try:
+            if args.script:
+                from pathlib import Path
+
+                sys.argv = [args.script] + args.args
+                result = shell.run_cell(
+                    Path(args.script).read_text(encoding="utf-8"), store_history=True
+                )
+                client.workflow.flush()
+                if not result.success:
+                    raise SystemExit(1)
+            else:
+                print(
+                    "Spinorio capture is active in this IPython session. Existing kernels are unaffected."
+                )
+                shell.mainloop()
+                client.workflow.flush()
+        finally:
+            client.workflow.stop()
+
+
+if __name__ == "__main__":
+    main()

spinorio/client.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+import hashlib
+import threading
+import time
+import uuid
+from urllib.parse import urlsplit
+import httpx
+
+
+class APIError(RuntimeError):
+    def __init__(self, status, detail, *, retry_after=None):
+        self.status_code = status
+        self.detail = detail
+        self.retry_after = retry_after
+        super().__init__(f"Spinorio API {status}: {detail}")
+
+
+class SubmissionUncertain(RuntimeError):
+    """The server may have accepted this request. Retry this exact saved body."""
+
+    def __init__(self, client, path, body, factory):
+        self.client = client
+        self.path = path
+        self.request = dict(body)
+        self.factory = factory
+        self.idempotency_key = body["idempotency_key"]
+        super().__init__(
+            "Submission acknowledgement unavailable. Call exception.retry(); do not create a new job."
+        )
+
+    def retry(self):
+        return self.factory(
+            self.client.request("POST", self.path, json=self.request, retry=True)
+        )
+
+
+class Spinorio:
+    """One authenticated client. Credentials never travel to artifact download hosts."""
+
+    def __init__(
+        self, token=None, *, base_url=None, profile=None, timeout=30, transport=None
+    ):
+        from ._credentials import resolve
+
+        self.base_url, self._credential = resolve(token, base_url, profile)
+        self._http = httpx.Client(
+            timeout=timeout, transport=transport, follow_redirects=False
+        )
+        self._lock = threading.Lock()
+        self._access = ""
+        self._expires = 0
+        self.identity = None
+        self.session_id = "sdk_" + uuid.uuid4().hex
+        from .compile import CompileClient
+        from .solvers import SolverClient
+        from .workflow import WorkflowClient
+
+        self.compile = CompileClient(self)
+        self.solvers = SolverClient(self)
+        self.workflow = WorkflowClient(self)
+
+    def __repr__(self):
+        return f"Spinorio(base_url={self.base_url!r})"
+
+    def close(self):
+        if getattr(self.workflow, "_owns_capture", False):
+            self.workflow.stop()
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    @staticmethod
+    def _checked(response):
+        if not 200 <= response.status_code < 300:
+            try:
+                detail = response.json().get("detail", "Request failed")
+            except ValueError:
+                detail = "Request failed"
+            raise APIError(
+                response.status_code,
+                detail,
+                retry_after=response.headers.get("retry-after"),
+            )
+        return response
+
+    def sensor_token(self):
+        with self._lock:
+            if time.monotonic() + 30 >= self._expires:
+                data = self._credential.exchange(self)
+                self._access = data["access_token"]
+                self._expires = time.monotonic() + data["expires_in"]
+                self.identity = {
+                    k: data[k] for k in ("user_id", "workspace_id", "plan", "scopes")
+                }
+            return {
+                "access_token": self._access,
+                "expires_in": max(1, int(self._expires - time.monotonic())),
+            }
+
+    def request(
+        self, method, path, *, json=None, params=None, binary=False, retry=False
+    ):
+        if not path.startswith("/") or "://" in path or ".." in path:
+            raise ValueError("Invalid API path")
+        attempts = 3 if method == "GET" or retry else 1
+        for attempt in range(attempts):
+            try:
+                token = self.sensor_token()["access_token"]
+                response = self._http.request(
+                    method,
+                    self.base_url + path,
+                    json=json,
+                    params=params,
+                    headers={"Authorization": "Bearer " + token},
+                )
+                if response.status_code == 401:
+                    self._expires = 0
+                    token = self.sensor_token()["access_token"]
+                    response = self._http.request(
+                        method,
+                        self.base_url + path,
+                        json=json,
+                        params=params,
+                        headers={"Authorization": "Bearer " + token},
+                    )
+                self._checked(response)
+                return (
+                    response.content
+                    if binary
+                    else (response.json() if response.content else None)
+                )
+            except APIError as exc:
+                if exc.status_code not in {502, 503, 504} or attempt + 1 == attempts:
+                    raise
+            except httpx.TransportError:
+                if attempt + 1 == attempts:
+                    raise
+            time.sleep(min(2**attempt, 4))
+
+    def upload(self, info, raw):
+        url = info["upload_url"]
+        if urlsplit(url).scheme != "https":
+            raise ValueError("Insecure artifact upload URL")
+        self._checked(
+            self._http.put(url, content=raw, headers=info.get("upload_headers", {}))
+        )
+
+    def download(self, info, destination):
+        from pathlib import Path
+        import tempfile
+
+        url = info["download_url"]
+        size = int(info["size_bytes"])
+        if urlsplit(url).scheme != "https" or size < 0 or size > 128 * 1024 * 1024:
+            raise ValueError("Invalid artifact download")
+        target = Path(destination)
+        temporary = None
+        try:
+            with tempfile.NamedTemporaryFile(dir=target.parent, delete=False) as out:
+                temporary = Path(out.name)
+                digest = hashlib.sha256()
+                total = 0
+                with self._http.stream("GET", url) as response:
+                    self._checked(response)
+                    for block in response.iter_bytes():
+                        total += len(block)
+                        if total > size:
+                            raise ValueError("Artifact exceeds declared size")
+                        digest.update(block)
+                        out.write(block)
+            if total != size or digest.hexdigest() != info["sha256"]:
+                raise ValueError("Artifact integrity check failed")
+            temporary.replace(target)
+            return target
+        finally:
+            if temporary and temporary.exists():
+                temporary.unlink()
+
+    def engines(self):
+        return self.request("GET", "/sdk/engines")
+
+    def usage(self):
+        return self.request("GET", "/sdk/usage")
+
+    def qcompile(self, circuit, *, backend="linear_5", timeout=360, **kwargs):
+        return self.compile.run(circuit, target_id=backend, **kwargs).result(
+            wait=True, timeout=timeout
+        )
+
+    def provider_connection(self):
+        return self.request("GET", "/provider-connections/ibm")
+
+    def connect_ibm(self, api_token):
+        return self.request(
+            "POST", "/provider-connections/ibm", json={"api_key": api_token}
+        )
+
+    def disconnect_ibm(self):
+        return self.request("POST", "/provider-connections/ibm/disconnect", json={})

spinorio/compile.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+import hashlib
+import io
+import time
+import uuid
+from urllib.parse import quote
+import httpx
+from .client import APIError, SubmissionUncertain
+
+
+def segment(value):
+    if not isinstance(value, str) or not value or "/" in value or value in {".", ".."}:
+        raise ValueError("Invalid identifier")
+    return quote(value, safe=":")
+
+
+def load_qpy(raw):
+    from qiskit import qpy
+
+    circuits = qpy.load(io.BytesIO(raw))
+    if len(circuits) != 1:
+        raise ValueError("Expected one Qiskit circuit")
+    return circuits[0]
+
+
+class Compilation:
+    def __init__(self, client, job_id):
+        self.client = client
+        self.job_id = job_id
+        self.path = "/compiler/jobs/" + segment(job_id)
+
+    def status(self):
+        row = self.client.request("GET", self.path)
+        if row.get("engine") == "spinorio":
+            row["engine"] = "weylattice"
+        return row
+
+    def wait(self, timeout=360, poll_seconds=2):
+        if poll_seconds < 1:
+            raise ValueError("Polling interval must be at least one second")
+        deadline = time.monotonic() + timeout
+        while True:
+            state = self.status()
+            if state["status"] in {"completed", "failed"}:
+                return state
+            if time.monotonic() >= deadline:
+                raise TimeoutError("Compilation continues. Job ID: " + self.job_id)
+            time.sleep(poll_seconds)
+
+    def result(self, *, wait=False, timeout=360):
+        if wait:
+            state = self.wait(timeout)
+            if state["status"] == "failed":
+                raise RuntimeError(state.get("error") or "Compilation failed")
+        return load_qpy(
+            self.client.request("GET", self.path + "/artifact", binary=True)
+        )
+
+    def download(self, destination):
+        from pathlib import Path
+
+        target = Path(destination)
+        target.write_bytes(
+            self.client.request("GET", self.path + "/artifact", binary=True)
+        )
+        return target
+
+    def metrics(self):
+        state = self.status()
+        return {
+            key: value
+            for key, value in state.items()
+            if "metric" in key or key in {"quality", "analysis", "comparison"}
+        }
+
+
+class CompileClient:
+    def __init__(self, client):
+        self.client = client
+
+    def list_engines(self):
+        return [e["id"] for e in self.client.engines()["compile"]["engines"]]
+
+    def get_default_engine(self):
+        return self.client.engines()["compile"]["default"]
+
+    def targets(self):
+        return self.client.request("GET", "/compiler/targets")
+
+    def ibm_instances(self):
+        return self.client.request("GET", "/compiler/ibm/instances")["instances"]
+
+    def ibm_backends(self, instance_id):
+        if not isinstance(instance_id, str) or not instance_id.startswith("ibmi_"):
+            raise ValueError("Choose an instance ID returned by client.compile.ibm_instances()")
+        segment(instance_id)
+        return self.client.request(
+            "GET", "/compiler/ibm/backends", params={"instance_id": instance_id}
+        )
+
+    def list(self, **filters):
+        return self.client.request("GET", "/compiler/jobs", params=filters)
+
+    def get(self, job_id):
+        return Compilation(self.client, job_id)
+
+    def upload_circuit(self, circuit, *, version_id=None):
+        from qiskit import QuantumCircuit, qpy, __version__
+
+        if not isinstance(circuit, QuantumCircuit):
+            raise TypeError("Expected a Qiskit QuantumCircuit")
+        buffer = io.BytesIO()
+        qpy.dump(circuit, buffer)
+        raw = buffer.getvalue()
+        if len(raw) > 16 * 1024 * 1024:
+            raise ValueError("Circuit QPY exceeds 16 MiB")
+        version_id = version_id or "cct_" + uuid.uuid4().hex + ":v1"
+        info = self.client.request(
+            "POST",
+            "/circuits/artifacts/uploads",
+            json={
+                "circuit_version_id": version_id,
+                "sha256": hashlib.sha256(raw).hexdigest(),
+                "size_bytes": len(raw),
+                "qiskit_version": __version__,
+            },
+            retry=True,
+        )
+        if info["status"] != "ready":
+            self.client.upload(info, raw)
+            self.client.request(
+                "POST",
+                "/circuits/artifacts/uploads/complete",
+                json={"circuit_version_id": version_id, "upload_id": info["upload_id"]},
+                retry=True,
+            )
+        return version_id
+
+    def run(
+        self,
+        circuit=None,
+        *,
+        circuit_version_id=None,
+        target_id="linear_5",
+        engine=None,
+        optimization_level=2,
+        idempotency_key=None,
+        **options,
+    ):
+        if (circuit is None) == (circuit_version_id is None):
+            raise ValueError("Supply exactly one circuit or circuit_version_id")
+        if engine not in (None, "weylattice"):
+            raise ValueError("Unknown engine; use compile.list_engines()")
+        key = idempotency_key or uuid.uuid4().hex
+        if circuit_version_id is None:
+            # Retry with the same key maps to the same immutable upload identity.
+            circuit_version_id = self.upload_circuit(
+                circuit,
+                version_id="cct_"
+                + hashlib.sha256(key.encode()).hexdigest()[:32]
+                + ":v1",
+            )
+        body = dict(
+            options,
+            circuit_version_id=circuit_version_id,
+            target_id=target_id,
+            engine=engine or "weylattice",
+            optimization_level=optimization_level,
+            idempotency_key=key,
+        )
+        factory = lambda row: self.get(row["job_id"])
+        try:
+            return factory(
+                self.client.request("POST", "/compiler/jobs", json=body, retry=True)
+            )
+        except (httpx.TransportError, APIError) as exc:
+            if isinstance(exc, APIError) and exc.status_code < 500:
+                raise
+            raise SubmissionUncertain(
+                self.client, "/compiler/jobs", body, factory
+            ) from exc

spinorio/solvers.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+import hashlib
+import json
+import time
+import uuid
+import httpx
+from .client import APIError, SubmissionUncertain
+from .compile import segment
+
+TERMINAL = {
+    "succeeded",
+    "failed",
+    "cancelled",
+    "deadline_exceeded",
+    "budget_exhausted",
+    "paused_calibration",
+    "needs_attention",
+}
+
+
+class SolverRun:
+    def __init__(self, client, run_id):
+        self.client = client
+        self.run_id = run_id
+        self.path = "/solvers/runs/" + segment(run_id)
+
+    def status(self):
+        return self.client.request("GET", self.path)
+
+    def wait(self, timeout=1800, poll_seconds=5):
+        if poll_seconds < 1:
+            raise ValueError("Polling interval must be at least one second")
+        deadline = time.monotonic() + timeout
+        while True:
+            state = self.status()
+            if state["status"] in TERMINAL:
+                return state
+            if time.monotonic() >= deadline:
+                raise TimeoutError("Solver continues. Run ID: " + self.run_id)
+            time.sleep(poll_seconds)
+
+    def result(self, *, wait=False, timeout=1800):
+        if wait:
+            self.wait(timeout)
+        return self.client.request("GET", self.path + "/result")
+
+    def cancel(self):
+        return self.client.request("POST", self.path + "/cancel", json={})
+
+    def resume(self, *, recalibrate=False):
+        return self.client.request(
+            "POST", self.path + "/resume", json={"recalibrate": recalibrate}
+        )
+
+    def events(self, after=0, limit=100):
+        return self.client.request(
+            "GET", self.path + "/events", params={"after": after, "limit": limit}
+        )
+
+    def artifacts(self, limit=100, offset=0):
+        return self.client.request(
+            "GET", self.path + "/artifacts", params={"limit": limit, "offset": offset}
+        )
+
+    def download(self, artifact_id, destination):
+        return self.client.download(
+            self.client.request(
+                "GET", self.path + "/artifacts/" + segment(artifact_id)
+            ),
+            destination,
+        )
+
+
+class SolverClient:
+    def __init__(self, client):
+        self.client = client
+        self.optimization = self
+
+    def capabilities(self):
+        return self.client.request("GET", "/solvers/capabilities")
+
+    def list_engines(self):
+        return [e["id"] for e in self.client.engines()["solver"]["engines"]]
+
+    def get_default_engine(self):
+        return self.client.engines()["solver"]["default"]
+
+    def models(self, limit=50, offset=0):
+        return self.client.request(
+            "GET", "/solvers/models", params={"limit": limit, "offset": offset}
+        )
+
+    def remove_model(self, model_id):
+        return self.client.request(
+            "POST", "/solvers/models/" + segment(model_id) + "/remove", json={}
+        )
+
+    def list(self, limit=50, offset=0):
+        return self.client.request(
+            "GET", "/solvers/runs", params={"limit": limit, "offset": offset}
+        )
+
+    runs = list
+
+    def get(self, run_id):
+        return SolverRun(self.client, run_id)
+
+    def upload_model(self, problem, *, name="Optimization model", problem_type=None):
+        if hasattr(problem, "to_dict"):
+            problem = problem.to_dict()
+        if not isinstance(problem, dict):
+            raise TypeError("Expected an interchange model dictionary or BinaryModel")
+        problem = dict(problem)
+        if problem_type and problem.get("schema") == "qas.model.v1":
+            if problem.get("source") != problem_type:
+                raise ValueError("Conflicting problem types")
+        elif problem_type:
+            if problem.get("problem_type", problem_type) != problem_type:
+                raise ValueError("Conflicting problem types")
+            problem.setdefault("schema", "spinorio.solver.model.v1")
+            problem["problem_type"] = problem_type
+        raw = json.dumps(
+            problem, sort_keys=True, separators=(",", ":"), allow_nan=False
+        ).encode()
+        if len(raw) > 16 * 1024 * 1024:
+            raise ValueError("Model exceeds 16 MiB")
+        info = self.client.request(
+            "POST",
+            "/solvers/models/uploads",
+            json={
+                "name": name,
+                "sha256": hashlib.sha256(raw).hexdigest(),
+                "size_bytes": len(raw),
+            },
+            retry=True,
+        )
+        if info.get("status") != "ready":
+            self.client.upload(info, raw)
+            self.client.request(
+                "POST",
+                "/solvers/models/" + segment(info["model_id"]) + "/complete",
+                json={},
+                retry=True,
+            )
+        return info["model_id"]
+
+    def run(
+        self,
+        *,
+        problem=None,
+        model_id=None,
+        problem_type=None,
+        name="Optimization model",
+        engine=None,
+        idempotency_key=None,
+        **options,
+    ):
+        if (problem is None) == (model_id is None):
+            raise ValueError("Supply exactly one problem or model_id")
+        if engine not in (None, "hilvarian"):
+            raise ValueError("Unknown engine; use solvers.list_engines()")
+        if model_id is None:
+            model_id = self.upload_model(problem, name=name, problem_type=problem_type)
+        body = dict(
+            options,
+            model_id=model_id,
+            engine=engine or "hilvarian",
+            idempotency_key=idempotency_key or uuid.uuid4().hex,
+        )
+        factory = lambda row: self.get(row["run_id"])
+        try:
+            return factory(
+                self.client.request("POST", "/solvers/runs", json=body, retry=True)
+            )
+        except (httpx.TransportError, APIError) as exc:
+            if isinstance(exc, APIError) and exc.status_code < 500:
+                raise
+            raise SubmissionUncertain(
+                self.client, "/solvers/runs", body, factory
+            ) from exc
+

spinorio/workflow.py

@@ -0,0 +1,295 @@
+"""Kernel capture and retrieval through an authenticated Spinorio client."""
+
+from __future__ import annotations
+import hashlib
+import time
+from pathlib import Path
+from .compile import segment, load_qpy
+
+
+class Records:
+    def __init__(self, client, path):
+        self.client = client
+        self.path = path
+
+    def list(self, **filters):
+        return self.client.request("GET", self.path, params=filters)
+
+    def get(self, identifier):
+        return self.client.request("GET", self.path + "/" + segment(identifier))
+
+
+class Jobs(Records):
+    def refresh(self, job_id):
+        return self.client.request(
+            "POST", "/provider-jobs/" + segment(job_id) + "/refresh", json={}
+        )
+
+    def list(self, **filters):
+        return self.client.request("GET", "/ui/jobs", params=filters)
+
+    def metrics(self, job_id):
+        return self.get(job_id).get("analysis")
+
+    def units(self, job_id, **pagination):
+        return self.client.request(
+            "GET", "/job-work-units/" + segment(job_id), params=pagination
+        )
+
+    def hardware(self, job_id):
+        return self.client.request("GET", "/job-hardware-context/" + segment(job_id))
+
+
+class Circuits(Records):
+    def versions(self, circuit_id, **pagination):
+        return self.client.request(
+            "GET", "/circuits/" + segment(circuit_id) + "/versions", params=pagination
+        )
+
+    def version(self, version_id):
+        return self.client.request("GET", "/circuit-versions/" + segment(version_id))
+
+    def load(self, version_id):
+        return load_qpy(
+            self.client.request(
+                "GET", "/compiler/circuit-artifacts/" + segment(version_id), binary=True
+            )
+        )
+
+    def diagram(self, version_id):
+        return self.client.request("GET", "/circuit-diagrams/" + segment(version_id))
+
+    def draw(self, version_id, **options):
+        return self.load(version_id).draw(**options)
+
+    def metrics(self, version_id):
+        return self.client.request("GET", "/circuit-analyses/" + segment(version_id))
+
+
+class WorkflowClient:
+    def __init__(self, client):
+        self.client = client
+        self.jobs = Jobs(client, "/jobs")
+        self.circuits = Circuits(client, "/circuits")
+        self.experiments = Records(client, "/experiments")
+        self.transpilations = Records(client, "/transpilations")
+
+    def run(
+        self,
+        *,
+        mode="automatic",
+        objects=None,
+        kinds=None,
+        include_code=False,
+        include_errors=False,
+        ipython=None,
+        resume_session_id=None,
+    ):
+        """Activate this kernel. Selective mode captures chosen namespace snapshots."""
+        from IPython import get_ipython
+        import _spinorio_runtime as runtime
+
+        shell = ipython or get_ipython()
+        if shell is None:
+            raise RuntimeError(
+                "Run this inside IPython/Jupyter, or use spinorio workflow run -- script.py"
+            )
+        if mode not in {"automatic", "selective"}:
+            raise ValueError("mode must be automatic or selective")
+        names = list(objects or [])
+        if any(
+            not isinstance(n, str) or not n.isidentifier() or n.startswith("_")
+            for n in names
+        ):
+            raise ValueError(
+                "objects must be public variable names in the active kernel"
+            )
+        types = list(kinds or ["circuits", "jobs", "results", "pass_managers"])
+        if not set(types) <= {"circuits", "jobs", "results", "pass_managers"}:
+            raise ValueError("Unsupported capture kind")
+        if mode == "selective" and not names:
+            raise ValueError("Selective capture requires at least one variable name")
+        if mode == "automatic" and (objects is not None or kinds is not None):
+            raise ValueError('Object/type filters require mode="selective"')
+        existing = _active.get(id(shell))
+        selection = (mode, tuple(sorted(names)), tuple(sorted(types)), bool(include_code), bool(include_errors))
+        if existing is not None:
+            if selection != existing._selection or (
+                resume_session_id is not None and resume_session_id != existing.client.session_id
+            ):
+                raise RuntimeError("Capture is active with different settings. Call client.workflow.stop() before changing them.")
+            self.client.session_id = existing.client.session_id
+            if self is not existing:
+                self.client._expires = 0
+        if resume_session_id is not None:
+            import re
+
+            if not re.fullmatch(r"sdk_[a-f0-9]{32}", resume_session_id):
+                raise ValueError("Invalid saved session ID")
+            self.client.session_id = resume_session_id
+            self.client._expires = 0
+        self.client.sensor_token()
+        identity = self.client.identity
+        if "workflow:write" not in identity["scopes"]:
+            raise PermissionError(
+                "This token needs Workflow write permission to capture"
+            )
+        if existing is not None:
+            owner = existing.client
+            if (self.client.base_url, identity["user_id"], identity["workspace_id"]) != (
+                owner.base_url, owner.identity["user_id"], owner.identity["workspace_id"]
+            ):
+                raise RuntimeError("This kernel is capturing for another account or API URL. Stop capture before switching accounts.")
+            self._shell = shell
+            return runtime.status(shell)
+        if runtime.status(shell).get("installed"):
+            raise RuntimeError("A sensor is already active outside this client. Stop it before starting capture.")
+        key = hashlib.sha256(
+            (
+                self.client.base_url
+                + "\0"
+                + identity["user_id"]
+                + "\0"
+                + identity["workspace_id"]
+            ).encode()
+        ).hexdigest()[:32]
+        # Each process has its own active queue; session id persists in its directory
+        # for CLI replay after a crash. Never mix accounts or API origins.
+        root = Path.home() / ".spinorio" / "capture" / key / self.client.session_id
+        root.mkdir(parents=True, exist_ok=True, mode=0o700)
+        # Lock an active spool so two kernels cannot consume the same queue.
+        from filelock import FileLock, Timeout
+
+        lock = FileLock(str(root / "capture.lock"))
+        try:
+            lock.acquire(timeout=0)
+        except Timeout as exc:
+            raise RuntimeError("This saved capture session is already active") from exc
+        config = {
+            "endpoint": self.client.base_url + "/observations",
+            "token_endpoint": self.client.base_url + "/auth/token",
+            "bootstrap_refresh_token": "",
+            "refresh_token_path": str(root / "unused-refresh"),
+            "spool_dir": str(root / "pending"),
+            "dead_letter_dir": str(root / "dead-letter"),
+            "sender_state_path": str(root / "state.json"),
+            "qpy_spool_dir": str(root / "qpy"),
+            "qpy_upload_endpoint": self.client.base_url + "/circuits/artifacts/uploads",
+            "qpy_capture_enabled": True,
+            "token_provider": self.client.sensor_token,
+            "include_cell_code": include_code,
+            "include_errors": include_errors,
+            "capture_mode": mode,
+            "capture_names": names,
+            "capture_kinds": types,
+            "http_timeout": 15.0,
+            "enabled": True,
+            "dev_jsonl_path": "",
+        }
+        try:
+            if not runtime.install(shell, config):
+                raise RuntimeError("Sensor could not register IPython hooks")
+        except BaseException:
+            lock.release()
+            raise
+        _active[id(shell)] = self
+        self._spool_lock = lock
+        self._shell = shell
+        self._selection = selection
+        self._owns_capture = True
+        return runtime.status(shell)
+
+    start = run
+
+    def status(self):
+        import _spinorio_runtime as runtime
+        from IPython import get_ipython
+
+        return runtime.status(getattr(self, "_shell", None) or get_ipython())
+
+    def stop(self):
+        import _spinorio_runtime as runtime
+        from IPython import get_ipython
+
+        shell = getattr(self, "_shell", None) or get_ipython()
+        result = runtime.uninstall(shell)
+        owner = _active.pop(id(shell), None)
+        if owner is not None:
+            owner._spool_lock.release()
+            owner._owns_capture = False
+            owner._shell = None
+        self._shell = None
+        return result
+
+    def flush(self, timeout=30):
+        deadline = time.monotonic() + timeout
+        while True:
+            state = self.status()
+            if not state.get("installed"):
+                return state
+            sender = state.get("sender", {})
+            qpy = state.get("qpy", {})
+            if (
+                not sender.get("pending_batches", 0)
+                and not sender.get("pending_detail_batches", 0)
+                and not qpy.get("queued", 0)
+            ):
+                return state
+            if time.monotonic() >= deadline:
+                raise TimeoutError(
+                    "Capture remains on disk. Use workflow.status() to inspect delivery."
+                )
+            time.sleep(0.2)
+
+    def pending_sessions(self):
+        """List resumable spool session IDs for this account and API origin."""
+        self.client.sensor_token()
+        identity = self.client.identity
+        key = hashlib.sha256(
+            (
+                self.client.base_url
+                + "\0"
+                + identity["user_id"]
+                + "\0"
+                + identity["workspace_id"]
+            ).encode()
+        ).hexdigest()[:32]
+        base = Path.home() / ".spinorio" / "capture" / key
+        return [
+            {
+                "session_id": folder.name,
+                "pending_files": len(list((folder / "pending").glob("*.json"))),
+                "qpy_files": len(list((folder / "qpy").glob("*.qpy"))),
+            }
+            for folder in sorted(base.glob("sdk_*"))
+            if folder.is_dir()
+        ]
+
+    def enable_autostart(self, *, profile=None):
+        """Explicit opt-in for future kernels in the current IPython profile."""
+        from IPython.paths import get_ipython_dir
+
+        target = (
+            Path(get_ipython_dir()) / "profile_default" / "startup" / "90-spinorio.py"
+        )
+        target.parent.mkdir(parents=True, exist_ok=True)
+        code = (
+            "from spinorio import Spinorio\n_spinorio_capture = Spinorio(profile="
+            + repr(profile)
+            + ")\n_spinorio_capture.workflow.run()\n"
+        )
+        target.write_text(code, encoding="utf-8")
+        return target
+
+    def disable_autostart(self):
+        from IPython.paths import get_ipython_dir
+
+        target = (
+            Path(get_ipython_dir()) / "profile_default" / "startup" / "90-spinorio.py"
+        )
+        if target.exists():
+            target.unlink()
+
+
+
+_active = {}

spinorio-1.1.0.dist-info/METADATA

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: spinorio
+Version: 1.1.0
+Summary: Spinorio Workflow, Weylattice compilation and Hilvarian optimization client
+Author: Spinorio Inc
+License: Proprietary
+Requires-Python: <3.14,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: spinorio-runtime==1.1.0
+Requires-Dist: ipython>=8.18
+Requires-Dist: keyring<27,>=25
+Requires-Dist: filelock<4,>=3.16
+Provides-Extra: qiskit
+Requires-Dist: qiskit<2.6,>=2.5; extra == "qiskit"
+Dynamic: license-file
+
+# Spinorio Python SDK
+
+Workflow capture and retrieval, Weylattice compilation, and Hilvarian optimization from your own Python environment.
+
+Install Spinorio 1.1.0:
+
+```bash
+python -m pip install 'spinorio[qiskit]==1.1.0'
+```
+
+`spinorio-runtime` is a **required dependency**, including when installing plain `spinorio`. The native sensor is installed by default. The `qiskit` extra installs the supported Qiskit 2.5 series for circuit helpers and workflow capture; it does not control sensor installation. Importing the package does not start capture.
+
+Supported environments: CPython 3.12 and 3.13, Windows x64, Linux x64 with glibc, and macOS Intel/Apple Silicon. Python 3.14, PyPy, Windows ARM and Linux ARM are not declared supported in this release.
+
+## Authentication
+
+Create an expiring token at **Account → API tokens** on spinorio.com. Copy it when shown. You can list token metadata and revoke it later; the full secret cannot be retrieved again.
+
+```python
+import os
+from spinorio import Spinorio
+
+client = Spinorio(token=os.environ['SPINORIO_API_TOKEN'])
+print(client.usage())
+```
+
+Inside Spinorio Lab, use the same client without copying a token:
+
+```python
+from spinorio import Spinorio
+client = Spinorio()
+```
+
+The client reuses your authenticated Lab workspace. On your laptop, `Spinorio()` reads `SPINORIO_API_TOKEN` automatically. You can also use an operating-system credential store:
+
+```bash
+spinorio auth save
+spinorio usage
+```
+
+The prompt hides your token. `spinorio --profile research auth save` and `Spinorio(profile='research')` select a named profile. Credential selection is explicit token, explicit named profile, environment token, authenticated Lab workspace, then default saved profile. An invalid explicit credential raises an error; the client never switches accounts silently. No browser login is required. On a headless system without a working keyring, pass the token or use the environment variable. Never place a real token in a shared notebook or Git repository.
+
+Tokens authenticate to `https://api.spinorio.com/api/v1`; the client exchanges them for short-lived access tokens. Different client instances keep separate credentials. Revocation rejects subsequent requests, including requests with an unexpired access token. Accepted jobs continue after revocation. Plan changes are reflected without replacing the personal token; the entitlement cache lasts at most 30 seconds.
+
+## Compile
+
+```python
+from qiskit import QuantumCircuit
+
+qc = QuantumCircuit(2)
+qc.h(0)
+qc.cx(0, 1)
+
+print(client.compile.list_engines())          # ['weylattice']
+print(client.compile.get_default_engine())    # 'weylattice'
+print(client.compile.targets())
+
+job = client.compile.run(qc, target_id='linear_5')
+print(job.job_id)
+print(job.status())
+compiled = job.result(wait=True, timeout=360)
+print(job.metrics())
+job.download('compiled.qpy')
+
+# Reconnect to existing work, including from another machine:
+job = client.compile.get(job.job_id)
+
+# Synchronous convenience:
+compiled = client.qcompile(qc, backend='linear_5')
+```
+
+`linear_5` is a reference topology, not a physical QPU. Engine selection is optional: `engine='weylattice'` is the default. Unsupported engines are rejected. Fetch the catalog again to discover later additions.
+
+For IBM targets, connect your provider account first, select an instance using `client.compile.ibm_instances()`, then select a returned target from `client.compile.ibm_backends(instance_id)`. Existing provider connections from Lab are reused. A token with `providers:manage` can call `client.connect_ibm(api_token)`, `client.provider_connection()` and `client.disconnect_ibm()`. Provider credentials are stored by the existing encrypted control-plane path and are never returned through the public API. An API subscription does not include provider QPU charges.
+
+## Solve
+
+```python
+print(client.solvers.list_engines())          # ['hilvarian']
+print(client.solvers.get_default_engine())    # 'hilvarian'
+print(client.solvers.capabilities())
+
+problem = {
+    'schema': 'spinorio.solver.model.v1',
+    'problem_type': 'maxcut',
+    'variables': ['a', 'b', 'c'],
+    'edges': [['a', 'b', 1], ['b', 'c', 1], ['c', 'a', 1]],
+}
+run = client.solvers.optimization.run(
+    problem=problem, problem_type='maxcut', executor='local_numpy',
+    engine='hilvarian',
+)
+print(run.run_id, run.status())
+state = run.wait(timeout=300)
+result = run.result()
+print(run.events())
+for item in run.artifacts():
+    print(item)
+
+same_run = client.solvers.get(run.run_id)
+# same_run.cancel()
+# same_run.resume(recalibrate=True)
+# same_run.download(artifact_id, 'evidence.json')
+```
+
+`local_numpy` and `local_aer` are server-side executors. Availability comes from `capabilities()`. IBM execution retains the existing per-account hardware gate. No automatic escalation to paid hardware occurs. Search, error-management and budget parameters use the existing solver contract. Basic/Plus API admissions also enforce per-run wall-time and shot ceilings. `result()` reports an error when no result exists; `wait()` can also return a paused or failed state.
+
+For uncertain submission acknowledgements, retain the exception and retry its exact request:
+
+```python
+from spinorio import SubmissionUncertain
+try:
+    run = client.solvers.run(model_id=saved_model_id, idempotency_key='my-experiment-001')
+except SubmissionUncertain as error:
+    run = error.retry()
+```
+
+The retry retains the originating client, model and idempotency key. Changing request settings with the same key returns a conflict. Ordinary reads, polls and idempotent job retries do not consume another job allowance. Keep your returned job/run IDs.
+
+## Workflow in your existing notebook
+
+```python
+client.workflow.run()              # current IPython kernel only
+# Run your quantum experiment in following cells.
+client.workflow.status()           # sender, native observer and QPY queue health
+client.workflow.flush(timeout=30)  # wait for pending uploads
+client.workflow.stop()             # stop hooks; unsent work stays on disk
+```
+
+Spinorio Lab starts automatic capture when its kernel starts. Calling `client.workflow.run()` again with the same account and settings reuses that sensor. To change capture settings, call `client.workflow.stop()` first, then `client.workflow.run(...)`. On your laptop, capture starts only when you call `run()` or explicitly enable autostart.
+
+Automatic mode uses the existing Qiskit observation adapters: circuits and versions, supported transpilation boundaries, provider jobs and already-returned results. It is not a recorder of every Python object, arbitrary file or complete kernel memory. A completed experiment cannot be reconstructed if it was never observed or its QPY capture failed. Use `status()` to inspect dropped, rejected, pending and failed delivery counts.
+
+Selective mode is deliberately narrower: it takes supported named-object snapshots at cell boundaries and disables global runtime-boundary capture:
+
+```python
+client.workflow.run(
+    mode='selective', objects=['qc', 'job', 'result'],
+    kinds=['circuits', 'jobs', 'results'],
+)
+```
+
+Names must exist in the active kernel when the observed cell finishes. Direct QuantumCircuit, supported job/result and pass-manager objects are eligible. Selective mode does not recursively capture arbitrary containers or full intermediate call histories. Raw cell code and exception messages are off by default; opt in with `include_code=True` or `include_errors=True`.
+
+Queues are bounded and stored under `~/.spinorio/capture/`, partitioned by account, API origin and sensor session. They contain experiment data, not your API token. Delivery retries use persisted payloads. After a kernel crash:
+
+```python
+print(client.workflow.pending_sessions())
+client.workflow.run(resume_session_id='sdk_...')  # choose a returned session ID
+```
+
+Only one kernel may use a given spool at a time. Retrying an unchanged payload does not double-charge ingress bytes. Queue overflow is reported rather than silently accepting data. Revocation or exhausted allowance can interrupt delivery, so preserve pending queues until the issue is resolved.
+
+From a terminal:
+
+```bash
+spinorio workflow run                  # opens a new captured IPython session
+spinorio workflow run -- experiment.py # executes a script in captured IPython
+spinorio workflow enable-autostart     # explicitly enable future default-profile kernels
+spinorio workflow disable-autostart
+```
+
+The CLI cannot attach to a different, already-running kernel. Use the Python call inside that kernel. Autostart is optional; installation and ordinary `run()` do not edit IPython startup files. For scripts, runtime boundaries are captured during the script; namespace snapshots occur at the script's end.
+
+## Recall and analysis
+
+```python
+jobs = client.workflow.jobs.list(limit=50)
+record = client.workflow.jobs.get(job_id)
+analysis = client.workflow.jobs.metrics(job_id)
+# client.workflow.jobs.refresh(job_id)  # refresh supported provider jobs using your stored connection
+units = client.workflow.jobs.units(job_id, limit=50, offset=0)
+
+circuits = client.workflow.circuits.list(limit=50)
+versions = client.workflow.circuits.versions(circuit_id)
+snapshot = client.workflow.circuits.version(circuit_version_id)
+qc = client.workflow.circuits.load(circuit_version_id)
+diagram_data = client.workflow.circuits.diagram(circuit_version_id)
+print(client.workflow.circuits.draw(circuit_version_id, output='text'))
+metrics = client.workflow.circuits.metrics(circuit_version_id)
+```
+
+`load()` returns a Qiskit circuit from stored QPY. `diagram()` returns the control plane's structured diagram data; `draw()` renders locally using Qiskit. Metrics are the control plane's available analyses, not invented values. Missing artifacts return a clear API error. Nothing unpickles arbitrary remote Python objects.
+
+## Account usage
+
+`client.usage()` returns your current plan, monthly limits and usage. Basic includes 10 compilation jobs and 10 solver runs per month; Plus includes 200 of each. Workflow capture is measured by uploaded data, with 10 MiB per month on Basic and 1 GiB on Plus. Reads and polling do not use another job allowance. Upload and solver execution limits are also returned by `usage()`.
+
+Usage belongs to your account across Lab, laptops and API tokens. Creating another token does not reset it. Lab session time is a separate allowance. If an allowance is exhausted, the API returns HTTP 429; `APIError` exposes `status_code`, `detail` and `retry_after`. Check usage or upgrade through your account.

spinorio-1.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+spinorio/__init__.py,sha256=4a9Qm9VMHEaAzw472MPbvTOw6AnOaHGqmxlGh6N3cJA,224
+spinorio/_credentials.py,sha256=xjgfNcTdwIq_TD66YzYQVHlJsjqxwRjLYXI4RpMLhEg,4381
+spinorio/cli.py,sha256=huZGSq-1IQk43FdqVn4B2pcr85FBJ8hFcoMQPGF3CmE,2793
+spinorio/client.py,sha256=5fQPVwnchJoNlKA05E7MMpg8rV1hXfRWwH_d4YneJc4,7225
+spinorio/compile.py,sha256=a-NraVIPJglpPqa-JtvHmE1ByIWL9z9jSwLSjOVj1P4,6112
+spinorio/solvers.py,sha256=UPo9qtB2gq9i46TBRiUlb555ew-kPq_-qG5mJKGXCx4,5961
+spinorio/workflow.py,sha256=2MN2Jbw2CIXNvEw7NCA_4SC-1Q49WYhfuuegybfvVLM,11080
+spinorio-1.1.0.dist-info/licenses/LICENSE,sha256=6KqGnUmyeWSLZNwajEZM2gjA1hSaisrn1nOzSxFus4Q,190
+spinorio-1.1.0.dist-info/METADATA,sha256=s1Qx_XBvxg9FiPtPT7977Xtq1GAskUQFoagnKoTWe0A,11088
+spinorio-1.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+spinorio-1.1.0.dist-info/entry_points.txt,sha256=dDVoYFZ-Q7LhTFoFBbiFsQcW1_R1XB5H4tp1LIZ9qJk,47
+spinorio-1.1.0.dist-info/top_level.txt,sha256=2OVrUpNvV9G1Qfb6PcId8WAAnZmHBKSpv6xV9lEjXx0,9
+spinorio-1.1.0.dist-info/RECORD,,

spinorio-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spinorio-1.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spinorio = spinorio.cli:main

spinorio-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,4 @@
+Copyright (c) 2026 Spinorio Inc. All rights reserved.
+
+Proprietary software. No open-source license is granted by this distribution.
+Use is subject to the applicable Spinorio service terms.

spinorio-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+spinorio