plexus-python 0.5.1__tar.gz → 0.5.2__tar.gz

{plexus_python-0.5.1 → plexus_python-0.5.2}/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.5.2] - 2026-05-21 - DX hardening for hardware engineers
+
+### Fixed
+
+- Error messages now reference `plexus init` instead of the non-existent `plexus start`.
+- `close()` now attempts to flush any buffered points before tearing down the transport,
+  preventing silent data loss on graceful shutdown.
+- `persistent_buffer` default changed from `False` to `True` — store-and-forward is now
+  on by default, matching the `~/.plexus/config.json` default and the right choice for
+  field hardware. Pass `persistent_buffer=False` to opt out (e.g. in test fixtures).
+
+### Added
+
+- `send_batch()` now accepts 3-tuples `(metric, value, timestamp)` alongside the existing
+  2-tuple form. Per-point timestamps let sensors on different interrupt timers share a
+  single batch call. 2-tuples continue to use the shared `timestamp` argument.
+- `on_command()` now warns immediately via stderr if called after the WebSocket has already
+  authenticated, making the "register before first send()" ordering requirement visible
+  rather than silently broken.
+- `source_id` is validated against `^[a-z0-9][a-z0-9_-]{1,62}$` at construction time.
+  Invalid names now raise `ValueError` with a clear message instead of failing obscurely
+  at the gateway.
+
+### Changed
+
+- `_say()` / `_QUIET` consolidated into a new internal `plexus/_log.py` module.
+  Previously duplicated verbatim between `client.py` and `ws.py`.
+
 ## [0.5.1] - 2026-05-19 - Binary video frames + non-blocking send
 
 ### Performance

{plexus_python-0.5.1 → plexus_python-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.5.1
+Version: 0.5.2
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.dev
 Project-URL: Documentation, https://docs.plexus.dev

{plexus_python-0.5.1 → plexus_python-0.5.2}/examples/uv.lock

@@ -674,11 +674,11 @@ wheels = [
 
 [[package]]
 name = "urllib3"
-version = "2.6.3"
+version = "2.7.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" },
 ]
 
 [[package]]

{plexus_python-0.5.1 → plexus_python-0.5.2}/plexus/__init__.py

@@ -10,5 +10,5 @@ Plexus — thin Python SDK for sending telemetry to the Plexus gateway.
 from plexus.client import Plexus, read_mjpeg_frames
 from plexus.ws import WebSocketTransport
 
-__version__ = "0.5.1"
+__version__ = "0.5.2"
 __all__ = ["Plexus", "WebSocketTransport", "read_mjpeg_frames"]

plexus_python-0.5.2/plexus/_log.py

@@ -0,0 +1,15 @@
+import os
+import sys
+
+_QUIET = os.environ.get("PLEXUS_QUIET", "").lower() in ("1", "true", "yes")
+
+
+def _say(line: str) -> None:
+    """Single-line status message to stderr. Skipped if PLEXUS_QUIET=1."""
+    if _QUIET:
+        return
+    try:
+        sys.stderr.write(f"[plexus] {line}\n")
+        sys.stderr.flush()
+    except Exception:
+        pass

{plexus_python-0.5.1 → plexus_python-0.5.2}/plexus/client.py

@@ -30,17 +30,16 @@ Usage:
             px.send("temperature", read_temp())
             time.sleep(0.01)
 
-Note: Requires authentication. Run 'plexus start' or set PLEXUS_API_KEY.
+Note: Requires authentication. Run 'plexus init' or set PLEXUS_API_KEY.
 """
 
 import gzip
 import json
 import logging
-import os
+import re
 import shutil
 import socket
 import subprocess
-import sys
 import threading
 import time
 import urllib.error
@@ -48,6 +47,7 @@ import urllib.request
 from contextlib import contextmanager
 from typing import Any, Dict, Generator, List, Optional, Tuple, Union
 
+from plexus._log import _say
 from plexus.buffer import BufferBackend, MemoryBuffer, SqliteBuffer
 from plexus.config import (
     RetryConfig,
@@ -59,6 +59,7 @@ from plexus.config import (
     get_source_id,
     set_source_id,
 )
+
 logger = logging.getLogger(__name__)
 
 
@@ -101,20 +102,6 @@ class _ConnError(OSError):
     pass
 
 
-# Status messages to stderr so users running `python my_script.py` see what's
-# happening without having to configure logging. Set PLEXUS_QUIET=1 to disable.
-_QUIET = os.environ.get("PLEXUS_QUIET", "").lower() in ("1", "true", "yes")
-
-
-def _say(line: str) -> None:
-    if _QUIET:
-        return
-    try:
-        sys.stderr.write(f"[plexus] {line}\n")
-        sys.stderr.flush()
-    except Exception:
-        pass
-
 # Flexible value type - supports any JSON-serializable value
 FlexValue = Union[int, float, str, bool, Dict[str, Any], List[Any]]
 
@@ -161,6 +148,18 @@ class AuthenticationError(PlexusError):
     pass
 
 
+_SOURCE_ID_RE = re.compile(r'^[a-z0-9][a-z0-9_-]{1,62}$')
+
+
+def _validate_source_id(source_id: str) -> None:
+    if not _SOURCE_ID_RE.match(source_id):
+        raise ValueError(
+            f"Invalid source_id {source_id!r}. "
+            "Must match ^[a-z0-9][a-z0-9_-]{1,62}$ "
+            "(lowercase letters, digits, hyphens, underscores; start with letter or digit)."
+        )
+
+
 class Plexus:
     """
     Client for sending sensor data to Plexus.
