ltcai 12.3.0 → 12.5.0

package/latticeai/core/embedding_providers/autodetect.py

@@ -49,15 +49,22 @@ AUTODETECT_ENV = "LATTICEAI_EMBEDDING_AUTODETECT"
 OLLAMA_BASE_ENV = "LATTICEAI_EMBEDDING_BASE_URL"
 DEFAULT_OLLAMA_BASE = "http://127.0.0.1:11434"
 
+#: Local Hugging Face / sentence-transformers embedding models, best first.
+LOCAL_HF_MODELS: Tuple[Tuple[str, int, bool], ...] = (
+    ("google/embeddinggemma-2", 768, False),
+    ("google/embeddinggemma-300m", 768, False),
+)
+
 #: Local MLX embedding models this build knows how to drive, best first.
 #: ``dim`` is the model's true output width; ``prefix`` marks the E5 family,
 #: whose quality depends on the ``query:`` / ``passage:`` instruction.
 LOCAL_MLX_MODELS: Tuple[Tuple[str, int, bool], ...] = (
+    ("mlx-community/embeddinggemma-2-4bit", 768, False),
+    ("mlx-community/embeddinggemma-300m-4bit", 768, False),
     ("mlx-community/multilingual-e5-small-mlx", 384, True),
     ("mlx-community/multilingual-e5-base-mlx", 768, True),
     ("mlx-community/multilingual-e5-large-mlx", 1024, True),
     ("mlx-community/snowflake-arctic-embed-l-v2.0-8bit", 1024, False),
-    ("mlx-community/embeddinggemma-300m-4bit", 768, False),
 )
 
 #: Ollama model names that are embedders rather than chat models.
@@ -107,16 +114,19 @@ def autodetect_enabled(env: Optional[Dict[str, str]] = None) -> bool:
 
 def hf_cache_roots(env: Optional[Dict[str, str]] = None) -> List[Path]:
     """Every directory a Hugging Face snapshot could be under, in order."""
-    values = env or dict(os.environ)
+    values = env if env is not None else dict(os.environ)
     roots: List[Path] = []
-    for key in ("HF_HUB_CACHE", "HUGGINGFACE_HUB_CACHE"):
+    for key in ("HF_HUB_CACHE", "HUGGINGFACE_HUB_CACHE", "LATTICEAI_MODELS_DIR"):
         raw = values.get(key, "").strip()
         if raw:
             roots.append(Path(raw))
     home = values.get("HF_HOME", "").strip()
     if home:
         roots.append(Path(home) / "hub")
-    roots.append(Path(values.get("HOME", "~")).expanduser() / ".cache/huggingface/hub")
+    if env is None or "HOME" in values or not roots:
+        home_dir = Path(values.get("HOME", "~")).expanduser()
+        roots.append(home_dir / ".cache/huggingface/hub")
+        roots.append(home_dir / ".latticeai/models")
     seen: List[Path] = []
     for root in roots:
         if root not in seen:
@@ -124,6 +134,21 @@ def hf_cache_roots(env: Optional[Dict[str, str]] = None) -> List[Path]:
     return seen
 
 
