Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

19.8 KB
Raw Blame
"""Channel manager for coordinating chat channels."""

from __future__ import annotations

import asyncio
from contextlib import suppress
import hashlib
from typing import Any

from deeptutor.partners.bus.events import OutboundMessage
from deeptutor.partners.bus.queue import MessageBus
from deeptutor.partners.channels.base import BaseChannel, constructing_for, deliver_outbound
from deeptutor.partners.config.schema import ChannelsConfig


def _logger():
    from loguru import logger as _log

    return _log


# Retry delays for message sending (exponential backoff: 1s, 2s, 4s)
_SEND_RETRY_DELAYS = (1, 2, 4)
# Recent outbound replies remembered to drop a channel's duplicate sends.
_REPLY_FINGERPRINT_LIMIT = 2048

_BOOL_CAMEL_ALIASES: dict[str, str] = {
    "send_progress": "sendProgress",
    "send_tool_hints": "sendToolHints",
}


def _drain_outbound(bus: Any) -> OutboundMessage | None:
    """Pop one queued outbound message without waiting, or ``None`` when empty.

    Tolerates buses that only expose the blocking ``consume_outbound`` (tests
    and embedders): those simply never coalesce.
    """
    try_consume = getattr(bus, "try_consume_outbound", None)
    if callable(try_consume):
        return try_consume()
    try:
        return bus.outbound.get_nowait()
    except (asyncio.QueueEmpty, AttributeError, NotImplementedError):
        return None


def coalesce_stream_deltas(
    bus: Any, first_msg: OutboundMessage
) -> tuple[OutboundMessage, list[OutboundMessage]]:
    """Merge consecutive ``_stream_delta`` messages for the same stream segment.

    Shared by the channel dispatcher and the partner outbound router so both
    keep the same delivery contract: an LLM that generates faster than the
    channel can post must not turn every token into its own API call.

    Returns:
        tuple of (merged_message, list_of_non_matching_messages)
    """
    target_key = (first_msg.channel, first_msg.chat_id)
    target_stream = (first_msg.metadata or {}).get("_stream_id")
    combined_content = first_msg.content
    final_metadata = dict(first_msg.metadata or {})
    non_matching: list[OutboundMessage] = []

    # Only merge consecutive deltas of the same stream segment. As soon
    # as we hit any other message, stop and hand that boundary back to
    # the dispatcher via `pending`.
    while True:
        next_msg = _drain_outbound(bus)
        if next_msg is None:
            break

        next_meta = next_msg.metadata or {}
        same_target = (next_msg.channel, next_msg.chat_id) == target_key
        same_stream = next_meta.get("_stream_id") == target_stream
        is_delta = bool(next_meta.get("_stream_delta"))
        is_end = bool(next_meta.get("_stream_end"))

        if same_target and same_stream and is_delta:
            combined_content += next_msg.content
            if is_end:
                final_metadata["_stream_end"] = True
                if next_meta.get("_stream_final"):
                    final_metadata["_stream_final"] = True
                break
        else:
            # First non-matching message defines the coalescing boundary.
            non_matching.append(next_msg)
            break

    merged = OutboundMessage(
        channel=first_msg.channel,
        chat_id=first_msg.chat_id,
        content=combined_content,
        # Routing hints belong to the segment, not to one delta: keep the first
        # message's so a merged frame still replies/threads where it started.
        reply_to=first_msg.reply_to,
        media=list(first_msg.media),
        metadata=final_metadata,
    )
    return merged, non_matching


