ltcai 11.0.1 → 11.2.0

package/latticeai/api/memory.py

@@ -3,17 +3,26 @@
 Exposes :class:`~latticeai.services.memory_service.MemoryService` so the /app
 Memory view can inspect every memory tier, recall across them, and run manager
 operations (prune / compact / rebuild / clear). Full paths in decorators.
+
+v11.1.0 adds the Self-Model surface (Track 4) on the same factory: the profile
+the Brain holds about its owner is *memory*, so it is read, edited and deleted
+here rather than behind a router of its own. Ownership is the whole point —
+extraction only ever proposes (``/self-model/propose`` →  Review Center →
+``/self-model/apply``), while the user's own edits and deletions write
+directly.
 """
 
 from __future__ import annotations
 
-from typing import Callable, List, Optional
+from typing import Any, Callable, List, Optional
 
 from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel
 
+from lattice_brain.self_model import SelfModelError
 from latticeai.core.messages import http_error, resolve_language
 from latticeai.services.memory_service import MemoryService
+from latticeai.services.self_model_service import SelfModelService
 
 
 class RecallRequest(BaseModel):
@@ -35,6 +44,49 @@ class ClearRequest(BaseModel):
     confirm: bool = False
 
 
+#: Self-Model failure codes → catalog ids. Brain Core raises codes (it cannot
+#: import the catalog); the answer a person reads is chosen here, in their
+#: language. An unknown code degrades to the generic entry rather than leaking
+#: an English developer sentence.
+SELF_MODEL_MESSAGES = {
+    "invalid_kind": "self_model.invalid_kind",
+    "text_required": "self_model.text_required",
+    "not_found": "self_model.not_found",
+    "not_self_model": "self_model.not_self_model",
+    "not_a_proposal": "self_model.not_a_proposal",
+    "empty_proposal": "self_model.empty_proposal",
+    "graph_unavailable": "self_model.graph_unavailable",
+    "queue_unavailable": "self_model.queue_unavailable",
+}
+
+
+def _self_model_error(exc: SelfModelError, request: Request) -> HTTPException:
+    status = 404 if exc.code == "not_found" else 400
+    message_id = SELF_MODEL_MESSAGES.get(exc.code, "self_model.invalid")
+    return http_error(status, message_id, resolve_language(request))
+
+
+class SelfModelFactRequest(BaseModel):
+    """A fact the user states about themselves (user-initiated direct write)."""
+
+    kind: str
+    text: str
+
+
+class SelfModelProposeRequest(BaseModel):
+    """Text to read for candidate facts. Output is proposals, never writes."""
+
+    text: str = ""
+    source: str = ""
+    max_proposals: int = 5
+
+
+class SelfModelApplyRequest(BaseModel):
+    """Approve one Self-Model proposal and write the fact it carries."""
+
+    item_id: str
+
+
 def create_memory_router(
     *,
     service: MemoryService,
@@ -44,8 +96,13 @@ def create_memory_router(
     gate_write: Callable[[Request], Optional[str]],
     append_audit_event: Callable[..., None],
     active_model_getter: Callable[[], str] | None = None,
+    self_model: Any = None,
 ) -> APIRouter:
     router = APIRouter()
+    # Derived from the memory service by default (graph + review queue), so the
+    # Self-Model routes exist on every build and report honestly when this
+    # Brain has no graph rather than disappearing from the API surface.
+    profile = self_model or SelfModelService(memory_service=service)
 
     @router.get("/api/memory/manager")
     async def memory_manager(request: Request):
@@ -140,4 +197,74 @@ def create_memory_router(
         append_audit_event("memory_clear", user_email=user, scope=req.scope)
         return result
 
+    # ── Self-Model (v11.1.0) ─────────────────────────────────────────────
+
+    @router.get("/api/memory/self-model")
+    async def self_model_profile(request: Request):
+        """What the Brain believes about its owner, and the injected summary."""
+        user = require_user(request)
+        scope = gate_read(request)
+        return profile.profile(user_email=user, workspace_id=scope)
+
+    @router.post("/api/memory/self-model")
+    async def self_model_upsert(req: SelfModelFactRequest, request: Request):
+        """Add or correct one fact directly — the user owns their profile."""
+        user = require_user(request)
+        scope = gate_write(request)
+        try:
+            fact = profile.upsert(kind=req.kind, text=req.text, workspace_id=scope)
+        except SelfModelError as exc:
+            raise _self_model_error(exc, request) from exc
+        append_audit_event(
+            "self_model_upsert", user_email=user, node_id=fact["id"], kind=fact["kind"]
+        )
+        return fact
+
+    @router.delete("/api/memory/self-model/{node_id}")
+    async def self_model_delete(node_id: str, request: Request):
+        """Forget one fact about the user, permanently."""
+        user = require_user(request)
+        gate_write(request)
+        try:
+            result = profile.delete(node_id)
+        except SelfModelError as exc:
+            raise _self_model_error(exc, request) from exc
+        append_audit_event("self_model_delete", user_email=user, node_id=node_id)
+        return result
+
+    @router.post("/api/memory/self-model/propose")
+    async def self_model_propose(req: SelfModelProposeRequest, request: Request):
+        """Read text for candidate facts; every hit becomes a review proposal."""
+        user = require_user(request)
+        scope = gate_write(request)
+        result = profile.propose(
+            req.text,
+            source=req.source or None,
+            user_email=user,
+            workspace_id=scope,
+            max_proposals=req.max_proposals,
+        )
+        append_audit_event(
+            "self_model_proposed",
+            user_email=user,
+            proposed=result.get("proposed_count", 0),
+        )
+        return result
+
+    @router.post("/api/memory/self-model/apply")
+    async def self_model_apply(req: SelfModelApplyRequest, request: Request):
+        """Approve a proposal and write the fact it carries into the graph."""
+        user = require_user(request)
+        scope = gate_write(request)
+        try:
+            result = profile.apply(req.item_id, workspace_id=scope)
+        except SelfModelError as exc:
+            raise _self_model_error(exc, request) from exc
+        except (KeyError, FileNotFoundError) as exc:
+            raise http_error(404, "review.item_not_found", resolve_language(request)) from exc
+        append_audit_event(
+            "self_model_applied", user_email=user, item_id=req.item_id
+        )
+        return result
+
     return router

package/latticeai/api/portability.py

@@ -87,8 +87,16 @@ class SubgraphSelection(BaseModel):
 
 
 class SubgraphArchiveRequest(SubgraphSelection):
+    """Exactly one recipient mechanism — a passphrase, or a public key.
+
+    Both optional at the schema level and validated in the service, so the
+    error a caller gets names the rule ("choose one") instead of a field.
+    """
+
     path: Optional[str] = None
-    passphrase: str
+    passphrase: Optional[str] = None
+    #: The recipient's X25519 public key, from their ``/share/recipient-key``.
+    recipient_public_key: Optional[str] = None
 
 
 class SubgraphImportRequest(BaseModel):
@@ -269,6 +277,22 @@ def create_portability_router(
         except (ValueError, RuntimeError) as exc:
             raise HTTPException(status_code=400, detail=str(exc))
 
+    @router.get("/api/knowledge-graph/share/recipient-key")
+    async def share_recipient_key(request: Request):
+        """This Brain's X25519 receiving key, for a sender to seal a bundle to.
+
+        Public by construction — a public key encrypts, it does not decrypt —
+        so handing it out is the whole point. Still admin-gated and still
+        behind the share flag, because minting the key is a decision to
+        participate in sharing at all.
+        """
+        require_admin(request)
+        _require_service(request)
+        try:
+            return service.recipient_key()
+        except PermissionError:
+            raise http_error(403, "portability.brain_network_disabled", resolve_language(request))
+
     @router.post("/api/knowledge-graph/share/archive")
     async def share_archive(req: SubgraphArchiveRequest, request: Request):
         """Same bundle, written as an encrypted ``.latticebrain`` file."""
@@ -277,8 +301,14 @@ def create_portability_router(
         body = req.model_dump()
         path = body.pop("path")
         passphrase = body.pop("passphrase")
+        recipient_public_key = body.pop("recipient_public_key")
         try:
-            return service.export_subgraph_archive(path, passphrase=passphrase, **body)
+            return service.export_subgraph_archive(
+                path,
+                passphrase=passphrase,
+                recipient_public_key=recipient_public_key,
+                **body,
+            )
         except PermissionError:
             raise http_error(403, "portability.brain_network_disabled", resolve_language(request))
         except (ValueError, RuntimeError) as exc:
@@ -294,8 +324,13 @@ def create_portability_router(
         try:
             artifact = req.artifact
             if artifact is None:
-                if not req.path or not req.passphrase:
-                    raise ValueError("Provide an artifact, or a path with its passphrase.")
+                if not req.path:
+                    raise ValueError(
+                        "Provide an artifact, or the path of a bundle on disk."
+                    )
+                # A sealed bundle needs no passphrase — the envelope says which
+                # mechanism it used and the service refuses if the wrong one is
+                # supplied, so the route does not have to guess here.
                 artifact = service.read_subgraph_archive(req.path, passphrase=req.passphrase)
             return service.import_subgraph_proposals(
                 artifact,

package/latticeai/api/review_queue.py

@@ -70,6 +70,39 @@ class ReviewCounts(BaseModel):
     pending_by_source: Dict[str, int] = Field(default_factory=dict)
 
 
+class BulkActionRequest(BaseModel):
+    """Decide several review items at once, named explicitly.
+
+    ``ids`` is required and never defaults to "everything pending": a bulk
+    action whose scope is implicit is how an inbox gets emptied by accident.
+    """
+
+    ids: List[str] = Field(default_factory=list)
+    reason: str = ""
+
+
+class BulkActionOutcome(BaseModel):
+    """Per-item verdict, so a partial success is legible rather than a total."""
+
+    id: str
+    status: str  # ok | not_found | conflict | failed
+    item_status: Optional[str] = None
+    detail: Optional[str] = None
+
+
+class BulkActionResult(BaseModel):
+    action: str
+    requested: int
+    succeeded: int
+    failed: int
+    results: List[BulkActionOutcome] = Field(default_factory=list)
+
+
+#: Ceiling on one bulk call. Large enough for "clear today's inbox", small
+#: enough that one request cannot walk the whole table inside a web worker.
+BULK_ACTION_CAP = 200
+
+
 def create_review_queue_router(
     *,
     service: ReviewQueueService,
@@ -123,6 +156,19 @@ def create_review_queue_router(
         scope = gate_read(request)
         return service.counts(workspace_id=scope, user_email=user)
 
+    # NOTE: declared *before* /automation/reviews/{item_id} for the same reason
+    # "counts" is — routes match in declaration order, so a later /bulk/... would
+    # be swallowed by the {item_id} matcher and answer 404 for a missing item.
+    @router.post("/automation/reviews/bulk/approve", response_model=BulkActionResult)
+    async def bulk_approve(req: BulkActionRequest, request: Request):
+        """Approve several items, reporting each one's outcome individually."""
+        return _bulk(request, req, "approve")
+
+    @router.post("/automation/reviews/bulk/dismiss", response_model=BulkActionResult)
+    async def bulk_dismiss(req: BulkActionRequest, request: Request):
+        """Dismiss several items, reporting each one's outcome individually."""
+        return _bulk(request, req, "dismiss")
+
     @router.get("/automation/reviews/{item_id}", response_model=ReviewItem)
     async def get_item(item_id: str, request: Request):
         require_user(request)
