studio-baton 0.1.0__py3-none-any.whl

baton/__init__.py

@@ -0,0 +1,19 @@
+"""Studio Baton — scripted operations for a one-to-one teaching studio.
+
+The public surface is the ``baton`` command-line tool. Everything a skill or an
+agent needs to do is one subcommand with a stable exit code; nothing is left to
+be assembled by hand from raw API calls.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # Read from the installed distribution rather than repeating the number
+    # here. Two copies drift, and the one that drifts is the one a user reads
+    # off `baton --version` when they report a bug — which is how a report
+    # ends up describing a build nobody shipped.
+    __version__ = version("studio-baton")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

baton/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m baton`` alongside the installed ``baton`` script."""
+
+from .cli.app import main
+
+if __name__ == "__main__":
+    main()

baton/adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Everything that talks to something outside Baton.
+
+Each subpackage defines a Protocol and one or more drivers behind it, chosen by
+a single line of configuration. Pipelines depend on the Protocol only, which is
+what lets the whole suite run offline against `baton.adapters.fakes`.
+"""

baton/adapters/cal/__init__.py

@@ -0,0 +1,27 @@
+"""Calendar drivers, selected by configuration."""
+
+from __future__ import annotations
+
+from ...core.config import Config
+from ...errors import ConfigError
+from .base import CalendarEvent, CalendarStore
+
+#: Drivers this build implements.
+DRIVERS = ("google",)
+
+
+def open_calendar(config: Config) -> CalendarStore:
+    """Build the configured calendar."""
+    driver = str(config.get("calendar.driver", "google"))
+    if driver == "google":
+        from .google import GoogleCalendar
+
+        return GoogleCalendar.from_config(config)
+    raise ConfigError(
+        f"Unknown calendar driver `{driver}`.",
+        remedy=f"Set calendar.driver to one of: {', '.join(DRIVERS)}.",
+        details={"driver": driver, "supported": list(DRIVERS)},
+    )
+
+
+__all__ = ["DRIVERS", "CalendarEvent", "CalendarStore", "open_calendar"]

baton/adapters/cal/base.py

@@ -0,0 +1,51 @@
+"""What a calendar must do.
+
+Small on purpose. Baton books lessons and cancels them; it is not a calendar
+client. Anything richer belongs in the calendar app the studio already uses.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class CalendarEvent:
+    """One booking."""
+
+    id: str
+    title: str
+    start: str
+    """Local ISO 8601 with offset, e.g. ``2026-08-20T17:00:00+07:00``."""
+    end: str
+    description: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "start": self.start,
+            "end": self.end,
+            "description": self.description,
+        }
+
+
+@runtime_checkable
+class CalendarStore(Protocol):
+    """Creates, lists, and removes bookings."""
+
+    def create(self, event: CalendarEvent) -> CalendarEvent:
+        """Create one event. Returns it with the calendar's assigned id."""
+        ...
+
+    def list_between(self, start: str, end: str) -> list[CalendarEvent]:
+        """Events overlapping the window, in start order."""
+        ...
+
+    def delete(self, event_id: str) -> None:
+        """Remove one event. A missing event is not an error — the desired
+        state has been reached, and a cancel run twice must not fail."""
+        ...
+
+    def health(self) -> None: ...

baton/adapters/cal/google.py

