docs(spec): add Telegram adapter notes

Signed-off-by: theonlychant <sacehenry@gmail.com>

Author: theonlychant

docs/guides/telegram.mdx

@@ -0,0 +1,19 @@
+---
+title: Telegram Messaging Adapter
+---
+
+This page documents the v0.18.2 Telegram messaging adapter scaffold.
+
+Status: scaffolded — implementation work in progress.
+
+Acceptance criteria (v0.18.2):
+
+- `gaia telegram --token <TOKEN>` starts the adapter (scaffold currently logs and exits).
+- `/start` command replies within 5 seconds.
+- Streaming responses use message edits via `send_stream` from `AgentSDK`.
+
+Next steps:
+
+- Implement runtime using `python-telegram-bot` Application and handlers.
+- Wire uploads to VLM/RAG ingestion.
+- Add tests for allowed-users gate and restricted tools enforcement.

setup.py

@@ -160,6 +160,9 @@
             "starlette",
             "uvicorn",
         ],
+        "telegram": [
+            "python-telegram-bot>=20.3",
+        ],
         "dev": [
             "pytest",
             "pytest-benchmark",

src/gaia/cli.py

@@ -1408,6 +1408,50 @@ def main():
     )
     api_parser.set_defaults(action="api")
 
+    # Telegram adapter command (v0.18.2) - supports start|stop|status
+    telegram_parser = subparsers.add_parser(
+        "telegram",
+        help="Manage Telegram messaging adapter (start|stop|status)",
+        parents=[parent_parser],
+    )
+    telegram_subparsers = telegram_parser.add_subparsers(
+        dest="telegram_action", help="telegram action to perform"
+    )
+
+    # Start subcommand
+    t_start = telegram_subparsers.add_parser(
+        "start", help="Start the Telegram adapter (polling)"
+    )
+    t_start.add_argument("--token", required=True, help="Telegram bot token")
+    t_start.add_argument(
+        "--allowed-users",
+        help="Comma-separated Telegram user IDs allowed to interact (default: allow all)",
+    )
+    t_start.add_argument(
+        "--background",
+        action="store_true",
+        help="Run adapter in background/daemon mode (writes PID and health endpoint)",
+    )
+
+    # Stop subcommand
+    t_stop = telegram_subparsers.add_parser("stop", help="Stop background Telegram adapter")
+    t_stop.add_argument(
+        "--force",
+        action="store_true",
+        help="Force stop even if graceful shutdown fails",
+    )
+
+    # Status subcommand
+    t_status = telegram_subparsers.add_parser("status", help="Show status of Telegram adapter")
+    t_status.add_argument(
+        "--health-host", default="127.0.0.1", help="Health server host (default: 127.0.0.1)"
+    )
+    t_status.add_argument(
+        "--health-port", type=int, default=8765, help="Health server port (default: 8765)"
+    )
+
+    telegram_parser.set_defaults(action="telegram")
+
     # Add model download command
     download_parser = subparsers.add_parser(
         "download",
@@ -2156,6 +2200,85 @@ def main():
         )
         return
 