@@ -205,6 +251,86 @@ def create_review_queue_router(
     async def unsnooze_item(item_id: str, request: Request):
         return _act(request, item_id, "unsnooze")
 
+    def _bulk(request: Request, req: BulkActionRequest, action: str) -> Dict[str, Any]:
+        """One transition applied N times through the *same* single-item guard.
+
+        Deliberately not a bulk UPDATE. Every id goes through the ordinary
+        service call, so an already-approved item still 409s, a
+        ``change_proposal`` still applies its staged content, and the audit
+        trail records N decisions — because that is what happened. A failure
+        on one id never aborts the rest, and the response says exactly which
+        ones did not land instead of returning a single number the caller has
+        to interpret.
+        """
+        user = require_user(request)
+        scope = gate_write(request)
+        language = resolve_language(request)
+        wanted = [str(item).strip() for item in req.ids if str(item).strip()]
+        if not wanted:
+            raise http_error(422, "review.bulk_ids_required", language)
+        if len(wanted) > BULK_ACTION_CAP:
+            raise http_error(422, "review.bulk_too_many", language, cap=BULK_ACTION_CAP)
+        results: List[Dict[str, Any]] = []
+        succeeded = 0
+        for item_id in wanted:
+            outcome = _bulk_one(request, item_id, action, user=user, scope=scope, reason=req.reason)
+            if outcome["status"] == "ok":
+                succeeded += 1
+            results.append(outcome)
+        return {
+            "action": action,
+            "requested": len(wanted),
+            "succeeded": succeeded,
+            "failed": len(wanted) - succeeded,
+            "results": results,
+        }
+
+    def _bulk_one(
+        request: Request,
+        item_id: str,
+        action: str,
+        *,
+        user: str,
+        scope: Optional[str],
+        reason: str,
+    ) -> Dict[str, Any]:
+        try:
+            if action == "dismiss":
+                item = service.dismiss(item_id, workspace_id=scope, reason=reason or None)
+            else:
+                item = _approve_one(request, item_id, user=user, scope=scope)
+        except (FileNotFoundError, KeyError):
+            return {"id": item_id, "status": "not_found", "detail": None}
+        except InvalidReviewTransition as exc:
+            return {"id": item_id, "status": "conflict", "detail": str(exc)}
+        except ProposalConflictError as exc:
+            return {"id": item_id, "status": "conflict", "detail": str(exc)}
+        except HTTPException as exc:
+            return {
+                "id": item_id,
+                "status": "conflict" if exc.status_code == 409 else "failed",
+                "detail": str(exc.detail),
+            }
+        except ValueError as exc:
+            return {"id": item_id, "status": "failed", "detail": str(exc)}
+        append_audit_event(f"review_item_{action}", user_email=user, item_id=item_id)
+        return {"id": item_id, "status": "ok", "item_status": item.get("status"), "detail": None}
+
+    def _approve_one(
+        request: Request, item_id: str, *, user: str, scope: Optional[str]
+    ) -> Dict[str, Any]:
+        """Approve exactly the way the single-item route does, staged content included."""
+        if change_proposals is not None:
+            stored = service.get(item_id, workspace_id=scope)
+            if stored.get("source") == "change_proposal":
+                if stored.get("effective_status") not in ("pending", "snoozed"):
+                    raise InvalidReviewTransition("approve", str(stored.get("status")))
+                applied = change_proposals.approve_and_apply(
+                    item_id, user_email=user, workspace_id=scope
+                )
+                return dict(applied["item"])
+        return service.approve(item_id, workspace_id=scope)
+
     @router.post("/automation/reviews/{item_id}/run_now", response_model=ReviewItem)
     async def run_now_item(item_id: str, request: Request):
         user = require_user(request)

package/latticeai/api/search.py

@@ -25,6 +25,11 @@ class HybridSearchRequest(SearchRequest):
     vector_limit: int = 30
     graph_limit: int = 30
     weights: Optional[Dict[str, float]] = None
+    #: Opt in to scoring this text query against the *image* index too
+    #: (v11.2.0). Only possible when a shared-space vision model is
+    #: configured; when it is not, the response says so instead of quietly
+    #: returning the text-only ranking as if fusion had happened.
+    image_fusion: bool = False
 
 
 class GraphNodeRequest(BaseModel):
@@ -106,17 +111,26 @@ def create_search_router(
                 vector_limit=req.vector_limit,
                 graph_limit=req.graph_limit,
                 weights=req.weights or DEFAULT_HYBRID_WEIGHTS,
+                image_fusion=req.image_fusion,
             )
         except ValueError as exc:
             _raise_graph_error(exc)
 
     @router.get("/api/search/hybrid")
-    async def hybrid_search_get(q: str, request: Request, limit: int = 30) -> Dict[str, Any]:
+    async def hybrid_search_get(
+        q: str, request: Request, limit: int = 30, image_fusion: bool = False,
+    ) -> Dict[str, Any]:
         try:
-            return _guarded(request).hybrid_search(q, limit=limit)
+            return _guarded(request).hybrid_search(q, limit=limit, image_fusion=image_fusion)
         except ValueError as exc:
             _raise_graph_error(exc)
 
+    @router.get("/api/search/image-query")
+    async def image_query_status(request: Request) -> Dict[str, Any]:
+        """Whether a typed question can reach the image index on this install."""
+        require_user(request)
+        return service.image_query_status()
+
     @router.post("/api/search/keyword")
     async def keyword_search(req: SearchRequest, request: Request) -> Dict[str, Any]:
         try:

package/latticeai/core/agent.py

@@ -62,6 +62,7 @@ from latticeai.core.agent_permission import (
     resolve_deps_mode,
 )
 from latticeai.core.agent_profiles import AgentProfile, profile_for_model
+from latticeai.core.agent_prompts import executor_prompt_for
 
 # The state vocabulary and the pure helpers live in sibling modules so this one
 # holds only the loop. They are re-exported (see ``__all__``) because callers —
@@ -113,7 +114,8 @@ class AgentRunContext:
     __slots__ = ("state", "plan", "transcript", "retry_count",
                  "state_history", "corrections", "final_message", "rollback_log",
                  "executing_model", "reviewing_model", "approved_by_human", "trace",
-                 "on_step", "project_context", "permission_mode")
+                 "on_step", "project_context", "permission_mode",
+                 "self_model_summary")
 
     def __init__(self) -> None:
         self.state:           AgentState   = AgentState.IDLE
