matebot 0.2.2__tar.gz → 0.3.0__tar.gz

{matebot-0.2.2 → matebot-0.3.0}/AGENTS.md

@@ -43,7 +43,9 @@ The decision tree:
 6. **Optional extras**, in ascending effort: journal repo + GitHub Pages
    (README "Publishing your journal"), dial-in hints (on by default), bean
    bag tracking (`/newbag`, multiple bags, `/tossbag`), smart plug hooks for cold-start `/wake`
-   (README "Smart plug cold start").
+   (README "Smart plug cold start"), shot-video camera module (README
+   "Camera module" — MATEBOT_CAMERA=1, needs ffmpeg + HTTPS in front of the
+   camera page; getUserMedia refuses plain HTTP).
 
 Common failure modes: token/chat id swapped or quoted wrong; bot and machine
 on different networks/VLANs; machine powered off at a dumb power strip;

{matebot-0.2.2 → matebot-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matebot
-Version: 0.2.2
+Version: 0.3.0
 Summary: The proactive companion for GaggiMate espresso machines: post-shot logging bot, .slog decoder, shot-journal site generator
 Project-URL: Homepage, https://github.com/AlexNly/matebot
 Project-URL: Issues, https://github.com/AlexNly/matebot/issues
@@ -159,6 +159,30 @@ MATEBOT_WAKE_HOOK='curl -sf "http://192.168.1.60/relay/0?turn=on"'
 ```
 
 Any shell command works (Home Assistant webhook, `tinytuya`, zigbee2mqtt…).
+NixOS module users: write `%` as `%%` in the hook options — the values pass
+through a systemd unit, which treats single `%` as a specifier.
+
+## Camera module (optional): shot videos synced with the charts
+
+Opt in with `MATEBOT_CAMERA=1` and MATEbot serves a phone-camera page on
+`MATEBOT_CAMERA_PORT` (default 8877). Open it on a phone near the machine,
+allow camera access, and leave the page open — recording starts and stops
+automatically with each shot. Clips are transcoded (720p, with audio),
+committed to the journal repo, and the shot page plays them in sync with the
+curves (scrub the chart, the video follows).
+
+**HTTPS is required** — browsers only grant camera access on secure pages.
+MATEbot itself serves plain HTTP; put it behind whatever TLS you have:
+
+- a reverse proxy with certificates (nginx/caddy/traefik), e.g.
+  `matebot.example.com` → `127.0.0.1:8877` (WebSocket support needed)
+- or zero-config on a tailnet: `tailscale serve https / http://127.0.0.1:8877`
+
+Sync calibration: detection and stream latency mean the video usually starts
+~1 s after the true shot start. `MATEBOT_CAMERA_OFFSET` (default `-1.0`)
+corrects this globally; watch one replay and nudge per shot with
+`/vsync +0.5` if needed. Videos rotate out after `MATEBOT_VIDEO_KEEP` shots
+(git history keeps every clip recoverable).
 
 ## Configuration
 

{matebot-0.2.2 → matebot-0.3.0}/README.md

@@ -125,6 +125,30 @@ MATEBOT_WAKE_HOOK='curl -sf "http://192.168.1.60/relay/0?turn=on"'
 ```
 
 Any shell command works (Home Assistant webhook, `tinytuya`, zigbee2mqtt…).
+NixOS module users: write `%` as `%%` in the hook options — the values pass
+through a systemd unit, which treats single `%` as a specifier.
+
+## Camera module (optional): shot videos synced with the charts
+
+Opt in with `MATEBOT_CAMERA=1` and MATEbot serves a phone-camera page on
+`MATEBOT_CAMERA_PORT` (default 8877). Open it on a phone near the machine,
+allow camera access, and leave the page open — recording starts and stops
+automatically with each shot. Clips are transcoded (720p, with audio),
+committed to the journal repo, and the shot page plays them in sync with the
+curves (scrub the chart, the video follows).
+
+**HTTPS is required** — browsers only grant camera access on secure pages.
+MATEbot itself serves plain HTTP; put it behind whatever TLS you have:
+
+- a reverse proxy with certificates (nginx/caddy/traefik), e.g.
+  `matebot.example.com` → `127.0.0.1:8877` (WebSocket support needed)
+- or zero-config on a tailnet: `tailscale serve https / http://127.0.0.1:8877`
+
+Sync calibration: detection and stream latency mean the video usually starts
+~1 s after the true shot start. `MATEBOT_CAMERA_OFFSET` (default `-1.0`)
+corrects this globally; watch one replay and nudge per shot with
+`/vsync +0.5` if needed. Videos rotate out after `MATEBOT_VIDEO_KEEP` shots
+(git history keeps every clip recoverable).
 
 ## Configuration
 

{matebot-0.2.2 → matebot-0.3.0}/flake.nix

@@ -13,7 +13,7 @@
           default = matebot;
           matebot = pkgs.python3Packages.buildPythonApplication {
             pname = "matebot";
-            version = "0.2.2";
+            version = "0.3.0";
             pyproject = true;
             src = self;
             build-system = [ pkgs.python3Packages.hatchling ];
@@ -90,7 +90,7 @@
               wantedBy = [ "multi-user.target" ];
               after = [ "network-online.target" ];
               wants = [ "network-online.target" ];
-              path = [ pkgs.git pkgs.openssh ];
+              path = [ pkgs.git pkgs.openssh pkgs.ffmpeg-headless ];
               environment = {
                 MATEBOT_MACHINE_HOST = cfg.machineHost;
                 MATEBOT_MESSENGER = cfg.messenger;

{matebot-0.2.2 → matebot-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matebot"
-version = "0.2.2"
+version = "0.3.0"
 description = "The proactive companion for GaggiMate espresso machines: post-shot logging bot, .slog decoder, shot-journal site generator"
 readme = "README.md"
 license = "MIT"

matebot-0.3.0/scripts/discord_cmd_smoke.py

@@ -0,0 +1,62 @@
+"""Command-routing smoke test for Discord: /help, /status, /bag as plain text."""
+import asyncio
+import logging
+import os
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent / "src"))
+
+from matebot.commands import CommandRouter, make_frame_cache  # noqa: E402
+from matebot.config import Config  # noqa: E402
+from matebot.messengers.base import TextReply  # noqa: E402
+from matebot.messengers.discord import DiscordMessenger  # noqa: E402
+from matebot.state import State  # noqa: E402
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s: %(message)s")
+log = logging.getLogger("cmdsmoke")
+
+
+class FakeMachine:
+    async def request(self, tp, **f):
+        return {"msg": "Ok"}
+
+    async def send_event(self, tp, **f):
+        log.info("MACHINE would receive: %s %s", tp, f)
+
+
+async def main():
+    messenger = DiscordMessenger(
+        os.environ["DISCORD_BOT_TOKEN"], os.environ["DISCORD_CHANNEL_ID"]
+    )
+    state = State("/tmp/discord-cmd-state.json")
+    state.set("last_shot", {"shot_id": 73, "profile": "Direct Lever v3",
+                            "duration_ms": 42600, "volume_g": 36.4})
+    cache, latest = make_frame_cache()
+    cache({"tp": "evt:status", "m": 0, "ct": 91.2, "tt": 0, "wl": 55})
+    router = CommandRouter(FakeMachine(), state, None, messenger,
+                           Config(journal_url="https://alexnly.github.io/GAGGIMATE-0614/"), latest)
+    await messenger.start()
+    await messenger.send("Command smoke test ready — send /help, /status, /last, /wake as messages.")
+
+    async def pump():
+        handled = 0
+        async for event in messenger.events():
+            log.info("EVENT: %r", event)
+            if isinstance(event, TextReply) and event.text.strip().startswith("/"):
+                consumed = await router.handle(event.text.strip())
+                log.info("router consumed=%s", consumed)
+                handled += 1
+                if handled >= 4:
+                    log.info("✅ command routing works on Discord")
+                    return
+
+    try:
+        await asyncio.wait_for(pump(), timeout=600)
+    except TimeoutError:
+        log.error("timed out")
+    finally:
+        await messenger.stop()
+
+
+asyncio.run(main())

matebot-0.3.0/scripts/discord_smoke.py

@@ -0,0 +1,75 @@
+"""Live smoke test for the Discord messenger backend.
+
+Drives a complete fake-shot questionnaire through real Discord — buttons,
+free-text answers, photo, commands — without needing the machine. Saved
+notes land in a recorder and are printed instead of hitting hardware.
+
+Usage:
+    DISCORD_BOT_TOKEN=... DISCORD_CHANNEL_ID=... python scripts/discord_smoke.py
+"""
+
+import asyncio
+import logging
+import os
+import pathlib
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent / "src"))
+
+from matebot.conversation import Conversation  # noqa: E402
+from matebot.messengers.discord import DiscordMessenger  # noqa: E402
+from matebot.state import State  # noqa: E402
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+log = logging.getLogger("smoke")
+
+GOLDEN = pathlib.Path(__file__).parent.parent / "tests" / "fixtures" / "000004.slog"
+
+
+async def main() -> None:
+    messenger = DiscordMessenger(
+        os.environ["DISCORD_BOT_TOKEN"], os.environ["DISCORD_CHANNEL_ID"]
+    )
+    state = State("/tmp/discord-smoke-state.json")
+    saved = {}
+
+    async def save_notes(shot_id, notes):
+        saved[shot_id] = notes
+        log.info("NOTES SAVED for #%s: %s", shot_id, notes)
+        return True
+
+    convo = Conversation(messenger, state, save_notes)
+    await messenger.start()
+    log.info("connected — starting fake questionnaire")
+
+    photo = None
+    try:
+        from matebot.plot import render_shot_png
+        from matebot.slog import parse_slog
+
+        photo = render_shot_png(parse_slog(GOLDEN.read_bytes()), title="Shot #999 — Smoke Test")
+        log.info("photo rendered (%d bytes)", len(photo))
+    except Exception as exc:  # noqa: BLE001
+        log.warning("photo skipped: %s", exc)
+
+    await convo.start_shot(999, "Discord Smoke Test", 31000, 36.2, photo=photo)
+    log.info("questionnaire sent — play it through in Discord (buttons AND typed answers)")
+
+    async def pump():
+        async for event in messenger.events():
+            log.info("EVENT: %r", event)
+            await convo.handle_event(event)
+            if saved:
+                log.info("✅ questionnaire complete — smoke test PASSED")
+                return
+
+    try:
+        await asyncio.wait_for(pump(), timeout=600)
+    except TimeoutError:
+        log.error("timed out waiting for interactions")
+    finally:
+        await messenger.stop()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{matebot-0.2.2 → matebot-0.3.0}/src/matebot/__init__.py

