minia_telegram 0.1.0__tar.gz

minia_telegram-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: minia_telegram
+Version: 0.1.0
+Summary: Telegram integration for the minia agent framework
+Requires-Python: <3.14,>=3.11
+Requires-Dist: httpx
+Requires-Dist: minia_contracts

minia_telegram-0.1.0/minia_telegram/__init__.py

@@ -0,0 +1,14 @@
+"""minia_telegram - Telegram integration for the minia agent framework.
+
+This package provides a Telegram-specific implementation of the interaction layer,
+allowing the agent to communicate with users via Telegram's Bot API.
+
+Exports:
+    - TelegramClient: Low-level client for the Telegram Bot API.
+    - TelegramBridge: High-level bridge that maps Telegram updates to internal messages.
+"""
+
+from minia_telegram.bridge import TelegramBridge
+from minia_telegram.client import TelegramClient
+
+__all__ = ["TelegramClient", "TelegramBridge"]

minia_telegram-0.1.0/minia_telegram/bridge.py

@@ -0,0 +1,229 @@
+"""Bridge between Telegram's raw data and the internal minia system.
+
+This gets incoming Telegram updates into the internal format (text for now)
+and provides a way for the agent to route responses back to the Telegram client.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import AsyncIterator
+
+import httpx
+
+from minia_contracts.config.settings import config
+from minia_contracts.protocol.ask_user import AskUserTracker
+from minia_contracts.protocol.commands import CommandSender
+from minia_contracts.protocol.dispatch import as_event_consumer
+from minia_contracts.protocol.events import run_event_socket_client
+from minia_contracts.reports import ReportEvent, ReportEventPayload, cmd_answer, cmd_input
+from minia_telegram.client import TelegramClient
+
+log = logging.getLogger(__name__)
+
+
+class TelegramBridge:
+    """Handles translation between Telegram and internal message formats.
+
+    Connects to the agent's event socket as a client (not a server), consuming
+    report events and forwarding them back through Telegram. Incoming user
+    messages from Telegram are sent to the agent via the command socket.
+    """
+
+    def __init__(self, client: TelegramClient) -> None:
+        self.client = client
+        # Ensure chat_id is always a string (TOML may parse it as an integer).
+        telegram_cfg = getattr(config, "telegram", None)
+        raw_chat_id = telegram_cfg.chat_id if telegram_cfg else ""
+        self.chat_id = str(raw_chat_id) if raw_chat_id else ""
+        log.info("[Telegram] Bridge initialized with chat_id=%s", self.chat_id)
+        self._sender: CommandSender | None = None
+        self._ask_users = AskUserTracker()
+
+    # ------------------------------------------------------------------
+    # Incoming: Telegram → agent
+    # ------------------------------------------------------------------
+
+    async def send_response(self, chat_id: str, text: str) -> None:
+        """Send a response back through the Telegram client, truncating if needed."""
+        if not chat_id:
+            log.error("[Telegram] Cannot send: chat_id is empty")
+            return
+
+        # Telegram's limit is 4096 characters per message
+        MAX_LENGTH = 4090
+        if len(text) > MAX_LENGTH:
+            original_len = len(text)
+            text = text[:MAX_LENGTH]
+            log.warning(
+                "[Telegram] Truncated response from %d to %d chars", original_len, MAX_LENGTH
+            )
+
+        try:
+            await self.client.send_message(chat_id, text)
+            log.info("[Telegram] Sent message to chat %s (%d chars)", chat_id, len(text))
+        except Exception as exc:
+            log.error("[Telegram] Failed to send message to chat %s: %s", exc)
+
+    async def get_updates(self) -> AsyncIterator[str]:
+        """Bridge method to fetch and map Telegram updates to internal Messages."""
+        async for update in self.client.poll_updates(self.chat_id):
+            yield update["message"]["text"]
+
+    def _update_ask_user(self, event: ReportEvent, payload: ReportEventPayload) -> None:
+        """Update the shared ask_user tracker from a report event.
+
+        Marks the agent when an ``ask_user`` tool call is observed; clears it
+        on the matching tool result, a final response, or an error.
+        """
+        tool = payload.get("tool", "")
+        agent = payload.get("agent") or "main"
+        if event == ReportEvent.TOOL_CALL and tool == "ask_user":
+            self._ask_users.mark(agent)
+        elif (event == ReportEvent.TOOL_RESULT and tool == "ask_user") or event in (
+            ReportEvent.FINAL_RESPONSE,
+            ReportEvent.ERROR,
+        ):
+            self._ask_users.clear(agent)
+
+    async def send_to_agent(self, text: str) -> None:
+        """Send a message to the agent via the command socket."""
+        if self._sender is None:
+            self._sender = CommandSender(
+                config.default.cmd_socket_path,
+                logger=log,
+            )
+        if self._ask_users.any_pending():
+            await self._sender.send(cmd_answer(text))
+            self._ask_users.clear_most_recent()
+        else:
+            await self._sender.send(cmd_input(text))
+
+    def _sanitize_for_telegram(self, text: str) -> str:
+        """Remove things that Telegram's Markdown parser can't handle."""
+        return text
+
+    # ------------------------------------------------------------------
+    # Outgoing: agent → Telegram (event socket client)
+    # ------------------------------------------------------------------
+
+    def handle(self, event: ReportEvent, payload: ReportEventPayload) -> None:
+        """Handle report events from the agent and forward to Telegram.
+
+        Implements :class:`minia_contracts.protocol.interfaces.EventConsumer`.
+        Only ``FINAL_RESPONSE`` events are forwarded as visible messages.
+        """
+        log.debug("[Telegram] handle() called with event=%s", event.value)
+        content = payload.get("content", "")
+
+        self._update_ask_user(event, payload)
+
+        match event:
+            case ReportEvent.FINAL_RESPONSE:
+                if content:
+                    if payload.get("agent") == "main":
+                        clean_content = self._sanitize_for_telegram(content)
+                        log.info("[Telegram] Forwarding final response: '%s'", clean_content[:200])
+                        asyncio.create_task(self.send_response(self.chat_id, clean_content))
+                else:
+                    log.warning("[Telegram] FINAL_RESPONSE with empty content")
+            case ReportEvent.REASONING_CONTENT:
+                log.debug("[Telegram] Agent thinking: '%s'", content[:200])
+            case ReportEvent.ERROR:
+                log.warning("[Telegram] Agent error: %s", content[:200])
+            case ReportEvent.TOOL_CALL:
+                tool = payload.get("tool", "")
+                if tool == "ask_user":
+                    question = payload.get("args", {}).get("question", "")
+                    if question:
+                        clean_question = self._sanitize_for_telegram(question)
+                        log.info("[Telegram] ask_user question: '%s'", clean_question[:200])
+                        asyncio.create_task(
+                            self.send_response(self.chat_id, f"💬 {clean_question}")
+                        )
+                else:
+                    log.debug("[Telegram] Tool call: %s", content[:200])
+            case ReportEvent.TOOL_RESULT:
+                tool = payload.get("tool", "")
+                if tool == "ask_user":
+                    log.info("[Telegram] ask_user answered: '%s'", content[:200])
+                else:
+                    log.debug("[Telegram] Tool result: %s", content[:200])
+            case ReportEvent.USER_INPUT:
+                log.debug("[Telegram] USER_INPUT: '%s'", payload.get("content", "")[:200])
+            case (
+                ReportEvent.ITERATION_START
+                | ReportEvent.ITERATION_END
+                | ReportEvent.REFUSAL
+                | ReportEvent.LIVE_TOKEN
+                | ReportEvent.STATS
+                | ReportEvent.TOKEN_WARNING
+                | ReportEvent.RETRY
+                | ReportEvent.WARNING
+                | ReportEvent.COMMAND_RECEIVED
+                | ReportEvent.TTS_START
+                | ReportEvent.TTS_END
+                | ReportEvent.TTS_STOP
+                | ReportEvent.RUN_START
+                | ReportEvent.RUN_END
+                | ReportEvent.RUN_STOPPED
+                | ReportEvent.RUN_HEARTBEAT
+                | ReportEvent.BACKGROUND_DONE
+                | ReportEvent.DELEGATE_RELAY_DONE
+                | ReportEvent.PROGRESS_UPDATE
+            ):
+                log.debug("[Telegram] Event %s: '%s'", event.value, content[:100])
+
+    async def connect_to_event_socket(self) -> None:
+        """Connect to the agent's event socket and start consuming events."""
+        log.info("[Telegram] Connecting to event socket: %s", config.default.event_socket_path)
+        try:
+            await run_event_socket_client(
+                config.default.event_socket_path,
+                as_event_consumer(self),
+                auto_reconnect=True,
+                client_type="telegram",
+            )
+            log.info("[Telegram] Event socket connection established")
+        except Exception as exc:
+            log.error("[Telegram] Failed to connect to event socket: %s", exc)
+            raise
+
+    async def run(self) -> None:
+        """Run the bidirectional bridge.
+
+        Runs both directions concurrently:
+        - Incoming: polls Telegram for user messages, sends them to agent
+        - Outgoing: connects to event socket, forwards agent responses to Telegram
+        """
+        log.info("[Telegram] Starting bidirectional bridge")
+
+        # Start event socket consumer in background
+        event_task = asyncio.create_task(self.connect_to_event_socket())
+        event_task.add_done_callback(
+            lambda t: (
+                log.info("[Telegram] Event socket task completed successfully")
+                if not t.cancelled() and not t.exception()
+                else log.error("[Telegram] Event socket task failed: %s", t.exception())
+            )
+        )
+
+        try:
+            # Poll for incoming messages from Telegram and forward to agent
+            async for message in self.get_updates():
+                if message.strip():
+                    log.info("[Telegram] Received user message: '%s'", message[:200])
+                    await self.send_to_agent(message)
+        except (ConnectionError, httpx.ConnectTimeout, httpx.ConnectError) as exc:
+            log.error("[Telegram] Network error during polling: %s", exc)
+            # Don't crash - just log and let the event socket reconnect
+        except asyncio.CancelledError:
+            log.info("[Telegram] Bridge cancelled")
+            event_task.cancel()
+            raise
+        finally:
+            event_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await event_task

