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

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

@@ -2,6 +2,49 @@
 
 ## [Unreleased]
 
+## [0.11.2] - 2026-09-02 - Stamp run boundaries on the server's clock
+
+### Fixed
+
+- **A run's window was measured by a different clock than the points inside
+  it.** `_normalize_ts_ms` corrects generated timestamps by the offset the
+  gateway reports on connect; `start_run` / `end_run` read the local clock
+  instead. Every point taken in the final `offset` milliseconds of a run
+  therefore landed *after* `ended_at` and fell outside the window its own run
+  was evaluated over.
+
+  Measured on production: a device running 58ms behind the server sent 300
+  points and its run was judged on 284 of them. The shortfall reads exactly
+  like ingest lag, which is what it was mistaken for — a pass criterion can
+  come back green because the excursion that would have failed it was outside
+  the window by 58 milliseconds. Run boundaries now carry the same correction
+  as the telemetry. An explicitly passed `started_at` / `ended_at` is still
+  left alone.
+
+## [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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plexus-python
-Version: 0.11.0
+Version: 0.11.2
 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.2}/plexus/__init__.py

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

{plexus_python-0.11.0 → plexus_python-0.11.2}/plexus/client.py

@@ -60,10 +60,12 @@ if TYPE_CHECKING:  # pragma: no cover - typing only
 logger = logging.getLogger(__name__)
 
 
-def _utc_now_iso() -> str:
-    """Now as ISO-8601 with a Z offset — the shape /api/runs validates."""
-    return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace(
-        "+00:00", "Z"
+def _iso_from_ms(ms: int) -> str:
+    """Epoch milliseconds as ISO-8601 with a Z offset — /api/runs validates the shape."""
+    return (
+        datetime.fromtimestamp(ms / 1000, timezone.utc)
+        .isoformat(timespec="milliseconds")
+        .replace("+00:00", "Z")
     )
 
 
@@ -350,6 +352,22 @@ class Plexus:
             return int(timestamp * 1000)
         return int(timestamp)
 
+    def _now_iso(self) -> str:
+        """Now on the SERVER's clock, as ISO-8601.
+
+        Run boundaries have to be stamped on the same clock as the telemetry
+        they bound, and `_normalize_ts_ms` corrects generated timestamps by the
+        offset the gateway reports on connect. Reading the local clock here
+        instead — which this did — leaves `ended_at` behind every point taken
+        in the final `offset` milliseconds of the run, and those points then
+        fall outside the window their own run is evaluated over.
+
+        The failure is quiet and looks like something else entirely: on a
+        device running 58ms behind the server, a 300-point run was evaluated
+        over 284 of them, and the shortfall reads exactly like ingest lag.
+        """
+        return _iso_from_ms(int(time.time() * 1000) + self._clock_offset_ms)
+
     @staticmethod
     def _infer_class(value: FlexValue) -> str:
         """Numbers are metrics; everything else (str/bool/dict/list) is an event.
@@ -584,7 +602,10 @@ class Plexus:
         Returns:
             The created run dict, including its "id".
         """
-        body: dict[str, Any] = {"name": name, "started_at": started_at or _utc_now_iso()}
+        body: dict[str, Any] = {
+            "name": name,
+            "started_at": started_at or self._now_iso(),
+        }
         if source_id is not _USE_CLIENT_SOURCE:
             body["source_id"] = source_id
         else:
@@ -664,7 +685,7 @@ class Plexus:
         return self._api(
             "PATCH",
             f"/api/runs/{run_id}",
-            {"status": status, "ended_at": ended_at or _utc_now_iso()},
+            {"status": status, "ended_at": ended_at or self._now_iso()},
         )["run"]
 
     @contextmanager

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plexus-python"
-version = "0.11.0"
+version = "0.11.2"
 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.2}/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.2}/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.2}/tests/test_runs.py

@@ -10,6 +10,7 @@ The HTTP layer is stubbed at `_Session.request`, so no socket is opened.
 """
 
 import json
+import time
 
 import pytest
 
@@ -72,6 +73,47 @@ def test_started_at_matches_the_shape_the_route_validates():
     datetime.fromisoformat(started.replace("Z", "+00:00"))  # parses or raises
 
 
+def test_run_boundaries_are_stamped_on_the_server_clock():
+    """The window must be measured by the same clock as the points inside it.
+
+    `_normalize_ts_ms` corrects generated timestamps by the offset the gateway
+    reports on connect. Stamping run boundaries from the local clock instead
+    leaves `ended_at` behind every point taken in the final `offset`
+    milliseconds — and those points then fall outside the window their own run
+    is evaluated over. Measured on production before the fix: a 300-point run
+    on a device 58ms behind the server was judged on 284 of them, and the
+    shortfall reads exactly like ingest lag.
+    """
+    from datetime import datetime
+
+    session = _StubSession()
+    px = _client(session)
+    px._clock_offset_ms = 5_000  # device 5s behind the server
+
+    px.start_run("run")
+    px.end_run({"id": "run_1"})
+
+    def as_ms(iso: str) -> int:
+        return int(datetime.fromisoformat(iso.replace("Z", "+00:00")).timestamp() * 1000)
+
+    local_ms = int(time.time() * 1000)
+    started = as_ms(session.calls[0][2]["started_at"])
+    ended = as_ms(session.calls[1][2]["ended_at"])
+
+    # Both carry the offset, so they bound points that also carry it.
+    assert started - local_ms > 4_000
+    assert ended - local_ms > 4_000
+
+
+def test_an_explicit_boundary_is_left_alone():
+    """A caller passing its own timestamp owns it — we do not shift it."""
+    session = _StubSession()
+    px = _client(session)
+    px._clock_offset_ms = 5_000
+    px.start_run("run", started_at="2026-09-01T10:00:00.000Z")
+    assert session.calls[0][2]["started_at"] == "2026-09-01T10:00:00.000Z"
+
+
 def test_run_defaults_to_the_clients_own_source():
     session = _StubSession()
     px = _client(session)

{plexus_python-0.11.0 → plexus_python-0.11.2}/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" },