plexus-python 0.7.0__tar.gz → 0.8.0__tar.gz

{plexus_python-0.7.0 → plexus_python-0.8.0}/AGENTS.md

@@ -7,8 +7,8 @@ Machine-readable interface for AI assistants and automation scripts.
 | Variable                | Description                           | Default                          |
 | ----------------------- | ------------------------------------- | -------------------------------- |
 | `PLEXUS_API_KEY`        | API key for authentication (required) | none                             |
-| `PLEXUS_GATEWAY_URL`    | Gateway HTTP ingest URL               | `https://plexus-gateway.fly.dev` |
-| `PLEXUS_GATEWAY_WS_URL` | Gateway WebSocket URL                 | `wss://plexus-gateway.fly.dev`   |
+| `PLEXUS_GATEWAY_URL`    | Gateway HTTP ingest URL               | `https://gateway.plexus.company` |
+| `PLEXUS_GATEWAY_WS_URL` | Gateway WebSocket URL                 | `wss://gateway.plexus.company`   |
 
 ## CLI Commands
 

{plexus_python-0.7.0 → plexus_python-0.8.0}/API.md

@@ -30,7 +30,7 @@ Then control streaming, recording, and configuration from [app.plexus.company/de
 Send data directly via HTTP:
 
 ```bash
-curl -X POST https://plexus-gateway.fly.dev/ingest \
+curl -X POST https://gateway.plexus.company/ingest \
   -H "x-api-key: YOUR_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
@@ -94,14 +94,14 @@ x-api-key: plx_xxxxx
 }
 ```
 
-| Field        | Type   | Required | Description                                    |
-| ------------ | ------ | -------- | ---------------------------------------------- |
-| `metric`     | string | Yes      | Metric name (e.g., `temperature`, `motor.rpm`) |
-| `value`      | any    | Yes      | See supported value types below                |
+| Field        | Type   | Required | Description                                                                                                                                                                                             |
+| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `metric`     | string | Yes      | Metric name (e.g., `temperature`, `motor.rpm`)                                                                                                                                                          |
+| `value`      | any    | Yes      | See supported value types below                                                                                                                                                                         |
 | `timestamp`  | float  | No       | Unix timestamp in seconds (or ms if ≥ 1e12). Omit to use device time. Over WebSocket, the Python SDK applies a server-synced clock correction when omitted — see [Clock correction](#clock-correction). |
-| `source_id`  | string | Yes      | Your source identifier                         |
-| `tags`       | object | No       | Key-value labels                               |
-| `session_id` | string | No       | Group data into sessions                       |
+| `source_id`  | string | Yes      | Your source identifier                                                                                                                                                                                  |
+| `tags`       | object | No       | Key-value labels                                                                                                                                                                                        |
+| `session_id` | string | No       | Group data into sessions                                                                                                                                                                                |
 
 ### Supported Value Types
 
@@ -152,7 +152,7 @@ For real-time UI-controlled streaming, devices connect via WebSocket.
 
 ### Device Authentication
 
-Devices authenticate using an API key. The `source_id` in the request is the device's *desired* name; the server may return a different, auto-suffixed name in the `authenticated` frame if the desired name is already claimed by another device (see [Device identity](../README.md#device-identity) in the README).
+Devices authenticate using an API key. The `source_id` in the request is the device's _desired_ name; the server may return a different, auto-suffixed name in the `authenticated` frame if the desired name is already claimed by another device (see [Device identity](../README.md#device-identity) in the README).
 
 ```json
 // Device → Server
@@ -286,7 +286,7 @@ import requests
 import time
 
 requests.post(
-    "https://plexus-gateway.fly.dev/ingest",
+    "https://gateway.plexus.company/ingest",
     headers={"x-api-key": "plx_xxxxx"},
     json={
         "points": [{
@@ -302,7 +302,7 @@ requests.post(
 ### JavaScript
 
 ```javascript
-await fetch("https://plexus-gateway.fly.dev/ingest", {
+await fetch("https://gateway.plexus.company/ingest", {
   method: "POST",
   headers: {
     "x-api-key": "plx_xxxxx",
@@ -344,7 +344,7 @@ func main() {
     }
 
     body, _ := json.Marshal(points)
-    req, _ := http.NewRequest("POST", "https://plexus-gateway.fly.dev/ingest", bytes.NewBuffer(body))
+    req, _ := http.NewRequest("POST", "https://gateway.plexus.company/ingest", bytes.NewBuffer(body))
     req.Header.Set("x-api-key", "plx_xxxxx")
     req.Header.Set("Content-Type", "application/json")
 
@@ -363,7 +363,7 @@ func main() {
 // field entirely if you cannot guarantee NTP sync at send time.
 void sendToPlexus(const char* metric, float value) {
     HTTPClient http;
-    http.begin("https://plexus-gateway.fly.dev/ingest");
+    http.begin("https://gateway.plexus.company/ingest");
     http.addHeader("Content-Type", "application/json");
     http.addHeader("x-api-key", "plx_xxxxx");
 
@@ -386,7 +386,7 @@ void sendToPlexus(const char* metric, float value) {
 API_KEY="plx_xxxxx"
 SOURCE_ID="sensor-001"
 
-curl -X POST https://plexus-gateway.fly.dev/ingest \
+curl -X POST https://gateway.plexus.company/ingest \
   -H "x-api-key: $API_KEY" \
   -H "Content-Type: application/json" \
   -d "{
@@ -430,8 +430,6 @@ while True:
         px.send("attitude.pitch", msg.pitch)
 ```
 
-See [docs.plexus.dev/recipes](https://docs.plexus.dev/recipes) for more.
-
 ## Python SDK with Sensor Drivers
 
 For Raspberry Pi and other Linux devices, the Python SDK includes sensor drivers:
@@ -492,15 +490,18 @@ px.send("temperature", 72.5, timestamp=t)        # your timestamp → used as-is
 ```
 
 **When to pass an explicit timestamp:**
+
 - You have a reliable wall-clock source (GPS, trusted hardware RTC, host NTP)
 - You are replaying or backfilling historical data
 - Your sensor provides its own wall-clock timestamp
 
 **When to omit timestamp:**
+
 - The device may have booted without NTP (Raspberry Pi, Jetson, field robots without network on first boot)
 - You have no reliable external time source
 
 **Known limitations:**
+
 - The clock offset refreshes only on WebSocket reconnect. A device with a drifting RTC that stays connected for many days will accumulate uncorrected drift between reconnects proportional to the drift rate.
 - HTTP transport (`transport="http"`) does not receive clock sync — timestamps default to the device clock uncorrected.
 - `send_batch()` takes one shared `timestamp` for the whole batch, not per-point. For per-point timestamps, call `send()` in a loop.

{plexus_python-0.7.0 → plexus_python-0.8.0}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.8.0] - 2026-07-02 - Command concurrency control
+
+### Added
+
+- `concurrency` option on `on_command()` / `register_command()`. Defaults to `"accept"`
+  (unchanged behavior — overlapping invocations run concurrently). Set `"reject"` to refuse a
+  new invocation with an error result (`command already in progress: <name>`) while a previous
+  invocation of the same command is still running. Use it for handlers that drive exclusive
+  hardware (e.g. a pump init) so a client retry or double-click can't start two at once.
+  Protection is per command name; the immediate ack is still sent before the handler runs.
+
+## [0.7.1] - 2026-06-02 - Remove install_id / source_id auto-suffix
+
+### Changed
+
+- Removed `install_id` from the device auth frame and `WebSocketTransport`.
+- Removed server-side source_id auto-suffix handling (`on_source_id_assigned` callback, `set_source_id` persistence).
+- Removed `get_install_id` and `set_source_id` from `plexus.config`.
+
 ## [0.7.0] - 2026-05-29 - SDK hardening
 
 ### Fixed
@@ -176,7 +195,7 @@
 
 ### Changed
 
-- Gateway WebSocket URL (`wss://plexus-gateway.fly.dev`) is now the SDK
+- Gateway WebSocket URL (`wss://gateway.plexus.company`) is now the SDK
   default — no need to pass `ws_url` explicitly.
 - Removed the `[plexus]   endpoint: …` line from the connection printout.
 
@@ -334,7 +353,7 @@ Breaking. `plexus-python` is now just the thin client — no agent, adapters, se
 
 ### Changed
 
-- Default ingest endpoint points directly at the Plexus gateway (`https://plexus-gateway.fly.dev/ingest`), not the Next.js app proxy
+- Default ingest endpoint points directly at the Plexus gateway (`https://gateway.plexus.company/ingest`), not the Next.js app proxy
 - Client raises `ValueError` clearly when no API key is available, instead of invoking a login flow
 
 ## [0.1.0] - Initial release

{plexus_python-0.7.0 → plexus_python-0.8.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.7.0
+Version: 0.8.0
 Summary: Thin Python SDK for Plexus — send telemetry in one line
-Project-URL: Homepage, https://plexus.dev
-Project-URL: Documentation, https://docs.plexus.dev
+Project-URL: Homepage, https://plexus.company
+Project-URL: Documentation, https://docs.plexus.company
 Project-URL: Repository, https://github.com/plexus-oss/plexus-python
 Project-URL: Issues, https://github.com/plexus-oss/plexus-python/issues
-Author-email: Plexus <hello@plexus.dev>
+Author-email: Plexus <info@plexus.company>
 License-Expression: Apache-2.0
 License-File: LICENSE
 Keywords: fleet,hardware,iot,monitoring,observability,telemetry
@@ -270,8 +270,8 @@ The SDK sends an `ack` frame before invoking the handler, then a `result` frame
 | Variable                | Description                  | Default                          |
 | ----------------------- | ---------------------------- | -------------------------------- |
 | `PLEXUS_API_KEY`        | API key (required)           | none                             |
-| `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://plexus-gateway.fly.dev` |
-| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://plexus-gateway.fly.dev`   |
+| `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://gateway.plexus.company` |
+| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://gateway.plexus.company`   |
 
 ## Architecture
 

{plexus_python-0.7.0 → plexus_python-0.8.0}/README.md

@@ -233,8 +233,8 @@ The SDK sends an `ack` frame before invoking the handler, then a `result` frame
 | Variable                | Description                  | Default                          |
 | ----------------------- | ---------------------------- | -------------------------------- |
 | `PLEXUS_API_KEY`        | API key (required)           | none                             |
-| `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://plexus-gateway.fly.dev` |
-| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://plexus-gateway.fly.dev`   |
+| `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://gateway.plexus.company` |
+| `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://gateway.plexus.company`   |
 
 ## Architecture
 

{plexus_python-0.7.0 → plexus_python-0.8.0}/plexus/__init__.py

@@ -10,5 +10,5 @@ Plexus — thin Python SDK for sending telemetry to the Plexus gateway.
 from plexus.client import Plexus, PlexusError, AuthenticationError, read_mjpeg_frames
 from plexus.config import RetryConfig
 
-__version__ = "0.7.0"
+__version__ = "0.8.0"
 __all__ = ["Plexus", "PlexusError", "AuthenticationError", "RetryConfig", "read_mjpeg_frames"]

{plexus_python-0.7.0 → plexus_python-0.8.0}/plexus/client.py

@@ -55,9 +55,7 @@ from plexus.config import (
     get_endpoint,
     get_gateway_url,
     get_gateway_ws_url,
-    get_install_id,
     get_source_id,
-    set_source_id,
 )
 
 logger = logging.getLogger(__name__)
@@ -414,9 +412,7 @@ class Plexus:
             api_key=self.api_key,
             source_id=self.source_id,
             ws_url=self._ws_url,
-            install_id=get_install_id(),
             agent_version=__version__,
-            on_source_id_assigned=self._on_source_id_assigned,
             on_clock_synced=self._on_clock_synced,
         )
         self._ws.start()
@@ -428,16 +424,6 @@ class Plexus:
     def _on_clock_synced(self, offset_ms: int) -> None:
         self._clock_offset_ms = offset_ms
 
-    def _on_source_id_assigned(self, assigned: str) -> None:
-        """Callback from WebSocketTransport when the gateway returns an
-        auto-suffixed source_id. Persists it so subsequent runs (and the HTTP
-        fallback path in this process) use the assigned name directly."""
-        self.source_id = assigned
-        try:
-            set_source_id(assigned)
-        except Exception as e:  # pragma: no cover - persistence failure is non-fatal
-            logger.debug("failed to persist assigned source_id: %s", e)
-
     def _encode_frame(self, frame, quality: int) -> Tuple[bytes, int, int]:
         """Normalize any supported frame type to (jpeg_bytes, width, height).
 
@@ -700,6 +686,7 @@ class Plexus:
         *,
         description: Optional[str] = None,
         params: Optional[List[Dict[str, Any]]] = None,
+        concurrency: str = "accept",
     ) -> None:
         """Register a command handler (WebSocket transport only).
 
@@ -709,6 +696,12 @@ class Plexus:
 
         Must be called before the first send() so the command is advertised
         in the auth frame.
+
+        concurrency: "accept" (default) runs overlapping invocations of the
+            same command concurrently; "reject" refuses a new invocation with
+            an error result while a previous one is still running. Use
+            "reject" for handlers that drive exclusive hardware (e.g. a pump
+            init) so a retry or double-click can't start two at once.
         """
         ws = self._ensure_ws()
         if ws.is_authenticated:
@@ -718,7 +711,10 @@ class Plexus:
                 "Call on_command() before the first send().",
                 name,
             )
-        ws.register_command(name, handler, description=description, params=params)
+        ws.register_command(
+            name, handler, description=description, params=params,
+            concurrency=concurrency,
+        )
 
     def _send_points(self, points: List[Dict[str, Any]]) -> bool:
         """Send data points to the gateway with retry and buffering.

{plexus_python-0.7.0 → plexus_python-0.8.0}/plexus/config.py

@@ -49,8 +49,8 @@ CONFIG_DIR = Path.home() / ".plexus"
 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"
+PLEXUS_GATEWAY_URL = "https://gateway.plexus.company"
+PLEXUS_GATEWAY_WS_URL = "wss://gateway.plexus.company"
 
 DEFAULT_CONFIG = {
     "api_key": None,
@@ -145,54 +145,6 @@ def get_source_id() -> Optional[str]:
     return source_id
 
 
-def get_install_id() -> str:
-    """Get the device install ID, generating one if not set.
-
-    The install_id is a stable per-installation UUID. It is generated lazily
-    on first run (NOT at image-build time) so that cloned SD-card images
-    naturally get distinct install_ids on their first boot. The gateway uses
-    it to tell "same device reconnecting" from "different device claiming the
-    same name" when resolving source_id collisions.
-
-    Resolution order:
-      1. ``PLEXUS_INSTALL_ID`` env var — lets ephemeral containers (Fly
-         machines, CI runners, Kubernetes pods) pin a stable identity
-         across restarts when the config filesystem is ephemeral. Without
-         this, every redeploy generates a new install_id and the gateway
-         auto-suffixes the source_id to avoid a collision with the prior
-         install ("gw-001" → "gw-001_2" → "gw-001_3"…).
-      2. ``install_id`` in the on-disk config.
-      3. Newly-generated UUID, persisted to config.
-    """
-    env_id = os.environ.get("PLEXUS_INSTALL_ID", "").strip()
-    if env_id:
-        return env_id
-
-    config = load_config()
-    install_id = config.get("install_id")
-
-    if not install_id:
-        import uuid
-        install_id = uuid.uuid4().hex
-        config["install_id"] = install_id
-        save_config(config)
-
-    return install_id
-
-
-def set_source_id(source_id: str) -> None:
-    """Persist an updated source_id to the config file.
-
-    Called by the SDK when the gateway returns an auto-suffixed name so the
-    assigned name is stable across reconnects.
-    """
-    config = load_config()
-    if config.get("source_id") == source_id:
-        return
-    config["source_id"] = source_id
-    save_config(config)
-
-
 def get_persistent_buffer() -> bool:
     """Get persistent buffer setting. Default True (store-and-forward enabled)."""
     config = load_config()

{plexus_python-0.7.0 → plexus_python-0.8.0}/plexus/ws.py

@@ -62,6 +62,11 @@ class _RegisteredCommand:
     handler: CommandHandler
     description: Optional[str] = None
     params: List[Dict[str, Any]] = field(default_factory=list)
+    # "accept" (default): run overlapping invocations concurrently.
+    # "reject": refuse a new invocation with an error result while a
+    # previous one of the same command is still running.
+    concurrency: str = "accept"
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
 
     def to_manifest(self) -> Dict[str, Any]:
         m: Dict[str, Any] = {"name": self.name}
@@ -89,11 +94,9 @@ class WebSocketTransport:
         source_id: str,
         ws_url: str,
         *,
-        install_id: str = "",
         agent_version: str = "0.0.0",
         platform: str = "python-sdk",
         auto_reconnect: bool = True,
-        on_source_id_assigned: Optional[Callable[[str], None]] = None,
         on_clock_synced: Optional[Callable[[int], None]] = None,
     ):
         if not api_key:
@@ -103,12 +106,10 @@ class WebSocketTransport:
 
         self.api_key = api_key
         self.source_id = source_id
-        self.install_id = install_id
         self.ws_url = _ensure_device_path(ws_url)
         self.agent_version = agent_version
         self.platform = platform
         self.auto_reconnect = auto_reconnect
-        self._on_source_id_assigned = on_source_id_assigned
         self._on_clock_synced = on_clock_synced
 
         self._commands: Dict[str, _RegisteredCommand] = {}
@@ -131,11 +132,24 @@ class WebSocketTransport:
         *,
         description: Optional[str] = None,
         params: Optional[List[Dict[str, Any]]] = None,
+        concurrency: str = "accept",
     ) -> None:
         """Register a command handler. Must be called before start() to be
-        advertised in the auth frame."""
+        advertised in the auth frame.
+
+        concurrency controls what happens when a command arrives while a
+        previous invocation of the *same* command is still running:
+            "accept" (default) — run it concurrently on a new thread.
+            "reject"           — refuse it with an error result until the
+                                 in-flight invocation finishes.
+        """
+        if concurrency not in ("accept", "reject"):
+            raise ValueError(
+                f"concurrency must be 'accept' or 'reject', got {concurrency!r}"
+            )
         self._commands[name] = _RegisteredCommand(
-            name=name, handler=handler, description=description, params=params or []
+            name=name, handler=handler, description=description,
+            params=params or [], concurrency=concurrency,
         )
 
     def start(self) -> None:
@@ -278,16 +292,13 @@ class WebSocketTransport:
             self._ws = ws
 
         # 1. Send device_auth
-        desired_source_id = self.source_id
         auth = {
             "type": "device_auth",
             "api_key": self.api_key,
-            "source_id": desired_source_id,
+            "source_id": self.source_id,
             "platform": self.platform,
             "agent_version": self.agent_version,
         }
-        if self.install_id:
-            auth["install_id"] = self.install_id
         if self._commands:
             auth["commands"] = [c.to_manifest() for c in self._commands.values()]
         ws.send(json.dumps(auth))
@@ -312,22 +323,6 @@ class WebSocketTransport:
                 except Exception as e:
                     logger.debug("on_clock_synced callback raised: %s", e)
 
-        # The gateway may return a different source_id if the desired name
-        # was already claimed by another install — adopt the assigned value
-        # so all subsequent frames (heartbeats, future reconnects) use it.
-        assigned = msg.get("source_id")
-        if isinstance(assigned, str) and assigned and assigned != self.source_id:
-            logger.info(
-                "plexus ws source_id auto-suffixed: requested=%s assigned=%s",
-                desired_source_id, assigned,
-            )
-            self.source_id = assigned
-            if self._on_source_id_assigned is not None:
-                try:
-                    self._on_source_id_assigned(assigned)
-                except Exception as e:  # pragma: no cover - callback errors must not break auth
-                    logger.debug("on_source_id_assigned callback raised: %s", e)
-
         was_reconnect = self._backoff_attempt > 0
         self._authenticated.set()
         self._backoff_attempt = 0
@@ -394,13 +389,42 @@ class WebSocketTransport:
             })
             return
 
+        # concurrency="reject": if an invocation is already running, refuse
+        # this one immediately rather than starting a second in parallel.
+        holds_lock = False
+        if reg.concurrency == "reject":
+            if not reg._lock.acquire(blocking=False):
+                self._send_frame({
+                    "type": "command_result",
+                    "id": cmd_id,
+                    "command": command,
+                    "event": "error",
+                    "error": f"command already in progress: {command}",
+                })
+                return
+            holds_lock = True
+
         # 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()
+        try:
+            threading.Thread(
+                target=self._run_handler,
+                args=(reg, cmd_id, command, params, holds_lock),
+                daemon=True,
+            ).start()
+        except Exception as e:
+            # Thread creation failed (e.g. resource exhaustion). Release the
+            # concurrency lock so the command isn't wedged as "in progress",
+            # and report the failure rather than leaving it silently un-acked.
+            if holds_lock:
+                reg._lock.release()
+            self._send_frame({
+                "type": "command_result",
+                "id": cmd_id,
+                "command": command,
+                "event": "error",
+                "error": f"failed to start command handler: {e}",
+            })
 
     def _run_handler(
         self,
@@ -408,6 +432,7 @@ class WebSocketTransport:
         cmd_id: str,
         command: str,
         params: Dict[str, Any],
+        holds_lock: bool = False,
     ) -> None:
         try:
             result = reg.handler(command, params)
@@ -420,6 +445,11 @@ class WebSocketTransport:
                 "error": str(e),
             })
             return
+        finally:
+            # Release the concurrency lock (if held) as soon as the handler
+            # returns, regardless of success or failure.
+            if holds_lock:
+                reg._lock.release()
         self._send_frame({
             "type": "command_result",
             "id": cmd_id,

{plexus_python-0.7.0 → plexus_python-0.8.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plexus-python"
-version = "0.7.0"
+version = "0.8.0"
 description = "Thin Python SDK for Plexus — send telemetry in one line"
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.10"
 authors = [
-    { name = "Plexus", email = "hello@plexus.dev" }
+    { name = "Plexus", email = "info@plexus.company" }
 ]
 keywords = ["telemetry", "iot", "hardware", "observability", "fleet", "monitoring"]
 classifiers = [
@@ -41,8 +41,8 @@ dev = ["pytest>=9.0.3", "pytest-cov", "ruff", "websockets>=12", "opencv-python-h
 plexus = "plexus.cli:main"
 
 [project.urls]
-Homepage = "https://plexus.dev"
-Documentation = "https://docs.plexus.dev"
+Homepage = "https://plexus.company"
+Documentation = "https://docs.plexus.company"
 Repository = "https://github.com/plexus-oss/plexus-python"
 Issues = "https://github.com/plexus-oss/plexus-python/issues"