ltcai 11.1.0 → 11.4.0

package/latticeai/core/workspace_os_constants.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 from typing import Dict
 
-WORKSPACE_OS_VERSION = "11.1.0"
+WORKSPACE_OS_VERSION = "11.4.0"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type

package/latticeai/integrations/telegram_bot/__init__.py

@@ -0,0 +1,123 @@
+"""Telegram bridge — the phone-side surface of a local Lattice AI.
+
+The bot mirrors the web app's capabilities onto a chat: server status, models,
+Knowledge Graph counts, screenshots, history, document capture, the Review
+Center, and the full human-in-the-loop agent handshake. It is fail-closed by
+construction — no bot token, no chat allowlist, or no explicitly provisioned
+server capability and the loop refuses to start.
+
+Split into cohesive submodules in v11.3.0 (no behaviour change): ``config``
+(environment, endpoints, logger and the authenticated server client),
+``helpers`` (chat-id registry, Telegram API, network, agent artifacts),
+``screens`` (the menu commands that report on the running system), ``flows``
+(ask → render → approve, including the pending-plan state), and ``dispatch``
+(command/callback routing and the poll loop). ``__main__`` keeps
+``python -m latticeai.integrations.telegram_bot`` working. This module
+re-exports every name the single file exposed, so
+``latticeai.integrations.telegram_bot.X`` keeps working.
+
+Stubbing note: rebinding one of these *here* changes only this module's name.
+The submodule that calls it holds its own reference, so a test standing in for
+``CHAT_IDS_FILE``/``TOKEN``/``AGENT_WORKSPACE`` patches
+``…telegram_bot.helpers``, for ``_server_client``/``_bot_pending_plans``
+``…telegram_bot.flows`` (or ``…screens`` for a screen), and for ``get_updates``
+``…telegram_bot.dispatch``.
+"""
+
+# The single file had no ``__all__``, so its public surface was "every module
+# global" — including the names it imported for its own use. Every re-export
+# below therefore uses the redundant-alias form: it reproduces exactly that
+# surface, and it marks each name as deliberate rather than a leftover import.
+from latticeai.cli.runtime import _load_env_file as _load_env_file
+from latticeai.core.io_utils import atomic_write_json as atomic_write_json
+from latticeai.core.logging_safety import (
+    install_sensitive_log_filter as install_sensitive_log_filter,
+)
+from latticeai.core.logging_safety import safe_log_text as safe_log_text
+from latticeai.core.quiet import quiet as quiet
+
+from .config import AGENT_RESUME_URL as AGENT_RESUME_URL
+from .config import AGENT_URL as AGENT_URL
+from .config import AGENT_WORKSPACE as AGENT_WORKSPACE
+from .config import API_URL as API_URL
+from .config import BASE_URL as BASE_URL
+from .config import CHAT_IDS_FILE as CHAT_IDS_FILE
+from .config import CHAT_URL as CHAT_URL
+from .config import DATA_DIR as DATA_DIR
+from .config import GRAPH_STATS_URL as GRAPH_STATS_URL
+from .config import HISTORY_URL as HISTORY_URL
+from .config import INVITE_CODE as INVITE_CODE
+from .config import MAX_TELEGRAM_FILE_BYTES as MAX_TELEGRAM_FILE_BYTES
+from .config import MCP_TOOLS_URL as MCP_TOOLS_URL
+from .config import MODELS_URL as MODELS_URL
+from .config import PROPOSALS_URL as PROPOSALS_URL
+from .config import PUBLIC_WEB_URL as PUBLIC_WEB_URL
+from .config import SERVER_PORT as SERVER_PORT
+from .config import STATUS_URL as STATUS_URL
+from .config import TOKEN as TOKEN
+from .config import UPLOAD_DOC_URL as UPLOAD_DOC_URL
+from .config import _get_server_session as _get_server_session
+from .config import _server_client as _server_client
+from .config import env_value as env_value
+from .config import load_env_file as load_env_file
+from .config import logger as logger
+from .dispatch import HELP_TEXT as HELP_TEXT
+from .dispatch import _log_task_exception as _log_task_exception
+from .dispatch import handle_callback_query as handle_callback_query
+from .dispatch import handle_command as handle_command
+from .dispatch import run_bot as run_bot
+from .flows import _approval_pause_id as _approval_pause_id
+from .flows import _bot_pending_plans as _bot_pending_plans
+from .flows import _is_approval_pause as _is_approval_pause
+from .flows import _resume_payload as _resume_payload
+from .flows import ask_ai as ask_ai
+from .flows import format_artifact_card as format_artifact_card
+from .flows import format_grounding_badge as format_grounding_badge
+from .flows import format_proposals as format_proposals
+from .flows import format_run_explanation as format_run_explanation
+from .flows import handle_plan_callback as handle_plan_callback
+from .flows import handle_proposal_callback as handle_proposal_callback
+from .flows import process_ai_request as process_ai_request
+from .flows import send_artifact_card as send_artifact_card
+from .flows import send_grounding_badge as send_grounding_badge
+from .flows import send_plan_for_approval as send_plan_for_approval
+from .flows import send_run_explanation as send_run_explanation
+from .flows import show_review_center as show_review_center
+from .helpers import allowed_chat_ids as allowed_chat_ids
+from .helpers import answer_callback as answer_callback
+from .helpers import broadcast_web_chat as broadcast_web_chat
+from .helpers import collect_generated_files as collect_generated_files
+from .helpers import collect_preview_urls as collect_preview_urls
+from .helpers import download_as_base64 as download_as_base64
+from .helpers import download_telegram_file as download_telegram_file
+from .helpers import edit_message as edit_message
+from .helpers import get_graph_url as get_graph_url
+from .helpers import get_lan_ip as get_lan_ip
+from .helpers import get_updates as get_updates
+from .helpers import get_web_url as get_web_url
+from .helpers import is_chat_allowed as is_chat_allowed
+from .helpers import load_chat_ids as load_chat_ids
+from .helpers import parse_allowed_chat_ids as parse_allowed_chat_ids
+from .helpers import register_chat_id as register_chat_id
+from .helpers import resolve_workspace_file as resolve_workspace_file
+from .helpers import save_chat_ids as save_chat_ids
+from .helpers import send_chat_action as send_chat_action
+from .helpers import send_document as send_document
+from .helpers import send_generated_files as send_generated_files
+from .helpers import send_message as send_message
+from .helpers import send_photo as send_photo
+from .helpers import send_preview_links as send_preview_links
+from .screens import MAIN_MENU as MAIN_MENU
+from .screens import _mac_ram_used_gb as _mac_ram_used_gb
+from .screens import _unload_all_report as _unload_all_report
+from .screens import clear_server_history as clear_server_history
+from .screens import do_unload_model as do_unload_model
+from .screens import process_document_file as process_document_file
+from .screens import send_mcp_tools as send_mcp_tools
+from .screens import send_web_link as send_web_link
+from .screens import show_graph_stats as show_graph_stats
+from .screens import show_history_summary as show_history_summary
+from .screens import show_menu as show_menu
+from .screens import show_model_info as show_model_info
+from .screens import show_status as show_status
+from .screens import take_screenshot as take_screenshot