@@ -1,3 +1,3 @@
 """matebot — the proactive companion for GaggiMate espresso machines."""
 
-__version__ = "0.2.2"
+__version__ = "0.3.0"

matebot-0.3.0/src/matebot/camera.py

@@ -0,0 +1,141 @@
+"""Optional camera module: MATEbot serves a phone-camera page and records shots.
+
+Strictly opt-in (``MATEBOT_CAMERA=1``). The phone opens the page (HTTPS via
+the user's reverse proxy — getUserMedia requires a secure context), grants
+camera access and keeps the page open near the machine. When a shot starts,
+the server tells the page to record; MediaRecorder chunks stream back over
+the WebSocket. When the shot ends (+ a short tail), the clip is transcoded
+and attached to the shot via the video pipeline.
+
+Best-effort by design: no page connected → no recording, no errors.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import importlib.resources
+import json
+import logging
+import tempfile
+from pathlib import Path
+
+from aiohttp import WSMsgType, web
+
+log = logging.getLogger(__name__)
+
+TAIL_SECONDS = 5.0
+MAX_RECORD_SECONDS = 240
+
+
+class CameraServer:
+    def __init__(self, port: int, on_clip) -> None:
+        """*on_clip* is ``async (webm_path: Path) -> None`` — called per finished clip."""
+        self.port = port
+        self.on_clip = on_clip
+        self._ws: web.WebSocketResponse | None = None
+        self._chunks: list[bytes] = []
+        self._recording = False
+        self._runner: web.AppRunner | None = None
+        self._stop_task: asyncio.Task | None = None
+
+    # ------------------------------------------------------------ lifecycle
+
+    async def start(self) -> None:
+        app = web.Application()
+        app.router.add_get("/", self._page)
+        app.router.add_get("/ws", self._websocket)
+        self._runner = web.AppRunner(app)
+        await self._runner.setup()
+        site = web.TCPSite(self._runner, "0.0.0.0", self.port)
+        await site.start()
+        log.info("camera server listening on :%d", self.port)
+
+    async def stop(self) -> None:
+        if self._runner:
+            await self._runner.cleanup()
+
+    @property
+    def page_connected(self) -> bool:
+        return self._ws is not None and not self._ws.closed
+
+    # ------------------------------------------------------------ recording
+
+    async def shot_started(self) -> None:
+        if not self.page_connected or self._recording:
+            return
+        self._chunks = []
+        self._recording = True
+        await self._send({"cmd": "start"})
+        log.info("camera: recording started")
+        self._stop_task = asyncio.create_task(self._safety_stop())
+
+    async def shot_ended(self) -> None:
+        if not self._recording:
+            return
+        await asyncio.sleep(TAIL_SECONDS)
+        await self._finish()
+
+    async def _safety_stop(self) -> None:
+        await asyncio.sleep(MAX_RECORD_SECONDS)
+        if self._recording:
+            log.warning("camera: safety stop after %ds", MAX_RECORD_SECONDS)
+            await self._finish()
+
+    async def _finish(self) -> None:
+        if not self._recording:
+            return
+        self._recording = False
+        if self._stop_task and not self._stop_task.done():
+            self._stop_task.cancel()
+        await self._send({"cmd": "stop"})
+        # give the page a moment to flush its final chunks
+        for _ in range(20):
+            await asyncio.sleep(0.25)
+            if not self.page_connected:
+                break
+        chunks, self._chunks = self._chunks, []
+        if not chunks:
+            log.info("camera: no video data received")
+            return
+        with tempfile.NamedTemporaryFile(suffix=".webm", delete=False) as tmp:
+            for chunk in chunks:
+                tmp.write(chunk)
+            path = Path(tmp.name)
+        log.info("camera: clip complete (%.1f MB)", path.stat().st_size / 1e6)
+        try:
+            await self.on_clip(path)
+        finally:
+            path.unlink(missing_ok=True)
+
+    # ------------------------------------------------------------ http
+
+    async def _page(self, request: web.Request) -> web.Response:
+        html = (importlib.resources.files("matebot") / "web_cam" / "index.html").read_text()
+        return web.Response(text=html, content_type="text/html")
+
+    async def _websocket(self, request: web.Request) -> web.WebSocketResponse:
+        ws = web.WebSocketResponse(max_msg_size=8 * 2**20)
+        await ws.prepare(request)
+        if self._ws and not self._ws.closed:
+            await self._ws.close()  # newest page wins
+        self._ws = ws
+        log.info("camera page connected from %s", request.remote)
+        try:
+            async for msg in ws:
+                if msg.type == WSMsgType.BINARY:
+                    if self._recording or self._chunks is not None:
+                        self._chunks.append(msg.data)
+                elif msg.type == WSMsgType.TEXT:
+                    log.debug("camera page: %s", msg.data[:100])
+        finally:
+            if self._ws is ws:
+                self._ws = None
+            log.info("camera page disconnected")
+        return ws
+
+    async def _send(self, payload: dict) -> None:
+        if self.page_connected:
+            try:
+                await self._ws.send_str(json.dumps(payload))
+            except Exception as exc:  # noqa: BLE001
+                log.warning("camera send failed: %s", exc)

{matebot-0.2.2 → matebot-0.3.0}/src/matebot/cli.py

@@ -76,7 +76,10 @@ async def _sync(config: Config) -> int:
         return 1
     async with GaggiMateClient(config.machine_host) as client:
         # WS connection (for profiles) is optional here; HTTP does the rest.
-        pushed = await sync(client, config.data_repo, site_title=config.site_title)
+        pushed = await sync(
+            client, config.data_repo,
+            site_title=config.site_title, video_keep=config.video_keep,
+        )
     print("synced" if pushed else "nothing new")
     return 0
 
@@ -117,7 +120,8 @@ async def _run(config: Config, *, replay: str | None, dry_run: bool) -> int:
                 asyncio.create_task(
                     sync_soon(
                         client, config.data_repo, messenger.send,
-                        site_title=config.site_title, state=state, quiet=quiet,
+                        site_title=config.site_title, video_keep=config.video_keep,
+                        state=state, quiet=quiet,
                     )
                 )
 
@@ -146,6 +150,52 @@ async def _run(config: Config, *, replay: str | None, dry_run: bool) -> int:
         convo = Conversation(messenger, state, save_notes)
         cache_frame, latest_frame = make_frame_cache()
         router = CommandRouter(client, state, convo, messenger, config, latest_frame)
+
+        camera = None
+        pending_clip: dict = {"path": None, "ts": 0.0}
+        attach_lock = asyncio.Lock()
+
+        async def try_attach_clip(shot_id: int | None = None) -> None:
+            """Rendezvous: a finished clip and a resolved shot id arrive in
+            either order; whichever side is second completes the attach."""
+            import time as _time
+
+            from .video import VideoError, attach_video, get_offset
+
+            async with attach_lock:
+                clip = pending_clip["path"]
+                if clip is None or _time.monotonic() - pending_clip["ts"] > 300:
+                    return
+                sid = shot_id if shot_id is not None else state.get("last_shot_id")
+                if not sid or get_offset(config.data_repo, sid) is not None:
+                    return  # no shot yet, or it already has a video
+                pending_clip["path"] = None
+                try:
+                    await attach_video(config.data_repo, sid, clip,
+                                       offset=config.camera_offset)
+                    log.info("camera clip attached to shot %06d", sid)
+                    schedule_sync(quiet=True)
+                except VideoError as exc:
+                    log.warning("clip attach failed: %s", exc)
+                    await messenger.send(f"🎬 Couldn't process the shot video: {exc}")
+                finally:
+                    pathlib.Path(clip).unlink(missing_ok=True)
+
+        if config.camera_enabled and config.data_repo:
+            import shutil as _shutil
+            import time as _time
+
+            from .camera import CameraServer
+
+            async def on_clip(webm_path):
+                keep = pathlib.Path(config.state_dir) / "pending_clip.webm"
+                _shutil.copy(webm_path, keep)
+                pending_clip["path"] = str(keep)
+                pending_clip["ts"] = _time.monotonic()
+                await try_attach_clip()
+
+            camera = CameraServer(config.camera_port, on_clip)
+            await camera.start()
         # messenger APIs can be flaky at boot; retry instead of crash-looping
         for attempt in range(8):
             try:
@@ -175,16 +225,31 @@ async def _run(config: Config, *, replay: str | None, dry_run: bool) -> int:
 
                 last_frame_at = 0.0
 
+                shot_active = False
+
                 async def tee(source):
-                    nonlocal last_frame_at
+                    nonlocal last_frame_at, shot_active
                     async for frame in source:
                         now = _time.monotonic()
                         gap = now - last_frame_at if last_frame_at else None
                         last_frame_at = now
-                        if state.get("sync_pending") and (gap is None or gap > 60):
-                            log.info("machine is back; retrying pending journal sync")
-                            state.set("sync_pending", False)  # avoid re-trigger storms
-                            schedule_sync(quiet=True)
+                        if camera is not None and frame.get("tp") == "evt:status":
+                            active = (
+                                frame.get("m") == 1
+                                and (frame.get("process") or {}).get("a") == 1
+                                and not _re.search(config.ignore_profiles, frame.get("p") or "")
+                            )
+                            if active and not shot_active:
+                                await camera.shot_started()
+                            elif shot_active and not active:
+                                asyncio.create_task(camera.shot_ended())
+                            shot_active = active
+                        if gap is None or gap > 60:
+                            await router.on_machine_online(frame)
+                            if state.get("sync_pending"):
+                                log.info("machine is back; retrying pending journal sync")
+                                state.set("sync_pending", False)  # avoid re-trigger storms
+                                schedule_sync(quiet=True)
                         cache_frame(frame)
                         await router.on_frame(frame)
                         yield frame
@@ -247,6 +312,7 @@ async def _run(config: Config, *, replay: str | None, dry_run: bool) -> int:
                         )
                     except Exception:  # noqa: BLE001 - keep watching even if messaging fails
                         log.exception("questionnaire start failed (state kept for resume)")
+                    await try_attach_clip(shot.entry.id)
                     schedule_sync()  # archive the .slog right away
 
             async def weekly_digest():
@@ -279,6 +345,8 @@ async def _run(config: Config, *, replay: str | None, dry_run: bool) -> int:
                 if exc:
                     raise exc
         finally:
+            if camera is not None:
+                await camera.stop()
             await messenger.stop()
     return 0