minia_telegram-0.1.0/minia_telegram/client.py

@@ -0,0 +1,83 @@
+"""Telegram client for the minia agent framework.
+
+This module provides a Telegram-specific implementation of the interaction layer,
+allowing the agent to communicate with users via Telegram's Bot API."""
+
+import asyncio
+import logging
+import re
+from collections.abc import AsyncIterator
+
+import httpx
+
+log = logging.getLogger(__name__)
+
+
+class TelegramClient:
+    """A client to interact with the Telegram Bot API."""
+
+    _TOKEN_PATTERN = re.compile(r"^\d{8,}:[A-Za-z0-9_-]{9,}$")
+
+    def __init__(self, bot_token: str) -> None:
+        """Initialize the Telegram client with a valid bot token.
+
+        Args:
+            bot_token: The Telegram Bot API token (format: '1234567890:ABCdef...').
+
+        Raises:
+            ValueError: If the token is invalid or doesn't match expected format.
+        """
+        if not bot_token or not self._TOKEN_PATTERN.match(bot_token):
+            raise ValueError(
+                f"Invalid Telegram bot token: {bot_token!r}. "
+                "Expected format '1234567890:ABCdefGhIjKlMnOpQrStUvWxYz'."
+            )
+        self.bot_token = bot_token
+        self.api_base = f"https://api.telegram.org/bot{self.bot_token}"
+
+    async def send_message(self, chat_id: str, text: str) -> None:
+        """Send a message to a specific Telegram chat."""
+        url = f"{self.api_base}/sendMessage"
+        payload = {"chat_id": chat_id, "text": text, "parse_mode": "markdown"}
+        async with httpx.AsyncClient() as client:
+            response = await client.post(url, json=payload)
+            if response.status_code == 200:
+                log.debug("Successfully sent message to Telegram chat %s", chat_id)
+            else:
+                log.error("Failed to send message to Telegram: %s", response.text)
+
+    async def poll_updates(self, chat_id: str | None = None) -> AsyncIterator[dict]:
+        """Continuously poll for new updates from the Telegram API.
+
+        Includes a 25-second sleep between iterations as requested.
+        """
+        offset = 0
+        while True:
+            url = f"{self.api_base}/getUpdates"
+            params = {"offset": offset}
+
+            async with httpx.AsyncClient() as client:
+                response = await client.get(url, params=params)
+
+                if response.status_code == 200:
+                    updates = response.json().get("result", [])
+
+                    for update in updates:
+                        offset = update["update_id"] + 1
+
+                        # Ensure we only process messages for the configured chat.
+                        # Convert chat_id to str to handle TOML config where
+                        # chat_id may be an integer (e.g. 1071941511) — always
+                        # compare strings so the check works regardless of config type.
+                        if chat_id and "message" in update:
+                            msg_chat = str(update["message"]["chat"]["id"])
+                            if msg_chat != str(chat_id):
+                                continue
+
+                        yield update
+
+                    # The 25-second pause between polls
+                    await asyncio.sleep(25)
+                else:
+                    log.error("Failed to poll updates from Telegram: %s", response.text)
+                    await asyncio.sleep(25)