package/latticeai/integrations/telegram_bot/__main__.py

@@ -0,0 +1,17 @@
+"""Script entry: ``python -m latticeai.integrations.telegram_bot``.
+
+The single file carried this block under ``if __name__ == "__main__"``. A
+package cannot: ``__init__`` is never ``__main__``. Moving it here verbatim is
+what keeps the ``-m`` invocation working after the v11.3.0 split.
+"""
+
+import asyncio
+
+from latticeai.core.quiet import quiet
+from latticeai.integrations.telegram_bot import run_bot
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(run_bot())
+    except KeyboardInterrupt:
+        quiet()

package/latticeai/integrations/telegram_bot/config.py

@@ -0,0 +1,86 @@
+"""Environment, endpoints, logger, and the bot's server capability.
+
+Every value the bridge reads from the environment is resolved here, once, at
+import — the module *is* the bot's configuration surface. Importing it has the
+same side effects the single file had at its own import: the sensitive-log
+filter is installed, ``.env`` is loaded, and the data directory is provisioned.
+
+Security boundary (unchanged since 11.0.1): :func:`_server_client` is the only
+authenticated client. It carries the explicitly provisioned bot-to-server
+bearer capability and is used for Lattice-server calls alone — never for
+api.telegram.org, which always gets the plain ``httpx.AsyncClient`` the poll
+loop owns.
+
+Stubbing note: a constant is read through the globals of the module that *uses*
+it, so a test standing in for ``TOKEN``/``CHAT_IDS_FILE``/``AGENT_WORKSPACE``
+patches ``helpers``/``screens``/``flows``/``dispatch``, not this module.
+"""
+
+import logging
+import os
+from pathlib import Path
+
+import httpx
+
+from latticeai.cli.runtime import _load_env_file
+from latticeai.core.logging_safety import install_sensitive_log_filter
+
+install_sensitive_log_filter()
+
+def load_env_file(path=".env"):
+    # Single source of truth: shared with ltcai_cli via latticeai.cli.runtime.
+    _load_env_file(Path(path))
+
+load_env_file()
+
+def env_value(primary: str, default: str = "") -> str:
+    return os.getenv(primary) or default
+
+TOKEN          = env_value("LATTICEAI_TELEGRAM_BOT_TOKEN")
+API_URL        = f"https://api.telegram.org/bot{TOKEN}"
+SERVER_PORT    = int(env_value("LATTICEAI_SERVER_PORT", "4825"))
+BASE_URL       = env_value("LATTICEAI_BASE_URL", env_value("LATTICEAI_SERVER_URL", f"http://127.0.0.1:{SERVER_PORT}")).rstrip("/")
+CHAT_URL       = f"{BASE_URL}/chat"
+AGENT_URL      = f"{BASE_URL}/agent"
+MCP_TOOLS_URL  = f"{BASE_URL}/mcp/tools"
+HISTORY_URL    = f"{BASE_URL}/history"
+STATUS_URL     = f"{BASE_URL}/status"
+MODELS_URL     = f"{BASE_URL}/models"
+GRAPH_STATS_URL = f"{BASE_URL}/knowledge-graph/stats"
+UPLOAD_DOC_URL  = f"{BASE_URL}/upload/document"
+PROPOSALS_URL   = f"{BASE_URL}/api/proposals"
+
+AGENT_RESUME_URL      = f"{BASE_URL}/agent/resume"
+AGENT_WORKSPACE       = Path(env_value("LATTICEAI_AGENT_ROOT", "agent_workspace")).resolve()
+
+MAX_TELEGRAM_FILE_BYTES = 45 * 1024 * 1024
+INVITE_CODE           = env_value("LATTICEAI_INVITE_CODE")
+PUBLIC_WEB_URL        = env_value("LATTICEAI_PUBLIC_URL")
+DATA_DIR              = Path(env_value("LATTICEAI_DATA_DIR", str(Path.home() / ".ltcai")))
+DATA_DIR.mkdir(parents=True, exist_ok=True)
+CHAT_IDS_FILE = Path(env_value("LATTICEAI_TELEGRAM_CHATS_FILE", str(DATA_DIR / "telegram_chats.json")))
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+# ── Server session auth ───────────────────────────────────────────────────────
+
+def _get_server_session() -> str:
+    """Return only the explicitly provisioned bot-to-server token.
+
+    Web sessions are hashed at rest and belong to interactive users. Scanning
+    ``sessions.json`` cannot recover a usable token and would couple the bot to
+    whichever administrator happened to be logged in most recently.
+    """
+    return env_value("LATTICEAI_SERVER_SESSION_TOKEN").strip()
+
+def _server_client(**kwargs) -> httpx.AsyncClient:
+    """Return a server client authenticated by an explicit bearer capability."""
+    token = _get_server_session()
+    if not token:
+        raise RuntimeError(
+            "LATTICEAI_SERVER_SESSION_TOKEN is required for Telegram server API calls."
+        )
+    headers = dict(kwargs.pop("headers", {}) or {})
+    headers["Authorization"] = f"Bearer {token}"
+    return httpx.AsyncClient(headers=headers, **kwargs)

