ltcai 11.2.0 → 11.4.0

package/latticeai/integrations/telegram_bot/screens.py

@@ -0,0 +1,394 @@
+"""The command screens — one Lattice-server read (or upload) rendered for a phone.
+
+Everything reachable from the main menu that answers a question about the
+running system rather than driving a conversation: server status, loaded
+models, Knowledge Graph counts, a screenshot, chat history, the web-UI link,
+the MCP tool list, and document upload into the graph.
+
+Each screen follows the same shape: an optimistic chat action, one call through
+:func:`~latticeai.integrations.telegram_bot.config._server_client`, and a plain
+Korean rendering of exactly what came back — an unreachable server produces an
+empty payload, never an invented one.
+
+Stubbing note: these functions read ``_server_client``, ``_mac_ram_used_gb``,
+``send_photo``, ``send_message`` and ``download_telegram_file`` as *this*
+module's globals, so a test standing in for any of them patches this module.
+``get_web_url``/``get_graph_url`` are read here but resolve
+``PUBLIC_WEB_URL``/``get_lan_ip``/``SERVER_PORT`` inside ``helpers``.
+"""
+
+import asyncio
+import os
+import tempfile
+from pathlib import Path
+
+from latticeai.core.logging_safety import safe_log_text
+from latticeai.core.quiet import quiet
+
+from .config import (
+    API_URL,
+    BASE_URL,
+    GRAPH_STATS_URL,
+    HISTORY_URL,
+    MCP_TOOLS_URL,
+    MODELS_URL,
+    STATUS_URL,
+    UPLOAD_DOC_URL,
+    _server_client,
+    logger,
+)
+from .helpers import (
+    download_telegram_file,
+    get_graph_url,
+    get_web_url,
+    send_chat_action,
+    send_message,
+    send_photo,
+)
+
+# ── Main menu ─────────────────────────────────────────────────────────────────
+
+MAIN_MENU = {
+    "inline_keyboard": [
+        [
+            {"text": "📊 서버 상태",          "callback_data": "cmd:status"},
+            {"text": "🧠 현재 모델",           "callback_data": "cmd:model"},
+        ],
+        [
+            {"text": "🕸 Knowledge Graph",     "callback_data": "cmd:graph"},
+            {"text": "📸 스크린샷",            "callback_data": "cmd:screenshot"},
+        ],
+        [
+            {"text": "📜 최근 대화 5건",        "callback_data": "cmd:history"},
+            {"text": "🗑 기록 정리",            "callback_data": "cmd:clear"},
+        ],
+        [
+            {"text": "🔗 웹 UI 열기",           "callback_data": "cmd:web"},
+            {"text": "🔌 MCP 도구 목록",        "callback_data": "cmd:mcp"},
+        ],
+        [
+            {"text": "🗂 변경 제안 검토",        "callback_data": "cmd:review"},
+        ],
+    ]
+}
+
+async def show_menu(client, chat_id):
+    await send_message(client, chat_id, "📱 Lattice AI 원격 제어 메뉴입니다.", reply_markup=MAIN_MENU)
+
+# ── Server status ─────────────────────────────────────────────────────────────
+
+async def _mac_ram_used_gb() -> str:
+    try:
+        vm_proc = await asyncio.create_subprocess_exec(
+            "vm_stat", stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.DEVNULL
+        )
+        vm_out, _ = await vm_proc.communicate()
+        lines = vm_out.decode().splitlines()
+
+        # Parse page size from header line: "Mach Virtual Memory Statistics: (page size of 16384 bytes)"
+        page_size = 4096
+        if lines:
+            import re
+            m = re.search(r"page size of (\d+) bytes", lines[0])
+            if m:
+                page_size = int(m.group(1))
+
+        stats = {}
+        for line in lines[1:]:
+            if ":" in line:
+                k, _, v = line.partition(":")
+                try:
+                    stats[k.strip()] = int(v.strip().rstrip(".")) * page_size
+                except ValueError:
+                    quiet()
+
+        used = stats.get("Pages active", 0) + stats.get("Pages wired down", 0)
+
+        mem_proc = await asyncio.create_subprocess_exec(
+            "sysctl", "-n", "hw.memsize", stdout=asyncio.subprocess.PIPE
+        )
+        mem_out, _ = await mem_proc.communicate()
+        total = int(mem_out.strip())
+        return f"{used/1e9:.1f} GB / {total/1e9:.0f} GB"
+    except Exception:
+        return "N/A"
+
+async def show_status(client, chat_id):
+    await send_chat_action(client, chat_id, "typing")
+    try:
+        async with _server_client() as lc:
+            res = await lc.get(STATUS_URL, timeout=5.0)
+            data = res.json() if res.status_code == 200 else {}
+    except Exception:
+        data = {}
+
+    ram = await _mac_ram_used_gb()
+    model = data.get("loaded_model") or "없음"
+    mode  = data.get("mode") or "unknown"
+    state = "🟢 온라인" if data.get("status") == "online" else "🔴 오프라인"
+
+    text = (
+        f"📊 Lattice AI 서버 상태\n"
+        f"상태: {state}\n"
+        f"모드: {mode}\n"
+        f"모델: {model}\n"
+        f"RAM: {ram}"
+    )
+    await send_message(client, chat_id, text)
+
+# ── Model info & unload ───────────────────────────────────────────────────────
+
+async def show_model_info(client, chat_id):
+    await send_chat_action(client, chat_id, "typing")
+    try:
+        async with _server_client() as lc:
+            res = await lc.get(MODELS_URL, timeout=5.0)
+            data = res.json() if res.status_code == 200 else {}
+    except Exception:
+        data = {}
+
+    current = data.get("current") or "없음"
+    loaded  = data.get("loaded") or []
+    loaded_str = "\n".join(f"  - {m}" for m in loaded) if loaded else "  없음"
+    text = f"🧠 현재 모델: {current}\n\n로드된 모델:\n{loaded_str}"
+
+    markup = None
+    if loaded:
+        markup = {
+            "inline_keyboard": [
+                [{"text": f"🗑 {m} 언로드", "callback_data": f"model:unload:{m}"}]
+                for m in loaded
+            ] + [[{"text": "↩ 메뉴로", "callback_data": "cmd:menu"}]]
+        }
+    await send_message(client, chat_id, text, reply_markup=markup)
+
+def _unload_all_report(results: list[tuple[str, int]]) -> str:
+    """Report an unload-all run from the statuses the server actually returned."""
+    failed = [(mid, code) for mid, code in results if code != 200]
+    if not failed:
+        return "✅ 모든 모델 언로드 완료. RAM이 해제되었습니다."
+    detail = ", ".join(f"{mid} ({code})" for mid, code in failed)
+    return (
+        f"일부 모델 언로드 실패: {detail}\n"
+        f"성공 {len(results) - len(failed)}개 / 실패 {len(failed)}개"
+    )
+
+async def do_unload_model(client, chat_id, model_id: str = ""):
+    await send_chat_action(client, chat_id, "typing")
+    try:
+        results: list[tuple[str, int]] | None = None
+        async with _server_client() as lc:
+            if model_id:
+                res = await lc.delete(f"{BASE_URL}/models/unload/{model_id}", timeout=15.0)
+            else:
+                # Unload all: keep every delete's real status. Discarding them
+                # for a synthesized 200 reported "모든 모델 언로드 완료" even
+                # when a model refused to unload.
+                res = await lc.get(MODELS_URL, timeout=5.0)
+                if res.status_code == 200:
+                    results = []
+                    for mid in res.json().get("loaded") or []:
+                        deleted = await lc.delete(f"{BASE_URL}/models/unload/{mid}", timeout=15.0)
+                        results.append((mid, deleted.status_code))
+        if results is not None:
+            await send_message(client, chat_id, _unload_all_report(results))
+        elif res.status_code == 200:
+            await send_message(client, chat_id, f"✅ {model_id} 언로드 완료. RAM이 해제되었습니다.")
+        else:
+            await send_message(client, chat_id, f"언로드 실패 ({res.status_code})")
+    except Exception as e:
+        await send_message(client, chat_id, f"언로드 오류: {e}")
+
+# ── Knowledge Graph stats ─────────────────────────────────────────────────────
+
+async def show_graph_stats(client, chat_id):
+    await send_chat_action(client, chat_id, "typing")
+    try:
+        async with _server_client() as lc:
+            res = await lc.get(GRAPH_STATS_URL, timeout=5.0)
+            data = res.json() if res.status_code == 200 else {}
+    except Exception:
+        data = {}
+
+    nodes = data.get("nodes") or {}
+    edges = data.get("edges") or {}
+    total_nodes = sum(nodes.values())
+    total_edges = sum(edges.values())
+
+    node_lines = "\n".join(f"  {t}: {c}" for t, c in sorted(nodes.items(), key=lambda x: -x[1])) or "  없음"
+    edge_lines  = "\n".join(f"  {t}: {c}" for t, c in sorted(edges.items(), key=lambda x: -x[1])[:8]) or "  없음"
+
+    text = (
+        f"🕸 Knowledge Graph 통계\n\n"
+        f"노드 총 {total_nodes}개:\n{node_lines}\n\n"
+        f"엣지 총 {total_edges}개:\n{edge_lines}\n\n"
+        f"그래프 보기: {get_graph_url()}"
+    )
+    markup = {
+        "inline_keyboard": [[
+            {"text": "🔗 그래프 열기", "url": get_graph_url()},
+            {"text": "↩ 메뉴로", "callback_data": "cmd:menu"},
+        ]]
+    }
+    await send_message(client, chat_id, text, reply_markup=markup)
+
+# ── Screenshot ────────────────────────────────────────────────────────────────
+
+async def take_screenshot(client, chat_id):
+    await send_chat_action(client, chat_id, "upload_photo")
+    # mkstemp, not mktemp: mktemp only predicts an unused name, leaving a
+    # window in which anything can create that path first. mkstemp creates
+    # the file atomically with 0600.
+    _fd, _name = tempfile.mkstemp(suffix=".jpg")
+    os.close(_fd)
+    tmp = Path(_name)
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            "screencapture", "-x", str(tmp),
+            stdout=asyncio.subprocess.DEVNULL,
+            stderr=asyncio.subprocess.DEVNULL,
+        )
+        await asyncio.wait_for(proc.communicate(), timeout=10.0)
+        if tmp.exists() and tmp.stat().st_size > 0:
+            await send_photo(client, chat_id, tmp, caption="현재 화면입니다.")
+        else:
+            await send_message(client, chat_id, "스크린샷 파일이 생성되지 않았습니다. screencapture가 설치되어 있는지 확인하세요.")
+    except asyncio.TimeoutError:
+        await send_message(client, chat_id, "스크린샷 시간 초과")
+    except FileNotFoundError:
+        await send_message(client, chat_id, "screencapture 명령이 없습니다. macOS에서만 동작합니다.")
+    except Exception as e:
+        await send_message(client, chat_id, f"스크린샷 오류: {e}")
+    finally:
+        try:
+            tmp.unlink(missing_ok=True)
+        except Exception:
+            quiet()
+
+# ── History ───────────────────────────────────────────────────────────────────
+
+async def show_history_summary(client, chat_id, n: int = 5):
+    await send_chat_action(client, chat_id, "typing")
+    try:
+        async with _server_client() as lc:
+            res = await lc.get(HISTORY_URL, timeout=10.0)
+            items = res.json() if res.status_code == 200 else []
+    except Exception:
+        items = []
+
+    if not items:
+        await send_message(client, chat_id, "저장된 대화 기록이 없습니다.")
+        return
+
+    recent = [i for i in items if i.get("role") == "user"][-n:]
+    lines = [f"📜 최근 사용자 메시지 {len(recent)}건\n"]
+    for item in recent:
+        ts  = str(item.get("timestamp", ""))[:16]
+        src = item.get("source", "web")
+        content = str(item.get("content", ""))[:120].replace("\n", " ")
+        lines.append(f"[{ts}] ({src}) {content}")
+    await send_message(client, chat_id, "\n".join(lines))
+
+async def clear_server_history(client, chat_id, keep_last=0):
+    try:
+        async with _server_client() as lc:
+            res = await lc.delete(HISTORY_URL, params={"keep_last": keep_last}, timeout=10.0)
+            data = res.json() if res.headers.get("content-type", "").startswith("application/json") else {}
+        if res.status_code == 200:
+            await send_message(client, chat_id, f"대화 기록을 정리했습니다. 삭제 {data.get('removed', 0)}개, 유지 {data.get('kept', 0)}개.")
+        else:
+            await send_message(client, chat_id, f"대화 기록 정리 실패: {res.status_code}")
+    except Exception as e:
+        await send_message(client, chat_id, f"대화 기록 정리 오류: {e}")
+
+# ── Web UI link ───────────────────────────────────────────────────────────────
+
+async def send_web_link(client, chat_id):
+    web_url = get_web_url()
+    text = (
+        "웹 UI 링크입니다.\n"
+        f"{web_url}\n\n"
+        "핸드폰이 Mac과 같은 Wi-Fi에 있어야 바로 열립니다. "
+        "외부망에서 쓰려면 LATTICEAI_PUBLIC_URL에 터널 주소를 설정하세요."
+    )
+    payload = {
+        "chat_id": chat_id,
+        "text": text,
+        "reply_markup": {
+            "inline_keyboard": [[
+                {"text": "Lattice AI Web 열기", "url": web_url},
+                {"text": "Knowledge Graph", "url": get_graph_url()},
+            ]]
+        },
+    }
+    try:
+        # The Telegram client, like every other helper here. Sending this on the
+        # server client shipped the local bearer capability to api.telegram.org
+        # and failed outright whenever that token was unset.
+        await client.post(f"{API_URL}/sendMessage", json=payload)
+    except Exception as e:
+        logger.error("웹 링크 전송 실패: %s", safe_log_text(e))
+
+# ── MCP tools ─────────────────────────────────────────────────────────────────
+
+async def send_mcp_tools(client, chat_id):
+    try:
+        async with _server_client() as lc:
+            res = await lc.get(MCP_TOOLS_URL, timeout=10.0)
+            if res.status_code != 200:
+                await send_message(client, chat_id, f"MCP 도구 목록을 가져오지 못했습니다: {res.status_code}")
+                return
+            data = res.json()
+        names = [tool["name"] for tool in data.get("tools", [])]
+        await send_message(client, chat_id, "사용 가능한 MCP 도구:\n" + ("\n".join(f"- {n}" for n in names) or "없음"))
+    except Exception as e:
+        await send_message(client, chat_id, f"MCP 도구 조회 실패: {e}")
+
+# ── Document upload → knowledge graph ────────────────────────────────────────
+
+async def process_document_file(client, chat_id, file_id: str, filename: str, caption: str = ""):
+    await send_chat_action(client, chat_id, "upload_document")
+    raw = await download_telegram_file(client, file_id)
+    if not raw:
+        await send_message(client, chat_id, "파일 다운로드 실패")
+        return
+
+    suffix = Path(filename).suffix.lower()
+    allowed = {".pdf", ".docx", ".xlsx", ".pptx", ".txt", ".md", ".csv"}
+    if suffix not in allowed:
+        await send_message(client, chat_id,
+                           f"지원하지 않는 파일 형식입니다({suffix}). "
+                           f"지원 형식: {', '.join(sorted(allowed))}")
+        return
+
+    _fd, _name = tempfile.mkstemp(suffix=suffix)  # see take_screenshot
+    os.close(_fd)
+    tmp = Path(_name)
+    try:
+        tmp.write_bytes(raw)
+        async with _server_client() as lc:
+            res = await lc.post(
+                UPLOAD_DOC_URL,
+                files={"file": (filename, raw)},
+                timeout=60.0,
+            )
+        if res.status_code == 200:
+            data = res.json()
+            chars   = data.get("chars") or len(raw)
+            preview = str(data.get("preview") or "")[:300]
+            kg      = data.get("knowledge_graph") or {}
+            node_id = kg.get("node_id", "")
+            text = (
+                f"✅ {filename} 수집 완료\n"
+                f"크기: {len(raw) // 1024} KB | 문자: {chars}\n"
+                f"노드: {node_id}\n"
+                f"\n미리보기:\n{preview}"
+            )
+            await send_message(client, chat_id, text)
+        else:
+            err = res.json().get("detail") if res.headers.get("content-type", "").startswith("application/json") else res.text
+            await send_message(client, chat_id, f"업로드 실패 ({res.status_code}): {err}")
+    except Exception as e:
+        await send_message(client, chat_id, f"문서 처리 오류: {e}")
+    finally:
+        tmp.unlink(missing_ok=True)