@@ -0,0 +1,136 @@
+"""Google Calendar.
+
+Behind the ``google`` extra, like the media drivers, and for the same reason:
+someone using Baton without a calendar never installs the SDK, and turning it
+on without it gets a sentence rather than an ImportError.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from ...core.config import Config
+from ...errors import BatonError, ConfigError, UpstreamError
+from .base import CalendarEvent
+
+
+def _require_google() -> Any:
+    try:
+        from google.oauth2.credentials import Credentials
+        from googleapiclient.discovery import build
+    except ImportError as exc:
+        raise ConfigError(
+            "The Google client libraries are not installed.",
+            remedy="Install them with `pip install 'studio-baton[google]'`.",
+        ) from exc
+    return build, Credentials
+
+
+class GoogleCalendar:
+    """A :class:`~baton.adapters.cal.base.CalendarStore` over Google Calendar."""
+
+    driver = "google"
+
+    SCOPES: ClassVar[list[str]] = ["https://www.googleapis.com/auth/calendar"]
+
+    def __init__(self, config: Config, calendar_id: str = "primary") -> None:
+        self.config = config
+        self.calendar_id = calendar_id
+        self._service: Any = None
+
+    @classmethod
+    def from_config(cls, config: Config) -> GoogleCalendar:
+        return cls(config, calendar_id=str(config.get("calendar.google.calendar_id", "primary")))
+
+    @property
+    def service(self) -> Any:
+        if self._service is None:
+            build, Credentials = _require_google()
+            credentials = Credentials(
+                token=None,
+                refresh_token=str(self.config.secret("calendar.google.refresh_token_env")),
+                client_id=str(self.config.secret("calendar.google.client_id_env")),
+                client_secret=str(self.config.secret("calendar.google.client_secret_env")),
+                token_uri="https://oauth2.googleapis.com/token",  # noqa: S106 - public endpoint
+                scopes=self.SCOPES,
+            )
+            self._service = build("calendar", "v3", credentials=credentials, cache_discovery=False)
+        return self._service
+
+    @staticmethod
+    def _event(raw: dict[str, Any]) -> CalendarEvent:
+        start = raw.get("start", {}) or {}
+        end = raw.get("end", {}) or {}
+        return CalendarEvent(
+            id=str(raw.get("id", "")),
+            title=str(raw.get("summary", "")),
+            start=str(start.get("dateTime") or start.get("date") or ""),
+            end=str(end.get("dateTime") or end.get("date") or ""),
+            description=str(raw.get("description", "")),
+        )
+
+    def create(self, event: CalendarEvent) -> CalendarEvent:
+        created = (
+            self.service.events()
+            .insert(
+                calendarId=self.calendar_id,
+                body={
+                    "summary": event.title,
+                    "description": event.description,
+                    "start": {"dateTime": event.start},
+                    "end": {"dateTime": event.end},
+                },
+            )
+            .execute()
+        )
+        return self._event(created)
+
+    def list_between(self, start: str, end: str) -> list[CalendarEvent]:
+        response = (
+            self.service.events()
+            .list(
+                calendarId=self.calendar_id,
+                timeMin=start,
+                timeMax=end,
+                singleEvents=True,
+                orderBy="startTime",
+                maxResults=250,
+            )
+            .execute()
+        )
+        return [self._event(item) for item in response.get("items", [])]
+
+    def delete(self, event_id: str) -> None:
+        from googleapiclient.errors import HttpError
+
+        try:
+            self.service.events().delete(calendarId=self.calendar_id, eventId=event_id).execute()
+        except HttpError as exc:
+            # Already gone is the desired state, not a failure: a cancel run
+            # twice must not report an error the second time.
+            if getattr(exc, "status_code", None) in (404, 410):
+                return
+            raise UpstreamError(
+                f"Google Calendar refused the delete: {exc}", service="google-calendar"
+            ) from exc
+
+    def health(self) -> None:
+        """Prove the credentials still work.
+
+        Google refreshes the access token lazily, on the first call, and a
+        refresh token that has been revoked or has expired fails there with a
+        `RefreshError` rather than anything Baton defines. Left alone it reaches
+        `doctor` as a traceback — which is the one thing doctor must never
+        print, since its whole job is to name every problem at once.
+        """
+        try:
+            self.service.calendars().get(calendarId=self.calendar_id).execute()
+        except BatonError:
+            raise
+        except Exception as exc:  # any vendor failure is a failed check, not a crash
+            raise UpstreamError(
+                f"Google Calendar refused the credentials: {exc}",
+                service="google-calendar",
+                remedy="Re-authorise the calendar and update the refresh token, "
+                "then run `baton doctor` again.",
+            ) from exc

baton/adapters/chat/__init__.py

@@ -0,0 +1,43 @@
+"""Chat drivers, selected by one line of configuration."""
+
+from __future__ import annotations
+
+from ...core.config import Config
+from ...errors import ConfigError
+from .base import Messenger, SendOutcome, resolve_contact
+from .drivers import LineMessenger, TelegramMessenger, WebhookMessenger
+
+#: Every driver this build implements.
+DRIVERS = ("line", "telegram", "webhook")
+
+
+def open_chat(config: Config) -> Messenger:
+    """Build the configured messenger.
+
+    Raises:
+        ConfigError: The driver is unknown or its credentials are missing.
+    """
+    driver = str(config.get("chat.driver", "line"))
+    if driver == "line":
+        return LineMessenger.from_config(config)
+    if driver == "telegram":
+        return TelegramMessenger.from_config(config)
+    if driver == "webhook":
+        return WebhookMessenger.from_config(config)
+    raise ConfigError(
+        f"Unknown chat driver `{driver}`.",
+        remedy=f"Set chat.driver to one of: {', '.join(DRIVERS)}.",
+        details={"driver": driver, "supported": list(DRIVERS)},
+    )
+
+
+__all__ = [
+    "DRIVERS",
+    "LineMessenger",
+    "Messenger",
+    "SendOutcome",
+    "TelegramMessenger",
+    "WebhookMessenger",
+    "open_chat",
+    "resolve_contact",
+]

baton/adapters/chat/base.py

@@ -0,0 +1,129 @@
+"""What a messenger must do, and how a typed name becomes a recipient.
+
+The gate is the point of this subsystem, so the protocol reflects it:
+:meth:`Messenger.resolve` answers "does this recipient exist" *before* anything
+is sent, and :meth:`SendOutcome.sent` is a fact the caller records — never an
+assumption the caller makes from the absence of an error.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from ...core.config import Config
+from ...errors import NeedsHumanError
+
+
+@dataclass(frozen=True)
+class SendOutcome:
+    """What one attempted send actually did."""
+
+    sent: bool
+    recipient: str
+    detail: str = ""
+    warnings: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {"sent": self.sent, "recipient": self.recipient}
+        if self.detail:
+            payload["detail"] = self.detail
+        if self.warnings:
+            payload["warnings"] = self.warnings
+        return payload
+
+
+@runtime_checkable
+class Messenger(Protocol):
+    """Delivers a text message to a named recipient."""
+
+    def resolve(self, name: str) -> str:
+        """A typed name to a platform recipient id.
+
+        Raises:
+            NeedsHumanError: The name matches no configured contact, or more
+                than one. The error carries the candidates; a recipient is
+                never guessed, because a message about one learner delivered
+                to the wrong household is worse than no message.
+        """
+        ...
+
+    def send(self, recipient_id: str, text: str) -> SendOutcome:
+        """Deliver one text message.
+
+        Implementations retry transient faults internally; the outcome records
+        the final truth rather than letting a caller infer it.
+        """
+        ...
+
+    def health(self) -> None:
+        """Prove credentials work, without sending anything."""
+        ...
+
+
+def resolve_contact(config: Config, query: str) -> tuple[str, str]:
+    """Resolve a typed name against the profile's contacts.
+
+    Same stance as learner resolution, for the same reason: exact or alias
+    only. A recipient alias list is short enough that a partial match being
+    "helpfully" completed is all it takes to send a child's progress report to
+    the wrong person.
+
+    Returns:
+        ``(contact_key, recipient_id)`` — the key names the contact in
+        configuration; the id is the *value* of the environment variable named
+        by that contact's ``id_env``, ready for a driver to deliver to. The
+        name of the variable is never what gets sent.
+
+    Raises:
+        NeedsHumanError: No match, or several. Carries the candidates.
+        ConfigError: The matched contact's ``id_env`` names a variable that is
+            not set — the same failure every other credential reports.
+    """
+    contacts = config.section("chat.contacts")
+    if not contacts:
+        raise NeedsHumanError(
+            "No contacts are configured.",
+            candidates=[],
+            remedy="Add a `chat.contacts` block to baton.yaml before sending anything.",
+        )
+
+    wanted = query.strip().casefold()
+    # Keyed by contact key, not a list: the same alias written twice under one
+    # contact is one match, not two — a duplicate would report an ambiguity
+    # that does not exist. A contact whose *key* matches wins outright.
+    exact: dict[str, dict[str, Any]] = {}
+    for key, entry in contacts.items():
+        if not isinstance(entry, dict):
+            continue
+        name = str(key)
+        if name.casefold() == wanted:
+            exact = {name: entry}
+            break
+        for alias in entry.get("aliases", []) or []:
+            if str(alias).strip().casefold() == wanted:
+                exact.setdefault(name, entry)
+
+    if len(exact) == 1:
+        key, entry = next(iter(exact.items()))
+        if not str(entry.get("id_env", "")).strip():
+            raise NeedsHumanError(
+                f"Contact `{key}` has no id_env.",
+                candidates=[],
+                remedy=f"Set chat.contacts.{key}.id_env to the environment variable "
+                "holding their platform id.",
+            )
+        return key, str(config.secret(f"chat.contacts.{key}.id_env"))
+
+    if len(exact) > 1:
+        raise NeedsHumanError(
+            f"“{query}” matches more than one contact.",
+            candidates=[{"name": key} for key in exact],
+            remedy="Use the contact's exact name from baton.yaml.",
+        )
+
+    raise NeedsHumanError(
+        f"No contact matches “{query}”.",
+        candidates=[{"name": str(key)} for key in contacts],
+        remedy="Check chat.contacts in baton.yaml, or add the person first.",
+    )

