ltcai 12.3.0 → 12.5.0

package/latticeai/services/architecture_readiness.py

@@ -19,7 +19,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Dict, List
 
-ARCHITECTURE_VERSION_TARGET = "12.3.0"
+ARCHITECTURE_VERSION_TARGET = "12.5.0"
 
 PREFERRED_REFACTORING_ORDER = [
     "agent-runtime",

package/latticeai/services/embedding_recommendation.py

@@ -0,0 +1,229 @@
+"""Embedding model capability registry and PC-tailored hardware recommendations.
+
+Dedicated module to keep `model_capability_registry.py` under the 1000-line cap
+while providing first-class Google EmbeddingGemma 2 / 300M recommendation logic.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional
+
+
+def build_embedding_capabilities(
+    model_capability_cls: type,
+    hardware_profile_cls: type,
+    verification_status_cls: type,
+) -> List[Any]:
+    """Construct ModelCapability instances for EmbeddingGemma 2 / 300M."""
+    return [
+        model_capability_cls(
+            id="google/embeddinggemma-2",
+            hf_repo_id="google/embeddinggemma-2",
+            name="Google EmbeddingGemma 2",
+            family="EmbeddingGemma",
+            tag="local-embedding",
+            size="1.5GB",
+            modality="text",
+            architecture="gemma3",
+            download_size_gb=1.48,
+            quantization="FP16",
+            provider_hints=["local_mlx", "ollama", "vllm", "lmstudio", "llamacpp"],
+            download_strategy="hf_hub",
+            load_strategy="sentence_transformers",
+            hardware=hardware_profile_cls(
+                min_ram_gb=4.0, recommended_ram_gb=8.0, apple_silicon_pref=True, cuda_pref=True,
+                notes="Google DeepMind 740M multilingual & code semantic embedding model (768d). Uses ~1.5GB in FP16 HF or ~0.5GB in 4-bit MLX.",
+            ),
+            source_country="미국", source_company="Google",
+            verification=verification_status_cls(
+                hf_exists=True, hf_last_checked="2026-11-11", has_config=True, has_tokenizer=True,
+                has_weights_hint=True, pipeline_tag="feature-extraction", likes=120, license="apache-2.0",
+                notes="Hugging Face google/embeddinggemma-2, 768d semantic embeddings.", verified_by="hf-api-light",
+            ),
+            recommended_default=True,
+            display_priority=70,
+            category="embedding",
+            task="embedding",
+            dimensions=768,
+        ),
+        model_capability_cls(
+            id="mlx-community/embeddinggemma-2-4bit",
+            hf_repo_id="mlx-community/embeddinggemma-2-4bit",
+            name="Google EmbeddingGemma 2 4-bit",
+            family="EmbeddingGemma",
+            tag="local-embedding",
+            size="0.4GB",
+            modality="text",
+            architecture="gemma3",
+            download_size_gb=0.42,
+            quantization="4bit",
+            provider_hints=["local_mlx"],
+            download_strategy="hf_hub",
+            load_strategy="mlx_embeddings",
+            hardware=hardware_profile_cls(
+                min_ram_gb=4.0, recommended_ram_gb=8.0, apple_silicon_pref=True,
+                notes="Apple Silicon MLX 4-bit quantized EmbeddingGemma 2 (768d, 0.42GB on disk, ~0.5GB RAM).",
+            ),
+            source_country="미국", source_company="Google",
+            verification=verification_status_cls(
+                hf_exists=True, hf_last_checked="2026-11-11", has_config=True, has_tokenizer=True,
+                has_weights_hint=True, pipeline_tag="feature-extraction", likes=45, license="apache-2.0",
+                notes="library_name=mlx, ungated, 4-bit quantized EmbeddingGemma 2.", verified_by="hf-api-light",
+            ),
+            recommended_default=True,
+            display_priority=71,
+            category="embedding",
+            task="embedding",
+            dimensions=768,
+        ),
+        model_capability_cls(
+            id="google/embeddinggemma-300m",
+            hf_repo_id="google/embeddinggemma-300m",
+            name="Google EmbeddingGemma 300M",
+            family="EmbeddingGemma",
+            tag="local-embedding",
+            size="0.6GB",
+            modality="text",
+            architecture="gemma3",
+            download_size_gb=0.60,
+            quantization="FP16",
+            provider_hints=["local_mlx", "ollama", "vllm", "lmstudio", "llamacpp"],
+            download_strategy="hf_hub",
+            load_strategy="sentence_transformers",
+            hardware=hardware_profile_cls(
+                min_ram_gb=2.0, recommended_ram_gb=4.0, apple_silicon_pref=True, cuda_pref=True,
+                notes="Compact 300M multilingual semantic embedding model (768d) for constrained-RAM PCs (<8GB).",
+            ),
+            source_country="미국", source_company="Google",
+            verification=verification_status_cls(
+                hf_exists=True, hf_last_checked="2026-11-11", has_config=True, has_tokenizer=True,
+                has_weights_hint=True, pipeline_tag="feature-extraction", likes=85, license="apache-2.0",
+                notes="Hugging Face google/embeddinggemma-300m, 768d semantic embeddings.", verified_by="hf-api-light",
+            ),
+            recommended_default=False,
+            display_priority=72,
+            category="embedding",
+            task="embedding",
+            dimensions=768,
+        ),
+        model_capability_cls(
+            id="mlx-community/embeddinggemma-300m-4bit",
+            hf_repo_id="mlx-community/embeddinggemma-300m-4bit",
+            name="Google EmbeddingGemma 300M 4-bit",
+            family="EmbeddingGemma",
+            tag="local-embedding",
+            size="0.3GB",
+            modality="text",
+            architecture="gemma3",
+            download_size_gb=0.30,
+            quantization="4bit",
+            provider_hints=["local_mlx"],
+            download_strategy="hf_hub",
+            load_strategy="mlx_embeddings",
+            hardware=hardware_profile_cls(
+                min_ram_gb=2.0, recommended_ram_gb=4.0, apple_silicon_pref=True,
+                notes="Ultralight 4-bit MLX EmbeddingGemma 300M (~0.3GB RAM) for low-memory Macs.",
+            ),
+            source_country="미국", source_company="Google",
+            verification=verification_status_cls(
+                hf_exists=True, hf_last_checked="2026-11-11", has_config=True, has_tokenizer=True,
+                has_weights_hint=True, pipeline_tag="feature-extraction", likes=30, license="apache-2.0",
+                notes="library_name=mlx, ungated, 4-bit quantized EmbeddingGemma 300M.", verified_by="hf-api-light",
+            ),
+            recommended_default=False,
+            display_priority=73,
+            category="embedding",
+            task="embedding",
+            dimensions=768,
+        ),
+    ]
+
+
+def recommend_embedding_for_hardware(
+    *,
+    ram_gb: Optional[float] = None,
+    apple_silicon: bool = False,
+    cuda: bool = False,
+    get_capability_fn: Optional[Callable[[str], Any]] = None,
+) -> Dict[str, Any]:
+    """Return a PC-tailored embedding model recommendation accounting for RAM & accelerator."""
+    effective_ram = 16.0 if ram_gb is None or ram_gb <= 0 else float(ram_gb)
+    cap = get_capability_fn("google/embeddinggemma-2") if get_capability_fn else None
+    mlx_cap = get_capability_fn("mlx-community/embeddinggemma-2-4bit") if get_capability_fn else None
+
+    if effective_ram >= 8.0:
+        use_mlx = bool(apple_silicon and mlx_cap is not None)
+        footprint_gb = 0.5 if use_mlx else 1.5
+        chosen_cap = cap or mlx_cap
+        base = chosen_cap.to_legacy_dict() if chosen_cap is not None else {}
+        return {
+            **base,
+            "id": "google/embeddinggemma-2",
+            "model_id": "google/embeddinggemma-2",
+            "hf_repo_id": "google/embeddinggemma-2",
+            "mlx_repo_id": "mlx-community/embeddinggemma-2-4bit",
+            "recommended_load_id": "mlx-community/embeddinggemma-2-4bit" if use_mlx else "google/embeddinggemma-2",
+            "recommended_engine": "local_mlx" if use_mlx else "huggingface",
+            "provider": "mlx" if use_mlx else "huggingface",
+            "profile_id": "mlx:embeddinggemma-2" if use_mlx else "local:embeddinggemma-2",
+            "name": "Google EmbeddingGemma 2",
+            "display_name": "Google EmbeddingGemma 2",
+            "family": "EmbeddingGemma",
+            "category": "embedding",
+            "role": "embedding",
+            "task": "embedding",
+            "tag": "local-embedding",
+            "modality": "text",
+            "dimensions": 768,
+            "size": "0.4GB" if use_mlx else "1.5GB",
+            "download_size": "0.4GB" if use_mlx else "1.5GB",
+            "download_size_gb": 0.42 if use_mlx else 1.48,
+            "memory_footprint_gb": footprint_gb,
+            "effective_llm_ram_gb": max(0.0, round(effective_ram - footprint_gb, 2)),
+            "status": "recommended",
+            "load_status": "ready",
+            "supported": True,
+            "recommended_default": True,
+            "display_priority": 70,
+            "reason": (
+                f"Apple Silicon ({int(round(effective_ram))}GB RAM) 맞춤 4-bit MLX / Hugging Face 시맨틱 임베딩 모델 (Google EmbeddingGemma 2, 768차원)"
+                if apple_silicon
+                else f"{int(round(effective_ram))}GB RAM PC 맞춤 Hugging Face 시맨틱 임베딩 모델 (Google EmbeddingGemma 2, 768차원)"
+            ),
+        }
+
+    cap_300m = get_capability_fn("google/embeddinggemma-300m") if get_capability_fn else None
+    use_mlx = bool(apple_silicon)
+    footprint_gb = 0.3
+    base = cap_300m.to_legacy_dict() if cap_300m else {}
+    return {
+        **base,
+        "id": "google/embeddinggemma-300m",
+        "model_id": "google/embeddinggemma-300m",
+        "hf_repo_id": "google/embeddinggemma-300m",
+        "mlx_repo_id": "mlx-community/embeddinggemma-300m-4bit",
+        "recommended_load_id": "mlx-community/embeddinggemma-300m-4bit" if use_mlx else "google/embeddinggemma-300m",
+        "recommended_engine": "local_mlx" if use_mlx else "huggingface",
+        "provider": "mlx" if use_mlx else "huggingface",
+        "profile_id": "local:embeddinggemma-300m",
+        "name": "Google EmbeddingGemma 300M",
+        "display_name": "Google EmbeddingGemma 300M",
+        "family": "EmbeddingGemma",
+        "category": "embedding",
+        "role": "embedding",
+        "task": "embedding",
+        "tag": "local-embedding",
+        "modality": "text",
+        "dimensions": 768,
+        "size": "0.3GB" if use_mlx else "0.6GB",
+        "download_size": "0.3GB" if use_mlx else "0.6GB",
+        "download_size_gb": 0.30 if use_mlx else 0.60,
+        "memory_footprint_gb": footprint_gb,
+        "effective_llm_ram_gb": max(0.0, round(effective_ram - footprint_gb, 2)),
+        "status": "recommended",
+        "load_status": "ready",
+        "supported": True,
+        "recommended_default": True,
+        "display_priority": 72,
+        "reason": f"저사양 PC ({int(round(effective_ram))}GB RAM) 맞춤 초경량 시맨틱 임베딩 모델 (Google EmbeddingGemma 300M, 768차원)",
+    }

package/latticeai/services/model_capability_registry.py

@@ -43,6 +43,13 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional
 
+from .embedding_recommendation import (
+    build_embedding_capabilities,
+)
+from .embedding_recommendation import (
+    recommend_embedding_for_hardware as _rec_embedding_for_hardware,
+)
+
 
 @dataclass(frozen=True)
 class HardwareProfile:
@@ -109,6 +116,9 @@ class ModelCapability:
     # UI / rec hints
     recommended_default: bool = False
     display_priority: int = 100
+    category: str = "chat"
+    task: str = "chat"
+    dimensions: Optional[int] = None
 
     def to_legacy_dict(self) -> Dict[str, Any]:
         """Exact shape expected by older ENGINE_MODEL_CATALOG consumers + extra 5.2 fields."""
@@ -123,6 +133,9 @@ class ModelCapability:
             "modality": self.modality,
             "architecture": self.architecture,
             "lifecycle": self.lifecycle,
+            "category": self.category,
+            "task": self.task,
+            "role": "embedding" if self.category == "embedding" else "chat",
             "source_country": self.source_country,
             "source_company": self.source_company,
             "execution_method": self.execution_method,
@@ -162,6 +175,8 @@ class ModelCapability:
             },
             "recommended_default": self.recommended_default,
         }
+        if self.dimensions is not None:
+            base["dimensions"] = self.dimensions
         return base
 
 
@@ -346,6 +361,32 @@ _REGISTRY: List[ModelCapability] = [
     ),
 
     # ── MoE tier (32GB+ RAM) ─────────────────────────────────────────────────
+    ModelCapability(
+        id="mlx-community/gemma-4-26B-A4B-it-qat-4bit",
+        hf_repo_id="mlx-community/gemma-4-26B-A4B-it-qat-4bit",
+        name="Gemma 4 26B A4B QAT Instruct",
+        family="Gemma 4",
+        tag="local-vlm",
+        size="15.6GB",
+        architecture="gemma4",
+        download_size_gb=15.64,
+        quantization="4bit",
+        provider_hints=["local_mlx", "ollama", "vllm", "lmstudio", "llamacpp"],
+        download_strategy="hf_hub",
+        load_strategy="mlx_vlm",
+        hardware=HardwareProfile(
+            min_ram_gb=22.0, recommended_ram_gb=32.0, apple_silicon_pref=True,
+            notes="Quantization-Aware Trained (QAT) 4-bit MoE with 8-bit shared MLP and router layers; higher accuracy than standard 4-bit PTQ on 32GB+ Apple Silicon.",
+        ),
+        source_country="미국", source_company="Google",
+        verification=VerificationStatus(
+            hf_exists=True, hf_last_checked="2026-11-11", has_config=True, has_tokenizer=True,
+            has_weights_hint=True, pipeline_tag="image-text-to-text", likes=9, license="apache-2.0",
+            notes="library_name=mlx, ungated, 3 safetensors shards, official Google QAT base.",
+            verified_by="hf-api-light",
+        ),
+        display_priority=48,
+    ),
     ModelCapability(
         id="mlx-community/gemma-4-26b-a4b-it-4bit",
         hf_repo_id="mlx-community/gemma-4-26b-a4b-it-4bit",
@@ -371,6 +412,32 @@ _REGISTRY: List[ModelCapability] = [
         ),
         display_priority=50,
     ),
+    ModelCapability(
+        id="mlx-community/gemma-4-26B-A4B-it-qat-OptiQ-4bit",
+        hf_repo_id="mlx-community/gemma-4-26B-A4B-it-qat-OptiQ-4bit",
+        name="Gemma 4 26B A4B QAT OptiQ Instruct",
+        family="Gemma 4",
+        tag="local-vlm",
+        size="21.9GB",
+        architecture="gemma4",
+        download_size_gb=21.89,
+        quantization="OptiQ-4bit",
+        provider_hints=["local_mlx"],
+        download_strategy="hf_hub",
+        load_strategy="mlx_vlm",
+        hardware=HardwareProfile(
+            min_ram_gb=28.0, recommended_ram_gb=48.0, apple_silicon_pref=True,
+            notes="Sensitivity-guided mixed 4-bit/8-bit OptiQ quantization built on Google's QAT Gemma 4 26B A4B base for higher reasoning and tool-calling fidelity.",
+        ),
+        source_country="미국", source_company="Google",
+        verification=VerificationStatus(
+            hf_exists=True, hf_last_checked="2026-11-11", has_config=True, has_tokenizer=True,
+            has_weights_hint=True, pipeline_tag="text-generation", likes=4, license="apache-2.0",
+            notes="library_name=mlx, ungated, 5 safetensors shards, mlx-optiq sensitivity-guided mixed 4/8-bit.",
+            verified_by="hf-api-light",
+        ),
+        display_priority=51,
+    ),
     ModelCapability(
         id="mlx-community/Qwen3.6-35B-A3B-4bit",
         hf_repo_id="mlx-community/Qwen3.6-35B-A3B-4bit",
@@ -398,6 +465,31 @@ _REGISTRY: List[ModelCapability] = [
     ),
 
     # ── Large tier (48GB+ RAM) ───────────────────────────────────────────────
+    ModelCapability(
+        id="mlx-community/Qwen3.8-27B-4bit",
+        hf_repo_id="mlx-community/Qwen3.8-27B-4bit",
+        name="Qwen3.8 27B",
+        family="Qwen3.8",
+        tag="local-vlm",
+        size="16.1GB",
+        architecture="qwen3_5",
+        download_size_gb=16.08,
+        quantization="4bit",
+        provider_hints=["local_mlx", "ollama", "vllm", "lmstudio", "llamacpp"],
+        download_strategy="hf_hub",
+        load_strategy="mlx_vlm",
+        hardware=HardwareProfile(
+            min_ram_gb=24.0, recommended_ram_gb=48.0, apple_silicon_pref=True,
+            notes="Latest Qwen 3.8 27B dense multimodal model; higher coding, reasoning, and agentic tool accuracy than Qwen 3.6 27B at identical 16.1GB 4-bit footprint.",
+        ),
+        source_country="중국", source_company="Alibaba",
+        verification=VerificationStatus(
+            hf_exists=True, hf_last_checked="2026-11-11", has_config=True, has_tokenizer=True,
+            has_weights_hint=True, pipeline_tag="image-text-to-text", likes=237, license="apache-2.0",
+            notes="library_name=mlx, ungated, 3 safetensors shards.", verified_by="hf-api-light",
+        ),
+        display_priority=52,
+    ),
     ModelCapability(
         id="mlx-community/Qwen3.6-27B-4bit",
         hf_repo_id="mlx-community/Qwen3.6-27B-4bit",
@@ -449,6 +541,7 @@ _REGISTRY: List[ModelCapability] = [
         display_priority=60,
     ),
 ]
+_REGISTRY.extend(build_embedding_capabilities(ModelCapability, HardwareProfile, VerificationStatus))
 
 
 # ── Recognised-only entries (LEGACY) ──────────────────────────────────────────
@@ -706,3 +799,24 @@ def get_verified_models() -> List[Dict[str, Any]]:
         if c.verification.hf_exists and c.verification.has_config and c.verification.has_tokenizer
     ]
 
+
+def get_embedding_capabilities() -> List[ModelCapability]:
+    """Return recommended embedding model capabilities (Google EmbeddingGemma 2 / 300M)."""
+    return [c for c in _REGISTRY if c.category == "embedding"]
+
+
+def recommend_embedding_for_hardware(
+    *,
+    ram_gb: Optional[float] = None,
+    apple_silicon: bool = False,
+    cuda: bool = False,
+) -> Dict[str, Any]:
+    """Return a PC-tailored embedding model recommendation accounting for RAM & accelerator."""
+    return _rec_embedding_for_hardware(
+        ram_gb=ram_gb,
+        apple_silicon=apple_silicon,
+        cuda=cuda,
+        get_capability_fn=get_capability,
+    )
+
+

package/latticeai/services/model_catalog.py

@@ -26,9 +26,15 @@ from latticeai.services.model_capability_registry import (
 from latticeai.services.model_capability_registry import (
     get_capability as _get_capability,
 )
+from latticeai.services.model_capability_registry import (
+    get_embedding_capabilities as _get_embedding_capabilities,
+)
 from latticeai.services.model_capability_registry import (
     get_verified_models as _get_verified_models,
 )
+from latticeai.services.model_capability_registry import (
+    recommend_embedding_for_hardware as _recommend_embedding_for_hardware,
+)
 
 ENGINE_INSTALLERS: Dict[str, Dict[str, Any]] = {
     "local_mlx": {
@@ -135,15 +141,28 @@ _ENGINE_ROUTES: Dict[str, Dict[str, str]] = {
         "mlx-community/gemma-4-12B-it-4bit", "ggml-org/gemma-4-12B-it-GGUF", "google/gemma-4-12B-it",
         ollama_tag="Q4_0",
     ),
+    "mlx-community/gemma-4-26B-A4B-it-qat-4bit": _gguf_routes(
+        "mlx-community/gemma-4-26B-A4B-it-qat-4bit", "google/gemma-4-26B-A4B-it-qat-q4_0-gguf",
+        "google/gemma-4-26B-A4B-it-qat-q4_0-unquantized",
+        ollama_tag="Q4_0",
+    ),
     "mlx-community/gemma-4-26b-a4b-it-4bit": _gguf_routes(
         "mlx-community/gemma-4-26b-a4b-it-4bit", "ggml-org/gemma-4-26B-A4B-it-GGUF",
         "google/gemma-4-26B-A4B-it",
         ollama_tag="Q4_0",
     ),
+    "mlx-community/gemma-4-26B-A4B-it-qat-OptiQ-4bit": _gguf_routes(
+        "mlx-community/gemma-4-26B-A4B-it-qat-OptiQ-4bit", "unsloth/gemma-4-26B-A4B-it-GGUF",
+        "google/gemma-4-26B-A4B-it-qat-q4_0-unquantized",
+        ollama_tag="Q4_0",
+    ),
     "mlx-community/gemma-4-31b-it-4bit": _gguf_routes(
         "mlx-community/gemma-4-31b-it-4bit", "ggml-org/gemma-4-31B-it-GGUF", "google/gemma-4-31B-it",
         ollama_tag="Q4_0",
     ),
+    "mlx-community/Qwen3.8-27B-4bit": _gguf_routes(
+        "mlx-community/Qwen3.8-27B-4bit", "ggml-org/Qwen3.8-27B-GGUF", "Qwen/Qwen3.8-27B",
+    ),
     "mlx-community/Qwen3.6-27B-4bit": _gguf_routes(
         "mlx-community/Qwen3.6-27B-4bit", "ggml-org/Qwen3.6-27B-GGUF", "Qwen/Qwen3.6-27B",
     ),
@@ -157,6 +176,18 @@ _ENGINE_ROUTES: Dict[str, Dict[str, str]] = {
     "mlx-community/Qwen3.6-35B-A3B-4bit": _gguf_routes(
         "mlx-community/Qwen3.6-35B-A3B-4bit", "ggml-org/Qwen3.6-35B-A3B-GGUF", "Qwen/Qwen3.6-35B-A3B",
     ),
+    "google/embeddinggemma-2": _gguf_routes(
+        "google/embeddinggemma-2", "ggml-org/embeddinggemma-2-GGUF", "google/embeddinggemma-2",
+    ),
+    "mlx-community/embeddinggemma-2-4bit": _gguf_routes(
+        "mlx-community/embeddinggemma-2-4bit", "mlx-community/embeddinggemma-2-4bit-GGUF", "mlx-community/embeddinggemma-2-4bit",
+    ),
+    "google/embeddinggemma-300m": _gguf_routes(
+        "google/embeddinggemma-300m", "ggml-org/embeddinggemma-300m-GGUF", "google/embeddinggemma-300m",
+    ),
+    "mlx-community/embeddinggemma-300m-4bit": _gguf_routes(
+        "mlx-community/embeddinggemma-300m-4bit", "mlx-community/embeddinggemma-300m-4bit-GGUF", "mlx-community/embeddinggemma-300m-4bit",
+    ),
 }
 
 # Names people actually type that are not the repo's own short name. Kept
@@ -164,6 +195,13 @@ _ENGINE_ROUTES: Dict[str, Dict[str, str]] = {
 # is no other Gemma 4 26B — and resolving that to nothing would be pedantry.
 _COMMON_MISNAMES: Dict[str, str] = {
     "gemma-4-26b-it-4bit": "mlx-community/gemma-4-26b-a4b-it-4bit",
+    "gemma-4-26b-qat-4bit": "mlx-community/gemma-4-26B-A4B-it-qat-4bit",
+    "gemma-4-26b-a4b-qat-4bit": "mlx-community/gemma-4-26B-A4B-it-qat-4bit",
+    "gemma-4-26b-optiq-4bit": "mlx-community/gemma-4-26B-A4B-it-qat-OptiQ-4bit",
+    "qwen-3.8-27b-4bit": "mlx-community/Qwen3.8-27B-4bit",
+    "qwen3.8-27b": "mlx-community/Qwen3.8-27B-4bit",
+    "embeddinggemma2": "google/embeddinggemma-2",
+    "embeddinggemma-2-hf": "google/embeddinggemma-2",
 }
 
 # Keyed by both the lowercase short name ("gemma-4-12b-it-4bit") and the
@@ -180,7 +218,9 @@ MODEL_ENGINE_ALIASES: Dict[str, Dict[str, str]] = {
 # Also expose registry helpers directly from here for consumers who want the rich objects
 get_all_capabilities = _get_all_capabilities
 get_capability = _get_capability
+get_embedding_capabilities = _get_embedding_capabilities
 get_verified_models = _get_verified_models
+recommend_embedding_for_hardware = _recommend_embedding_for_hardware
 
 _VERSIONED_MODEL_PATTERNS = (
     ("gemma", re.compile(r"\bgemma[-\s]?(\d+(?:\.\d+)?)", re.IGNORECASE)),
@@ -195,6 +235,8 @@ def _version_tuple(raw: str) -> tuple[int, ...]:
 
 def _model_family_version(model: Dict[str, Any]) -> Optional[tuple[str, tuple[int, ...]]]:
     text = " ".join(str(model.get(key) or "") for key in ("family", "name", "id"))
+    if "embeddinggemma" in text.lower() or model.get("category") == "embedding" or model.get("task") == "embedding":
+        return None
     for family, pattern in _VERSIONED_MODEL_PATTERNS:
         match = pattern.search(text)
         if match:
@@ -252,6 +294,8 @@ _BLOCKED_CATALOG_FRAGMENTS = (
 
 def _is_blocked_catalog_id(model: Dict[str, Any]) -> bool:
     ident = str(model.get("id") or "").lower()
+    if "embeddinggemma" in ident:
+        return False
     return any(fragment in ident for fragment in _BLOCKED_CATALOG_FRAGMENTS)
 
 
@@ -293,3 +337,107 @@ def _finalize_engine_catalog(
 
 
 ENGINE_MODEL_CATALOG = _finalize_engine_catalog(_RAW_ENGINE_MODEL_CATALOG)
+
+
+def recommend_models_for_pc(
+    *,
+    ram_gb: float = 16.0,
+    apple_silicon: bool = True,
+    cuda: bool = False,
+    engine: str = "local_mlx",
+) -> Dict[str, Any]:
+    """Compute PC-tailored model recommendations including EmbeddingGemma 2.
+
+    Evaluates the system RAM/VRAM budget while accounting for the embedding
+    model's memory footprint (``google/embeddinggemma-2`` uses ~0.5 GB in 4-bit
+    MLX / ~1.5 GB in FP16 HF; ``google/embeddinggemma-300m`` uses ~0.3 GB) so
+    the recommended LLM + embedding model setup fits comfortably on the host.
+    """
+    embedding_rec = recommend_embedding_for_hardware(
+        ram_gb=ram_gb,
+        apple_silicon=apple_silicon,
+        cuda=cuda,
+    )
+    embedding_ram_gb = float(embedding_rec.get("memory_footprint_gb") or 0.5)
+    effective_llm_ram_gb = max(0.0, float(ram_gb) - embedding_ram_gb)
+
+    catalog_rows = list(ENGINE_MODEL_CATALOG.get(engine) or ENGINE_MODEL_CATALOG.get("local_mlx") or [])
+    models_out: List[Dict[str, Any]] = []
+    chat_candidates: List[Dict[str, Any]] = []
+
+    for row in catalog_rows:
+        entry = dict(row)
+        category = str(entry.get("category") or "chat")
+        min_ram = float(entry.get("min_ram_gb") or 4.0)
+        rec_ram = float(entry.get("recommended_ram_gb") or max(min_ram, 8.0))
+        dl_gb = float(entry.get("download_size_gb") or 0.0)
+        if category == "embedding":
+            fits = float(ram_gb) + 0.01 >= min_ram
+            comfortable = float(ram_gb) + 0.01 >= rec_ram
+            status = "recommended" if comfortable else ("compatible" if fits else "not_recommended")
+            entry["compatibility"] = {
+                "status": status,
+                "reason": embedding_rec.get("reason") if status != "not_recommended" else f"최소 {min_ram:.0f}GB RAM이 필요합니다.",
+                "min_ram_gb": min_ram,
+                "recommended_ram_gb": rec_ram,
+            }
+            models_out.append(entry)
+            continue
+
+        # Account for the embedding model footprint when evaluating LLM fit.
+        exceeds_combined = dl_gb > 0.0 and (dl_gb + embedding_ram_gb) > float(ram_gb)
+        if exceeds_combined or effective_llm_ram_gb + 0.01 < min_ram:
+            status = "not_recommended"
+            reason = (
+                f"임베딩 모델({embedding_rec['id']}, ~{embedding_ram_gb:.1f}GB)과 함께 실행 시 "
+                f"최소 {min_ram + embedding_ram_gb:.1f}GB RAM이 필요합니다 (현재 {ram_gb:.1f}GB)."
+            )
+        elif effective_llm_ram_gb + 0.01 >= rec_ram or float(ram_gb) + 0.01 >= rec_ram:
+            status = "recommended"
+            reason = (
+                f"{ram_gb:.0f}GB RAM 환경에서 {embedding_rec['name']} (~{embedding_ram_gb:.1f}GB) 임베딩 모델과 "
+                f"동시에 여유 있게 실행됩니다 (권장 {rec_ram:.0f}GB)."
+            )
+        else:
+            status = "compatible"
+            reason = (
+                f"실행 가능하지만 임베딩 모델(~{embedding_ram_gb:.1f}GB) 병행 시 메모리가 빠듯할 수 있습니다 "
+                f"(최소 {min_ram:.0f}GB / 권장 {rec_ram:.0f}GB)."
+            )
+        entry["compatibility"] = {
+            "status": status,
+            "reason": reason,
+            "min_ram_gb": min_ram,
+            "recommended_ram_gb": rec_ram,
+            "embedding_reserved_ram_gb": embedding_ram_gb,
+        }
+        models_out.append(entry)
+        if status in {"recommended", "compatible"}:
+            chat_candidates.append(entry)
+
+    # Ensure the PC-tailored embedding recommendation is present in models_out
+    if not any(str(m.get("category") or "") == "embedding" for m in models_out):
+        models_out.append(dict(embedding_rec))
+
+    chat_candidates.sort(
+        key=lambda m: (
+            0 if m.get("compatibility", {}).get("status") == "recommended" else 1,
+            -float(m.get("recommended_ram_gb") or 0.0),
+            0 if m.get("recommended_default") else 1,
+            int(m.get("recommendation_priority") or 99),
+        )
+    )
+    top_pick = chat_candidates[0] if chat_candidates else None
+
+    return {
+        "ram_gb": float(ram_gb),
+        "effective_ram_gb": round(effective_llm_ram_gb, 2),
+        "embedding_reserved_ram_gb": embedding_ram_gb,
+        "apple_silicon": bool(apple_silicon),
+        "cuda": bool(cuda),
+        "top_pick": top_pick,
+        "embedding_model": embedding_rec["id"],
+        "embedding_recommendation": embedding_rec,
+        "models": models_out,
+    }
+

package/latticeai/services/model_engines.py

@@ -112,6 +112,8 @@ def _json_request(
     payload: Optional[Dict[str, Any]] = None,
     timeout: float = 10.0,
 ) -> Dict[str, Any]:
+    if not str(url).startswith(("http://", "https://")):
+        raise ValueError(f"Unsupported URL scheme in {url!r}")
     data = None
     req_headers = dict(headers or {})
     if payload is not None:
@@ -225,7 +227,7 @@ def get_openai_compatible_server_models(provider: str) -> List[str]:
     config = OPENAI_COMPATIBLE_PROVIDERS.get(provider) or {}
     base_url = os.getenv(config.get("base_url_env", "")) if config.get("base_url_env") else None
     base_url = (base_url or config.get("base_url") or "").rstrip("/")
-    if not base_url:
+    if not base_url or not base_url.startswith(("http://", "https://")):
         return []
 
     api_key = os.getenv(config.get("env_key", "")) or config.get("api_key_fallback") or provider

package/latticeai/services/product_readiness.py

@@ -28,7 +28,7 @@ from typing import Any, Dict, List
 
 from latticeai.services.architecture_readiness import architecture_readiness
 
-PRODUCT_VERSION_TARGET = "12.3.0"
+PRODUCT_VERSION_TARGET = "12.5.0"
 
 
 @dataclass(frozen=True)