@@ -186,7 +185,7 @@ class Plexus:
         timeout: float = 10.0,
         retry_config: Optional[RetryConfig] = None,
         max_buffer_size: int = 10000,
-        persistent_buffer: bool = False,
+        persistent_buffer: bool = True,
         buffer_path: Optional[str] = None,
         transport: str = "ws",
         ws_url: Optional[str] = None,
@@ -201,6 +200,7 @@ class Plexus:
         self.endpoint = (endpoint or get_endpoint()).rstrip("/")
         self.gateway_url = get_gateway_url()
         self.source_id = source_id or get_source_id()
+        _validate_source_id(self.source_id)
         self.timeout = timeout
         self.retry_config = retry_config or RetryConfig()
         self._max_buffer_size = max_buffer_size
@@ -360,7 +360,7 @@ class Plexus:
 
     def send_batch(
         self,
-        points: List[Tuple[str, FlexValue]],
+        points: List[Union[Tuple[str, FlexValue], Tuple[str, FlexValue, float]]],
         timestamp: Optional[float] = None,
         tags: Optional[Dict[str, str]] = None,
     ) -> bool:
@@ -368,8 +368,11 @@ class Plexus:
         Send multiple metrics at once.
 
         Args:
-            points: List of (metric, value) tuples. Values can be any FlexValue type.
-            timestamp: Shared timestamp for all points. If not provided, uses current time.
+            points: List of (metric, value) or (metric, value, timestamp) tuples.
+                    Values can be any FlexValue type. Per-point timestamps override
+                    the shared timestamp argument.
+            timestamp: Shared timestamp for points that don't supply their own.
+                       If not provided, uses current time.
             tags: Shared tags for all points
 
         Returns:
@@ -382,9 +385,23 @@ class Plexus:
                 ("robot.state", "RUNNING"),
                 ("position", {"x": 1.0, "y": 2.0}),
             ])
+
+            # Per-point timestamps (e.g. sensors on different interrupt timers):
+            px.send_batch([
+                ("imu.accel_x", 0.12, t_imu),
+                ("pressure",    1013.2, t_baro),
+                ("temperature", 22.4),   # uses shared timestamp
+            ])
         """
-        ts_ms = self._normalize_ts_ms(timestamp)
-        data_points = [self._make_point(m, v, ts_ms, tags) for m, v in points]
+        default_ts_ms = self._normalize_ts_ms(timestamp)
+        data_points = []
+        for p in points:
+            if len(p) == 3:
+                m, v, t = p
+                data_points.append(self._make_point(m, v, self._normalize_ts_ms(t), tags))
+            else:
+                m, v = p
+                data_points.append(self._make_point(m, v, default_ts_ms, tags))
         return self._send_points(data_points)
 
     def _ensure_ws(self):
@@ -656,6 +673,12 @@ class Plexus:
         if self.transport != "ws":
             raise PlexusError("on_command requires transport='ws'")
         ws = self._ensure_ws()
+        if ws.is_authenticated:
+            _say(
+                f"⚠ on_command('{name}') called after connection is already authenticated — "
+                "command will not be advertised to the dashboard until next reconnect. "
+                "Call on_command() before the first send()."
+            )
         ws.register_command(name, handler, description=description, params=params)
 
     def _send_points(self, points: List[Dict[str, Any]]) -> bool:
@@ -673,7 +696,7 @@ class Plexus:
         """
         if not self.api_key:
             raise AuthenticationError(
-                "No API key configured. Run 'plexus start' or set PLEXUS_API_KEY"
+                "No API key configured. Run 'plexus init' or set PLEXUS_API_KEY"
             )
 
         # Include any previously buffered points
