qdsv-bridge 0.1.0__tar.gz

qdsv_bridge-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+.env

qdsv_bridge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QDSV / Qruba
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qdsv_bridge-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: qdsv-bridge
+Version: 0.1.0
+Summary: Lightweight Python client for QDSV Bridge, a controlled semantic-to-IR/oracle/circuit compiler.
+Project-URL: Homepage, https://qdsv.cloud
+Project-URL: Documentation, https://qdsv.cloud/#bridge
+Project-URL: Source, https://github.com/qdsvquantum-afk/qdsv-bridge
+Author: QDSV / Qruba
+License-Expression: MIT
+License-File: LICENSE
+Keywords: circuit,qasm,qdsv,quantum,sdk,semantic-computation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.31
+Description-Content-Type: text/markdown
+
+# QDSV Bridge Developer Preview
+
+Lightweight Python SDK for **QDSV Bridge**, a controlled semantic compiler that turns supported problem-family specifications into QDSV IR, oracle specs, QASM blueprints, or integration-ready circuit scaffolds.
+
+QDSV Bridge is not a free circuit generator. It is a restricted semantic-to-circuit bridge for supported problem families.
+
+```text
+problem family spec
+-> family ontology validation
+-> semantic ProblemSpec / IR
+-> oracle specification
+-> materialization policy
+-> QASM / Qiskit blueprint when the target requires circuits
+```
+
+The SDK is a client only. It does not include the private QDSV Runtime, CAP, backend selector, lowering internals, QuEST/Aer/IBM adapters, or advanced orchestration.
+
+```bash
+pip install qdsv-bridge
+```
+
+## Why This Exists
+
+Traditional quantum workflows often start by asking users to choose a circuit, encoding, ansatz, or measurement pattern. That can force the data to adapt to a circuit.
+
+QDSV Bridge starts from a controlled semantic family. The family defines what kind of problem is allowed, what concepts belong to it, what patterns are excluded, and what evidence must be produced. Circuit materialization is only one possible export when another platform requires it.
+
+For example, in signal classification:
+
+```text
+prepared signals
+-> semantic_signal_classification
+-> preserve signal geometry
+-> oracle / IR / QASM blueprint
+```
+
+This is designed to avoid a fixed pattern such as:
+
+```text
+forced reduction -> angle encoding -> fixed ansatz -> fixed measurement
+```
+
+## Quick Start
+
+```python
+from qdsv_bridge import QDSVBridgeClient
+
+client = QDSVBridgeClient()
+
+spec = {
+    "family": "semantic_signal_classification",
+    "state_space": {
+        "kind": "finite_candidates",
+        "candidate_count": 300,
+        "candidate_id": "eeg_window",
+    },
+    "signals": [
+        "dwt_cD3_std_score",
+        "std_score",
+        "activity_score",
+        "energy_score",
+        "dwt_cD2_std_score",
+        "complexity_score",
+    ],
+    "goal": {
+        "kind": "binary_marking",
+        "positive_state": "ictal",
+    },
+    "materialization_policy": {
+        "preserve_signal_geometry": True,
+        "avoid_fixed_ansatz": True,
+        "avoid_forced_dimensionality_reduction": True,
+        "report_information_loss": True,
+    },
+    "target": {
+        "format": "qasm3",
+        "backend_family": "qiskit",
+    },
+    "limits": {
+        "max_qubits": 10,
+        "max_depth": 300,
+    },
+}
+
+result = client.export(spec)
+
+print(result["status"])
+print(result["semantic_preservation_report"])
+print(result["artifact"]["content"])
+```
+
+## Public Endpoints
+
+The SDK calls the QDSV API:
+
+- `GET /api/bridge/families`
+- `POST /api/bridge/validate`
+- `POST /api/bridge/compile`
+- `POST /api/bridge/explain`
+- `POST /api/bridge/export`
+
+Default cloud endpoint:
+
+```python
+client = QDSVBridgeClient(api_url="https://api.qdsv.cloud/api")
+```
+
+Local/private Docker endpoint:
+
+```python
+client = QDSVBridgeClient.local()
+```
+
+## Supported Families
+
+Developer Preview families:
+
+- `semantic_signal_classification`
+- `predicate_marking`
+- `state_similarity`
+- `combinatorial_relation`
+- `distribution_sampling`
+
+Each family has:
+
+- ontology boundary;
+- allowed state-space kinds;
+- allowed goal kinds;
+- allowed semantic operations;
+- excluded patterns;
+- public limits;
+- export targets;
+- evidence / digest contract.
+
+## What It Exports
+
+Depending on `target.format`, QDSV Bridge can export:
+
+- `problem_spec`
+- `ir`
+- `oracle_spec`
+- `qasm2`
+- `qasm3`
+- `qiskit_blueprint`
+
+QASM outputs are bridge blueprints with explicit semantic oracle insertion points and QDSV digests. External platforms should inspect the returned preservation report, qubit/depth limits and oracle digest before executing or optimizing the generated artifact.
+
+## Important Boundaries
+
+QDSV Bridge does not expose:
+
+- QDSV Runtime internals;
+- CAP internals;
+- backend selection heuristics;
+- private QuEST/Aer/IBM adapters;
+- native lowering internals;
+- unrestricted circuit generation;
+- arbitrary Python execution;
+- user-supplied free circuits as family contracts.
+
+The product principle is:
+
+```text
+controlled semantic family
+-> flexible materialization
+-> auditable export
+```
+
+Not:
+
+```text
+any input
+-> arbitrary circuit
+```
+
+## Open SDK, Private Runtime
+
+This repository is open-core:
+
+- **Open under MIT:** Python client SDK, examples, docs and tests.
+- **Not included:** QDSV Runtime, ontology compiler internals, CAP, lowering, advanced materialization, backend adapters, private endpoints, secrets or production configuration.
+
+QDSV, QIntent and Qruba names and marks are project marks of their respective owners. The MIT License for this repository does not grant trademark rights.

