plexus-python 0.11.4__py3-none-any.whl → 0.11.6__py3-none-any.whl

plexus/__init__.py

@@ -23,7 +23,7 @@ from plexus.client import (
 )
 from plexus.config import RetryConfig
 
-__version__ = "0.11.4"
+__version__ = "0.11.6"
 __all__ = [
     "AuthenticationError",
     "BatchSender",

plexus/_skills/README.md

@@ -36,8 +36,9 @@ Then just ask for what you want — "send my ESP32's battery voltage to Plexus",
 An agent that has not read these invents a plausible Plexus API and gets it
 wrong in ways that fail quietly. The three that cost the most real time:
 
-- The ingest array is **`points`**, not `metrics`, and every point needs a
-  `class`. Getting this wrong is a 400 on every write.
+- The ingest array is **`points`**, not `metrics`. Getting this wrong is a
+  400 on every write. Every point should also carry a `class`: HTTP infers
+  it when missing, the WebSocket does not.
 - `timestamp` must be a **number**. An ISO-8601 string is rejected outright.
 - The query response is **columnar** — `series[m].avg[i]`, not
   `series[m][i].v`. Guessing wrong yields `undefined` with no error: an empty

plexus/_skills/plexus/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plexus
-description: Integrate with the Plexus telemetry API — send data, query metrics, subscribe to live streams, send commands to devices. Use when the user mentions Plexus, plexus.company, gateway.plexus.company, plexus-data-api.fly.dev, or plx_ API keys. ALSO USE when the request involves IoT/hardware telemetry, fleet observability, sending sensor data to a backend, querying device time-series, building a fleet dashboard, monitoring drones/satellites/robots/edge devices, or any phrase like "send my sensor readings somewhere", "store telemetry", "track a fleet", "ingest metrics", or "device observability" — even if "Plexus" is never said.
+description: Integrate with the Plexus telemetry API — send data, query metrics, subscribe to live streams. Use when the user mentions Plexus, plexus.company, gateway.plexus.company, api.plexus.company, or plx_ API keys. ALSO USE when the request involves IoT/hardware telemetry, fleet observability, sending sensor data to a backend, querying device time-series, building a fleet dashboard, monitoring drones/satellites/robots/edge devices, or any phrase like "send my sensor readings somewhere", "store telemetry", "track a fleet", "ingest metrics", or "device observability" — even if "Plexus" is never said.
 tools: Read, Write, Edit, Bash, WebFetch
 ---
 
@@ -12,8 +12,8 @@ Plexus is a telemetry/observability platform for hardware fleets (drones, satell
 
 Trigger on any of:
 
-- The user mentions "Plexus", "plexus.company", `plx_` keys, `gateway.plexus.company`, or `plexus-data-api.fly.dev`
-- The user wants to ingest telemetry, query device metrics, stream live points, or send commands to a device
+- The user mentions "Plexus", "plexus.company", `plx_` keys, `gateway.plexus.company`, or `api.plexus.company`
+- The user wants to ingest telemetry, query device metrics, or stream live points
 - The user is building a dashboard, alert pipeline, or analysis on top of fleet telemetry
 - The user pastes a Plexus curl example and asks for help
 
@@ -27,19 +27,21 @@ Two base URLs. Authenticate with an `x-api-key` header on HTTP.
 | Purpose                                            | Host                             |
 | -------------------------------------------------- | -------------------------------- |
 | Ingest                                              | `https://gateway.plexus.company` |
-| Read API (sources, metrics, logs, fleet, commands, live stream) | `https://plexus-data-api.fly.dev` |
+| Read API (sources, metrics, events, fleet, live stream) | `https://api.plexus.company` |
 
 ```
 x-api-key: plx_...
 ```
 
-The OpenAPI spec for the read API lives at `https://plexus-data-api.fly.dev/openapi.json` — fetch it when you need exact schemas. **It does not list the WebSocket endpoints** (FastAPI omits them), so use the Live section below for those.
+The OpenAPI spec for the read API lives at `https://api.plexus.company/openapi.json` — fetch it when you need exact schemas. **It does not list the WebSocket endpoints** (FastAPI omits them), so use the Live section below for those.
 
 Read keys from env, never hardcode:
 
 - `PLEXUS_API_KEY` — server / CLI
 - `NEXT_PUBLIC_PLEXUS_API_KEY` — client-side Next.js (only if the user explicitly accepts the trade-off)
 
+Keys are made at `https://app.plexus.company/api`. The optional **Limit to device slug** field binds a key to one `source_id`; the gateway then refuses it for any other source (`403` on `/ingest`). Recommend a bound key per device for hardware that ships to customers, and a fleet key only for servers you control.
+
 ## Endpoint cheat sheet
 
 ### Send (gateway)
@@ -57,13 +59,16 @@ Read keys from env, never hardcode:
 
 Per point:
 
-- **`class` is required** and must be `"metric"` or `"event"`. Omitting it is a 400.
+- **Set `class` on every point**: `"metric"` (the value must be a number) or `"event"` (string, bool, object, array). On HTTP `/ingest` a missing `class` is inferred — numbers become metrics, everything else events — but the WebSocket path rejects a point without it, and an explicit class says what you meant. The Python SDK always sets it.
 - **The array is `points`, not `metrics`.** Sending `metrics: [...]` returns `400 {"error":"'points' array is required"}`. This is the single most common mistake.
 - `metric` (string) and `value` are required.
 - `timestamp` must be a **number** — an ISO-8601 string is rejected with `points[i].timestamp must be a number`. Epoch **milliseconds** is the intended unit; a positive value under `1e12` is interpreted as **seconds** and scaled up automatically.
 - Omitting `timestamp` is safe: the point is stamped with gateway receive time. (This used to land at 1970 and be invisible — fixed, the loader now falls back to `ingested_at`.)
 - `source_id` may be set at the envelope level, per point, or both — per point wins.
 - The gateway creates the source on first write; no registration step.
+- Event limits: a string value up to 256 bytes, an object/array value up to 4,096 bytes of JSON, up to 16 tags per point. Larger is a 400.
+- **There is no log upload endpoint.** Send log lines that matter as event points, e.g. `{"class":"event","metric":"log","value":{"level":"error","msg":"..."}}` (`px.event("log", {...})` in plexus-python).
+- **Free plan:** `/ingest` works. The device WebSocket and video are refused (`streaming_requires_plan`); plexus-python falls back to HTTP by itself. Free keeps 7 days of history and up to 3 devices.
 
 `POST /api/v1/write` also exists as a Prometheus/Alloy/OTel/Telegraf remote-write receiver. Do not reach for it unless the user already runs one of those.
 
@@ -78,7 +83,7 @@ Paths are `/v1/sources/...`. `/v1/devices/...` is a deprecated alias — bare `/
 - `GET /v1/sources/{id}/metrics` → `string[]` (metric names)
 - `GET /v1/sources/{id}/metrics/latest` → `{ metrics: { [name]: number } }`
 - `GET /v1/sources/{id}/metrics/query?metrics=a,b&last=1h` → columnar, see below. Also takes `start`, `end`, `interval`.
-- `GET /v1/sources/{id}/logs?last=1h&limit=1000` → log rows (also `tail`, `name`, `start`, `end`)
+- `GET /v1/sources/{id}/events?last=1h&limit=1000` → `[{ timestamp_ms, metric, value, tags }]`, the `class: "event"` points (also `tail`, `name`, `start`, `end`). Plexus has no separate log type. `/logs` is an old alias for the same route; use `/events`.
 - `GET /v1/fleet/health` → `{ sources_total, sources_online }`
 - `GET /v1/fleet/metrics?metric=X&last=1h` → `{ metric, interval, sources_online, sources_w_metric, sources: [...], truncated }`
 
@@ -117,10 +122,10 @@ const points = s.timestamp_ms.map((t, i) => ({ t, v: s.avg[i] }));
 ### Live (data API, not the gateway)
 
 ```
-WS wss://plexus-data-api.fly.dev/v1/sources/{source_id}/metrics/stream?metrics=a,b
+WS wss://api.plexus.company/v1/sources/{source_id}/metrics/stream?metrics=a,b
 ```
 
-Also `/logs/stream` and `/video/stream` under the same source prefix.
+Also `/events/stream` (event points) and `/video/stream` under the same source prefix.
 
 **Auth is the first message, not a header.** Immediately after connect, send:
 
@@ -141,9 +146,9 @@ You do **not** need to answer application-level pings on this endpoint; keepaliv
 
 The gateway's own sockets (`/ws/device`, `/ws/browser`) are for the Python SDK and the Plexus app respectively. Don't write third-party clients against them. There is no `/v1/stream` on the gateway.
 
-### Control (data API)
+### Control
 
-`POST /v1/sources/{id}/commands` — body `{ command, params? }`, response `{ queued: bool }`. Confirm with the user before sending — these hit physical hardware.
+There is no API for sending commands to devices. `POST /v1/sources/{id}/commands` was turned off and returns `410 Gone`. Don't write code that calls it, and don't offer to trigger device behavior through the API.
 
 ## Standard scaffolding
 
@@ -202,27 +207,26 @@ let the pipeline settle first.
 
 - **Polling cadences for dashboards**: latest values 5s, charts 10s, fleet health 10s, source list 30s. Use SWR or TanStack Query with `refreshInterval`.
 - **Time ranges**: prefer `last=1h` (relative) over `start`/`end` (absolute) — easier to reason about and less timezone footgun. `start`/`end` are ISO date-times, not epoch ms.
-- **Batching ingest**: the gateway meters **messages, not points** — 500/s per WebSocket connection, 2000/s per source, up to 10,000 points in one message. Buffer up to 64 points or 5 seconds, whichever first. One send per reading at bench rates exceeds the limit and the overflow is *discarded*, reported asynchronously as `RATE_LIMITED` after the send returned. In plexus-python use `px.batch(interval_ms=50)`; `px.send()` alone is one message per call. On 429 / 5xx, exponential backoff with max 3 attempts.
+- **Batching ingest**: the gateway meters **messages, not points** — 2,000/s per WebSocket connection and per source (bursts up to 500), up to 10,000 points in one message. Buffer up to 64 points or 5 seconds, whichever first. One send per reading at bench rates exceeds the limit and the overflow is *discarded*, reported asynchronously as `RATE_LIMITED` after the send returned. In plexus-python use `px.batch(interval_ms=50)`; `px.send()` alone is one message per call. On 429 / 5xx, exponential backoff with max 3 attempts.
 - **Source IDs are slugs**: `drone-001`, `sat-alpha-3`, `bench.rig-2`. Must match `^[a-z0-9][a-z0-9._-]*$`, up to 256 characters — dots are legal and a single character is legal. A uuid-shaped slug is rejected: every resolver reads uuid-shaped refs as internal ids, so such a source would be unreachable. Stable, lowercase.
 - **Source IDs are not deduplicated.** The gateway writes whatever `source_id` you declare. Two devices declaring the same name merge into one source.
 - **Metric names are opaque and may be long.** Anything that round-trips a name must use the identical string on both sides or the series and its metadata will not join.
 
 ## Common pitfalls
 
-- **`points`, not `metrics`, on ingest**, and every point needs `class`. The two most common 400s.
+- **`points`, not `metrics`, on ingest.** The most common 400. Set `class` on every point too: HTTP infers it when missing, the WebSocket does not, and `class: "metric"` with a non-numeric value is a 400.
 - **Numeric timestamps only.** ISO strings 400. Milliseconds unless the value is under `1e12`, in which case it's read as seconds.
 - **The query response is columnar.** `series[m].avg[i]`, not `series[m][i].v`. Reaching for `.t`/`.v` yields `undefined` and an empty chart with no error.
 - **The live stream is on the data API, and auths by first message.** There is no `/v1/stream` on the gateway.
 - **Telemetry frames are batched** — `points` is an array. Handling one frame as one point silently drops data.
-- `start`/`end` are **ISO date-times on every endpoint** that takes them — `query`, `logs` and `fleet/metrics` alike. `last=1h` is easier and works on all three.
+- `start`/`end` are **ISO date-times on every endpoint** that takes them — `query`, `events` and `fleet/metrics` alike. `last=1h` is easier and works on all three.
 - `auto_downsampled: true` in a query response means the bucket size was picked for you — surface it in the UI so users understand what they're looking at.
-- Commands queue on the device; they don't execute synchronously. Don't promise the user "it rebooted" — promise "reboot queued".
 
 ## When unsure
 
-Fetch `https://plexus-data-api.fly.dev/openapi.json` for the authoritative HTTP schema (it will not show WebSocket routes), and check a real response before writing parsing code. `scripts/verify_skills.py` in this repo checks these docs against the live spec — run it if something here looks stale.
+Fetch `https://api.plexus.company/openapi.json` for the authoritative HTTP schema (it will not show WebSocket routes), and check a real response before writing parsing code. `scripts/verify_skills.py` in this repo checks these docs against the live spec — run it if something here looks stale.
 
 This cheat sheet has drifted before. Corrected 2026-09-01 against the shipped
 gateway and app (runs API — which an earlier revision of API.md wrongly said did
 not exist; message-not-point metering and `px.batch()`; the real slug rule,
-which permits dots, single characters and 256 bytes). Corrected 2026-08-27 against Data API 0.1.0 (ingest array name, `sources`/`devices` paths, removed per-source health, columnar query) and again 2026-08-28 against gateway + API source (the live-stream host/path/auth/frame shape, the required `class` field, numeric-only timestamps, the redirect chain, and the now-fixed 1970 timestamp behavior).
+which permits dots, single characters and 256 bytes). Corrected 2026-08-27 against Data API 0.1.0 (ingest array name, `sources`/`devices` paths, removed per-source health, columnar query) and again 2026-08-28 against gateway + API source (the live-stream host/path/auth/frame shape, the required `class` field, numeric-only timestamps, the redirect chain, and the now-fixed 1970 timestamp behavior). Corrected 2026-09-22: the read API host is `api.plexus.company`; `class` is inferred on HTTP `/ingest` (not a 400) but required on the WebSocket; key binding to one source; Free-plan WebSocket refusal; event size limits; no log upload.

plexus/_skills/plexus-dashboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plexus-dashboard
-description: Scaffold a working web dashboard against the Plexus telemetry API — device picker, latest-value tiles, time-series charts, log viewer. Use when the user wants to build a frontend, dashboard, ops UI, mission control, or fleet view on top of Plexus data. Triggering phrases include "show me my drones/satellites/robots", "build a dashboard for my fleet", "vibe code a Plexus frontend", "fleet monitoring UI", "telemetry dashboard", "device status page", "live charts of sensor data", or "ops view for my hardware" — even if "Plexus" is never said, as long as the data source is the Plexus API.
+description: Scaffold a working web dashboard against the Plexus telemetry API — device picker, latest-value tiles, time-series charts, event viewer. Use when the user wants to build a frontend, dashboard, ops UI, mission control, or fleet view on top of Plexus data. Triggering phrases include "show me my drones/satellites/robots", "build a dashboard for my fleet", "vibe code a Plexus frontend", "fleet monitoring UI", "telemetry dashboard", "device status page", "live charts of sensor data", or "ops view for my hardware" — even if "Plexus" is never said, as long as the data source is the Plexus API.
 tools: Read, Write, Edit, Bash, WebFetch
 ---
 
@@ -37,7 +37,7 @@ Dashboard
 └─ Detail pane
    ├─ Tile row: every metric from /metrics/latest as a big-number card
    ├─ Chart grid: one line chart per metric over the last 1h via /metrics/query
-   └─ (Optional) Log pane: /logs in a virtualized list
+   └─ (Optional) Event pane: /events (event points: faults, state changes, log lines) in a virtualized list
 ```
 
 ## Polling cadences
@@ -71,7 +71,7 @@ Ask exactly two questions, no more:
 Create `src/lib/plexus.ts`:
 
 ```ts
-const BASE = "https://plexus-data-api.fly.dev";
+const BASE = "https://api.plexus.company";
 const KEY = process.env.NEXT_PUBLIC_PLEXUS_API_KEY!;
 
 export class PlexusError extends Error {
@@ -158,7 +158,7 @@ export function subscribeMetrics(
 ) {
   const qs = metrics.length ? `?metrics=${metrics.join(",")}` : "";
   const ws = new WebSocket(
-    `wss://plexus-data-api.fly.dev/v1/sources/${sourceId}/metrics/stream${qs}`,
+    `wss://api.plexus.company/v1/sources/${sourceId}/metrics/stream${qs}`,
   );
 
   // Auth is the FIRST MESSAGE, not a header. Send it within 10s or the
@@ -199,6 +199,6 @@ Wire it alongside SWR: keep `useSWR` for initial load (UI hydrates with a value
 
 ## When unsure about endpoint shapes
 
-`https://plexus-data-api.fly.dev/openapi.json` is the source of truth for HTTP. It does **not** list WebSocket routes — the generic `plexus` skill documents those.
+`https://api.plexus.company/openapi.json` is the source of truth for HTTP. It does **not** list WebSocket routes — the generic `plexus` skill documents those.
 
-Corrected 2026-08-28: `/v1/devices` → `/v1/sources`, removed the non-existent per-source health endpoint, fixed the columnar query type, and replaced the live-stream section (the old `wss://gateway.plexus.company/v1/stream` 404s, and the "browsers can't authenticate" caveat no longer holds).
+Corrected 2026-08-28: `/v1/devices` → `/v1/sources`, removed the non-existent per-source health endpoint, fixed the columnar query type, and replaced the live-stream section (the old `wss://gateway.plexus.company/v1/stream` 404s, and the "browsers can't authenticate" caveat no longer holds). Corrected 2026-09-22: the read API host is `api.plexus.company`.

plexus/_skills/plexus-firmware/SKILL.md

@@ -14,7 +14,7 @@ Adds a small, well-behaved Plexus ingest client to device-side code. Optimized f
 - Targets include: ESP32 / Arduino / RP2040, Raspberry Pi, NVIDIA Jetson, embedded Linux gateways, drone autopilot companion computers, satellite OBC software
 - Languages: C / C++, MicroPython, CPython, Rust, Go (for edge gateways)
 
-**If the target runs CPython (Pi, Jetson, any embedded Linux with room), stop and use the SDK instead** — `pip install plexus-python`, then `Plexus(api_key=..., source_id=...)`. It handles backoff, store-and-forward buffering and the WebSocket transport. Hand-rolling is for targets the SDK can't reach.
+**If the target runs CPython (Pi, Jetson, any embedded Linux with room), stop and use the SDK instead** — `pip install plexus-python`, then `Plexus(api_key=..., source_id=...)`. It handles backoff, store-and-forward buffering and the WebSocket transport, and falls back to HTTP on its own (including on the Free plan, where the gateway refuses the device WebSocket). Hand-rolling is for targets the SDK can't reach.
 
 **`send()` does NOT batch.** Every call is its own message on the wire, and the ceiling below counts messages. Above a few readings a second, use `px.batch()`:
 
@@ -56,12 +56,14 @@ Response:
   { "success": true, "count": 2, "source_id": "drone-001" }
 ```
 
-Four things the gateway will reject you for. Get these right or nothing lands:
+Three things the gateway will reject you for, and one to always set. Get these right or nothing lands:
 
 1. **The array is `points`.** `"metrics": [...]` returns `400 {"error":"'points' array is required"}`.
-2. **Every point needs `class`**, either `"metric"` or `"event"`. There is no default.
-3. **`timestamp` is a number, never a string.** An ISO-8601 string returns `points[i].timestamp must be a number`. Epoch **milliseconds**; a positive value below `1e12` is read as **seconds** and scaled for you, so either unit works as long as it's numeric.
-4. **`source_id` must match `^[a-z0-9][a-z0-9._-]*$` (max 256 chars)** and is not deduplicated — two devices declaring the same id merge into one source. This is what SD-card clones do when they all boot as `raspberrypi`.
+2. **`timestamp` is a number, never a string.** An ISO-8601 string returns `points[i].timestamp must be a number`. Epoch **milliseconds**; a positive value below `1e12` is read as **seconds** and scaled for you, so either unit works as long as it's numeric.
+3. **`source_id` must match `^[a-z0-9][a-z0-9._-]*$` (max 256 chars)** and is not deduplicated — two devices declaring the same id merge into one source. This is what SD-card clones do when they all boot as `raspberrypi`.
+4. **Set `class` on every point**: `"metric"` for numbers, `"event"` for strings, bools, objects and arrays. HTTP `/ingest` infers it when missing (numbers → metric, anything else → event), but the WebSocket rejects a point without it, and `"class": "metric"` on a non-number is a 400. Set it explicitly.
+
+Events are for faults, state changes and log lines. There is no log upload: send the lines that matter as `{"class":"event","metric":"log","value":{"level":"error","msg":"..."}}`. Limits: a string value up to 256 bytes, an object/array value up to 4,096 bytes of JSON, up to 16 tags.
 
 `timestamp` is optional. Omit it and the gateway stamps the point with its receive time — which is the right move on a device whose clock has never been NTP-synced. Per-point `tags` (a flat string→string map) are supported and optional.
 
@@ -77,12 +79,12 @@ decides whether you hit a limit:
 
 | Limit | Value |
 | --- | --- |
-| Telemetry messages per WebSocket connection | 500/s sustained, 2000 burst |
-| Hard ceiling per source (WS and HTTP) | 2000 messages/s |
+| Telemetry messages per WebSocket connection | 2,000/s |
+| Hard ceiling per source (WS and HTTP) | 2,000 messages/s, bursts up to 500 |
 | Points per message | 10,000 |
 | Body size | 1 MB (WS) / 5 MB (HTTP) |
 
-Eight channels at 100 Hz sent one at a time is 800 messages/s — over the limit,
+25 channels at 100 Hz sent one at a time is 2,500 messages/s — over the limit,
 and **the overflow is discarded**. Batched every 50 ms it is 20 messages/s.
 
 Over the limit the gateway drops the whole message and answers `RATE_LIMITED`,
@@ -118,6 +120,7 @@ The `source_id` must be stable across reboots **and unique across the fleet**. U
 - ESP32 / Arduino: NVS / preferences storage, **not** hardcoded in firmware
 - Raspberry Pi / Linux: `/etc/plexus/key` with mode 0600, or env var
 - Never compile keys into a binary that ships to multiple devices — one leak compromises the fleet
+- For devices in customer hands, give each one its own key made at `https://app.plexus.company/api` with **Limit to device slug** set to its `source_id`. The gateway refuses that key for any other source (`403`), so a key pulled off one unit cannot write as the rest of the fleet
 
 ### 5. Bound memory
 
@@ -142,7 +145,7 @@ _lock = _thread.allocate_lock()
 def emit(metric, value):
     """Called from sensor-read context. Cheap — just appends to a buffer."""
     with _lock:
-        # class is REQUIRED. timestamp must be a NUMBER (epoch ms) — omit it
+        # Always set class. timestamp must be a NUMBER (epoch ms) — omit it
         # entirely if this board has never NTP-synced and the gateway will
         # stamp it on receive.
         _buf.append({
@@ -203,10 +206,12 @@ Use the SDK — `pip install plexus-python` — unless there's a reason not to:
 from plexus import Plexus
 
 px = Plexus(api_key=os.environ["PLEXUS_API_KEY"], source_id="pi-fieldunit-03")
-px.send("battery.voltage", 11.8)          # class=metric, batched for you
+px.send("battery.voltage", 11.8)          # class=metric, one message per call
 px.event("fault", "undervoltage lockout")  # class=event
 ```
 
+`send()` does not batch. Above a few readings a second, use `with px.batch(interval_ms=50) as b:` as shown at the top.
+
 If you must hand-roll: `requests` with a `Session` for connection pooling, same batching + backoff rules, key from `os.environ["PLEXUS_API_KEY"]`, flush on a background thread on a 5-second tick.
 
 ### C (ESP-IDF / generic embedded)
@@ -247,11 +252,13 @@ If they see `{"success":true,"count":1,"source_id":"test-laptop"}`, auth + conne
 
 ```bash
 curl -H "x-api-key: $PLEXUS_API_KEY" \
-  https://plexus-data-api.fly.dev/v1/sources/test-laptop/metrics/latest
+  https://api.plexus.company/v1/sources/test-laptop/metrics/latest
 ```
 
 ## When unsure
 
-The ingest contract above is the authority for the device side. For reading data back, fetch `https://plexus-data-api.fly.dev/openapi.json` or use the generic `plexus` skill.
+The ingest contract above is the authority for the device side. For reading data back, fetch `https://api.plexus.company/openapi.json` or use the generic `plexus` skill.
 
 Corrected 2026-08-28 against gateway source (`ingest.go`, `validate.go`): the array is `points` not `metrics`, `class` is required, timestamps must be numeric, and the response is `{success, count, source_id}`. Every template in the previous version of this file would have 400'd.
+
+Corrected 2026-09-22: `class` is inferred on HTTP `/ingest` when missing (it was documented as a 400) but is required on the WebSocket, so set it anyway; per-device keys via "Limit to device slug"; the read API host is `api.plexus.company`; `px.send()` is one message per call, not batched.

plexus/batching.py

@@ -2,11 +2,10 @@
 
 `px.send()` transmits immediately: every call is its own WebSocket frame. That
 is the right shape for a script sampling a sensor once a second, and the wrong
-one for a test bench. The gateway allows 500 telemetry messages per second on a
-connection and hard-drops a source above 2000/s, and both ceilings count
-*messages*, not points — so eight channels at 100 Hz is 800 frames/s and lands
-over the limit, while the same 800 readings coalesced into ten frames is not
-close to it. The dropped frames come back as `RATE_LIMITED`, after `send()` has
+one for a test bench. The gateway allows 2,000 telemetry messages per second on
+a connection and per source, and the ceiling counts *messages*, not points — so
+25 channels at 100 Hz is 2,500 frames/s and lands over the limit, while the same
+2,500 readings coalesced into ten frames is not close to it. The dropped frames come back as `RATE_LIMITED`, after `send()` has
 already returned True, which is why this is a batching problem rather than a
 retry one: by the time anyone can react, the points are gone.
 

plexus/client.py

@@ -182,8 +182,8 @@ class RateLimitedError(PlexusError):
 # The wire slug rule (gateway validate.go sourceIDPattern, max length =
 # MaxStringLen 256) — the old stricter local regex rejected dots, 1-char and
 # >63-char slugs that the gateway accepts. Uuid-shaped slugs are additionally
-# rejected (TypeScript SDK parity): the Plexus app resolves uuid-shaped refs
-# as internal ids, which would make such a source unreachable.
+# rejected: the Plexus app resolves uuid-shaped refs as internal ids, which
+# would make such a source unreachable.
 _SOURCE_ID_RE = re.compile(r'^[a-z0-9][a-z0-9._-]*$')
 _SOURCE_ID_UUID_RE = re.compile(
     r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
@@ -271,7 +271,7 @@ class Plexus:
         if not self.api_key:
             raise ValueError(
                 "No API key. Pass api_key=... or set PLEXUS_API_KEY. "
-                "Get a key at app.plexus.company/devices."
+                "Get a key at app.plexus.company/api."
             )
 
         self.endpoint = (endpoint or get_endpoint()).rstrip("/")
@@ -372,9 +372,9 @@ class Plexus:
     def _infer_class(value: FlexValue) -> str:
         """Numbers are metrics; everything else (str/bool/dict/list) is an event.
 
-        Mirrors the gateway (ingest.go inferClass) and the TypeScript SDK
-        (wire.ts inferClass). bool is a subclass of int in Python, so it must
-        be excluded explicitly or True/False would wrongly become metrics.
+        Mirrors the gateway, which infers class the same way on HTTP /ingest
+        (ingest.go). bool is a subclass of int in Python, so it must be
+        excluded explicitly or True/False would wrongly become metrics.
         """
         return "metric" if isinstance(value, (int, float)) and not isinstance(value, bool) else "event"
 
@@ -543,9 +543,9 @@ class Plexus:
 
         Use this whenever readings arrive faster than a few times a second.
         `send()` puts every reading in its own WebSocket frame, and the gateway
-        limits *frames*, not points — so eight channels at 100 Hz is 800
-        frames/s against a 500/s ceiling, and the overflow is discarded.
-        Batched, the same 800 readings/s is 10 frames/s.
+        limits *frames*, not points — so 25 channels at 100 Hz is 2,500
+        frames/s against a 2,000/s ceiling, and the overflow is discarded.
+        Batched, the same 2,500 readings/s is 10 frames/s.
 
             with px.batch(interval_ms=50) as b:
                 while running:

{plexus_python-0.11.4.dist-info → plexus_python-0.11.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plexus-python
-Version: 0.11.4
+Version: 0.11.6
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.company
 Project-URL: Documentation, https://docs.plexus.company
@@ -55,7 +55,9 @@ px = Plexus(api_key="plx_xxx", source_id="device-001")
 px.send("temperature", 72.5)
 ```
 
-Get an API key at [app.plexus.company](https://app.plexus.company) → Devices → Add Device.
+Get an API key at [app.plexus.company/api](https://app.plexus.company/api), or run `plexus init` to authorize the machine in a browser.
+
+When you create a key there, you can fill in **Limit to device slug**. That key can then only send as that one `source_id`; the gateway refuses it for any other. Use one of these for every device you put in a customer's hands, so a key pulled off one unit cannot write as the rest of your fleet.
 
 ## Device identity
 
@@ -66,7 +68,7 @@ curl -sL https://app.plexus.company/setup | bash -s -- \
   --key plx_xxx --name drone-01
 ```
 
-The name must match `^[a-z0-9][a-z0-9._-]*$` (max 256 chars). `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`.
+The name is turned into the device's `source_id`, which must match `^[a-z0-9][a-z0-9._-]*$` (max 256 chars). Pass `--name` every time. Without it, and without `source_id=...` in code, the SDK makes up a random id like `source-1a2b3c4d` on first run and saves it to `~/.plexus/config.json`. Don't use the hostname: cloned SD-card images all boot as `raspberrypi`, and their telemetry merges into one source.
 
 **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.
 
@@ -115,7 +117,7 @@ px.send_batch([
 
 ### `batch()` — coalesce a fast stream of readings
 
-Use this above a few readings per second. Every `send()` is one WebSocket message, and the gateway limits **messages**, not points — 500/s on a connection. Eight channels at 100 Hz sent one at a time is 800 messages/s, and the overflow is discarded before it is stored.
+Use this above a few readings per second. Every `send()` is one WebSocket message, and the gateway limits **messages**, not points — 2,000/s on a connection. 25 channels at 100 Hz sent one at a time is 2,500 messages/s, and the overflow is discarded before it is stored.
 
 ```python
 with px.batch(interval_ms=50) as b:
@@ -154,10 +156,24 @@ 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.
 
+Limits per event: a string value up to 256 bytes, a dict or list value up to 4,096 bytes of JSON, and up to 16 tags. The gateway rejects anything larger.
+
+### Logs
+
+There is no log-file upload and no `logging.Handler` in this package. To get important log lines into Plexus, send them as events:
+
+```python
+px.event("log", {"level": "error", "msg": "IMU read timed out"})
+```
+
+Forward the lines you would want on the timeline next to your telemetry (errors, warnings, state changes), not every debug line. Each call is one message, and the gateway limits messages (see [`batch()`](#batch--coalesce-a-fast-stream-of-readings)).
+
 ## Video streaming
 
 Two methods depending on whether you control the capture loop or just have a URL.
 
+Video needs a paid plan: frames go over the WebSocket, which the gateway refuses on the Free plan. Frames are relayed live to anyone watching. They are stored only when someone presses **Record** in the app, for up to 4 hours per recording.
+
 ### `send_video_frame(frame, camera_id)` — send frames you capture yourself
 
 Use this when your code owns the capture loop — a `picamera2` callback, an OpenCV `VideoCapture` loop, or an FFmpeg pipe you manage. Pass each frame and the SDK ships it to Plexus over WebSocket.
@@ -219,10 +235,10 @@ See [`examples/`](examples/) for runnable versions of each.
 
 ## Reliability
 
-Every send buffers locally before hitting the network, retries with exponential backoff, and keeps your data safe across outages. Enable SQLite persistence to survive restarts and power loss:
+Every send buffers locally before hitting the network, retries with exponential backoff, and keeps your data safe across outages. The buffer is on disk (SQLite) by default, so it survives restarts and power loss. To keep it in memory only:
 
 ```python
-px = Plexus(persistent_buffer=True)
+px = Plexus(persistent_buffer=False)
 ```
 
 Point counts and flush:
@@ -255,7 +271,7 @@ px.send("temperature", 72.5, timestamp=t)   # your timestamp, used as-is, no cor
 By default the SDK connects over a **WebSocket** to `/ws/device` on the gateway — the gateway's device wire protocol. This gives you:
 
 - lower-latency streaming of telemetry,
-- live command delivery from the UI / API to the device.
+- the channel that will carry actions triggered from a Plexus dashboard.
 
 If the socket is unavailable, sends transparently fall back to `POST /ingest` so no data is lost.
 
@@ -266,6 +282,10 @@ px = Plexus()
 
 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.
 
+Either way, plain `px.send()` is one message per call; it does not batch. `px.send_batch()` sends one list as one message, and `px.batch()` groups a fast stream for you in the background.
+
+**On the Free plan** the gateway refuses the device WebSocket (`streaming_requires_plan`). The SDK falls back to HTTP by itself, so `send()`, `send_batch()`, `batch()` and `event()` all still work. Live streaming and video need a paid plan. Free also caps you at 3 devices and 7 days of history.
+
 ### Handling commands
 
 Register a handler before the first `send()` so the command is advertised in the auth frame:
@@ -283,6 +303,8 @@ px.send("temperature", 72.5)   # opens the socket, waits for auth
 
 The SDK sends an `ack` frame before invoking the handler, then a `result` frame with whatever the handler returns (or an `error` frame if it raises).
 
+> **Note:** nothing in Plexus can currently trigger a custom handler. The API route for sending commands was turned off on 2026-09-21. Triggering handlers from a dashboard, with permissions and a record of every run, is being rebuilt.
+
 ## Environment Variables
 
 | Variable                | Description                  | Default                          |
@@ -308,7 +330,7 @@ credentials. See [skills/README.md](skills/README.md).
 ## Architecture
 
 ```
-Your code ── px.send() ── HTTP POST /ingest ──> plexus-gateway ──> ClickHouse + Dashboard
+Your code ── px.send() ── WebSocket /ws/device (or HTTP POST /ingest) ──> plexus-gateway ──> ClickHouse + Dashboard
 ```
 
 One thin path. No agent, no daemon, no adapters. If you want the full HardwareOps platform — dashboards, alerts, RCA, fleet views — that's the web UI at app.plexus.company. This package gets your data there.

plexus_python-0.11.6.dist-info/RECORD

@@ -0,0 +1,19 @@
+plexus/__init__.py,sha256=71KGed-vePAvaK-OaC6gPUX4JDY_OUbtxwbvvk8EKv8,808
+plexus/_log.py,sha256=3fjXrHFZghQ_17umMcvDUjjTH6aTQB3J4SpVDBiH03w,335
+plexus/batching.py,sha256=s0ipaQTMPIW9d6VOwSLpmMSvbYF1o5WIJ06jlFezVfk,10432
+plexus/buffer.py,sha256=UNv_jEcrDwbkjJ6uhCehb7uBI2EuFEwO40waDpZn_5I,9579
+plexus/cli.py,sha256=YFkptze8LRc6mBmDgbsTeU8J6i8MMsdTWvtm3jCINiI,21773
+plexus/client.py,sha256=agPH8_nBdfL4SA6OUKJcP8RnBNHSTSm2aqt2GW95UGo,53834
+plexus/config.py,sha256=RuDh5UdVGdVQld5kQlXZO6CVXO4tS0HBalyaoAlXNvc,4416
+plexus/ws.py,sha256=xQhJCOizX-V34tF3-r7Zpzs_wnBbNSCeEoZeFFXWH7E,19763
+plexus/cameras/__init__.py,sha256=AVu1vE1xfYk9lz1cprHlTfi0ieHf84UhQh9Z92E05b8,490
+plexus/cameras/thermal.py,sha256=-klCEJQG5GlLtELaowWOPYomwMsLK8O5pmmX0PqUrTA,12022
+plexus/_skills/README.md,sha256=yOJCcwIjzwk3g6EJkzkkTaSU7l1axOaqHj0UYRyzdg4,3306
+plexus/_skills/plexus/SKILL.md,sha256=E-csIYsMMiipqK-5pYWRgFtxzY6MZBPfNgXmrtpBRRo,15088
+plexus/_skills/plexus-dashboard/SKILL.md,sha256=qJJVsFbkZe1LqnsfaNPxMFS1BWqm_VqztLv33g7tZ3M,9613
+plexus/_skills/plexus-firmware/SKILL.md,sha256=jx9noI4P6mY9pXMKLNBIw6tVuAVipeU_w2L1vwXBdRM,13420
+plexus_python-0.11.6.dist-info/METADATA,sha256=37ryJgYdD1rz4CyQbQyGkjbVgtQtTBATBOwrHHb5vhY,15667
+plexus_python-0.11.6.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+plexus_python-0.11.6.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
+plexus_python-0.11.6.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
+plexus_python-0.11.6.dist-info/RECORD,,

{plexus_python-0.11.4.dist-info → plexus_python-0.11.6.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.32.0
+Generator: hatchling 1.32.4
 Root-Is-Purelib: true
 Tag: py3-none-any

plexus_python-0.11.4.dist-info/RECORD

@@ -1,19 +0,0 @@
-plexus/__init__.py,sha256=3108jW9HO6oLnblXhpp7gpqyL2ZAE7uaMC5F18gwQ5c,808
-plexus/_log.py,sha256=3fjXrHFZghQ_17umMcvDUjjTH6aTQB3J4SpVDBiH03w,335
-plexus/batching.py,sha256=mPMa3m9xK-DCwRmuyL_aqaTltimIOtwoDzz4PfKWyh8,10452
-plexus/buffer.py,sha256=UNv_jEcrDwbkjJ6uhCehb7uBI2EuFEwO40waDpZn_5I,9579
-plexus/cli.py,sha256=YFkptze8LRc6mBmDgbsTeU8J6i8MMsdTWvtm3jCINiI,21773
-plexus/client.py,sha256=H69DR30pj3X8PiURZsViGTDHsIsQ2Kn4muHNECsioKw,53865
-plexus/config.py,sha256=RuDh5UdVGdVQld5kQlXZO6CVXO4tS0HBalyaoAlXNvc,4416
-plexus/ws.py,sha256=xQhJCOizX-V34tF3-r7Zpzs_wnBbNSCeEoZeFFXWH7E,19763
-plexus/cameras/__init__.py,sha256=AVu1vE1xfYk9lz1cprHlTfi0ieHf84UhQh9Z92E05b8,490
-plexus/cameras/thermal.py,sha256=-klCEJQG5GlLtELaowWOPYomwMsLK8O5pmmX0PqUrTA,12022
-plexus/_skills/README.md,sha256=9TNo9mssmBiBPkrYBiA2JJHWOIAEw6DvCWCYAvfzmjM,3243
-plexus/_skills/plexus/SKILL.md,sha256=Q1ZYe9YH-gOhMcGYuMG5H9DkHMfQOr3OazCtlxtP9f8,13617
-plexus/_skills/plexus-dashboard/SKILL.md,sha256=8xjdvI3orM31XHTLv1fSAWstCGMwt1HnEbo0SlpTxV4,9508
-plexus/_skills/plexus-firmware/SKILL.md,sha256=C5tOGu0_LOb76n8US2SLpWSdZdeHQIa4e_5fvkX4DGU,12093
-plexus_python-0.11.4.dist-info/METADATA,sha256=wu8laMoqY4e-3NtQbbma-LQFg4C0C6f0-1MwVzskasY,13532
-plexus_python-0.11.4.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-plexus_python-0.11.4.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
-plexus_python-0.11.4.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
-plexus_python-0.11.4.dist-info/RECORD,,