matebot 0.2.0__py3-none-any.whl

matebot/messengers/__init__.py

@@ -0,0 +1,28 @@
+from .base import Event, Messenger, Option, OptionSelected, TextReply
+
+
+def create_messenger(config) -> Messenger:
+    """Instantiate the configured backend (imports lazily: extras are optional)."""
+    kind = config.messenger
+    if kind == "telegram":
+        from .telegram import TelegramMessenger
+
+        return TelegramMessenger(config.telegram_token, config.telegram_chat_id)
+    if kind == "discord":
+        from .discord import DiscordMessenger
+
+        return DiscordMessenger(config.discord_token, config.discord_channel_id)
+    raise ValueError(
+        f"unknown messenger {kind!r} (supported: telegram, discord; "
+        "matrix is planned — see README for WhatsApp options)"
+    )
+
+
+__all__ = [
+    "Event",
+    "Messenger",
+    "Option",
+    "OptionSelected",
+    "TextReply",
+    "create_messenger",
+]

matebot/messengers/base.py

@@ -0,0 +1,58 @@
+"""Messenger abstraction: everything the conversation engine needs, nothing more.
+
+A backend renders prompts (text + option buttons where the platform has them),
+and yields user interactions as a single event stream. Option ids stay ≤64
+bytes so they fit Telegram ``callback_data`` and Discord ``custom_id``.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+
+
+@dataclass
+class Option:
+    id: str  # e.g. "g|59|r|4"
+    label: str  # e.g. "★★★★"
+
+
+@dataclass
+class OptionSelected:
+    option_id: str
+
+
+@dataclass
+class TextReply:
+    text: str
+
+
+Event = OptionSelected | TextReply
+
+
+class Messenger(ABC):
+    """One chat/channel with one user; the espresso machine's voice."""
+
+    @abstractmethod
+    async def start(self) -> None: ...
+
+    @abstractmethod
+    async def stop(self) -> None: ...
+
+    @abstractmethod
+    async def send(self, text: str, options: list[Option] | None = None) -> str:
+        """Send a message, return an opaque reference usable with edit()."""
+
+    @abstractmethod
+    async def edit(self, ref: str, text: str, options: list[Option] | None = None) -> None:
+        """Replace a previously sent message's text/options (best effort)."""
+
+    async def send_photo(self, image: bytes, caption: str) -> str:
+        """Send an image with caption; backends without photo support fall
+        back to the caption text."""
+        return await self.send(caption)
+
+    @abstractmethod
+    def events(self) -> AsyncIterator[Event]:
+        """User interactions, in order. Runs until stop()."""

matebot/messengers/discord.py