qdsv_bridge-0.1.0/README.md

@@ -0,0 +1,183 @@
+# QDSV Bridge Developer Preview
+
+Lightweight Python SDK for **QDSV Bridge**, a controlled semantic compiler that turns supported problem-family specifications into QDSV IR, oracle specs, QASM blueprints, or integration-ready circuit scaffolds.
+
+QDSV Bridge is not a free circuit generator. It is a restricted semantic-to-circuit bridge for supported problem families.
+
+```text
+problem family spec
+-> family ontology validation
+-> semantic ProblemSpec / IR
+-> oracle specification
+-> materialization policy
+-> QASM / Qiskit blueprint when the target requires circuits
+```
+
+The SDK is a client only. It does not include the private QDSV Runtime, CAP, backend selector, lowering internals, QuEST/Aer/IBM adapters, or advanced orchestration.
+
+```bash
+pip install qdsv-bridge
+```
+
+## Why This Exists
+
+Traditional quantum workflows often start by asking users to choose a circuit, encoding, ansatz, or measurement pattern. That can force the data to adapt to a circuit.
+
+QDSV Bridge starts from a controlled semantic family. The family defines what kind of problem is allowed, what concepts belong to it, what patterns are excluded, and what evidence must be produced. Circuit materialization is only one possible export when another platform requires it.
+
+For example, in signal classification:
+
+```text
+prepared signals
+-> semantic_signal_classification
+-> preserve signal geometry
+-> oracle / IR / QASM blueprint
+```
+
+This is designed to avoid a fixed pattern such as:
+
+```text
+forced reduction -> angle encoding -> fixed ansatz -> fixed measurement
+```
+
+## Quick Start
+
+```python
+from qdsv_bridge import QDSVBridgeClient
+
+client = QDSVBridgeClient()
+
+spec = {
+    "family": "semantic_signal_classification",
+    "state_space": {
+        "kind": "finite_candidates",
+        "candidate_count": 300,
+        "candidate_id": "eeg_window",
+    },
+    "signals": [
+        "dwt_cD3_std_score",
+        "std_score",
+        "activity_score",
+        "energy_score",
+        "dwt_cD2_std_score",
+        "complexity_score",
+    ],
+    "goal": {
+        "kind": "binary_marking",
+        "positive_state": "ictal",
+    },
+    "materialization_policy": {
+        "preserve_signal_geometry": True,
+        "avoid_fixed_ansatz": True,
+        "avoid_forced_dimensionality_reduction": True,
+        "report_information_loss": True,
+    },
+    "target": {
+        "format": "qasm3",
+        "backend_family": "qiskit",
+    },
+    "limits": {
+        "max_qubits": 10,
+        "max_depth": 300,
+    },
+}
+
+result = client.export(spec)
+
+print(result["status"])
+print(result["semantic_preservation_report"])
+print(result["artifact"]["content"])
+```
+
+## Public Endpoints
+
+The SDK calls the QDSV API:
+
+- `GET /api/bridge/families`
+- `POST /api/bridge/validate`
+- `POST /api/bridge/compile`
+- `POST /api/bridge/explain`
+- `POST /api/bridge/export`
+
+Default cloud endpoint:
+
+```python
+client = QDSVBridgeClient(api_url="https://api.qdsv.cloud/api")
+```
+
+Local/private Docker endpoint:
+
+```python
+client = QDSVBridgeClient.local()
+```
+
+## Supported Families
+
+Developer Preview families:
+
+- `semantic_signal_classification`
+- `predicate_marking`
+- `state_similarity`
+- `combinatorial_relation`
+- `distribution_sampling`
+
+Each family has:
+
+- ontology boundary;
+- allowed state-space kinds;
+- allowed goal kinds;
+- allowed semantic operations;
+- excluded patterns;
+- public limits;
+- export targets;
+- evidence / digest contract.
+
+## What It Exports
+
+Depending on `target.format`, QDSV Bridge can export:
+
+- `problem_spec`
+- `ir`
+- `oracle_spec`
+- `qasm2`
+- `qasm3`
+- `qiskit_blueprint`
+
+QASM outputs are bridge blueprints with explicit semantic oracle insertion points and QDSV digests. External platforms should inspect the returned preservation report, qubit/depth limits and oracle digest before executing or optimizing the generated artifact.
+
+## Important Boundaries
+
+QDSV Bridge does not expose:
+
+- QDSV Runtime internals;
+- CAP internals;
+- backend selection heuristics;
+- private QuEST/Aer/IBM adapters;
+- native lowering internals;
+- unrestricted circuit generation;
+- arbitrary Python execution;
+- user-supplied free circuits as family contracts.
+
+The product principle is:
+
+```text
+controlled semantic family
+-> flexible materialization
+-> auditable export
+```
+
+Not:
+
+```text
+any input
+-> arbitrary circuit
+```
+
+## Open SDK, Private Runtime
+
+This repository is open-core:
+
+- **Open under MIT:** Python client SDK, examples, docs and tests.
+- **Not included:** QDSV Runtime, ontology compiler internals, CAP, lowering, advanced materialization, backend adapters, private endpoints, secrets or production configuration.
+
+QDSV, QIntent and Qruba names and marks are project marks of their respective owners. The MIT License for this repository does not grant trademark rights.

