matebot 0.2.0__py3-none-any.whl

matebot/__init__.py

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

matebot/bags.py

@@ -0,0 +1,77 @@
+"""Bean bag tracking — strictly opt-in.
+
+Nothing happens until the user registers a bag with ``/newbag``; from then on
+every logged dose-in is subtracted, and the bot warns once when roughly three
+doses are left. ``/bag`` shows the current state at any time.
+
+State shape (in the bot's state file):
+    bag = {"name": str, "total_g": float, "used_g": float,
+           "shots": int, "rating_sum": int, "warned": bool}
+"""
+
+from __future__ import annotations
+
+DEFAULT_DOSE_G = 18.0
+WARN_DOSES = 3
+
+
+def open_bag(state, total_g: float, name: str) -> str:
+    state.set("bag", {
+        "name": name, "total_g": total_g, "used_g": 0.0,
+        "shots": 0, "rating_sum": 0, "warned": False,
+    })
+    return f"🫘 New bag registered: {name}, {total_g:.0f} g. I'll keep count."
+
+
+def bag_status(state) -> str:
+    bag = state.get("bag")
+    if not bag:
+        return "No bag registered. Start one with: /newbag <grams> [name]"
+    remaining = max(0.0, bag["total_g"] - bag["used_g"])
+    dose = _typical_dose(state)
+    doses_left = int(remaining // dose) if dose else 0
+    line = (
+        f"🫘 {bag['name']}: {remaining:.0f} g of {bag['total_g']:.0f} g left"
+        f" (≈{doses_left} doses) · {bag['shots']} shots"
+    )
+    if bag["shots"] and bag["rating_sum"]:
+        line += f" · avg {'★' * round(bag['rating_sum'] / bag['shots'])}"
+    return line
+
+
+def track_shot(state, notes: dict) -> str | None:
+    """Subtract the logged dose; returns a warning message when running low."""
+    bag = state.get("bag")
+    if not bag:
+        return None
+    try:
+        dose = float(notes.get("doseIn", ""))
+    except (TypeError, ValueError):
+        dose = 0.0
+    if dose <= 0:
+        return None
+    bag["used_g"] += dose
+    bag["shots"] += 1
+    rating = notes.get("rating")
+    if isinstance(rating, int):
+        bag["rating_sum"] += rating
+    remaining = bag["total_g"] - bag["used_g"]
+
+    message = None
+    if remaining <= 0:
+        message = f"🫘 That was the last of '{bag['name']}' by my count — bag empty."
+    elif remaining < WARN_DOSES * dose and not bag["warned"]:
+        bag["warned"] = True
+        message = (
+            f"🫘 Heads-up: '{bag['name']}' is down to ~{remaining:.0f} g "
+            f"(≈{int(remaining // dose)} doses). Time to restock?"
+        )
+    state.set("bag", bag)
+    return message
+
+
+def _typical_dose(state) -> float:
+    try:
+        return float(state.get("last_notes", {}).get("doseIn", DEFAULT_DOSE_G))
+    except (TypeError, ValueError):
+        return DEFAULT_DOSE_G

matebot/cli.py

@@ -0,0 +1,293 @@
+"""matebot CLI: run / decode / sitegen / sync."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import pathlib
+import sys
+
+from . import __version__
+from .config import Config
+from .slog import SlogError, parse_slog
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="matebot",
+        description="The proactive companion for GaggiMate espresso machines.",
+    )
+    parser.add_argument("--version", action="version", version=f"matebot {__version__}")
+    parser.add_argument("--config", help="path to config.toml")
+    parser.add_argument("-v", "--verbose", action="store_true")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_run = sub.add_parser("run", help="watch the machine, message after every shot")
+    p_run.add_argument("--replay", help="JSONL frame capture instead of the live machine")
+    p_run.add_argument("--dry-run", action="store_true", help="log instead of messaging")
+
+    p_dec = sub.add_parser("decode", help="decode a .slog file to JSON or CSV")
+    p_dec.add_argument("file", type=pathlib.Path)
+    p_dec.add_argument("--csv", action="store_true")
+
+    p_site = sub.add_parser("sitegen", help="generate the static shot-explorer site")
+    p_site.add_argument("shots_dir", type=pathlib.Path)
+    p_site.add_argument("-o", "--out", type=pathlib.Path, required=True)
+    p_site.add_argument("--title", default="Shot Journal")
+
+    sub.add_parser("sync", help="one-off sync of the data repo (shots, profiles, site)")
+
+    args = parser.parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    config = Config.load(args.config)
+
+    if args.cmd == "decode":
+        try:
+            shot = parse_slog(args.file.read_bytes())
+        except SlogError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 1
+        print(shot.to_csv() if args.csv else shot.to_json(indent=1))
+        return 0
+
+    if args.cmd == "sitegen":
+        from .sitegen import generate
+
+        count = generate(args.shots_dir, args.out, title=args.title)
+        print(f"{count} shots -> {args.out}")
+        return 0
+
+    if args.cmd == "sync":
+        return asyncio.run(_sync(config))
+
+    return asyncio.run(_run(config, replay=args.replay, dry_run=args.dry_run))
+
+
+async def _sync(config: Config) -> int:
+    from .machine import GaggiMateClient
+    from .sync import sync
+
+    if not config.data_repo:
+        print("error: MATEBOT_DATA_REPO / data_repo not configured", file=sys.stderr)
+        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)
+    print("synced" if pushed else "nothing new")
+    return 0
+
+
+async def _run(config: Config, *, replay: str | None, dry_run: bool) -> int:
+    from .commands import CommandRouter, make_frame_cache
+    from .conversation import Conversation
+    from .machine import GaggiMateClient
+    from .messengers.base import TextReply
+    from .state import State
+    from .sync import sync_soon
+    from .watcher import ShotWatcher, replay_frames
+
+    log = logging.getLogger("matebot")
+    state = State(pathlib.Path(config.state_dir) / "state.json")
+
+    async with GaggiMateClient(config.machine_host) as client:
+        if dry_run:
+
+            class _DryMessenger:
+                async def start(self): ...
+                async def stop(self): ...
+                async def send(self, text, options=None):
+                    log.info("DRY SEND: %s %s", text, [o.label for o in options or []])
+                    return "0"
+                async def edit(self, ref, text, options=None): ...
+                def events(self):
+                    return _never()
+
+            messenger = _DryMessenger()
+        else:
+            from .messengers import create_messenger
+
+            messenger = create_messenger(config)
+
+        def schedule_sync(*, quiet: bool = False):
+            if config.sync_enabled and config.data_repo:
+                asyncio.create_task(
+                    sync_soon(
+                        client, config.data_repo, messenger.send,
+                        site_title=config.site_title, state=state, quiet=quiet,
+                    )
+                )
+
+        async def save_notes(shot_id: int, notes: dict) -> bool:
+            from .bags import track_shot
+            from .hints import make_hint
+
+            for attempt in range(3):
+                try:
+                    resp = await client.notes_save(shot_id, notes)
+                    log.info("notes saved for %06d: %s", shot_id, resp.get("msg", "?"))
+                    schedule_sync()  # push notes + regenerated journal
+                    if config.hints_enabled:
+                        hint = make_hint(notes)
+                        if hint:
+                            await messenger.send(hint)
+                    bag_msg = track_shot(state, notes)  # no-op unless a bag is registered
+                    if bag_msg:
+                        await messenger.send(bag_msg)
+                    return True
+                except Exception as exc:  # noqa: BLE001
+                    log.warning("notes save attempt %d failed: %s", attempt + 1, exc)
+                    await asyncio.sleep(5 * (attempt + 1))
+            return False
+
+        convo = Conversation(messenger, state, save_notes)
+        cache_frame, latest_frame = make_frame_cache()
+        router = CommandRouter(client, state, convo, messenger, config, latest_frame)
+        # messenger APIs can be flaky at boot; retry instead of crash-looping
+        for attempt in range(8):
+            try:
+                await messenger.start()
+                break
+            except Exception as exc:  # noqa: BLE001
+                if attempt == 7:
+                    raise
+                log.warning("messenger start failed (%s); retry in %ds", exc, 10 * (attempt + 1))
+                await asyncio.sleep(10 * (attempt + 1))
+        try:
+            await convo.resume_if_pending()
+
+            async def pump_events():
+                async for event in messenger.events():
+                    try:
+                        if isinstance(event, TextReply) and event.text.strip().startswith("/"):
+                            if await router.handle(event.text):
+                                continue
+                        await convo.handle_event(event)
+                    except Exception:  # noqa: BLE001 - a flaky send must not kill the bot
+                        log.exception("event handling failed")
+
+            async def pump_shots():
+                import re as _re
+                import time as _time
+
+                last_frame_at = 0.0
+
+                async def tee(source):
+                    nonlocal last_frame_at
+                    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)
+                        cache_frame(frame)
+                        await router.on_frame(frame)
+                        yield frame
+
+                async def on_utility(profile):
+                    # only actual cleaning runs reset the counter, not water flushes
+                    if _re.search(r"(?i)backflush|descale|clean", profile or ""):
+                        state.set("shots_since_clean", 0)
+                        log.info("cleaning run detected (%s); counter reset", profile)
+
+                frames = tee(
+                    replay_frames(replay) if replay else client.status_stream()
+                )
+                watcher = ShotWatcher(
+                    client,
+                    min_duration_s=config.min_shot_s,
+                    ignore_profiles=config.ignore_profiles,
+                    last_known_id=state.get("last_shot_id", -1),
+                    on_utility=on_utility,
+                )
+                async for shot in watcher.shots(frames):
+                    since_clean = state.get("shots_since_clean", 0) + 1
+                    state.set("shots_since_clean", since_clean)
+                    if config.clean_every and since_clean % config.clean_every == 0:
+                        try:
+                            await messenger.send(
+                                f"🧽 {since_clean} espresso shots since the last backflush — "
+                                "the group head would appreciate a round with the blind basket."
+                            )
+                        except Exception:  # noqa: BLE001
+                            log.exception("cleaning reminder failed")
+                    state.update(
+                        last_shot_id=shot.entry.id,
+                        last_shot={
+                            "shot_id": shot.entry.id,
+                            "profile": shot.profile_label or shot.entry.profile_name,
+                            "duration_ms": shot.duration_ms,
+                            "volume_g": shot.entry.volume_g,
+                        },
+                    )
+                    photo = None
+                    if config.plots_enabled:
+                        try:
+                            from .plot import render_shot_png
+                            from .slog import parse_slog
+
+                            parsed = parse_slog(await client.fetch_slog(shot.entry.id))
+                            photo = render_shot_png(
+                                parsed, title=f"Shot #{shot.entry.id} — {parsed.profile_name}"
+                            )
+                        except Exception as exc:  # noqa: BLE001 - photo is a nice-to-have
+                            log.info("shot plot skipped: %s", exc)
+                    try:
+                        await convo.start_shot(
+                            shot.entry.id,
+                            shot.profile_label or shot.entry.profile_name,
+                            shot.duration_ms,
+                            shot.entry.volume_g,
+                            photo=photo,
+                        )
+                    except Exception:  # noqa: BLE001 - keep watching even if messaging fails
+                        log.exception("questionnaire start failed (state kept for resume)")
+                    schedule_sync()  # archive the .slog right away
+
+            async def weekly_digest():
+                from datetime import datetime
+
+                from .commands import build_digest
+                from .digest import seconds_until_sunday_evening
+
+                while True:
+                    await asyncio.sleep(seconds_until_sunday_evening(datetime.now()))
+                    stamp = datetime.now().strftime("%G-W%V")
+                    if state.get("last_digest") == stamp:
+                        continue
+                    try:
+                        text = await build_digest(client, config)
+                        if text:
+                            await messenger.send(text)
+                        state.set("last_digest", stamp)
+                    except Exception:  # noqa: BLE001
+                        log.exception("weekly digest failed")
+
+            tasks = [asyncio.create_task(pump_events()), asyncio.create_task(pump_shots())]
+            if config.digest_enabled:
+                tasks.append(asyncio.create_task(weekly_digest()))
+            done, pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+            for task in pending:
+                task.cancel()
+            for task in done:
+                exc = task.exception()
+                if exc:
+                    raise exc
+        finally:
+            await messenger.stop()
+    return 0
+
+
+async def _never():
+    if False:  # pragma: no cover - typed empty async generator
+        yield
+    await asyncio.Event().wait()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

matebot/commands.py

@@ -0,0 +1,272 @@
+"""Chat commands — messenger-agnostic.
+
+Commands arrive as plain text events starting with "/" (every backend already
+delivers text), so this router works identically on Telegram, Discord and any
+future messenger. It is consulted before the questionnaire so a command never
+gets swallowed as a free-text answer.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any
+
+from .machine import MachineError
+
+log = logging.getLogger(__name__)
+
+MODE_NAMES = {0: "standby", 1: "brew", 2: "steam", 3: "water", 4: "grind"}
+
+HELP = (
+    "/wake — turn the machine on (brew mode); I'll ping you when it's at temperature\n"
+    "/sleep — back to standby\n"
+    "/status — mode, temperature, connectivity\n"
+    "/last — the last logged shot\n"
+    "/fix — redo the questionnaire for the last shot\n"
+    "/newbag <grams> [name] — start tracking a bean bag (optional feature)\n"
+    "/bag — how much is left in the bag\n"
+    "/digest — your last 7 days in espresso\n"
+    "/help — this list"
+)
+
+
+class CommandRouter:
+    def __init__(self, client, state, convo, messenger, config, latest_frame) -> None:
+        self.client = client
+        self.state = state
+        self.convo = convo
+        self.messenger = messenger
+        self.config = config
+        self.latest_frame = latest_frame  # () -> (frame dict | None, age seconds)
+        self._awaiting_ready = False
+        self._args: list[str] = []
+
+    # ------------------------------------------------------------- dispatch
+
+    async def handle(self, text: str) -> bool:
+        """Handle a command; returns True when the text was consumed."""
+        parts = text.strip().split()
+        cmd = parts[0].lower().lstrip("/").split("@")[0]
+        self._args = parts[1:]
+        handler = getattr(self, f"_cmd_{cmd}", None)
+        if handler is None:
+            if cmd == "start":
+                await self.messenger.send("☕ matebot at your service.\n\n" + HELP)
+                return True
+            return False
+        try:
+            await handler()
+        except MachineError as exc:
+            await self.messenger.send(f"⚠️ Can't reach the machine ({exc}). Is it plugged in?")
+        except Exception:  # noqa: BLE001
+            log.exception("command %s failed", cmd)
+            await self.messenger.send("⚠️ That didn't work — check the logs.")
+        return True
+
+    # ------------------------------------------------------------- commands
+
+    async def _cmd_help(self) -> None:
+        await self.messenger.send(HELP)
+
+    async def _run_hook(self, hook: str, label: str) -> bool:
+        """Run a smart-plug shell hook; reports failure to the user."""
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                hook,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.STDOUT,
+            )
+            out, _ = await asyncio.wait_for(proc.communicate(), timeout=20)
+            if proc.returncode != 0:
+                log.warning("%s hook failed (%d): %s", label, proc.returncode, out.decode()[-200:])
+                await self.messenger.send(f"⚠️ The {label} hook failed — check the plug.")
+                return False
+            return True
+        except Exception as exc:  # noqa: BLE001
+            log.warning("%s hook error: %s", label, exc)
+            await self.messenger.send(f"⚠️ The {label} hook errored: {exc}")
+            return False
+
+    async def _machine_online(self) -> bool:
+        _, age = self.latest_frame()
+        return age < 20
+
+    async def _cmd_wake(self) -> None:
+        cold_start = self.config.wake_hook and not await self._machine_online()
+        if self.config.wake_hook and not await self._run_hook(self.config.wake_hook, "wake"):
+            return
+        if cold_start:
+            await self.messenger.send(
+                "🔌 Plug is on — waiting for the machine to boot (can take a minute)…"
+            )
+            for _ in range(90):
+                await asyncio.sleep(1)
+                if await self._machine_online():
+                    break
+            else:
+                await self.messenger.send(
+                    "⚠️ The machine didn't come online. Check the plug and the machine's switch."
+                )
+                return
+        await self.client.send_event("req:change-mode", mode=1)
+        self._awaiting_ready = True
+        await self.messenger.send("🔥 Waking the machine — I'll tell you when it's hot.")
+
+    async def _cmd_sleep(self) -> None:
+        try:
+            await self.client.send_event("req:change-mode", mode=0)
+        except MachineError:
+            if not self.config.sleep_hook:
+                raise
+        self._awaiting_ready = False
+        if self.config.sleep_hook:
+            await asyncio.sleep(3)  # let the machine settle into standby first
+            if await self._run_hook(self.config.sleep_hook, "sleep"):
+                await self.messenger.send("😴 Standby, and the plug is off. Fully dark.")
+                return
+        await self.messenger.send("😴 Machine is going to standby.")
+
+    async def _cmd_status(self) -> None:
+        frame, age = self.latest_frame()
+        if frame is None or age > 20:
+            await self.messenger.send(
+                "🔌 Machine is offline (no status for a while) — probably powered off."
+            )
+            return
+        mode = MODE_NAMES.get(frame.get("m"), "?")
+        ct, tt = frame.get("ct", 0), frame.get("tt", 0)
+        line = f"Machine is in {mode} mode · boiler {ct:.1f}°C"
+        if tt:
+            line += f" → target {tt:.0f}°C"
+        if frame.get("wl") is not None:
+            line += f" · water {frame['wl']}%"
+        since_clean = self.state.get("shots_since_clean", 0)
+        if since_clean:
+            line += f"\n🧽 {since_clean} shots since the last backflush"
+        await self.messenger.send(line)
+
+    async def _cmd_last(self) -> None:
+        last = self.state.get("last_shot")
+        if not last:
+            await self.messenger.send("No shot logged yet.")
+            return
+        notes = self.state.get("last_notes", {})
+        bits = [f"Shot #{last['shot_id']} — {last.get('profile', '?')}"]
+        bits.append(f"{last.get('duration_ms', 0) / 1000:.0f}s")
+        if last.get("volume_g"):
+            bits.append(f"{last['volume_g']:.1f} g")
+        if notes.get("beanType"):
+            bits.append(notes["beanType"])
+        text = " · ".join(bits)
+        if self.config.journal_url:
+            text += f"\n{self.config.journal_url.rstrip('/')}/#{last['shot_id']:06d}"
+        await self.messenger.send(text)
+
+    async def _cmd_fix(self) -> None:
+        last = self.state.get("last_shot")
+        if not last:
+            await self.messenger.send("No shot to fix yet.")
+            return
+        await self.messenger.send(f"✏️ Let's redo shot #{last['shot_id']}:")
+        await self.convo.start_shot(
+            last["shot_id"], last.get("profile", ""),
+            last.get("duration_ms", 0), last.get("volume_g", 0.0),
+        )
+
+    async def _cmd_newbag(self) -> None:
+        from . import bags
+
+        usage = "Usage: /newbag <grams> [name] — e.g. /newbag 250 Mondo Classico"
+        if not self._args:
+            await self.messenger.send(usage)
+            return
+        try:
+            grams = float(self._args[0].replace("g", ""))
+        except ValueError:
+            await self.messenger.send(usage)
+            return
+        name = (
+            " ".join(self._args[1:])
+            or self.state.get("last_notes", {}).get("beanType")
+            or "Unnamed beans"
+        )
+        await self.messenger.send(bags.open_bag(self.state, grams, name))
+
+    async def _cmd_bag(self) -> None:
+        from . import bags
+
+        await self.messenger.send(bags.bag_status(self.state))
+
+    async def _cmd_digest(self) -> None:
+        text = await build_digest(self.client, self.config)
+        await self.messenger.send(text or "No shots in the last 7 days. The machine misses you.")
+
+    # ------------------------------------------------------------- frames
+
+    async def on_frame(self, frame: dict[str, Any]) -> None:
+        """Called for every status frame: ready ping after /wake, tank watch."""
+        if frame.get("tp") != "evt:status":
+            return
+        await self._check_water(frame)
+        if not self._awaiting_ready:
+            return
+        ct, tt = frame.get("ct", 0), frame.get("tt", 0)
+        if frame.get("m") == 1 and tt >= 60 and ct >= tt - 1.0:
+            self._awaiting_ready = False
+            text = f"☕ {ct:.1f}°C — the machine is ready when you are."
+            wl = frame.get("wl")
+            if wl is not None and self.config.water_warn_pct and wl < self.config.water_warn_pct:
+                text += f" The tank is at {wl}%, though."
+            await self.messenger.send(text)
+
+    async def _check_water(self, frame: dict[str, Any]) -> None:
+        """Warn once when the tank runs low; re-arm after a refill."""
+        wl = frame.get("wl")
+        threshold = self.config.water_warn_pct
+        if wl is None or not threshold:
+            return
+        warned = self.state.get("water_warned", False)
+        if not warned and wl < threshold:
+            self.state.set("water_warned", True)
+            await self.messenger.send(
+                f"💧 Water tank at {wl}% — maybe top it up before the next shot."
+            )
+        elif warned and wl >= threshold + 10:
+            self.state.set("water_warned", False)
+
+
+async def build_digest(client, config) -> str | None:
+    """Digest from the machine index, falling back to the local journal data."""
+    from datetime import datetime
+    from pathlib import Path
+
+    from . import digest
+
+    rows = None
+    try:
+        rows = digest.rows_from_index(await client.fetch_index())
+    except Exception:  # noqa: BLE001 - machine may be off
+        site_index = Path(config.data_repo or "") / "docs" / "index.json"
+        if config.data_repo and site_index.exists():
+            rows = digest.rows_from_site_index(site_index)
+    if rows is None:
+        return None
+    return digest.compute(rows, now=datetime.now(), journal_url=config.journal_url)
+
+
+def make_frame_cache():
+    """Returns (update, get): cache the newest status frame with a timestamp."""
+    box: dict[str, Any] = {"frame": None, "ts": 0.0}
+
+    def update(frame: dict) -> None:
+        if frame.get("tp") == "evt:status":
+            box["frame"] = frame
+            box["ts"] = time.monotonic()
+
+    def get():
+        age = time.monotonic() - box["ts"] if box["frame"] else 1e9
+        return box["frame"], age
+
+    return update, get