ltcai 4.3.3 → 4.5.1

package/latticeai/core/marketplace.py

@@ -11,7 +11,7 @@ from copy import deepcopy
 from typing import Any, Dict, List, Optional
 
 
-MARKETPLACE_VERSION = "4.3.3"
+MARKETPLACE_VERSION = "4.5.1"
 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",