@@ -0,0 +1,88 @@
+"""Discord backend (discord.py v2: gateway websocket + button Views)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import AsyncIterator
+
+from .base import Event, Messenger, Option, OptionSelected, TextReply
+
+log = logging.getLogger(__name__)
+
+
+class DiscordMessenger(Messenger):
+    def __init__(self, token: str, channel_id: int | str) -> None:
+        import discord
+
+        self.token = token
+        self.channel_id = int(channel_id)
+        self._queue: asyncio.Queue[Event] = asyncio.Queue()
+        self._ready = asyncio.Event()
+        self._task: asyncio.Task | None = None
+
+        intents = discord.Intents.default()
+        intents.message_content = True
+        self.client = discord.Client(intents=intents)
+
+        @self.client.event
+        async def on_ready():
+            self._ready.set()
+            log.info("discord messenger ready in channel %s", self.channel_id)
+
+        @self.client.event
+        async def on_message(message):
+            if message.author == self.client.user or message.channel.id != self.channel_id:
+                return
+            await self._queue.put(TextReply(message.content))
+
+        @self.client.event
+        async def on_interaction(interaction):
+            if interaction.type == discord.InteractionType.component:
+                await interaction.response.defer()
+                await self._queue.put(OptionSelected(interaction.data["custom_id"]))
+
+    async def start(self) -> None:
+        self._task = asyncio.create_task(self.client.start(self.token))
+        await asyncio.wait_for(self._ready.wait(), timeout=60)
+
+    async def stop(self) -> None:
+        await self.client.close()
+        if self._task:
+            self._task.cancel()
+
+    def _view(self, options: list[Option] | None):
+        if not options:
+            return None
+        import discord
+
+        view = discord.ui.View(timeout=None)
+        for o in options:
+            view.add_item(discord.ui.Button(label=o.label, custom_id=o.id))
+        return view
+
+    async def send(self, text: str, options: list[Option] | None = None) -> str:
+        channel = self.client.get_channel(self.channel_id)
+        msg = await channel.send(text, view=self._view(options))
+        return str(msg.id)
+
+    async def send_photo(self, image: bytes, caption: str) -> str:
+        import io as _io
+
+        import discord
+
+        channel = self.client.get_channel(self.channel_id)
+        msg = await channel.send(caption, file=discord.File(_io.BytesIO(image), "shot.png"))
+        return str(msg.id)
+
+    async def edit(self, ref: str, text: str, options: list[Option] | None = None) -> None:
+        try:
+            channel = self.client.get_channel(self.channel_id)
+            msg = await channel.fetch_message(int(ref))
+            await msg.edit(content=text, view=self._view(options))
+        except Exception as exc:  # noqa: BLE001 - edits are cosmetic
+            log.debug("edit failed: %s", exc)
+
+    async def events(self) -> AsyncIterator[Event]:
+        while True:
+            yield await self._queue.get()

matebot/messengers/telegram.py

@@ -0,0 +1,118 @@
+"""Telegram backend (python-telegram-bot v20+ async API, long-polling)."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import AsyncIterator
+
+from .base import Event, Messenger, Option, OptionSelected, TextReply
+
+log = logging.getLogger(__name__)
+
+
+class TelegramMessenger(Messenger):
+    def __init__(self, token: str, chat_id: int | str) -> None:
+        from telegram.ext import (
+            Application,
+            CallbackQueryHandler,
+            MessageHandler,
+            filters,
+        )
+
+        self.chat_id = int(chat_id)
+        self._queue: asyncio.Queue[Event] = asyncio.Queue()
+        self.app = Application.builder().token(token).build()
+        self.app.add_handler(CallbackQueryHandler(self._on_callback))
+        self.app.add_handler(
+            MessageHandler(filters.TEXT & filters.Chat(self.chat_id), self._on_text)
+        )
+
+    async def _on_callback(self, update, context) -> None:
+        query = update.callback_query
+        await query.answer()
+        if query.message and query.message.chat_id != self.chat_id:
+            return
+        await self._queue.put(OptionSelected(query.data))
+
+    async def _on_text(self, update, context) -> None:
+        await self._queue.put(TextReply(update.message.text))
+
+    async def start(self) -> None:
+        from telegram import BotCommand
+
+        await self.app.initialize()
+        await self.app.start()
+        with contextlib.suppress(Exception):  # menu is cosmetic
+            await self.app.bot.set_my_commands([
+                BotCommand("wake", "turn the machine on, ping when hot"),
+                BotCommand("sleep", "machine to standby"),
+                BotCommand("status", "mode, temperature, connectivity"),
+                BotCommand("last", "last logged shot"),
+                BotCommand("fix", "redo the last shot's log"),
+                BotCommand("bag", "how much is left in the bean bag"),
+                BotCommand("newbag", "start tracking a bean bag"),
+                BotCommand("help", "list commands"),
+            ])
+        await self.app.updater.start_polling(drop_pending_updates=True)
+        log.info("telegram messenger polling as chat %s", self.chat_id)
+
+    async def stop(self) -> None:
+        await self.app.updater.stop()
+        await self.app.stop()
+        await self.app.shutdown()
+
+    def _keyboard(self, options: list[Option] | None):
+        if not options:
+            return None
+        from telegram import InlineKeyboardButton, InlineKeyboardMarkup
+
+        buttons = [InlineKeyboardButton(o.label, callback_data=o.id) for o in options]
+        # ratings in rows of three (a single row of five truncates on phones),
+        # everything else stacked
+        if all(o.id.split("|")[2] == "r" for o in options):
+            rows = [buttons[i : i + 3] for i in range(0, len(buttons), 3)]
+        else:
+            rows = [[b] for b in buttons]
+        return InlineKeyboardMarkup(rows)
+
+    async def send(self, text: str, options: list[Option] | None = None) -> str:
+        # telegram API connectivity can flap; a lost send must not crash the bot
+        last_exc = None
+        for attempt in range(5):
+            try:
+                msg = await self.app.bot.send_message(
+                    self.chat_id, text, reply_markup=self._keyboard(options)
+                )
+                return str(msg.message_id)
+            except Exception as exc:  # noqa: BLE001 - NetworkError et al.
+                last_exc = exc
+                log.warning("send attempt %d failed: %s", attempt + 1, exc)
+                await asyncio.sleep(2 * (attempt + 1))
+        raise last_exc
+
+    async def send_photo(self, image: bytes, caption: str) -> str:
+        last_exc = None
+        for attempt in range(5):
+            try:
+                msg = await self.app.bot.send_photo(self.chat_id, photo=image, caption=caption)
+                return str(msg.message_id)
+            except Exception as exc:  # noqa: BLE001
+                last_exc = exc
+                log.warning("photo send attempt %d failed: %s", attempt + 1, exc)
+                await asyncio.sleep(2 * (attempt + 1))
+        raise last_exc
+
+    async def edit(self, ref: str, text: str, options: list[Option] | None = None) -> None:
+        try:
+            await self.app.bot.edit_message_text(
+                text, chat_id=self.chat_id, message_id=int(ref),
+                reply_markup=self._keyboard(options),
+            )
+        except Exception as exc:  # noqa: BLE001 - edits are cosmetic
+            log.debug("edit failed: %s", exc)
+
+    async def events(self) -> AsyncIterator[Event]:
+        while True:
+            yield await self._queue.get()

