plexus-python 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

plexus/__init__.py

@@ -1,31 +1,14 @@
 """
-Plexus Agent - Send sensor data to Plexus in one line of code.
+Plexus — thin Python SDK for sending telemetry to the Plexus gateway.
 
-Basic Usage:
     from plexus import Plexus
 
-    px = Plexus()
+    px = Plexus(api_key="plx_xxx", source_id="device-001")
     px.send("temperature", 72.5)
-
-With Sensors (pip install plexus-python[sensors]):
-    from plexus import Plexus
-    from plexus.sensors import SensorHub, MPU6050, BME280
-
-    hub = SensorHub()
-    hub.add(MPU6050(sample_rate=100))
-    hub.add(BME280(sample_rate=1))
-    hub.run(Plexus())
-
-Auto-Detection:
-    from plexus import Plexus
-    from plexus.sensors import auto_sensors
-
-    hub = auto_sensors()  # Finds all connected sensors
-    hub.run(Plexus())
 """
 
 from plexus.client import Plexus
-from plexus.config import load_config, save_config
+from plexus.ws import WebSocketTransport
 
-__version__ = "0.1.0"
-__all__ = ["Plexus", "load_config", "save_config"]
+__version__ = "0.3.0"
+__all__ = ["Plexus", "WebSocketTransport"]

plexus/client.py

@@ -48,8 +48,8 @@ from plexus.config import (
     get_api_key,
     get_endpoint,
     get_gateway_url,
+    get_gateway_ws_url,
     get_source_id,
-    require_login,
 )
 logger = logging.getLogger(__name__)
 
@@ -96,12 +96,15 @@ class Plexus:
         max_buffer_size: int = 10000,
         persistent_buffer: bool = False,
         buffer_path: Optional[str] = None,
+        transport: str = "ws",
+        ws_url: Optional[str] = None,
     ):
         self.api_key = api_key or get_api_key()
-
-        # Require login if no API key provided
         if not self.api_key:
-            require_login()
+            raise ValueError(
+                "No API key. Pass api_key=... or set PLEXUS_API_KEY. "
+                "Get a key at app.plexus.company/devices."
+            )
 
         self.endpoint = (endpoint or get_endpoint()).rstrip("/")
         self.gateway_url = get_gateway_url()
@@ -114,6 +117,12 @@ class Plexus:
         self._session: Optional[requests.Session] = None
         self._store_frames: bool = False
 