@@ -905,7 +928,12 @@ class Plexus:
             self._store_frames = False
 
     def close(self):
-        """Close the client and release resources."""
+        """Close the client, flush any buffered points, and release resources."""
+        if self.buffer_size() > 0:
+            try:
+                self.flush_buffer()
+            except Exception as e:
+                logger.debug("flush on close failed: %s", e)
         if self._ws is not None:
             self._ws.stop()
             self._ws = None

{plexus_python-0.5.1 → plexus_python-0.5.2}/plexus/ws.py

@@ -28,11 +28,9 @@ from __future__ import annotations
 import atexit
 import json
 import logging
-import os
 import queue
 import random
 import struct
-import sys
 import threading
 import time
 from dataclasses import dataclass, field
@@ -46,24 +44,9 @@ except ImportError as e:  # pragma: no cover - import-time failure is obvious
         "Install with: pip install websocket-client"
     ) from e
 
-logger = logging.getLogger(__name__)
-
-# By default, print connection status to stderr so users running
-# `python my_script.py` can see what's happening without having to
-# configure the logging module. Set PLEXUS_QUIET=1 to disable.
-_QUIET = os.environ.get("PLEXUS_QUIET", "").lower() in ("1", "true", "yes")
-
+from plexus._log import _say
 
-def _say(line: str) -> None:
-    """Single-line status message to stderr. Skipped if PLEXUS_QUIET=1."""
-    if _QUIET:
-        return
-    try:
-        sys.stderr.write(f"[plexus] {line}\n")
-        sys.stderr.flush()
-    except Exception:
-        # Stderr blew up — don't take the whole client down with it.
-        pass
+logger = logging.getLogger(__name__)
 
 AUTH_TIMEOUT_S = 10.0
 HEARTBEAT_INTERVAL_S = 30.0

