openquantum-sdk 0.4.2__tar.gz → 1.0.0__tar.gz

openquantum_sdk-1.0.0/MANIFEST.in

@@ -0,0 +1,10 @@
+# Unit tests ship in the sdist. packages.find excludes them from the wheel,
+# so they are not installed into site-packages.
+# plugins/ is a separate set of distributions and must not ride along.
+# smoke/ is the live runner for the manual SDK smoke workflow.
+include README.md
+include requirements*.txt
+recursive-include tests *.py
+global-exclude *.pyc
+prune plugins
+prune smoke

{openquantum_sdk-0.4.2/openquantum_sdk.egg-info → openquantum_sdk-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openquantum-sdk
-Version: 0.4.2
+Version: 1.0.0
 Summary: Python SDK for Open Quantum
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: Apache Software License
@@ -16,9 +16,13 @@ Requires-Dist: requests-mock>=1.10.0; extra == "dev"
 Requires-Dist: flake8; extra == "dev"
 Requires-Dist: black; extra == "dev"
 Provides-Extra: qiskit
-Requires-Dist: openquantum-sdk-qiskit>=0.3.1; extra == "qiskit"
+Requires-Dist: openquantum-sdk-qiskit>=1.0.0; extra == "qiskit"
 Provides-Extra: pennylane
-Requires-Dist: openquantum-sdk-pennylane>=0.2.1; extra == "pennylane"
+Requires-Dist: openquantum-sdk-pennylane>=1.0.0; extra == "pennylane"
+Provides-Extra: cirq
+Requires-Dist: openquantum-sdk-cirq>=0.5.0; extra == "cirq"
+Provides-Extra: qrisp
+Requires-Dist: openquantum-sdk-qrisp>=0.5.0; extra == "qrisp"
 
 # Open Quantum Python SDK
 
@@ -44,6 +48,8 @@ pip install -e .
 
 Python 3.8+ required.
 
+Source distributions include the `tests/` tree so the unit tests can be run from an sdist. Wheels do not install those tests into `site-packages`. The Qiskit, PennyLane, Cirq, and Qrisp plugins, and `openquantum-mcp`, use the same split. Package versions live in each `pyproject.toml` and `__version__` (core, Qiskit, and PennyLane `1.0.0`; Cirq and Qrisp `0.5.0`; MCP `0.2.0`).
+
 ## Authentication
 
 ### Option 1: SDK Key File (Recommended)
@@ -78,6 +84,18 @@ export OPENQUANTUM_CLIENT_ID=s_...
 export OPENQUANTUM_CLIENT_SECRET=e460c8...
 ```
 
+### `OpenQuantumClient.from_env()`
+
+Builds a client from those environment credentials and from `OPENQUANTUM_SCHEDULER_URL`, `OPENQUANTUM_MANAGEMENT_URL`, `OPENQUANTUM_KEYCLOAK_BASE`, and `OPENQUANTUM_KEYCLOAK_REALM`. It does not autoload a saved account. It raises `AuthenticationError` when no credential resolves.
+
+```python
+from openquantum_sdk import OpenQuantumClient
+
+client = OpenQuantumClient.from_env()
+```
+
+`OPENQUANTUM_ORGANIZATION_ID` is not read by the core client constructor. PennyLane, Cirq, Qrisp, `get_backend`, and the MCP server use it when `organization_id` is omitted. The old names `OQ_ORG_ID` and `OQ_SUBCATEGORY_ID` are not read.
+
 ## Quickstart: One-Call Submission (Recommended)
 
 ```python
@@ -282,9 +300,10 @@ finally:
 | `name` | `str` | — | **Required** |
 | `shots` | `int` | — | **Required** |
 | `configuration_data` | `Dict[str, Any]` |`None` | |
-| `execution_plan` | `ExecutionPlanType \| "auto"` | `"auto"` | |
-| `queue_priority` | `QueuePriorityType \| "auto"` | `"auto"` | |
+| `execution_plan` | `str`, enum, or UUID | `"auto"` | `"auto"`, `"public"`, `"private"`, `ExecutionPlanType`, or a plan UUID. `"auto"` picks the cheapest plan |
+| `queue_priority` | `str`, enum, or UUID | `"auto"` | `"auto"`, `"standard"`, `"priority"`, `"instant"`, `QueuePriorityType`, or a priority UUID. `"auto"` picks the cheapest priority |
 | `auto_approve_quote` | `bool` | `True` | Set `False` in notebooks |
+| `verbose` | `bool` | `False` | Print submission progress. Same default on every plugin |
 | `job_timeout_seconds` | `int` | `86400` | 1 day |
 | `input_format` | `str` | `"qasm"` | OpenQASM by default; other values only if listed in backend `supported_formats` |
 | `submitted_with` | `str` | `"sdk"` | Client surface for analytics |
@@ -301,7 +320,10 @@ finally:
 | `upload_job_input(file_path=... or file_content=...)` | `str` | Returns upload ID |
 | `prepare_job(JobPreparationCreate)` | `JobPreparationResponse` | Starts preparation |
 | `get_preparation_result(preparation_id)` | `JobPreparationResultResponse` | Includes `.quote` |
+| `wait_for_preparation(preparation_id, timeout=300, interval=2)` | `JobPreparationResultResponse` | Poll until preparation completes |
+| `choose_plan_and_priority(result, execution_plan="auto", queue_priority="auto")` | `PlanSelection` | Friendly names, enums, and UUIDs. `prefer_public=True` ranks Public first when the plan is `"auto"` |
 | `create_job(JobCreate)` | `JobRead` | Submits job |
+| `wait_for_job(job_id, timeout=300, interval=5)` | `JobRead` | Poll until a terminal status. `raise_on_timeout` and `raise_on_failure` default to `True` |
 | `get_job(job_id)` | `JobRead` | Fetch job status |
 | `cancel_job(job_id)` | `None` | Cancel running job |
 | `list_jobs(organization_id, limit=20, cursor=..., status=...)` | `PaginatedJobs` | List your jobs |
@@ -353,8 +375,9 @@ from openquantum_sdk.utils import poll_for_status
 | ------ | ------ | ------ | ------ |
 | `get_status_fn` | `Callable[[str], Tuple[bool, Any]]` | | Function to be polled |
 | `resource_id` | `str` | | id to be passed to status function: `get_status_fn(resource_id)` | 
-| `interval` | `int` | `5` | Number of seconds to wait before next call of status function |
-| `timeout` | `int` | `300` | Number of seconds before timeout | 
+| `interval` | `float` | `5` | Seconds to wait before the next status call |
+| `timeout` | `float` | `300` | Seconds before polling stops |
+| `raise_on_timeout` | `bool` | `True` | Raise `TimeoutError`, or return the last result when `False` | 
   
 
 ## Enums
@@ -455,13 +478,17 @@ for cat in cats:
 ```
 
 
+## Live smoke tests
+
+`.github/workflows/sdk-smoke.yml` is a manual Actions workflow. It builds the core SDK and the Qiskit, PennyLane, Cirq, and Qrisp plugins from a git ref (empty means `main`), submits a Bell circuit through each one, and waits until the platform job completes. The QPU input defaults to `rigetti:cepheus-1-108q`. Choose the `dev` or `prd` environment when you run it. See [sdk/smoke/README.md](smoke/README.md).
+
 ## FAQ
 
 **Q: How do I get results as JSON?**  
 **A:** Use `scheduler.download_job_output(job)` — returns parsed object.
 
 **Q: Why does auto mode fail on some QPUs?**
-**A:** `"auto"` selects the cheapest plan and priority (`PUBLIC` + `STANDARD`). If a backend only offers private execution, pass `execution_plan="private"` explicitly. Similarly, use `queue_priority="priority"` or `"instant"` for higher-priority queue access.
+**A:** `"auto"` selects the cheapest plan and priority, which is often Public + Standard. It is not limited to those two. Friendly names (`"public"`, `"private"`, `"standard"`, `"priority"`, `"instant"`), enums, and UUIDs select that option exactly. If you need a specific plan or a faster queue, pass it explicitly. The MCP server passes `prefer_public=True` so Spark credits can apply; `submit_job()` does not.
 
 **Q: Can I hide the public plan citation notice?**  
 **A:** Setting `OPENQUANTUM_HIDE_CITATION_NOTICE=true` will omit the citation notice from output.

openquantum_sdk-0.4.2/PKG-INFO → openquantum_sdk-1.0.0/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.4
-Name: openquantum-sdk
-Version: 0.4.2
-Summary: Python SDK for Open Quantum
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.25.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: pytest-mock; extra == "dev"
-Requires-Dist: requests-mock>=1.10.0; extra == "dev"
-Requires-Dist: flake8; extra == "dev"
-Requires-Dist: black; extra == "dev"
-Provides-Extra: qiskit
-Requires-Dist: openquantum-sdk-qiskit>=0.3.1; extra == "qiskit"
-Provides-Extra: pennylane
-Requires-Dist: openquantum-sdk-pennylane>=0.2.1; extra == "pennylane"
-
 # Open Quantum Python SDK
 
 A lightweight, modern Python SDK for the **Open Quantum Platform**.
@@ -44,6 +22,8 @@ pip install -e .
 
 Python 3.8+ required.
 
+Source distributions include the `tests/` tree so the unit tests can be run from an sdist. Wheels do not install those tests into `site-packages`. The Qiskit, PennyLane, Cirq, and Qrisp plugins, and `openquantum-mcp`, use the same split. Package versions live in each `pyproject.toml` and `__version__` (core, Qiskit, and PennyLane `1.0.0`; Cirq and Qrisp `0.5.0`; MCP `0.2.0`).
+
 ## Authentication
 
 ### Option 1: SDK Key File (Recommended)
@@ -78,6 +58,18 @@ export OPENQUANTUM_CLIENT_ID=s_...
 export OPENQUANTUM_CLIENT_SECRET=e460c8...
 ```
 
+### `OpenQuantumClient.from_env()`
+
+Builds a client from those environment credentials and from `OPENQUANTUM_SCHEDULER_URL`, `OPENQUANTUM_MANAGEMENT_URL`, `OPENQUANTUM_KEYCLOAK_BASE`, and `OPENQUANTUM_KEYCLOAK_REALM`. It does not autoload a saved account. It raises `AuthenticationError` when no credential resolves.
+
+```python
+from openquantum_sdk import OpenQuantumClient
+
+client = OpenQuantumClient.from_env()
+```
+
+`OPENQUANTUM_ORGANIZATION_ID` is not read by the core client constructor. PennyLane, Cirq, Qrisp, `get_backend`, and the MCP server use it when `organization_id` is omitted. The old names `OQ_ORG_ID` and `OQ_SUBCATEGORY_ID` are not read.
+
 ## Quickstart: One-Call Submission (Recommended)
 
 ```python
@@ -282,9 +274,10 @@ finally:
 | `name` | `str` | — | **Required** |
 | `shots` | `int` | — | **Required** |
 | `configuration_data` | `Dict[str, Any]` |`None` | |
-| `execution_plan` | `ExecutionPlanType \| "auto"` | `"auto"` | |
-| `queue_priority` | `QueuePriorityType \| "auto"` | `"auto"` | |
+| `execution_plan` | `str`, enum, or UUID | `"auto"` | `"auto"`, `"public"`, `"private"`, `ExecutionPlanType`, or a plan UUID. `"auto"` picks the cheapest plan |
+| `queue_priority` | `str`, enum, or UUID | `"auto"` | `"auto"`, `"standard"`, `"priority"`, `"instant"`, `QueuePriorityType`, or a priority UUID. `"auto"` picks the cheapest priority |
 | `auto_approve_quote` | `bool` | `True` | Set `False` in notebooks |
+| `verbose` | `bool` | `False` | Print submission progress. Same default on every plugin |
 | `job_timeout_seconds` | `int` | `86400` | 1 day |
 | `input_format` | `str` | `"qasm"` | OpenQASM by default; other values only if listed in backend `supported_formats` |
 | `submitted_with` | `str` | `"sdk"` | Client surface for analytics |
@@ -301,7 +294,10 @@ finally:
 | `upload_job_input(file_path=... or file_content=...)` | `str` | Returns upload ID |
 | `prepare_job(JobPreparationCreate)` | `JobPreparationResponse` | Starts preparation |
 | `get_preparation_result(preparation_id)` | `JobPreparationResultResponse` | Includes `.quote` |
+| `wait_for_preparation(preparation_id, timeout=300, interval=2)` | `JobPreparationResultResponse` | Poll until preparation completes |
+| `choose_plan_and_priority(result, execution_plan="auto", queue_priority="auto")` | `PlanSelection` | Friendly names, enums, and UUIDs. `prefer_public=True` ranks Public first when the plan is `"auto"` |
 | `create_job(JobCreate)` | `JobRead` | Submits job |
+| `wait_for_job(job_id, timeout=300, interval=5)` | `JobRead` | Poll until a terminal status. `raise_on_timeout` and `raise_on_failure` default to `True` |
 | `get_job(job_id)` | `JobRead` | Fetch job status |
 | `cancel_job(job_id)` | `None` | Cancel running job |
 | `list_jobs(organization_id, limit=20, cursor=..., status=...)` | `PaginatedJobs` | List your jobs |
@@ -353,8 +349,9 @@ from openquantum_sdk.utils import poll_for_status
 | ------ | ------ | ------ | ------ |
 | `get_status_fn` | `Callable[[str], Tuple[bool, Any]]` | | Function to be polled |
 | `resource_id` | `str` | | id to be passed to status function: `get_status_fn(resource_id)` | 
-| `interval` | `int` | `5` | Number of seconds to wait before next call of status function |
-| `timeout` | `int` | `300` | Number of seconds before timeout | 
+| `interval` | `float` | `5` | Seconds to wait before the next status call |
+| `timeout` | `float` | `300` | Seconds before polling stops |
+| `raise_on_timeout` | `bool` | `True` | Raise `TimeoutError`, or return the last result when `False` | 
   
 
 ## Enums
@@ -455,13 +452,17 @@ for cat in cats:
 ```
 
 
+## Live smoke tests
+
+`.github/workflows/sdk-smoke.yml` is a manual Actions workflow. It builds the core SDK and the Qiskit, PennyLane, Cirq, and Qrisp plugins from a git ref (empty means `main`), submits a Bell circuit through each one, and waits until the platform job completes. The QPU input defaults to `rigetti:cepheus-1-108q`. Choose the `dev` or `prd` environment when you run it. See [sdk/smoke/README.md](smoke/README.md).
+
 ## FAQ
 
 **Q: How do I get results as JSON?**  
 **A:** Use `scheduler.download_job_output(job)` — returns parsed object.
 
 **Q: Why does auto mode fail on some QPUs?**
-**A:** `"auto"` selects the cheapest plan and priority (`PUBLIC` + `STANDARD`). If a backend only offers private execution, pass `execution_plan="private"` explicitly. Similarly, use `queue_priority="priority"` or `"instant"` for higher-priority queue access.
+**A:** `"auto"` selects the cheapest plan and priority, which is often Public + Standard. It is not limited to those two. Friendly names (`"public"`, `"private"`, `"standard"`, `"priority"`, `"instant"`), enums, and UUIDs select that option exactly. If you need a specific plan or a faster queue, pass it explicitly. The MCP server passes `prefer_public=True` so Spark credits can apply; `submit_job()` does not.
 
 **Q: Can I hide the public plan citation notice?**  
 **A:** Setting `OPENQUANTUM_HIDE_CITATION_NOTICE=true` will omit the citation notice from output.

{openquantum_sdk-0.4.2 → openquantum_sdk-1.0.0}/openquantum_sdk/__init__.py

@@ -1,4 +1,13 @@
 from .clients import SchedulerClient, ManagementClient
+from .auth import ClientCredentials, ClientCredentialsAuth
+from .credentials import resolve_env_credentials
+from .session import OpenQuantumClient
+from .exceptions import (
+    OpenQuantumError,
+    AuthenticationError,
+    CircuitValidationError,
+    JobError,
+)
 from .models import (
     APIError,
     ApiErrorType,
@@ -10,11 +19,19 @@ from .models import (
 )
 from .utils import poll_for_status
 
-__version__ = "0.4.2"
+__version__ = "1.0.0"
 __all__ = [
     "SchedulerClient",
     "ManagementClient",
+    "OpenQuantumClient",
+    "ClientCredentials",
+    "ClientCredentialsAuth",
+    "resolve_env_credentials",
     "poll_for_status",
+    "OpenQuantumError",
+    "AuthenticationError",
+    "CircuitValidationError",
+    "JobError",
     "APIError",
     "ApiErrorType",
     "TermsOfUseRequiredError",

{openquantum_sdk-0.4.2 → openquantum_sdk-1.0.0}/openquantum_sdk/__main__.py

@@ -1,48 +1,38 @@
 #!/usr/bin/env python
 """CLI entry point for running the full job example."""
 import sys
-import os
 import json
 import argparse
 import requests
 from .auth import ClientCredentials, ClientCredentialsAuth
 from .clients import SchedulerClient, ManagementClient, JobSubmissionConfig
+from .credentials import resolve_env_credentials
 from .models import APIError, TermsOfUseRequiredError, EmailVerificationRequiredError
 
 
-def load_creds_from_file(path: str) -> ClientCredentials:
-    with open(path, "r", encoding="utf-8") as f:
-        data = json.load(f)
-    try:
-        return ClientCredentials(client_id=data["client_id"], client_secret=data["client_secret"])
-    except KeyError as e:
-        raise ValueError(f"SDK key file missing field: {e}")
-
-
 def resolve_credentials(args: argparse.Namespace) -> ClientCredentials:
-    # 1) explicit file flag
-    if args.sdk_key:
-        return load_creds_from_file(args.sdk_key)
-
-    # 2) env var file path
-    sdk_key_env = os.getenv("OPENQUANTUM_SDK_KEY")
-    if sdk_key_env and os.path.exists(sdk_key_env):
-        return load_creds_from_file(sdk_key_env)
-
-    # 3) direct args
-    if args.client_id and args.client_secret:
-        return ClientCredentials(client_id=args.client_id, client_secret=args.client_secret)
-
-    # 4) env direct
-    env_id = os.getenv("OPENQUANTUM_CLIENT_ID")
-    env_secret = os.getenv("OPENQUANTUM_CLIENT_SECRET")
-    if env_id and env_secret:
-        return ClientCredentials(client_id=env_id, client_secret=env_secret)
-
-    raise SystemExit(
-        "Missing credentials. Provide --sdk-key <file.json> or --client-id/--client-secret "
-        "or set OPENQUANTUM_SDK_KEY or OPENQUANTUM_CLIENT_ID/OPENQUANTUM_CLIENT_SECRET."
-    )
+    """Resolve client credentials via the shared core resolver.
+
+    The ``--sdk-key`` flag takes precedence over ``--client-id`` /
+    ``--client-secret``; both fall back to the environment.
+    """
+    # Honor the --sdk-key flag ahead of direct client id/secret args.
+    client_id = None if args.sdk_key else args.client_id
+    client_secret = None if args.sdk_key else args.client_secret
+    try:
+        _token, creds = resolve_env_credentials(
+            client_id=client_id,
+            client_secret=client_secret,
+            sdk_key_path=args.sdk_key,
+            require=True,
+        )
+    except ValueError as e:
+        raise SystemExit(str(e))
+    if creds is None:
+        raise SystemExit(
+            "The SDK CLI requires client credentials (SDK key), not a token."
+        )
+    return creds
 
 
 def build_arg_parser() -> argparse.ArgumentParser:

openquantum_sdk-1.0.0/openquantum_sdk/accounts.py

@@ -0,0 +1,257 @@
+"""Account persistence for the Open Quantum SDK.
+
+Stores named authentication accounts (bearer tokens or OAuth2 client
+credentials) in a JSON file at a platform-appropriate location, with secrets
+kept in the system keyring when one is available. This logic is
+framework-agnostic and is shared by every SDK surface (core client, Qiskit,
+PennyLane, Qrisp, CLI).
+
+The on-disk format and keyring key scheme are intentionally stable: a file
+written by an older release remains readable here.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Any, Dict, Optional
+
+from openquantum_sdk.auth import ClientCredentials
+
+DEFAULT_KEYCLOAK_BASE = "https://id.openquantum.com"
+DEFAULT_REALM = "platform"
+DEFAULT_SCHEDULER_URL = "https://scheduler.openquantum.com"
+DEFAULT_MANAGEMENT_URL = "https://management.openquantum.com"
+
+_KEYRING_SERVICE = "openquantum"
+
+
+def accounts_path(filename: Optional[str] = None) -> Path:
+    """Resolve the accounts file path.
+
+    Order of precedence: explicit ``filename`` → ``OPENQUANTUM_CONFIG_DIR`` →
+    the platform user config dir → ``~/.openquantum/accounts.json``.
+    """
+    if filename:
+        return Path(filename).expanduser()
+    cfg_dir = os.getenv("OPENQUANTUM_CONFIG_DIR")
+    if cfg_dir:
+        return Path(cfg_dir).expanduser() / "accounts.json"
+    try:
+        from platformdirs import PlatformDirs
+
+        d = PlatformDirs(appname="OpenQuantum", appauthor=False)
+        return Path(d.user_config_dir) / "accounts.json"
+    except Exception:
+        return Path(os.path.expanduser("~/.openquantum/accounts.json"))
+
+
+def _ensure_cfg_dir(path: Path) -> None:
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    except Exception:
+        pass
+
+
+def save_account(
+    *,
+    name: str = "default",
+    token: Optional[str] = None,
+    creds: Optional[ClientCredentials] = None,
+    keycloak_base: str = DEFAULT_KEYCLOAK_BASE,
+    realm: str = DEFAULT_REALM,
+    scheduler_url: str = DEFAULT_SCHEDULER_URL,
+    management_url: str = DEFAULT_MANAGEMENT_URL,
+    filename: Optional[str] = None,
+    overwrite: bool = True,
+    use_keyring: bool = True,
+) -> None:
+    """Persist account credentials to disk for later reuse.
+
+    Secrets (tokens, client secrets) are stored in the system keyring when
+    available; otherwise they are written to the JSON file directly.
+
+    Raises:
+        ValueError: If both ``token`` and ``creds`` are provided, or if
+            ``overwrite`` is ``False`` and the account already exists.
+    """
+    if token and creds:
+        raise ValueError("Provide either 'token' or 'creds', not both.")
+    path = accounts_path(filename)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data: Dict[str, Any] = {}
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except Exception:
+            if not overwrite:
+                raise
+            data = {}
+    if not overwrite and name in data:
+        raise ValueError(
+            f"Account '{name}' already exists. Set overwrite=True to replace."
+        )
+    entry: Dict[str, Any] = {
+        "auth_mode": "token" if token else "client_credentials",
+        "token": token,
+        "creds": (
+            {"client_id": creds.client_id, "client_secret": creds.client_secret}
+            if creds
+            else None
+        ),
+        "keycloak_base": keycloak_base,
+        "realm": realm,
+        "scheduler_url": scheduler_url,
+        "management_url": management_url,
+    }
+    if use_keyring:
+        try:
+            import keyring
+
+            if token:
+                keyring.set_password(_KEYRING_SERVICE, f"{name}:token", token)
+                entry["token"] = None
+            if creds and creds.client_secret:
+                keyring.set_password(
+                    _KEYRING_SERVICE, f"{name}:client_secret", creds.client_secret
+                )
+                entry["creds"] = {
+                    "client_id": creds.client_id,
+                    "client_secret": None,
+                }
+            entry["keyring"] = True
+        except Exception:
+            entry.setdefault("keyring", False)
+    data[name] = entry
+
+    tmp_txt = json.dumps(data, indent=2)
+    _ensure_cfg_dir(path)
+    with NamedTemporaryFile(
+        "w", delete=False, encoding="utf-8", dir=str(path.parent)
+    ) as tmp:
+        tmp.write(tmp_txt)
+        tmp.flush()
+        os.fsync(tmp.fileno())
+        tmp_path = Path(tmp.name)
+    tmp_path.replace(path)
+    try:
+        os.chmod(path, 0o600)
+    except Exception:
+        pass
+
+
+def saved_accounts(*, filename: Optional[str] = None) -> Dict[str, Any]:
+    """Return all saved accounts with secrets masked.
+
+    Tokens and client secrets are truncated so that only the first and last
+    few characters remain visible. Returns an empty dict if no accounts file
+    exists or it cannot be parsed.
+    """
+    path = accounts_path(filename)
+    if not path.exists():
+        return {}
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+        masked: Dict[str, Any] = {}
+        for k, v in raw.items():
+            v = dict(v)
+            tok = v.get("token")
+            if tok:
+                v["token"] = tok[:6] + "…" + tok[-4:]
+            creds = v.get("creds") or {}
+            if creds.get("client_secret"):
+                cs = creds["client_secret"]
+                creds["client_secret"] = cs[:4] + "…" + cs[-4:]
+            v["creds"] = creds
+            masked[k] = v
+        return masked
+    except Exception:
+        return {}
+
+
+def delete_account(*, name: str = "default", filename: Optional[str] = None) -> bool:
+    """Delete a saved account by name.
+
+    Returns ``True`` if the account was found and deleted, ``False`` otherwise.
+    """
+    path = accounts_path(filename)
+    if not path.exists():
+        return False
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return False
+    if name not in data:
+        return False
+    try:
+        import keyring
+
+        keyring.delete_password(_KEYRING_SERVICE, f"{name}:token")
+        keyring.delete_password(_KEYRING_SERVICE, f"{name}:client_secret")
+    except Exception:
+        pass
+    del data[name]
+    path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    return True
+
+
+def load_account(
+    name: str = "default", *, filename: Optional[str] = None
+) -> Optional[Dict[str, Any]]:
+    """Load a saved account and resolve its secrets from the keyring.
+
+    Returns a dict with keys ``auth_mode``, ``token`` (or ``None``), ``creds``
+    (a :class:`ClientCredentials` or ``None``), ``keycloak_base``, ``realm``,
+    ``scheduler_url``, and ``management_url``. Returns ``None`` if the file or
+    the named account does not exist.
+    """
+    path = accounts_path(filename)
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    if name not in data:
+        return None
+    entry = data[name]
+    kr = bool(entry.get("keyring", False))
+
+    token: Optional[str] = None
+    creds: Optional[ClientCredentials] = None
+    if entry.get("auth_mode") == "token":
+        token = entry.get("token")
+        if (not token) and kr:
+            try:
+                import keyring
+
+                token = keyring.get_password(_KEYRING_SERVICE, f"{name}:token")
+            except Exception:
+                pass
+    else:
+        c = entry.get("creds") or {}
+        if c.get("client_id"):
+            secret = c.get("client_secret") or ""
+            if (not secret) and kr:
+                try:
+                    import keyring
+
+                    maybe = keyring.get_password(
+                        _KEYRING_SERVICE, f"{name}:client_secret"
+                    )
+                    secret = maybe or secret
+                except Exception:
+                    pass
+            creds = ClientCredentials(client_id=c.get("client_id"), client_secret=secret)
+
+    return {
+        "auth_mode": entry.get("auth_mode"),
+        "token": token,
+        "creds": creds,
+        "keycloak_base": entry.get("keycloak_base", DEFAULT_KEYCLOAK_BASE),
+        "realm": entry.get("realm", DEFAULT_REALM),
+        "scheduler_url": entry.get("scheduler_url", DEFAULT_SCHEDULER_URL),
+        "management_url": entry.get("management_url", DEFAULT_MANAGEMENT_URL),
+    }