matebot/plot.py

@@ -0,0 +1,100 @@
+"""Render a shot as a PNG chart (sent as the post-shot photo).
+
+Same visual language as the journal and the GaggiMate web UI: temperature on
+the left axis, pressure/flow on the right, weight on its own scale, dashed
+targets, phase markers. matplotlib is an optional dependency (``[plots]``
+extra) — callers fall back to a text summary when it is missing.
+"""
+
+from __future__ import annotations
+
+import io
+
+from .slog import Shot
+
+# Same palette as the GaggiMate web UI shot chart (design match, no code copied)
+COLORS = {
+    "temp": "#F0561D",
+    "target_temp": "#731F00",
+    "press": "#0066CC",
+    "flow": "#63993D",
+    "puck": "#204D00",
+    "weight": "#8B5CF6",
+    "wflow": "#4b2e8d",
+    "phase": "#6B7280",
+}
+
+
+def render_shot_png(shot: Shot, *, title: str | None = None) -> bytes:
+    import matplotlib
+
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    t = shot.times_s
+    s = shot.series
+    have = lambda k: k in s and any(s[k])  # noqa: E731
+
+    fig, ax_temp = plt.subplots(figsize=(8, 4.5), dpi=110)
+    ax_bar = ax_temp.twinx()
+
+    dash = (0, (4, 4))
+    if have("ct"):
+        ax_temp.plot(t, s["ct"], color=COLORS["temp"], lw=2.2, label="Temp")
+    if have("tt"):
+        ax_temp.plot(t, s["tt"], color=COLORS["target_temp"], lw=1.4, ls=dash)
+    if have("cp"):
+        ax_bar.plot(t, s["cp"], color=COLORS["press"], lw=2.2, label="Pressure")
+    if have("tp"):
+        ax_bar.plot(t, s["tp"], color=COLORS["press"], lw=1.4, ls=dash, alpha=0.8)
+    if have("fl"):
+        ax_bar.plot(t, s["fl"], color=COLORS["flow"], lw=1.8, label="Pump flow")
+    if have("tf"):
+        ax_bar.plot(t, s["tf"], color=COLORS["flow"], lw=1.4, ls=dash, alpha=0.8)
+    if have("pf"):
+        ax_bar.plot(t, s["pf"], color=COLORS["puck"], lw=1.8, label="Puck flow")
+
+    weight = s.get("v") if have("v") else s.get("ev") if have("ev") else None
+    if weight:
+        ax_g = ax_temp.twinx()
+        ax_g.spines.right.set_position(("axes", 1.12))
+        ax_g.plot(t, weight, color=COLORS["weight"], lw=2.2, label="Weight")
+        ax_g.set_ylabel("g", color=COLORS["weight"])
+        ax_g.set_ylim(bottom=0)
+        ax_g.tick_params(axis="y", colors=COLORS["weight"], labelsize=8)
+
+    for phase in shot.phases:
+        px = phase.sample_index * shot.sample_interval_ms / 1000
+        if 0.3 < px < (t[-1] if t else 0) - 0.3:
+            ax_temp.axvline(px, color=COLORS["phase"], lw=1.0, alpha=0.8)
+            ax_temp.annotate(
+                phase.name[:18], (px, 0.99), xycoords=("data", "axes fraction"),
+                rotation=90, va="top", ha="right", fontsize=6.5, color="white",
+                bbox={"boxstyle": "round,pad=0.25", "facecolor": "#162132",
+                      "alpha": 0.75, "edgecolor": "none"},
+            )
+
+    ax_temp.set_xlabel("s", fontsize=8)
+    ax_temp.set_ylabel("°C", color=COLORS["temp"], fontsize=9)
+    ax_temp.tick_params(labelsize=8)
+    ax_temp.tick_params(axis="y", colors=COLORS["temp"])
+    ax_bar.set_ylabel("bar · g/s", color=COLORS["press"], fontsize=9)
+    ax_bar.tick_params(axis="y", colors=COLORS["press"], labelsize=8)
+    ax_bar.set_ylim(0, 16)
+    ax_temp.grid(True, axis="y", lw=0.3, alpha=0.4)
+    if title:
+        ax_temp.set_title(title, fontsize=10)
+
+    handles, labels = [], []
+    for ax in fig.axes:
+        h, lab = ax.get_legend_handles_labels()
+        handles += h
+        labels += lab
+    fig.legend(handles, labels, loc="lower center", ncol=len(labels),
+               bbox_to_anchor=(0.5, 0.0), fontsize=7.5, frameon=False)
+
+    fig.tight_layout(rect=(0, 0.08, 1, 1))
+    buf = io.BytesIO()
+    fig.savefig(buf, format="png")
+    plt.close(fig)
+    return buf.getvalue()