minia_telegram-0.1.0/minia_telegram/main.py

@@ -0,0 +1,74 @@
+"""minia_telegram - Telegram client for minia.
+
+Polls incoming messages from Telegram and sends them to the minia agent input socket.
+
+Usage:
+    minia-telegram
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from minia_contracts.config.settings import config
+from minia_contracts.utils.cli import apply_config_flag, run_cli
+from minia_contracts.utils.logging import get_logger, resolve_log_level
+from minia_telegram.bridge import TelegramBridge
+from minia_telegram.client import TelegramClient
+
+logger = get_logger(__name__)
+
+
+class TelegramListener:
+    """Poll Telegram -> bridge to internal Message format -> send to agent."""
+
+    def __init__(self) -> None:
+        # Ensure chat_id is always a string (TOML may parse it as an integer).
+        raw_chat_id = getattr(config.telegram, "chat_id", "") or ""
+        self.chat_id = str(raw_chat_id) if raw_chat_id else ""
+
+    async def start(self) -> None:
+        """Initialize the Telegram client and bridge."""
+        logger.info("[Telegram] Initializing...")
+
+        bot_token = getattr(config.telegram, "bot_token", "")
+        if not bot_token:
+            raise RuntimeError(
+                "[Telegram] Missing bot_token in config. Set it under [telegram] section."
+            )
+
+        self.client = TelegramClient(bot_token)
+        self.bridge = TelegramBridge(self.client)
+
+        logger.info("[Telegram] Ready")
+
+    async def run(self) -> None:
+        """Main entry point. Runs the bidirectional bridge."""
+        assert self.bridge is not None, "start() must be called before run()"
+        logger.info("[Telegram] Starting bidirectional bridge")
+
+        try:
+            await self.bridge.run()
+        except asyncio.CancelledError:
+            logger.info("[Telegram] Bridge cancelled")
+            raise
+        except Exception:
+            logger.exception("[Telegram] Error in bridge")
+            raise
+
+
+async def _main() -> None:
+    listener = TelegramListener()
+    await listener.start()
+    await listener.run()
+
+
+def main() -> None:
+    """Entry point for minia-telegram."""
+    apply_config_flag()
+    log_level = resolve_log_level(config, "telegram")
+    run_cli(log_level, _main, add_console=True)
+
+
+if __name__ == "__main__":
+    main()

minia_telegram-0.1.0/minia_telegram.egg-info/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: minia_telegram
+Version: 0.1.0
+Summary: Telegram integration for the minia agent framework
+Requires-Python: <3.14,>=3.11
+Requires-Dist: httpx
+Requires-Dist: minia_contracts

minia_telegram-0.1.0/minia_telegram.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+pyproject.toml
+minia_telegram/__init__.py
+minia_telegram/bridge.py
+minia_telegram/client.py
+minia_telegram/main.py
+minia_telegram.egg-info/PKG-INFO
+minia_telegram.egg-info/SOURCES.txt
+minia_telegram.egg-info/dependency_links.txt
+minia_telegram.egg-info/entry_points.txt
+minia_telegram.egg-info/requires.txt
+minia_telegram.egg-info/top_level.txt

minia_telegram-0.1.0/minia_telegram.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

minia_telegram-0.1.0/minia_telegram.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+minia-telegram = minia_telegram.main:main

minia_telegram-0.1.0/minia_telegram.egg-info/requires.txt

@@ -0,0 +1,2 @@
+httpx
+minia_contracts

minia_telegram-0.1.0/minia_telegram.egg-info/top_level.txt

@@ -0,0 +1 @@
+minia_telegram

minia_telegram-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "minia_telegram"
+version = "0.1.0"
+description = "Telegram integration for the minia agent framework"
+requires-python = ">=3.11,<3.14"
+dependencies = [
+    "httpx",
+    "minia_contracts",
+]
+
+[project.scripts]
+minia-telegram = "minia_telegram.main:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["minia_telegram", "minia_telegram.*"]
+
+[tool.uv.sources]
+minia_contracts = { workspace = true }

minia_telegram-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+