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

{plexus_python-0.9.0 → plexus_python-0.11.0}/.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.9.0 → plexus_python-0.11.0}/API.md

@@ -111,9 +111,48 @@ x-api-key: plx_xxxxx
 | object  | `{"x": 1.2, "y": 3.4, "z": 5.6}` | Vector data, structured readings |
 | array   | `[1.0, 2.0, 3.0, 4.0]`           | Waveforms, multiple values       |
 
-### Sessions
+### Runs
 
-> **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.
+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 when they close.
+
+The SDK opens and closes them, so the software driving the bench owns the
+window rather than someone remembering to drag a time-range picker afterwards:
+
+```python
+with px.run("hotfire-03", pass_criteria=[
+    {"metric": "motor.temp_c", "operator": "<", "value": 85, "label": "motor stays cool"},
+    {"metric": "frames.dropped", "operator": "=", "value": 0},
+]) as run:
+    bench.execute()
+
+print(run["id"])
+```
+
+Leaving the block closes the run as `completed`; an exception closes it as
+`aborted` and re-raises. For a bench that starts and stops from different
+places, call the two halves directly:
+
+```python
+run = px.start_run("hotfire-03", tags={"build": "a41f"})
+...
+result = px.end_run(run)             # or px.end_run(run, status="aborted")
+print(result["test_result"])          # {"passed": bool, "criteria_results": [...]}
+```
+
+`start_run()` defaults `source_id` to the client's source; pass
+`source_id=None` for an org-wide run. Underneath these are `POST /api/runs`
+and `PATCH /api/runs/{id}` on the app API (not the gateway), authenticated
+with the same `x-api-key`.
+
+**Pass criteria.** Each is `{metric, operator, value, label?}` with operator
+one of `> >= < <= = !=`. On close, every point for that metric inside the run
+window is checked; the criterion passes only if all of them satisfy it, and a
+criterion whose metric has no data in the window fails. The verdict is stored
+on the run's `test_result` and shown on `/runs`.
+
+To group data without a window, plain `tags` on each point still work.
 
 ## WebSocket API
 
@@ -367,6 +406,51 @@ while True:
 | 404    | Resource not found              |
 | 410    | Resource expired                |
 
+## Rate limits and batching
+
+The gateway meters **messages**, not points. One `px.send()` call is one
+message, whatever it carries:
+
+| Limit                              | Value            |
+| ---------------------------------- | ---------------- |
+| Telemetry messages per WS connection | 500/s sustained, 2000 burst |
+| Hard ceiling per source (WS + HTTP) | 2000 messages/s  |
+| Points per message                 | 10,000           |
+| Message size                       | 1 MB             |
+
+Because the ceiling counts messages, the shape of your sends decides whether
+you hit it. Eight channels at 100 Hz sent one at a time is 800 messages/s —
+over the limit. The same 800 readings/s batched every 100 ms is 10 messages/s,
+and the batches are also several times cheaper to store.
+
+**Over the limit, the gateway discards the whole message.** It replies with a
+`RATE_LIMITED` error frame, but that arrives after `send()` has already
+returned — those points are gone and cannot be resent. The SDK counts the
+notices (`px.rate_limited_frames`) and raises `RateLimitedError` on the next
+send so the loss cannot pass unnoticed, but the only real fix is to send
+fewer, larger messages.
+
+Use `px.batch()` for anything above a few readings per second:
+
+```python
+with px.batch(interval_ms=50) as b:
+    while running:
+        b.send("att.pos_x", att.x)
+        b.send("att.rate_x", gyro.x)
+        b.send("frames.captured", grabber.count)
+```
+
+`b.send()` takes the same arguments as `px.send()` and queues the reading; a
+background thread flushes the queue on the interval, and leaving the block
+flushes what is left. A failed flush leaves the points in the local
+store-and-forward buffer, so nothing is dropped for a transient outage — the
+one bounded exception is `max_pending` (default 200,000 points), reached only
+when the gateway has been unreachable for a long time, and counted on
+`BatchSender.dropped`.
+
+If you are already accumulating readings yourself, `px.send_batch([...])`
+sends a list in one message without the background thread.
+
 ## Clock correction
 
 Embedded devices commonly boot with a wrong system clock — no hardware RTC, NTP unreachable on first boot, or a fresh OS image whose filesystem timestamp is months in the past. Without correction, all telemetry lands at the wrong place on the timeline.