package/latticeai/models/router/__init__.py

@@ -0,0 +1,88 @@
+"""
+LLM Router — mlx-vlm 기반 Gemma 4 최적화 및 추측 디코딩(Speculative Decoding) 코어
+
+v11.3.0 turned this module into a package. :class:`LLMRouter` is composed from
+four cohesive mixins, each of which moved here verbatim:
+
+* :mod:`.loading` — the guarded optional backends and every method that reads
+  them (``load_model``, ``_load_cloud_model``, ``_release_memory``);
+* :mod:`.registry` — the locked model registry, eviction, and the immutable
+  request-scoped snapshot generation runs against;
+* :mod:`.generation` — chat generation and streaming, local and cloud;
+* :mod:`.documents` — the same backends driven by a caller-supplied system
+  prompt.
+
+Around them: :mod:`.branding` (system prompt + legacy-alias rewrite),
+:mod:`.errors` (the typed mid-stream failure), :mod:`.catalog` (model refs and
+provenance), :mod:`.local_models` (finding a downloaded model on disk).
+
+Every name this module exported still resolves from
+``latticeai.models.router`` — with one deliberate exception, spelled out
+because it is the whole reason the loading half is one module:
+
+    ``mx`` / ``vlm_load`` / ``lm_load`` / ``VLM_AVAILABLE`` / ``LM_AVAILABLE``
+    are **rebound at runtime** by :func:`ensure_mlx_runtime` after an installer
+    has run. Re-exporting them here would publish the import-time value
+    forever, so ``ensure_mlx_runtime`` would appear to do nothing. Read them —
+    and stand in for them — on ``latticeai.models.router.loading``, where they
+    live.
+
+Stubbing note, same shape: a name rebound *here* changes only this module's
+binding. The submodule that calls it holds its own, so a test standing in for
+a collaborator patches the submodule that reads it.
+"""
+
+# The catalog data lives in .model_providers; re-exported here so
+# ``from latticeai.models.router import OPENAI_COMPATIBLE_PROVIDERS`` (and the
+# model_runtime re-export chain) resolve unchanged after the split.
+from latticeai.core.quiet import quiet as quiet
+from latticeai.models.model_providers import (
+    MODEL_SOURCE_BY_FAMILY as MODEL_SOURCE_BY_FAMILY,
+)
+from latticeai.models.model_providers import (
+    OPENAI_COMPATIBLE_PROVIDERS as OPENAI_COMPATIBLE_PROVIDERS,
+)
+from latticeai.models.model_providers import (
+    PROVIDER_MODEL_CATALOG as PROVIDER_MODEL_CATALOG,
+)
+
+from .branding import BRAND_NAME as BRAND_NAME
+from .branding import CITATION_INSTRUCTION as CITATION_INSTRUCTION
+from .branding import LEGACY_BRAND_PATTERNS as LEGACY_BRAND_PATTERNS
+from .branding import SYSTEM_PROMPT as SYSTEM_PROMPT
+from .branding import _compose_system as _compose_system
+from .branding import normalize_branding as normalize_branding
+from .catalog import CloudModel as CloudModel
+from .catalog import parse_model_ref as parse_model_ref
+from .catalog import source_metadata_for_model as source_metadata_for_model
+from .documents import _DocumentMixin
+from .errors import ModelStreamError as ModelStreamError
+from .errors import _stream_failure as _stream_failure
+from .generation import _GenerationMixin
+
+# ``AsyncOpenAI`` and ``executor`` are bound once at import and never rebound,
+# so a re-export is the same object the loading half uses — unlike the five MLX
+# names named in the module docstring.
+from .loading import AsyncOpenAI as AsyncOpenAI
+from .loading import _LoadingMixin
+from .loading import _mlx_sampler as _mlx_sampler
+from .loading import ensure_mlx_runtime as ensure_mlx_runtime
+from .loading import executor as executor
+from .local_models import HF_MODELS_ROOT as HF_MODELS_ROOT
+from .local_models import _is_gemma4_model_id as _is_gemma4_model_id
+from .local_models import _local_model_type as _local_model_type
+from .local_models import _looks_like_hf_model_dir as _looks_like_hf_model_dir
+from .local_models import _resolve_local_hf_model as _resolve_local_hf_model
+from .local_models import hf_cache_model_dir as hf_cache_model_dir
+from .local_models import hf_model_dir as hf_model_dir
+from .registry import _RegistryMixin
+
+
+class LLMRouter(_LoadingMixin, _RegistryMixin, _GenerationMixin, _DocumentMixin):
+    """The multi-engine router, composed from its four cohesive halves.
+
+    The mixins define disjoint method sets, so resolution order changes nothing
+    at runtime: this class exposes exactly the methods it exposed when they all
+    lived in one 1,007-line module. ``__init__`` comes from the registry half,
+    which owns the state the other three read.
+    """

