DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
"""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())