package/latticeai/integrations/telegram_bot/dispatch.py

@@ -0,0 +1,311 @@
+"""Routing and lifecycle: the poll loop and the two things it can route to.
+
+Slash commands (:func:`handle_command`), inline-button callbacks
+(:func:`handle_callback_query`), and the long-poll loop (:func:`run_bot`) that
+feeds both. This is the only layer that decides *what* happens for an incoming
+update; every branch delegates to a screen or a flow and holds no logic of its
+own beyond the routing table.
+
+Fail-closed startup, unchanged: no bot token, no allowlist, or no server
+capability means the loop never starts. Every allowed update is dispatched onto
+its own task with an exception logger attached, so one failing handler cannot
+stop the poll.
+
+Stubbing note: ``get_updates``, ``TOKEN``, ``download_as_base64``,
+``process_ai_request``, ``handle_command``, ``handle_callback_query``, and every
+screen/flow handler are read as *this* module's globals, so a test standing in
+for any of them patches this module.
+"""
+
+import asyncio
+
+import httpx
+
+from latticeai.core.logging_safety import safe_log_text
+
+from .config import TOKEN, _get_server_session, logger
+from .flows import (
+    _is_approval_pause,
+    ask_ai,
+    handle_plan_callback,
+    handle_proposal_callback,
+    process_ai_request,
+    send_plan_for_approval,
+    show_review_center,
+)
+from .helpers import (
+    allowed_chat_ids,
+    answer_callback,
+    download_as_base64,
+    get_updates,
+    is_chat_allowed,
+    register_chat_id,
+    send_chat_action,
+    send_message,
+)
+from .screens import (
+    clear_server_history,
+    do_unload_model,
+    process_document_file,
+    send_mcp_tools,
+    send_web_link,
+    show_graph_stats,
+    show_history_summary,
+    show_menu,
+    show_model_info,
+    show_status,
+    take_screenshot,
+)
+
+# ── Command dispatch ──────────────────────────────────────────────────────────
+
+HELP_TEXT = """\
+🧠 Lattice AI 원격 제어 명령어
+
+/menu — 메인 메뉴 (인라인 키보드)
+/status — 서버 상태 및 메모리
+/model — 현재 모델 + 언로드 버튼
+/unload — 모든 모델 언로드 (RAM 해제)
+/graph — Knowledge Graph 통계
+/ss 또는 /screenshot — 현재 화면 캡처
+/history [n] — 최근 대화 n건 (기본 5)
+/clear [n] — 기록 정리 (마지막 n건 유지)
+/web — 웹 UI 링크
+/mcp — MCP 도구 목록
+/review — 변경 제안 검토함 (승인/거절)
+/help — 이 도움말
+
+/agent <작업> — 멀티 LLM 에이전트 (계획 확인 후 실행)
+/agent <작업> --exec <모델> --review <모델> — 실행/검토 LLM 지정
+
+일반 텍스트 → AI에게 질문
+사진 전송 → AI 이미지 분석
+문서 전송(PDF, DOCX, XLSX, PPTX, TXT, CSV) → Knowledge Graph 수집
+"""
+
+async def handle_command(client, chat_id, command: str, args: str):
+    cmd = command.lower().lstrip("/").split("@")[0]
+
+    if cmd == "start":
+        await send_message(client, chat_id, "🧠 Lattice AI 원격 제어 준비 완료!")
+        await show_menu(client, chat_id)
+    elif cmd == "menu":
+        await show_menu(client, chat_id)
+    elif cmd == "status":
+        await show_status(client, chat_id)
+    elif cmd == "model":
+        await show_model_info(client, chat_id)
+    elif cmd == "unload":
+        await do_unload_model(client, chat_id)
+    elif cmd == "graph":
+        await show_graph_stats(client, chat_id)
+    elif cmd in {"ss", "screenshot"}:
+        await take_screenshot(client, chat_id)
+    elif cmd == "history":
+        n = int(args.strip()) if args.strip().isdigit() else 5
+        await show_history_summary(client, chat_id, n)
+    elif cmd in {"clear", "clear_history", "forget"}:
+        keep = int(args.strip()) if args.strip().isdigit() else 0
+        await clear_server_history(client, chat_id, keep)
+    elif cmd == "web":
+        await send_web_link(client, chat_id)
+    elif cmd == "mcp":
+        await send_mcp_tools(client, chat_id)
+    elif cmd in {"review", "proposals"}:
+        await show_review_center(client, chat_id)
+    elif cmd in {"help", "h"}:
+        await send_message(client, chat_id, HELP_TEXT)
+    elif cmd == "agent":
+        if not args:
+            await send_message(client, chat_id, "사용법: /agent <작업 내용>\n예: /agent 쇼핑몰 메인 페이지 HTML 만들어줘\n\n특정 AI 지정:\n/agent <작업> --exec openai/gpt-4o --review together:Qwen/Qwen3-VL-32B-Instruct")
+            return
+        # Parse optional --exec / --review flags
+        exec_model = reviewing_model = None
+        task_text = args
+        import re as _re
+        em = _re.search(r'--exec\s+(\S+)', args)
+        rm = _re.search(r'--review\s+(\S+)', args)
+        if em:
+            exec_model = em.group(1)
+            task_text = task_text.replace(em.group(0), "").strip()
+        if rm:
+            reviewing_model = rm.group(1)
+            task_text = task_text.replace(rm.group(0), "").strip()
+        await send_chat_action(client, chat_id, "typing")
+        data = await ask_ai(client, task_text, agent_mode=True,
+                            executing_model=exec_model, reviewing_model=reviewing_model)
+        if isinstance(data, dict) and _is_approval_pause(data):
+            await send_plan_for_approval(client, chat_id, data)
+        else:
+            ans = data.get("response", str(data)) if isinstance(data, dict) else str(data)
+            await send_message(client, chat_id, ans)
+    else:
+        await send_message(client, chat_id, f"알 수 없는 명령어: /{cmd}\n/help 로 명령어 목록을 확인하세요.")
+
+# ── Callback query handler ────────────────────────────────────────────────────
+
+async def handle_callback_query(client, callback_query):
+    cq_id = callback_query.get("id", "")
+    chat_id = (
+        (callback_query.get("message") or {}).get("chat") or {}
+    ).get("id")
+    data    = callback_query.get("data", "")
+
+    if not is_chat_allowed(chat_id):
+        logger.warning("허용되지 않은 텔레그램 callback 차단: %s", safe_log_text(chat_id))
+        await answer_callback(client, cq_id, "허용되지 않은 채팅입니다.")
+        return
+
+    await answer_callback(client, cq_id)
+
+    if data == "cmd:status":
+        await show_status(client, chat_id)
+    elif data == "cmd:model":
+        await show_model_info(client, chat_id)
+    elif data == "cmd:graph":
+        await show_graph_stats(client, chat_id)
+    elif data == "cmd:screenshot":
+        await take_screenshot(client, chat_id)
+    elif data == "cmd:history":
+        await show_history_summary(client, chat_id, 5)
+    elif data == "cmd:clear":
+        await clear_server_history(client, chat_id, 0)
+    elif data == "cmd:web":
+        await send_web_link(client, chat_id)
+    elif data == "cmd:mcp":
+        await send_mcp_tools(client, chat_id)
+    elif data == "cmd:review":
+        await show_review_center(client, chat_id)
+    elif data == "cmd:menu":
+        await show_menu(client, chat_id)
+    elif data.startswith("model:unload:"):
+        model_id = data[len("model:unload:"):]
+        await do_unload_model(client, chat_id, model_id)
+    elif data.startswith("plan:"):
+        task = asyncio.create_task(handle_plan_callback(client, chat_id, data))
+        task.add_done_callback(_log_task_exception)
+    elif data.startswith("proposal:"):
+        task = asyncio.create_task(handle_proposal_callback(client, chat_id, data))
+        task.add_done_callback(_log_task_exception)
+
+# ── Main loop ─────────────────────────────────────────────────────────────────
+
+async def run_bot():
+    if not TOKEN:
+        logger.warning("LATTICEAI_TELEGRAM_BOT_TOKEN이 설정되지 않아 텔레그램 봇을 시작하지 않습니다.")
+        return
+    if not allowed_chat_ids():
+        logger.error(
+            "LATTICEAI_TELEGRAM_ALLOWED_CHAT_IDS가 없어 텔레그램 봇을 시작하지 않습니다."
+        )
+        return
+    if not _get_server_session():
+        logger.error(
+            "LATTICEAI_SERVER_SESSION_TOKEN이 없어 텔레그램 봇을 시작하지 않습니다."
+        )
+        return
+
+    logger.info("🚀 비동기 텔레그램 봇 모드 시작!")
+    last_update_id = None
+    retry_delay = 1
+
+    async with httpx.AsyncClient() as client:
+        while True:
+            try:
+                updates = await get_updates(client, last_update_id)
+                retry_delay = 1
+            except Exception as e:
+                logger.error("get_updates 실패: %s", safe_log_text(e))
+                await asyncio.sleep(min(retry_delay, 30))
+                retry_delay = min(retry_delay * 2, 30)
+                continue
+
+            if not (updates and updates.get("ok")):
+                await asyncio.sleep(0.5)
+                continue
+
+            for update in updates.get("result", []):
+                try:
+                    last_update_id = update.get("update_id") + 1
+
+                    # ── Callback query (inline button press) ──────────────────
+                    if "callback_query" in update:
+                        task = asyncio.create_task(handle_callback_query(client, update["callback_query"]))
+                        task.add_done_callback(_log_task_exception)
+                        continue
+
+                    if "message" not in update:
+                        continue
+
+                    msg     = update["message"]
+                    chat_id = msg["chat"]["id"]
+                    if not is_chat_allowed(chat_id):
+                        logger.warning(
+                            "허용되지 않은 텔레그램 메시지 차단: %s",
+                            safe_log_text(chat_id),
+                        )
+                        continue
+                    register_chat_id(chat_id)
+                    text    = msg.get("text", "")
+                    caption = msg.get("caption", "")
+
+                    # ── Photo → vision AI ─────────────────────────────────────
+                    if "photo" in msg:
+                        file_id = msg["photo"][-1]["file_id"]
+                        await send_message(client, chat_id, "📸 사진을 받았습니다. 분석을 시작합니다...")
+                        image_data = await download_as_base64(client, file_id)
+                        prompt = caption or text or "이 이미지를 분석해줘."
+                        task = asyncio.create_task(process_ai_request(client, chat_id, prompt, image_data))
+                        task.add_done_callback(_log_task_exception)
+                        continue
+
+                    # ── Document ──────────────────────────────────────────────
+                    if "document" in msg:
+                        doc      = msg["document"]
+                        mime     = doc.get("mime_type", "")
+                        filename = doc.get("file_name", "file")
+                        if mime.startswith("image/"):
+                            image_data = await download_as_base64(client, doc["file_id"])
+                            prompt = caption or text or "이 이미지를 분석해줘."
+                            task = asyncio.create_task(process_ai_request(client, chat_id, prompt, image_data))
+                        else:
+                            await send_message(client, chat_id, f"📄 {filename} 을 Knowledge Graph에 수집합니다...")
+                            task = asyncio.create_task(
+                                process_document_file(client, chat_id, doc["file_id"], filename, caption)
+                            )
+                        task.add_done_callback(_log_task_exception)
+                        continue
+
+                    # ── Voice / audio ─────────────────────────────────────────
+                    if "voice" in msg or "audio" in msg:
+                        await send_message(
+                            client, chat_id,
+                            "🎤 음성 메시지를 받았습니다. 현재 음성 인식(Whisper)이 설정되어 있지 않습니다.\n"
+                            "텍스트로 질문을 보내주세요."
+                        )
+                        continue
+
+                    if not text:
+                        continue
+
+                    # ── Commands ──────────────────────────────────────────────
+                    if text.startswith("/"):
+                        parts   = text.split(None, 1)
+                        command = parts[0]
+                        args    = parts[1] if len(parts) > 1 else ""
+                        task = asyncio.create_task(handle_command(client, chat_id, command, args))
+                        task.add_done_callback(_log_task_exception)
+                        continue
+
+                    # ── Plain text → AI ───────────────────────────────────────
+                    task = asyncio.create_task(process_ai_request(client, chat_id, text))
+                    task.add_done_callback(_log_task_exception)
+
+                except Exception as e:
+                    logger.error("업데이트 처리 중 예외: %s", safe_log_text(e))
+
+            await asyncio.sleep(0.5)
+
+def _log_task_exception(task):
+    if not task.cancelled() and task.exception():
+        logger.error("백그라운드 태스크 예외: %s", safe_log_text(task.exception()))