ltcai 11.1.0 → 11.4.0

package/latticeai/setup/wizard/catalog.py

@@ -0,0 +1,172 @@
+"""The wizard's model catalogue and the per-engine "best model" tiers.
+
+Data plus the two pure decisions that read it: hide superseded model
+*generations* (:func:`_filter_lower_family_versions`) and pick the best model a
+machine with this much RAM can actually hold (:func:`_best_model_for_engine`).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List, Tuple
+
+# ── Model Catalog ─────────────────────────────────────────────────────────────
+# (model_id, display_name, size_gb, tag, description, min_ram_gb)
+# 11.2.0: 모든 repo id 를 2026-08-10 Hugging Face API 로 확인했다 — 존재 여부,
+# gated 여부, 정확한 대소문자, siblings 합계 크기. 크기 값은 측정값이다.
+# 삭제: Qwen3-VL 전 라인업(2025-10, Qwen3.5/3.6 이 상위 세대), Llama 4 Scout
+# (vLLM/LM Studio 경로가 gated 인 meta-llama 저장소를 가리켰다).
+_MODEL_CATALOG = [
+    ("mlx-community/LFM2.5-2.6B-4bit",               "LFM2.5 2.6B",          1.5,  "LLM",     "가장 가벼움 · 한국어 대화 (사진은 못 읽음)", 4),
+    ("mlx-community/gemma-4-e2b-it-4bit",            "Gemma 4 E2B",          3.6,  "VLM",     "사진을 읽는 가장 작은 모델",        8),
+    ("mlx-community/gemma-4-e4b-it-4bit",            "Gemma 4 E4B",          5.2,  "VLM",     "E2B 보다 한 단계 위 · 여전히 가벼움", 10),
+    ("mlx-community/Qwen3.5-9B-MLX-4bit",            "Qwen3.5 9B",           6.0,  "VLM",     "중형 멀티모달 · 균형 추천",         12),
+    ("mlx-community/gemma-4-12B-it-4bit",            "Gemma 4 12B",          6.8,  "VLM",     "Gemma 4 기본 추천 · 4bit",          16),
+    ("mlx-community/gpt-oss-20b-MXFP4-Q8",           "GPT-OSS 20B",         12.1,  "LLM",     "범용 · 다운로드 최다 (사진은 못 읽음)", 24),
+    ("mlx-community/gemma-4-26b-a4b-it-4bit",        "Gemma 4 26B A4B",     15.4,  "VLM",     "MoE · 대형 추천",                   32),
+    ("mlx-community/Qwen3.6-27B-4bit",               "Qwen3.6 27B",         16.1,  "VLM+",    "dense 최상위 · 느리지만 일정함",     48),
+    ("mlx-community/gemma-4-31b-it-4bit",            "Gemma 4 31B",         18.4,  "VLM+",    "Gemma 4 최대 모델",                 48),
+    ("mlx-community/Qwen3.6-35B-A3B-4bit",           "Qwen3.6 35B A3B",     20.4,  "VLM+",    "MoE 최상위",                        48),
+]
+
+_CROSS_PLATFORM_MODEL_CATALOG: Dict[str, List[Tuple[str, str, float, str, str, int]]] = {
+    "ollama": [
+        ("ollama:hf.co/LiquidAI/LFM2.5-2.6B-GGUF:Q4_K_M", "LFM2.5 2.6B Q4", 1.7, "LLM", "가장 가벼움 · 한국어 대화", 4),
+        ("ollama:hf.co/ggml-org/gemma-4-E2B-it-GGUF:Q4_K_M", "Gemma 4 E2B Q4", 3.8, "VLM", "Hugging Face GGUF 기반 Gemma 4", 8),
+        ("ollama:hf.co/ggml-org/gemma-4-E4B-it-GGUF:Q4_K_M", "Gemma 4 E4B Q4", 5.4, "VLM", "Hugging Face GGUF 기반 Gemma 4", 10),
+        ("ollama:hf.co/ggml-org/gemma-4-12B-it-GGUF:Q4_K_M", "Gemma 4 12B Q4", 7.9, "VLM", "Hugging Face GGUF 기반 Gemma 4", 16),
+        ("ollama:hf.co/ggml-org/gpt-oss-20b-GGUF:Q4_K_M", "GPT-OSS 20B Q4", 12.5, "LLM", "범용 · 다운로드 최다", 24),
+        ("ollama:hf.co/ggml-org/gemma-4-26B-A4B-it-GGUF:Q4_K_M", "Gemma 4 26B Q4", 16.0, "VLM", "MoE · 대형 추천", 32),
+        ("ollama:hf.co/ggml-org/Qwen3.6-27B-GGUF:Q4_K_M", "Qwen3.6 27B Q4", 16.6, "VLM+", "dense 최상위", 48),
+        ("ollama:hf.co/ggml-org/gemma-4-31B-it-GGUF:Q4_K_M", "Gemma 4 31B Q4", 18.7, "VLM+", "Gemma 4 최대 모델", 48),
+    ],
+    "lmstudio": [
+        ("lmstudio:LiquidAI/LFM2.5-2.6B-GGUF", "LFM2.5 2.6B", 1.7, "LLM", "가장 가벼움 · 한국어 대화", 4),
+        ("lmstudio:ggml-org/gemma-4-E2B-it-GGUF", "Gemma 4 E2B", 3.8, "VLM", "LM Studio GGUF Gemma 4", 8),
+        ("lmstudio:ggml-org/gemma-4-E4B-it-GGUF", "Gemma 4 E4B", 5.4, "VLM", "LM Studio GGUF Gemma 4", 10),
+        ("lmstudio:ggml-org/gemma-4-12B-it-GGUF", "Gemma 4 12B", 7.9, "VLM", "LM Studio GGUF Gemma 4", 16),
+        ("lmstudio:ggml-org/gpt-oss-20b-GGUF", "GPT-OSS 20B", 12.5, "LLM", "범용 · 다운로드 최다", 24),
+        ("lmstudio:ggml-org/gemma-4-26B-A4B-it-GGUF", "Gemma 4 26B", 16.0, "VLM", "MoE · 대형 추천", 32),
+        ("lmstudio:ggml-org/Qwen3.6-27B-GGUF", "Qwen3.6 27B", 16.6, "VLM+", "dense 최상위", 48),
+        ("lmstudio:ggml-org/gemma-4-31B-it-GGUF", "Gemma 4 31B", 18.7, "VLM+", "Gemma 4 최대 모델", 48),
+    ],
+    "vllm": [
+        ("vllm:LiquidAI/LFM2.5-2.6B", "LFM2.5 2.6B", 5.2, "LLM", "가장 가벼움 · 한국어 대화", 8),
+        ("vllm:google/gemma-4-E2B-it", "Gemma 4 E2B", 6.0, "VLM", "내 컴퓨터 GPU 실행 도구 권장", 12),
+        ("vllm:google/gemma-4-E4B-it", "Gemma 4 E4B", 9.0, "VLM", "내 컴퓨터 GPU 실행 도구 권장", 16),
+        ("vllm:Qwen/Qwen3.5-9B", "Qwen3.5 9B", 18.0, "VLM", "중형 멀티모달 · 균형 추천", 24),
+        ("vllm:google/gemma-4-12B-it", "Gemma 4 12B", 24.0, "VLM", "Gemma 4 기본 추천", 32),
+        ("vllm:openai/gpt-oss-20b", "GPT-OSS 20B", 13.5, "LLM", "범용 · 다운로드 최다", 24),
+        ("vllm:Qwen/Qwen3.6-27B", "Qwen3.6 27B", 54.0, "VLM+", "dense 최상위 · 24GB+ VRAM 권장", 64),
+        ("vllm:Qwen/Qwen3.6-35B-A3B", "Qwen3.6 35B A3B", 70.0, "VLM+", "MoE 최상위 · 24GB+ VRAM 권장", 80),
+    ],
+    "llamacpp": [
+        ("llamacpp:LiquidAI/LFM2.5-2.6B-GGUF", "LFM2.5 2.6B GGUF", 1.7, "GGUF", "CPU/Vulkan 백업 · 가장 가벼움", 4),
+        ("llamacpp:ggml-org/gemma-4-E2B-it-GGUF", "Gemma 4 E2B GGUF", 3.8, "GGUF", "Gemma 4 E2B Q4_K_M", 8),
+        ("llamacpp:ggml-org/gemma-4-E4B-it-GGUF", "Gemma 4 E4B GGUF", 5.4, "GGUF", "Gemma 4 E4B Q4_K_M", 10),
+        ("llamacpp:ggml-org/gemma-4-12B-it-GGUF", "Gemma 4 12B GGUF", 7.9, "GGUF", "Gemma 4 12B Q4_K_M", 16),
+        ("llamacpp:ggml-org/gpt-oss-20b-GGUF", "GPT-OSS 20B GGUF", 12.5, "GGUF", "범용 · 다운로드 최다", 24),
+        ("llamacpp:ggml-org/gemma-4-26B-A4B-it-GGUF", "Gemma 4 26B GGUF", 16.0, "GGUF", "MoE · 대형 추천", 32),
+        ("llamacpp:ggml-org/Qwen3.6-27B-GGUF", "Qwen3.6 27B GGUF", 16.6, "GGUF", "dense 최상위", 48),
+        ("llamacpp:ggml-org/gemma-4-31B-it-GGUF", "Gemma 4 31B GGUF", 18.7, "GGUF", "Gemma 4 31B Q4_K_M", 48),
+    ],
+}
+
+_VERSIONED_MODEL_PATTERNS = (
+    ("gemma", re.compile(r"\bgemma[-\s]?(\d+(?:\.\d+)?)", re.IGNORECASE)),
+    ("qwen", re.compile(r"\bqwen[-\s]?(\d+(?:\.\d+)?)", re.IGNORECASE)),
+    ("llama", re.compile(r"\bllama[-\s]?(\d+(?:\.\d+)?)", re.IGNORECASE)),
+)
+
+# RAM(GB) 내림차순 티어. 첫 번째로 조건을 만족하는 항목이 "이 컴퓨터에서 가장
+# 좋은 모델"이 된다. 초경량(≤8) / 경량(16) / 중형(24) / MoE(32) / 대형(48).
+_BEST_MODEL_TIERS: Dict[str, List[Tuple[int, str]]] = {
+    "local_mlx": [
+        (48, "mlx-community/gemma-4-31b-it-4bit"),
+        (32, "mlx-community/gemma-4-26b-a4b-it-4bit"),
+        (24, "mlx-community/gemma-4-12B-it-4bit"),
+        (16, "mlx-community/Qwen3.5-9B-MLX-4bit"),
+        (8, "mlx-community/gemma-4-e2b-it-4bit"),
+        (4, "mlx-community/LFM2.5-2.6B-4bit"),
+    ],
+    "ollama": [
+        (48, "ollama:hf.co/ggml-org/gemma-4-31B-it-GGUF:Q4_K_M"),
+        (32, "ollama:hf.co/ggml-org/gemma-4-26B-A4B-it-GGUF:Q4_K_M"),
+        (24, "ollama:hf.co/ggml-org/gemma-4-12B-it-GGUF:Q4_K_M"),
+        (16, "ollama:hf.co/ggml-org/gemma-4-E4B-it-GGUF:Q4_K_M"),
+        (8, "ollama:hf.co/ggml-org/gemma-4-E2B-it-GGUF:Q4_K_M"),
+        (4, "ollama:hf.co/LiquidAI/LFM2.5-2.6B-GGUF:Q4_K_M"),
+    ],
+    "lmstudio": [
+        (48, "lmstudio:ggml-org/gemma-4-31B-it-GGUF"),
+        (32, "lmstudio:ggml-org/gemma-4-26B-A4B-it-GGUF"),
+        (24, "lmstudio:ggml-org/gemma-4-12B-it-GGUF"),
+        (16, "lmstudio:ggml-org/gemma-4-E4B-it-GGUF"),
+        (8, "lmstudio:ggml-org/gemma-4-E2B-it-GGUF"),
+        (4, "lmstudio:LiquidAI/LFM2.5-2.6B-GGUF"),
+    ],
+    # vLLM serves the upstream bf16 repos, which are 3-4x the MLX 4-bit builds
+    # (Qwen3.6-27B is 54GB, not 16GB), so its thresholds sit far higher than the
+    # local_mlx ones. Picking by RAM alone would nominate a model no consumer
+    # GPU can hold.
+    "vllm": [
+        (96, "vllm:Qwen/Qwen3.6-27B"),
+        (32, "vllm:google/gemma-4-12B-it"),
+        (24, "vllm:Qwen/Qwen3.5-9B"),
+        (16, "vllm:google/gemma-4-E4B-it"),
+        (8, "vllm:LiquidAI/LFM2.5-2.6B"),
+    ],
+    "llamacpp": [
+        (48, "llamacpp:ggml-org/gemma-4-31B-it-GGUF"),
+        (32, "llamacpp:ggml-org/gemma-4-26B-A4B-it-GGUF"),
+        (24, "llamacpp:ggml-org/gemma-4-12B-it-GGUF"),
+        (16, "llamacpp:ggml-org/gemma-4-E4B-it-GGUF"),
+        (8, "llamacpp:ggml-org/gemma-4-E2B-it-GGUF"),
+        (4, "llamacpp:LiquidAI/LFM2.5-2.6B-GGUF"),
+    ],
+}
+
+
+def _version_tuple(raw: str) -> Tuple[int, ...]:
+    return tuple(int(part) for part in raw.split(".") if part.isdigit())
+
+
+def _catalog_row_family_version(row: Tuple[str, str, float, str, str, int]) -> Tuple[str, Tuple[int, ...]] | None:
+    text = f"{row[0]} {row[1]}"
+    for family, pattern in _VERSIONED_MODEL_PATTERNS:
+        match = pattern.search(text)
+        if match:
+            # Major version only — see model_catalog._model_family_version. The
+            # filter hides superseded *generations*; Qwen3.5 and Qwen3.6 are one
+            # generation filling two different RAM tiers and must coexist.
+            version = _version_tuple(match.group(1))[:1]
+            if version:
+                return family, version
+    return None
+
+
+def _filter_lower_family_versions(
+    rows: List[Tuple[str, str, float, str, str, int]],
+) -> List[Tuple[str, str, float, str, str, int]]:
+    max_versions: Dict[str, Tuple[int, ...]] = {}
+    detected: List[Tuple[Tuple[str, str, float, str, str, int], Tuple[str, Tuple[int, ...]] | None]] = []
+    for row in rows:
+        version_info = _catalog_row_family_version(row)
+        detected.append((row, version_info))
+        if not version_info:
+            continue
+        family, version = version_info
+        if version > max_versions.get(family, (0,)):
+            max_versions[family] = version
+    return [
+        row for row, version_info in detected
+        if not version_info or version_info[1] >= max_versions.get(version_info[0], version_info[1])
+    ]
+
+
+def _best_model_for_engine(engine: str, ram_gb: float, rows: List[Tuple[str, str, float, str, str, int]]) -> str:
+    available_ids = {row[0] for row in rows}
+    for min_ram, model_id in _BEST_MODEL_TIERS.get(engine, []):
+        if ram_gb >= min_ram and model_id in available_ids:
+            return model_id
+    return rows[0][0] if rows else ""

package/latticeai/setup/wizard/detect.py

@@ -0,0 +1,323 @@
+"""Hardware, OS, toolchain and API-key detection for the setup wizard.
+
+Everything the recommender needs to know about *this* machine: chip, CPU
+features, RAM, free disk, GPU/CUDA/WSL, which CLIs are on PATH, whether MLX
+imports, and which provider keys are in the environment. Every probe is
+best-effort — a failed probe answers "unknown", never raises.
+"""
+
+from __future__ import annotations
+
+import os
+import platform
+import re
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, List
+
+from latticeai.core.quiet import quiet
+from latticeai.services.setup_detection import (
+    detect_cuda,
+    detect_tools,
+    detect_wsl_from_text,
+)
+from latticeai.services.setup_detection import (
+    parse_windows_video_controllers as _parse_windows_video_controllers,
+)
+from latticeai.setup.wizard.paths import (
+    _component_detail,
+    _module_available,
+    _which_any,
+    repair_path_for,
+)
+
+
+def _cmd(args: List[str], timeout: int = 10) -> str:
+    try:
+        r = subprocess.run(args, capture_output=True, text=True, timeout=timeout, check=False)
+        return (r.stdout or r.stderr or "").strip()
+    except Exception:
+        return ""
+
+# ── Environment Detection ─────────────────────────────────────────────────────
+
+def _detect_chip() -> Dict[str, Any]:
+    arch = platform.machine()
+    is_apple = arch == "arm64" and platform.system() == "Darwin"
+    name = "Unknown CPU"
+    gen: Any = None
+
+    if is_apple:
+        profiler = _cmd(["system_profiler", "SPHardwareDataType"], timeout=8)
+        m = re.search(r"Chip:\s+(Apple M\S+)", profiler)
+        name = m.group(1) if m else "Apple Silicon"
+        gm = re.search(r"M(\d+)", name)
+        gen = int(gm.group(1)) if gm else 1
+    else:
+        brand = ""
+        if platform.system() == "Darwin":
+            brand = _cmd(["sysctl", "-n", "machdep.cpu.brand_string"])
+        elif platform.system() == "Windows":
+            raw = _cmd(["wmic", "cpu", "get", "Name", "/value"], timeout=5)
+            if "Name=" in raw:
+                brand = raw.split("Name=", 1)[-1].splitlines()[0].strip()
+        elif platform.system() == "Linux":
+            try:
+                for line in Path("/proc/cpuinfo").read_text(encoding="utf-8", errors="replace").splitlines():
+                    if line.lower().startswith("model name"):
+                        brand = line.split(":", 1)[-1].strip()
+                        break
+            except Exception:
+                quiet()
+        name = brand or platform.processor() or "Unknown CPU"
+
+    return {"name": name, "arch": arch, "is_apple_silicon": is_apple, "gen": gen}
+
+
+def _detect_cpu() -> Dict[str, Any]:
+    flags: List[str] = []
+    physical_cores = os.cpu_count() or 0
+    logical_cores = os.cpu_count() or 0
+    model = _detect_chip()["name"]
+    if platform.system() == "Darwin":
+        flags = [item.lower() for item in _cmd(["sysctl", "-n", "machdep.cpu.features"], timeout=5).split()]
+        try:
+            physical_cores = int(_cmd(["sysctl", "-n", "hw.physicalcpu"], timeout=5) or physical_cores)
+            logical_cores = int(_cmd(["sysctl", "-n", "hw.logicalcpu"], timeout=5) or logical_cores)
+        except ValueError:
+            quiet()
+    elif platform.system() == "Linux":
+        try:
+            text = Path("/proc/cpuinfo").read_text(encoding="utf-8", errors="replace")
+            for line in text.splitlines():
+                if line.lower().startswith(("flags", "features")):
+                    flags = line.split(":", 1)[-1].strip().lower().split()
+                    break
+        except Exception:
+            quiet()
+    elif platform.system() == "Windows":
+        raw = _cmd(["wmic", "cpu", "get", "Name,NumberOfCores,NumberOfLogicalProcessors", "/format:list"], timeout=5)
+        for line in raw.splitlines():
+            key, _, value = line.partition("=")
+            if key == "Name" and value.strip():
+                model = value.strip()
+            elif key == "NumberOfCores" and value.strip():
+                try:
+                    physical_cores = int(value.strip())
+                except ValueError:
+                    quiet()
+            elif key == "NumberOfLogicalProcessors" and value.strip():
+                try:
+                    logical_cores = int(value.strip())
+                except ValueError:
+                    quiet()
+        try:
+            import ctypes
+            kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]  # Windows-only
+            feature_map = {
+                6: "sse",
+                10: "sse2",
+                13: "sse3",
+                19: "neon",
+                28: "rdrand",
+            }
+            flags.extend(name for code, name in feature_map.items() if kernel32.IsProcessorFeaturePresent(code))
+        except Exception:
+            quiet()
+    interesting = {"avx", "avx2", "avx512f", "fma", "neon", "sse4_2"}
+    if platform.system() == "Windows":
+        interesting.update({"sse", "sse2", "sse3", "rdrand"})
+    return {
+        "model": model,
+        "physical_cores": physical_cores,
+        "logical_cores": logical_cores,
+        "instructions": sorted({flag for flag in flags if flag in interesting}),
+    }
+
+def _detect_ram_gb() -> float:
+    if platform.system() == "Windows":
+        raw = _cmd(["wmic", "ComputerSystem", "get", "TotalPhysicalMemory", "/format:list"], timeout=5)
+        for line in raw.splitlines():
+            if line.startswith("TotalPhysicalMemory="):
+                try:
+                    return round(int(line.split("=", 1)[-1].strip()) / 1_073_741_824, 1)
+                except ValueError:
+                    break
+    raw = _cmd(["sysctl", "-n", "hw.memsize"])
+    if raw:
+        try:
+            return round(int(raw) / 1_073_741_824, 1)
+        except ValueError:
+            quiet()
+    if platform.system() == "Darwin":
+        profiler = _cmd(["system_profiler", "SPHardwareDataType"], timeout=8)
+        m = re.search(r"Memory:\s+([\d.]+)\s*(TB|GB|MB)", profiler, re.IGNORECASE)
+        if m:
+            value = float(m.group(1))
+            unit = m.group(2).lower()
+            if unit == "tb":
+                return round(value * 1024, 1)
+            if unit == "gb":
+                return round(value, 1)
+            return round(value / 1024, 1)
+        hostinfo = _cmd(["hostinfo"], timeout=5)
+        m = re.search(r"Primary memory available:\s+([\d.]+)\s+gigabytes", hostinfo, re.IGNORECASE)
+        if m:
+            return round(float(m.group(1)), 1)
+    try:
+        with open("/proc/meminfo") as f:
+            for line in f:
+                if line.startswith("MemTotal:"):
+                    return round(int(line.split()[1]) / 1_048_576, 1)
+    except Exception:
+        quiet()
+    return 0.0
+
+def _detect_disk_free_gb() -> float:
+    try:
+        path = "C:\\" if platform.system() == "Windows" else "/"
+        return round(shutil.disk_usage(path).free / 1_073_741_824, 1)
+    except Exception:
+        return 0.0
+
+
+def _detect_gpu() -> Dict[str, Any]:
+    devices: List[Dict[str, Any]] = []
+    nvidia_smi = _which_any("nvidia-smi")
+    if nvidia_smi:
+        info = _cmd([nvidia_smi, "--query-gpu=name,memory.total", "--format=csv,noheader,nounits"], timeout=8)
+        for line in [item.strip() for item in info.splitlines() if item.strip()]:
+            try:
+                name, mem = [part.strip() for part in line.split(",", 1)]
+                devices.append({"vendor": "nvidia", "name": name, "vram_mb": int(float(mem)), "backend": "cuda"})
+            except Exception:
+                quiet()
+                continue
+
+    if platform.system() == "Windows":
+        shell = _which_any("powershell") or _which_any("pwsh")
+        raw = ""
+        if shell:
+            raw = _cmd([
+                shell, "-NoProfile", "-Command",
+                "Get-CimInstance Win32_VideoController | Select-Object Name,AdapterRAM | ConvertTo-Json -Compress",
+            ], timeout=8)
+        if not raw:
+            raw = _cmd(["wmic", "path", "win32_VideoController", "get", "Name,AdapterRAM", "/format:list"], timeout=8)
+        for item in _parse_windows_video_controllers(raw):
+            if any(existing.get("name") == item["name"] for existing in devices):
+                continue
+            low = item["name"].lower()
+            vendor, backend = "unknown", "cpu"
+            if "nvidia" in low or "geforce" in low or "rtx" in low:
+                vendor, backend = "nvidia", "cuda"
+            elif "amd" in low or "radeon" in low:
+                vendor, backend = "amd", "directml/vulkan"
+            elif "intel" in low or "arc" in low or "iris" in low:
+                vendor, backend = "intel", "directml/vulkan"
+            devices.append({"vendor": vendor, "name": item["name"], "vram_mb": item["vram_mb"], "backend": backend})
+    elif platform.system() == "Darwin":
+        sp = _cmd(["system_profiler", "SPDisplaysDataType"], timeout=8)
+        for line in sp.splitlines():
+            if "Chipset Model" in line:
+                devices.append({"vendor": "apple", "name": line.split(":", 1)[-1].strip(), "vram_mb": 0, "backend": "metal/mlx"})
+                break
+    elif platform.system() == "Linux" and not devices:
+        info = _cmd(["lspci"], timeout=5)
+        for line in info.splitlines():
+            low = line.lower()
+            if not any(token in low for token in ("vga", "3d controller", "display")):
+                continue
+            if "nvidia" in low:
+                devices.append({"vendor": "nvidia", "name": line.strip(), "vram_mb": 0, "backend": "cuda"})
+            elif "amd" in low or "advanced micro devices" in low or "radeon" in low:
+                devices.append({"vendor": "amd", "name": line.strip(), "vram_mb": 0, "backend": "rocm/vulkan"})
+            elif "intel" in low:
+                devices.append({"vendor": "intel", "name": line.strip(), "vram_mb": 0, "backend": "vulkan"})
+
+    primary = max(devices, key=lambda item: int(item.get("vram_mb") or 0), default={})
+    vram_mb = int(primary.get("vram_mb") or 0)
+    return {
+        "devices": devices,
+        "vendor": primary.get("vendor", "none"),
+        "name": primary.get("name", ""),
+        "vram_mb": vram_mb,
+        "vram_gb": round(vram_mb / 1024, 1),
+        "backend": primary.get("backend", "cpu"),
+    }
+
+
+def _detect_cuda() -> Dict[str, Any]:
+    available, version, nvidia_smi, nvcc = detect_cuda(_which_any, lambda args: _cmd(args, timeout=5))
+    return {"available": available, "nvidia_smi": nvidia_smi, "nvcc": nvcc, "version": version}
+
+
+def _detect_wsl() -> Dict[str, Any]:
+    raw = ""
+    try:
+        raw = Path("/proc/version").read_text(encoding="utf-8", errors="replace")
+    except Exception:
+        quiet()
+    is_wsl, version = detect_wsl_from_text(platform.system().lower(), raw)
+    return {"is_wsl": is_wsl, "version": version}
+
+
+def _detect_tools() -> Dict[str, bool]:
+    repair_path_for()
+    detected = detect_tools(_which_any, ["brew", "ollama", "python3", "python", "node", "npm", "git", "tesseract", "lms", "nvidia-smi", "nvcc"])
+    return {tool: path is not None for tool, path in detected.items()}
+
+def _detect_mlx() -> Dict[str, Any]:
+    return {
+        "available": _module_available("mlx"),
+        "mlx_vlm": _module_available("mlx_vlm"),
+    }
+
+def _detect_api_keys() -> Dict[str, bool]:
+    return {
+        "openai":     bool(os.getenv("OPENAI_API_KEY")),
+        "openrouter": bool(os.getenv("OPENROUTER_API_KEY")),
+        "groq":       bool(os.getenv("GROQ_API_KEY")),
+        "together":   bool(os.getenv("TOGETHER_API_KEY")),
+    }
+
+def scan_environment() -> Dict[str, Any]:
+    chip = _detect_chip()
+    cpu = _detect_cpu()
+    gpu = _detect_gpu()
+    cuda = _detect_cuda()
+    wsl = _detect_wsl()
+    tools = _detect_tools()
+    python_binary = "python3" if tools.get("python3") else "python"
+    return {
+        "os":           platform.system(),
+        "os_version":   platform.mac_ver()[0] if platform.system() == "Darwin" else platform.version(),
+        "chip":         chip,
+        "cpu":          cpu,
+        "gpu":          gpu,
+        "cuda":         cuda,
+        "wsl":          wsl,
+        "ram_gb":       _detect_ram_gb(),
+        "disk_free_gb": _detect_disk_free_gb(),
+        "tools":        tools,
+        "components": {
+            "homebrew": _component_detail("homebrew", "brew"),
+            "python": {**_component_detail("python", python_binary), "version": platform.python_version()},
+            "node": _component_detail("node", "node"),
+            "npm": _component_detail("node", "npm"),
+            "git": _component_detail("git", "git"),
+            "ollama": _component_detail("ollama", "ollama"),
+            "lmstudio": _component_detail("lmstudio", "lms"),
+            "cuda": {**_component_detail("cuda", "nvcc"), **cuda},
+            "tesseract": _component_detail("tesseract", "tesseract"),
+            "mlx": _component_detail("mlx", module="mlx"),
+            "mlx_vlm": _component_detail("mlx", module="mlx_vlm"),
+        },
+        "path": {
+            "active": os.environ.get("PATH", ""),
+            "extra": os.environ.get("LATTICEAI_EXTRA_PATH", ""),
+        },
+        "mlx":          _detect_mlx(),
+        "api_keys":     _detect_api_keys(),
+    }