ltcai 12.2.0 → 12.3.0

package/latticeai/core/vector_index/hnsw.py

@@ -118,6 +118,11 @@ class HnswIndex:
     def model_id(self) -> str:
         return self._model_id
 
+    @property
+    def labels(self) -> List[str]:
+        """Live label order — the sidecar's identity, loaded or rebuilt."""
+        return list(self._labels)
+
     def _identity_matches(self, dim: int, space: str, model_id: str) -> bool:
         return (
             int(dim) == self._dim
@@ -177,10 +182,12 @@ class HnswIndex:
         doors without guessing.
 
         Full rebuild when the embedder identity changed, when any currently
-        indexed id is missing from the incoming set (a deletion), when
-        deletes would exceed :data:`DELETE_REBUILD_RATIO`, or when this
-        instance was loaded from a sidecar and cannot append (no source
-        vectors to keep the label map honest).
+        indexed id is missing from a *full* incoming snapshot (a deletion),
+        or when deletes would exceed :data:`DELETE_REBUILD_RATIO`. A sidecar
+        that was loaded without source vectors still **appends**: the
+        caller passes only the new ids (COUNT+delta) and ``_append_live``
+        extends the graph. A disjoint incoming set is that delta, not a
+        wipe.
         """
         incoming: Dict[str, IndexItem] = {}
         for item_id, vector, metadata in items:
@@ -197,13 +204,36 @@ class HnswIndex:
             return "rebuild"
 
         if self._loaded:
+            current = set(self._labels)
+            incoming_ids = set(incoming)
+            overlap = current & incoming_ids
+            deleted = current - incoming_ids
+            # Delta-only: the caller passed new ids, none of the live labels.
+            # A full snapshot that dropped ids is a deletion and must rebuild.
+            delta_only = bool(incoming_ids) and not overlap
+            if deleted and not delta_only:
+                self.rebuild(incoming.values())
+                return "rebuild"
+            new_ids = [item_id for item_id in incoming if item_id not in current]
+            if not new_ids:
+                return "append"
+            for item_id in new_ids:
+                _, vector, metadata = incoming[item_id]
+                self._vectors[item_id] = [float(value) for value in vector]
+                self._metadata[item_id] = dict(metadata or {})
+            if self._ann is not None and self._module is not None:
+                self._append_live(new_ids)
+                return "append"
             self.rebuild(incoming.values())
             return "rebuild"
 
         current = set(self._vectors)
         incoming_ids = set(incoming)
         deleted = current - incoming_ids
-        if deleted:
+        overlap = current & incoming_ids
+        # Same discriminant as the loaded path: a disjoint incoming set is
+        # COUNT+delta, not a snapshot that deleted every live id.
+        if deleted and not (bool(incoming_ids) and not overlap):
             ratio = len(deleted) / max(1, len(current))
             if ratio >= DELETE_REBUILD_RATIO or not current:
                 self.rebuild(incoming.values())
@@ -339,18 +369,25 @@ class HnswIndex:
             return False
         return True
 
-    def load(self, db_path: Any, *, fingerprint: str) -> bool:
-        """Adopt a sidecar graph when it provably matches ``fingerprint``."""
+    def load(self, db_path: Any, *, fingerprint: str, strict: bool = True) -> bool:
+        """Adopt a sidecar graph when it matches this embedder identity.
+
+        ``strict`` (the default) also requires the stored fingerprint — size
+        included — so a grown store does not search a stale graph. Relaxed
+        load keeps dim/model and leaves COUNT+delta to append the missing
+        ids rather than dumping the whole table.
+        """
         module = self._module
         if module is None:
             return False
         index_path, meta_path = sidecar_paths(db_path)
         try:
             meta = json.loads(meta_path.read_text(encoding="utf-8"))
-            matches = str(meta["fingerprint"]) == str(fingerprint)
-            matches = matches and int(meta["dim"]) == self._dim
+            matches = int(meta["dim"]) == self._dim
             if meta.get("model_id") not in (None, "", self._model_id):
                 matches = False
+            if strict:
+                matches = matches and str(meta["fingerprint"]) == str(fingerprint)
             labels = [str(label) for label in meta["labels"]]
         except Exception:  # noqa: BLE001 — absent/corrupt sidecar = rebuild
             return False
@@ -358,7 +395,9 @@ class HnswIndex:
             return False
         try:
             graph = module.Index(space=self._space, dim=self._dim)
-            graph.load_index(str(index_path), max_elements=len(labels))
+            # Headroom so an in-process append does not have to rebuild
+            # just because load_index pinned max_elements to the old size.
+            graph.load_index(str(index_path), max_elements=max(len(labels) + 64, 1))
         except Exception:  # noqa: BLE001 — corrupt binary = rebuild
             return False
         self._ann = graph

package/latticeai/core/vector_index/sidecar.py

@@ -2,10 +2,10 @@
 
 The live graph is cached per ``(db_path, model_id, dim)``. A missing sidecar
 is ``index: "none"``. When the store has vectors the cache (or a rebuild from
-``vector_embeddings``) can serve, the reply is ``index: "hnsw"``. Staleness is
-sidecar size vs ``COUNT(*)`` for that identity — reported honestly, and
-refreshed through :meth:`HnswIndex.add_items` so an ingest append does not
-rebuild the whole graph.
+``vector_embeddings``) can serve, the reply is ``index: "hnsw"``. Freshness is
+sidecar size vs ``COUNT(*)`` for that identity. A warm COUNT match never
+opens embedding blobs. Growth loads **missing ids only** and appends; a
+shrink still rebuilds from the remaining rows.
 """
 
 from __future__ import annotations
@@ -81,6 +81,83 @@ def load_store_items(
     return items
 
 
+def load_store_ids(conn: sqlite3.Connection, model_id: str, dim: int) -> List[str]:
+    """Item ids only — the COUNT+delta path must not pull embedding blobs."""
+    rows = conn.execute(
+        "SELECT item_id FROM vector_embeddings "
+        "WHERE embedding_model=? AND embedding_dim=? ORDER BY indexed_at ASC, item_id ASC",
+        (model_id, int(dim)),
+    )
+    return [str(item_id) for (item_id,) in rows]
+
+
+def load_store_items_for(
+    conn: sqlite3.Connection,
+    model_id: str,
+    dim: int,
+    item_ids: Sequence[str],
+) -> List[Tuple[str, List[float], Dict[str, Any]]]:
+    """Blobs for ``item_ids`` only, preserving the caller's order."""
+    if not item_ids:
+        return []
+    by_id: Dict[str, List[float]] = {}
+    wanted = [str(item_id) for item_id in item_ids]
+    # SQLite caps bound parameters; 400 leaves room for the identity pair.
+    for start in range(0, len(wanted), 400):
+        chunk = wanted[start : start + 400]
+        qmarks = ",".join("?" * len(chunk))
+        query = "SELECT item_id, embedding FROM vector_embeddings WHERE embedding_model=? AND embedding_dim=? AND item_id IN (%s)" % qmarks  # noqa: S608
+        for item_id, blob in conn.execute(query, (model_id, int(dim), *chunk)):
+            vector = decode_f32le(bytes(blob or b""), int(dim))
+            if len(vector) != int(dim):
+                continue
+            by_id[str(item_id)] = vector
+    return [
+        (item_id, by_id[item_id], {})
+        for item_id in wanted
+        if item_id in by_id
+    ]
+
+
+def _open_and_count(path: Path, model_id: str, dim: int) -> int:
+    conn = _open_readonly(path)
+    if conn is None:
+        return 0
+    try:
+        return store_vector_count(conn, model_id, dim)
+    finally:
+        conn.close()
+
+
+def _load_all_items(
+    path: Path, model_id: str, dim: int
+) -> List[Tuple[str, List[float], Dict[str, Any]]]:
+    conn = _open_readonly(path)
+    if conn is None:
+        return []
+    try:
+        return load_store_items(conn, model_id, dim)
+    finally:
+        conn.close()
+
+
+def _load_missing_items(
+    path: Path,
+    model_id: str,
+    dim: int,
+    have: Sequence[str],
+) -> List[Tuple[str, List[float], Dict[str, Any]]]:
+    conn = _open_readonly(path)
+    if conn is None:
+        return []
+    try:
+        have_set = set(have)
+        missing = [item_id for item_id in load_store_ids(conn, model_id, dim) if item_id not in have_set]
+        return load_store_items_for(conn, model_id, dim, missing)
+    finally:
+        conn.close()
+
+
 def sidecar_meta_size(db_path: Path) -> Optional[int]:
     """Label count from the sidecar meta file, or ``None`` when it is absent."""
     _, meta_path = sidecar_paths(db_path)
@@ -185,17 +262,8 @@ def query_sidecar(
     if not model_id:
         return _none_reply(detail="embedding_model is required")
 
-    conn = _open_readonly(path)
-    store_size = 0
-    items: List[Tuple[str, List[float], Dict[str, Any]]] = []
-    if conn is not None:
-        try:
-            store_size = store_vector_count(conn, model_id, dim)
-            if store_size > 0:
-                items = load_store_items(conn, model_id, dim)
-                store_size = len(items)
-        finally:
-            conn.close()
+    # COUNT first. Warm queries that already match never open embedding blobs.
+    store_size = _open_and_count(path, model_id, dim)
 
     key = (str(path), model_id, dim)
     with _LOCK:
@@ -203,8 +271,20 @@ def query_sidecar(
         refreshed: Optional[str] = None
         if index is None:
             index = HnswIndex(dim=dim, model_id=model_id)
-            loaded = index.load(path, fingerprint=sidecar_fingerprint(model_id, dim, store_size))
+            loaded = index.load(
+                path, fingerprint=sidecar_fingerprint(model_id, dim, store_size)
+            )
+            if not loaded and store_size > 0:
+                # Sidecar exists for this identity but the COUNT moved —
+                # load the graph and append the missing ids below.
+                loaded = index.load(
+                    path,
+                    fingerprint=sidecar_fingerprint(model_id, dim, store_size),
+                    strict=False,
+                )
             if not loaded:
+                items = _load_all_items(path, model_id, dim)
+                store_size = len(items)
                 if not items:
                     return _none_reply(
                         store_size=store_size,
@@ -216,25 +296,31 @@ def query_sidecar(
 
         cached_size = int(index.stats().get("size") or 0)
         stale = cached_size != store_size
-        if stale:
-            if not items and store_size > 0:
-                conn = _open_readonly(path)
-                if conn is not None:
-                    try:
-                        items = load_store_items(conn, model_id, dim)
-                    finally:
-                        conn.close()
+        if stale and store_size == 0:
+            _CACHE.pop(key, None)
+            return _none_reply(
+                store_size=0,
+                detail="vector store is empty for this embedding identity",
+            )
+        if stale and store_size > cached_size:
+            delta = _load_missing_items(path, model_id, dim, index.labels)
+            if delta:
+                refreshed = _refresh_index(index, delta, model_id, dim)
+                cached_size = int(index.stats().get("size") or 0)
+                index.save(
+                    path, fingerprint=sidecar_fingerprint(model_id, dim, cached_size)
+                )
+                stale = cached_size != store_size
+        elif stale:
+            items = _load_all_items(path, model_id, dim)
+            store_size = len(items)
             if items:
                 refreshed = _refresh_index(index, items, model_id, dim)
-                index.save(path, fingerprint=sidecar_fingerprint(model_id, dim, len(items)))
                 cached_size = int(index.stats().get("size") or 0)
-                stale = cached_size != len(items)
-            elif store_size == 0:
-                _CACHE.pop(key, None)
-                return _none_reply(
-                    store_size=0,
-                    detail="vector store is empty for this embedding identity",
+                index.save(
+                    path, fingerprint=sidecar_fingerprint(model_id, dim, cached_size)
                 )
+                stale = cached_size != store_size
 
         if cached_size <= 0:
             return _none_reply(
@@ -326,4 +412,7 @@ __all__ = [
     "sidecar_freshness",
     "sidecar_meta_size",
     "store_vector_count",
+    "load_store_ids",
+    "load_store_items",
+    "load_store_items_for",
 ]

package/latticeai/models/model_providers.py

@@ -27,29 +27,28 @@ OPENAI_COMPATIBLE_PROVIDERS = {
     "together": {
         "env_key": "TOGETHER_API_KEY",
         "base_url": "https://api.together.xyz/v1",
-        "default_model": "Qwen/Qwen3-VL-32B-Instruct",
+        "default_model": "Qwen/Qwen3.6-27B",
     },
     "xai": {
         "env_key": "XAI_API_KEY",
         "base_url": "https://api.x.ai/v1",
         # ``grok-beta`` was xAI's 2024 preview id and has been decommissioned;
-        # a request naming it now 404s at the provider. ``grok-4.5`` is the
-        # current flagship on api.x.ai and is multimodal, which is also why the
-        # separate ``grok-vision-beta`` row below is gone rather than renamed.
-        "default_model": "grok-4.5",
+        # a request naming it now 404s at the provider. ``grok-4.6`` is the
+        # current flagship on api.x.ai and matches the Rust cloud adapter.
+        "default_model": "grok-4.6",
     },
     "ollama": {
         "env_key": "OLLAMA_API_KEY",
         "base_url_env": "OLLAMA_BASE_URL",
         "base_url": "http://localhost:11434/v1",
-        "default_model": "hf.co/ggml-org/gemma-4-12B-it-GGUF:Q4_K_M",
+        "default_model": "hf.co/ggml-org/gemma-4-12B-it-GGUF:Q4_0",
         "api_key_fallback": "ollama",
     },
     "vllm": {
         "env_key": "VLLM_API_KEY",
         "base_url_env": "VLLM_BASE_URL",
         "base_url": "http://localhost:8000/v1",
-        "default_model": "Qwen/Qwen3-VL-8B-Instruct",
+        "default_model": "google/gemma-4-12B-it",
         "api_key_fallback": "vllm",
     },
     "lmstudio": {
@@ -85,9 +84,9 @@ 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-vl-235b-a22b-instruct", "name": "Qwen3-VL 235B A22B 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.5", "name": "Grok 4.5 via OpenRouter", "family": "Grok"},
+        {"id": "x-ai/grok-4.6", "name": "Grok 4.6 via OpenRouter", "family": "Grok"},
         {"id": "meta-llama/llama-4-scout-17b-16e-instruct", "name": "Llama 4 Scout via OpenRouter", "family": "Llama"},
         {"id": "google/gemini-2.5-flash", "name": "Gemini 2.5 Flash via OpenRouter", "family": "Gemini"},
     ],
@@ -95,7 +94,7 @@ PROVIDER_MODEL_CATALOG = {
         {"id": "meta-llama/llama-4-scout-17b-16e-instruct", "name": "Llama 4 Scout", "family": "Llama"},
     ],
     "together": [
-        {"id": "Qwen/Qwen3-VL-32B-Instruct", "name": "Qwen3-VL 32B", "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"},
     ],
@@ -105,7 +104,7 @@ PROVIDER_MODEL_CATALOG = {
         # (grok-beta / grok-vision-beta) are not carried as fallbacks: a model
         # the provider no longer serves is not compatibility, it is a 404 the
         # user has to discover for themselves.
-        {"id": "grok-4.5", "name": "Grok 4.5", "family": "Grok"},
+        {"id": "grok-4.6", "name": "Grok 4.6", "family": "Grok"},
     ],
 }
 

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.2.0"
+ARCHITECTURE_VERSION_TARGET = "12.3.0"
 
 PREFERRED_REFACTORING_ORDER = [
     "agent-runtime",

package/latticeai/services/model_capability_registry.py

@@ -300,7 +300,7 @@ _REGISTRY: List[ModelCapability] = [
         architecture="qwen3_5",
         download_size_gb=5.98,
         quantization="4bit",
-        provider_hints=["local_mlx", "vllm"],
+        provider_hints=["local_mlx", "ollama", "vllm", "lmstudio", "llamacpp"],
         download_strategy="hf_hub",
         load_strategy="mlx_vlm",
         hardware=HardwareProfile(
@@ -381,7 +381,7 @@ _REGISTRY: List[ModelCapability] = [
         architecture="qwen3_5_moe",
         download_size_gb=20.43,
         quantization="4bit",
-        provider_hints=["local_mlx", "vllm"],
+        provider_hints=["local_mlx", "ollama", "vllm", "lmstudio", "llamacpp"],
         download_strategy="hf_hub",
         load_strategy="mlx_vlm",
         hardware=HardwareProfile(

package/latticeai/services/model_catalog.py

@@ -102,11 +102,17 @@ ENGINE_MODEL_CATALOG: Dict[str, List[Dict[str, Any]]] = {}
 # gated — the download could never succeed without Hub credentials.
 
 
-def _gguf_routes(mlx_repo: str, gguf_repo: str, hf_repo: str) -> Dict[str, str]:
+def _gguf_routes(
+    mlx_repo: str,
+    gguf_repo: str,
+    hf_repo: str,
+    *,
+    ollama_tag: str = "Q4_K_M",
+) -> Dict[str, str]:
     """One model's engine map: MLX weights, a GGUF repo, and the upstream HF repo."""
     return {
         "local_mlx": mlx_repo,
-        "ollama": f"hf.co/{gguf_repo}:Q4_K_M",
+        "ollama": f"hf.co/{gguf_repo}:{ollama_tag}",
         "vllm": hf_repo,
         "lmstudio": gguf_repo,
         "llamacpp": gguf_repo,
@@ -119,36 +125,38 @@ _ENGINE_ROUTES: Dict[str, Dict[str, str]] = {
     ),
     "mlx-community/gemma-4-e2b-it-4bit": _gguf_routes(
         "mlx-community/gemma-4-e2b-it-4bit", "ggml-org/gemma-4-E2B-it-GGUF", "google/gemma-4-E2B-it",
+        ollama_tag="Q4_0",
     ),
     "mlx-community/gemma-4-e4b-it-4bit": _gguf_routes(
         "mlx-community/gemma-4-e4b-it-4bit", "ggml-org/gemma-4-E4B-it-GGUF", "google/gemma-4-E4B-it",
+        ollama_tag="Q4_0",
     ),
     "mlx-community/gemma-4-12B-it-4bit": _gguf_routes(
         "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-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-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.6-27B-4bit": _gguf_routes(
         "mlx-community/Qwen3.6-27B-4bit", "ggml-org/Qwen3.6-27B-GGUF", "Qwen/Qwen3.6-27B",
     ),
     "mlx-community/gpt-oss-20b-MXFP4-Q8": _gguf_routes(
         "mlx-community/gpt-oss-20b-MXFP4-Q8", "ggml-org/gpt-oss-20b-GGUF", "openai/gpt-oss-20b",
+        ollama_tag="MXFP4",
+    ),
+    "mlx-community/Qwen3.5-9B-MLX-4bit": _gguf_routes(
+        "mlx-community/Qwen3.5-9B-MLX-4bit", "unsloth/Qwen3.5-9B-GGUF", "Qwen/Qwen3.5-9B",
+    ),
+    "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",
     ),
-    # No community GGUF build verified for these two, so they offer the MLX
-    # weights and the upstream repo only rather than a route that would 404.
-    "mlx-community/Qwen3.5-9B-MLX-4bit": {
-        "local_mlx": "mlx-community/Qwen3.5-9B-MLX-4bit",
-        "vllm": "Qwen/Qwen3.5-9B",
-    },
-    "mlx-community/Qwen3.6-35B-A3B-4bit": {
-        "local_mlx": "mlx-community/Qwen3.6-35B-A3B-4bit",
-        "vllm": "Qwen/Qwen3.6-35B-A3B",
-    },
 }
 
 # Names people actually type that are not the repo's own short name. Kept

package/latticeai/services/model_engines.py

@@ -332,6 +332,10 @@ def ensure_llamacpp_server(model_name: str) -> None:
         hf_model_dir,
         hf_model_ready,
     )
+    from latticeai.services.model_runtime.download import (
+        GGUF_QUANT_PREFERENCE,
+        is_auxiliary_gguf,
+    )
 
     served_models = get_openai_compatible_server_models("llamacpp")
     if model_name in served_models:
@@ -347,23 +351,31 @@ def ensure_llamacpp_server(model_name: str) -> None:
         download_hf_model(model_name, "llamacpp")
 
     gguf_files = sorted(hf_model_dir(model_name).rglob("*.gguf"))
-    if not gguf_files:
+    primary_ggufs = [p for p in gguf_files if not is_auxiliary_gguf(p.name)]
+    if not primary_ggufs:
         raise ModelRuntimeError(status_code=500, detail="다운로드된 GGUF 파일을 찾지 못했습니다.")
 
-    preferred = next((p for p in gguf_files if "q4_k_m" in p.name.lower()), None)
-    model_file = preferred or gguf_files[0]
+    preferred = next(
+        (p for pref in GGUF_QUANT_PREFERENCE for p in primary_ggufs if pref in p.name.lower()),
+        None,
+    )
+    model_file = preferred or primary_ggufs[0]
+    command = [
+        "llama-server",
+        "-m",
+        str(model_file),
+        "--alias",
+        model_name,
+        "--host",
+        "127.0.0.1",
+        "--port",
+        "8080",
+    ]
+    mmprojs = [p for p in gguf_files if p.name.lower().startswith("mmproj-")]
+    if mmprojs:
+        command.extend(["--mmproj", str(mmprojs[0])])
     LOCAL_SERVER_PROCESSES["llamacpp"] = subprocess.Popen(
-        [
-            "llama-server",
-            "-m",
-            str(model_file),
-            "--alias",
-            model_name,
-            "--host",
-            "127.0.0.1",
-            "--port",
-            "8080",
-        ],
+        command,
         stdout=subprocess.DEVNULL,
         stderr=subprocess.DEVNULL,
         start_new_session=True,

package/latticeai/services/model_runtime/download.py

@@ -10,6 +10,7 @@ differently.
 from __future__ import annotations
 
 import importlib.util
+import json
 import logging
 import time
 from pathlib import Path
@@ -19,6 +20,29 @@ from latticeai.core.quiet import quiet
 from latticeai.models.router import hf_cache_model_dir, hf_model_dir
 from latticeai.services.model_errors import ModelRuntimeError
 
+_AUXILIARY_GGUF_PREFIXES = ("mmproj-", "mtp-", "dflash-", "eagle3-")
+GGUF_QUANT_PREFERENCE = ("q4_k_m", "q4_0", "mxfp4", "q4_k_s", "q3_k_m", "q2_k", "q8_0")
+
+
+def is_auxiliary_gguf(filename: str) -> bool:
+    base = Path(str(filename)).name.lower()
+    return base.startswith(_AUXILIARY_GGUF_PREFIXES) or "imatrix" in base
+
+
+def _shards_complete(model_dir: Path) -> bool:
+    index_file = model_dir / "model.safetensors.index.json"
+    if not index_file.exists():
+        return True
+    try:
+        payload = json.loads(index_file.read_text(encoding="utf-8"))
+        weight_map = payload.get("weight_map") if isinstance(payload, dict) else None
+        if isinstance(weight_map, dict) and weight_map:
+            shards = {str(shard) for shard in weight_map.values() if shard}
+            return all((model_dir / shard).exists() for shard in shards)
+    except Exception:
+        quiet()
+    return True
+
 
 def hf_model_ready(repo_id: str, provider: str = "local_mlx") -> bool:
     model_dir = hf_model_dir(repo_id)
@@ -32,9 +56,11 @@ def hf_model_ready(repo_id: str, provider: str = "local_mlx") -> bool:
     if not model_dir.exists() or not model_dir.is_dir():
         return False
     if provider == "llamacpp":
-        return any(model_dir.rglob("*.gguf"))
+        return any(not is_auxiliary_gguf(p.name) for p in model_dir.rglob("*.gguf"))
     has_config = (model_dir / "config.json").exists()
-    has_weights = any(model_dir.glob("*.safetensors")) or any(model_dir.glob("*.bin"))
+    has_weights = (
+        any(model_dir.glob("*.safetensors")) or any(model_dir.glob("*.bin"))
+    ) and _shards_complete(model_dir)
     has_tokenizer = (
         (model_dir / "tokenizer.json").exists()
         or (model_dir / "tokenizer.model").exists()
@@ -139,15 +165,36 @@ def download_hf_model(
                 [item for item in all_files if str(item["name"]).lower().endswith(".gguf")],
                 key=lambda item: str(item["name"]),
             )
-            if not ggufs:
+            primary_ggufs = [item for item in ggufs if not is_auxiliary_gguf(str(item["name"]))]
+            if not primary_ggufs:
                 raise RuntimeError("GGUF 파일을 찾지 못했습니다.")
-            preference = ("q4_k_m", "q4_0", "q4_k_s", "q3_k_m", "q2_k")
             selected_files = [
                 next(
-                    (item for pref in preference for item in ggufs if pref in str(item["name"]).lower()),
-                    ggufs[0],
+                    (
+                        item
+                        for pref in GGUF_QUANT_PREFERENCE
+                        for item in primary_ggufs
+                        if pref in str(item["name"]).lower()
+                    ),
+                    primary_ggufs[0],
                 )
             ]
+            mmprojs = [
+                item
+                for item in ggufs
+                if Path(str(item["name"])).name.lower().startswith("mmproj-")
+            ]
+            if mmprojs:
+                preferred_mmproj = next(
+                    (
+                        item
+                        for pref in ("bf16", "f16", "f32")
+                        for item in mmprojs
+                        if pref in str(item["name"]).lower()
+                    ),
+                    mmprojs[0],
+                )
+                selected_files.append(preferred_mmproj)
         else:
             selected_files = all_files
 

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.2.0"
+PRODUCT_VERSION_TARGET = "12.3.0"
 
 
 @dataclass(frozen=True)
@@ -123,7 +123,7 @@ PRODUCT_GATES: List[ProductGate] = [
             f"vscode-extension/README.md::**{PRODUCT_VERSION_TARGET}",
             f"docs/CHANGELOG.md::## [{PRODUCT_VERSION_TARGET}]",
             "FEATURE_STATUS.md",
-            f"RELEASE_NOTES_v{PRODUCT_VERSION_TARGET}.md",
+            f"docs/releases/RELEASE_NOTES_v{PRODUCT_VERSION_TARGET}.md",
             "rust/lattice-agent/src/kernel/permission.rs::pub fn block_reason_for_tool",
             "rust/lattice-agent/src/kernel/mod.rs::pub mod agentloop",
             "latticeai/api/agent_worker_seam.py::create_agent_worker_seam_router",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ltcai",
-  "version": "12.2.0",
+  "version": "12.3.0",
   "description": "Lattice AI — local-first Digital Brain that keeps your knowledge durable across any AI model.",
   "homepage": "https://github.com/TaeSooPark-PTS/LatticeAI#readme",
   "repository": {
@@ -111,16 +111,14 @@
     "!TOOLS.md",
     "!USER.md",
     "!docs/images/tmp_frames/",
-    "!**/__pycache__/",
-    "!**/*.pyc",
-    "!**/*.map",
+    "!{latticeai,lattice_brain,skills,plugins,scripts}/**/__pycache__/",
+    "!{latticeai,lattice_brain,skills,plugins,scripts}/**/*.pyc",
+    "!static/**/*.map",
     "README.md",
     "static/vendor/",
     "src-tauri/",
     "!src-tauri/gen/",
-    "!src-tauri/gen/**",
     "!src-tauri/target/",
-    "!src-tauri/target/**",
     "docs/*.md",
     "!docs/assets/",
     "!docs/images/"