spanda-sdk 0.4.0__py3-none-any.whl

spanda/__init__.py

@@ -0,0 +1,5 @@
+"""Spanda SDK package alias — `from spanda import SpandaClient`."""
+
+from spanda_sdk import SpandaClient, SpandaError, TelemetryStream
+
+__all__ = ["SpandaClient", "SpandaError", "TelemetryStream"]

spanda_sdk/__init__.py

@@ -0,0 +1,7 @@
+"""Official Spanda Python SDK."""
+
+from spanda_sdk.client import SpandaClient
+from spanda_sdk.errors import SpandaError
+from spanda_sdk.stream import TelemetryStream
+
+__all__ = ["SpandaClient", "SpandaError", "TelemetryStream"]

spanda_sdk/client.py

@@ -0,0 +1,176 @@
+"""Official Spanda Python SDK — thin REST client over Control Center API v1."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+import uuid
+from typing import Any, Mapping, Optional
+
+from spanda_sdk.errors import ConnectionError, PermissionError, SpandaError, ValidationError
+from spanda_sdk.stream import TelemetryStream
+
+__all__ = ["SpandaClient", "SpandaError", "TelemetryStream"]
+
+
+class SpandaClient:
+    """REST v1 client with optional Bearer auth and correlation IDs."""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        timeout: float = 30.0,
+    ) -> None:
+        resolved_url = base_url or os.environ.get(
+            "SPANDA_CONTROL_CENTER_URL", "http://127.0.0.1:8080"
+        )
+        self.base_url = resolved_url.rstrip("/")
+        self.api_key = api_key if api_key is not None else os.environ.get("SPANDA_API_KEY")
+        self.timeout = timeout
+
+    @classmethod
+    def local(cls) -> "SpandaClient":
+        """Connect to the local Control Center."""
+        return cls()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Optional[Mapping[str, Any]] = None,
+        auth: bool = False,
+    ) -> Any:
+        url = f"{self.base_url}{path}"
+        headers = {"Accept": "application/json", "X-Correlation-ID": f"py-sdk-{uuid.uuid4().hex[:12]}"}
+        data = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            data = json.dumps(body).encode("utf-8")
+        if auth and self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                payload = resp.read().decode("utf-8")
+                if not payload:
+                    return {}
+                return json.loads(payload)
+        except urllib.error.HTTPError as exc:
+            detail = exc.read().decode("utf-8", errors="replace")
+            if exc.code in (401, 403):
+                raise PermissionError(detail, status=exc.code) from exc
+            if exc.code == 400:
+                raise ValidationError(detail, status=exc.code) from exc
+            raise SpandaError(detail, status=exc.code) from exc
+        except urllib.error.URLError as exc:
+            raise ConnectionError(str(exc.reason)) from exc
+
+    def _program_body(self, file_or_project: str) -> dict[str, str]:
+        return {"file": file_or_project}
+
+    def readiness(self, file_or_project: str) -> Any:
+        return self._request(
+            "POST", "/v1/programs/readiness", self._program_body(file_or_project)
+        )
+
+    def assure(self, file_or_project: str) -> Any:
+        return self._request(
+            "POST", "/v1/programs/assure", self._program_body(file_or_project)
+        )
+
+    def diagnose(self, trace_or_file: str) -> Any:
+        return self._request(
+            "POST", "/v1/programs/diagnose", self._program_body(trace_or_file)
+        )
+
+    def heal(self, target: str) -> Any:
+        return self._request("POST", "/v1/programs/recovery/heal", self._program_body(target))
+
+    def verify_hardware(self, project: str) -> Any:
+        return self._request(
+            "POST", "/v1/programs/verify/hardware", self._program_body(project)
+        )
+
+    def verify_capabilities(self, project: str) -> Any:
+        return self._request(
+            "POST",
+            "/v1/programs/verify/capabilities",
+            {"file": project, "traceability": True},
+        )
+
+    def list_entities(self) -> Any:
+        return self._request("GET", "/v1/entities")
+
+    def get_entity(self, entity_id: str) -> Any:
+        return self._request("GET", f"/v1/entities/{entity_id}")
+
+    def list_devices(self) -> Any:
+        return self._request("GET", "/v1/devices", auth=True)
+
+    def provision_device(self, device_id: str, body: Optional[Mapping[str, Any]] = None) -> Any:
+        return self._request(
+            "POST",
+            f"/v1/devices/{device_id}/provision",
+            body or {},
+            auth=True,
+        )
+
+    def run_simulation(self, project: str, *, execute: bool = False) -> Any:
+        return self._request(
+            "POST",
+            "/v1/programs/simulation",
+            {"file": project, "execute": execute},
+        )
+
+    def replay(
+        self,
+        trace: str,
+        *,
+        deterministic: bool = False,
+        playback: bool = False,
+    ) -> Any:
+        return self._request(
+            "POST",
+            "/v1/programs/replay",
+            {
+                "file": trace,
+                "deterministic": deterministic,
+                "playback": playback,
+            },
+        )
+
+    def get_health(self, entity_id: str) -> Any:
+        return self._request("GET", f"/v1/entities/{entity_id}/health")
+
+    def get_trust(self, entity_id: str) -> Any:
+        return self._request("GET", f"/v1/entities/{entity_id}/trust")
+
+    def get_package_trust(self, package: str, version: Optional[str] = None) -> Any:
+        path = f"/v1/trust/package?name={package}"
+        if version:
+            path += f"&version={version}"
+        return self._request("GET", path)
+
+    def health_check(self) -> Any:
+        return self._request("GET", "/v1/health")
+
+    def rpc(self, method: str, params: Optional[Mapping[str, Any]] = None) -> Any:
+        payload = self._request(
+            "POST",
+            "/v1/rpc",
+            {"method": method, "params": params or {}},
+        )
+        return payload.get("result", payload)
+
+    # Backward-compatible Control Center helpers
+    def dashboard(self) -> Any:
+        return self._request("GET", "/v1/dashboard")
+
+    def readiness_run(self, body: Optional[Mapping[str, Any]] = None) -> Any:
+        return self._request("POST", "/v1/readiness/run", body or {})
+
+    def trust_package(self, name: str, version: Optional[str] = None) -> Any:
+        return self.get_package_trust(name, version)

spanda_sdk/errors.py

@@ -0,0 +1,35 @@
+"""Structured errors for the Spanda Python SDK."""
+
+from __future__ import annotations
+
+
+class SpandaError(Exception):
+    """Base SDK error."""
+
+    def __init__(self, message: str, *, status: int | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+
+
+class ValidationError(SpandaError):
+    """Invalid request or response payload."""
+
+
+class ReadinessError(SpandaError):
+    """Readiness evaluation failed."""
+
+
+class VerificationError(SpandaError):
+    """Hardware or capability verification failed."""
+
+
+class SecurityError(SpandaError):
+    """Authentication or authorization failure."""
+
+
+class ConnectionError(SpandaError):
+    """Network or server connectivity failure."""
+
+
+class PermissionError(SpandaError):
+    """Insufficient permissions for the requested operation."""

spanda_sdk/stream.py

@@ -0,0 +1,43 @@
+"""WebSocket telemetry stream for Control Center events."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+from typing import Any, AsyncIterator, Callable, Optional
+
+
+class TelemetryStream:
+    """Async WebSocket client for `WS /v1/stream/telemetry`."""
+
+    def __init__(self, base_url: Optional[str] = None) -> None:
+        http = base_url or os.environ.get(
+            "SPANDA_CONTROL_CENTER_URL", "http://127.0.0.1:8080"
+        )
+        self.ws_url = http.replace("https://", "wss://").replace("http://", "ws://")
+        if not self.ws_url.endswith("/v1/stream/telemetry"):
+            self.ws_url = f"{self.ws_url.rstrip('/')}/v1/stream/telemetry"
+
+    async def events(self) -> AsyncIterator[dict[str, Any]]:
+        """Yield parsed JSON events from the telemetry stream."""
+        try:
+            import websockets
+        except ImportError as exc:
+            raise RuntimeError(
+                "Install stream extras: pip install 'spanda-sdk[stream]'"
+            ) from exc
+
+        async with websockets.connect(self.ws_url) as ws:
+            async for message in ws:
+                yield json.loads(message)
+
+    async def listen(self, handler: Callable[[dict[str, Any]], None]) -> None:
+        """Invoke handler for each telemetry event."""
+        async for event in self.events():
+            handler(event)
+
+
+def run_stream(handler: Callable[[dict[str, Any]], None], base_url: Optional[str] = None) -> None:
+    """Blocking helper to run an event handler loop."""
+    asyncio.run(TelemetryStream(base_url).listen(handler))

