ltcai 12.4.0 → 12.5.0

package/README.md

@@ -12,7 +12,7 @@
 [![CD Status](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/publish.yml/badge.svg)](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/publish.yml)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-![v12.4.0 Living Brain walkthrough](output/release/v12.4.0/gifs/v12.4.0-living-brain-walkthrough.gif)
+![v12.5.0 Living Brain walkthrough](output/release/v12.5.0/gifs/v12.5.0-living-brain-walkthrough.gif)
 
 Lattice AI is a Digital Brain that lives on your computer. Chat, files,
 folders, notes, and web pages all land in one knowledge graph you own.
@@ -42,19 +42,19 @@ LTCAI                    # then open http://127.0.0.1:4825/app
 
 | | | |
 | --- | --- | --- |
-| ![Login](output/release/v12.4.0/screenshots/01-login.png) | ![Model install](output/release/v12.4.0/screenshots/03-install-load-progress.png) | ![Model library](output/release/v12.4.0/screenshots/07-model-library.png) |
+| ![Login](output/release/v12.5.0/screenshots/01-login.png) | ![Model install](output/release/v12.5.0/screenshots/03-install-load-progress.png) | ![Model library](output/release/v12.5.0/screenshots/07-model-library.png) |
 
 Screenshot index:
-[output/release/v12.4.0/SCREENSHOT_INDEX.md](output/release/v12.4.0/SCREENSHOT_INDEX.md)
+[output/release/v12.5.0/SCREENSHOT_INDEX.md](output/release/v12.5.0/SCREENSHOT_INDEX.md)
 
 ## What you can do
 
 | | |
 | --- | --- |
-| **See your Brain's story in time** — a growth curve, an activity heatmap, and each day's story ![Brain Chronicle](output/release/v12.4.0/screenshots/13-chronicle.png) | **Chat with a Brain that remembers** — every conversation grows durable, source-linked memory ![Brain Chat](output/release/v12.4.0/screenshots/04-brain-chat-home.png) |
-| **See how knowledge connects** — a real relationship graph, not a file list ![Memory Graph](output/release/v12.4.0/screenshots/05-memory-graph.png) | **Capture anything** — files, whole folders, notes, screenshots, web pages ![Capture](output/release/v12.4.0/screenshots/06-capture.png) |
-| **Automate with review** — agent changes become proposals you approve first ![Review Center](output/release/v12.4.0/screenshots/12-review-center.png) | **Pick a model in one click** — recommended local models for your hardware ![Recommended Models](output/release/v12.4.0/screenshots/02-recommended-models.png) |
-| **Watch a file become memory** — three named steps, not a pipeline diagram ![Material to memory](output/release/v12.4.0/screenshots/11-knowledge-journey.png) | **Say how much it may do alone** — one dial in plain words ![Settings](output/release/v12.4.0/screenshots/08-system.png) |
+| **See your Brain's story in time** — a growth curve, an activity heatmap, and each day's story ![Brain Chronicle](output/release/v12.5.0/screenshots/13-chronicle.png) | **Chat with a Brain that remembers** — every conversation grows durable, source-linked memory ![Brain Chat](output/release/v12.5.0/screenshots/04-brain-chat-home.png) |
+| **See how knowledge connects** — a real relationship graph, not a file list ![Memory Graph](output/release/v12.5.0/screenshots/05-memory-graph.png) | **Capture anything** — files, whole folders, notes, screenshots, web pages ![Capture](output/release/v12.5.0/screenshots/06-capture.png) |
+| **Automate with review** — agent changes become proposals you approve first ![Review Center](output/release/v12.5.0/screenshots/12-review-center.png) | **Pick a model in one click** — recommended local models for your hardware ![Recommended Models](output/release/v12.5.0/screenshots/02-recommended-models.png) |
+| **Watch a file become memory** — three named steps, not a pipeline diagram ![Material to memory](output/release/v12.5.0/screenshots/11-knowledge-journey.png) | **Say how much it may do alone** — one dial in plain words ![Settings](output/release/v12.5.0/screenshots/08-system.png) |
 
 ## Why this is yours
 