@@ -142,6 +144,12 @@ class AgentRunContext:
         # per-tool gate in the same run agree; ``None`` falls back to the
         # process-wide resolver on ``deps``.
         self.permission_mode: Optional[str] = None
+        # Self-Model summary resolved once per run (v11.2.0). The executor
+        # prompt is rebuilt on every turn of the loop; reading the profile
+        # once and reusing it keeps a graph query off that hot path — and
+        # keeps every turn of one run describing the same person. ``None``
+        # means "not resolved yet"; ``""`` is a resolved, empty profile.
+        self.self_model_summary: Optional[str] = None
 
 
 @dataclass
@@ -241,6 +249,17 @@ class AgentDeps:
     # which is exactly the pre-9.9.8 behaviour.
     permission_mode: Any = None
 
+    # ── Self-Model port (optional, v11.2.0) ──────────────────────────
+    # What the Brain has learned about its owner, injected into the executor
+    # prompt. Either a fixed string or a resolver callable taking
+    # ``user_email``/``workspace_id`` scope kwargs (or none at all). 11.1.0
+    # built ``executor_prompt_for(self_model_summary=…)`` and then had nothing
+    # to pass it, because the runtime held its executor prompt as a fixed
+    # string; this is the port that was missing. ``None`` — and an empty
+    # summary — produce exactly the prompt bytes the loop produced before it
+    # existed.
+    self_model_summary: Any = None
+
 
 class SingleAgentRuntime:
     """Drives the agent state machine over injected :class:`AgentDeps`."""