baton/adapters/chat/drivers.py

@@ -0,0 +1,260 @@
+"""Message drivers: LINE, Telegram, and a generic webhook.
+
+All three are plain HTTP with a token, so they share one shape and differ only
+in envelope. That sameness is deliberate — the original system had LINE logic
+duplicated across three skills, and every copy had drifted by the time anyone
+looked.
+"""
+
+from __future__ import annotations
+
+import hmac
+import json
+from typing import Any
+from urllib.parse import quote
+
+from ...core.config import Config
+from ...core.retry import http_request
+from ...errors import ConfigError, UpstreamError
+from .base import SendOutcome, resolve_contact
+
+
+class _HttpMessenger:
+    """Shared plumbing for the HTTP drivers."""
+
+    driver = "http"
+
+    def __init__(self, token: str, *, api_root: str, service: str, timeout: float = 20.0) -> None:
+        self.token = token
+        self.api_root = api_root.rstrip("/")
+        self.service = service
+        self.timeout = timeout
+
+    # -- to be provided by each driver ------------------------------------
+
+    # Stubs, not abstract methods: each driver overrides all four, and an
+    # ABC would force an import-time metaclass dance for four one-liners.
+    def _endpoint(self, recipient_id: str) -> str:  # pragma: no cover - overridden
+        raise NotImplementedError
+
+    def _payload(self, recipient_id: str, text: str) -> dict[str, Any]:  # pragma: no cover
+        raise NotImplementedError
+
+    def _headers(self) -> dict[str, str]:  # pragma: no cover - overridden
+        raise NotImplementedError
+
+    def _check(self, response_status: int, body: str) -> str | None:
+        """Return an error message when the platform refused the send, else ``None``."""
+        return None if response_status < 400 else f"HTTP {response_status}: {body[:200]}"
+
+    # -- Messenger ----------------------------------------------------------
+
+    def resolve(self, name: str) -> str:
+        _, recipient_id = resolve_contact(self._config_for_resolve(), name)
+        return recipient_id
+
+    def _config_for_resolve(self) -> Config:  # pragma: no cover - replaced per driver
+        raise NotImplementedError
+
+    def send(self, recipient_id: str, text: str) -> SendOutcome:
+        body = self._payload(recipient_id, text)
+        headers = dict(self._headers())
+        encoded = self._encode(body)
+        if encoded is not None:
+            # The driver owns the exact bytes on the wire, so what is signed
+            # is what is sent — a receiver verifying the raw body agrees.
+            self._sign(encoded, headers)
+            request_kwargs: dict[str, Any] = {"data": encoded}
+        else:
+            self._sign(None, headers)
+            request_kwargs = {"json": body}
+        response = http_request(
+            "POST",
+            self._endpoint(recipient_id),
+            service=self.service,
+            headers=headers,
+            timeout=self.timeout,
+            **request_kwargs,
+        )
+        problem = self._check(response.status_code, response.text)
+        if problem:
+            # The platform answered and refused. Not retryable, and not
+            # something a caller may treat as success.
+            raise UpstreamError(
+                f"{self.service} refused the message: {problem}",
+                service=self.service,
+                status=response.status_code,
+                remedy="The message was NOT delivered. Check the recipient id and "
+                "the bot's ability to message them.",
+            )
+        return SendOutcome(sent=True, recipient=recipient_id)
+
+    def _encode(self, _body: dict[str, Any]) -> bytes | None:
+        """The exact wire bytes, when the driver must own them. ``None`` defers.
+
+        A driver returning ``None`` lets the HTTP layer serialise with
+        ``json=``, which is fine whenever nobody has to verify the body
+        afterwards. The webhook driver cannot afford that luxury: a signature
+        computed over one serialisation and sent over another verifies
+        nowhere.
+        """
+        return None
+
+    def _sign(self, _encoded: bytes | None, _headers: dict[str, str]) -> None:
+        """Hook for drivers that authenticate the request body."""
+
+    def health(self) -> None:
+        """Default: a get-me style probe supplied by the driver."""
+        raise ConfigError(f"The {self.service} driver has no health check.")
+
+
+class LineMessenger(_HttpMessenger):
+    """LINE Messaging API push."""
+
+    driver = "line"
+
+    def __init__(self, token: str, *, api_url: str, config: Config, timeout: float = 20.0) -> None:
+        super().__init__(token, api_root=api_url, service="line", timeout=timeout)
+        self._config = config
+
+    @classmethod
+    def from_config(cls, config: Config) -> LineMessenger:
+        return cls(
+            token=str(config.secret("chat.line.token_env")),
+            api_url=str(config.get("chat.line.api_url", "https://api.line.me/v2/bot/message/push")),
+            config=config,
+        )
+
+    def _config_for_resolve(self) -> Config:
+        return self._config
+
+    def _endpoint(self, _recipient_id: str) -> str:
+        return self.api_root
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+        }
+
+    def _payload(self, recipient_id: str, text: str) -> dict[str, Any]:
+        return {
+            "to": recipient_id,
+            "messages": [{"type": "text", "text": text}],
+        }
+
+
+class TelegramMessenger(_HttpMessenger):
+    """Telegram Bot API sendMessage."""
+
+    driver = "telegram"
+
+    def __init__(self, token: str, *, api_url: str, config: Config, timeout: float = 20.0) -> None:
+        super().__init__(token, api_root=api_url, service="telegram", timeout=timeout)
+        self._config = config
+
+    @classmethod
+    def from_config(cls, config: Config) -> TelegramMessenger:
+        return cls(
+            token=str(config.secret("chat.telegram.token_env")),
+            api_url=str(config.get("chat.telegram.api_url", "https://api.telegram.org")),
+            config=config,
+        )
+
+    def _config_for_resolve(self) -> Config:
+        return self._config
+
+    def _endpoint(self, recipient_id: str) -> str:
+        # The recipient travels in the path, so it must be quoted — a chat id
+        # is numeric today but nothing guarantees that tomorrow.
+        return f"{self.api_root}/bot{quote(self.token, safe='')}/sendMessage"
+
+    def _headers(self) -> dict[str, str]:
+        return {"Content-Type": "application/json"}
+
+    def _payload(self, recipient_id: str, text: str) -> dict[str, Any]:
+        return {"chat_id": recipient_id, "text": text}
+
+    def _check(self, response_status: int, body: str) -> str | None:
+        if response_status < 400:
+            return None
+        # Telegram reports "chat not found" as a 400 with a description; keep
+        # it, because it names the fix (the recipient must message the bot
+        # first before a bot can initiate).
+        return f"HTTP {response_status}: {body[:200]}"
+
+
+class WebhookMessenger(_HttpMessenger):
+    """POST to a URL of your choosing — for Slack, n8n, or anything else.
+
+    The recipient id is passed through in the payload, so the receiving end
+    decides what to do with it. An optional shared secret is signed rather
+    than sent, so the receiver can verify the call came from Baton.
+    """
+
+    driver = "webhook"
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        secret: str | None = None,
+        config: Config,
+        timeout: float = 20.0,
+    ) -> None:
+        super().__init__("", api_root=url, service="webhook", timeout=timeout)
+        self.secret = secret
+        self._config = config
+
+    @classmethod
+    def from_config(cls, config: Config) -> WebhookMessenger:
+        return cls(
+            url=str(config.secret("chat.webhook.url_env")),
+            secret=config.secret("chat.webhook.secret_env", required=False),
+            config=config,
+        )
+
+    def _config_for_resolve(self) -> Config:
+        return self._config
+
+    def _endpoint(self, recipient_id: str) -> str:
+        return self.api_root
+
+    def _headers(self) -> dict[str, str]:
+        return {"Content-Type": "application/json"}
+
+    def _payload(self, recipient_id: str, text: str) -> dict[str, Any]:
+        return {"recipient": recipient_id, "text": text}
+
+    def _encode(self, body: dict[str, Any]) -> bytes | None:
+        """Serialise once, only when there is a secret to sign those bytes."""
+        if not self.secret:
+            return None
+        return json.dumps(body, separators=(",", ":"), ensure_ascii=False).encode()
+
+    def _sign(self, encoded: bytes | None, headers: dict[str, str]) -> None:
+        """Sign the exact bytes that will be sent.
+
+        The receiver verifies HMAC-SHA256 over the raw request body, so the
+        signature is computed over the same ``bytes`` object handed to the
+        HTTP layer — never over a second serialisation of the same payload,
+        which is guaranteed to differ in separators or escaping and verify
+        nowhere.
+        """
+        if not self.secret or encoded is None:
+            return
+        headers["X-Baton-Signature"] = hmac.new(self.secret.encode(), encoded, "sha256").hexdigest()
+
+    def _check(self, response_status: int, body: str) -> str | None:
+        # A webhook receiver's contract is only "2xx means accepted".
+        return None if response_status < 400 else f"HTTP {response_status}: {body[:200]}"
+
+    def health(self) -> None:
+        """Webhooks have no introspection endpoint; connectivity is the check."""
+        response = http_request("GET", self.api_root, service="webhook", timeout=self.timeout)
+        if response.status_code >= 500:
+            raise UpstreamError(
+                f"The webhook endpoint returned {response.status_code}.",
+                service="webhook",
+                status=response.status_code,
+            )