ltcai 0.1.11 → 0.1.16

package/README.md

@@ -4,13 +4,34 @@
 
 Apple Silicon MLX 로컬 추론 · OpenAI/Groq/OpenRouter 클라우드 모델 · Graph RAG · 멀티스텝 에이전트 워크플로
 
-[![PyPI](https://img.shields.io/pypi/v/ltcai)](https://pypi.org/project/ltcai/)
-[![npm](https://img.shields.io/npm/v/ltcai)](https://www.npmjs.com/package/ltcai)
-[![VS Code](https://img.shields.io/visual-studio-marketplace/v/parktaesoo.ltcai)](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/ltcai?label=pypi)](https://pypi.org/project/ltcai/)
+[![npm](https://img.shields.io/npm/v/ltcai?label=npm)](https://www.npmjs.com/package/ltcai)
+[![VS Code Marketplace](https://vsmarketplacebadges.dev/version/parktaesoo.ltcai.svg)](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai)
+[![Open VSX](https://img.shields.io/open-vsx/v/parktaesoo/ltcai?label=Open%20VSX)](https://open-vsx.org/extension/parktaesoo/ltcai)
+[![License](https://img.shields.io/github/license/TaeSooPark-PTS/LatticeAI)](./LICENSE)
 
-<!-- 스크린샷 / GIF — docs/demo.gif 또는 스크린샷으로 교체하세요 -->
-<!-- ![Lattice AI demo](docs/demo.gif) -->
+Lattice AI는 개인 개발자가 로컬 모델, 클라우드 모델, 에이전트 툴링, 코드 에디터 연동을 하나의 워크스페이스로 운영할 수 있게 만든 서버입니다.
+
+### 현재 배포 버전
+
+- `PyPI`: `ltcai==0.1.16`
+- `npm`: `ltcai@0.1.16`
+- `VS Code Marketplace`: `parktaesoo.ltcai@0.1.16`
+- `Open VSX`: `parktaesoo.ltcai@0.1.16`
+
+### 왜 Lattice AI인가
+
+- **하나의 서버, 여러 인터페이스**: 웹 UI, VS Code/Cursor 확장, Telegram 봇, MCP 도구를 한 번에 연결합니다.
+- **로컬 우선 + 클라우드 선택**: Apple Silicon MLX 로컬 모델과 OpenAI 호환 클라우드 모델을 같은 UX로 다룹니다.
+- **실전형 에이전트 워크플로**: 파일 편집, grep, todo, 터미널 도구를 묶어 멀티스텝 작업을 수행합니다.
+
+### 빠른 링크
+
+- [설치 & 첫 실행](#설치--첫-실행-30초)
+- [퍼블릭 배포 가이드](./docs/public-deploy.md)
+- [보안 모델](./docs/security-model.md)
+- [아키텍처](./docs/architecture.md)
+- [변경 이력](./docs/CHANGELOG.md)
 
 ---
 
@@ -26,11 +47,22 @@ pip install "ltcai[local]"
 # npm (자동 Python 환경 구성)
 npm install -g ltcai
 
-# 서버 실행
+# 서버 실행 (로컬)
 LTCAI
 # → http://localhost:4825
+
+# 외부에서 접속 가능하게 실행 (Cloudflare 터널 자동 개설)
+LTCAI --tunnel
+# → http://localhost:4825
+# → https://xxxx.trycloudflare.com  ← 어디서든 접속 가능한 공개 URL
 ```
 
+**`--tunnel` 동작 방식:**
+- cloudflared가 없으면 자동 다운로드 (계정 불필요)
+- 서버를 `0.0.0.0`에 바인딩하고 Cloudflare 무료 터널로 HTTPS 공개 URL 발급
+- `LATTICEAI_TELEGRAM_BOT_TOKEN` + `LATTICEAI_TELEGRAM_CHAT_ID` 환경변수가 있으면 시작 시 Telegram으로 URL 자동 전송
+- 서버 종료 시 터널도 함께 종료
+
 **설치 확인:**
 
 ```
@@ -214,6 +246,15 @@ docker run --rm -p 4825:4825 \
 | VS Code / Cursor | [marketplace.visualstudio.com](https://marketplace.visualstudio.com/items?itemName=parktaesoo.ltcai) |
 | Antigravity / VSCodium | [open-vsx.org](https://open-vsx.org/extension/parktaesoo/ltcai) |
 
+### 릴리스 체크
+
+`0.1.16 릴리스는 아래 네 채널을 동일 버전으로 맞춥니다.
+
+- `npm`
+- `PyPI`
+- `VS Code Marketplace`
+- `Open VSX`
+
 ### 수동 설치 (VSIX)
 
 ```bash
@@ -318,7 +359,7 @@ launchctl load ~/Library/LaunchAgents/com.ltcai.plist
 
 ## 릴리스 노트
 
-현재 버전: **0.1.11** — 자세한 변경 이력은 [docs/CHANGELOG.md](docs/CHANGELOG.md) 참고.
+현재 버전: **0.1.16** — 자세한 변경 이력은 [docs/CHANGELOG.md](docs/CHANGELOG.md) 참고.
 
 ## 라이선스
 

package/docs/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## [0.1.16] - 2026-05-22
+
+### First-user admin bootstrap
+
+- 서버를 처음 설치하고 가입하는 첫 번째 사용자가 자동으로 **admin** 권한 획득
+- 이후 가입자는 기존과 동일하게 `user` 역할
+- `/register` 응답에 `role` 필드 추가 — 클라이언트가 첫 가입 여부 확인 가능
+
+### Release
+- 배포 버전을 `0.1.16`으로 상향
+
+## [0.1.15] - 2026-05-22
+
+### Security hardening
+
+- `LTCAI --tunnel` 실행 시 `LATTICEAI_REQUIRE_AUTH=true` 자동 강제 — 터널로 공개된 서버에 로그인 없이 접근 불가
+- `/register` IP당 시간당 5회 rate limit
+- `/login` IP당 5분당 10회 rate limit (brute force 방지)
+- Cloudflare 터널 통과 시 `CF-Connecting-IP` 헤더로 실제 클라이언트 IP 추출
+- `LATTICEAI_OPEN_REGISTRATION=false` 설정 시 회원가입 완전 차단 (관리자 직접 추가만 허용)
+
+### Release
+- 배포 버전을 `0.1.15`로 상향
+
+## [0.1.14] - 2026-05-22
+
+### `--tunnel` flag — 누구나 자기 PC를 서버로
+
+- `LTCAI --tunnel` 한 줄로 Cloudflare 무료 터널 자동 개설
+- cloudflared 바이너리가 없으면 GitHub에서 자동 다운로드 (`~/.latticeai/bin/`)
+- macOS arm64/amd64, Linux arm64/amd64, Windows amd64 지원
+- 터널 URL을 배너에 출력 + `LATTICEAI_TELEGRAM_BOT_TOKEN` / `LATTICEAI_TELEGRAM_CHAT_ID` 설정 시 Telegram 자동 알림
+- `--tunnel` 지정 시 host 자동으로 `0.0.0.0`, CORS 네트워크 허용으로 전환
+
+### Release
+- 배포 버전을 `0.1.14`로 상향
+- 대상 채널: `npm`, `PyPI`, `VS Code Marketplace`, `Open VSX`
+
+## [0.1.13] - 2026-05-22
+
+### Code quality & efficiency
+
+- `HF_MODELS_ROOT` / `hf_model_dir` 중복 정의 제거 — `llm_router.py` 단일 소스로 통합, `server.py`에서 import
+- `_looks_like_hf_model_dir` 가중치 파일 체크를 `.safetensors` / `.bin`으로 일치 — `.gguf`를 MLX 경로에서 잘못 허용하던 버그 수정
+- `vllm_executable()` `shutil.which` 이중 호출 → 변수 캐시
+- `ensure_lmstudio_model()` `_find_lmstudio_model_key` 이중 호출 → `found_key` 변수로 캐시
+- `engine_support_status` 3단계 중첩 조건 → `is_apple_silicon` 플래그로 평탄화
+- `ensure_llamacpp_server` 동일 프로세스 이중 `terminate()` 블록 → 단일 블록 (vllm 패턴과 통일)
+- `ensure_vllm_server` 37줄 중첩 삼항 커맨드 빌더 → `if/elif/else` + `_host_args` 공통화
+- `except: pass` → `except Exception: pass` (KeyboardInterrupt 노출)
+- `knowledge_graph.py` 엣지 순회 루프 두 번 (`degree_map` + `topic_metrics`) → 단일 루프로 병합
+
+### Performance & correctness
+
+- `get_lmstudio_models()` TTL 캐시(10초) 추가 — `/health`, `/engines`, `/models` 매 요청마다 LM Studio HTTP 프로브하던 문제 해결, 서버 미응답 시 마지막 캐시 반환
+- `/health`, `/engines`, `/models` 엔드포인트에서 `engine_status()` 호출을 `asyncio.to_thread()`로 오프로드 — LM Studio 최대 45초, ollama subprocess 블로킹이 이벤트 루프를 점유하던 문제 해결
+- 앱 종료 시 `LOCAL_SERVER_PROCESSES` (vLLM, llama.cpp) 자식 프로세스 정리 — GPU 메모리 고아 프로세스 누수 수정
+
+### Release
+- 배포 버전을 `0.1.13`으로 상향
+- 대상 채널: `npm`, `PyPI`, `VS Code Marketplace`, `Open VSX`
+
+## [0.1.12] - 2026-05-22
+
+### Local engine install / load flow
+- `vLLM` 설치 경로를 macOS용 `Python 3.12 + vllm-metal` 흐름으로 교체
+- `LM Studio` 번들 `lms` CLI와 native API를 사용해 서버 시작, 모델 다운로드, 모델 로드를 자동화
+- `llama.cpp`는 선택한 GGUF를 alias와 함께 OpenAI 호환 서버로 직접 로드하도록 정리
+- 모델 패널의 `설치` / `다운로드 후 자동 로드` 흐름이 실제 `prepare_and_load_model()` 경로로 수렴되도록 정리
+
+### Verified
+- 최소 테스트 모델 기준 실사용 검증 완료
+- `vLLM`: `Qwen/Qwen2.5-0.5B-Instruct-AWQ`
+- `LM Studio`: `https://huggingface.co/lmstudio-community/Qwen2.5-0.5B-Instruct-GGUF`
+- `llama.cpp`: `lmstudio-community/Qwen2.5-0.5B-Instruct-GGUF`
+
+### Release
+- 배포 버전을 `0.1.12`로 상향
+- 대상 채널: `npm`, `PyPI`, `VS Code Marketplace`, `Open VSX`
+
 ## [0.1.11] - 2026-05-21
 
 ### Agent state machine (renamed + cleaned up)

package/knowledge_graph.py

@@ -9,6 +9,7 @@ the ingestion contract.
 import hashlib
 import json
 import logging
+import math
 import re
 import shutil
 import sqlite3
@@ -25,6 +26,25 @@ def _now() -> str:
     return datetime.now().isoformat()
 
 
+def _parse_iso(raw: Optional[str]) -> Optional[datetime]:
+    if not raw:
+        return None
+    try:
+        return datetime.fromisoformat(str(raw))
+    except (TypeError, ValueError):
+        return None
+
+
+def _recency_score(updated_at: Optional[str], *, now: Optional[datetime] = None, half_life_days: float = 14.0) -> float:
+    stamp = _parse_iso(updated_at)
+    if not stamp:
+        return 0.0
+    now = now or datetime.now()
+    age_days = max(0.0, (now - stamp).total_seconds() / 86400.0)
+    decay = math.log(2) / max(0.1, half_life_days)
+    return math.exp(-decay * age_days)
+
+
 def _json(data: Optional[Dict[str, Any]]) -> str:
     return json.dumps(data or {}, ensure_ascii=False, sort_keys=True)
 
@@ -587,28 +607,115 @@ class KnowledgeGraphStore:
                     "title": row["title"],
                     "summary": row["summary"],
                     "metadata": _safe_loads(row["metadata_json"]),
+                    "updated_at": row["updated_at"],
                 }
                 for row in conn.execute(
-                    "SELECT id, type, title, summary, metadata_json FROM nodes WHERE type != 'Chunk' ORDER BY updated_at DESC LIMIT ?",
+                    "SELECT id, type, title, summary, metadata_json, updated_at FROM nodes WHERE type != 'Chunk' ORDER BY updated_at DESC LIMIT ?",
                     (limit,),
                 )
             ]
             node_ids = {node["id"] for node in nodes}
-            edges = [
-                {
-                    "id": row["id"],
-                    "from": row["from_node"],
-                    "to": row["to_node"],
-                    "type": row["type"],
-                    "weight": row["weight"],
-                    "metadata": _safe_loads(row["metadata_json"]),
-                }
-                for row in conn.execute(
-                    "SELECT id, from_node, to_node, type, weight, metadata_json FROM edges ORDER BY created_at DESC LIMIT ?",
-                    (limit * 3,),
+            edges: List[Dict[str, Any]] = []
+            if node_ids:
+                edge_rows = conn.execute(
+                    """
+                    SELECT id, from_node, to_node, type, weight, metadata_json
+                    FROM edges
+                    WHERE from_node IN (
+                        SELECT id
+                        FROM nodes
+                        WHERE type != 'Chunk'
+                        ORDER BY updated_at DESC
+                        LIMIT ?
+                    )
+                    AND to_node IN (
+                        SELECT id
+                        FROM nodes
+                        WHERE type != 'Chunk'
+                        ORDER BY updated_at DESC
+                        LIMIT ?
+                    )
+                    ORDER BY created_at DESC
+                    """,
+                    (limit, limit),
+                ).fetchall()
+                edges = [
+                    {
+                        "id": row["id"],
+                        "from": row["from_node"],
+                        "to": row["to_node"],
+                        "type": row["type"],
+                        "weight": row["weight"],
+                        "metadata": _safe_loads(row["metadata_json"]),
+                    }
+                    for row in edge_rows
+                ]
+
+        degree_map: Dict[str, int] = {}
+        now = datetime.now()
+        node_by_id = {node["id"]: node for node in nodes}
+        topic_metrics: Dict[str, Dict[str, Any]] = {}
+
+        for edge in edges:
+            degree_map[edge["from"]] = degree_map.get(edge["from"], 0) + 1
+            degree_map[edge["to"]] = degree_map.get(edge["to"], 0) + 1
+            from_node = node_by_id.get(edge["from"])
+            to_node = node_by_id.get(edge["to"])
+            if not from_node or not to_node:
+                continue
+            for topic_node, other_node in ((from_node, to_node), (to_node, from_node)):
+                if topic_node["type"] != "Topic":
+                    continue
+                metrics = topic_metrics.setdefault(topic_node["id"], {
+                    "mention_count": 0.0,
+                    "conversation_ids": set(),
+                })
+                if edge["type"] in {"mentions", "discusses"}:
+                    metrics["mention_count"] += max(0.5, float(edge.get("weight") or 1.0))
+                other_meta = other_node.get("metadata") or {}
+                conversation_id = other_meta.get("conversation_id")
+                if other_node["type"] == "Conversation":
+                    conversation_id = other_node["id"]
+                if conversation_id:
+                    metrics["conversation_ids"].add(str(conversation_id))
+
+        type_max_raw: Dict[str, float] = {}
+        for node in nodes:
+            degree = degree_map.get(node["id"], 0)
+            recency = _recency_score(node.get("updated_at"), now=now)
+            metrics = {
+                "degree": degree,
+                "recency_score": round(recency, 4),
+            }
+            if node["type"] == "Topic":
+                topic_stat = topic_metrics.get(node["id"], {})
+                mention_count = float(topic_stat.get("mention_count") or 0.0)
+                conversation_count = len(topic_stat.get("conversation_ids") or ())
+                raw_importance = (
+                    math.log1p(mention_count) * 2.8
+                    + math.log1p(conversation_count) * 2.2
+                    + recency * 1.4
+                    + math.sqrt(max(0, degree)) * 0.45
                 )
-                if row["from_node"] in node_ids and row["to_node"] in node_ids
-            ]
+                metrics.update({
+                    "mention_count": round(mention_count, 2),
+                    "conversation_count": conversation_count,
+                })
+            else:
+                raw_importance = math.log1p(max(0, degree)) * 1.4 + recency * 0.9
+
+            metrics["importance_raw"] = round(raw_importance, 4)
+            node["importance"] = round(raw_importance, 4)
+            node["_raw_importance"] = raw_importance
+            node["metadata"] = {**(node.get("metadata") or {}), "graph_metrics": metrics}
+            type_max_raw[node["type"]] = max(type_max_raw.get(node["type"], 0.0), raw_importance)
+
+        for node in nodes:
+            max_raw = max(type_max_raw.get(node["type"], 0.0), 0.0001)
+            importance_norm = min(1.0, (node.get("_raw_importance") or 0.0) / max_raw)
+            node["importance_norm"] = round(importance_norm, 4)
+            node["metadata"]["graph_metrics"]["importance_norm"] = node["importance_norm"]
+            node.pop("_raw_importance", None)
         return {"nodes": nodes, "edges": edges}
 
     def search(self, query: str, limit: int = 30) -> Dict[str, Any]:
@@ -669,6 +776,7 @@ class KnowledgeGraphStore:
                     "title": row["title"],
                     "summary": row["summary"],
                     "metadata": _safe_loads(row["metadata_json"]),
+                    "updated_at": row["updated_at"],
                 }
                 for row in rows
             ],

package/llm_router.py

@@ -10,6 +10,7 @@ import os
 import re
 import time
 from dataclasses import dataclass
+from pathlib import Path
 
 # Set MLX_VLM_DRAFT_KIND to 'mtp' to enable the Gemma 4 assistant MTP drafter.
 os.environ["MLX_VLM_DRAFT_KIND"] = "mtp"
@@ -167,10 +168,59 @@ def parse_model_ref(model_id: str) -> tuple[str, str]:
         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]
     return "local_mlx", model_id
 
+HF_MODELS_ROOT = Path.home() / ".latticeai" / "hf-models"
+
+def hf_model_dir(repo_id: str) -> Path:
+    return HF_MODELS_ROOT / repo_id.replace("/", "__")
+
+def _looks_like_hf_model_dir(path: Path) -> bool:
+    if not path.exists() or not path.is_dir():
+        return False
+    has_config = (path / "config.json").exists()
+    has_weights = any(path.glob("*.safetensors")) or any(path.glob("*.bin"))
+    has_tokenizer = (
+        (path / "tokenizer.json").exists()
+        or (path / "tokenizer.model").exists()
+        or (path / "tokenizer_config.json").exists()
+    )
+    return has_config and has_weights and has_tokenizer
+
+def _resolve_local_hf_model(model_id: str) -> str:
+    explicit_path = Path(model_id).expanduser()
+    if explicit_path.exists():
+        return str(explicit_path)
+    local_dir = hf_model_dir(model_id)
+    if _looks_like_hf_model_dir(local_dir):
+        return str(local_dir)
+    return model_id
+
+def ensure_mlx_runtime() -> None:
+    global mx, lm_load, vlm_load, VLM_AVAILABLE
+    if mx is not None and lm_load is not None:
+        return
+    try:
+        import mlx.core as mlx_core
+        from mlx_lm import load as mlx_lm_load
+
+        mx = mlx_core
+        lm_load = mlx_lm_load
+        try:
+            from mlx_vlm import load as mlx_vlm_load
+            vlm_load = mlx_vlm_load
+            VLM_AVAILABLE = True
+        except Exception:
+            vlm_load = None
+            VLM_AVAILABLE = False
+        mx.set_default_device(mx.gpu)
+    except Exception as e:
+        raise RuntimeError(f"MLX runtime is not available after install: {e}") from e
+
 class LLMRouter:
     def __init__(self):
         self._cache: Dict[str, Tuple] = {}
@@ -262,6 +312,7 @@ class LLMRouter:
         if provider != "local_mlx":
             return self._load_cloud_model(provider, provider_model, api_key_override=api_key_override, owner=owner)
 
+        ensure_mlx_runtime()
         if mx is None or lm_load is None:
             raise RuntimeError("MLX is not available in this process. Run on Apple Silicon with Metal access.")
 
@@ -274,6 +325,8 @@ class LLMRouter:
         self._enforce_local_model_limit(cache_key)
         print(f"⏳ Loading Gemma 4 Stack: {cache_key}...")
         loop = asyncio.get_event_loop()
+        target_model_id = _resolve_local_hf_model(model_id)
+        target_draft_model_id = _resolve_local_hf_model(draft_model_id) if draft_model_id else None
         
         def _load():
             mx.set_default_device(mx.gpu)
@@ -281,20 +334,20 @@ class LLMRouter:
             
             # 1. Target 로드 (Gemma 4는 항상 vlm_load 사용)
             if is_gemma4 and VLM_AVAILABLE:
-                print(f"🔄 Loading Target (VLM Mode): {model_id}...")
-                model, tokenizer = vlm_load(model_id)
+                print(f"🔄 Loading Target (VLM Mode): {target_model_id}...")
+                model, tokenizer = vlm_load(target_model_id)
             else:
-                print(f"🔄 Loading Target (LM Mode): {model_id}...")
-                model, tokenizer = lm_load(model_id)
+                print(f"🔄 Loading Target (LM Mode): {target_model_id}...")
+                model, tokenizer = lm_load(target_model_id)
 
             # 2. Draft 로드 (Gemma 4는 항상 vlm_load 사용)
             draft_model = None
-            if draft_model_id:
-                print(f"🔄 Loading Assistant (VLM Mode): {draft_model_id}...")
+            if target_draft_model_id:
+                print(f"🔄 Loading Assistant (VLM Mode): {target_draft_model_id}...")
                 if is_gemma4 and VLM_AVAILABLE:
-                    draft_model, _ = vlm_load(draft_model_id)
+                    draft_model, _ = vlm_load(target_draft_model_id)
                 else:
-                    draft_model, _ = lm_load(draft_model_id)
+                    draft_model, _ = lm_load(target_draft_model_id)
                 print(f"✅ Assistant Ready.")
 
             return model, tokenizer, draft_model
@@ -374,6 +427,18 @@ class LLMRouter:
     def _is_cloud_current(self) -> bool:
         return bool(self._current and isinstance(self._cache.get(self._current), CloudModel))
 
+    def _local_server_error_hint(self, cloud: CloudModel, error: Exception) -> str:
+        raw = str(error)
+        if cloud.provider == "lmstudio":
+            base_url = os.getenv("LMSTUDIO_BASE_URL") or OPENAI_COMPATIBLE_PROVIDERS["lmstudio"]["base_url"]
+            return (
+                f"LM Studio 연결 실패: {raw}\n\n"
+                f"- LM Studio의 Developer/Local Server를 켜고 모델을 로드했는지 확인하세요.\n"
+                f"- Lattice가 보는 주소는 {base_url} 입니다. 포트가 다르면 LMSTUDIO_BASE_URL을 맞춰주세요.\n"
+                f"- 모델 선택창에는 LM Studio /v1/models에서 감지된 모델만 표시됩니다."
+            )
+        return raw
+
     def _build_prompt(self, message: str, context: Optional[str], tokenizer) -> str:
         system = SYSTEM_PROMPT
         context = normalize_branding(context)
@@ -382,7 +447,7 @@ class LLMRouter:
             try:
                 msgs = [{"role": "system", "content": system}, {"role": "user", "content": message}]
                 return tokenizer.apply_chat_template(msgs, tokenize=False, add_generation_prompt=True)
-            except: pass
+            except Exception: pass
         return f"<|im_start|>system\n{system}<|im_end|>\n<|im_start|>user\n{message}<|im_end|>\n<|im_start|>assistant\n"
 
     def _build_vlm_prompt(self, model, processor, message: str, context: Optional[str], num_images: int) -> str:
@@ -445,15 +510,18 @@ class LLMRouter:
         context = normalize_branding(context)
         if context:
             system += f"\n\nContext:\n{context}"
-        response = await cloud.client.chat.completions.create(
-            model=cloud.model,
-            messages=[
-                {"role": "system", "content": system},
-                {"role": "user", "content": message},
-            ],
-            max_tokens=max_tokens,
-            temperature=temperature,
-        )
+        try:
+            response = await cloud.client.chat.completions.create(
+                model=cloud.model,
+                messages=[
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": message},
+                ],
+                max_tokens=max_tokens,
+                temperature=temperature,
+            )
+        except Exception as e:
+            raise RuntimeError(self._local_server_error_hint(cloud, e)) from e
         return normalize_branding(response.choices[0].message.content or "")
 
     async def stream_generate(self, message: str, context: Optional[str] = None, max_tokens: int = 4096, temperature: float = 0.2, image_data: Optional[str] = None) -> AsyncIterator[str]:
@@ -508,16 +576,20 @@ class LLMRouter:
         context = normalize_branding(context)
         if context:
             system += f"\n\nContext:\n{context}"
-        stream = await cloud.client.chat.completions.create(
-            model=cloud.model,
-            messages=[
-                {"role": "system", "content": system},
-                {"role": "user", "content": message},
-            ],
-            max_tokens=max_tokens,
-            temperature=temperature,
-            stream=True,
-        )
+        try:
+            stream = await cloud.client.chat.completions.create(
+                model=cloud.model,
+                messages=[
+                    {"role": "system", "content": system},
+                    {"role": "user", "content": message},
+                ],
+                max_tokens=max_tokens,
+                temperature=temperature,
+                stream=True,
+            )
+        except Exception as e:
+            yield f"⚠️ {self._local_server_error_hint(cloud, e)}"
+            return
         async for event in stream:
             if not event.choices:
                 continue