ltcai 9.0.0 → 9.1.0

package/latticeai/services/model_engines.py

@@ -1,8 +1,9 @@
 """Engine server management, pull, install and support logic extracted from model_runtime monolith.
 
 This module is the home for engine-specific server starting, model pulling and install flows.
-model_runtime re-exports the names to keep exact legacy globals, callers and monkeypatching working.
-Circular imports are avoided by late imports inside functions.
+``model_runtime`` exposes compatibility callables, while application configuration
+is passed explicitly through the bound runtime service. Circular imports are
+avoided by late imports inside functions.
 """
 from __future__ import annotations
 
@@ -21,8 +22,8 @@ import urllib.request
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
-from fastapi import HTTPException
-
+from latticeai.services.model_errors import ModelRuntimeError
+from latticeai.services.model_catalog import ENGINE_INSTALLERS
 from latticeai.services.process_audit import (
     CommandConfirmationError,
     append_process_audit_event,
@@ -148,7 +149,7 @@ def ensure_lmstudio_server() -> None:
 
     cli = find_lmstudio_cli()
     if not cli:
-        raise HTTPException(status_code=400, detail="LM Studio CLI를 찾지 못했습니다. LM Studio를 설치한 뒤 다시 시도하세요.")
+        raise ModelRuntimeError(status_code=400, detail="LM Studio CLI를 찾지 못했습니다. LM Studio를 설치한 뒤 다시 시도하세요.")
 
     try:
         subprocess.Popen(
@@ -158,7 +159,7 @@ def ensure_lmstudio_server() -> None:
             start_new_session=True,
         )
     except Exception as e:
-        raise HTTPException(status_code=500, detail=f"LM Studio 서버 시작 실패: {e}")
+        raise ModelRuntimeError(status_code=500, detail=f"LM Studio 서버 시작 실패: {e}")
 
     deadline = time.time() + 45
     while time.time() < deadline:
@@ -167,13 +168,13 @@ def ensure_lmstudio_server() -> None:
             return
         except Exception:
             time.sleep(1)
-    raise HTTPException(status_code=500, detail="LM Studio Local Server를 자동으로 시작하지 못했습니다.")
+    raise ModelRuntimeError(status_code=500, detail="LM Studio Local Server를 자동으로 시작하지 못했습니다.")
 
 
 def ensure_ollama_server() -> None:
     ollama = local_binary("ollama")
     if not ollama:
-        raise HTTPException(status_code=400, detail="Ollama가 설치되지 않았습니다.")
+        raise ModelRuntimeError(status_code=400, detail="Ollama가 설치되지 않았습니다.")
     try:
         probe = subprocess.run([ollama, "list"], capture_output=True, text=True, timeout=3, check=False)
         if probe.returncode == 0:
@@ -195,7 +196,7 @@ def ensure_ollama_server() -> None:
         except Exception:
             pass
         time.sleep(0.5)
-    raise HTTPException(status_code=500, detail="Ollama 서버를 자동으로 시작하지 못했습니다.")
+    raise ModelRuntimeError(status_code=500, detail="Ollama 서버를 자동으로 시작하지 못했습니다.")
 
 
 def get_openai_compatible_server_models(provider: str) -> List[str]:
@@ -262,7 +263,7 @@ def ensure_vllm_server(model_name: str) -> None:
     vllm_bin = vllm_executable()
     vllm_metal_py = vllm_metal_python()
     if not vllm_bin and not vllm_metal_py and importlib.util.find_spec("vllm") is None:
-        raise HTTPException(status_code=400, detail="vLLM runtime이 설치되지 않았습니다.")
+        raise ModelRuntimeError(status_code=400, detail="vLLM runtime이 설치되지 않았습니다.")
 
     local_dir = hf_model_dir(model_name)
     if not vllm_metal_py and not hf_model_ready(model_name, "vllm"):
@@ -276,7 +277,7 @@ def ensure_vllm_server(model_name: str) -> None:
         except subprocess.TimeoutExpired:
             running.kill()
     elif served_models:
-        raise HTTPException(status_code=409, detail="다른 vLLM 서버가 이미 실행 중입니다. 현재 서버를 종료한 뒤 다시 시도하세요.")
+        raise ModelRuntimeError(status_code=409, detail="다른 vLLM 서버가 이미 실행 중입니다. 현재 서버를 종료한 뒤 다시 시도하세요.")
 
     running = LOCAL_SERVER_PROCESSES.get("vllm")
     if running and running.poll() is None:
@@ -296,7 +297,7 @@ def ensure_vllm_server(model_name: str) -> None:
         start_new_session=True,
     )
     if not wait_for_openai_compatible_server("vllm", model_name, timeout=90):
