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

{plexus_python-0.8.0 → plexus_python-0.9.1}/.github/workflows/publish.yml

@@ -30,10 +30,24 @@ jobs:
               match = re.search(r'^version\s*=\s*\"(.+?)\"', f.read(), re.MULTILINE)
               print(match.group(1))
           ")
-          echo "Git tag version: $TAG"
-          echo "Code version:    $CODE_VERSION"
+          INIT_VERSION=$(python -c "
+          import re
+          with open('plexus/__init__.py') as f:
+              match = re.search(r'^__version__\s*=\s*\"(.+?)\"', f.read(), re.MULTILINE)
+              print(match.group(1))
+          ")
+          echo "Git tag version:     $TAG"
+          echo "pyproject.toml:      $CODE_VERSION"
+          echo "plexus/__init__.py:  $INIT_VERSION"
           if [ "$TAG" != "$CODE_VERSION" ]; then
-            echo "::error::Tag v$TAG does not match code version $CODE_VERSION"
+            echo "::error::Tag v$TAG does not match pyproject.toml version $CODE_VERSION"
+            exit 1
+          fi
+          # 0.9.0 shipped to PyPI with __version__ still reading 0.8.0: the CI
+          # job that checks this does not gate publish, and this job only read
+          # pyproject.toml. Check it here, where it can actually stop an upload.
+          if [ "$TAG" != "$INIT_VERSION" ]; then
+            echo "::error::Tag v$TAG does not match plexus/__init__.py version $INIT_VERSION"
             exit 1
           fi
 

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

@@ -4,22 +4,27 @@ Machine-readable interface for AI assistants and automation scripts.
 
 ## Environment Variables
 
-| Variable                | Description                           | Default                          |
-| ----------------------- | ------------------------------------- | -------------------------------- |
-| `PLEXUS_API_KEY`        | API key for authentication (required) | none                             |
-| `PLEXUS_GATEWAY_URL`    | Gateway HTTP ingest URL               | `https://gateway.plexus.company` |
-| `PLEXUS_GATEWAY_WS_URL` | Gateway WebSocket URL                 | `wss://gateway.plexus.company`   |
+| Variable                | Description                                     | Default                          |
+| ----------------------- | ----------------------------------------------- | -------------------------------- |
+| `PLEXUS_API_KEY`        | API key for authentication (required)           | none                             |
+| `PLEXUS_GATEWAY_URL`    | Gateway HTTP ingest URL                         | `https://gateway.plexus.company` |
+| `PLEXUS_GATEWAY_WS_URL` | Gateway WebSocket URL                           | `wss://gateway.plexus.company`   |
+| `PLEXUS_ENDPOINT`       | Product app URL (runs, frame uploads, CLI auth) | `https://app.plexus.company`     |
+| `PLEXUS_QUIET`          | Set `1`/`true`/`yes` to silence `[plexus]` stderr status lines | unset (status lines on) |
 
 ## CLI Commands
 
 ```bash
-plexus start                           # Stream with PLEXUS_API_KEY env var
-plexus start --key plx_xxxxx           # Pass key inline
-plexus start --device-id my-device     # Set device identifier
-plexus reset                           # Clear config
+plexus init                            # Authorize this machine, save an API key locally (alias: login)
+plexus init --name my-key              # Label for the issued key (default: cli-<hostname>)
+plexus init --force                    # Overwrite an existing local key
+plexus logout                          # Forget the local API key
+plexus whoami                          # Show the local credential summary
 ```
 
-An API key is required — set `PLEXUS_API_KEY` or pass `--key`. There is no interactive signup; get a key at app.plexus.company/devices.
+`plexus init` opens a browser to `app.plexus.company/auth/cli`, waits for the callback, and
+persists the issued key to `~/.plexus/config.json`. Alternatively, set `PLEXUS_API_KEY` (or pass
+`api_key=` to `Plexus()`) instead of running `init`; get a key at app.plexus.company/api.
 
 ## Exit Codes
 

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

@@ -55,8 +55,8 @@ Plexus uses API keys for all authentication:
 
 **Option A: CLI setup (recommended for devices)**
 
-1. Run `plexus start` on your device
-2. Sign up or sign in directly in the terminal
+1. Run `plexus init` on your device
+2. Authorize the machine in the browser tab it opens
 3. API key is saved to `~/.plexus/config.json`
 
 **Option B: Manual creation**
@@ -77,7 +77,7 @@ x-api-key: plx_xxxxx
 
 ### Send Data
 
-**POST** `/api/ingest`
+**POST** `https://gateway.plexus.company/ingest`
 
 ```json
 {
@@ -87,8 +87,7 @@ x-api-key: plx_xxxxx
       "value": 72.5,
       "timestamp": 1699900000.123,
       "source_id": "sensor-001",
-      "tags": { "location": "lab" },
-      "session_id": "test-001"
+      "tags": { "location": "lab" }
     }
   ]
 }
@@ -101,7 +100,6 @@ x-api-key: plx_xxxxx
 | `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                                                                                                                                                                                |
 
 ### Supported Value Types
 
@@ -115,29 +113,7 @@ x-api-key: plx_xxxxx
 
 ### Sessions
 
-Group related data for analysis and playback.
-
-**Create session:**
-
-```json
-POST /api/sessions
-{
-  "session_id": "test-001",
-  "name": "Motor Test Run",
-  "source_id": "sensor-001",
-  "status": "active"
-}
-```
-
-**End session:**
-
-```json
-PATCH /api/sessions/{session_id}
-{
-  "status": "completed",
-  "ended_at": "2024-01-15T10:30:00Z"
-}
-```
+> **Removed / not built.** There is no sessions or runs REST API (`POST /api/sessions`, `POST /api/runs`) — no such route exists in the gateway or platform, and the SDK's former `run()` context has been removed. To group a slice of data, use plain `tags` on each point.
 
 ## WebSocket API
 
@@ -146,13 +122,13 @@ For real-time UI-controlled streaming, devices connect via WebSocket.
 ### Connection Flow
 
 1. Device connects to the gateway
-2. Device authenticates with API key
-3. Device reports available sensors
-4. Dashboard controls streaming via messages
+2. Device authenticates with API key (and advertises any registered commands)
+3. Device streams `telemetry` frames
+4. Dashboard/API invokes registered commands via `typed_command`
 
 ### 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 gateway echoes the declared `source_id` back unchanged — there is no auto-suffixing, so pick a unique `source_id` per device.
 
 ```json
 // Device → Server
@@ -160,9 +136,8 @@ Devices authenticate using an API key. The `source_id` in the request is the dev
   "type": "device_auth",
   "api_key": "plx_xxxxx",
   "source_id": "drone-01",
-  "install_id": "c9f2e0b46f4a4f6a8c3e1d5b0a2e7f91",
   "platform": "python-sdk",
-  "agent_version": "0.3.1"
+  "agent_version": "0.8.0"
 }
 
 // Server → Device
@@ -171,53 +146,34 @@ Devices authenticate using an API key. The `source_id` in the request is the dev
   "source_id": "drone-01",
   "server_time_ms": 1746100800000
 }
-
-// Server → Device (collision case)
-{
-  "type": "authenticated",
-  "source_id": "drone-01_2",
-  "server_time_ms": 1746100800000
-}
 ```
 
-The SDK **adopts** whatever `source_id` the server returns and uses it for all subsequent frames, heartbeats, and reconnects. It also persists the assigned name locally so reconnects go straight to the claimed slot.
-
 `server_time_ms` is the gateway's current Unix time in milliseconds. The Python SDK uses it to compute a clock offset (`server_time - device_time`) that is applied to every SDK-generated timestamp for the lifetime of the connection. This corrects for devices that boot without NTP or have an unreliable RTC — a common condition on embedded Linux. See [Clock correction](#clock-correction) for details and limitations.
 
-`install_id` is a stable per-installation UUID, generated on the device's first run and saved to `~/.plexus/config.json`. It lets the server distinguish a rebooting device from a new device trying to claim an existing name. Legacy SDKs that omit `install_id` continue to work as before (the server passes the declared `source_id` through unchanged).
+> **Removed:** `install_id` and server-side `source_id` auto-suffixing were removed in 0.7.1. The device_auth frame no longer carries an `install_id`, and the client does not adopt or persist a server-assigned name.
 
-### Message Types (Dashboard → Device)
+### Frame Types
 
-| Type            | Description                          |
-| --------------- | ------------------------------------ |
-| `start_stream`  | Start streaming sensor data          |
-| `stop_stream`   | Stop streaming                       |
-| `start_session` | Start recording to a session         |
-| `stop_session`  | Stop recording                       |
-| `configure`     | Configure sensor (e.g., sample rate) |
-| `ping`          | Keepalive request                    |
+**Device → Server**
 
-### Message Types (Device → Dashboard)
+| Type             | Description                                     |
+| ---------------- | ----------------------------------------------- |
+| `device_auth`    | Authenticate on connect (see above)             |
+| `telemetry`      | Sensor data points                              |
+| `heartbeat`      | Liveness ping (every 30s)                       |
+| `command_result` | `ack` / `result` / `error` for a typed command  |
 
-| Type              | Description             |
-| ----------------- | ----------------------- |
-| `telemetry`       | Sensor data points      |
-| `session_started` | Confirm session started |
-| `session_stopped` | Confirm session stopped |
-| `pong`            | Keepalive response      |
+**Server → Device**
 
-### Start Streaming
+| Type            | Description                                            |
+| --------------- | ----------------------------------------------------- |
+| `authenticated` | Auth accepted; carries `server_time_ms`               |
+| `typed_command` | Invoke a command the device registered via `on_command` |
 
-```json
-// Dashboard → Device
-{
-  "type": "start_stream",
-  "source_id": "my-device-001",
-  "metrics": ["accel_x", "accel_y", "accel_z"],
-  "interval_ms": 100
-}
+### Telemetry
 
-// Device → Dashboard (continuous)
+```json
+// Device → Server (streamed continuously)
 {
   "type": "telemetry",
   "points": [
@@ -228,54 +184,20 @@ The SDK **adopts** whatever `source_id` the server returns and uses it for all s
 }
 ```
 
-### Start Session (Recording)
+### Commands
 
-```json
-// Dashboard → Device
-{
-  "type": "start_session",
-  "source_id": "my-device-001",
-  "session_id": "session_1699900000_abc123",
-  "session_name": "Motor Test",
-  "metrics": [],
-  "interval_ms": 100
-}
+Dashboard/API actions reach the device as a single `typed_command` envelope; the device replies with `command_result` frames. Register handlers with `px.on_command(...)` before the first `send()`.
 
-// Device → Dashboard
-{
-  "type": "session_started",
-  "session_id": "session_1699900000_abc123",
-  "session_name": "Motor Test"
-}
+```json
+// Server → Device
+{ "type": "typed_command", "id": "cmd-1", "command": "reboot", "params": { "delay_s": 0 } }
 
-// Device streams telemetry with session_id tag
-{
-  "type": "telemetry",
-  "session_id": "session_1699900000_abc123",
-  "points": [
-    {
-      "metric": "accel_x",
-      "value": 0.12,
-      "timestamp": 1699900000123,
-      "tags": { "session_id": "session_1699900000_abc123" }
-    }
-  ]
-}
+// Device → Server (ack, then result or error)
+{ "type": "command_result", "id": "cmd-1", "command": "reboot", "event": "ack" }
+{ "type": "command_result", "id": "cmd-1", "command": "reboot", "event": "result", "result": { "ok": true } }
 ```
 
-### Configure Sensor
-
-```json
-// Dashboard → Device
-{
-  "type": "configure",
-  "source_id": "my-device-001",
-  "sensor": "MPU6050",
-  "config": {
-    "sample_rate": 50
-  }
-}
-```
+> **Removed / not built.** There are no raw `start_stream`, `stop_stream`, `start_session`, `stop_session`, `configure`, `session_started`, or `session_stopped` frames — the earlier agent-style streaming/recording protocol was removed. Dashboard-driven control now flows through the `typed_command` envelope above.
 
 ## Code Examples
 
@@ -432,36 +354,7 @@ while True:
 
 ## Python SDK with Sensor Drivers
 
-For Raspberry Pi and other Linux devices, the Python SDK includes sensor drivers:
-
-```bash
-pip install plexus-python[sensors]
-plexus start
-```
-
-### Supported Sensors
-
-| Sensor  | Type        | Metrics                                                       | I2C Address |
-| ------- | ----------- | ------------------------------------------------------------- | ----------- |
-| MPU6050 | 6-axis IMU  | `accel_x`, `accel_y`, `accel_z`, `gyro_x`, `gyro_y`, `gyro_z` | 0x68, 0x69  |
-| MPU9250 | 9-axis IMU  | `accel_x`, `accel_y`, `accel_z`, `gyro_x`, `gyro_y`, `gyro_z` | 0x68        |
-| BME280  | Environment | `temperature`, `humidity`, `pressure`                         | 0x76, 0x77  |
-
-### Custom Sensors
-
-```python
-from plexus.sensors import BaseSensor, SensorReading
-
-class MySensor(BaseSensor):
-    name = "MySensor"
-    metrics = ["voltage", "current"]
-
-    def read(self):
-        return [
-            SensorReading("voltage", read_adc(0) * 3.3),
-            SensorReading("current", read_adc(1) * 0.1),
-        ]
-```
+> **Removed / not built.** There is no `plexus-python[sensors]` extra and no `plexus.sensors` module (`BaseSensor` / `SensorReading` do not exist). The only optional extras are `[video]` and `[dev]`. This SDK stays out of your decode path — read your sensor with whatever library you already use and pass values to `px.send()` (see [Bring Your Own Protocol](#bring-your-own-protocol) above).
 
 ## Errors
 
@@ -503,14 +396,13 @@ px.send("temperature", 72.5, timestamp=t)        # your timestamp → used as-is
 **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.
+- The HTTP fallback path (used when the WebSocket is unavailable) does not receive clock sync — timestamps default to the device clock uncorrected.
+- `send_batch()` takes one shared `timestamp` by default; pass `(metric, value, timestamp)` 3-tuples for per-point timestamps.
 
 ## Best Practices
 
 - **Batch points** - Send up to 100 points per request for HTTP
 - **Omit timestamp when unsure** - The Python SDK applies server-synced clock correction when `timestamp` is omitted over WebSocket; only pass an explicit timestamp when you have a reliable wall-clock source
 - **Consistent source_id** - Use the same ID for each physical device/source
-- **Use tags** - Label data for filtering (e.g., `{"location": "lab"}`)
-- **Use sessions** - Group related data for easier analysis
-- **Prefer WebSocket** - For real-time UI-controlled devices, use `plexus start`
+- **Use tags** - Label data for filtering and grouping (e.g., `{"location": "lab"}`)
+- **Prefer WebSocket** - For real-time UI-controlled devices, the SDK connects over WebSocket by default

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

@@ -1,5 +1,58 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.9.1] - 2026-08-27 - Version sync
+
+### Fixed
+
+- `plexus.__version__` reported `0.8.0` in the 0.9.0 release. The release script
+  and the publish workflow both validated `pyproject.toml` only; the CI job that
+  compares the two version sites does not gate publishing, so it failed after the
+  upload had already gone out. Both gates now check `plexus/__init__.py` too.
+  0.9.0 is functionally identical to this release — only the reported version
+  string was wrong.
+
+## [0.9.0] - 2026-08-27 - Flexible values and the real slug rule
+
+Two fixes for data that looked like it was sent but never arrived, plus the
+removal of a dead API.
+
+### Fixed
+
+- **`send()` now infers a point's class from its value type** instead of always
+  tagging `class="metric"`. Numbers stay metrics; strings, bools, dicts and
+  lists become events. The gateway rejects a non-numeric value on
+  `class="metric"` and drops the *whole frame* — so `px.send("state", "RUNNING")`
+  silently took every other point in that batch down with it. Non-numeric values
+  have been advertised since 0.2.0; this is what makes them work.
+  An explicit `data_class="metric"` with a non-numeric value now raises
+  `PlexusError` locally rather than failing on the wire.
+
+- **`source_id` validation matched an older, stricter rule than the server.**
+  The SDK enforced `^[a-z0-9][a-z0-9_-]{1,62}$` — no dots, minimum two
+  characters — while the gateway accepts `^[a-z0-9][a-z0-9._-]*$` up to 256
+  characters. Names production would have accepted (`rack.01`, `a`) raised
+  `ValueError` in the constructor before a single byte left the host, which
+  reads as an auth problem and is not one. The SDK now mirrors the wire rule.
+  Uuid-shaped ids are still rejected: the app resolves those as internal ids,
+  so such a source would be unreachable.
+
+- Buffer drains are chunked, so a backlog over the gateway's 10k-points-per-batch
+  ceiling no longer wedges every subsequent send. The WebSocket auth wait is paid
+  once, on the first send, instead of stalling each call.
+
+### Removed
+
+- `run()` context manager and its `POST /api/runs` plumbing. The `/api/runs` route never
+  existed on the platform (both notifications failed silently on every call), the ingest
+  loader drops `run_id` from points, and nothing was ever stored — so removal loses no
+  data. To group a slice of data, use `tags` on each point.
+
+### Security
+
+- Bumped pillow to 12.3.0 and idna to 3.19 for published advisories.
+
 ## [0.8.0] - 2026-07-02 - Command concurrency control
 
 ### Added

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: plexus-python
-Version: 0.8.0
+Version: 0.9.1
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.company
 Project-URL: Documentation, https://docs.plexus.company
@@ -27,7 +27,7 @@ Requires-Dist: numpy>=1.24; extra == 'dev'
 Requires-Dist: opencv-python-headless>=4.8; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: pytest>=9.0.3; extra == 'dev'
-Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: ruff==0.15.12; extra == 'dev'
 Requires-Dist: websockets>=12; extra == 'dev'
 Provides-Extra: video
 Requires-Dist: numpy>=1.24; extra == 'video'
@@ -68,7 +68,7 @@ curl -sL https://app.plexus.company/setup | bash -s -- \
 
 The name must match `^[a-z0-9][a-z0-9_-]{1,62}$`. `setup.sh` refuses to run without `--name` (or without a TTY to prompt for one) — this is deliberate, because the previous `hostname` fallback silently merged telemetry from cloned SD-card images that all booted as `raspberrypi`.
 
-**If two devices end up requesting the same name**, the gateway auto-suffixes: the first connection gets `drone-01`, the second gets `drone-01_2`, the third `drone-01_3`, and so on. The SDK logs the rename at INFO and persists the assigned name to `~/.plexus/config.json` so the device keeps its identity across reboots. Under the hood, a per-installation UUID (`install_id`, lazily generated on first run) is what lets the gateway tell "same device reconnecting" from "different device claiming the same name."
+**Names are not auto-deduplicated.** The gateway echoes back whatever `source_id` you declare, unchanged — pick a unique name per device (that's what `--name` and `source_id=...` are for). Two devices that declare the same name write into the same source.
 
 In normal code, you usually just pass `source_id=...` explicitly to `Plexus(...)` and never have to think about it.
 
@@ -111,7 +111,7 @@ px.send_batch([
 ])
 ```
 
-`points` is a list of `(metric, value)` tuples. All points share the same timestamp (now, unless you pass `timestamp=t`). For independent timestamps per point, call `send()` in a loop instead.
+`points` is a list of `(metric, value)` tuples, or `(metric, value, timestamp)` 3-tuples when you need a per-point timestamp. Points without their own timestamp share the batch timestamp (now, unless you pass `timestamp=t`).
 
 ### `event(name, data)` — record a discrete occurrence
 
@@ -125,16 +125,6 @@ px.event("sensor_error", {"sensor": "imu", "code": 42}, tags={"motor": "A"})
 
 The platform displays events as markers overlaid on your telemetry charts, not as time-series lines.
 
-### `run(run_id)` — group data into a named recording
-
-```python
-with px.run("thermal-cycle-001"):
-    while running:
-        px.send("temperature", read_temp())
-```
-
-All `send()` calls inside the context are tagged with `run_id`, making it easy to isolate and replay that slice of data in the dashboard.
-
 ## Video streaming
 
 Two methods depending on whether you control the capture loop or just have a URL.
@@ -228,8 +218,8 @@ px.send("temperature", 72.5, timestamp=t)   # your timestamp, used as-is, no cor
 
 **Known limits:**
 - Clock sync refreshes on WebSocket (re)connect. A device with a drifting RTC that stays connected for many days accumulates uncorrected drift between reconnects.
-- HTTP-only transport (`transport="http"`) does not receive clock sync — timestamps default to the uncorrected device clock.
-- `send_batch()` shares one timestamp across the whole batch. For per-point timestamps, call `send()` in a loop.
+- The HTTP fallback path (used when the WebSocket is unavailable) does not receive clock sync — timestamps default to the uncorrected device clock.
+- `send_batch()` shares one timestamp across the batch by default; pass `(metric, value, timestamp)` 3-tuples for per-point timestamps.
 
 ## Transport
 
@@ -241,13 +231,12 @@ By default the SDK connects over a **WebSocket** to `/ws/device` on the gateway
 If the socket is unavailable, sends transparently fall back to `POST /ingest` so no data is lost.
 
 ```python
-# default — ws with http fallback
+# ws with transparent http fallback — this is the only mode
 px = Plexus()
-
-# force http (legacy)
-px = Plexus(transport="http")
 ```
 
+There is no transport selector: the SDK always prefers the WebSocket and falls back to `POST /ingest` on its own when the socket is unavailable.
+
 ### Handling commands
 
 Register a handler before the first `send()` so the command is advertised in the auth frame:

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

@@ -31,7 +31,7 @@ curl -sL https://app.plexus.company/setup | bash -s -- \
 
 The name must match `^[a-z0-9][a-z0-9_-]{1,62}$`. `setup.sh` refuses to run without `--name` (or without a TTY to prompt for one) — this is deliberate, because the previous `hostname` fallback silently merged telemetry from cloned SD-card images that all booted as `raspberrypi`.
 
-**If two devices end up requesting the same name**, the gateway auto-suffixes: the first connection gets `drone-01`, the second gets `drone-01_2`, the third `drone-01_3`, and so on. The SDK logs the rename at INFO and persists the assigned name to `~/.plexus/config.json` so the device keeps its identity across reboots. Under the hood, a per-installation UUID (`install_id`, lazily generated on first run) is what lets the gateway tell "same device reconnecting" from "different device claiming the same name."
+**Names are not auto-deduplicated.** The gateway echoes back whatever `source_id` you declare, unchanged — pick a unique name per device (that's what `--name` and `source_id=...` are for). Two devices that declare the same name write into the same source.
 
 In normal code, you usually just pass `source_id=...` explicitly to `Plexus(...)` and never have to think about it.
 
@@ -74,7 +74,7 @@ px.send_batch([
 ])
 ```
 
-`points` is a list of `(metric, value)` tuples. All points share the same timestamp (now, unless you pass `timestamp=t`). For independent timestamps per point, call `send()` in a loop instead.
+`points` is a list of `(metric, value)` tuples, or `(metric, value, timestamp)` 3-tuples when you need a per-point timestamp. Points without their own timestamp share the batch timestamp (now, unless you pass `timestamp=t`).
 
 ### `event(name, data)` — record a discrete occurrence
 
@@ -88,16 +88,6 @@ px.event("sensor_error", {"sensor": "imu", "code": 42}, tags={"motor": "A"})
 
 The platform displays events as markers overlaid on your telemetry charts, not as time-series lines.
 
-### `run(run_id)` — group data into a named recording
-
-```python
-with px.run("thermal-cycle-001"):
-    while running:
-        px.send("temperature", read_temp())
-```
-
-All `send()` calls inside the context are tagged with `run_id`, making it easy to isolate and replay that slice of data in the dashboard.
-
 ## Video streaming
 
 Two methods depending on whether you control the capture loop or just have a URL.
@@ -191,8 +181,8 @@ px.send("temperature", 72.5, timestamp=t)   # your timestamp, used as-is, no cor
 
 **Known limits:**
 - Clock sync refreshes on WebSocket (re)connect. A device with a drifting RTC that stays connected for many days accumulates uncorrected drift between reconnects.
-- HTTP-only transport (`transport="http"`) does not receive clock sync — timestamps default to the uncorrected device clock.
-- `send_batch()` shares one timestamp across the whole batch. For per-point timestamps, call `send()` in a loop.
+- The HTTP fallback path (used when the WebSocket is unavailable) does not receive clock sync — timestamps default to the uncorrected device clock.
+- `send_batch()` shares one timestamp across the batch by default; pass `(metric, value, timestamp)` 3-tuples for per-point timestamps.
 
 ## Transport
 
@@ -204,13 +194,12 @@ By default the SDK connects over a **WebSocket** to `/ws/device` on the gateway
 If the socket is unavailable, sends transparently fall back to `POST /ingest` so no data is lost.
 
 ```python
-# default — ws with http fallback
+# ws with transparent http fallback — this is the only mode
 px = Plexus()
-
-# force http (legacy)
-px = Plexus(transport="http")
 ```
 
+There is no transport selector: the SDK always prefers the WebSocket and falls back to `POST /ingest` on its own when the socket is unavailable.
+
 ### Handling commands
 
 Register a handler before the first `send()` so the command is advertised in the auth frame:

{plexus_python-0.8.0 → plexus_python-0.9.1}/examples/mac_metrics.py

@@ -11,7 +11,9 @@ Run:
 
 import argparse
 import time
+
 import psutil
+
 from plexus import Plexus
 
 parser = argparse.ArgumentParser(description="Stream Mac system metrics to Plexus.")

{plexus_python-0.8.0 → plexus_python-0.9.1}/examples/thermal_camera.py

@@ -53,8 +53,7 @@ def main() -> None:
         print(f"Error: {e}", file=sys.stderr)
         sys.exit(1)
 
-    px = Plexus(transport="ws")
-    px.wait_connected()
+    px = Plexus()
 
     interval = 1.0 / FPS
     frame_count = 0

{plexus_python-0.8.0 → plexus_python-0.9.1}/examples/uv.lock

@@ -1,5 +1,5 @@
 version = 1
-revision = 2
+revision = 3
 requires-python = ">=3.12"
 
 [[package]]
@@ -389,11 +389,11 @@ wheels = [
 
 [[package]]
 name = "idna"
-version = "3.13"
+version = "3.19"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/ce/cc/762dfb036166873f0059f3b7de4565e1b5bc3d6f28a414c13da27e442f99/idna-3.13.tar.gz", hash = "sha256:585ea8fe5d69b9181ec1afba340451fba6ba764af97026f92a91d4eef164a242", size = 194210, upload-time = "2026-04-22T16:42:42.314Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/5f/f7/abb373e5757eaec4b922b92f97ec8d6d7e057cf06778247604fbc4e7c3f3/idna-3.19.tar.gz", hash = "sha256:5e0811a4383b21dc5838069f801c4fb62113b7447663d2530d2bd6e77b49bf15", size = 215237, upload-time = "2026-08-18T05:14:24.27Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/5d/13/ad7d7ca3808a898b4612b6fe93cde56b53f3034dcde235acb1f0e1df24c6/idna-3.13-py3-none-any.whl", hash = "sha256:892ea0cde124a99ce773decba204c5552b69c3c67ffd5f232eb7696135bc8bb3", size = 68629, upload-time = "2026-04-22T16:42:40.909Z" },
+    { url = "https://files.pythonhosted.org/packages/57/b0/0e52c878c53f245edd3a11020f20979b3f490f245af532c7cae3027754b5/idna-3.19-py3-none-any.whl", hash = "sha256:815e7be7a7806d54abb586dc943addc79e8b2ee16915059658cbeff4b1b43bf4", size = 68550, upload-time = "2026-08-18T05:14:22.343Z" },
 ]
 
 [[package]]

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

@@ -7,8 +7,8 @@ Plexus — thin Python SDK for sending telemetry to the Plexus gateway.
     px.send("temperature", 72.5)
 """
 
-from plexus.client import Plexus, PlexusError, AuthenticationError, read_mjpeg_frames
+from plexus.client import AuthenticationError, Plexus, PlexusError, read_mjpeg_frames
 from plexus.config import RetryConfig
 
-__version__ = "0.8.0"
-__all__ = ["Plexus", "PlexusError", "AuthenticationError", "RetryConfig", "read_mjpeg_frames"]
+__version__ = "0.9.1"
+__all__ = ["AuthenticationError", "Plexus", "PlexusError", "RetryConfig", "read_mjpeg_frames"]