package/latticeai/models/router/_contract.py

@@ -0,0 +1,66 @@
+"""The seam the four LLMRouter mixins share.
+
+``LLMRouter`` is assembled from the loading, registry, generation and document
+mixins. Each reads state it does not own — the registry dict and its lock, the
+snapshot helper, the cloud error hint — because the point of the split is that
+"how a model is loaded" and "how a document is streamed" stop sharing a
+1,007-line file, not that they stop sharing ``self``.
+
+Typing-only, exactly like :mod:`lattice_brain.ingestion._contract`: the
+declarations below are never the implementation, so the MRO and every method
+resolution stay byte-for-byte what the single-file class had. Adding a
+cross-mixin call without declaring it here is a type error.
+"""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Dict, Optional, Tuple
+
+from .catalog import CloudModel
+
+
+class RouterCore:
+    """What any router mixin may assume about ``self``.
+
+    Never instantiated directly. Members are declared, not implemented: the
+    implementation lives in whichever mixin owns it.
+    """
+
+    # ── State owned by _RegistryMixin.__init__ ───────────────────────────────
+    #: A local entry is ``(model, tokenizer, draft_model, loader_kind)``; a
+    #: cloud entry is a :class:`CloudModel`.
+    _cache: Dict[str, Any]
+    _current: Optional[str]
+    _last_used: Dict[str, float]
+    _max_local_models: int
+    #: ``threading.RLock``; annotated ``Any`` because the runtime lock type is
+    #: private in typeshed and nothing here depends on its identity.
+    _lock: Any
+
+    # ── registry.py: reached from the load path ──────────────────────────────
+    def _touch(self, model_id: Optional[str] = None) -> None:
+        raise NotImplementedError
+
+    def _enforce_local_model_limit(self, incoming_key: str) -> None:
+        raise NotImplementedError
+
+    # ── loading.py: reached from every unload path ───────────────────────────
+    def _release_memory(self) -> None:
+        raise NotImplementedError
+
+    # ── registry.py: reached from both generation halves ─────────────────────
+    def _model_snapshot(
+        self, model_id: Optional[str] = None
+    ) -> tuple[Optional[str], object | None]:
+        raise NotImplementedError
+
+    def _unpack_local_cache(self, cached: Any) -> Tuple[Any, Any, Any, str]:
+        raise NotImplementedError
+
+    def _local_server_error_hint(self, cloud: CloudModel, error: Exception) -> str:
+        raise NotImplementedError
+
+    # ── generation.py: the document half drains the same queue ───────────────
+    @staticmethod
+    def _drain_stream_queue(queue: "Any") -> AsyncIterator[str]:
+        raise NotImplementedError