+    # Handle telegram scaffold command
+    if args.action == "telegram":
+        # Telegram management: start | stop | status
+        action = getattr(args, "telegram_action", None)
+        if action == "start":
+            try:
+                from gaia.messaging.telegram import run_telegram
+            except Exception as e:  # pragma: no cover - runtime import error
+                print(f"❌ Telegram support is not available: {e}", file=sys.stderr)
+                sys.exit(1)
+
+            allowed = None
+            if getattr(args, "allowed_users", None):
+                try:
+                    allowed = set(int(x.strip()) for x in args.allowed_users.split(",") if x.strip())
+                except Exception:
+                    print("Invalid --allowed-users format; expected comma-separated integers", file=sys.stderr)
+                    sys.exit(2)
+
+            run_telegram(token=args.token, allowed_users=allowed, background=getattr(args, "background", False))
+            return
+
+        if action == "stop":
+            import signal
+
+            pid_path = os.path.expanduser("~/.gaia/telegram.pid")
+            if not os.path.exists(pid_path):
+                print("Telegram adapter is not running (no PID file).")
+                return
+            try:
+                with open(pid_path, "r", encoding="utf-8") as f:
+                    pid = int(f.read().strip())
+                os.kill(pid, signal.SIGTERM)
+                print(f"Sent SIGTERM to Telegram adapter (pid {pid}).")
+                try:
+                    os.remove(pid_path)
+                except OSError:
+                    pass
+            except ProcessLookupError:
+                print("Process not found; removing stale PID file.")
+                try:
+                    os.remove(pid_path)
+                except OSError:
+                    pass
+            except PermissionError:
+                print("Permission denied when attempting to stop process. Try sudo.")
+                sys.exit(1)
+            except Exception as e:
+                print(f"Failed to stop Telegram adapter: {e}")
+                sys.exit(1)
+            return
+
+        if action == "status":
+            # Prefer health endpoint; fallback to pid file existence
+            import urllib.request
+            import urllib.error
+
+            host = getattr(args, "health_host", "127.0.0.1")
+            port = getattr(args, "health_port", 8765)
+            url = f"http://{host}:{port}/healthz"
+            try:
+                with urllib.request.urlopen(url, timeout=1) as resp:
+                    body = resp.read().decode("utf-8").strip()
+                    if resp.status == 200 and body == "ok":
+                        print(f"Telegram adapter: healthy ({url})")
+                        return
+            except urllib.error.URLError:
+                pass
+
+            pid_path = os.path.expanduser("~/.gaia/telegram.pid")
+            if os.path.exists(pid_path):
+                print("Telegram adapter: PID file exists, but health check failed (may be starting or unhealthy).")
+            else:
+                print("Telegram adapter: not running")
+            return
+
+        print("No telegram action specified. Use: gaia telegram start|stop|status", file=sys.stderr)
+        return
+
     # Handle core Gaia CLI commands
     if args.action in ["prompt", "chat", "talk", "stats"]:
         kwargs = {

src/gaia/messaging/ingest.py

@@ -0,0 +1,44 @@
+"""Helpers to ingest uploaded media into VLM and RAG pipelines.
+
+Provides small, testable wrappers around `VLMClient` and `RAGSDK` so
+messaging adapters can hand off downloaded files for processing.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from typing import Dict, Any
+
+from gaia.llm.vlm_client import VLMClient
+from gaia.rag.sdk import RAGSDK, RAGConfig
+
+log = logging.getLogger(__name__)
+
+
+def ingest_image_to_vlm(image_path: str, vlm_model: str = None) -> Dict[str, Any]:
+    """Run VLM extraction on an image file and return results.
+
+    Returns dict with keys: status, text, model, error (if any)
+    """
+    if not os.path.exists(image_path):
+        return {"status": "error", "error": "file_not_found", "path": image_path}
+
+    try:
+        client = VLMClient(vlm_model=vlm_model) if vlm_model else VLMClient()
+        image_bytes = open(image_path, "rb").read()
+        text = client.extract_from_image(image_bytes)
+        return {"status": "success", "text": text, "model": client.vlm_model}
+    except Exception as e:  # pragma: no cover - integration depends on Lemonade
+        log.exception("VLM ingestion failed")
+        return {"status": "error", "error": str(e), "path": image_path}
+
+
+def ingest_document_to_rag(file_path: str, config: RAGConfig | None = None) -> Dict[str, Any]:
+    """Index a document into the RAG index via RAGSDK.index_document.
+
+    Returns whatever `RAGSDK.index_document` returns (a dict of stats).
+    """
+    cfg = config or RAGConfig()
+    rag = RAGSDK(cfg)
+    result = rag.index_document(file_path)
+    return result