@@ -70,41 +70,27 @@ Screenshot index:
 
 ## Current Release
 
-The current release is **12.4.0 — Sharp Weight**:
-
-The local and cloud model catalog adds **Qwen 3.8 27B 4-bit** and **Gemma 4 26B
-A4B QAT / QAT-OptiQ 4-bit** builds, closes all Python (`pillow>=13,<14`) and npm
-dependency security advisories, hardens engine URL scheme validation, and scopes
-Tailwind CSS v4's oxide scanner to `frontend/`. The door is still **422
-operations / 41 families** over a **20-route worker**. Cloud is still optional
-and the default is still local.
-
-- **Qwen 3.8 27B 4-bit local & cloud integration.** Added
-  `mlx-community/Qwen3.8-27B-4bit` (`16.1GB`, `qwen3_5`), wired GGUF/HF routes
-  (`ggml-org/Qwen3.8-27B-GGUF:Q4_K_M`, `Qwen/Qwen3.8-27B`) across all 5 local
-  engines, and added `Qwen/Qwen3.8-27B` / `qwen/qwen3.8-27b` to `together` and
-  `openrouter`.
-- **Gemma 4 26B A4B QAT & QAT-OptiQ 4-bit builds.** Added
-  `mlx-community/gemma-4-26B-A4B-it-qat-4bit` (`15.6GB`, routed to Google's
-  official QAT GGUF `google/gemma-4-26B-A4B-it-qat-q4_0-gguf:Q4_0`) and
-  `mlx-community/gemma-4-26B-A4B-it-qat-OptiQ-4bit` (`21.9GB`, sensitivity-guided
-  mixed 4-bit/8-bit `mlx-optiq` build).
-- **Dependency security audit closure & runtime hardening.** Upgraded `pillow`
-  to `>=13,<14`, resolved all npm lockfile advisories in root and
-  `vscode-extension`, enforced `http(s)://` scheme checks in `model_engines`,
-  and scoped `@import "tailwindcss" source("..");` in `frontend/src/styles.css`.
+The current release is **12.5.0 — Deep Vector**:
+
+The embedding pipeline adds native **Google EmbeddingGemma 2** (`google/embeddinggemma-2`, 768-dim) support with Hugging Face mean-pooling and L2 normalization, adds **hardware-aware embedding model recommendations** that calculate host RAM/VRAM reservations before recommending LLMs, migrates screenshot pixel diffing to Pillow 13+ `get_flattened_data()`, upgrades GitHub Actions CI/CD to Node 24 native major versions, and automates full OpenAPI specification and fragment synchronization in `scripts/bump_version.py`. The door is still **422 operations / 41 families** over a **20-route worker**. Cloud is still optional and the default is still local.
+
+- **Google EmbeddingGemma 2 native integration.** Native Hugging Face embedding provider support (`google/embeddinggemma-2`, `embeddinggemma-2`, `embeddinggemma-2-4bit`, `embeddinggemma-2-8bit`, `embeddinggemma-300m`, 768-dimensional vectors) in `latticeai/core/embedding_providers/text.py` with mean pooling, L2 normalization, task instruction prefixes, and automatic semantic activation. Hash embedding fallback remains preserved when offline.
+- **Hardware-aware PC-tailored embedding recommendations.** Modularized `recommend_embedding_for_host` in `lattice-platform` and `latticeai/services/embedding_recommendation.py`. Systems with >=8GB RAM receive `google/embeddinggemma-2` with a 0.5GB–1.5GB reserved RAM budget; smaller hosts receive `google/embeddinggemma-300m`. The host probe calculates `effective_ram_gb` before LLM tier selection.
+- **Onboarding and Model Library embedding UI.** Added the PC-tailored EmbeddingGemma 2 recommendation card in `ProductFlow.tsx` with full i18n support, and surfaced Google EmbeddingGemma 2 in the Model Library (`Library.tsx`) embedding section with 1-click install and activation.
+- **Pillow 13+ flattened data & CI/CD modernisation.** Replaced Pillow 14-deprecated `diff.getdata()` calls in `scripts/check_screenshot_pixel_delta.py` with `diff.get_flattened_data()`, and pinned GitHub Actions to Node 24 native versions with `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"`.
+- **OpenAPI specification and fixture version automation.** Extended `scripts/bump_version.py` to synchronize `frontend/openapi.json`, `rust/fixtures/openapi/_envelope.json`, all 13 OpenAPI fragment files, and `rust/fixtures/openapi/_index.json` with recomputed SHA-256 digests across 49 targets.
 
 Release notes live in [docs/releases/](docs/releases/). This version:
