spinorio 1.1.0__tar.gz

spinorio-1.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,189 @@
+# 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/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=75", "wheel"]
+build-backend = "setuptools.build_meta"
+[project]
+name = "spinorio"
+version = "1.1.0"
+description = "Spinorio Workflow, Weylattice compilation and Hilvarian optimization client"
+readme = "README.md"
+requires-python = ">=3.12,<3.14"
+license = {text = "Proprietary"}
+authors = [{name = "Spinorio Inc"}]
+dependencies = ["httpx>=0.27,<1", "spinorio-runtime==1.1.0", "ipython>=8.18", "keyring>=25,<27", "filelock>=3.16,<4"]
+[project.optional-dependencies]
+qiskit = ["qiskit>=2.5,<2.6"]
+[project.scripts]
+spinorio = "spinorio.cli:main"
+[tool.setuptools.packages.find]
+where = ["src"]
+[tool.pytest.ini_options]
+testpaths = ["tests"]

spinorio-1.1.0/setup.cfg

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

spinorio-1.1.0/src/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-1.1.0/src/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-1.1.0/src/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()