-        raise HTTPException(status_code=500, detail="vLLM 서버가 모델을 자동 로드하지 못했습니다.")
+        raise ModelRuntimeError(status_code=500, detail="vLLM 서버가 모델을 자동 로드하지 못했습니다.")
 
 
 def ensure_llamacpp_server(model_name: str) -> None:
@@ -313,15 +314,15 @@ def ensure_llamacpp_server(model_name: str) -> None:
         except subprocess.TimeoutExpired:
             running.kill()
     elif served_models:
-        raise HTTPException(status_code=409, detail="다른 llama.cpp 서버가 이미 실행 중입니다. 현재 서버를 종료한 뒤 다시 시도하세요.")
+        raise ModelRuntimeError(status_code=409, detail="다른 llama.cpp 서버가 이미 실행 중입니다. 현재 서버를 종료한 뒤 다시 시도하세요.")
     if not shutil.which("llama-server"):
-        raise HTTPException(status_code=400, detail="llama.cpp가 설치되지 않았습니다.")
+        raise ModelRuntimeError(status_code=400, detail="llama.cpp가 설치되지 않았습니다.")
     if not hf_model_ready(model_name, "llamacpp"):
         download_hf_model(model_name, "llamacpp")
 
     gguf_files = sorted(hf_model_dir(model_name).rglob("*.gguf"))
     if not gguf_files:
-        raise HTTPException(status_code=500, detail="다운로드된 GGUF 파일을 찾지 못했습니다.")
+        raise ModelRuntimeError(status_code=500, detail="다운로드된 GGUF 파일을 찾지 못했습니다.")
 
     preferred = next((p for p in gguf_files if "q4_k_m" in p.name.lower()), None)
     model_file = preferred or gguf_files[0]
@@ -342,13 +343,13 @@ def ensure_llamacpp_server(model_name: str) -> None:
         start_new_session=True,
     )
     if not wait_for_openai_compatible_server("llamacpp", model_name, timeout=45):
-        raise HTTPException(status_code=500, detail="llama.cpp 서버가 모델을 자동 로드하지 못했습니다.")
+        raise ModelRuntimeError(status_code=500, detail="llama.cpp 서버가 모델을 자동 로드하지 못했습니다.")
 
 
 def pull_ollama_model_with_progress(model_name: str, progress_emit=None) -> Dict[str, object]:
     ollama = local_binary("ollama")
     if not ollama:
-        raise HTTPException(status_code=400, detail="Ollama가 설치되지 않았습니다.")
+        raise ModelRuntimeError(status_code=400, detail="Ollama가 설치되지 않았습니다.")
     if progress_emit:
         progress_emit(_progress_payload(
             "download",
@@ -402,7 +403,7 @@ def pull_ollama_model_with_progress(model_name: str, progress_emit=None) -> Dict
 
     if returncode != 0:
         tail = "\n".join(lines[-12:])
-        raise HTTPException(status_code=500, detail=tail[-2000:] or "Ollama 모델 다운로드 실패")
+        raise ModelRuntimeError(status_code=500, detail=tail[-2000:] or "Ollama 모델 다운로드 실패")
 
     if progress_emit:
         progress_emit(_progress_payload(
@@ -447,15 +448,17 @@ def engine_support_status(engine: str) -> Dict[str, object]:
     return {"supported": True, "reason": None}
 
 
-def _engine_install_command(engine: str) -> tuple[list[str], str, bool]:
-    from latticeai.services.model_runtime import BASE_DIR, ENGINE_INSTALLERS
-
+def _engine_install_command(
+    engine: str,
+    *,
+    base_dir: Optional[Path] = None,
+) -> tuple[list[str], str, bool]:
     if engine not in ENGINE_INSTALLERS:
-        raise HTTPException(status_code=400, detail="지원하지 않는 엔진입니다.")
+        raise ModelRuntimeError(status_code=400, detail="지원하지 않는 엔진입니다.")
     installer = ENGINE_INSTALLERS[engine]
     required_binary = installer.get("requires_binary")
     if required_binary and shutil.which(required_binary) is None:
-        raise HTTPException(status_code=400, detail=f"{required_binary}가 설치되어 있지 않아 자동 설치할 수 없습니다.")
+        raise ModelRuntimeError(status_code=400, detail=f"{required_binary}가 설치되어 있지 않아 자동 설치할 수 없습니다.")
     command = list(installer["command"])
 
     if engine == "vllm" and sys.platform == "darwin" and platform.machine() == "arm64":
@@ -469,11 +472,15 @@ def _engine_install_command(engine: str) -> tuple[list[str], str, bool]:
             "~/.venv-vllm-metal/bin/pip install vllm-metal",
         ]
     requires_admin = bool(command and command[0] in {"apt", "apt-get", "dnf", "pacman"})
-    return command, str(BASE_DIR), requires_admin
+    return command, str(base_dir or Path.cwd()), requires_admin
 
 
-def engine_install_plan(engine: str) -> Dict[str, Any]:
-    command, cwd, requires_admin = _engine_install_command(engine)
+def engine_install_plan(
+    engine: str,
+    *,
+    base_dir: Optional[Path] = None,
+) -> Dict[str, Any]:
+    command, cwd, requires_admin = _engine_install_command(engine, base_dir=base_dir)
     return command_plan(
         command,
         name=f"engine:{engine}",
@@ -484,16 +491,21 @@ def engine_install_plan(engine: str) -> Dict[str, Any]:
     )
 
 
-def install_engine(engine: str, confirmation_token: Optional[str] = None) -> Dict[str, Any]:
+def install_engine(
+    engine: str,
+    confirmation_token: Optional[str] = None,
+    *,
+    base_dir: Optional[Path] = None,
+) -> Dict[str, Any]:
     from latticeai.services.model_runtime import engine_installed
 
-    command, cwd, _requires_admin = _engine_install_command(engine)
-    plan = engine_install_plan(engine)
+    command, cwd, _requires_admin = _engine_install_command(engine, base_dir=base_dir)
+    plan = engine_install_plan(engine, base_dir=base_dir)
     try:
         require_command_confirmation(command, confirmation_token, cwd=cwd, purpose="engine_install")
     except CommandConfirmationError as exc:
         append_process_audit_event("engine_install", plan=plan, status="denied", error=str(exc))
-        raise HTTPException(
+        raise ModelRuntimeError(
             status_code=403,
             detail={
                 "status": "confirmation_required",
@@ -514,7 +526,7 @@ def install_engine(engine: str, confirmation_token: Optional[str] = None) -> Dic
         completed = subprocess.run(command, **run_kwargs)
     except subprocess.TimeoutExpired:
         append_process_audit_event("engine_install", plan=plan, status="timeout")
-        raise HTTPException(status_code=408, detail="엔진 설치 시간이 초과되었습니다.")
+        raise ModelRuntimeError(status_code=408, detail="엔진 설치 시간이 초과되었습니다.")
     except Exception as exc:
         append_process_audit_event("engine_install", plan=plan, status="error", error=str(exc))
         raise
@@ -576,6 +588,7 @@ async def _smoke_test_loaded_model(
     resolution: Any,
     *,
     api_key_override: Optional[str] = None,
+    model_router: Any = None,
 ) -> Dict[str, object]:
     """로드 직후 짧은 채팅 테스트를 돌려 ready_to_chat 여부를 판정한다.
 
@@ -585,7 +598,6 @@ async def _smoke_test_loaded_model(
     # late imports to avoid circular and keep lattice_brain/latticeai clean
     try:
         from latticeai.services.model_runtime import (
-            router as _router,
             _LOCAL_SMOKE_ENGINES,
             _SMOKE_PROMPT,
         )
@@ -599,6 +611,9 @@ async def _smoke_test_loaded_model(
     except Exception as e:
         return {"ok": False, "reason": f"smoke import failed: {e}", "skipped": True}
 
+    if model_router is None:
+        return {"ok": False, "reason": "model router is not configured", "skipped": True}
+
     if (getattr(resolution, "engine", "") or "").lower() not in _LOCAL_SMOKE_ENGINES:
         profile = _ensure_compat_profile(getattr(resolution, "load_id", ""), getattr(resolution, "engine", ""))
         return {
@@ -610,7 +625,7 @@ async def _smoke_test_loaded_model(
         }
     try:
         text = await asyncio.wait_for(
-            _router.generate(
+            model_router.generate(
                 _SMOKE_PROMPT,
                 context=None,
                 max_tokens=128,

package/latticeai/services/model_errors.py

@@ -0,0 +1,17 @@
+"""Transport-neutral model runtime failures."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ModelRuntimeError(RuntimeError):
+    """A model operation failure with an API-safe status and detail payload."""
+
+    def __init__(self, status_code: int, detail: Any):
+        self.status_code = int(status_code)
+        self.detail = detail
+        super().__init__(str(detail))
+
+
+__all__ = ["ModelRuntimeError"]

package/latticeai/services/model_loading.py

@@ -11,13 +11,15 @@ import logging
 import queue
 import subprocess
 import threading
+from functools import partial
 from pathlib import Path
-from typing import AsyncIterator, Dict, Optional
+from typing import Any, AsyncIterator, Dict, Optional
 
-from fastapi import HTTPException, Request
+from .model_errors import ModelRuntimeError
 
-# Late imports to avoid circulars during extraction
-def _get_model_runtime_deps():
+# Late imports to avoid circulars during extraction. The state argument is
+# mandatory so this module cannot fall back to ambient process configuration.
+def _get_model_runtime_deps(runtime_state: Any):
     from .model_runtime import (
         _download_allowed,
         _download_block,
@@ -33,10 +35,8 @@ def _get_model_runtime_deps():
         ensure_lmstudio_model,
         ensure_ollama_server,
         ensure_vllm_server,
-        get_current_user,
         get_lmstudio_models,
         get_ollama_pulled_models,
-        get_user_api_key,
         hf_model_dir,
         hf_model_ready,
         local_binary,
@@ -45,27 +45,26 @@ def _get_model_runtime_deps():
         normalize_local_model_request,
         parse_model_ref,
         pull_ollama_model_with_progress,
-        router,
     )
     return {
-        "_download_allowed": _download_allowed,
+        "_download_allowed": partial(_download_allowed, state=runtime_state),
         "_download_block": _download_block,
         "_engine_install_block": _engine_install_block,
         "_friendly_model_runtime_error": _friendly_model_runtime_error,
         "_ModelResolution": _ModelResolution,
         "_model_runtime_compatibility": _model_runtime_compatibility,
-        "_smoke_test_loaded_model": _smoke_test_loaded_model,
+        "_smoke_test_loaded_model": partial(_smoke_test_loaded_model, state=runtime_state),
         "download_hf_model": download_hf_model,
         "engine_installed": engine_installed,
-        "ensure_engine_ready": ensure_engine_ready,
+        "ensure_engine_ready": partial(ensure_engine_ready, state=runtime_state),
         "ensure_llamacpp_server": ensure_llamacpp_server,
         "ensure_lmstudio_model": ensure_lmstudio_model,
         "ensure_ollama_server": ensure_ollama_server,
         "ensure_vllm_server": ensure_vllm_server,
-        "get_current_user": get_current_user,
+        "get_current_user": runtime_state.get_current_user,
         "get_lmstudio_models": get_lmstudio_models,
         "get_ollama_pulled_models": get_ollama_pulled_models,
-        "get_user_api_key": get_user_api_key,
+        "get_user_api_key": runtime_state.get_user_api_key,
         "hf_model_dir": hf_model_dir,
         "hf_model_ready": hf_model_ready,
         "local_binary": local_binary,
@@ -74,23 +73,25 @@ def _get_model_runtime_deps():
         "normalize_local_model_request": normalize_local_model_request,
         "parse_model_ref": parse_model_ref,
         "pull_ollama_model_with_progress": pull_ollama_model_with_progress,
-        "router": router,
+        "router": runtime_state.router,
     }
 
 
 async def prepare_and_load_model(
     model_id: str,
-    request: Request,
+    request: Any,
     engine: Optional[str] = None,
     user_email: Optional[str] = None,
     adapter_path: Optional[str] = None,
     draft_model_id: Optional[str] = None,
     allow_download: bool = False,
+    *,
+    runtime_state: Any,
 ) -> Dict[str, object]:
-    deps = _get_model_runtime_deps()
+    deps = _get_model_runtime_deps(runtime_state)
     model_id = deps["normalize_local_model_request"](model_id, engine)
     if not model_id:
-        raise HTTPException(status_code=400, detail="모델 식별자가 비어 있습니다.")
+        raise ModelRuntimeError(status_code=400, detail="모델 식별자가 비어 있습니다.")
 
     resolution = deps["_ModelResolution"].from_request(
         model_id,
@@ -104,7 +105,7 @@ async def prepare_and_load_model(
         parsed_provider = "local_mlx"
     compatibility = deps["_model_runtime_compatibility"](parsed_model, engine=parsed_provider)
     if compatibility.get("supported") is False:
-        raise HTTPException(status_code=400, detail=compatibility)
+        raise ModelRuntimeError(status_code=400, detail=compatibility)
 
     local_engines = {"local_mlx", "ollama", "vllm", "lmstudio", "llamacpp"}
     install_result: Dict[str, object] = {}
@@ -125,7 +126,7 @@ async def prepare_and_load_model(
         deps["ensure_ollama_server"]()
         ollama = deps["local_binary"]("ollama")
         if not ollama:
-            raise HTTPException(status_code=400, detail="Ollama가 설치되지 않았습니다.")
+            raise ModelRuntimeError(status_code=400, detail="Ollama가 설치되지 않았습니다.")
         if parsed_model not in deps["get_ollama_pulled_models"]():
             if not deps["_download_allowed"](allow_download):
                 deps["_download_block"](parsed_provider, parsed_model)
@@ -137,7 +138,7 @@ async def prepare_and_load_model(
                 check=False,
             )
             if completed.returncode != 0:
-                raise HTTPException(status_code=500, detail=completed.stderr[-2000:] or "Ollama 모델 다운로드 실패")
+                raise ModelRuntimeError(status_code=500, detail=completed.stderr[-2000:] or "Ollama 모델 다운로드 실패")
             download_result = {"provider": "ollama", "model": parsed_model, "returncode": completed.returncode}
     elif parsed_provider == "vllm":
         if not deps["hf_model_ready"](parsed_model, "vllm") and not deps["_download_allowed"](allow_download):
@@ -210,22 +211,24 @@ def sse_event(event: str, data: Dict[str, object]) -> str:
 
 async def prepare_and_load_model_stream(
     model_id: str,
-    request: Request,
+    request: Any,
     engine: Optional[str] = None,
     user_email: Optional[str] = None,
     allow_download: bool = False,
+    *,
+    runtime_state: Any,
 ) -> AsyncIterator[str]:
-    deps = _get_model_runtime_deps()
+    deps = _get_model_runtime_deps(runtime_state)
     model_id = deps["normalize_local_model_request"](model_id, engine)
     if not model_id:
-        raise HTTPException(status_code=400, detail="모델 식별자가 비어 있습니다.")
+        raise ModelRuntimeError(status_code=400, detail="모델 식별자가 비어 있습니다.")
 
     parsed_provider, parsed_model = deps["parse_model_ref"](model_id)
     if parsed_provider == "mlx":
         parsed_provider = "local_mlx"
     compatibility = deps["_model_runtime_compatibility"](parsed_model, engine=parsed_provider)
     if compatibility.get("supported") is False:
-        raise HTTPException(status_code=400, detail=compatibility)
+        raise ModelRuntimeError(status_code=400, detail=compatibility)
 
     work_queue: "queue.Queue[Dict[str, object]]" = queue.Queue()
     work_result: Dict[str, object] = {}
@@ -385,7 +388,7 @@ async def prepare_and_load_model_stream(
                 "download_result": download_result,
             })
             work_queue.put({"kind": "done"})
-        except HTTPException as exc:
+        except ModelRuntimeError as exc:
             work_queue.put({"kind": "error", "status_code": exc.status_code, "detail": exc.detail})
         except Exception as exc:
             logging.exception("model prepare stream worker failed")
@@ -404,7 +407,7 @@ async def prepare_and_load_model_stream(
         if kind == "progress":
             yield sse_event("progress", item["data"])
         elif kind == "error":
-            raise HTTPException(
+            raise ModelRuntimeError(
                 status_code=int(item.get("status_code") or 500),
                 detail=item.get("detail") or "모델 준비에 실패했습니다.",
             )