-[docs/releases/RELEASE_NOTES_v12.4.0.md](docs/releases/RELEASE_NOTES_v12.4.0.md).
+[docs/releases/RELEASE_NOTES_v12.5.0.md](docs/releases/RELEASE_NOTES_v12.5.0.md).
 Guide: [RELEASE.md](RELEASE.md) · History: [docs/CHANGELOG.md](docs/CHANGELOG.md).
 
-Expected artifacts for 12.4.0 must use exact filenames:
+Expected artifacts for 12.5.0 must use exact filenames:
 
-- `dist/ltcai-12.4.0-py3-none-any.whl`
-- `dist/ltcai-12.4.0.tar.gz`
-- `ltcai-12.4.0.tgz`
-- `dist/ltcai-12.4.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_12.4.0_aarch64.dmg`
+- `dist/ltcai-12.5.0-py3-none-any.whl`
+- `dist/ltcai-12.5.0.tar.gz`
+- `ltcai-12.5.0.tgz`
+- `dist/ltcai-12.5.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_12.5.0_aarch64.dmg`
 
 Do not use wildcard artifact uploads. Package registry publishing remains owner-run.
 

package/docs/CHANGELOG.md

@@ -4,6 +4,19 @@ The top entry is either the current unreleased main-branch work or the current
 release line. Older entries are historical and may describe behavior as it
 existed at that release.
 
+## [12.5.0] - 2026-11-11 — Deep Vector
+
+### Added
+- Added native Hugging Face embedding provider for Google EmbeddingGemma 2 (`google/embeddinggemma-2`, `embeddinggemma-2`, `embeddinggemma-2-4bit`, `embeddinggemma-2-8bit`, `embeddinggemma-300m`, 768-dim) with mean-pooling, L2 normalization, task prefixes, and fallback protection in `latticeai/core/embedding_providers/text.py`.
+- Added hardware-aware PC-tailored embedding recommendations (`recommend_embedding_for_host`) in `rust/lattice-platform/src/modelops/models_catalog/embedding.rs` and `latticeai/services/embedding_recommendation.py` with memory reservation (0.5GB–1.5GB for Gemma 2, 0.3GB for 300M) before LLM selection.
+- Added PC-tailored EmbeddingGemma 2 recommendation card in `ProductFlow.tsx` (i18n supported) and surfaced Google EmbeddingGemma 2 in `Library.tsx` with 1-click prepare/download.
+- Added comprehensive visual E2E test suite `tests/visual/v3.all_buttons_inspection.spec.js` asserting all routes, controls, tabs, and buttons operate with 0 errors.
+
+### Changed
+- Migrated `scripts/check_screenshot_pixel_delta.py` from Pillow 14-deprecated `diff.getdata()` to `diff.get_flattened_data()`.
+- Upgraded all GitHub Actions workflows (`.github/workflows/*.yml`) to Node 24 native major versions with `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"`.
+- Automated OpenAPI specification and fixture version synchronization across 49 targets in `scripts/bump_version.py`.
+
 ## [12.4.0] - 2026-11-11 — Sharp Weight
 
 ### Added

package/docs/COMMUNITY_AND_PLUGINS.md

@@ -1,6 +1,6 @@
 # Community And Plugins
 