matebot/sitegen.py

@@ -0,0 +1,119 @@
+"""Generate the static shot-explorer site (GitHub Pages friendly).
+
+Input:  a folder of ``NNNNNN.slog`` + optional ``NNNNNN.json`` notes files
+        (the layout of a matebot/GaggiMate data repo's ``shots/`` dir).
+Output: ``docs/`` with a self-contained viewer (no CDN):
+        index.html + app.js + style.css + index.json + shots/<id>.json
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+import json
+import logging
+from pathlib import Path
+
+from .slog import Shot, SlogError, parse_slog
+
+log = logging.getLogger(__name__)
+
+WEB_ASSETS = (
+    "index.html",
+    "app.js",
+    "style.css",
+    "vendor/chart.umd.js",
+    "vendor/chartjs-plugin-annotation.min.js",
+)
+
+
+def _round(values: list[float], digits: int) -> list[float]:
+    return [round(v, digits) for v in values]
+
+
+def _shot_payload(shot: Shot, notes: dict | None) -> dict:
+    s = shot.series
+    step = shot.sample_interval_ms / 1000.0
+    return {
+        "header": {
+            "profile": shot.profile_name,
+            "ts": shot.start_epoch,
+            "duration_s": round(shot.duration_ms / 1000, 1),
+            "final_g": shot.final_weight_g,
+            "phases": [
+                {"t": round(p.sample_index * step, 2), "name": p.name} for p in shot.phases
+            ],
+        },
+        "series": {
+            "t": _round([t * step for t in s.get("t", [])], 2),
+            "ct": _round(s.get("ct", []), 1),
+            "tt": _round(s.get("tt", []), 1),
+            "cp": _round(s.get("cp", []), 2),
+            "tp": _round(s.get("tp", []), 2),
+            "fl": _round(s.get("fl", []), 2),
+            "tf": _round(s.get("tf", []), 2),
+            "pf": _round(s.get("pf", []), 2),
+            "vf": _round(s.get("vf", []), 2),
+            "v": _round(s.get("v", []), 1),
+            "ev": _round(s.get("ev", []), 1),
+        },
+        "notes": notes or {},
+    }
+
+
+def _load_notes(path: Path) -> dict | None:
+    try:
+        raw = path.read_bytes()
+    except OSError:
+        return None
+    if not raw.lstrip().startswith(b"{"):  # gzip/HTML masquerade, see machine.py
+        log.warning("skipping non-JSON notes file %s", path.name)
+        return None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+
+
+def generate(shots_dir: str | Path, out_dir: str | Path, *, title: str = "Shot Journal") -> int:
+    """Build the site; returns the number of shots included."""
+    shots_dir, out_dir = Path(shots_dir), Path(out_dir)
+    (out_dir / "shots").mkdir(parents=True, exist_ok=True)
+
+    index = []
+    for slog_path in sorted(shots_dir.glob("*.slog")):
+        try:
+            shot = parse_slog(slog_path.read_bytes())
+        except SlogError as exc:
+            log.warning("skipping %s: %s", slog_path.name, exc)
+            continue
+        sid = slog_path.stem
+        notes = _load_notes(slog_path.with_suffix(".json"))
+        payload = _shot_payload(shot, notes)
+        (out_dir / "shots" / f"{sid}.json").write_text(
+            json.dumps(payload, separators=(",", ":"))
+        )
+        cp = payload["series"]["cp"]
+        index.append(
+            {
+                "id": sid,
+                "ts": shot.start_epoch,
+                "duration_s": payload["header"]["duration_s"],
+                "profile": shot.profile_name,
+                "final_g": shot.final_weight_g,
+                "peak_bar": max(cp) if cp else 0,
+                "rating": (notes or {}).get("rating") or 0,
+                "bean": (notes or {}).get("beanType", ""),
+                "ratio": (notes or {}).get("ratio", ""),
+                "taste": (notes or {}).get("balanceTaste", ""),
+            }
+        )
+
+    index.sort(key=lambda e: e["id"], reverse=True)
+    (out_dir / "index.json").write_text(json.dumps({"title": title, "shots": index}))
+
+    web = importlib.resources.files("matebot") / "web"
+    (out_dir / "vendor").mkdir(exist_ok=True)
+    for name in WEB_ASSETS:
+        (out_dir / name).write_text((web / name).read_text())
+    log.info("site generated: %d shots -> %s", len(index), out_dir)
+    return len(index)