{plexus_python-0.5.1 → plexus_python-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plexus-python"
-version = "0.5.1"
+version = "0.5.2"
 description = "Thin Python SDK for Plexus — send telemetry in one line"
 readme = "README.md"
 license = "Apache-2.0"

plexus_python-0.5.2/skills/plexus/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: Plexus
+description: This skill should be used when the user asks to "set up Plexus on my device", "install Plexus on my Raspberry Pi", "send telemetry to Plexus", "integrate Plexus into my project", "build a monitoring app with Plexus", "query my Plexus devices", "stream live data from Plexus", or "connect to the Plexus API". Covers both the device-side SDK and the consumer-side REST/WebSocket API.
+version: 0.1.0
+---
+
+# Plexus
+
+Plexus is a hardware observability platform. Devices push telemetry (metrics, events, video) via the Python SDK or raw HTTP. That data is then queryable and streamable through the Plexus Data API and dashboard.
+
+There are two distinct workflows — choose based on what the user is building:
+
+- **Device side** — install the SDK, authenticate, and start sending data from hardware
+- **App side** — query historical data, stream live updates, and monitor a fleet via the REST/WebSocket API
+
+---
+
+## Device Side: SDK Setup
+
+### Install
+
+One-line setup for Linux devices (Raspberry Pi, Jetson, etc.) — installs the SDK, configures auth, and handles hardware support automatically:
+
+```bash
+curl -sL https://app.plexus.company/setup | bash -s -- --key plx_xxx --name drone-01
+```
+
+`--name` is required and must be unique across the fleet (`^[a-z0-9][a-z0-9_-]{1,62}$`). The gateway auto-suffixes duplicates (`drone-01_2`, etc.).
+
+For development machines or manual installs:
+
+```bash
+pip install plexus-python
+plexus init   # opens browser to authenticate and saves key to ~/.plexus/config.json
+```
+
+### Send telemetry
+
+```python
+from plexus import Plexus
+
+px = Plexus(source_id="drone-01")  # reads PLEXUS_API_KEY from env or ~/.plexus/config.json
+
+px.send("battery.voltage", 12.4)
+px.send("motor.rpm", 3200, tags={"motor_id": "A1"})
+px.send_batch([
+    ("battery.voltage", 12.4),
+    ("battery.current_ma", 340),
+    ("motor.rpm", 3200),
+])
+```
+
+Metric names use `<subsystem>.<metric>` convention (`battery.voltage`, `motor.rpm`, `gps.latitude`).
+
+### Send events
+
+Use `event()` for discrete occurrences — faults, state changes, operator actions. These appear as markers on the timeline, not time-series lines:
+
+```python
+px.event("fault", "E-stop triggered")
+px.event("state_change", {"from": "IDLE", "to": "RUNNING"})
+```
+
+### Group data into a run
+
+```python
+with px.run("thermal-cycle-001"):
+    while running:
+        px.send("temperature", read_temp())
+```
+
+### Reliability
+
+Enable SQLite persistence to survive restarts and power loss:
+
+```python
+px = Plexus(persistent_buffer=True)
+```
+
+The SDK buffers locally, retries with exponential backoff, and syncs the device clock against the gateway on every WebSocket connection — important on embedded boards that boot without NTP.
+
+### Video streaming
+
+```python
+# Frame by frame (OpenCV, picamera2)
+import cv2
+cap = cv2.VideoCapture(0)
+while True:
+    ok, frame = cap.read()
+    if ok:
+        px.send_video_frame(frame, camera_id="front")
+
+# From a URL (RTSP, HLS — requires FFmpeg on $PATH)
+stop = px.stream_camera("rtsp://192.168.1.10/stream", camera_id="front")
+stop.set()  # stop when done
+```
+
+---
+
+## App Side: API Integration
+
+**Base URL:** `https://api.plexus.company`  
+**Auth:** `x-api-key: plx_...` header on every request  
+**Keys:** [app.plexus.company/api](https://app.plexus.company/api)
+
+### Discover devices
+
+```bash
+GET /v1/sources                          # all devices
+GET /v1/sources?status=online            # online only
+GET /v1/sources/{source_id}              # single device
+```
+
+### Discover metrics
+
+```bash
+GET /v1/sources/{source_id}/metrics      # list metric names the device has reported
+```
+
+### Fetch latest values
+
+```bash
+GET /v1/sources/{source_id}/metrics/latest
+```
+
+### Query historical data
+
+```bash
+GET /v1/sources/{source_id}/metrics/query?metrics=battery.voltage&last=1h
+GET /v1/sources/{source_id}/metrics/query?metrics=cpu.percent&start=2026-05-01T00:00:00Z&end=2026-05-02T00:00:00Z
+```
+
+Windows under ~10 min return raw `value` arrays. Longer windows auto-downsample to `min/max/avg/count` — Plexus picks an interval (`1m`, `10m`, `1h`, `1d`) targeting ~1000 points. Force with `?interval=raw` or `?interval=10m`.
+
+### Stream live data (WebSocket)
+
+```ts
+const ws = new WebSocket(
+  "wss://api.plexus.company/v1/sources/drone-01/metrics/stream?metrics=battery.voltage,motor.rpm"
+);
+ws.onopen = () => ws.send(JSON.stringify({ type: "auth", api_key: "plx_..." }));
+ws.onmessage = (e) => {
+  const msg = JSON.parse(e.data);
+  if (msg.type === "telemetry") console.log(msg.points);
+};
+```
+
+Auth frame must be the **first frame** — socket closes with `4401` after 10 s if not received.
+
+### Stream live video (WebSocket)
+
+```ts
+const ws = new WebSocket(
+  "wss://api.plexus.company/v1/sources/drone-01/video/stream?camera_id=front"
+);
+ws.onopen = () => ws.send(JSON.stringify({ type: "auth", api_key: "plx_..." }));
+ws.onmessage = (e) => {
+  const msg = JSON.parse(e.data);
+  if (msg.type === "video_frame") {
+    img.src = `data:image/jpeg;base64,${msg.frame}`;
+  }
+};
+```
+
+### Fleet-wide queries
+
+```bash
+GET /v1/fleet/health                               # total and online device counts
+GET /v1/fleet/metrics?metric=cpu.percent&last=1h   # one metric across all devices
+```
+
+---
+
+## Key Conventions
+
+- `source_id` is the stable device identity — everything (metrics, events, commands) is scoped to it
+- API keys are prefixed `plx_` and scoped to an org
+- Config persists to `~/.plexus/config.json`; SDK reads `PLEXUS_API_KEY` env var automatically
+- Metric names: `<subsystem>.<metric>` — keep subsystems consistent across a fleet
+- Tags: low-cardinality key-value pairs for filtering (`firmware`, `location`, `motor_id`) — not UUIDs or timestamps
+
+---
+
+## Additional Resources
+
+For complete method signatures, options, and advanced patterns:
+
+- **`references/sdk.md`** — Full SDK reference: all methods, transport options, clock correction, commands, environment variables
+- **`references/api.md`** — Full API reference: all REST endpoints, WebSocket frame shapes, query params, close codes