def coalesce_progress_messages(
    bus: Any, first_msg: OutboundMessage
) -> tuple[OutboundMessage, list[OutboundMessage]]:
    """Merge consecutive progress messages that are already queued together.

    Narration rounds and tool hints become separate messages, which is what a
    reader wants while the channel keeps up. When the model outruns the channel
    they instead pile up in the queue, and every one of them costs a blocking
    API round trip — post the backlog as one message rather than dribbling it
    out after the turn has already finished. Nothing waits for a merge: only
    messages already waiting in the queue are combined.
    """
    target_key = (first_msg.channel, first_msg.chat_id)
    is_tool_hint = bool((first_msg.metadata or {}).get("_tool_hint"))
    joiner = "\n" if is_tool_hint else "\n\n"
    combined_content = first_msg.content
    final_metadata = dict(first_msg.metadata or {})
    non_matching: list[OutboundMessage] = []

    while True:
        next_msg = _drain_outbound(bus)
        if next_msg is None:
            break

        next_meta = next_msg.metadata or {}
        mergeable = (
            (next_msg.channel, next_msg.chat_id) == target_key
            and bool(next_meta.get("_progress"))
            and not next_meta.get("_stream_delta")
            and not next_meta.get("_stream_end")
            # The "thinking…" notice carries its own lifecycle (it is retracted
            # once output starts), so it must stay a message of its own.
            and not next_meta.get("_thinking_notice")
            and not (first_msg.metadata or {}).get("_thinking_notice")
            and bool(next_meta.get("_tool_hint")) == is_tool_hint
        )
        if not mergeable:
            non_matching.append(next_msg)
            break
        combined_content = f"{combined_content}{joiner}{next_msg.content}"

    merged = OutboundMessage(
        channel=first_msg.channel,
        chat_id=first_msg.chat_id,
        content=combined_content,
        reply_to=first_msg.reply_to,
        media=list(first_msg.media),
        metadata=final_metadata,
    )
    return merged, non_matching


async def send_with_retry(
    channel: BaseChannel,
    msg: OutboundMessage,
    *,
    max_attempts: int = 3,
    retry_delays: tuple[float, ...] = _SEND_RETRY_DELAYS,
) -> None:
    """Send a message with retry on failure using exponential backoff.

    Note: CancelledError is re-raised to allow graceful shutdown.
    """
    attempts = max(max_attempts, 1)

    for attempt in range(attempts):
        try:
            await deliver_outbound(channel, msg)
            return
        except asyncio.CancelledError:
            raise
        except Exception as e:
            if attempt == attempts - 1:
                _logger().exception("Failed to send to {} after {} attempts", msg.channel, attempts)
                return
            delay = retry_delays[min(attempt, len(retry_delays) - 1)]
            _logger().warning(
                "Send to {} failed (attempt {}/{}): {}, retrying in {}s",
                msg.channel,
                attempt + 1,
                attempts,
                type(e).__name__,
                delay,
            )
            try:
                await asyncio.sleep(delay)
            except asyncio.CancelledError:
                raise