+        if transport not in ("ws", "http"):
+            raise ValueError(f"transport must be 'ws' or 'http', got {transport!r}")
+        self.transport = transport
+        self._ws_url = (ws_url or get_gateway_ws_url())
+        self._ws = None  # lazily constructed in _ensure_ws()
+
         # Pluggable buffer backend for failed sends
         if persistent_buffer:
             self._buffer: BufferBackend = SqliteBuffer(
@@ -254,12 +263,54 @@ class Plexus:
         data_points = [self._make_point(m, v, ts, tags) for m, v in points]
         return self._send_points(data_points)
 
+    def _ensure_ws(self):
+        """Lazily construct and start the WebSocket transport."""
+        if self._ws is not None:
+            return self._ws
+        from plexus.ws import WebSocketTransport
+        from plexus import __version__
+        self._ws = WebSocketTransport(
+            api_key=self.api_key,
+            source_id=self.source_id,
+            ws_url=self._ws_url,
+            agent_version=__version__,
+        )
+        self._ws.start()
+        return self._ws
+
+    def on_command(
+        self,
+        name: str,
+        handler,
+        *,
+        description: Optional[str] = None,
+        params: Optional[List[Dict[str, Any]]] = None,
+    ) -> None:
+        """Register a command handler (WebSocket transport only).
+
+        The handler is called as `handler(command_name, params_dict)` and may
+        return a dict (→ `result`) or raise (→ `error`). An `ack` is sent
+        automatically before the handler runs.
+
+        Must be called before the first send() so the command is advertised
+        in the auth frame.
+        """
+        if self.transport != "ws":
+            raise PlexusError("on_command requires transport='ws'")
+        ws = self._ensure_ws()
+        ws.register_command(name, handler, description=description, params=params)
+
     def _send_points(self, points: List[Dict[str, Any]]) -> bool:
-        """Send data points to the API with retry and buffering.
+        """Send data points to the gateway with retry and buffering.
 
-        Retry behavior:
-        - Retries on: Timeout, ConnectionError, HTTP 429 (rate limit), HTTP 5xx
-        - No retry on: HTTP 401/403 (auth errors), HTTP 400/422 (bad request)
+        Path:
+        - transport='ws': try the WebSocket first; if not yet authenticated or
+          the socket fails, fall through to the HTTP path so points still land.
+        - transport='http': always POST /ingest with retries.
+
+        Retry behavior (HTTP path):
+        - Retries on: Timeout, ConnectionError, HTTP 429, HTTP 5xx
+        - No retry on: HTTP 401/403 (auth), HTTP 400/422 (bad request)
         - After max retries: buffers points locally for next send attempt
         """
         if not self.api_key:
@@ -270,6 +321,18 @@ class Plexus:
         # Include any previously buffered points
         all_points = self._get_buffered_points() + points
 
+        # Preferred path: WebSocket.
+        if self.transport == "ws":
+            ws = self._ensure_ws()
+            # Brief wait on first call so startup races don't dump every point
+            # into the HTTP fallback path.
+            if not ws.is_authenticated:
+                ws.wait_authenticated(timeout=min(self.timeout, 5.0))
+            if ws.send_points(all_points):
+                self._clear_buffer()
+                return True
+            # Socket unavailable → fall through to HTTP.
+
         url = f"{self.gateway_url}/ingest"
         last_error: Optional[Exception] = None
 
@@ -451,6 +514,9 @@ class Plexus:
 
     def close(self):
         """Close the client and release resources."""
+        if self._ws is not None:
+            self._ws.stop()
+            self._ws = None
         if self._session:
             self._session.close()
             self._session = None

plexus/config.py

@@ -50,15 +50,12 @@ CONFIG_FILE = CONFIG_DIR / "config.json"
 
 PLEXUS_ENDPOINT = "https://app.plexus.company"
 PLEXUS_GATEWAY_URL = "https://plexus-gateway.fly.dev"
+PLEXUS_GATEWAY_WS_URL = "wss://plexus-gateway.fly.dev"
 
 DEFAULT_CONFIG = {
     "api_key": None,
     "source_id": None,
-    "org_id": None,
-    "source_name": None,
-    "endpoint": None,
     "persistent_buffer": True,
-    "sensors": None,
 }
 
 def get_config_path() -> Path:
@@ -117,7 +114,7 @@ def get_endpoint() -> str:
 
 
 def get_gateway_url() -> str:
-    """Get the ingest gateway base URL (POST /ingest, GET /ws/device)."""
+    """Get the ingest gateway base URL (POST /ingest)."""
     env_gateway = os.environ.get("PLEXUS_GATEWAY_URL")
     if env_gateway:
         return env_gateway.rstrip("/")
@@ -125,6 +122,15 @@ def get_gateway_url() -> str:
     return (config.get("gateway_url") or PLEXUS_GATEWAY_URL).rstrip("/")
 
 
+def get_gateway_ws_url() -> str:
+    """Get the gateway WebSocket base URL (/ws/device)."""
+    env_ws = os.environ.get("PLEXUS_GATEWAY_WS_URL")
+    if env_ws:
+        return env_ws.rstrip("/")
+    config = load_config()
+    return (config.get("gateway_ws_url") or PLEXUS_GATEWAY_WS_URL).rstrip("/")
+
+
 def get_source_id() -> Optional[str]:
     """Get the source ID, generating one if not set."""
     config = load_config()
@@ -139,30 +145,6 @@ def get_source_id() -> Optional[str]:
     return source_id
 
 
-def get_org_id() -> Optional[str]:
-    """Get the organization ID from config or environment variable."""
-    # Environment variable takes precedence
-    env_org = os.environ.get("PLEXUS_ORG_ID")
-    if env_org:
-        return env_org
-
-    config = load_config()
-    return config.get("org_id")
-
-
-def is_logged_in() -> bool:
-    """Check if device is authenticated (has API key)."""
-    return get_api_key() is not None
-
-
-def require_login() -> None:
-    """Raise an error if not logged in."""
-    if not is_logged_in():
-        raise RuntimeError(
-            "Not logged in. Run 'plexus start' to connect your account."
-        )
-
-
 def get_persistent_buffer() -> bool:
     """Get persistent buffer setting. Default True (store-and-forward enabled)."""
     config = load_config()

plexus/ws.py

@@ -0,0 +1,344 @@
+"""
+WebSocket transport for the Plexus Python SDK.
+
+Wire-compatible with the C SDK (`plexus_ws.c`). Targets the gateway's
+`/ws/device` endpoint and exchanges the same JSON frames:
+
+    client → {"type": "device_auth", "api_key": ..., "source_id": ...,
+              "platform": "python-sdk", "agent_version": ..., "commands": [...]}
+    server → {"type": "authenticated", "source_id": ...}
+    client → {"type": "telemetry", "points": [...]}
+    client → {"type": "heartbeat", "source_id": ..., "agent_version": ...}   # every 30s
+    server → {"type": "typed_command", "id": ..., "command": ..., "params": {...}}
+    client → {"type": "command_result", "id": ..., "command": ..., "event": "ack"}
+    client → {"type": "command_result", "id": ..., "command": ...,
+              "event": "result" | "error", "result": {...} | "error": "..."}
+
+Runs the read loop on a background daemon thread so callers can stay sync.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import random
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+
+try:
+    import websocket  # websocket-client
+except ImportError as e:  # pragma: no cover - import-time failure is obvious
+    raise ImportError(
+        "WebSocket transport requires 'websocket-client'. "
+        "Install with: pip install websocket-client"
+    ) from e
+
+logger = logging.getLogger(__name__)
+
+AUTH_TIMEOUT_S = 10.0
+HEARTBEAT_INTERVAL_S = 30.0
+BACKOFF_BASE_S = 1.0
+BACKOFF_MAX_S = 60.0
+
+CommandHandler = Callable[[str, Dict[str, Any]], Optional[Dict[str, Any]]]
+
+
+@dataclass
+class _RegisteredCommand:
+    name: str
+    handler: CommandHandler
+    description: Optional[str] = None
+    params: List[Dict[str, Any]] = field(default_factory=list)
+
+    def to_manifest(self) -> Dict[str, Any]:
+        m: Dict[str, Any] = {"name": self.name}
+        if self.description:
+            m["description"] = self.description
+        if self.params:
+            m["params"] = self.params
+        return m
+
+
+class WebSocketTransport:
+    """Background WebSocket connection to the Plexus gateway.
+
+    Lifecycle:
+        t = WebSocketTransport(api_key, source_id, ws_url)
+        t.start()
+        t.wait_authenticated(timeout=5)
+        t.send_points([...])
+        t.stop()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        source_id: str,
+        ws_url: str,
+        *,
+        agent_version: str = "0.0.0",
+        platform: str = "python-sdk",
+        auto_reconnect: bool = True,
+    ):
+        if not api_key:
+            raise ValueError("api_key required")
+        if not source_id:
+            raise ValueError("source_id required")
+
+        self.api_key = api_key
+        self.source_id = source_id
+        self.ws_url = _ensure_device_path(ws_url)
+        self.agent_version = agent_version
+        self.platform = platform
+        self.auto_reconnect = auto_reconnect
+
+        self._commands: Dict[str, _RegisteredCommand] = {}
+        self._ws: Optional[websocket.WebSocket] = None
+        self._ws_lock = threading.Lock()
+        self._authenticated = threading.Event()
+        self._stop = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+        self._backoff_attempt = 0
+
+    # ------------------------------------------------------------------ public
+
+    def register_command(
+        self,
+        name: str,
+        handler: CommandHandler,
+        *,
+        description: Optional[str] = None,
+        params: Optional[List[Dict[str, Any]]] = None,
+    ) -> None:
+        """Register a command handler. Must be called before start() to be
+        advertised in the auth frame."""
+        self._commands[name] = _RegisteredCommand(
+            name=name, handler=handler, description=description, params=params or []
+        )
+
+    def start(self) -> None:
+        if self._thread and self._thread.is_alive():
+            return
+        self._stop.clear()
+        self._thread = threading.Thread(
+            target=self._run, name="plexus-ws", daemon=True
+        )
+        self._thread.start()
+
+    def stop(self, timeout: float = 2.0) -> None:
+        self._stop.set()
+        with self._ws_lock:
+            ws = self._ws
+        if ws is not None:
+            try:
+                ws.close()
+            except Exception:  # pragma: no cover
+                pass
+        if self._thread:
+            self._thread.join(timeout=timeout)
+
+    def wait_authenticated(self, timeout: float = AUTH_TIMEOUT_S) -> bool:
+        return self._authenticated.wait(timeout=timeout)
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._authenticated.is_set()
+
+    def send_points(self, points: List[Dict[str, Any]]) -> bool:
+        """Send a telemetry frame. Returns False if the socket is not
+        authenticated — caller is expected to fall back to HTTP."""
+        if not points:
+            return True
+        if not self._authenticated.is_set():
+            return False
+        frame = {"type": "telemetry", "points": points}
+        return self._send_frame(frame)
+
+    # ------------------------------------------------------------------ thread
+
+    def _run(self) -> None:
+        while not self._stop.is_set():
+            try:
+                self._connect_and_serve()
+            except Exception as e:
+                logger.warning("plexus ws loop error: %s", e)
+            finally:
+                self._authenticated.clear()
+                with self._ws_lock:
+                    self._ws = None
+
+            if not self.auto_reconnect or self._stop.is_set():
+                break
+
+            delay = _backoff_delay(self._backoff_attempt)
+            self._backoff_attempt = min(self._backoff_attempt + 1, 10)
+            logger.info("plexus ws reconnect in %.1fs", delay)
+            if self._stop.wait(timeout=delay):
+                break
+
+    def _connect_and_serve(self) -> None:
+        ws = websocket.create_connection(self.ws_url, timeout=AUTH_TIMEOUT_S)
+        with self._ws_lock:
+            self._ws = ws
+
+        # 1. Send device_auth
+        auth = {
+            "type": "device_auth",
+            "api_key": self.api_key,
+            "source_id": self.source_id,
+            "platform": self.platform,
+            "agent_version": self.agent_version,
+        }
+        if self._commands:
+            auth["commands"] = [c.to_manifest() for c in self._commands.values()]
+        ws.send(json.dumps(auth))
+
+        # 2. Wait for authenticated
+        ws.settimeout(AUTH_TIMEOUT_S)
+        try:
+            raw = ws.recv()
+        except websocket.WebSocketTimeoutException as e:
+            raise TimeoutError("auth timeout") from e
+
+        msg = _safe_json(raw)
+        if msg.get("type") != "authenticated":
+            raise RuntimeError(f"auth failed: {msg}")
+
+        self._authenticated.set()
+        self._backoff_attempt = 0
+        logger.info("plexus ws authenticated as %s", self.source_id)
+
+        # 3. Read loop with heartbeat pump
+        ws.settimeout(1.0)
+        last_heartbeat = time.monotonic()
+        while not self._stop.is_set():
+            now = time.monotonic()
+            if now - last_heartbeat >= HEARTBEAT_INTERVAL_S:
+                self._send_frame({
+                    "type": "heartbeat",
+                    "source_id": self.source_id,
+                    "agent_version": self.agent_version,
+                })
+                last_heartbeat = now
+
+            try:
+                raw = ws.recv()
+            except websocket.WebSocketTimeoutException:
+                continue
+            except (websocket.WebSocketConnectionClosedException, OSError):
+                logger.info("plexus ws closed")
+                return
+
+            if not raw:
+                continue
+            self._dispatch(_safe_json(raw))
+
+    def _dispatch(self, msg: Dict[str, Any]) -> None:
+        mtype = msg.get("type")
+        if mtype == "typed_command":
+            self._handle_command(msg)
+        elif mtype == "error":
+            logger.warning("plexus ws server error: %s", msg.get("detail") or msg)
+        # ignore unknown types — forward-compat
+
+    def _handle_command(self, msg: Dict[str, Any]) -> None:
+        cmd_id = msg.get("id") or ""
+        command = msg.get("command") or ""
+        params = msg.get("params") or {}
+
+        # Ack immediately (matches C SDK: plexus_ws.c:275-280)
+        self._send_frame({
+            "type": "command_result",
+            "id": cmd_id,
+            "command": command,
+            "event": "ack",
+        })
+
+        reg = self._commands.get(command)
+        if reg is None:
+            self._send_frame({
+                "type": "command_result",
+                "id": cmd_id,
+                "command": command,
+                "event": "error",
+                "error": f"unknown command: {command}",
+            })
+            return
+
+        # Run the handler off the read-loop thread so a slow handler doesn't
+        # block heartbeats or other inbound frames.
+        threading.Thread(
+            target=self._run_handler,
+            args=(reg, cmd_id, command, params),
+            daemon=True,
+        ).start()
+
+    def _run_handler(
+        self,
+        reg: _RegisteredCommand,
+        cmd_id: str,
+        command: str,
+        params: Dict[str, Any],
+    ) -> None:
+        try:
+            result = reg.handler(command, params)
+        except Exception as e:
+            self._send_frame({
+                "type": "command_result",
+                "id": cmd_id,
+                "command": command,
+                "event": "error",
+                "error": str(e),
+            })
+            return
+        self._send_frame({
+            "type": "command_result",
+            "id": cmd_id,
+            "command": command,
+            "event": "result",
+            "result": result if result is not None else {},
+        })
+
+    def _send_frame(self, frame: Dict[str, Any]) -> bool:
+        with self._ws_lock:
+            ws = self._ws
+        if ws is None:
+            return False
+        try:
+            ws.send(json.dumps(frame))
+            return True
+        except Exception as e:
+            logger.debug("plexus ws send failed: %s", e)
+            return False
+
+
+# --------------------------------------------------------------------- helpers
+
+
+def _ensure_device_path(url: str) -> str:
+    url = url.rstrip("/")
+    if url.endswith("/ws/device"):
+        return url
+    return url + "/ws/device"
+
+
+def _safe_json(raw: Any) -> Dict[str, Any]:
+    if isinstance(raw, (bytes, bytearray)):
+        raw = raw.decode("utf-8", errors="replace")
+    if not isinstance(raw, str):
+        return {}
+    try:
+        obj = json.loads(raw)
+    except json.JSONDecodeError:
+        return {}
+    return obj if isinstance(obj, dict) else {}
+
+
+def _backoff_delay(attempt: int) -> float:
+    """Exponential backoff with ±25% jitter, capped at BACKOFF_MAX_S.
+    Matches plexus_ws.c:44-52."""
+    base = min(BACKOFF_BASE_S * (2 ** attempt), BACKOFF_MAX_S)
+    jitter = base * 0.25 * (2 * random.random() - 1)
+    return max(0.1, base + jitter)