spanda_sdk-0.4.0.dist-info/METADATA

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: spanda-sdk
+Version: 0.4.0
+Summary: Official Python SDK for Spanda Control Center API v1
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: stream
+Requires-Dist: websockets>=12; extra == "stream"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: websockets>=12; extra == "dev"
+
+# Spanda Python SDK
+
+Official Python client for Spanda Control Center API v1.
+
+## Install
+
+```bash
+pip install -e sdk/python
+# WebSocket telemetry
+pip install -e "sdk/python[stream]"
+```
+
+## Quick start
+
+```python
+from spanda import SpandaClient
+
+client = SpandaClient.local()
+report = client.readiness("rover.sd")
+print(report["report"])
+```
+
+Requires Control Center running:
+
+```bash
+spanda control-center serve --program examples/robotics/rover.sd
+```
+
+## Environment
+
+| Variable | Purpose |
+|----------|---------|
+| `SPANDA_CONTROL_CENTER_URL` | API base URL (default `http://127.0.0.1:8080`) |
+| `SPANDA_API_KEY` | Bearer token for authenticated endpoints |
+
+## Documentation
+
+- [docs/sdk-python.md](../../docs/sdk-python.md)
+- [docs/control-center-api.md](../../docs/control-center-api.md)
+
+## Legacy client
+
+Enterprise ops helpers (`ControlCenterClient` for drift, OTA, SRE) remain in `packages/sdk-python`.