@@ -607,6 +626,41 @@ class SingleAgentRuntime:
 
         ctx.state = AgentState.VERIFYING
 
+    def _self_model_summary(
+        self, ctx: AgentRunContext, current_user: str, request_workspace: Optional[str]
+    ) -> str:
+        """What this Brain knows about its owner, resolved once per run.
+
+        The port may be a plain string or a resolver taking scope kwargs — the
+        same two shapes ``permission_mode`` accepts, so there is one convention
+        for "a value or a way to get one". Anything that goes wrong yields an
+        empty summary: prompt assembly must not fail because a profile could
+        not be read, and an empty summary is byte-identical to having no port
+        at all.
+        """
+        if ctx.self_model_summary is not None:
+            return ctx.self_model_summary
+        source = self.deps.self_model_summary
+        summary = ""
+        if source is not None:
+            try:
+                if callable(source):
+                    try:
+                        summary = source(
+                            user_email=current_user or None,
+                            workspace_id=request_workspace,
+                        )
+                    except TypeError:
+                        # A resolver that takes no scope arguments is allowed.
+                        summary = source()
+                else:
+                    summary = source
+            except Exception:  # noqa: BLE001 — a profile is never worth a failed run
+                logging.debug("agent: self-model summary unavailable", exc_info=True)
+                summary = ""
+        ctx.self_model_summary = str(summary or "").strip()
+        return ctx.self_model_summary
+
     def _executor_context(
         self, ctx: AgentRunContext, req: Any, lang_hint: str,
         current_user: str, request_workspace: Optional[str],
@@ -646,7 +700,10 @@ class SingleAgentRuntime:
             + "\n".join(f"- {path}" for path in written)
         ) if written else ""
         return (
-            f"{d.executor_prompt}\n\n"
+            # v11.1.0: the executor prompt carries profile-aware file-writing
+            # hints, because "wrote nothing at all" was the weak-model failure
+            # mode the loop could not repair after the fact.
+            f"{executor_prompt_for(d.executor_prompt, profile=profile, self_model_summary=self._self_model_summary(ctx, current_user, request_workspace))}\n\n"
             f"[LANGUAGE HINT: {lang_hint}]\n"
             f"Workspace root: {d.agent_root}{self._project_block(ctx)}\n\n"
             f"PLAN:\n{json.dumps(ctx.plan, ensure_ascii=False)}{written_hint}\n\n"

package/latticeai/core/agent_prompts.py

@@ -2,6 +2,8 @@
 
 from __future__ import annotations
 
+from typing import Any, Optional
+
 from latticeai.core.tool_registry import TOOL_CATALOG_BRIEF
 
 PLANNER_PROMPT = """You are the PLANNER role in Lattice AI's multi-role agent harness.
@@ -103,3 +105,67 @@ Rules:
 
 
 AGENT_SYSTEM_PROMPT = EXECUTOR_PROMPT
+
+
+# ── file-writing hints (v11.1.0) ────────────────────────────────────────────
+#
+# A 1–4B local model does not fail at *writing a file*; it fails at deciding
+# it is allowed to write one yet. The compact profile already gives that model
+# a shorter transcript and an earlier escalation; these hints give it the two
+# things the transcripts showed it missing most: a concrete order of
+# operations, and permission to write the file on the very next turn.
+#
+# The strings are deliberately additive — ``EXECUTOR_PROMPT`` is untouched, so
+# every caller that wants today's prompt keeps getting exactly today's prompt.
+
+FILE_TASK_HINTS = """
+FILE TASKS — how to actually finish one:
+- If the request names a file to create, your FIRST action is write_file with
+  the complete content. Do not read, list, or plan around it first.
+- args.path is a workspace-relative path (e.g. "report.md"), never absolute.
+- args.content is the WHOLE file, not a fragment and not a description of it.
+- After the write result appears in the transcript, verify once (read_file),
+  then finish with {"action": "final", ...}.
+"""
+
+COMPACT_FILE_TASK_HINTS = """
+FILE TASKS (short form):
+1. write_file {"path": "<name>", "content": "<the whole file>"}
+2. read_file to confirm it exists
+3. {"action": "final", "message": "..."}
+Write the file on your next turn. Do not explain first.
+"""
+
+
+def file_task_hints(profile: Any = None) -> str:
+    """The file-writing hints for a loop profile.
+
+    ``profile`` is an :class:`~latticeai.core.agent_profiles.AgentProfile`, its
+    name, or ``None``. The compact profile gets the numbered short form (small
+    models follow a list better than prose); everything else gets the standard
+    hints, so a strong model's prompt grows by four sentences and no rules.
+    """
+    name = getattr(profile, "name", profile)
+    if str(name or "").strip().lower() == "compact":
+        return COMPACT_FILE_TASK_HINTS.strip()
+    return FILE_TASK_HINTS.strip()
+
+
+def executor_prompt_for(
+    base: str = EXECUTOR_PROMPT,
+    *,
+    profile: Any = None,
+    self_model_summary: Optional[str] = None,
+) -> str:
+    """``base`` plus the file hints, and the Self-Model summary when there is one.
+
+    The injection rule is the same one the context builder follows: an empty
+    (or missing) Self-Model adds nothing at all — no header, no placeholder —
+    so a Brain that knows nothing about its owner produces the prompt it
+    always produced.
+    """
+    parts = [str(base or "").rstrip(), file_task_hints(profile)]
+    summary = str(self_model_summary or "").strip()
+    if summary:
+        parts.append(f"ABOUT THE USER (from their Brain — honour it, do not restate it):\n{summary}")
+    return "\n\n".join(parts)

package/latticeai/core/config.py

@@ -172,7 +172,10 @@ class Config:
         trusted_proxies = [item.strip() for item in _value(env, "LATTICEAI_TRUSTED_PROXIES", "").split(",") if item.strip()]
 
         public_model = _value(env, "LATTICEAI_PUBLIC_MODEL", _value(env, "LATTICEAI_DEFAULT_MODEL", "openai:gpt-4o-mini"))
-        local_model = _value(env, "LATTICEAI_LOCAL_MODEL", "mlx-community/gemma-4-12b-it-4bit")
+        # Canonical HF casing (the Hub answers `gemma-4-12b-it-4bit` with
+        # `gemma-4-12B-it-4bit`); keeping it identical everywhere means the
+        # download path, the on-disk cache dir and the catalog key all agree.
+        local_model = _value(env, "LATTICEAI_LOCAL_MODEL", "mlx-community/gemma-4-12B-it-4bit")
 
         data_dir = Path(_value(env, "LATTICEAI_DATA_DIR", str(Path.home() / ".ltcai")))
         static_dir = Path(_value(env, "LATTICEAI_STATIC_DIR", str(base_dir / "static")))