@@ -401,7 +485,7 @@ px.send("temperature", 72.5, timestamp=t)        # your timestamp → used as-is
 
 ## Best Practices
 
-- **Batch points** - Send up to 100 points per request for HTTP
+- **Batch above a few readings per second** - `px.batch()` coalesces into one message per interval; the gateway's ceiling counts messages, not points (see [Rate limits and batching](#rate-limits-and-batching))
 - **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 and grouping (e.g., `{"location": "lab"}`)

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

@@ -2,6 +2,98 @@
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-09-01 - Batching, runs, and an end to silent drops
+
+### Added
+
+- **`px.batch()`** — a coalescing sender for anything faster than a few
+  readings a second. `send()` puts every reading in its own WebSocket frame,
+  and the gateway's telemetry ceiling counts *frames*: 500/s on a connection,
+  2000/s per source. Eight channels at 100 Hz sent one at a time is 800
+  frames/s, so roughly a third of it was discarded. Batched at 50 ms it is 20
+  frames/s. A background thread flushes on the interval, leaving the block
+  flushes the remainder, and readings keep the timestamp they were taken at.
+  Also the cheaper shape downstream — the loader moves ~400k rows/s at 100
+  points per message and ~65k at one.
+
+- **Runs** — `px.start_run()`, `px.end_run()` and `with px.run(...)`, against
+  the `/api/runs` routes that have existed for a while with nothing reaching
+  them. An exception leaving the `with` block closes the run as `aborted`.
+  Declared `pass_criteria` are now evaluated when the run closes, so
+  `end_run()` hands back a verdict in `test_result`.
+
+### Fixed
+
+- **`RATE_LIMITED` is no longer swallowed.** The gateway reports a discarded
+  telemetry frame asynchronously, after `send()` has already returned True.
+  The entire handling was a `logger.warning`, so a bench could lose a third of
+  its data with nothing to show for it. The transport now forwards server
+  error frames to the client, which counts them on `px.rate_limited_frames`
+  and raises `RateLimitedError` on the following send — after that send's own
+  points are away, so reporting the loss never causes more of it.
+
+### Changed
+
+- **`API.md` no longer claims runs do not exist.** It said "Removed / not
+  built … no such route exists in the gateway or platform" about routes that
+  do, which is the first thing anyone integrating would have read.
+
+## [0.10.0] - 2026-08-28 - Agent skills
+
+### Added
+
+- **`plexus skills install`** — copies three bundled agent skills into
+  `~/.claude/skills` (or `./.claude/skills` with `--project`), so a coding
+  agent knows the Plexus API instead of inventing it. `--list` shows what
+  ships; `--dir` picks a target. Existing copies are refreshed and reported:
+  they are reference docs, and a stale one is the failure this fixes.
+
+- **The skills themselves**, in `skills/`: `plexus` (hosts, auth, every
+  endpoint, the live stream), `plexus-firmware` (device-side ingest), and
+  `plexus-dashboard` (read-API frontend scaffolding). They ship inside the
+  wheel at `plexus/_skills`; previously they reached the sdist only, which
+  lands in a temp build directory nobody looks in.
+
+- **`scripts/verify_skills.py`** — checks every route the skills quote against
+  the live OpenAPI spec and every WebSocket route by real handshake, with no
+  API key. It also asserts that routes documented as *dead* are still dead:
+  the skills name non-existent routes on purpose, because agents invent them
+  otherwise, and if one ever ships the warning has become a lie.
+
+- **`tests/test_skills.py`** — offline guards on request/response shape, plus
+  the CLI. Touches no network, per the `conftest.py` isolation rule.
+
+### Fixed
+
+- The skills had drifted badly enough to generate broken code. The firmware
+  one keyed the ingest body `metrics` instead of `points`, omitted the
+  required `class` on every point, and sent ISO-8601 timestamp strings — every
+  template in it would have returned a 400. The dashboard one polled a route
+  that 404s and typed the query response as an array of points when it is
+  columnar. Both built their live-stream sections on a gateway URL that does
+  not exist; the stream is on the data API and authenticates by first message,
+  which means a browser can connect directly.
+
+- The test suite no longer reaches the production gateway. `plexus/config.py`
+  defaults to `wss://gateway.plexus.company`, so every run opened real sockets to
+  it and left a burst of `device auth failed / invalid API key` warnings in
+  production logs — noise indistinguishable from a customer with a broken key.
+  It also read the developer's own `~/.plexus/config.json`, so a real API key
+  could have authenticated the suite. `tests/conftest.py` pins all three
+  endpoints to loopback and redirects config reads to a tmp dir;
+  `tests/test_isolation.py` proves both are in effect.
+
+## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plexus-python
-Version: 0.9.0
+Version: 0.11.0
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.company
 Project-URL: Documentation, https://docs.plexus.company