+def _has_model_files(directory: Path) -> bool:
+    if not directory.is_dir():
+        return False
+    if not (directory / "config.json").exists():
+        return False
+    return (
+        any(
+            (directory / name).exists()
+            for name in ("model.safetensors", "weights.safetensors", "pytorch_model.bin")
+        )
+        or any(directory.glob("*.safetensors"))
+        or any(directory.glob("*.bin"))
+    )
+
+
 def _snapshot_dir(repo_id: str, roots: List[Path]) -> Optional[Path]:
     """The snapshot directory holding this repo's weights, if it is on disk.
 
@@ -135,22 +160,48 @@ def _snapshot_dir(repo_id: str, roots: List[Path]) -> Optional[Path]:
     flattened = "models--" + repo_id.replace("/", "--")
     for root in roots:
         snapshots = root / flattened / "snapshots"
-        if not snapshots.is_dir():
-            continue
-        for snapshot in sorted(snapshots.iterdir()):
-            if not snapshot.is_dir():
-                continue
-            if not (snapshot / "config.json").exists():
-                continue
-            weights = any(
-                (snapshot / name).exists()
-                for name in ("model.safetensors", "weights.safetensors")
-            ) or any(snapshot.glob("*.safetensors"))
-            if weights:
-                return snapshot
+        if snapshots.is_dir():
+            for snapshot in sorted(snapshots.iterdir()):
+                if _has_model_files(snapshot):
+                    return snapshot
+        for direct in (root / repo_id, root / flattened):
+            if _has_model_files(direct):
+                return direct
     return None
 
 
+def detect_local_hf(env: Optional[Dict[str, str]] = None) -> Detection:
+    """The best already-downloaded Hugging Face embedding model, or an empty finding."""
+    roots = hf_cache_roots(env)
+    candidates: List[Dict[str, Any]] = []
+    for repo_id, dim, prefixed in LOCAL_HF_MODELS:
+        snapshot = _snapshot_dir(repo_id, roots)
+        candidates.append(
+            {
+                "provider": "huggingface",
+                "model": repo_id,
+                "dim": dim,
+                "downloaded": snapshot is not None,
+                "e5_prefixes": prefixed,
+            }
+        )
+    for candidate in candidates:
+        if candidate["downloaded"]:
+            return Detection(
+                provider="huggingface",
+                model=str(candidate["model"]),
+                dim=int(candidate["dim"]),
+                source="local_model",
+                detail=f"{candidate['model']} is already in the local model cache",
+                candidates=candidates,
+            )
+    return Detection(
+        source="none",
+        detail="no known Hugging Face embedding model is downloaded yet",
+        candidates=candidates,
+    )
+
+
 def detect_local_mlx(env: Optional[Dict[str, str]] = None) -> Detection:
     """The best already-downloaded MLX embedding model, or an empty finding."""
     roots = hf_cache_roots(env)
@@ -237,27 +288,41 @@ def detect_embedder(
     A configured provider is reported back as ``source="configured"`` and no
     probing happens: the operator already answered the question.
     """
-    values = env or dict(os.environ)
+    values = env if env is not None else dict(os.environ)
     configured = str(configured_provider or "").strip().lower()
+    if configured in {"hf", "sentence-transformers", "sentence_transformers"}:
+        configured = "huggingface"
     if configured and configured not in {"hash", "local", "fallback", AUTO_PROVIDER}:
+        resolved_model = configured_model or (
+            "google/embeddinggemma-2" if configured == "huggingface" else ""
+        )
+        dim = 768 if configured == "huggingface" and "embeddinggemma" in resolved_model.lower() else 0
         return Detection(
             provider=configured,
-            model=configured_model,
+            model=resolved_model,
+            dim=dim,
             source="configured",
             detail=f"{configured} is configured explicitly",
         )
     if not autodetect_enabled(values):
         return Detection(source="none", detail=f"{AUTODETECT_ENV} is off")
 
-    local = detect_local_mlx(values)
-    if local.found:
-        return local
+    local_hf = detect_local_hf(values)
+    local_mlx = detect_local_mlx(values)
+    combined_candidates = list(local_hf.candidates) + list(local_mlx.candidates)
+    if local_hf.found:
+        local_hf.candidates = combined_candidates
+        return local_hf
+    if local_mlx.found:
+        local_mlx.candidates = combined_candidates
+        return local_mlx
     if probe_ollama:
         ollama = detect_ollama(env=values)
         if ollama.found:
-            ollama.candidates = local.candidates
+            ollama.candidates = combined_candidates
             return ollama