-Current release: **12.4.0 — Sharp Weight**.
+Current release: **12.5.0 — Deep Vector**.
 
 LatticeAI defines the path from a strong local-first framework (8.4.0
 action-aware baseline, 8.5.0 registry+DI hardening, 8.6.0 capture/navigation

package/docs/DEVELOPMENT.md

@@ -3,7 +3,7 @@
 > **Status: canonical** — current contributor guidance, kept in sync with the
 > current release.
 
-Current release: **12.4.0 — Sharp Weight**.
+Current release: **12.5.0 — Deep Vector**.
 
 This document is the contributor onboarding path: how to boot the tree, where
 a change belongs, which gates will go red, and the house rules that keep the
@@ -237,7 +237,7 @@ in `rust/`.
 Markdown) and `scripts/check_doc_status.mjs` (every relative link under the
 root canonical docs and `docs/**`). A red line is a broken relative path —
 fix the href or put the file where the href says. Canonical docs (this one
-included) must carry `Current release: **12.4.0 — …**` matching
+included) must carry `Current release: **12.5.0 — …**` matching
 `package.json`; do not bump that marker here ahead of the release lane.
 `npm run docs:check-current` is the release-set version pin
 ([`scripts/check_current_release_docs.mjs`](../scripts/check_current_release_docs.mjs)).
@@ -317,19 +317,19 @@ For user-facing, API, runtime, release, or packaging changes, check:
   appears
 
 The release-docs lane owns README / ARCHITECTURE / FEATURE_STATUS version
-bumps. Do not move this file's `Current release` marker off 12.4.0 ahead of
+bumps. Do not move this file's `Current release` marker off 12.5.0 ahead of
 that lane.
 
 Release/publish examples must use exact target-version filenames. Do not
 document wildcard artifact upload commands.
 
-For 12.4.0 release work, exact artifacts are:
+For 12.5.0 release work, exact artifacts are:
 
-- `dist/ltcai-12.4.0-py3-none-any.whl`
-- `dist/ltcai-12.4.0.tar.gz`
-- `ltcai-12.4.0.tgz`
-- `dist/ltcai-12.4.0.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_12.4.0_aarch64.dmg`
+- `dist/ltcai-12.5.0-py3-none-any.whl`
+- `dist/ltcai-12.5.0.tar.gz`
+- `ltcai-12.5.0.tgz`
+- `dist/ltcai-12.5.0.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_12.5.0_aarch64.dmg`
 
 The dmg is ad-hoc signed (effectively unsigned); `npm run release:validate`
 checks the names and presence, not a Developer ID signature.

package/docs/ONBOARDING.md

@@ -1,6 +1,6 @@
 # Lattice AI Onboarding
 
-Current release: **12.4.0 — Sharp Weight**.
+Current release: **12.5.0 — Deep Vector**.
 
 The first-run goal is a five-minute path from "I opened the app" to "my Brain
 has a source, a question, and proof." This page is the product contract behind

package/docs/OPERATIONS.md

@@ -1,4 +1,4 @@
-# Lattice AI — Operations Guide (v12.4.0)
+# Lattice AI — Operations Guide (v12.5.0)
 
 > **Status: canonical** — kept in sync with the current release. Storage layout
 > below reflects the SQLite live Brain store and workspace scoping, not the

package/docs/TRUST_MODEL.md

@@ -1,6 +1,6 @@
 # Lattice AI Trust Model
 
-Current release: **12.4.0 — Sharp Weight**.
+Current release: **12.5.0 — Deep Vector**.
 
 Lattice AI is local-first, explicit about external communication, and honest
 when a capability is unavailable.

package/docs/WHY_LATTICE.md

@@ -1,6 +1,6 @@
 # Why Lattice AI Exists
 
-Current release: **12.4.0 — Sharp Weight**.
+Current release: **12.5.0 — Deep Vector**.
 
 **Lattice AI is a local-first Digital Brain that keeps your knowledge durable
 across any AI model.**

package/docs/kg-schema.md

@@ -1,6 +1,6 @@
 # Knowledge Graph Schema
 
-Current release: **12.4.0 — Sharp Weight**.
+Current release: **12.5.0 — Deep Vector**.
 
 명세 출처: `lattice_ai_full_spec.pptx` 슬라이드 20·21·22
 구현: `lattice_brain/graph/schema.py`

package/lattice_brain/__init__.py

@@ -31,7 +31,7 @@ from .multimodal import (
     transcribe_audio,
 )
 
