ltcai 11.0.1 → 11.1.0

package/latticeai/core/workspace_reorganization.py

@@ -0,0 +1,335 @@
+"""Agent-native workspace reorganization — proposals, never a silent tidy-up.
+
+"이 프로젝트를 정리해줘" is a request an agent can now answer without being
+trusted with the filesystem. The Brain looks at a folder, asks the graph what
+each file is *about*, and stages one review proposal describing every move it
+would make. Nothing on disk changes until a person approves it, and approving
+applies exactly the moves that were reviewed.
+
+Three rules make this safe enough to hand to a long-running session:
+
+* **No deletions, ever.** The planner emits moves only. There is no code path
+  here that removes a file, so the worst outcome of a bad proposal is a file
+  in a folder you did not want (recoverable) rather than a file that is gone
+  (not). Plan §10's conservative mitigation, made structural.
+* **Only what the Brain actually knows.** A file is moved because the graph
+  links it to a topic — never because of a guess from its extension. Files the
+  Brain has nothing to say about are reported as ``unplaced`` with a reason
+  instead of being swept somewhere plausible.
+* **Deterministic.** The same folder and the same graph produce the same plan,
+  in the same order: candidates are sorted, topics are chosen by
+  (weight, title), and collisions resolve to the first path alphabetically.
+
+Every path in and out of this module is workspace-relative and resolved
+through the caller's sandboxed ``resolve_path`` (the agent-root resolver), so
+a proposal can never name a target outside the workspace.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import re
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from latticeai.core.timeutil import now_iso as _now
+
+LOGGER = logging.getLogger(__name__)
+
+#: Review-queue kind for a reorganization proposal. Source stays
+#: ``change_proposal`` so the Review Center's approve path applies it through
+#: :class:`~latticeai.services.change_proposals.ChangeProposalService`.
+REORG_KIND = "folder_reorganization"
+
+#: Folder the plan groups into. One level, named after the topic, so the result
+#: is legible without a map.
+TOPIC_ROOT = "topics"
+
+#: Node types that stand for a file on disk, and the ones that stand for what a
+#: file is about.
+FILE_NODE_TYPES = frozenset(
+    {
+        "File", "CodeFile", "Document", "Image", "Spreadsheet", "SlideDeck",
+        "ImageText", "Audio",
+    }
+)
+TOPIC_NODE_TYPES = frozenset({"Topic", "Concept", "Project", "Feature"})
+
+DEFAULT_MAX_MOVES = 20
+DEFAULT_SCAN_LIMIT = 400
+DEFAULT_GRAPH_LIMIT = 800
+
+_SLUG_RE = re.compile(r"[^0-9A-Za-z가-힣._-]+")
+
+
+def _slug(value: str) -> str:
+    """Folder-safe topic name (Korean kept — the user reads these folders)."""
+    return _SLUG_RE.sub("-", str(value or "").strip()).strip("-.").lower()[:48]
+
+
+def _rel(path: Path, base: Path) -> str:
+    return path.relative_to(base).as_posix()
+
+
+def _scan(base: Path, limit: int) -> List[Path]:
+    """Visible files under ``base``, deepest-stable order, capped at ``limit``."""
+    found: List[Path] = []
+    for path in sorted(base.rglob("*")):
+        if len(found) >= limit:
+            break
+        if not path.is_file():
+            continue
+        if any(part.startswith(".") for part in path.relative_to(base).parts):
+            continue
+        found.append(path)
+    return found
+
+
+def _file_node_index(graph: Any, limit: int) -> Tuple[Dict[str, str], str]:
+    """``{file name → graph node id}`` plus the basis for the plan.
+
+    A missing or unreadable graph yields an empty index and a basis that says
+    so, which is what makes an empty plan honest rather than mysterious.
+    """
+    if graph is None:
+        return {}, "no_graph"
+    try:
+        data = graph.graph(limit)
+    except Exception:  # noqa: BLE001 — a broken read proposes nothing
+        LOGGER.exception("workspace reorganization graph read failed")
+        return {}, "graph_unavailable"
+    index: Dict[str, str] = {}
+    for node in data.get("nodes") or []:
+        if str(node.get("type")) not in FILE_NODE_TYPES:
+            continue
+        for key in _file_keys(node):
+            index.setdefault(key, str(node.get("id")))
+    return index, "graph"
+
+
+def _topic_for(graph: Any, node_id: str) -> str:
+    """The topic a file node belongs to, or ``""`` when the Brain has none.
+
+    One hop, strongest edge first; ties break on the topic title so the same
+    graph always produces the same folder.
+    """
+    try:
+        data = graph.neighbors(node_id)
+    except Exception:  # noqa: BLE001 — one unreadable node is not a failure
+        LOGGER.exception("workspace reorganization neighbour read failed")
+        return ""
+    by_id = {str(node.get("id")): node for node in data.get("neighbors") or []}
+    best: Optional[Tuple[float, str]] = None
+    for edge in data.get("edges") or []:
+        far = edge.get("to") if str(edge.get("from")) == node_id else edge.get("from")
+        node = by_id.get(str(far))
+        if node is None or str(node.get("type")) not in TOPIC_NODE_TYPES:
+            continue
+        title = str(node.get("title") or "").strip()
+        if not title:
+            continue
+        candidate = (-float(edge.get("weight") or 1.0), title)
+        if best is None or candidate < best:
+            best = candidate
+    return best[1] if best is not None else ""
+
+
+def _file_keys(node: Dict[str, Any]) -> List[str]:
+    """Every name a graph file node might be matched by (lowercased)."""
+    metadata = node.get("metadata") or {}
+    candidates = [
+        metadata.get("relative_path"),
+        metadata.get("filename"),
+        metadata.get("path"),
+        node.get("title"),
+    ]
+    keys: List[str] = []
+    for candidate in candidates:
+        text = str(candidate or "").strip()
+        if not text:
+            continue
+        for key in (text.lower(), Path(text).name.lower()):
+            if key and key not in keys:
+                keys.append(key)
+    return keys
+
+
+def plan_reorganization(
+    *,
+    root: str = "",
+    resolve_path: Callable[[str], Path],
+    graph: Any = None,
+    max_moves: int = DEFAULT_MAX_MOVES,
+    scan_limit: int = DEFAULT_SCAN_LIMIT,
+    graph_limit: int = DEFAULT_GRAPH_LIMIT,
+) -> Dict[str, Any]:
+    """What the Brain would move, and what it deliberately would not.
+
+    Read-only: this touches no file and creates no proposal.
+    """
+    base = resolve_path(root)
+    if not base.is_dir():
+        return _empty_plan(root, "folder_missing")
+    index, basis = _file_node_index(graph, graph_limit)
+    moves: List[Dict[str, Any]] = []
+    unplaced: List[Dict[str, Any]] = []
+    claimed: set = set()
+    for path in _scan(base, scan_limit):
+        source = _rel(path, base)
+        node_id = index.get(source.lower()) or index.get(path.name.lower())
+        topic = _topic_for(graph, node_id) if node_id else ""
+        if not topic:
+            unplaced.append({"path": source, "reason": "brain_has_no_topic"})
+            continue
+        target = f"{TOPIC_ROOT}/{_slug(topic)}/{path.name}"
+        if target == source:
+            unplaced.append({"path": source, "reason": "already_in_place"})
+            continue
+        if target in claimed or (base / target).exists():
+            unplaced.append({"path": source, "reason": "target_taken"})
+            continue
+        claimed.add(target)
+        moves.append({
+            "source": source,
+            "target": target,
+            "topic": topic,
+            "reason": f"'{topic}' 주제와 이어져 있습니다",
+        })
+    trimmed = len(moves) > max_moves
+    return {
+        "available": True,
+        "root": root,
+        "basis": basis,
+        "moves": moves[: max(0, int(max_moves))],
+        "move_count": len(moves[: max(0, int(max_moves))]),
+        "truncated": trimmed,
+        "unplaced": unplaced,
+        "unplaced_count": len(unplaced),
+        # Structural, not a policy toggle: this planner has no delete path.
+        "deletes": [],
+        "generated_at": _now(),
+    }
+
+
+def _empty_plan(root: str, reason: str) -> Dict[str, Any]:
+    return {
+        "available": False,
+        "root": root,
+        "basis": reason,
+        "moves": [],
+        "move_count": 0,
+        "truncated": False,
+        "unplaced": [],
+        "unplaced_count": 0,
+        "deletes": [],
+        "generated_at": _now(),
+    }
+
+
+def propose_reorganization(
+    *,
+    root: str = "",
+    resolve_path: Callable[[str], Path],
+    review_queue: Any,
+    graph: Any = None,
+    user_email: Optional[str] = None,
+    workspace_id: Optional[str] = None,
+    max_moves: int = DEFAULT_MAX_MOVES,
+    audit: Optional[Callable[..., None]] = None,
+) -> Dict[str, Any]:
+    """Stage one review proposal describing the whole reorganization.
+
+    Returns ``{"proposed": None, ...}`` when there is nothing to propose — an
+    empty proposal is noise, and a Brain that knows nothing about a folder
+    should say so rather than invent a structure.
+    """
+    plan = plan_reorganization(
+        root=root, resolve_path=resolve_path, graph=graph, max_moves=max_moves
+    )
+    if not plan["moves"]:
+        return {"proposed": None, "plan": plan, "reason": plan["basis"]}
+    preview = ", ".join(move["source"] for move in plan["moves"][:3])
+    item = review_queue.create(
+        title=f"폴더 정리 제안: {root or '작업 폴더'} 파일 {plan['move_count']}개",
+        summary=(
+            f"{preview} 등 {plan['move_count']}개 파일을 주제별 폴더로 옮기는 제안입니다. "
+            "삭제는 제안하지 않으며, 승인하기 전에는 아무것도 움직이지 않습니다."
+        ),
+        source="change_proposal",
+        kind=REORG_KIND,
+        payload={
+            "root": root,
+            "moves": plan["moves"],
+            "unplaced": plan["unplaced"],
+            "basis": plan["basis"],
+            "contract": {"moves": "proposal", "deletions": "never_proposed"},
+        },
+        provenance={
+            "proposed_by": "agent",
+            "reason": "workspace reorganization",
+            "source_detail": "brain topic grouping",
+        },
+        user_email=user_email,
+        workspace_id=workspace_id,
+    )
+    if audit is not None:
+        audit(
+            "workspace_reorg_proposed",
+            user_email=user_email,
+            proposal_id=item.get("id"),
+            moves=plan["move_count"],
+        )
+    return {"proposed": item, "plan": plan, "reason": ""}
+
+
+def apply_reorganization(
+    payload: Dict[str, Any], *, resolve_path: Callable[[str], Path]
+) -> Dict[str, Any]:
+    """Carry out the reviewed moves. Nothing is ever deleted or overwritten.
+
+    Each move is checked again at apply time: a source that vanished and a
+    target that appeared are both reported as skipped rather than forced, so a
+    stale proposal degrades into an honest partial result.
+    """
+    applied: List[Dict[str, Any]] = []
+    skipped: List[Dict[str, Any]] = []
+    for move in payload.get("moves") or []:
+        source_rel = str(move.get("source") or "")
+        target_rel = str(move.get("target") or "")
+        if not source_rel or not target_rel:
+            skipped.append({"source": source_rel, "reason": "incomplete_move"})
+            continue
+        source = resolve_path(_join(payload, source_rel))
+        target = resolve_path(_join(payload, target_rel))
+        if not source.is_file():
+            skipped.append({"source": source_rel, "reason": "source_missing"})
+            continue
+        if target.exists():
+            skipped.append({"source": source_rel, "reason": "target_exists"})
+            continue
+        target.parent.mkdir(parents=True, exist_ok=True)
+        os.replace(source, target)
+        applied.append({"source": source_rel, "target": target_rel})
+    return {
+        "applied": applied,
+        "applied_count": len(applied),
+        "skipped": skipped,
+        "skipped_count": len(skipped),
+        "deleted": 0,
+    }
+
+
+def _join(payload: Dict[str, Any], relative: str) -> str:
+    root = str(payload.get("root") or "").strip("/")
+    return f"{root}/{relative}" if root else relative
+
+
+__all__ = [
+    "DEFAULT_MAX_MOVES",
+    "REORG_KIND",
+    "TOPIC_ROOT",
+    "apply_reorganization",
+    "plan_reorganization",
+    "propose_reorganization",
+]

package/latticeai/runtime/build_phases.py

@@ -542,6 +542,7 @@ def phase_brain(ctx: RuntimeContext) -> None:
         "BRAIN_INTELLIGENCE",
         "AUTOMATION_INTELLIGENCE",
         "INGESTION_PIPELINE",
+        "MULTIMODAL_PORTS",
         "DEVICE_IDENTITY",
         "KG_PORTABILITY",
         "FUNNEL_METRICS",
@@ -1197,11 +1198,13 @@ def phase_platform_features(ctx: RuntimeContext) -> None:
 
     # Voice memo capture (v9.9.7): the shortest path from a thought to the
     # Brain. Transcription is an optional local port — absent, the memo is
-    # still stored and the response says it is not searchable.
+    # still stored and the response says it is not searchable. v11.1.0 shares
+    # that one port with multi-modal ingestion, so a memo and a scanned
+    # recording can never disagree about whether this machine can hear.
     ctx.set(
         VOICE_CAPTURE=VoiceCaptureService(
             pipeline=ctx.INGESTION_PIPELINE if ctx.ENABLE_GRAPH else None,
-            transcriber=None,
+            transcriber=ctx.MULTIMODAL_PORTS.transcriber,
         )
     )
     ctx.app.include_router(

package/latticeai/runtime/persistence_runtime.py

@@ -42,6 +42,10 @@ def build_persistence_runtime(
     from latticeai.services.brain_intelligence import BrainIntelligenceService
     from latticeai.services.funnel_metrics import FunnelMetricsService
     from latticeai.services.memory_service import MemoryService
+    from latticeai.services.multimodal_ports import (
+        build_multimodal_ports,
+        multimodal_enabled,
+    )
     from latticeai.services.workspace_service import WorkspaceService
 
     realtime_bus = RealtimeBus()
@@ -80,21 +84,53 @@ def build_persistence_runtime(
     funnel_metrics = FunnelMetricsService(Path(data_dir) / "funnel_metrics.json")
 
     def _funnel_audit(action, detail, user):
-        try:
-            if action == "kg_ingest":
+        """Best-effort sinks for a landed ingest, then the real audit.
+
+        Both sinks are isolated separately: one failing must not cost the
+        other, and neither may cost the ingest that is already persisted.
+        """
+        if action == "kg_ingest":
+            try:
                 funnel_metrics.record_ingest(
                     duplicate=bool((detail or {}).get("duplicate"))
                 )
-        except Exception:  # noqa: BLE001 — metrics must never break ingestion
-            quiet()
+            except Exception:  # noqa: BLE001 — metrics must never break ingestion
+                quiet()
+            # v11.1.0: the same seam drives synthesis. The pipeline audits an
+            # ingest only after the graph write landed, so ``status: "ok"`` is
+            # a fact about this call site rather than a guess; ``duplicate``
+            # travels in the detail and is what keeps a re-import from pushing
+            # the Brain toward a pass it has nothing new to say in.
+            try:
+                brain_intelligence.note_ingest(
+                    {"status": "ok", **(detail or {})}, user_email=user
+                )
+            except Exception:  # noqa: BLE001 — synthesis must never break ingestion
+                quiet()
         audit(action, detail, user)
 
+    # Multi-modal capture (v11.1.0): off unless the user turned it on, and
+    # even then only as capable as the models actually present. With nothing
+    # configured this resolves to an empty bundle without importing or loading
+    # anything.
+    multimodal_ports = build_multimodal_ports()
     ingestion_pipeline = IngestionPipeline(
         knowledge_graph,
         hooks=hooks_registry,
         enable_graph=enable_graph,
         audit=_funnel_audit,
+        allow_multimodal=multimodal_enabled(),
+        multimodal=multimodal_ports,
     )
+    # The local folder scanner reads images through the same ports, so a
+    # caption in the Evidence panel and a caption on a scanned screenshot come
+    # from one model or from none. A disabled/absent graph has nothing to
+    # attach them to, and a store that refuses new attributes is not a reason
+    # to fail startup.
+    try:
+        knowledge_graph.multimodal_ports = multimodal_ports
+    except AttributeError:
+        quiet()
     device_identity = DeviceIdentity(data_dir)
     kg_portability = KGPortabilityService(
         knowledge_graph=knowledge_graph,
@@ -116,6 +152,7 @@ def build_persistence_runtime(
         "BRAIN_INTELLIGENCE": brain_intelligence,
         "AUTOMATION_INTELLIGENCE": automation_intelligence,
         "INGESTION_PIPELINE": ingestion_pipeline,
+        "MULTIMODAL_PORTS": multimodal_ports,
         "DEVICE_IDENTITY": device_identity,
         "KG_PORTABILITY": kg_portability,
         "FUNNEL_METRICS": funnel_metrics,

package/latticeai/runtime/runtime_context.py

@@ -144,6 +144,7 @@ class RuntimeContext:
     BRAIN_INTELLIGENCE: Any
     AUTOMATION_INTELLIGENCE: Any
     INGESTION_PIPELINE: Any
+    MULTIMODAL_PORTS: Any
     DEVICE_IDENTITY: Any
     KG_PORTABILITY: Any
     FUNNEL_METRICS: Any

package/latticeai/services/architecture_readiness.py

@@ -16,7 +16,7 @@ from typing import Any, Dict, List
 
 from latticeai.core.legacy_compatibility import legacy_shim_report
 
-ARCHITECTURE_VERSION_TARGET = "11.0.1"
+ARCHITECTURE_VERSION_TARGET = "11.1.0"
 
 PREFERRED_REFACTORING_ORDER = [
     "agent-runtime",

package/latticeai/services/change_proposals.py

@@ -31,6 +31,11 @@ from typing import Any, Callable, Dict, List, Optional, Tuple
 
 from latticeai.core.quiet import quiet
 from latticeai.core.tool_governor import classify_tool_call
+from latticeai.core.workspace_reorganization import (
+    REORG_KIND,
+    apply_reorganization,
+    propose_reorganization,
+)
 
 LOGGER = logging.getLogger(__name__)
 
@@ -301,6 +306,33 @@ class ChangeProposalService:
         )
         return item
 
+    def propose_reorganization(
+        self,
+        *,
+        root: str = "",
+        graph: Any = None,
+        user_email: Optional[str] = None,
+        workspace_id: Optional[str] = None,
+        max_moves: int = 20,
+    ) -> Dict[str, Any]:
+        """Stage a whole-folder reorganization as one reviewable proposal.
+
+        Moves only — see :mod:`latticeai.core.workspace_reorganization`. It
+        goes through this service (rather than the review queue directly) so
+        approving it from the Review Center applies it the same way every
+        other staged change is applied.
+        """
+        return propose_reorganization(
+            root=root,
+            resolve_path=self._resolve_path,
+            review_queue=self._review_queue,
+            graph=graph,
+            user_email=user_email,
+            workspace_id=workspace_id,
+            max_moves=max_moves,
+            audit=self._audit,
+        )
+
     # ── listing / apply / reject ─────────────────────────────────────────
 
     def pending(
@@ -362,8 +394,8 @@ class ChangeProposalService:
                 raise KeyError(f"not a change proposal: {item_id}")
             payload = item.get("payload") or {}
             kind = str(item.get("kind") or "")
-            path = str(payload.get("path") or "")
-            if kind not in ("file_update", "file_delete"):
+            path = str(payload.get("path") or payload.get("root") or "")
+            if kind not in ("file_update", "file_delete", REORG_KIND):
                 raise ValueError(f"unknown change proposal kind: {kind}")
 
             # Duplicate/concurrent approval guard: a resolved proposal must
@@ -375,20 +407,28 @@ class ChangeProposalService:
                     rebase_hint="이미 처리된 제안입니다. 다시 적용할 수 없습니다.",
                 )
 
-            self._check_base_unchanged(payload, path=path, kind=kind)
-
-            target = self._resolve_path(path)
-            if kind == "file_update":
-                self._atomic_write(target, str(payload.get("new_content") or ""))
-            else:  # file_delete — existence re-verified inside the lock
-                if target.is_file():
+            moves: Optional[Dict[str, Any]] = None
+            if kind == REORG_KIND:
+                # A reorganization has no single base file to hash: each move
+                # is re-checked at apply time and a drifted one is skipped,
+                # never forced (see workspace_reorganization.apply_*).
+                moves = apply_reorganization(payload, resolve_path=self._resolve_path)
+            else:
+                self._check_base_unchanged(payload, path=path, kind=kind)
+                target = self._resolve_path(path)
+                if kind == "file_update":
+                    self._atomic_write(target, str(payload.get("new_content") or ""))
+                elif target.is_file():  # file_delete — re-verified inside the lock
                     target.unlink()
             approved = self._review_queue.approve(item_id, workspace_id=workspace_id)
         self._audit(
             "change_proposal_applied", user_email=user_email,
             proposal_id=item_id, path=path, kind=kind,
         )
-        return {"item": approved, "applied": True, "path": path, "kind": kind}
+        result = {"item": approved, "applied": True, "path": path, "kind": kind}
+        if moves is not None:
+            result["moves"] = moves
+        return result
 
     def _check_base_unchanged(
         self, payload: Dict[str, Any], *, path: str, kind: str

package/latticeai/services/memory_service.py

@@ -44,6 +44,33 @@ TIERS = ("workspace", "project", "agent", "conversation", "graph", "vector")
 LOGGER = logging.getLogger(__name__)
 
 
+#: Longest inline thumbnail a recall row will carry (see ``_visual_fields``).
+MAX_RECALL_THUMBNAIL_CHARS = 24_000
+
+
+def _visual_fields(hit: Dict[str, Any]) -> Dict[str, Any]:
+    """Caption + inline thumbnail for a recall row, when the node has them.
+
+    v11.1.0: an ``Image`` node stores a 96px ``data:`` thumbnail and — only if
+    a vision-language model produced one — a caption. Passing them through here
+    is what lets the Evidence panel show the picture it is citing without a new
+    static route over the user's disk and without going around the local-file
+    approval gate: the bytes are already inside the graph payload the user
+    asked for. Absent keys stay absent, so every non-image row is unchanged.
+    """
+    metadata = hit.get("metadata")
+    if not isinstance(metadata, dict):
+        return {}
+    fields: Dict[str, Any] = {}
+    caption = str(metadata.get("caption") or "").strip()
+    if caption:
+        fields["caption"] = caption[:400]
+    thumbnail = str(metadata.get("thumbnail") or "")
+    if thumbnail.startswith("data:image/") and len(thumbnail) <= MAX_RECALL_THUMBNAIL_CHARS:
+        fields["thumbnail"] = thumbnail
+    return fields
+
+
 class MemoryServiceError(RuntimeError):
     """Raised when a configured memory backend cannot be read reliably."""
 
@@ -763,6 +790,11 @@ class MemoryService:
                 # citation UI can show the matched terms instead of a bare score.
                 "matched_terms": item.get("matched_terms") or [],
                 "confidence": item.get("confidence") or "low",
+                # v11.1.0: what kind of memory this is, and — for a picture —
+                # the caption and inline thumbnail the Evidence panel renders.
+                "kind": item.get("kind") or "",
+                **({"caption": item["caption"]} if item.get("caption") else {}),
+                **({"thumbnail": item["thumbnail"]} if item.get("thumbnail") else {}),
             }
             for item in list(recall.get("results", []))[: max(1, min(limit, 8))]
         ]
@@ -903,6 +935,7 @@ class MemoryService:
                     "kind": hit.get("type") or "node",
                     "score": _lexical_score(matched),
                     "matched_terms": matched,
+                    **_visual_fields(hit),
                 })
 
         # v9.3.0 hybrid recall: blend semantic similarity from the vector
@@ -964,6 +997,7 @@ class MemoryService:
                         "matched_terms": matched,
                         "vector_score": similarity,
                         **({"locator": locator} if locator else {}),
+                        **_visual_fields(hit),
                     }
                     results.append(row)
                     if node_id: