plexus-python 0.11.0__tar.gz → 0.11.1__tar.gz

{plexus_python-0.11.0 → plexus_python-0.11.1}/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 ## [Unreleased]
 
+## [0.11.1] - 2026-09-02 - Correct what the agent skills teach
+
+### Fixed
+
+- **`plexus-firmware` claimed the SDK batches. It does not.** Of CPython
+  targets — naming Jetson and embedded Linux specifically — the skill said
+  "stop and use the SDK instead ... It already does batching". `send()` is one
+  message per call, the gateway's ceiling counts messages, and the overflow is
+  discarded asynchronously after the send returned True. The skills are how a
+  coding agent learns this API instead of inventing it, so that line aimed
+  agents at silent data loss on exactly the hardware most likely to hit bench
+  rates. Both skills now carry the real ceilings and point at `px.batch()`.
+
+- **Runs were documented in no skill**, so an agent had no way to know a test
+  bench should name its window. The `plexus` skill now carries the contract:
+  the app host rather than the gateway, offset-bearing timestamps, the
+  operators, and the two semantics that surprise people — every sample must
+  satisfy a criterion, and a metric with no data in the window fails rather
+  than passes.
+
+- **The documented slug rule was wrong** (`^[a-z0-9][a-z0-9_-]{1,62}$`). The
+  gateway accepts dots, single characters and 256 bytes, so an agent applying
+  the documented rule would reject slugs the platform takes.
+
 ## [0.11.0] - 2026-09-01 - Batching, runs, and an end to silent drops
 
 ### Added

{plexus_python-0.11.0 → plexus_python-0.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plexus-python
-Version: 0.11.0
+Version: 0.11.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

{plexus_python-0.11.0 → plexus_python-0.11.1}/plexus/__init__.py

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

{plexus_python-0.11.0 → plexus_python-0.11.1}/pyproject.toml

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

{plexus_python-0.11.0 → plexus_python-0.11.1}/skills/plexus/SKILL.md

@@ -156,12 +156,54 @@ When asked to "set up Plexus" in a project, do this:
 5. **Add a single usage example** in the project — one obvious place, not five — so they can verify it works.
 6. **Update README** with a short section: "Set `PLEXUS_API_KEY`, then run X."
 
+## Runs
+
+A **run** is a named time window on a source — a hot-fire, a bench sequence, a
+flight. Runs are recalled on `/runs`, compared against each other aligned at
+T+0, and evaluated against declared pass criteria on close. Test-bench software
+should open one when a test starts and close it when the test ends, rather than
+expecting somebody to drag a time picker afterwards.
+
+These live on the **app** host (`https://app.plexus.company`), not the gateway,
+and take the same `x-api-key`.
+
+```
+POST  /api/runs           {name, source_id, started_at, pass_criteria?, tags?}
+PATCH /api/runs/{id}      {status: "completed"|"aborted", ended_at}
+GET   /api/runs           ?source_id=&status=
+```
+
+`started_at` / `ended_at` are ISO-8601 **with an offset** (`...Z` is fine); a
+naive local timestamp is a 400.
+
+In plexus-python (>= 0.11.0) this is `px.start_run()` / `px.end_run()`, or:
+
+```python
+with px.run("hotfire-03", pass_criteria=[
+    {"metric": "motor.temp_c", "operator": "<", "value": 85},
+]):
+    bench.execute()
+```
+
+An exception leaving the block closes the run `aborted`; a clean exit closes it
+`completed`.
+
+**Pass criteria** are `{metric, operator, value, label?}` with operator one of
+`> >= < <= = !=`. On close, every sample of that metric inside the window is
+checked. A criterion passes only if *all* of them satisfy it — one excursion
+fails it — and a criterion whose metric has no data in the window **fails**
+rather than passing. The verdict lands on the run's `test_result`.
+
+Criteria are evaluated against stored telemetry, which trails ingest by a few
+seconds. A run closed the instant its last point is sent may read "no data";
+let the pipeline settle first.
+
 ## Idioms
 
 - **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**: buffer up to 64 points or 5 seconds, whichever first. On 429 / 5xx, exponential backoff with max 3 attempts.
-- **Source IDs are slugs**: `drone-001`, `sat-alpha-3`. Must match `^[a-z0-9][a-z0-9_-]{1,62}$`. Stable, lowercase, hyphenated. Don't use UUIDs in user-facing surfaces.
+- **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.
+- **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.
 
@@ -180,4 +222,7 @@ When asked to "set up Plexus" in a project, do this:
 
 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.
 
-This cheat sheet has drifted before. 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).
+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).

{plexus_python-0.11.0 → plexus_python-0.11.1}/skills/plexus-firmware/SKILL.md

@@ -14,11 +14,29 @@ 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=...).send("temp", 72.5)`. It already does batching, backoff, and buffering. 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. 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()`:
+
+```python
+with px.batch(interval_ms=50) as b:      # one message per interval
+    while running:
+        b.send("imu.accel_x", imu.x)     # same signature as px.send()
+        b.send("imu.accel_y", imu.y)
+```
+
+Leaving the block flushes what is queued, and readings keep the timestamp they were taken at. Requires plexus-python >= 0.11.0.
 
 For **server-side ingestion** (a backend collecting metrics and forwarding), the generic `plexus` skill is fine.
 For **dashboards / UI**, use `plexus-dashboard`.
 
+**On a test bench, open a run.** Software driving a test should name its window
+rather than leave someone to find it on a chart later: `POST /api/runs` when the
+test starts, `PATCH /api/runs/{id}` with `status` and `ended_at` when it ends
+(app host, same `x-api-key`), or `with px.run(...)` from plexus-python. Declared
+`pass_criteria` are evaluated against every sample in the window on close. See
+the `plexus` skill for the contract.
+
 ## The ingest contract
 
 ```
@@ -53,7 +71,26 @@ Every firmware integration must do these. Skip any of them and you'll lose data
 
 ### 1. Batch
 
-Never POST one point at a time. Buffer until **64 points OR 5 seconds**, whichever first, then flush. Constants worth exposing:
+**The gateway meters messages, not points.** One request carrying 200 points costs
+exactly what one carrying 1 costs, so the shape of your sends — not their volume —
+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 |
+| 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,
+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`,
+which arrives *after* the send returned. Those points cannot be recovered, so
+this is a batching problem, not a retry one.
+
+Never POST one point at a time. Buffer until **64 points OR 5 seconds**, whichever
+first, then flush. Constants worth exposing:
 
 ```c
 #define PLEXUS_BATCH_SIZE   64

{plexus_python-0.11.0 → plexus_python-0.11.1}/uv.lock

@@ -425,7 +425,7 @@ wheels = [
 
 [[package]]
 name = "plexus-python"
-version = "0.11.0"
+version = "0.11.1"
 source = { editable = "." }
 dependencies = [
     { name = "websocket-client" },