-__version__ = "12.4.0"
+__version__ = "12.5.0"
 
 __all__ = [
     "AudioFacts",

package/latticeai/__init__.py

@@ -1,3 +1,3 @@
 """Lattice AI - modular server package."""
 
-__version__ = "12.4.0"
+__version__ = "12.5.0"

package/latticeai/api/models.py

@@ -264,6 +264,11 @@ def create_models_router(
                 "size": item["size"],
                 "display_name": item.get("name") or item.get("id"),
                 "modality": item.get("modality") or "multimodal",
+                "category": item.get("category") or ("embedding" if item.get("task") == "embedding" else "chat"),
+                "task": item.get("task") or ("embedding" if item.get("category") == "embedding" else "chat"),
+                "role": item.get("role") or ("embedding" if item.get("category") == "embedding" else "chat"),
+                "dimensions": item.get("dimensions"),
+                "hf_repo_id": item.get("hf_repo_id") or item["id"],
                 "source_country": item.get("source_country"),
                 "source_company": item.get("source_company"),
                 "execution_method": item.get("execution_method"),
@@ -356,12 +361,27 @@ def create_models_router(
         )
         # 5.2.0: surface structured registry info (verified status, hf, hardware, strategies) for UX
         try:
-            from latticeai.services.model_catalog import get_verified_models
+            from latticeai.services.model_catalog import (
+                get_verified_models,
+                recommend_embedding_for_hardware,
+            )
             verified = get_verified_models()
+            embedding_rec = recommend_embedding_for_hardware()
         except Exception:
             verified = []
+            embedding_rec = {
+                "id": "google/embeddinggemma-2",
+                "hf_repo_id": "google/embeddinggemma-2",
+                "name": "Google EmbeddingGemma 2",
+                "category": "embedding",
+                "task": "embedding",
+                "role": "embedding",
+                "dimensions": 768,
+            }
         return {
             "recommended": recommended,
+            "embedding_model": embedding_rec.get("id") or "google/embeddinggemma-2",
+            "embedding_recommendation": embedding_rec,
             "cloud": _router.detected_cloud_models(),
             "engines": engines,
             "loaded": _router.loaded_model_ids,

package/latticeai/api/search.py

@@ -23,6 +23,10 @@ from typing import Any, Callable, Dict, NoReturn, Optional
 
 from fastapi import APIRouter, HTTPException, Request
 
+from latticeai.core.embedding_providers.profiles import (
+    RECOMMENDED_EMBEDDING_MODEL,
+    RECOMMENDED_EMBEDDING_PROFILE,
+)
 from latticeai.services.search_service import SearchService
 
 
@@ -44,8 +48,11 @@ def create_search_router(
         require_user(request)
         resolved = embedding_info() if embedding_info else {}
         try:
-            return service.embeddings_status(resolved=resolved, refresh=refresh)
+            payload = dict(service.embeddings_status(resolved=resolved, refresh=refresh))
         except ValueError as exc:
             _raise_embedder_error(exc)
+        payload.setdefault("recommended_model", RECOMMENDED_EMBEDDING_MODEL)
+        payload.setdefault("recommended_profile", RECOMMENDED_EMBEDDING_PROFILE)
+        return payload
 
     return router

package/latticeai/api/worker_compute.py

@@ -85,6 +85,10 @@ from pydantic import BaseModel, Field
 
 from latticeai.api.agent_worker_seam import SEAM_RATE_BUCKET
 from latticeai.api.agent_worker_seam import _seam_open as seam_open
+from latticeai.core.embedding_providers.profiles import (
+    RECOMMENDED_EMBEDDING_MODEL,
+    RECOMMENDED_EMBEDDING_PROFILE,
+)
 from latticeai.core.messages import MESSAGES, http_error, resolve_language
 from latticeai.core.quiet import quiet
 from latticeai.services.voice_capture import (
@@ -633,6 +637,7 @@ def create_worker_compute_router(
             if callable(role_aware)
             else await asyncio.to_thread(provider.embed_batch, texts)
         )
+        grade = getattr(provider, "grade", "fallback")
         return {
             "vectors": vectors,
             "dim": provider.dim,
@@ -641,7 +646,10 @@ def create_worker_compute_router(
             "kind": kind,
             # Additive (v12.0.0): `fallback` means these vectors are feature
             # hashes, not meaning. A caller that stores them can say so.
-            "grade": getattr(provider, "grade", "fallback"),
+            "grade": grade,
+            "semantic": grade != "fallback",
+            "recommended_model": RECOMMENDED_EMBEDDING_MODEL,
+            "recommended_profile": RECOMMENDED_EMBEDDING_PROFILE,
         }
 
     @router.post("/worker/parse")

package/latticeai/core/embedding_providers/__init__.py

@@ -70,9 +70,11 @@ from lattice_brain.embeddings import LocalEmbeddingModel as LocalEmbeddingModel
 
 from .autodetect import AUTO_PROVIDER as AUTO_PROVIDER
 from .autodetect import AUTODETECT_ENV as AUTODETECT_ENV
+from .autodetect import LOCAL_HF_MODELS as LOCAL_HF_MODELS
 from .autodetect import LOCAL_MLX_MODELS as LOCAL_MLX_MODELS
 from .autodetect import Detection as Detection
 from .autodetect import detect_embedder as detect_embedder
+from .autodetect import detect_local_hf as detect_local_hf
 from .autodetect import detect_local_mlx as detect_local_mlx
 from .autodetect import detect_ollama as detect_ollama
 from .autodetect import resolve_auto_provider as resolve_auto_provider
@@ -92,11 +94,16 @@ from .captions import VisionCaptioner as VisionCaptioner
 from .captions import resolve_vision_captioner as resolve_vision_captioner
 from .captions import vision_caption_port as vision_caption_port
 from .profiles import PRODUCTION_PROVIDER_PROFILES as PRODUCTION_PROVIDER_PROFILES
+from .profiles import RECOMMENDED_EMBEDDING_MODEL as RECOMMENDED_EMBEDDING_MODEL
+from .profiles import RECOMMENDED_EMBEDDING_PROFILE as RECOMMENDED_EMBEDDING_PROFILE
 from .profiles import embedding_provider_profiles as embedding_provider_profiles
 from .profiles import resolve_embedding_profile as resolve_embedding_profile
+from .text import DEFAULT_HF_EMBEDDING_MODEL as DEFAULT_HF_EMBEDDING_MODEL
+from .text import EMBEDDINGGEMMA_PREFIXES as EMBEDDINGGEMMA_PREFIXES
 from .text import PROVIDER_TYPES as PROVIDER_TYPES
 from .text import CustomEmbeddingProvider as CustomEmbeddingProvider
 from .text import HashEmbeddingProvider as HashEmbeddingProvider
+from .text import HuggingFaceEmbeddingProvider as HuggingFaceEmbeddingProvider
 from .text import MLXEmbeddingProvider as MLXEmbeddingProvider
 from .text import OllamaEmbeddingProvider as OllamaEmbeddingProvider
 from .text import OpenAICompatibleEmbeddingProvider as OpenAICompatibleEmbeddingProvider
@@ -123,9 +130,15 @@ from .vision import resolve_vision_embedder as resolve_vision_embedder
 __all__ = [
     "AUTODETECT_ENV",
     "AUTO_PROVIDER",
+    "DEFAULT_HF_EMBEDDING_MODEL",
+    "EMBEDDINGGEMMA_PREFIXES",
+    "LOCAL_HF_MODELS",
     "LOCAL_MLX_MODELS",
+    "RECOMMENDED_EMBEDDING_MODEL",
+    "RECOMMENDED_EMBEDDING_PROFILE",
     "Detection",
     "detect_embedder",
+    "detect_local_hf",
     "detect_local_mlx",
     "detect_ollama",
     "resolve_auto_provider",
@@ -151,6 +164,7 @@ __all__ = [
     "resolve_vision_embedder",
     "vision_caption_port",
     "HashEmbeddingProvider",
+    "HuggingFaceEmbeddingProvider",
     "MLXEmbeddingProvider",
     "OllamaEmbeddingProvider",
     "OpenAICompatibleEmbeddingProvider",

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)