qdsv_bridge-0.1.0/examples/eeg_semantic_signal_classification.py

@@ -0,0 +1,32 @@
+from qdsv_bridge import QDSVBridgeClient
+
+
+spec = {
+    "family": "semantic_signal_classification",
+    "state_space": {"kind": "finite_candidates", "candidate_count": 300, "candidate_id": "eeg_window"},
+    "signals": [
+        "dwt_cD3_std_score",
+        "std_score",
+        "activity_score",
+        "energy_score",
+        "dwt_cD2_std_score",
+        "complexity_score",
+    ],
+    "goal": {"kind": "binary_marking", "positive_state": "ictal"},
+    "materialization_policy": {
+        "preserve_signal_geometry": True,
+        "avoid_fixed_ansatz": True,
+        "avoid_forced_dimensionality_reduction": True,
+        "report_information_loss": True,
+    },
+    "target": {"format": "qasm3", "backend_family": "qiskit"},
+    "limits": {"max_qubits": 10, "max_depth": 300},
+}
+
+
+client = QDSVBridgeClient()
+result = client.export(spec)
+
+print(result["status"])
+print(result["semantic_preservation_report"])
+print(result["artifact"]["content"])

qdsv_bridge-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qdsv-bridge"
+version = "0.1.0"
+description = "Lightweight Python client for QDSV Bridge, a controlled semantic-to-IR/oracle/circuit compiler."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+  { name = "QDSV / Qruba" }
+]
+keywords = ["qdsv", "semantic-computation", "quantum", "circuit", "qasm", "sdk"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Scientific/Engineering",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "requests>=2.31",
+]
+
+[project.urls]
+Homepage = "https://qdsv.cloud"
+Documentation = "https://qdsv.cloud/#bridge"
+Source = "https://github.com/qdsvquantum-afk/qdsv-bridge"
+
+[project.scripts]
+qdsv-bridge = "qdsv_bridge.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qdsv_bridge"]

qdsv_bridge-0.1.0/src/qdsv_bridge/__init__.py

@@ -0,0 +1,4 @@
+from .client import QDSVBridgeClient
+from .exceptions import QDSVBridgeAPIError, QDSVBridgeError, QDSVBridgeHTTPError
+
+__all__ = ["QDSVBridgeClient", "QDSVBridgeError", "QDSVBridgeAPIError", "QDSVBridgeHTTPError"]