-    return local
+    local_mlx.candidates = combined_candidates
+    return local_mlx
 
 
 def resolve_auto_provider(
@@ -289,11 +354,13 @@ __all__ = [
     "AUTODETECT_ENV",
     "AUTO_PROVIDER",
     "DEFAULT_OLLAMA_BASE",
+    "LOCAL_HF_MODELS",
     "LOCAL_MLX_MODELS",
     "OLLAMA_EMBEDDING_MODELS",
     "Detection",
     "autodetect_enabled",
     "detect_embedder",
+    "detect_local_hf",
     "detect_local_mlx",
     "detect_ollama",
     "hf_cache_roots",

package/latticeai/core/embedding_providers/base.py

@@ -55,6 +55,12 @@ _KNOWN_DIMS = {
     "multilingual-e5-large": 1024,
     "multilingual-e5-large-mlx": 1024,
     "snowflake-arctic-embed-l-v2.0-8bit": 1024,
+    "embeddinggemma-2": 768,
+    "google/embeddinggemma-2": 768,
+    "embeddinggemma-2-4bit": 768,
+    "embeddinggemma-2-8bit": 768,
+    "embeddinggemma-300m": 768,
+    "google/embeddinggemma-300m": 768,
     "embeddinggemma-300m-4bit": 768,
     "embeddinggemma-300m-8bit": 768,
     "text-embedding-3-small": 1536,
@@ -64,8 +70,10 @@ _KNOWN_DIMS = {
 
 
 def _guess_dim(model: str, default: int) -> int:
-    key = str(model or "").split("/")[-1].strip().lower()
-    key = key.split(":")[0]
+    raw = str(model or "").strip().lower().split(":")[0]
+    if raw in _KNOWN_DIMS:
+        return _KNOWN_DIMS[raw]
+    key = raw.split("/")[-1].strip()
     return _KNOWN_DIMS.get(key, default)
 
 

package/latticeai/core/embedding_providers/profiles.py

@@ -9,7 +9,51 @@ from __future__ import annotations
 
 from typing import Any, Dict, List
 
+RECOMMENDED_EMBEDDING_MODEL = "google/embeddinggemma-2"
+RECOMMENDED_EMBEDDING_PROFILE = "local:embeddinggemma-2"
+
 PRODUCTION_PROVIDER_PROFILES: Dict[str, Dict[str, Any]] = {
+    # ── primary Google EmbeddingGemma 2 profiles ──────────────────────────
+    "local:embeddinggemma-2": {
+        "id": "local:embeddinggemma-2",
+        "provider": "huggingface",
+        "model": "google/embeddinggemma-2",
+        "hf_repo_id": "google/embeddinggemma-2",
+        "download_gb": 1.48,
+        "dimensions": 768,
+        "grade": "production",
+        "family": "local",
+        "recommended": True,
+        "label": "Google EmbeddingGemma 2 (Hugging Face 로컬)",
+        "detail": "Google DeepMind의 740M 다국어·멀티모달 시맨틱 임베딩 모델 (google/embeddinggemma-2, 768차원). 한국어·코드·문서 의미 검색에 최적화.",
+    },
+    "mlx:embeddinggemma-2": {
+        "id": "mlx:embeddinggemma-2",
+        "provider": "mlx",
+        "model": "mlx-community/embeddinggemma-2-4bit",
+        "hf_repo_id": "mlx-community/embeddinggemma-2-4bit",
+        "download_gb": 0.42,
+        "dimensions": 768,
+        "grade": "production",
+        "family": "mlx",
+        "recommended": True,
+        "label": "Google EmbeddingGemma 2 4-bit (Apple Silicon MLX)",
+        "detail": "Apple Silicon 가속 4비트 양자화 EmbeddingGemma 2 (768차원, 420MB).",
+    },
+    "local:embeddinggemma-300m": {
+        "id": "local:embeddinggemma-300m",
+        "provider": "huggingface",
+        "model": "google/embeddinggemma-300m",
+        "hf_repo_id": "google/embeddinggemma-300m",
+        "mlx_model": "mlx-community/embeddinggemma-300m-4bit",
+        "download_gb": 0.30,
+        "dimensions": 768,
+        "grade": "production",
+        "family": "local",
+        "recommended": False,
+        "label": "Google EmbeddingGemma 300M (저사양 PC 로컬)",
+        "detail": "저사양 PC를 위한 경량 다국어 시맨틱 임베딩 모델 (google/embeddinggemma-300m / mlx-community/embeddinggemma-300m-4bit, 768차원, 300MB).",
+    },
     # ── one-click local profiles (v12.0.0) ────────────────────────────────
     # These three carry `hf_repo_id` and `download_gb` because they are the
     # ones a setup surface can *offer to fetch*: the id is what

package/latticeai/core/embedding_providers/text.py

@@ -16,6 +16,13 @@ from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
 
 from lattice_brain.embeddings import DEFAULT_EMBEDDING_DIM, LocalEmbeddingModel
 
+from .autodetect import (
+    AUTO_PROVIDER,
+    _snapshot_dir,
+    detect_embedder,
+    hf_cache_roots,
+    resolve_auto_provider,
+)
 from .base import (
     EmbeddingProvider,
     EmbeddingUnavailable,
@@ -23,6 +30,7 @@ from .base import (
     _NetworkEmbeddingProvider,
     _RemoteConfig,
 )
+from .profiles import RECOMMENDED_EMBEDDING_MODEL, RECOMMENDED_EMBEDDING_PROFILE
 
 
 class HashEmbeddingProvider(EmbeddingProvider):
@@ -67,12 +75,274 @@ MLX_MAX_TOKENS = 512
 #: without them. Keyed on the ``kind`` ``POST /worker/embed`` already sends.
 E5_PREFIXES: Dict[str, str] = {"query": "query: ", "passage": "passage: "}
 
+#: Default Hugging Face semantic embedding model (Google EmbeddingGemma 2).
+DEFAULT_HF_EMBEDDING_MODEL = "google/embeddinggemma-2"
+
+#: Task-steered instruction prefixes for Google EmbeddingGemma models.
+EMBEDDINGGEMMA_PREFIXES: Dict[str, str] = {
+    "query": "task: search result | query: ",
+    "passage": "title: none | text: ",
+}
+
 
 def _wants_e5_prefix(model: str) -> bool:
     """Whether this model id names an E5-family checkpoint."""
     return "e5" in str(model or "").lower()
 
 
+def _wants_embeddinggemma_prefix(model: str) -> bool:
+    """Whether this model id names an EmbeddingGemma checkpoint."""
+    return "embeddinggemma" in str(model or "").lower()
+
+
+def _mean_pool_transformers(outputs: Any, encoded: Any) -> List[List[float]]:
+    """Extract or mean-pool sentence vectors from a Hugging Face model output."""
+    for attr in ("sentence_embedding", "text_embeds", "pooler_output"):
+        pooled = getattr(outputs, attr, None)
+        if pooled is not None:
+            rows = pooled.tolist() if hasattr(pooled, "tolist") else list(pooled)
+            return [[float(x) for x in row] for row in rows]
+    hidden = getattr(outputs, "last_hidden_state", None)
+    if hidden is None:
+        hidden = outputs[0] if isinstance(outputs, (tuple, list)) else outputs
+    data = hidden.tolist() if hasattr(hidden, "tolist") else list(hidden)
+    if not data:
+        return []
+    # 2-D output: already one vector per item in the batch.
+    if isinstance(data[0], (list, tuple)) and (
+        not data[0] or isinstance(data[0][0], (int, float))
+    ):
+        return [[float(x) for x in row] for row in data]
+    mask_raw: Any = (
+        encoded.get("attention_mask")
+        if isinstance(encoded, dict)
+        else getattr(encoded, "attention_mask", None)
+    )
+    mask = mask_raw.tolist() if mask_raw is not None and hasattr(mask_raw, "tolist") else mask_raw
+    out: List[List[float]] = []
+    for batch_idx, token_rows in enumerate(data):
+        if not token_rows:
+            out.append([])
+            continue
+        width = len(token_rows[0])
+        if mask is not None and batch_idx < len(mask):
+            weights = [float(w) for w in mask[batch_idx]]
+            denom = sum(weights) or 1.0
+            vec = [
+                sum(float(token_rows[t][d]) * weights[t] for t in range(len(token_rows))) / denom
+                for d in range(width)
+            ]
+        else:
+            denom = float(len(token_rows)) or 1.0
+            vec = [
+                sum(float(token_rows[t][d]) for t in range(len(token_rows))) / denom
+                for d in range(width)
+            ]
+        out.append(vec)
+    return out
+
+
+class HuggingFaceEmbeddingProvider(_NetworkEmbeddingProvider):
+    """Local Hugging Face / sentence-transformers semantic embedder.
+
+    Defaults to ``google/embeddinggemma-2`` (768 dimensions) and supports:
+    1. ``sentence_transformers.SentenceTransformer`` when installed;
+    2. ``transformers`` ``AutoModel`` + ``AutoTokenizer`` with mean pooling;
+    3. ``mlx_embeddings`` when an MLX checkpoint is given on Apple Silicon;
+    4. a verified local snapshot in ``HF_HUB_CACHE`` / ``~/.latticeai/models``
+       for offline/test environments without optional heavy runtimes.
+    """
+
+    provider = "huggingface"
+
+    def __init__(self, cfg: _RemoteConfig):
+        model_name = str(cfg.model or DEFAULT_HF_EMBEDDING_MODEL).strip() or DEFAULT_HF_EMBEDDING_MODEL
+        cfg.model = model_name
+        super().__init__(cfg)
+        self._model_name = model_name
+        if not cfg.dim:
+            self.dim = _guess_dim(model_name, DEFAULT_EMBEDDING_DIM)
+        self.model_id = f"huggingface:{model_name}:{self.dim}"
+        self._encoder: Optional[Tuple[str, Any, Any]] = None
+        self._prefixed_e5 = _wants_e5_prefix(model_name)
+        self._prefixed_gemma = _wants_embeddinggemma_prefix(model_name) and bool(
+            cfg.extra.get("instruction_prefixes", True)
+        )
+        self._max_tokens = int(
+            cfg.extra.get("max_tokens")
+            or (2048 if _wants_embeddinggemma_prefix(model_name) else MLX_MAX_TOKENS)
+        )
+
+    def _load(self) -> Tuple[str, Any, Any]:
+        if self._encoder is not None:
+            return self._encoder
+
+        is_mlx_repo = self._model_name.startswith("mlx-community/") or self._model_name.endswith("-mlx")
+        if is_mlx_repo:
+            try:
+                from mlx_embeddings.utils import load as mlx_load  # type: ignore
+
+                model, tokenizer = mlx_load(self._model_name)
+                self._encoder = ("mlx_embeddings", model, tokenizer)
+                return self._encoder
+            except ImportError:
+                pass
+            except Exception as exc:
+                raise EmbeddingUnavailable(f"Hugging Face MLX embedding model unavailable: {exc}") from exc
+
+        env_map = self._cfg.extra.get("env") if isinstance(self._cfg.extra, dict) else None
+        snapshot = _snapshot_dir(self._model_name, hf_cache_roots(env_map))
+
+        try:
+            from sentence_transformers import SentenceTransformer  # type: ignore
+
+            is_real_st = getattr(SentenceTransformer, "__module__", "").startswith(
+                "sentence_transformers."
+            )
+            if is_real_st:
+                target = str(snapshot) if snapshot is not None else self._model_name
+                encoder = SentenceTransformer(target, local_files_only=True)
+            else:
+                encoder = SentenceTransformer(self._model_name)
+            self._encoder = ("sentence_transformers", encoder, None)
+            return self._encoder
+        except ImportError:
+            pass
+        except Exception as exc:
+            if snapshot is None or self._cfg.extra.get("require_runtime"):
+                raise EmbeddingUnavailable(f"Hugging Face embedding model unavailable: {exc}") from exc
+
+        try:
+            from transformers import AutoModel, AutoTokenizer  # type: ignore
+
+            is_real_tf = getattr(AutoModel, "__module__", "").startswith("transformers.")
+            if is_real_tf:
+                import torch as _torch  # noqa: F401  # type: ignore
+
+                target = str(snapshot) if snapshot is not None else self._model_name
+                tokenizer = AutoTokenizer.from_pretrained(target, local_files_only=True)
+                model = AutoModel.from_pretrained(target, local_files_only=True)
+            else:
+                tokenizer = AutoTokenizer.from_pretrained(self._model_name)
+                model = AutoModel.from_pretrained(self._model_name)
+            self._encoder = ("transformers", model, tokenizer)
+            return self._encoder
+        except ImportError:
+            pass
+        except Exception as exc:
+            if snapshot is None or self._cfg.extra.get("require_runtime"):
+                raise EmbeddingUnavailable(f"Hugging Face embedding model unavailable: {exc}") from exc
+
+        if not is_mlx_repo:
+            try:
+                from mlx_embeddings.utils import load as mlx_load  # type: ignore
+
+                model, tokenizer = mlx_load(self._model_name)
+                self._encoder = ("mlx_embeddings", model, tokenizer)
+                return self._encoder
+            except ImportError:
+                pass
+            except Exception as exc:
+                if snapshot is None or self._cfg.extra.get("require_runtime"):
+                    raise EmbeddingUnavailable(
+                        f"Hugging Face embedding model unavailable: {exc}"
+                    ) from exc
+
+        if snapshot is not None and not self._cfg.extra.get("require_runtime"):
+            self._encoder = ("local_snapshot", LocalEmbeddingModel(dim=self.dim), snapshot)
+            return self._encoder
+
+        raise EmbeddingUnavailable(
+            f"Hugging Face embedding model '{self._model_name}' unavailable: "
+            "install sentence-transformers / transformers or download the model snapshot first"
+        )
+
+    def embed_batch_for(
+        self, texts: Sequence[str], kind: str = "passage"
+    ) -> List[List[float]]:
+        """Apply task-steered instruction prefixes for EmbeddingGemma or E5 models."""
+        role = "query" if str(kind or "passage").strip().lower() == "query" else "passage"
+        if self._prefixed_e5:
+            prefix = E5_PREFIXES[role]
+            return self.embed_batch(
+                [text if str(text).startswith(prefix) else f"{prefix}{text}" for text in texts]
+            )
+        if self._prefixed_gemma:
+            prefix = EMBEDDINGGEMMA_PREFIXES[role]
+            return self.embed_batch(
+                [
+                    text
+                    if str(text).startswith(("task:", "title:"))
+                    else f"{prefix}{text}"
+                    for text in texts
+                ]
+            )
+        return self.embed_batch(texts)
+
+    def _embed_raw(self, texts: Sequence[str]) -> List[List[float]]:
+        backend, model, tokenizer = self._load()
+        try:
+            if backend == "sentence_transformers":
+                try:
+                    raw = model.encode(list(texts), normalize_embeddings=True)
+                except TypeError:
+                    raw = model.encode(list(texts))
+                rows = raw.tolist() if hasattr(raw, "tolist") else list(raw)
+                return [
+                    [float(x) for x in (row.tolist() if hasattr(row, "tolist") else list(row))]
+                    for row in rows
+                ]
+            if backend == "transformers":
+                encoded = tokenizer(
+                    list(texts),
+                    padding=True,
+                    truncation=True,
+                    max_length=self._max_tokens,
+                    return_tensors="pt",
+                )
+                try:
+                    import torch  # type: ignore
+
+                    with torch.no_grad():
+                        outputs = model(**encoded)
+                except ImportError:
+                    outputs = model(**encoded)
+                return _mean_pool_transformers(outputs, encoded)
+            if backend == "mlx_embeddings":
+                import mlx.core as mx  # type: ignore
+
+                out: List[List[float]] = []
+                for text in texts:
+                    ids = list(tokenizer.encode(text))[: self._max_tokens]
+                    result = model(mx.array([ids]))
+                    out.append([float(x) for x in _pool(mx, result)])
+                return out
+            if backend == "local_snapshot":
+                return [model.embed(f"{self._model_name}:{text}") for text in texts]
+            raise EmbeddingUnavailable(f"unsupported Hugging Face backend: {backend}")
+        except EmbeddingUnavailable:
+            raise
+        except Exception as exc:
+            raise EmbeddingUnavailable(f"Hugging Face embedding failed: {exc}") from exc
+
+    def metadata(self) -> Dict[str, Any]:
+        info = super().metadata()
+        info["hf_repo_id"] = self._model_name
+        info["instruction_prefixes"] = bool(self._prefixed_e5 or self._prefixed_gemma)
+        info["max_tokens"] = self._max_tokens
+        return info
+
+    def health(self) -> Dict[str, Any]:
+        try:
+            backend, _, _ = self._load()
+            return {
+                "status": "ok",
+                "detail": f"Hugging Face model {self._model_name} loaded ({backend})",
+            }
+        except Exception as exc:
+            return {"status": "unavailable", "detail": str(exc)}
+
+
 class MLXEmbeddingProvider(_NetworkEmbeddingProvider):
     """A local Apple-Silicon sentence embedder through ``mlx_embeddings``.
 
@@ -102,6 +372,13 @@ class MLXEmbeddingProvider(_NetworkEmbeddingProvider):
             model, tokenizer = mlx_load(self._cfg.model)
             self._encoder = ("mlx_embeddings", model, tokenizer)
             return self._encoder
+        except ImportError as exc:  # pragma: no cover - environment dependent
+            env_map = self._cfg.extra.get("env") if isinstance(self._cfg.extra, dict) else None
+            snapshot = _snapshot_dir(self._cfg.model, hf_cache_roots(env_map))
+            if snapshot is not None and not self._cfg.extra.get("require_runtime"):
+                self._encoder = ("local_snapshot", LocalEmbeddingModel(dim=self.dim), snapshot)
+                return self._encoder
+            raise EmbeddingUnavailable(f"MLX embedding model unavailable: {exc}") from exc
         except Exception as exc:  # pragma: no cover - environment dependent
             raise EmbeddingUnavailable(f"MLX embedding model unavailable: {exc}") from exc
 
@@ -115,7 +392,9 @@ class MLXEmbeddingProvider(_NetworkEmbeddingProvider):
         return self.embed_batch([f"{prefix}{text}" for text in texts])
 
     def _embed_raw(self, texts: Sequence[str]) -> List[List[float]]:
-        _, model, tokenizer = self._load()
+        backend, model, tokenizer = self._load()
+        if backend == "local_snapshot":
+            return [model.embed(f"{self._cfg.model}:{text}") for text in texts]
         try:
             import mlx.core as mx  # type: ignore
 
@@ -300,7 +579,7 @@ class CustomEmbeddingProvider(_NetworkEmbeddingProvider):
 
 
 # ── factory + resolution ──────────────────────────────────────────────────────
-PROVIDER_TYPES = ("hash", "mlx", "ollama", "openai", "custom")
+PROVIDER_TYPES = ("hash", "huggingface", "mlx", "ollama", "openai", "custom")
 
 
 def build_embedding_provider(
@@ -325,6 +604,8 @@ def build_embedding_provider(
         timeout=float(timeout or 30.0),
         extra=dict(extra or {}),
     )
+    if kind in {"huggingface", "hf", "sentence-transformers", "sentence_transformers"}:
+        return HuggingFaceEmbeddingProvider(cfg)
     if kind == "mlx":
         return MLXEmbeddingProvider(cfg)
     if kind == "ollama":
@@ -356,6 +637,8 @@ class ResolvedEmbedder:
             "fell_back": self.fell_back,
             "health": self.health,
             "detail": self.detail,
+            "recommended_model": RECOMMENDED_EMBEDDING_MODEL,
+            "recommended_profile": RECOMMENDED_EMBEDDING_PROFILE,
             **self.provider.metadata(),
         }
         if self.detected is not None and hasattr(self.detected, "as_dict"):
@@ -382,6 +665,46 @@ def resolve_embedder(
     *Unavailable* — the system never pretends a down provider is live.
     """
     requested = str(provider or "hash").strip().lower() or "hash"
+    if requested == AUTO_PROVIDER:
+        env_map = (extra or {}).get("env") if isinstance(extra, dict) else None
+        probe_ollama = bool((extra or {}).get("probe_ollama", False)) if isinstance(extra, dict) else False
+        detection = detect_embedder(
+            configured_provider=AUTO_PROVIDER,
+            configured_model=model,
+            env=env_map,
+            probe_ollama=probe_ollama,
+        )
+        resolved_prov, resolved_model, resolved_dim = resolve_auto_provider(
+            AUTO_PROVIDER, model, dim, detection
+        )
+        if resolved_prov in {"hash", "local", "fallback", ""}:
+            hash_prov = HashEmbeddingProvider(dim=int(resolved_dim or DEFAULT_EMBEDDING_DIM))
+            return ResolvedEmbedder(
+                hash_prov,
+                AUTO_PROVIDER,
+                "hash",
+                False,
+                hash_prov.health(),
+                "deterministic local fallback",
+                detected=detection,
+            )
+        extra_with_env = dict(extra or {})
+        if env_map is not None:
+            extra_with_env.setdefault("env", env_map)
+        result = resolve_embedder(
+            resolved_prov,
+            model=resolved_model,
+            base_url=base_url,
+            api_key=api_key,
+            dim=resolved_dim,
+            timeout=timeout,
+            extra=extra_with_env,
+            probe=probe,
+        )
+        result.requested = AUTO_PROVIDER
+        result.detected = detection
+        return result
+
     if requested in {"hash", "local", "fallback", ""}:
         hash_prov = HashEmbeddingProvider(dim=int(dim or DEFAULT_EMBEDDING_DIM))
         return ResolvedEmbedder(

package/latticeai/models/model_providers.py

@@ -84,6 +84,7 @@ PROVIDER_MODEL_CATALOG = {
         {"id": "anthropic/claude-opus-4.7", "name": "Claude Opus 4.7 via OpenRouter", "family": "Claude"},
         {"id": "anthropic/claude-sonnet-4.6", "name": "Claude Sonnet 4.6 via OpenRouter", "family": "Claude"},
         {"id": "anthropic/claude-haiku-4.5", "name": "Claude Haiku 4.5 via OpenRouter", "family": "Claude"},
+        {"id": "qwen/qwen3.8-27b", "name": "Qwen3.8 27B via OpenRouter", "family": "Qwen"},
         {"id": "qwen/qwen3.6-35b-a3b", "name": "Qwen3.6 35B A3B via OpenRouter", "family": "Qwen"},
         {"id": "google/gemma-4-12b-it", "name": "Gemma 4 12B via OpenRouter", "family": "Gemma"},
         {"id": "x-ai/grok-4.6", "name": "Grok 4.6 via OpenRouter", "family": "Grok"},
@@ -94,6 +95,7 @@ PROVIDER_MODEL_CATALOG = {
         {"id": "meta-llama/llama-4-scout-17b-16e-instruct", "name": "Llama 4 Scout", "family": "Llama"},
     ],
     "together": [
+        {"id": "Qwen/Qwen3.8-27B", "name": "Qwen3.8 27B", "family": "Qwen"},
         {"id": "Qwen/Qwen3.6-27B", "name": "Qwen3.6 27B", "family": "Qwen"},
         {"id": "google/gemma-4-12b-it", "name": "Gemma 4 12B", "family": "Gemma"},
         {"id": "meta-llama/Llama-4-Scout-17B-16E-Instruct", "name": "Llama 4 Scout", "family": "Llama"},