class ChannelManager:
    """
    Manages chat channels and coordinates message routing.

    Responsibilities:
    - Initialize enabled channels (Telegram, WhatsApp, etc.)
    - Start/stop channels
    - Route outbound messages with retry, duplicate suppression and
      stream-delta coalescing
    """

    def __init__(
        self,
        channels_config: ChannelsConfig,
        bus: MessageBus,
        groq_api_key: str = "",
        partner_id: str = "",
    ):
        self.channels_config = channels_config
        self.bus = bus
        self._groq_api_key = groq_api_key
        self._partner_id = str(partner_id or "")
        self.channels: dict[str, BaseChannel] = {}
        self._configured_status: dict[str, dict[str, Any]] = {}
        self._dispatch_task: asyncio.Task | None = None
        self._origin_reply_fingerprints: dict[tuple[str, str, str], str] = {}

        self._init_channels()

    def _init_channels(self) -> None:
        """Initialize channels discovered via pkgutil scan + entry_points plugins."""
        from deeptutor.partners.channels.registry import discover_all_with_errors

        discovered, import_errors = discover_all_with_errors()
        configured = dict(self.channels_config.model_extra or {})

        for name, section in configured.items():
            enabled = (
                section.get("enabled", False)
                if isinstance(section, dict)
                else getattr(section, "enabled", False)
            )
            if not enabled:
                continue
            self._configured_status[name] = {
                "enabled": True,
                "running": False,
                "setup": {},
            }

            cls = discovered.get(name)
            if cls is None:
                reason = import_errors.get(name)
                self._configured_status[name]["setup"] = {
                    "status": "unavailable",
                    "message": reason or "Channel implementation is not installed.",
                }
                continue
            try:
                with constructing_for(self._partner_id):
                    channel = cls(section, self.bus)
                channel.partner_id = self._partner_id
                channel.transcription_api_key = self._groq_api_key
                # Effective delivery flags are per-channel only. Historical
                # top-level channel config keys are ignored at runtime.
                channel.send_progress = self._resolve_bool_override(
                    section, "send_progress", default=True
                )
                channel.send_tool_hints = self._resolve_bool_override(
                    section, "send_tool_hints", default=True
                )
                if getattr(channel.config, "allow_from", None) == []:
                    _logger().warning(
                        'Skipping channel "{}": allowFrom is empty (denies all)',
                        name,
                    )
                    self._configured_status[name]["setup"] = {
                        "status": "action_required",
                        "message": "Add at least one allowed sender before starting this channel.",
                    }
                    continue
                self.channels[name] = channel
                _logger().info("{} channel enabled", cls.display_name)
            except Exception as e:
                _logger().warning("{} channel not available: {}", name, e)
                self._configured_status[name]["setup"] = {
                    "status": "error",
                    "message": f"Channel initialization failed ({type(e).__name__}).",
                }

    @staticmethod
    def _resolve_bool_override(section: Any, key: str, *, default: bool) -> bool:
        """Return *key* from *section* if it is a bool, otherwise *default*.

        For dict configs also checks the camelCase alias (e.g. ``sendProgress``
        for ``send_progress``) so raw JSON configs work alongside Pydantic
        models.
        """
        if isinstance(section, dict):
            value = section.get(key)
            if value is None:
                camel = _BOOL_CAMEL_ALIASES.get(key)
                if camel:
                    value = section.get(camel)
            return value if isinstance(value, bool) else default
        value = getattr(section, key, None)
        return value if isinstance(value, bool) else default

    async def _start_channel(self, name: str, channel: BaseChannel) -> None:
        channel.set_setup_state("connecting")
        manager_revision = channel.setup_revision
        start_task = asyncio.create_task(channel.start())
        try:
            # Most implementations set `_running` synchronously before their
            # first network await. If the channel did not publish a more
            # precise state of its own, report that its listener is alive —
            # not that external authentication has necessarily succeeded.
            await asyncio.sleep(0)
            if (
                channel.is_running
                and channel.setup_revision == manager_revision
                and not start_task.done()
            ):
                channel.set_setup_state("running")
                manager_revision = channel.setup_revision
            await start_task
            if channel.setup_revision == manager_revision:
                if channel.is_running:
                    channel.set_setup_state("running")
                else:
                    channel.set_setup_state(
                        "action_required",
                        message=(
                            "The channel did not start. Check its required fields "
                            "and optional dependencies."
                        ),
                    )
        except asyncio.CancelledError:
            start_task.cancel()
            with suppress(asyncio.CancelledError):
                await start_task
            raise
        except Exception as e:
            _logger().error("Failed to start channel {}: {}", name, e)
            channel._running = False
            channel.set_setup_state(
                "error",
                message=f"Channel startup failed ({type(e).__name__}).",
            )

    async def start_all(self) -> None:
        """Start all channels and the outbound dispatcher."""
        if not self.channels:
            _logger().warning("No channels enabled")
            return

        self._dispatch_task = asyncio.create_task(self._dispatch_outbound())

        tasks = []
        for name, channel in self.channels.items():
            _logger().info("Starting {} channel...", name)
            tasks.append(asyncio.create_task(self._start_channel(name, channel)))

        await asyncio.gather(*tasks, return_exceptions=True)

    async def stop_all(self) -> None:
        """Stop all channels and the dispatcher."""
        _logger().info("Stopping all channels...")

        if self._dispatch_task:
            self._dispatch_task.cancel()
            with suppress(asyncio.CancelledError):
                await self._dispatch_task

        for name, channel in self.channels.items():
            try:
                await channel.stop()
                channel.set_setup_state("disconnected")
                _logger().info("Stopped {} channel", name)
            except Exception as e:
                _logger().error("Error stopping {}: {}", name, e)

    @staticmethod
    def _fingerprint_content(content: str) -> str:
        normalized = " ".join(content.split())
        if not normalized:
            return ""
        return hashlib.sha1(normalized.encode("utf-8"), usedforsecurity=False).hexdigest()

    def _should_suppress_outbound(self, msg: OutboundMessage) -> bool:
        """Suppress an exact-duplicate reply to the same source message.

        Duplicate suppression is scoped to a known origin message id so
        repeated content from separate turns is still delivered.
        """
        metadata = msg.metadata or {}
        if metadata.get("_progress"):
            return False
        fingerprint = self._fingerprint_content(msg.content)
        if not fingerprint:
            return False

        origin_message_id = metadata.get("origin_message_id")
        if isinstance(origin_message_id, str) and origin_message_id:
            key = (msg.channel, msg.chat_id, origin_message_id)
            if self._origin_reply_fingerprints.get(key) == fingerprint:
                return True
            self._origin_reply_fingerprints[key] = fingerprint

        message_id = metadata.get("message_id")
        if isinstance(message_id, str) and message_id:
            key = (msg.channel, msg.chat_id, message_id)
            self._origin_reply_fingerprints[key] = fingerprint

        # Duplicates arrive within moments of the original; without a bound
        # the map kept one entry per reply for the partner's whole life.
        while len(self._origin_reply_fingerprints) > _REPLY_FINGERPRINT_LIMIT:
            self._origin_reply_fingerprints.pop(next(iter(self._origin_reply_fingerprints)))
        return False

    async def _dispatch_outbound(self) -> None:
        """Dispatch outbound messages to the appropriate channel."""
        _logger().info("Outbound dispatcher started")

        # Buffer for messages that couldn't be processed during delta
        # coalescing (asyncio.Queue doesn't support push_front).
        pending: list[OutboundMessage] = []

        while True:
            try:
                if pending:
                    msg = pending.pop(0)
                else:
                    msg = await asyncio.wait_for(self.bus.consume_outbound(), timeout=1.0)

                channel = self.channels.get(msg.channel)
                if not channel:
                    _logger().warning("Unknown channel: {}", msg.channel)
                    continue

                if msg.metadata.get("_progress"):
                    if msg.metadata.get("_tool_hint") and not channel.send_tool_hints:
                        continue
                    if not msg.metadata.get("_tool_hint") and not channel.send_progress:
                        continue

                # Coalesce consecutive _stream_delta messages for the same
                # (channel, chat_id) to reduce edit-API calls when the LLM
                # generates faster than the channel can process.
                if msg.metadata.get("_stream_delta") and not msg.metadata.get("_stream_end"):
                    msg, extra_pending = self._coalesce_stream_deltas(msg)
                    pending.extend(extra_pending)

                if (
                    not msg.metadata.get("_stream_delta")
                    and not msg.metadata.get("_stream_end")
                    and not msg.metadata.get("_streamed")
                ):
                    if self._should_suppress_outbound(msg):
                        _logger().info(
                            "Suppressing duplicate outbound message to {}:{}",
                            msg.channel,
                            msg.chat_id,
                        )
                        continue
                await self._send_with_retry(channel, msg)

            except asyncio.TimeoutError:
                # Idle-poll timeout on an empty queue: the cancelled consume
                # popped no message (a consume finishing despite the timeout
                # is returned by wait_for), so nothing is skipped. Channel
                # send timeouts are retried and logged in _send_with_retry.
                continue
            except asyncio.CancelledError:
                break

    def _coalesce_stream_deltas(
        self, first_msg: OutboundMessage
    ) -> tuple[OutboundMessage, list[OutboundMessage]]:
        """Merge consecutive _stream_delta messages for the same (channel, chat_id).

        Returns:
            tuple of (merged_message, list_of_non_matching_messages)
        """
        return coalesce_stream_deltas(self.bus, first_msg)

    async def _send_with_retry(self, channel: BaseChannel, msg: OutboundMessage) -> None:
        """Send a message with retry on failure using exponential backoff.

        Note: CancelledError is re-raised to allow graceful shutdown.
        """
        await send_with_retry(
            channel,
            msg,
            max_attempts=max(getattr(self.channels_config, "send_max_retries", 3), 1),
        )

    def get_channel(self, name: str) -> BaseChannel | None:
        return self.channels.get(name)

    def get_status(self) -> dict[str, Any]:
        status = {
            name: {
                "enabled": bool(state.get("enabled")),
                "running": bool(state.get("running")),
                "setup": dict(state.get("setup") or {}),
            }
            for name, state in self._configured_status.items()
        }
        status.update(
            {
                name: {
                    "enabled": True,
                    "running": channel.is_running,
                    "setup": channel.setup_state,
                }
                for name, channel in self.channels.items()
            }
        )
        return status

    @property
    def enabled_channels(self) -> list[str]:
        return list(self.channels.keys())