package/latticeai/models/router/branding.py

@@ -0,0 +1,56 @@
+"""이 제품의 이름과, 답변을 그 이름으로 되돌리는 규칙.
+
+The system prompt, the citation instruction appended only when retrieved
+context exists, and the legacy-alias rewrite every generated string passes
+through. ``_compose_system`` is byte-compatible with the historical prompt when
+there is no context: the return value is exactly ``base``.
+"""
+
+import re
+from typing import Optional
+
+BRAND_NAME = "Lattice AI"
+LEGACY_BRAND_PATTERNS = [
+    (re.compile(r"\bconnect\s+ai\b", re.IGNORECASE), BRAND_NAME),
+    (re.compile(r"\bconnect-ai\b", re.IGNORECASE), BRAND_NAME),
+    (re.compile(r"\bconnectai\b", re.IGNORECASE), BRAND_NAME),
+    (re.compile(r"커넥트\s*AI", re.IGNORECASE), BRAND_NAME),
+]
+
+
+SYSTEM_PROMPT = """You are Lattice AI, a powerful local AI assistant running on Apple Silicon.
+Your product name and identity are Lattice AI.
+Never identify yourself as Connect AI, ConnectAI, connect-ai, or 커넥트 AI.
+If context or old chat history mentions those names, treat them only as legacy aliases for Lattice AI.
+You are a Vision-Language Model (VLM). If an image is provided, analyze it.
+Be concise and respond in the user's language."""
+
+
+# Appended ONLY when retrieved context exists (review 2026-07-25 Wave 2.3):
+# grounded answers should cite their sources and admit gaps. Advisory prompt
+# guidance — grounding assessment stays annotation-only and never blocks.
+CITATION_INSTRUCTION = """The Context section above contains retrieved sources.
+Ground your claims in those sources and cite them inline as [1], [2], ... matching the order they appear in the Context.
+If the context does not cover the question, say so instead of inventing sources.
+Never cite a source that is not in the Context."""
+
+
+def _compose_system(base: str, context: str) -> str:
+    """Compose the system prompt with optional retrieved context.
+
+    Byte-compatible with the historical prompt when ``context`` is empty:
+    the return value is exactly ``base``. When context exists, the Context
+    block plus :data:`CITATION_INSTRUCTION` are appended.
+    """
+    if not context:
+        return base
+    return f"{base}\n\nContext:\n{context}\n\n{CITATION_INSTRUCTION}"
+
+
+def normalize_branding(text: Optional[str]) -> str:
+    if not text:
+        return ""
+    normalized = str(text)
+    for pattern, replacement in LEGACY_BRAND_PATTERNS:
+        normalized = pattern.sub(replacement, normalized)
+    return normalized