spanda_sdk-0.4.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+spanda/__init__.py,sha256=JugMNefsj4j3V_ESvGT_DM41Mx_-GbJGhXSln8d5wnk,199
+spanda_sdk/__init__.py,sha256=GsiGu_HpjMum6bPpm4GzbSlPwUq3gOzqzJzOBreP4lI,228
+spanda_sdk/client.py,sha256=VyvRMyxrHUv61WL5EVMuij0mxfKOGqE-dN3ejf1dQf0,6095
+spanda_sdk/errors.py,sha256=WmSmBx3GwENozxpT-98Sw5cUA84zZ11kLZn3r68AIVo,817
+spanda_sdk/stream.py,sha256=CVV6c0-UrwxXEikgopj-UG6Cu2SUNUMVGjDR4c9PNtQ,1578
+spanda_sdk-0.4.0.dist-info/METADATA,sha256=CDZYDICbb3mftYh_JE7NGhVVrkfPSIbYyDPBldK0OG4,1274
+spanda_sdk-0.4.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+spanda_sdk-0.4.0.dist-info/top_level.txt,sha256=O6u6MBJCrrAHyikzANQXI5x_OrbByshTCVdX62KgD-c,18
+spanda_sdk-0.4.0.dist-info/RECORD,,

spanda_sdk-0.4.0.dist-info/WHEEL

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

spanda_sdk-0.4.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+spanda
+spanda_sdk