@@ -113,6 +113,35 @@ px.send_batch([
 
 `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`).
 
+### `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.
+
+```python
+with px.batch(interval_ms=50) as b:
+    while running:
+        b.send("att.pos_x", att.x)
+        b.send("att.rate_x", gyro.x)
+        b.send("frames.captured", grabber.count)
+```
+
+`b.send()` takes the same arguments as `px.send()`. A background thread flushes the queue every `interval_ms`, and leaving the block flushes what is left, so nothing is stranded. Readings keep the timestamp they were taken at, not the one they were flushed at.
+
+If the gateway does discard frames it reports `RATE_LIMITED`; the SDK counts those on `px.rate_limited_frames` and raises `RateLimitedError` on the next send rather than letting the loss pass unnoticed.
+
+### `run(name)` — mark a test run
+
+A run is a named window on a source. Runs are recalled on `/runs`, compared against each other aligned at T+0, and checked against their pass criteria when they close.
+
+```python
+with px.run("hotfire-03", pass_criteria=[
+    {"metric": "motor.temp_c", "operator": "<", "value": 85},
+]) as run:
+    bench.execute()
+```
+
+Leaving the block closes the run as `completed`; an exception closes it as `aborted` and re-raises. Use `px.start_run()` / `px.end_run()` when the two halves happen in different places — `end_run()` returns the run with its verdict in `test_result`.
+
 ### `event(name, data)` — record a discrete occurrence
 
 Use `event()` for things that *happen* rather than things you *measure continuously*. Faults, state transitions, operator actions, log entries — anything you'd put on a timeline as a marker rather than plot as a graph.
@@ -262,6 +291,20 @@ The SDK sends an `ack` frame before invoking the handler, then a `result` frame
 | `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://gateway.plexus.company` |
 | `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://gateway.plexus.company`   |
 
+## Agent skills
+
+Three skills ship with the package and teach a coding agent the Plexus API —
+the endpoints, the live stream, and the mistakes that produce a silent 400.
+
+```bash
+plexus skills install          # -> ~/.claude/skills
+plexus skills install --project  # -> ./.claude/skills, travels with the repo
+```
+
+Then ask for what you want in plain language: *"send my ESP32's battery voltage
+to Plexus"*, *"build me a fleet dashboard"*. Plain Markdown, no install, no
+credentials. See [skills/README.md](skills/README.md).
+
 ## Architecture
 
 ```

{plexus_python-0.9.0 → plexus_python-0.11.0}/README.md

@@ -76,6 +76,35 @@ px.send_batch([
 
 `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`).
 
+### `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.
+
+```python
+with px.batch(interval_ms=50) as b:
+    while running:
+        b.send("att.pos_x", att.x)
+        b.send("att.rate_x", gyro.x)
+        b.send("frames.captured", grabber.count)
+```
+
+`b.send()` takes the same arguments as `px.send()`. A background thread flushes the queue every `interval_ms`, and leaving the block flushes what is left, so nothing is stranded. Readings keep the timestamp they were taken at, not the one they were flushed at.
+
+If the gateway does discard frames it reports `RATE_LIMITED`; the SDK counts those on `px.rate_limited_frames` and raises `RateLimitedError` on the next send rather than letting the loss pass unnoticed.
+
+### `run(name)` — mark a test run
+
+A run is a named window on a source. Runs are recalled on `/runs`, compared against each other aligned at T+0, and checked against their pass criteria when they close.
+
+```python
+with px.run("hotfire-03", pass_criteria=[
+    {"metric": "motor.temp_c", "operator": "<", "value": 85},
+]) as run:
+    bench.execute()
+```
+
+Leaving the block closes the run as `completed`; an exception closes it as `aborted` and re-raises. Use `px.start_run()` / `px.end_run()` when the two halves happen in different places — `end_run()` returns the run with its verdict in `test_result`.
+
 ### `event(name, data)` — record a discrete occurrence
 
 Use `event()` for things that *happen* rather than things you *measure continuously*. Faults, state transitions, operator actions, log entries — anything you'd put on a timeline as a marker rather than plot as a graph.
@@ -225,6 +254,20 @@ The SDK sends an `ack` frame before invoking the handler, then a `result` frame
 | `PLEXUS_GATEWAY_URL`    | HTTP ingest URL              | `https://gateway.plexus.company` |
 | `PLEXUS_GATEWAY_WS_URL` | WebSocket URL              | `wss://gateway.plexus.company`   |
 
+## Agent skills
+
+Three skills ship with the package and teach a coding agent the Plexus API —
+the endpoints, the live stream, and the mistakes that produce a silent 400.
+
+```bash
+plexus skills install          # -> ~/.claude/skills
+plexus skills install --project  # -> ./.claude/skills, travels with the repo
+```
+
+Then ask for what you want in plain language: *"send my ESP32's battery voltage
+to Plexus"*, *"build me a fleet dashboard"*. Plain Markdown, no install, no
+credentials. See [skills/README.md](skills/README.md).
+
 ## Architecture
 
 ```

plexus_python-0.11.0/plexus/__init__.py

@@ -0,0 +1,35 @@
+"""
+Plexus — thin Python SDK for sending telemetry to the Plexus gateway.
+
+    from plexus import Plexus
+
+    px = Plexus(api_key="plx_xxx", source_id="device-001")
+    px.send("temperature", 72.5)
+
+At bench rates, batch — `send()` is one WebSocket frame per call and the
+gateway limits frames, not points:
+
+    with px.run("hotfire-03"), px.batch(interval_ms=50) as b:
+        b.send("att.rate_x", gyro.x)
+"""
+
+from plexus.batching import BatchSender
+from plexus.client import (
+    AuthenticationError,
+    Plexus,
+    PlexusError,
+    RateLimitedError,
+    read_mjpeg_frames,
+)
+from plexus.config import RetryConfig
+
+__version__ = "0.11.0"
+__all__ = [
+    "AuthenticationError",
+    "BatchSender",
+    "Plexus",
+    "PlexusError",
+    "RateLimitedError",
+    "RetryConfig",
+    "read_mjpeg_frames",
+]

plexus_python-0.11.0/plexus/batching.py

@@ -0,0 +1,262 @@
+"""Coalescing sender — one frame per interval instead of one per reading.
+
+`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
+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.
+
+Downstream the same shape decides throughput. The ClickHouse loader measures
+~400k rows/s at 100 points per message and ~65k at one point per message — a 6x
+penalty paid entirely at the producer.
+
+    with px.batch(interval_ms=50) as b:
+        while running:
+            b.send("att.rate_x", gyro.x)
+            b.send("att.rate_y", gyro.y)
+            b.send("frames.captured", grabber.count)
+
+Points accumulate in memory and a background thread flushes them on the
+interval. `close()` (and so the `with` block) flushes what is left before
+returning, so exiting normally never strands a reading.
+
+Delivery semantics are the client's, unchanged: a failed flush leaves the
+points in the client's local store-and-forward buffer to go out with the next
+send. Nothing here drops data on the floor — the one bounded exception is
+`max_pending`, which exists so a permanently unreachable gateway cannot grow
+the process's memory without limit, and which reports every point it evicts.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import TYPE_CHECKING, Any
+
+from plexus._log import _say
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from plexus.client import FlexValue, Plexus
+
+logger = logging.getLogger(__name__)
+
+# Frames per second implied by the default interval: 10. Two orders of
+# magnitude under the gateway's per-connection ceiling, so a caller has room
+# to shorten it without having to know what the ceiling is.
+DEFAULT_INTERVAL_MS = 100.0
+
+# Hard floor on the flush interval. Below ~2ms the flush thread spends more
+# time waking up than sending, and 500 frames/s is the gateway's limit anyway.
+MIN_INTERVAL_MS = 2.0
+
+# Frames a periodic flush may send in one cycle. At the default interval and
+# `max_points` this is 200k points/s of drain capacity while holding the frame
+# rate at 40/s — an order of magnitude under the ceiling even while catching up.
+_FRAMES_PER_FLUSH = 4
+
+
+class BatchSender:
+    """Accumulates points and flushes them on an interval.
+
+    Construct via `Plexus.batch()` rather than directly — the client owns the
+    connection, the buffer and the retry policy, and this only decides when a
+    frame leaves.
+    """
+
+    def __init__(
+        self,
+        client: "Plexus",
+        interval_ms: float = DEFAULT_INTERVAL_MS,
+        max_points: int = 5000,
+        max_pending: int = 200_000,
+    ):
+        if interval_ms < MIN_INTERVAL_MS:
+            raise ValueError(
+                f"interval_ms must be >= {MIN_INTERVAL_MS} "
+                f"({1000 / MIN_INTERVAL_MS:.0f} flushes/s is already past the "
+                "gateway's per-connection ceiling)"
+            )
+        if max_points < 1:
+            raise ValueError("max_points must be >= 1")
+        if max_pending < max_points:
+            raise ValueError("max_pending must be >= max_points")
+
+        self._client = client
+        self._interval_s = interval_ms / 1000.0
+        self._max_points = max_points
+        self._max_pending = max_pending
+
+        self._pending: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._dropped = 0
+        self._announced_overflow = False
+        self._closed = False
+
+    # ------------------------------------------------------------------ public
+
+    def send(
+        self,
+        metric: str,
+        value: "FlexValue",
+        timestamp: float | None = None,
+        tags: dict[str, str] | None = None,
+        data_class: str | None = None,
+    ) -> None:
+        """Queue one reading. Same arguments as `Plexus.send()`.
+
+        Returns None rather than bool: the point has not been sent yet, and a
+        True here would mean the same thing `send()`'s True means, which it
+        does not. Value-type errors still raise immediately — that is a bug in
+        the caller's code and should surface at the call site, not on a
+        background thread a hundred milliseconds later.
+        """
+        point = self._client._make_point(metric, value, timestamp, tags, data_class)
+        self._append([point])
+
+    def send_batch(
+        self,
+        points: list[tuple[str, "FlexValue"] | tuple[str, "FlexValue", float]],
+        timestamp: float | None = None,
+        tags: dict[str, str] | None = None,
+    ) -> None:
+        """Queue several readings at once. Same arguments as `Plexus.send_batch()`."""
+        default_ts_ms = self._client._normalize_ts_ms(timestamp)
+        built: list[dict[str, Any]] = []
+        for p in points:
+            if len(p) == 3:
+                m, v, t = p
+                built.append(
+                    self._client._make_point(m, v, self._client._normalize_ts_ms(t), tags)
+                )
+            else:
+                m, v = p
+                built.append(self._client._make_point(m, v, default_ts_ms, tags))
+        self._append(built)
+
+    def flush(self) -> None:
+        """Send everything queued right now. Blocks until the send returns.
+
+        Raises whatever `Plexus.send()` raises. The points are already in the
+        client's local buffer by then, so a raise here means "not delivered
+        yet", not "lost".
+        """
+        self._flush_once(raise_on_error=True)
+
+    @property
+    def pending(self) -> int:
+        """Points queued but not yet handed to the client."""
+        with self._lock:
+            return len(self._pending)
+
+    @property
+    def dropped(self) -> int:
+        """Points evicted because the queue hit `max_pending`."""
+        return self._dropped
+
+    def start(self) -> "BatchSender":
+        if self._thread is not None:
+            return self
+        self._thread = threading.Thread(
+            target=self._run, name="plexus-batch", daemon=True
+        )
+        self._thread.start()
+        return self
+
+    def close(self) -> None:
+        """Stop the flush thread and send what is left.
+
+        Idempotent. The final flush is best-effort: anything it cannot deliver
+        stays in the client's buffer for the next send or for `close()` on the
+        client itself, which flushes again.
+        """
+        if self._closed:
+            return
+        self._closed = True
+        self._stop.set()
+        thread, self._thread = self._thread, None
+        if thread is not None:
+            thread.join(timeout=max(5.0, self._interval_s * 10))
+        self._flush_once(raise_on_error=False)
+
+    def __enter__(self) -> "BatchSender":
+        return self.start()
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        self.close()
+        return False
+
+    # ----------------------------------------------------------------- internal
+
+    def _append(self, points: list[dict[str, Any]]) -> None:
+        if self._closed:
+            raise RuntimeError("BatchSender is closed")
+        overflow = 0
+        with self._lock:
+            self._pending.extend(points)
+            excess = len(self._pending) - self._max_pending
+            if excess > 0:
+                # Drop oldest. A bench cares more about the reading it just
+                # took than one from several minutes of unreachable gateway.
+                del self._pending[:excess]
+                overflow = excess
+                self._dropped += excess
+        if overflow:
+            self._report_overflow(overflow)
+
+    def _report_overflow(self, dropped: int) -> None:
+        if not self._announced_overflow:
+            _say(
+                f"⚠ batch queue full at {self._max_pending} points — dropping "
+                f"oldest ({dropped} so far). The gateway is not keeping up."
+            )
+            self._announced_overflow = True
+        logger.warning("plexus batch overflow: dropped %d oldest points", dropped)
+
+    def _take(self) -> list[dict[str, Any]]:
+        with self._lock:
+            if not self._pending:
+                return []
+            batch = self._pending[: self._max_points]
+            del self._pending[: len(batch)]
+            return batch
+
+    def _flush_once(self, raise_on_error: bool, max_frames: int | None = None) -> None:
+        frames = 0
+        while max_frames is None or frames < max_frames:
+            batch = self._take()
+            if not batch:
+                return
+            frames += 1
+            try:
+                self._client._send_points(batch)
+            except Exception as e:
+                # _send_points has already returned the points to the client's
+                # buffer, so they are not lost — but there is no point spinning
+                # through the rest of the queue into the same failure.
+                logger.debug("plexus batch flush failed: %s", e)
+                if raise_on_error:
+                    raise
+                return
+
+    def _run(self) -> None:
+        # Pace off a fixed schedule rather than sleeping `interval` *after*
+        # each flush: a flush that runs long would otherwise stretch the
+        # effective interval, and a queue that is filling faster than it
+        # drains would stretch it further each cycle.
+        next_flush = time.monotonic() + self._interval_s
+        while not self._stop.is_set():
+            delay = next_flush - time.monotonic()
+            if delay > 0 and self._stop.wait(delay):
+                break
+            # Bounded per cycle so a large backlog drains at a predictable
+            # frame rate instead of bursting straight back into the gateway's
+            # per-connection limit — the thing this class exists to avoid.
+            self._flush_once(raise_on_error=False, max_frames=_FRAMES_PER_FLUSH)
+            next_flush = max(time.monotonic(), next_flush + self._interval_s)