ltcai 4.4.0 → 4.6.0

package/lattice_brain/__init__.py

@@ -26,7 +26,7 @@ from .storage import (
     storage_from_env,
 )
 
-__version__ = "4.4.0"
+__version__ = "4.6.0"
 
 __all__ = [
     "AgentRuntime",

package/lattice_brain/runtime/multi_agent.py

@@ -14,7 +14,7 @@ from datetime import datetime
 from typing import Any, Callable, Dict, List, Optional
 
 
-MULTI_AGENT_VERSION = "4.4.0"
+MULTI_AGENT_VERSION = "4.6.0"
 
 AGENT_ROLES = ("researcher", "planner", "executor", "reviewer", "release")
 CORE_PIPELINE = ("planner", "executor", "reviewer")

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "4.4.0"
+__version__ = "4.6.0"

package/latticeai/api/models.py

@@ -135,6 +135,8 @@ def create_models_router(
         loaded_ids: Optional[List[str]] = None,
         current_id: Optional[str] = None,
     ) -> List[Dict[str, object]]:
+        from latticeai.core.model_compat import model_runtime_compatibility
+
         engine_lookup = {str(engine.get("id") or ""): engine for engine in engines or []}
         model_lookup: Dict[str, Dict[str, object]] = {}
         for engine in engines or []:
@@ -147,30 +149,93 @@ def create_models_router(
         for item in items:
             short_id = str(item["id"]).lower()
             aliases = MODEL_ENGINE_ALIASES.get(short_id) or {}
-            options: List[Dict[str, str]] = []
+            options: List[Dict[str, object]] = []
             for engine_name in ("local_mlx", "ollama", "lmstudio", "llamacpp", "vllm"):
                 real = aliases.get(engine_name)
                 if not real:
                     continue
+                load_id = real if engine_name == "local_mlx" else f"{engine_name}:{real}"
+                engine_info = engine_lookup.get(engine_name) or {}
+                model_info = model_lookup.get(load_id) or model_lookup.get(real) or {}
+                option_loaded = load_id in loaded or real in loaded or current_id in {load_id, real}
+                option_runtime = model_runtime_compatibility(load_id, engine=engine_name)
+                option_supported = option_runtime.get("supported") is not False
+                option_pulled = bool(model_info.get("pulled"))
+                option_download_required = bool(item.get("pullable", True) and not option_pulled and not option_loaded)
                 options.append({
                     "engine": engine_name,
                     "model_id": real,
-                    "load_id": real if engine_name == "local_mlx" else f"{engine_name}:{real}",
+                    "load_id": load_id,
+                    "installed": bool(engine_info.get("installed")),
+                    "pulled": option_pulled,
+                    "loaded": option_loaded,
+                    "download_required": option_download_required,
+                    "runtime_compatibility": option_runtime,
+                    "runtime_supported": option_supported,
+                    "runtime_label": str(option_runtime.get("preferred_runtime") or engine_info.get("name") or engine_name),
                 })
             if not options:
-                options.append({"engine": "local_mlx", "model_id": item["id"], "load_id": item["id"]})
-            recommended_engine = options[0]["engine"]
-            load_id = options[0]["load_id"]
-            engine_info = engine_lookup.get(recommended_engine) or {}
-            model_info = model_lookup.get(load_id) or model_lookup.get(str(item["id"])) or {}
-            pulled = bool(model_info.get("pulled"))
-            is_loaded = load_id in loaded or str(item["id"]) in loaded or current_id in {load_id, str(item["id"])}
-            engine_installed = bool(engine_info.get("installed"))
+                raw_id = str(item["id"])
+                engine_info = engine_lookup.get("local_mlx") or {}
+                model_info = model_lookup.get(raw_id) or {}
+                option_loaded = raw_id in loaded or current_id == raw_id
+                option_pulled = bool(model_info.get("pulled"))
+                runtime_compatibility = model_runtime_compatibility(str(item["id"]), engine="local_mlx")
+                options.append({
+                    "engine": "local_mlx",
+                    "model_id": item["id"],
+                    "load_id": item["id"],
+                    "installed": bool(engine_info.get("installed")),
+                    "pulled": option_pulled,
+                    "loaded": option_loaded,
+                    "download_required": bool(item.get("pullable", True) and not option_pulled and not option_loaded),
+                    "runtime_compatibility": runtime_compatibility,
+                    "runtime_supported": runtime_compatibility.get("supported") is not False,
+                    "runtime_label": str(runtime_compatibility.get("preferred_runtime") or "MLX"),
+                })
+
+            def option_rank(option: Dict[str, object]) -> tuple[int, int, int, int]:
+                runtime_supported = bool(option.get("runtime_supported"))
+                installed = bool(option.get("installed"))
+                loaded_option = bool(option.get("loaded"))
+                ready_without_download = installed and not bool(option.get("download_required"))
+                return (
+                    0 if runtime_supported else 1,
+                    0 if loaded_option or ready_without_download else 1,
+                    0 if installed else 1,
+                    ["local_mlx", "ollama", "lmstudio", "llamacpp", "vllm"].index(str(option.get("engine") or "vllm")),
+                )
+
+            primary_option = options[0]
+            primary_compatibility = dict(primary_option.get("runtime_compatibility") or {})
+            hard_primary_statuses = {
+                "runtime_update_needed",
+                "unsupported_format",
+                "repair_model",
+                "incomplete_download",
+            }
+            selected_option = (
+                primary_option
+                if primary_compatibility.get("supported") is False
+                and primary_compatibility.get("status") in hard_primary_statuses
+                else min(options, key=option_rank)
+            )
+            recommended_engine = str(selected_option["engine"])
+            load_id = str(selected_option["load_id"])
+            model_info = model_lookup.get(load_id) or model_lookup.get(str(selected_option.get("model_id") or "")) or {}
+            pulled = bool(selected_option.get("pulled") or model_info.get("pulled"))
+            is_loaded = bool(selected_option.get("loaded"))
+            engine_installed = bool(selected_option.get("installed"))
             pullable = bool(item.get("pullable", True))
-            download_required = bool(pullable and not pulled and not is_loaded)
+            runtime_compatibility = dict(selected_option.get("runtime_compatibility") or {})
+            runtime_supported = runtime_compatibility.get("supported") is not False
+            download_required = bool(selected_option.get("download_required") and pullable and not is_loaded)
             if is_loaded:
                 load_status = "loaded"
                 unavailable_reason = None
+            elif not runtime_supported:
+                load_status = str(runtime_compatibility.get("status") or "unsupported")
+                unavailable_reason = str(runtime_compatibility.get("user_message") or "This model is not supported by the installed runtime.")
             elif not engine_installed:
                 load_status = "unavailable"
                 unavailable_reason = f"{engine_info.get('name') or recommended_engine} runtime is not installed."
@@ -196,9 +261,13 @@ def create_models_router(
                 "source_display_order": item.get("source_display_order"),
                 "pulled": pulled,
                 "download_required": download_required,
-                "load_available": is_loaded or (engine_installed and not download_required),
+                "load_available": is_loaded or (runtime_supported and engine_installed and not download_required),
                 "load_status": load_status,
                 "unavailable_reason": unavailable_reason,
+                "runtime_compatibility": runtime_compatibility,
+                "recovery_guidance": runtime_compatibility.get("recovery_guidance") or [],
+                "alternative_recommendations": runtime_compatibility.get("alternatives") or [],
+                "runtime_label": selected_option.get("runtime_label"),
             }
             base["engine_options"] = options
             base["recommended_engine"] = recommended_engine
@@ -272,10 +341,20 @@ def create_models_router(
     @router.post("/engines/prepare-model")
     async def engines_prepare_model(req: PrepareModelRequest, request: Request):
         require_user(request)
-        return await prepare_and_load_model(
-            req.model, request, engine=req.engine, user_email=req.user_email,
-            allow_download=req.allow_download,
-        )
+        try:
+            return await prepare_and_load_model(
+                req.model, request, engine=req.engine, user_email=req.user_email,
+                allow_download=req.allow_download,
+            )
+        except HTTPException:
+            raise
+        except Exception as exc:
+            from latticeai.core.model_compat import friendly_model_runtime_error
+
+            raise HTTPException(
+                status_code=500,
+                detail=friendly_model_runtime_error(exc, model_id=req.model, engine=req.engine),
+            )
 
     @router.post("/engines/prepare-model/stream")
     async def engines_prepare_model_stream(req: PrepareModelRequest, request: Request):
@@ -295,9 +374,11 @@ def create_models_router(
                 })
             except Exception as exc:
                 logging.exception("model prepare stream failed")
+                from latticeai.core.model_compat import friendly_model_runtime_error
+
                 yield sse_event("error", {
                     "status_code": 500,
-                    "detail": str(exc)[-1000:] or "모델 준비에 실패했습니다.",
+                    "detail": friendly_model_runtime_error(exc, model_id=req.model, engine=req.engine),
                 })
 
         return StreamingResponse(
@@ -356,6 +437,8 @@ def create_models_router(
     @router.post("/models/load")
     async def load_model(req: LoadModelRequest, request: Request):
         try:
+            from latticeai.core.model_compat import friendly_model_runtime_error, model_runtime_compatibility
+
             model_id = req.model_id
             requested_engine = req.engine or (model_id.split(":", 1)[0] if ":" in model_id else "local_mlx")
             if IS_PUBLIC_MODE and not ALLOW_LOCAL_MODELS and requested_engine in {"local_mlx", "mlx"}:
@@ -363,6 +446,9 @@ def create_models_router(
                     status_code=400,
                     detail="Public mode blocks local MLX model loading. Use openai:, openrouter:, groq:, together:, or set LATTICEAI_ALLOW_LOCAL_MODELS=true.",
                 )
+            compatibility = model_runtime_compatibility(model_id, engine=requested_engine)
+            if compatibility.get("supported") is False:
+                raise HTTPException(status_code=400, detail=compatibility)
             return await prepare_and_load_model(
                 model_id, request, engine=req.engine, user_email=req.user_email,
                 adapter_path=req.adapter_path, draft_model_id=req.draft_model_id,
@@ -371,7 +457,10 @@ def create_models_router(
         except HTTPException:
             raise
         except Exception as e:
-            raise HTTPException(status_code=500, detail=str(e))
+            raise HTTPException(
+                status_code=500,
+                detail=friendly_model_runtime_error(e, model_id=req.model_id, engine=req.engine),
+            )
 
     @router.post("/models/switch/{model_id:path}")
     async def switch_model(model_id: str, request: Request):

package/latticeai/core/marketplace.py

@@ -11,7 +11,7 @@ from copy import deepcopy
 from typing import Any, Dict, List, Optional
 
 
-MARKETPLACE_VERSION = "4.4.0"
+MARKETPLACE_VERSION = "4.6.0"
 TEMPLATE_KINDS = ("plugin", "workflow", "agent")
 
 

package/latticeai/core/model_compat.py

@@ -12,11 +12,14 @@
 
 from __future__ import annotations
 
+import importlib.util
+import json
 import logging
 import re
 import threading
 import time
 from dataclasses import dataclass, asdict
+from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
 logger = logging.getLogger(__name__)
@@ -119,6 +122,251 @@ def get_model_profile(model_id: str, engine: Optional[str] = None) -> Dict[str,
     return base
 
 
+# ── Runtime compatibility checks ─────────────────────────────────────────────
+
+GEMMA4_MLX_UNIFIED_MODULE = "mlx_vlm.models.gemma4_unified"
+GEMMA4_MLX_LM_MODULES = ("mlx_lm.models.gemma4", "mlx_lm.models.gemma4_text")
+GEMMA4_UNIFIED_ID_PATTERN = re.compile(r"gemma[-_/ ]?4[-_/ ]?12b", re.I)
+
+
+def _module_available(module: str) -> bool:
+    try:
+        return importlib.util.find_spec(module) is not None
+    except (ImportError, ModuleNotFoundError, AttributeError, ValueError):
+        return False
+
+
+def _is_gemma4(model_id: str) -> bool:
+    raw = str(model_id or "").lower()
+    return bool(re.search(r"gemma[-_/ ]?4", raw))
+
+
+def _hf_model_dir(repo_id: str) -> Path:
+    return Path.home() / ".ltcai" / "hf-models" / repo_id.replace("/", "__")
+
+
+def _local_model_type(model_id: str) -> Optional[str]:
+    raw = str(model_id or "").strip()
+    if "gemma4_unified" in raw.lower():
+        return "gemma4_unified"
+    candidates = []
+    explicit = Path(raw).expanduser()
+    if raw and explicit.exists():
+        candidates.append(explicit / "config.json")
+    candidates.append(_hf_model_dir(raw) / "config.json")
+    for config_path in candidates:
+        try:
+            if config_path.exists():
+                data = json.loads(config_path.read_text(encoding="utf-8"))
+                model_type = str(data.get("model_type") or "").strip().lower()
+                if model_type:
+                    return model_type
+        except Exception:
+            logger.debug("failed to read model config %s", config_path, exc_info=True)
+    if GEMMA4_UNIFIED_ID_PATTERN.search(raw):
+        return "gemma4_unified"
+    return None
+
+
+def _gemma4_runtime_candidates(raw_model_id: str) -> List[Dict[str, Any]]:
+    mlx_available = _module_available("mlx")
+    mlx_vlm_available = mlx_available and _module_available("mlx_vlm")
+    mlx_vlm_unified_available = mlx_vlm_available and _module_available(GEMMA4_MLX_UNIFIED_MODULE)
+    mlx_lm_available = mlx_available and _module_available("mlx_lm")
+    mlx_lm_gemma4_available = mlx_lm_available and any(_module_available(module) for module in GEMMA4_MLX_LM_MODULES)
+    return [
+        {
+            "engine": "local_mlx",
+            "runtime": "MLX-VLM",
+            "load_id": raw_model_id,
+            "available": mlx_vlm_available,
+            "supports_gemma4_unified": mlx_vlm_unified_available,
+            "role": "v3_primary",
+        },
+        {
+            "engine": "local_mlx",
+            "runtime": "MLX-LM",
+            "load_id": raw_model_id,
+            "available": mlx_lm_gemma4_available,
+            "role": "v3_text_fallback",
+        },
+        {
+            "engine": "ollama",
+            "runtime": "Ollama GGUF",
+            "load_id": "ollama:hf.co/ggml-org/gemma-4-12B-it-GGUF:Q4_K_M",
+            "available": None,
+            "role": "gguf_local_server",
+        },
+        {
+            "engine": "lmstudio",
+            "runtime": "LM Studio GGUF",
+            "load_id": "lmstudio:ggml-org/gemma-4-12B-it-GGUF",
+            "available": None,
+            "role": "gguf_local_server",
+        },
+        {
+            "engine": "llamacpp",
+            "runtime": "llama.cpp GGUF",
+            "load_id": "llamacpp:ggml-org/gemma-4-12B-it-GGUF",
+            "available": None,
+            "role": "gguf_local_server",
+        },
+    ]
+
+
+def model_runtime_compatibility(model_id: str, engine: Optional[str] = None) -> Dict[str, Any]:
+    """Return a lightweight pre-load runtime compatibility signal.
+
+    This intentionally checks only known fast failure modes. The loader and
+    smoke test remain the final authority, but the UI must not present a model
+    as ready when the installed runtime is known to lack its required loader.
+    """
+    normalized_engine = (engine or "").strip().lower()
+    if normalized_engine in {"", "mlx"}:
+        normalized_engine = "local_mlx"
+    raw_model_id = str(model_id or "")
+    if raw_model_id.startswith(("local_mlx:", "mlx:")):
+        raw_model_id = raw_model_id.split(":", 1)[1]
+
+    payload: Dict[str, Any] = {
+        "model_id": raw_model_id,
+        "engine": normalized_engine or None,
+        "family": detect_model_family(raw_model_id),
+        "status": "supported",
+        "supported": True,
+        "checked": True,
+        "runtime": None,
+        "preferred_runtime": None,
+        "runtime_candidates": [],
+        "missing_components": [],
+        "user_message": None,
+        "recovery_guidance": [],
+        "alternatives": [],
+    }
+
+    if normalized_engine != "local_mlx" or not _is_gemma4(raw_model_id):
+        return payload
+
+    candidates = _gemma4_runtime_candidates(raw_model_id)
+    payload["runtime_candidates"] = candidates
+    payload["runtime"] = "MLX-VLM"
+    payload["preferred_runtime"] = "MLX-VLM"
+    model_type = _local_model_type(raw_model_id)
+    if model_type:
+        payload["model_type"] = model_type
+
+    mlx_available = _module_available("mlx")
+    mlx_vlm_available = _module_available("mlx_vlm")
+    mlx_lm_available = any(bool(candidate.get("available")) for candidate in candidates if candidate.get("runtime") == "MLX-LM")
+
+    if not mlx_available or not (mlx_vlm_available or mlx_lm_available):
+        payload.update({
+            "status": "runtime_not_installed",
+            "checked": False,
+            "supported": True,
+            "user_message": (
+                "Install the local MLX runtime before loading Gemma 4, or choose "
+                "the Gemma 4 GGUF route through Ollama, LM Studio, or llama.cpp."
+            ),
+            "alternatives": candidates[2:],
+        })
+        return payload
+
+    if model_type == "gemma4_unified" and not _module_available(GEMMA4_MLX_UNIFIED_MODULE):
+        payload.update({
+            "status": "runtime_update_needed",
+            "supported": False,
+            "reason_code": "mlx_vlm_missing_gemma4_unified_model",
+            "model_type": "gemma4_unified",
+            "missing_components": [GEMMA4_MLX_UNIFIED_MODULE],
+            "user_message": (
+                "Gemma 4 12B uses the gemma4_unified MLX format. The installed "
+                "MLX-VLM runtime does not include that loader, so this local "
+                "model cannot load until MLX-VLM is updated."
+            ),
+            "recovery_guidance": [
+                "Update the MLX runtime from Library/System setup, or run: pip install --upgrade 'mlx-vlm>=0.6.3'.",
+                "After the runtime update, re-open Models so Lattice can re-check this model.",
+                "Use Gemma 4 26B A4B locally or Gemma 4 12B GGUF through Ollama, LM Studio, or llama.cpp until then.",
+            ],
+            "alternatives": [
+                {"id": "mlx-community/gemma-4-26b-a4b-it-4bit", "name": "Gemma 4 26B A4B", "engine": "local_mlx"},
+                {"id": "ollama:hf.co/ggml-org/gemma-4-12B-it-GGUF:Q4_K_M", "name": "Gemma 4 12B GGUF", "engine": "ollama"},
+                {"id": "lmstudio:ggml-org/gemma-4-12B-it-GGUF", "name": "Gemma 4 12B GGUF", "engine": "lmstudio"},
+            ],
+            "action": "Runtime update needed",
+        })
+        return payload
+
+    if mlx_vlm_available:
+        return payload
+
+    payload.update({
+        "status": "fallback_available",
+        "supported": True,
+        "reason_code": "mlx_vlm_missing_gemma4_standard_runtime",
+        "missing_components": ["mlx_vlm"],
+        "user_message": (
+            "MLX-VLM is not available for this Gemma 4 model. Lattice can use "
+            "the MLX-LM text fallback or a Gemma 4 GGUF local runtime."
+        ),
+        "recovery_guidance": [
+            "Use the MLX-LM text fallback for text chat.",
+            "Use a Gemma 4 GGUF model through Ollama, LM Studio, or llama.cpp if the MLX route fails.",
+        ],
+        "alternatives": [
+            {"id": candidate["load_id"], "name": candidate["runtime"], "engine": candidate["engine"]}
+            for candidate in candidates
+            if candidate.get("role") != "v3_primary"
+        ],
+    })
+    if mlx_lm_available:
+        payload["preferred_runtime"] = "MLX-LM fallback"
+    return payload
+
+
+def friendly_model_runtime_error(
+    error: BaseException | str,
+    *,
+    model_id: Optional[str] = None,
+    engine: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Convert loader exceptions into end-user recoverable error payloads."""
+    raw = str(error or "")
+    compat = model_runtime_compatibility(model_id or raw, engine=engine)
+    if not compat.get("supported", True):
+        return {
+            "status": compat.get("status") or "unsupported",
+            "model_id": model_id,
+            "engine": engine,
+            "user_message": compat.get("user_message") or (
+                "The selected model is not supported by the installed local runtime."
+            ),
+            "recovery_guidance": compat.get("recovery_guidance") or [
+                "Choose a recommended alternative model.",
+                "Update the local runtime and try validation again.",
+            ],
+            "alternatives": compat.get("alternatives") or [],
+            "missing_components": compat.get("missing_components") or [],
+            "action": compat.get("action"),
+            "reason_code": compat.get("reason_code") or "runtime_model_type_unsupported",
+        }
+    return {
+        "status": "load_failed",
+        "model_id": model_id,
+        "engine": engine,
+        "user_message": (
+            "The model could not be loaded. Check that the runtime is installed, "
+            "the model files are present, and try a recommended alternative if the issue continues."
+        ),
+        "recovery_guidance": [
+            "Open Models and run the setup flow again.",
+            "Confirm downloads were explicitly allowed for models that are not on this computer.",
+            "Try a recommended smaller local model if memory is low.",
+        ],
+    }
+
+
 # ── Postprocessing ────────────────────────────────────────────────────────────
 
 BAD_MARKERS = [
@@ -378,7 +626,9 @@ __all__ = [
     "FAMILY_PROFILES",
     "CompatProfile",
     "detect_model_family",
+    "friendly_model_runtime_error",
     "get_model_profile",
+    "model_runtime_compatibility",
     "fast_postprocess",
     "validate_smoke_response",
     "classify_smoke_response",

package/latticeai/core/workspace_os.py

@@ -19,7 +19,7 @@ from pathlib import Path
 from typing import Any, Callable, Dict, Iterable, List, Optional
 
 
-WORKSPACE_OS_VERSION = "4.4.0"
+WORKSPACE_OS_VERSION = "4.6.0"
 
 # Workspace types separate single-user Personal workspaces from shared
 # Organization workspaces. Both keep the same local-first JSON store; the type