qdsv_bridge-0.1.0/src/qdsv_bridge/cli.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .client import QDSVBridgeClient
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="QDSV Bridge SDK CLI")
+    parser.add_argument("command", choices=["families", "validate", "compile", "explain", "export"])
+    parser.add_argument("spec", nargs="?", help="Path to a Semantic Circuit Spec JSON file.")
+    parser.add_argument("--api-url", default=None)
+    parser.add_argument("--local", action="store_true", help="Use http://localhost:18080/api")
+    args = parser.parse_args()
+
+    client = QDSVBridgeClient.local() if args.local else QDSVBridgeClient(api_url=args.api_url)
+    if args.command == "families":
+        print(json.dumps(client.families(), indent=2, ensure_ascii=False))
+        return
+    if not args.spec:
+        parser.error("spec JSON file is required for this command")
+    spec = json.loads(Path(args.spec).read_text(encoding="utf-8"))
+    result = getattr(client, args.command)(spec)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

qdsv_bridge-0.1.0/src/qdsv_bridge/client.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping
+
+import requests
+
+from .exceptions import QDSVBridgeAPIError, QDSVBridgeHTTPError
+
+
+DEFAULT_API_URL = "https://api.qdsv.cloud/api"
+PRIVATE_NODE_UNAVAILABLE_MESSAGE = (
+    "Private QDSV node temporarily unavailable. It may be offline, reserved for "
+    "private processing, or busy. Try again later or use QDSVBridgeClient() for "
+    "public cloud examples."
+)
+
+
+class QDSVBridgeClient:
+    """Client for QDSV Bridge public API endpoints."""
+
+    def __init__(
+        self,
+        api_url: str | None = None,
+        api_key: str | None = None,
+        *,
+        timeout: float = 30.0,
+        license_key: str | None = None,
+        sdk_name: str = "qdsv-bridge",
+    ) -> None:
+        self.api_url = self._normalize_api_url(
+            api_url or os.getenv("QDSV_BRIDGE_API_URL") or os.getenv("QDSV_API_URL") or DEFAULT_API_URL
+        )
+        self.api_key = api_key or os.getenv("QDSV_BRIDGE_API_KEY") or os.getenv("QDSV_API_KEY")
+        self.license_key = license_key or os.getenv("QDSV_LICENSE_KEY")
+        self.timeout = timeout
+        self.sdk_name = sdk_name
+        self._private_node = self._looks_like_private_node(self.api_url)
+
+    @classmethod
+    def local(
+        cls,
+        *,
+        api_url: str = "http://localhost:18080/api",
+        api_key: str | None = None,
+        timeout: float = 30.0,
+        license_key: str | None = None,
+    ) -> "QDSVBridgeClient":
+        return cls(api_url=api_url, api_key=api_key, timeout=timeout, license_key=license_key)
+
+    @staticmethod
+    def _normalize_api_url(value: str) -> str:
+        clean = str(value or "").strip().rstrip("/")
+        if not clean:
+            return DEFAULT_API_URL
+        return clean if clean.lower().endswith("/api") else f"{clean}/api"
+
+    @staticmethod
+    def _looks_like_private_node(api_url: str) -> bool:
+        clean = str(api_url or "").lower()
+        return "localhost" in clean or "127.0.0.1" in clean or "qintent-local.qdsv.cloud" in clean or "qruba.site" in clean
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"Content-Type": "application/json", "x-sdk-name": self.sdk_name}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if self.license_key:
+            headers["x-license-key"] = self.license_key
+        return headers
+
+    def _request(self, method: str, path: str, *, json: Mapping[str, Any] | None = None) -> dict[str, Any]:
+        url = f"{self.api_url}{path}"
+        kwargs: dict[str, Any] = {"headers": self._headers(), "timeout": self.timeout}
+        if json is not None:
+            kwargs["json"] = dict(json)
+        try:
+            response = requests.request(method, url, **kwargs)
+        except requests.RequestException as exc:
+            if self._private_node:
+                raise QDSVBridgeAPIError(PRIVATE_NODE_UNAVAILABLE_MESSAGE) from exc
+            raise QDSVBridgeAPIError(str(exc)) from exc
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = {"status": "ERROR", "message": response.text}
+        if not response.ok:
+            raise QDSVBridgeHTTPError(response.status_code, payload)
+        if not isinstance(payload, dict):
+            raise QDSVBridgeAPIError(f"Unexpected API response type: {type(payload).__name__}")
+        return payload
+
+    def families(self) -> dict[str, Any]:
+        return self._request("GET", "/bridge/families")
+
+    def validate(self, spec: Mapping[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/bridge/validate", json={"spec": dict(spec)})
+
+    def compile(self, spec: Mapping[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/bridge/compile", json={"spec": dict(spec)})
+
+    def explain(self, spec: Mapping[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/bridge/explain", json={"spec": dict(spec)})
+
+    def export(self, spec: Mapping[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/bridge/export", json={"spec": dict(spec)})

qdsv_bridge-0.1.0/src/qdsv_bridge/exceptions.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+class QDSVBridgeError(Exception):
+    """Base exception for the QDSV Bridge SDK."""
+
+
+class QDSVBridgeHTTPError(QDSVBridgeError):
+    """Raised when the API returns an HTTP error response."""
+
+    def __init__(self, status_code: int, payload: Any) -> None:
+        self.status_code = status_code
+        self.payload = payload
+        super().__init__(f"QDSV Bridge API HTTP {status_code}: {payload}")
+
+
+class QDSVBridgeAPIError(QDSVBridgeError):
+    """Raised when a transport error prevents calling the API."""

qdsv_bridge-0.1.0/tests/test_client.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import pytest
+import requests
+
+from qdsv_bridge import QDSVBridgeClient
+from qdsv_bridge.exceptions import QDSVBridgeAPIError, QDSVBridgeHTTPError
+
+
+def test_normalizes_api_url() -> None:
+    assert QDSVBridgeClient("https://api.qdsv.cloud").api_url == "https://api.qdsv.cloud/api"
+    assert QDSVBridgeClient("https://api.qdsv.cloud/api").api_url == "https://api.qdsv.cloud/api"
+    assert QDSVBridgeClient.local().api_url == "http://localhost:18080/api"
+
+
+def test_families_get_has_no_json_body(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = {}
+
+    class FakeResponse:
+        ok = True
+        status_code = 200
+
+        @staticmethod
+        def json():
+            return {"status": "SUCCESS", "families": {}}
+
+    def fake_request(method, url, **kwargs):
+        calls["method"] = method
+        calls["url"] = url
+        calls["kwargs"] = kwargs
+        return FakeResponse()
+
+    monkeypatch.setattr("qdsv_bridge.client.requests.request", fake_request)
+    result = QDSVBridgeClient().families()
+
+    assert result["status"] == "SUCCESS"
+    assert calls["method"] == "GET"
+    assert calls["url"].endswith("/bridge/families")
+    assert "json" not in calls["kwargs"]
+
+
+def test_export_posts_spec(monkeypatch: pytest.MonkeyPatch) -> None:
+    calls = {}
+
+    class FakeResponse:
+        ok = True
+        status_code = 200
+
+        @staticmethod
+        def json():
+            return {"status": "SUCCESS", "artifact": {"format": "qasm3"}}
+
+    def fake_request(method, url, **kwargs):
+        calls["method"] = method
+        calls["url"] = url
+        calls["kwargs"] = kwargs
+        return FakeResponse()
+
+    monkeypatch.setattr("qdsv_bridge.client.requests.request", fake_request)
+    result = QDSVBridgeClient().export({"family": "semantic_signal_classification"})
+
+    assert result["artifact"]["format"] == "qasm3"
+    assert calls["method"] == "POST"
+    assert calls["url"].endswith("/bridge/export")
+    assert calls["kwargs"]["json"]["spec"]["family"] == "semantic_signal_classification"
+
+
+def test_private_node_transport_error_is_user_friendly(monkeypatch: pytest.MonkeyPatch) -> None:
+    def fake_request(method, url, **kwargs):
+        raise requests.ConnectionError("connection refused")
+
+    monkeypatch.setattr("qdsv_bridge.client.requests.request", fake_request)
+    with pytest.raises(QDSVBridgeAPIError) as exc:
+        QDSVBridgeClient.local().families()
+
+    assert "Private QDSV node temporarily unavailable" in str(exc.value)
+
+
+def test_http_error_is_not_hidden(monkeypatch: pytest.MonkeyPatch) -> None:
+    class FakeResponse:
+        ok = False
+        status_code = 400
+
+        @staticmethod
+        def json():
+            return {"detail": {"error_code": "E_BRIDGE_UNSUPPORTED_FAMILY"}}
+
+    def fake_request(method, url, **kwargs):
+        return FakeResponse()
+
+    monkeypatch.setattr("qdsv_bridge.client.requests.request", fake_request)
+    with pytest.raises(QDSVBridgeHTTPError) as exc:
+        QDSVBridgeClient.local().families()
+
+    assert exc.value.status_code == 400
+    assert exc.value.payload["detail"]["error_code"] == "E_BRIDGE_UNSUPPORTED_FAMILY"