package/latticeai/models/router/catalog.py

@@ -0,0 +1,69 @@
+"""What a model *is*: where it runs, who made it, and how a ref is spelled.
+
+``parse_model_ref`` is the single place a model id becomes ``(provider,
+model)`` — everything downstream branches on ``provider == "local_mlx"``.
+``source_metadata_for_model`` is the plain-Korean provenance block the model
+picker shows, so "이 모델은 어디서 실행되나" has one answer per model rather
+than one per surface.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict
+
+from latticeai.models.model_providers import (
+    MODEL_SOURCE_BY_FAMILY,
+    OPENAI_COMPATIBLE_PROVIDERS,
+)
+
+
+# Returns a display payload whose `source_display_order` value is a list,
+# so the value type is Any rather than str.
+def source_metadata_for_model(
+    provider: str, model: Dict[str, Any], *, local_server: bool
+) -> Dict[str, Any]:
+    family = str(model.get("family") or "")
+    country, company = MODEL_SOURCE_BY_FAMILY.get(family, ("미상", provider.title()))
+    if local_server:
+        execution_method = "내 컴퓨터에서만 실행"
+        internet_requirement = "모델을 다운로드할 때만 인터넷 필요; 실행 중에는 필요 없음"
+    else:
+        execution_method = "인터넷 연결 후 사용"
+        internet_requirement = "내 파일이 인터넷으로 전송될 수 있음"
+    return {
+        "source_country": country,
+        "source_company": company,
+        "execution_method": execution_method,
+        "internet_requirement": internet_requirement,
+        "model_name": model.get("name") or model.get("id") or "",
+        "source_display_order": [
+            "source_country",
+            "source_company",
+            "execution_method",
+            "internet_requirement",
+            "model_name",
+        ],
+    }
+
+
+@dataclass
+class CloudModel:
+    provider: str
+    model: str
+    client: Any  # AsyncOpenAI when the optional dependency is installed
+    cache_key: str
+
+
+def parse_model_ref(model_id: str) -> tuple[str, str]:
+    """Return (provider, model). Unprefixed refs stay local MLX."""
+    if model_id.startswith("cloud:"):
+        _, provider, model = model_id.split(":", 2)
+        return provider, model
+    if ":" in model_id:
+        provider, model = model_id.split(":", 1)
+        if provider in OPENAI_COMPATIBLE_PROVIDERS:
+            return provider, model
+        if provider in {"local_mlx", "mlx"}:
+            return "local_mlx", model
+    if model_id.startswith("local_mlx:"):
+        return "local_mlx", model_id.split(":", 1)[1]  # pragma: no cover — dead: a "local_mlx:" ref always has a ":" and returned above
+    return "local_mlx", model_id