ltcai 4.3.3 → 4.5.1

package/latticeai/brain/discovery.py

@@ -1,1455 +1,17 @@
-from __future__ import annotations
+"""Deprecated shim: physically moved to lattice_brain.graph.discovery.
 
-# ruff: noqa: F403,F405
+Kept only for the compatibility window. The module aliases itself to the
+physical module so identity, singletons, and monkeypatching are preserved.
+"""
 
-from ._kg_common import *  # noqa: F403,F401
+import sys
+import warnings
 
+import lattice_brain.graph.discovery as _impl
 
-class KnowledgeGraphDiscoveryMixin:
-    def discover_local_roots(self) -> Dict[str, Any]:
-        """Return safe, cross-platform starting points for structure browsing."""
-        os_type = _current_os_type()
-        home = Path.home().expanduser()
-        roots: List[Dict[str, Any]] = []
-        seen: set = set()
-
-        def add(
-            label: str,
-            path: Path,
-            kind: str,
-            *,
-            recommended: bool = True,
-            warning: Optional[str] = None,
-        ) -> None:
-            try:
-                resolved = path.expanduser().resolve()
-            except OSError:
-                resolved = path.expanduser()
-            key = str(resolved)
-            if key in seen or not resolved.exists():
-                return
-            seen.add(key)
-            roots.append(
-                {
-                    "id": f"{kind}:{_path_fingerprint(resolved)}",
-                    "label": label,
-                    "path": key,
-                    "kind": kind,
-                    "recommended": recommended,
-                    "warning": warning or _root_warning(resolved, os_type),
-                }
-            )
-
-        add("홈", home, "home", warning=_root_warning(home, os_type))
-        for name, label in (
-            ("Documents", "문서"),
-            ("Desktop", "데스크탑"),
-            ("Downloads", "다운로드"),
-            ("Pictures", "사진"),
-            ("Projects", "프로젝트"),
-        ):
-            add(label, home / name, name.lower())
-
-        if os_type == "macos":
-            volumes = Path("/Volumes")
-            if volumes.exists():
-                try:
-                    for volume in sorted(
-                        volumes.iterdir(), key=lambda p: p.name.lower()
-                    ):
-                        add(volume.name, volume, "volume", recommended=False)
-                except OSError:
-                    pass
-        elif os_type == "windows":
-            for letter in "ABCDEFGHIJKLMNOPQRSTUVWXYZ":
-                drive = Path(f"{letter}:\\")
-                if drive.exists():
-                    add(
-                        f"{letter}: 드라이브",
-                        drive,
-                        "drive",
-                        recommended=(letter != "C"),
-                    )
-            for env_name, label in (
-                ("OneDrive", "OneDrive"),
-                ("OneDriveCommercial", "OneDrive"),
-            ):
-                raw = os.environ.get(env_name)
-                if raw:
-                    add(label, Path(raw), "cloud", recommended=False)
-        elif os_type == "linux":
-            for base in (Path("/mnt"), Path("/media")):
-                add(str(base), base, "mounts", recommended=False)
-                try:
-                    if base.exists():
-                        for mounted in sorted(
-                            base.iterdir(), key=lambda p: p.name.lower()
-                        ):
-                            add(mounted.name, mounted, "volume", recommended=False)
-                except OSError:
-                    pass
-
-        return {
-            "os_type": os_type,
-            "computer": platform.node() or "local",
-            "roots": roots,
-            "privacy_notice": "처음에는 드라이브와 폴더 구조만 확인하며, 파일 내용은 사용자가 동의한 뒤에만 읽습니다.",
-        }
-
-    def preview_local_tree(self, path: Path, *, max_items: int = 200) -> Dict[str, Any]:
-        """List one folder level using metadata only; file contents are not read."""
-        root = Path(path).expanduser().resolve()
-        if not root.exists():
-            raise ValueError(f"경로가 존재하지 않습니다: {path}")
-        if not root.is_dir():
-            raise ValueError(f"폴더가 아닙니다: {path}")
-
-        os_type = _current_os_type()
-        max_items = max(1, min(int(max_items or 200), 1000))
-        items: List[Dict[str, Any]] = []
-        inaccessible = 0
-        try:
-            children = sorted(
-                root.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower())
-            )
-        except PermissionError as exc:
-            return {
-                "path": str(root),
-                "items": [],
-                "error": f"접근 권한 없음: {exc}",
-                "privacy_notice": "현재 단계에서는 파일 내용을 읽지 않고, 폴더와 파일의 이름/크기/수정일만 확인합니다.",
-            }
-
-        for child in children[:max_items]:
-            try:
-                is_dir = child.is_dir()
-                stat = child.stat()
-                reason = (
-                    _excluded_directory_reason(child, root=root, os_type=os_type)
-                    if is_dir
-                    else _sensitive_file_reason(child, root=root)
-                )
-                items.append(
-                    {
-                        "name": child.name,
-                        "path": str(child),
-                        "type": "directory" if is_dir else "file",
-                        "extension": "" if is_dir else child.suffix.lower(),
-                        "size_bytes": None if is_dir else stat.st_size,
-                        "modified_at": _safe_iso_from_stat_mtime(stat.st_mtime),
-                        "hidden": _is_hidden_path(child, root),
-                        "accessible": True,
-                        "excluded_reason": reason,
-                    }
-                )
-            except PermissionError:
-                inaccessible += 1
-                items.append(
-                    {
-                        "name": child.name,
-                        "path": str(child),
-                        "type": "unknown",
-                        "accessible": False,
-                        "excluded_reason": "permission_denied",
-                    }
-                )
-            except OSError as exc:
-                inaccessible += 1
-                items.append(
-                    {
-                        "name": child.name,
-                        "path": str(child),
-                        "type": "unknown",
-                        "accessible": False,
-                        "excluded_reason": str(exc),
-                    }
-                )
-
-        return {
-            "path": str(root),
-            "os_type": os_type,
-            "items": items,
-            "truncated": len(children) > max_items,
-            "inaccessible": inaccessible,
-            "warning": _root_warning(root, os_type),
-            "privacy_notice": "현재 단계에서는 파일 내용을 읽지 않고, 폴더와 파일의 이름/크기/수정일만 확인합니다.",
-        }
-
-    def _iter_local_scan_entries(
-        self, root: Path, *, max_files: int
-    ) -> Iterable[Dict[str, Any]]:
-        os_type = _current_os_type()
-        stack = [root]
-        files_seen = 0
-        while stack:
-            current = stack.pop()
-            try:
-                children = sorted(
-                    current.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower())
-                )
-            except PermissionError as exc:
-                yield {
-                    "kind": "inaccessible_dir",
-                    "path": current,
-                    "reason": f"permission_denied: {exc}",
-                }
-                continue
-            except OSError as exc:
-                yield {"kind": "inaccessible_dir", "path": current, "reason": str(exc)}
-                continue
-
-            for child in children:
-                if child.is_symlink():
-                    yield {"kind": "excluded", "path": child, "reason": "symlink"}
-                    continue
-                try:
-                    if child.is_dir():
-                        reason = _excluded_directory_reason(
-                            child, root=root, os_type=os_type
-                        )
-                        if reason:
-                            yield {
-                                "kind": "excluded_dir",
-                                "path": child,
-                                "reason": reason,
-                            }
-                        else:
-                            stack.append(child)
-                        continue
-                    if not child.is_file():
-                        yield {
-                            "kind": "excluded",
-                            "path": child,
-                            "reason": "not_regular_file",
-                        }
-                        continue
-                    stat = child.stat()
-                except PermissionError as exc:
-                    yield {
-                        "kind": "inaccessible_file",
-                        "path": child,
-                        "reason": f"permission_denied: {exc}",
-                    }
-                    continue
-                except OSError as exc:
-                    yield {
-                        "kind": "inaccessible_file",
-                        "path": child,
-                        "reason": str(exc),
-                    }
-                    continue
-
-                files_seen += 1
-                if files_seen > max_files:
-                    yield {
-                        "kind": "limit_reached",
-                        "path": child,
-                        "reason": "max_files",
-                    }
-                    return
-                yield {"kind": "file", "path": child, "stat": stat}
-
-    def _local_file_decision(
-        self, path: Path, root: Path, stat: os.stat_result
-    ) -> Dict[str, Any]:
-        ext = path.suffix.lower()
-        category = _file_category(ext)
-        parser_type = _parser_type_for_category(category, ext)
-        sensitive_reason = _sensitive_file_reason(path, root=root)
-        if sensitive_reason:
-            return {
-                "status": "sensitive_blocked",
-                "reason": sensitive_reason,
-                "category": category,
-                "parser_type": parser_type,
-                "indexable": False,
-            }
-        if category == "unsupported":
-            return {
-                "status": "unsupported",
-                "reason": "unsupported_extension",
-                "category": category,
-                "parser_type": parser_type,
-                "indexable": False,
-            }
-        limit = _size_limit_for_category(category)
-        if stat.st_size > limit:
-            return {
-                "status": "too_large",
-                "reason": f"size>{limit}",
-                "category": category,
-                "parser_type": parser_type,
-                "indexable": False,
-            }
-        return {
-            "status": "pending",
-            "reason": "",
-            "category": category,
-            "parser_type": parser_type,
-            "indexable": True,
-        }
-
-    def audit_local_folder(
-        self, path: Path, *, include_ocr: bool = False, max_files: int = 50_000
-    ) -> Dict[str, Any]:
-        """Safety-check a folder using metadata only; file bodies are not read."""
-        root = Path(path).expanduser().resolve()
-        if not root.exists():
-            raise ValueError(f"경로가 존재하지 않습니다: {path}")
-        if not root.is_dir():
-            raise ValueError(f"폴더가 아닙니다: {path}")
-
-        os_type = _current_os_type()
-        max_files = max(1, min(int(max_files or 50_000), 200_000))
-        status_counts: Counter = Counter()
-        category_counts: Counter = Counter()
-        extension_counts: Counter = Counter()
-        allowed_samples: List[Dict[str, Any]] = []
-        excluded_samples: List[Dict[str, Any]] = []
-        total_files = 0
-        readable_files = 0
-        inaccessible = 0
-        excluded_dirs = 0
-        limit_reached = False
-
-        for entry in self._iter_local_scan_entries(root, max_files=max_files):
-            kind = entry["kind"]
-            path_obj = entry["path"]
-            if kind == "limit_reached":
-                limit_reached = True
-                break
-            if kind == "excluded_dir":
-                excluded_dirs += 1
-                if len(excluded_samples) < 25:
-                    excluded_samples.append(
-                        _sample_file(
-                            path_obj, root, "excluded", entry.get("reason", "")
-                        )
-                    )
-                continue
-            if kind in {"inaccessible_dir", "inaccessible_file"}:
-                inaccessible += 1
-                status_counts["failed"] += 1
-                if len(excluded_samples) < 25:
-                    excluded_samples.append(
-                        _sample_file(path_obj, root, "failed", entry.get("reason", ""))
-                    )
-                continue
-            if kind == "excluded":
-                status_counts["excluded"] += 1
-                if len(excluded_samples) < 25:
-                    excluded_samples.append(
-                        _sample_file(
-                            path_obj, root, "excluded", entry.get("reason", "")
-                        )
-                    )
-                continue
-            if kind != "file":
-                continue
-
-            total_files += 1
-            stat = entry["stat"]
-            decision = self._local_file_decision(path_obj, root, stat)
-            status = decision["status"]
-            category = decision["category"]
-            ext = path_obj.suffix.lower() or "(none)"
-            category_counts[category] += 1
-            extension_counts[ext] += 1
-            if decision["indexable"]:
-                readable_files += 1
-                status_counts["readable"] += 1
-                if len(allowed_samples) < 25:
-                    allowed_samples.append(_sample_file(path_obj, root, "readable"))
-            else:
-                status_counts[status] += 1
-                if len(excluded_samples) < 25:
-                    excluded_samples.append(
-                        _sample_file(path_obj, root, status, decision["reason"])
-                    )
-
-        doc_weight = (
-            category_counts["pdf"] * 1.4
-            + category_counts["document"] * 0.9
-            + category_counts["slide_deck"] * 1.0
-        )
-        sheet_weight = category_counts["spreadsheet"] * 0.6
-        ocr_weight = category_counts["image"] * (1.8 if include_ocr else 0.1)
-        estimated_seconds = round(
-            readable_files * 0.04 + doc_weight + sheet_weight + ocr_weight, 1
-        )
-
-        return {
-            "path": str(root),
-            "source_id": f"source:{_path_fingerprint(root)}",
-            "os_type": os_type,
-            "drive_id": _drive_id_for_path(root),
-            "warning": _root_warning(root, os_type),
-            "privacy_notice": "현재 단계에서는 파일 내용을 읽지 않고, 폴더와 파일의 이름/크기/수정일만 확인합니다.",
-            "include_ocr_requested": bool(include_ocr),
-            "summary": {
-                "total_files": total_files,
-                "readable_files": readable_files,
-                "excluded_files": int(
-                    status_counts["excluded"]
-                    + status_counts["sensitive_blocked"]
-                    + status_counts["too_large"]
-                    + status_counts["unsupported"]
-                ),
-                "sensitive_files": int(status_counts["sensitive_blocked"]),
-                "too_large_files": int(status_counts["too_large"]),
-                "unsupported_files": int(status_counts["unsupported"]),
-                "image_ocr_candidates": int(category_counts["image"]),
-                "inaccessible_items": inaccessible,
-                "excluded_dirs": excluded_dirs,
-                "estimated_seconds": estimated_seconds,
-                "storage_root": str(self.db_path.parent),
-                "limit_reached": limit_reached,
-            },
-            "by_status": dict(status_counts),
-            "by_category": dict(category_counts),
-            "by_extension": dict(extension_counts.most_common(40)),
-            "allowed_samples": allowed_samples,
-            "excluded_samples": excluded_samples,
-            "consent_required": {
-                "knowledge_source": True,
-                "image_ocr": bool(category_counts["image"]),
-                "watch": True,
-                "sensitive_files_default_excluded": True,
-            },
-        }
-
-    def local_sources(self) -> Dict[str, Any]:
-        with self._connect() as conn:
-            sources = [
-                {
-                    "id": row["id"],
-                    "root_path": row["root_path"],
-                    "os_type": row["os_type"],
-                    "drive_id": row["drive_id"],
-                    "label": row["label"],
-                    "status": row["status"],
-                    "include_ocr": bool(row["include_ocr"]),
-                    "watch_enabled": bool(row["watch_enabled"]),
-                    "consent": _safe_loads(row["consent_json"]),
-                    "created_at": row["created_at"],
-                    "updated_at": row["updated_at"],
-                    "last_scanned_at": row["last_scanned_at"],
-                }
-                for row in conn.execute(
-                    """
-                        SELECT id, root_path, os_type, drive_id, label, status, include_ocr,
-                               watch_enabled, consent_json, created_at, updated_at, last_scanned_at
-                        FROM knowledge_sources
-                        ORDER BY updated_at DESC, id ASC
-                        """
-                )
-            ]
-            status_rows = conn.execute(
-                "SELECT source_id, status, COUNT(*) AS count FROM local_file_index GROUP BY source_id, status"
-            ).fetchall()
-        counts: Dict[str, Dict[str, int]] = {}
-        for row in status_rows:
-            counts.setdefault(row["source_id"], {})[row["status"]] = row["count"]
-        for source in sources:
-            source["file_status"] = counts.get(source["id"], {})
-        return {"sources": sources}
-
-    def set_local_source_watch(self, source_id: str, enabled: bool) -> Dict[str, Any]:
-        source_id = str(source_id or "").strip()
-        if not source_id:
-            raise ValueError("source_id required")
-        with self._connect() as conn:
-            row = conn.execute(
-                "SELECT id FROM knowledge_sources WHERE id=?",
-                (source_id,),
-            ).fetchone()
-            if not row:
-                raise ValueError(f"knowledge source not found: {source_id}")
-            conn.execute(
-                "UPDATE knowledge_sources SET watch_enabled=?, updated_at=? WHERE id=?",
-                (1 if enabled else 0, _now(), source_id),
-            )
-        return {"source_id": source_id, "watch_enabled": bool(enabled)}
-
-    def remove_local_source(self, source_id: str) -> Dict[str, Any]:
-        """Remove one approved local source and its derived graph projection.
-
-        This is intentionally non-destructive for user files: only the LatticeAI
-        index rows, graph nodes, edges, and chunks derived from the source are
-        removed. The original folder and files are never touched.
-        """
-        source_id = str(source_id or "").strip()
-        if not source_id:
-            raise ValueError("source_id required")
-        with self._connect() as conn:
-            source = conn.execute(
-                "SELECT id, root_path FROM knowledge_sources WHERE id=?",
-                (source_id,),
-            ).fetchone()
-            if not source:
-                raise ValueError(f"knowledge source not found: {source_id}")
-            rows = conn.execute(
-                "SELECT graph_node_id FROM local_file_index WHERE source_id=? AND graph_node_id IS NOT NULL",
-                (source_id,),
-            ).fetchall()
-            graph_node_ids = [
-                row["graph_node_id"] for row in rows if row["graph_node_id"]
-            ]
-            for graph_node_id in graph_node_ids:
-                self._delete_local_file_graph(conn, graph_node_id)
-            conn.execute("DELETE FROM local_file_index WHERE source_id=?", (source_id,))
-            conn.execute("DELETE FROM knowledge_sources WHERE id=?", (source_id,))
-            self._cleanup_local_graph_orphans(conn, source_id)
-        return {
-            "source_id": source_id,
-            "root_path": source["root_path"],
-            "removed_graph_nodes": len(graph_node_ids),
-        }
-
-    def _extract_local_file_text(
-        self, path: Path, category: str, *, include_ocr: bool
-    ) -> Tuple[str, Dict[str, Any]]:
-        ext = path.suffix.lower()
-        meta: Dict[str, Any] = {"parser": _parser_type_for_category(category, ext)}
-        text = ""
-        if category in {"text", "code"} or ext == ".csv":
-            text = path.read_text(encoding="utf-8", errors="replace")
-        elif ext == ".pdf":
-            import pdfplumber
-
-            with pdfplumber.open(str(path)) as pdf:
-                meta["pages"] = len(pdf.pages)
-                text = "\n\n".join((page.extract_text() or "") for page in pdf.pages)
-        elif ext == ".docx":
-            from docx import Document
-
-            doc = Document(str(path))
-            paragraphs = [p.text for p in doc.paragraphs if p.text.strip()]
-            table_lines = []
-            for table in doc.tables:
-                for row in table.rows:
-                    cells = [_clean_text(cell.text) for cell in row.cells]
-                    if any(cells):
-                        table_lines.append("\t".join(cells))
-            meta["paragraphs"] = len(paragraphs)
-            meta["tables"] = len(doc.tables)
-            meta["table_rows"] = len(table_lines)
-            text = "\n\n".join([*paragraphs, *table_lines])
-        elif ext == ".xlsx":
-            from openpyxl import load_workbook
-
-            wb = load_workbook(str(path), read_only=True, data_only=True)
-            rows_all = []
-            non_empty_rows = 0
-            non_empty_cells = 0
-            char_count = 0
-            for ws in wb.worksheets:
-                sheet_rows = []
-                for row in ws.iter_rows(values_only=True):
-                    cells = [
-                        str(cell).strip() if cell is not None else "" for cell in row
-                    ]
-                    if not any(cells):
-                        continue
-                    line = "\t".join(cells)
-                    non_empty_rows += 1
-                    non_empty_cells += sum(1 for cell in cells if cell)
-                    sheet_rows.append(line)
-                    char_count += len(line) + 1
-                    if char_count > 200_000:
-                        break
-                if sheet_rows:
-                    rows_all.append(f"[Sheet: {ws.title}]")
-                    rows_all.extend(sheet_rows)
-                if char_count > 200_000:
-                    break
-            meta["sheets"] = len(wb.worksheets)
-            meta["rows"] = non_empty_rows
-            meta["cells"] = non_empty_cells
-            text = "\n".join(rows_all)
-        elif ext == ".pptx":
-            from pptx import Presentation
-
-            prs = Presentation(str(path))
-            slides_text = []
-            for index, slide in enumerate(prs.slides, 1):
-                parts = []
-                for shape in slide.shapes:
-                    if getattr(shape, "has_text_frame", False):
-                        slide_text = shape.text_frame.text.strip()
-                        if slide_text:
-                            parts.append(slide_text)
-                if parts:
-                    slides_text.append(f"[Slide {index}]\n" + "\n".join(parts))
-            meta["slides"] = len(prs.slides)
-            meta["text_slides"] = len(slides_text)
-            text = "\n\n".join(slides_text)
-        elif category == "image":
-            from PIL import Image
-
-            with Image.open(str(path)) as image:
-                meta.update(
-                    {
-                        "width": image.width,
-                        "height": image.height,
-                        "format": image.format,
-                        "mode": image.mode,
-                        "ocr_enabled": bool(include_ocr),
-                    }
-                )
-                if include_ocr:
-                    try:
-                        import pytesseract
-
-                        text = pytesseract.image_to_string(image)
-                        meta["ocr_chars"] = len(text)
-                    except (
-                        Exception
-                    ) as exc:  # pragma: no cover - depends on local OCR runtime
-                        meta["ocr_error"] = str(exc)
-                        text = ""
-        return text[:200_000], meta
-
-    def _ensure_local_hierarchy(
-        self,
-        conn: sqlite3.Connection,
-        *,
-        source_id: str,
-        root: Path,
-        file_path: Path,
-        os_type: str,
-        drive_id: str,
-    ) -> str:
-        computer_label = platform.node() or "내 컴퓨터"
-        computer_id = f"computer:{_slug(computer_label)}"
-        drive_node_id = f"drive:{_sha256_text(f'{os_type}:{drive_id}')[:24]}"
-        root_folder_id = f"folder:{_sha256_text(f'{source_id}:root')[:24]}"
-        self._upsert_node(
-            conn, computer_id, "Computer", computer_label, metadata={"os_type": os_type}
-        )
-        self._upsert_node(
-            conn,
-            drive_node_id,
-            "Drive",
-            drive_id,
-            metadata={"os_type": os_type, "drive_id": drive_id},
-        )
-        self._upsert_edge(
-            conn,
-            computer_id,
-            drive_node_id,
-            "포함함",
-            metadata={"source": "local_scan"},
-        )
-        self._upsert_node(
-            conn,
-            root_folder_id,
-            "Folder",
-            root.name or str(root),
-            summary=str(root),
-            metadata={"source_id": source_id, "path": str(root), "root": True},
-        )
-        self._upsert_edge(
-            conn,
-            drive_node_id,
-            root_folder_id,
-            "포함함",
-            metadata={"source": "local_scan"},
-        )
-
-        try:
-            relative_parent = file_path.parent.relative_to(root)
-        except ValueError:
-            relative_parent = Path()
-        parent_id = root_folder_id
-        current_path = root
-        for part in relative_parent.parts:
-            current_path = current_path / part
-            folder_id = (
-                f"folder:{_sha256_text(f'{source_id}:{current_path.as_posix()}')[:24]}"
-            )
-            self._upsert_node(
-                conn,
-                folder_id,
-                "Folder",
-                part,
-                summary=str(current_path),
-                metadata={
-                    "source_id": source_id,
-                    "path": str(current_path),
-                    "root": False,
-                },
-            )
-            self._upsert_edge(
-                conn, parent_id, folder_id, "포함함", metadata={"source": "local_scan"}
-            )
-            parent_id = folder_id
-        return parent_id
-
-    def _upsert_local_file_index(
-        self,
-        conn: sqlite3.Connection,
-        *,
-        source_id: str,
-        root: Path,
-        file_path: Path,
-        stat: Optional[os.stat_result],
-        os_type: str,
-        drive_id: str,
-        status: str,
-        parser_type: str,
-        sha256: Optional[str] = None,
-        graph_node_id: Optional[str] = None,
-        error_message: Optional[str] = None,
-        metadata: Optional[Dict[str, Any]] = None,
-    ) -> str:
-        try:
-            relative_path = file_path.relative_to(root).as_posix()
-        except ValueError:
-            relative_path = file_path.name
-        index_id = f"local-index:{_sha256_text(f'{source_id}:{relative_path}')[:24]}"
-        now = _now()
-        size = stat.st_size if stat else None
-        modified_at = _safe_iso_from_stat_mtime(stat.st_mtime) if stat else ""
-        conn.execute(
-            """
-                INSERT INTO local_file_index(
-                  id, source_id, os_type, drive_id, root_path, file_path, relative_path,
-                  file_name, extension, size_bytes, modified_at, sha256, last_scanned_at,
-                  last_indexed_at, parser_type, status, error_message, graph_node_id,
-                  deleted, metadata_json
-                )
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                ON CONFLICT(source_id, relative_path) DO UPDATE SET
-                  os_type=excluded.os_type,
-                  drive_id=excluded.drive_id,
-                  root_path=excluded.root_path,
-                  file_path=excluded.file_path,
-                  file_name=excluded.file_name,
-                  extension=excluded.extension,
-                  size_bytes=excluded.size_bytes,
-                  modified_at=excluded.modified_at,
-                  sha256=excluded.sha256,
-                  last_scanned_at=excluded.last_scanned_at,
-                  last_indexed_at=excluded.last_indexed_at,
-                  parser_type=excluded.parser_type,
-                  status=excluded.status,
-                  error_message=excluded.error_message,
-                  graph_node_id=excluded.graph_node_id,
-                  deleted=excluded.deleted,
-                  metadata_json=excluded.metadata_json
-                """,
-            (
-                index_id,
-                source_id,
-                os_type,
-                drive_id,
-                str(root),
-                str(file_path),
-                relative_path,
-                file_path.name,
-                file_path.suffix.lower(),
-                size,
-                modified_at,
-                sha256,
-                now,
-                now if status == "indexed" else None,
-                parser_type,
-                status,
-                error_message,
-                graph_node_id,
-                0 if status != "deleted" else 1,
-                _json(metadata),
-            ),
-        )
-        return index_id
-
-    def _upsert_local_file_node(
-        self,
-        conn: sqlite3.Connection,
-        *,
-        source_id: str,
-        root: Path,
-        file_path: Path,
-        stat: os.stat_result,
-        os_type: str,
-        drive_id: str,
-        sha256: str,
-        category: str,
-        parser_type: str,
-        text: str,
-        parser_meta: Dict[str, Any],
-    ) -> str:
-        text = _clean_text(text)
-        if not text:
-            raise ValueError("텍스트 추출 결과가 비어 있습니다.")
-        try:
-            relative_path = file_path.relative_to(root).as_posix()
-        except ValueError:
-            relative_path = file_path.name
-        file_node_id = f"local-file:{_sha256_text(f'{source_id}:{relative_path}')[:24]}"
-        parent_folder_id = self._ensure_local_hierarchy(
-            conn,
-            source_id=source_id,
-            root=root,
-            file_path=file_path,
-            os_type=os_type,
-            drive_id=drive_id,
-        )
-        child_rows = conn.execute(
-            """
-                SELECT e.to_node AS id
-                FROM edges e
-                JOIN nodes n ON n.id=e.to_node
-                WHERE e.from_node=? AND n.type IN ('Chunk', 'ImageText', 'Section')
-                """,
-            (file_node_id,),
-        ).fetchall()
-        child_ids = [row["id"] for row in child_rows]
-        conn.execute("DELETE FROM chunks WHERE source_node=?", (file_node_id,))
-        if child_ids:
-            placeholders = ",".join("?" * len(child_ids))
-            conn.execute(f"DELETE FROM nodes WHERE id IN ({placeholders})", child_ids)
-            self._v2_delete_nodes(conn, child_ids)
-        conn.execute("DELETE FROM edges WHERE from_node=?", (file_node_id,))
-        self._v2_delete_edges_from(conn, file_node_id)
-
-        metadata = {
-            "source": "local_folder",
-            "source_id": source_id,
-            "root_path": str(root),
-            "file_path": str(file_path),
-            "relative_path": relative_path,
-            "filename": file_path.name,
-            "ext": file_path.suffix.lower(),
-            "category": category,
-            "parser_type": parser_type,
-            "bytes": stat.st_size,
-            "modified_at": _safe_iso_from_stat_mtime(stat.st_mtime),
-            "sha256": sha256,
-            "parser": parser_meta,
-        }
-        self._upsert_node(
-            conn,
-            file_node_id,
-            _node_type_for_category(category),
-            file_path.name,
-            summary=text[:700],
-            metadata=metadata,
-            raw=metadata,
-        )
-        self._upsert_edge(
-            conn,
-            parent_folder_id,
-            file_node_id,
-            "포함함",
-            weight=1.0,
-            metadata={"source": "local_scan"},
-        )
-
-        target_for_concepts = text
-        if category == "image" and text:
-            image_text_id = f"imagetext:{_sha256_text(f'{file_node_id}:ocr')[:24]}"
-            self._upsert_node(
-                conn,
-                image_text_id,
-                "ImageText",
-                f"{file_path.name} OCR",
-                summary=_clean_text(text)[:700],
-                metadata={
-                    "source_node": file_node_id,
-                    "source_id": source_id,
-                    "chars": len(text),
-                },
-            )
-            self._upsert_edge(
-                conn,
-                file_node_id,
-                image_text_id,
-                "포함함",
-                weight=0.8,
-                metadata={"source": "ocr"},
-            )
-
-        for index, chunk in enumerate(_chunks(text)):
-            chunk_id = f"chunk:{_sha256_text(f'{file_node_id}:{index}:{chunk}')[:24]}"
-            self._upsert_node(
-                conn,
-                chunk_id,
-                "Chunk",
-                f"{file_path.name} chunk {index + 1}",
-                summary=chunk[:500],
-                metadata={
-                    "index": index,
-                    "source_node": file_node_id,
-                    "source_id": source_id,
-                },
-            )
-            self._upsert_chunk(
-                conn,
-                chunk_id=chunk_id,
-                source_node=file_node_id,
-                text=chunk,
-                metadata={
-                    "index": index,
-                    "source_node": file_node_id,
-                    "source_id": source_id,
-                },
-            )
-            self._upsert_edge(
-                conn,
-                file_node_id,
-                chunk_id,
-                "포함함",
-                weight=0.7,
-                metadata={"source": "local_scan"},
-            )
-
-        concepts = _extract_concepts(target_for_concepts, limit=18)
-        concept_ids: Dict[str, str] = {}
-        for concept in concepts:
-            node_t = _classify_node_type(concept, target_for_concepts)
-            concept_id = f"{node_t.lower()}:{_slug(concept)}"
-            concept_ids[concept.lower()] = concept_id
-            self._upsert_node(
-                conn,
-                concept_id,
-                node_t,
-                concept,
-                metadata={
-                    "auto_extracted": True,
-                    "source": "local_folder",
-                    "source_id": source_id,
-                },
-            )
-            self._upsert_edge(
-                conn,
-                file_node_id,
-                concept_id,
-                "언급함",
-                weight=0.75,
-                metadata={"source": "local_scan"},
-            )
-
-        for triple in _extract_triples(target_for_concepts, concepts, limit=20):
-            subj_id = concept_ids.get(triple["subject"].lower())
-            obj_id = concept_ids.get(triple["object"].lower())
-            if subj_id and obj_id and subj_id != obj_id:
-                self._upsert_edge(
-                    conn,
-                    subj_id,
-                    obj_id,
-                    triple["relation"],
-                    weight=0.9,
-                    metadata={
-                        "context": triple.get("context", "")[:240],
-                        "source_id": source_id,
-                    },
-                )
-
-        for item in _semantic_items(target_for_concepts):
-            sem_type = item["type"]
-            sem_title = item["title"]
-            sem_id = f"{sem_type.lower()}:{_sha256_text(f'{file_node_id}:{sem_type}:{sem_title}')[:24]}"
-            self._upsert_node(
-                conn,
-                sem_id,
-                sem_type,
-                sem_title,
-                summary=item["summary"],
-                metadata={
-                    "auto_extracted": True,
-                    "source_node": file_node_id,
-                    "filename": file_path.name,
-                },
-                raw=item,
-            )
-            self._upsert_edge(conn, file_node_id, sem_id, "포함함", weight=0.9)
-
-        return file_node_id
-
-    def _delete_local_file_graph(
-        self, conn: sqlite3.Connection, file_node_id: Optional[str]
-    ) -> None:
-        if not file_node_id:
-            return
-
-        file_row = conn.execute(
-            "SELECT metadata_json FROM nodes WHERE id=?",
-            (file_node_id,),
-        ).fetchone()
-        source_id = None
-        if file_row:
-            source_id = _safe_loads(file_row["metadata_json"]).get("source_id")
-
-        linked_rows = conn.execute(
-            """
-                SELECT n.id, n.type, n.metadata_json
-                FROM edges e
-                JOIN nodes n ON n.id=e.to_node
-                WHERE e.from_node=?
-                """,
-            (file_node_id,),
-        ).fetchall()
-        owned_ids: set = set()
-        auto_candidate_ids: set = set()
-        for row in linked_rows:
-            metadata = _safe_loads(row["metadata_json"])
-            if (
-                row["type"] in {"Chunk", "ImageText", "Section"}
-                or metadata.get("source_node") == file_node_id
-            ):
-                owned_ids.add(row["id"])
-            elif (
-                metadata.get("auto_extracted")
-                and metadata.get("source") == "local_folder"
-            ):
-                auto_candidate_ids.add(row["id"])
-
-        conn.execute("DELETE FROM chunks WHERE source_node=?", (file_node_id,))
-        conn.execute(
-            "DELETE FROM edges WHERE from_node=? OR to_node=?",
-            (file_node_id, file_node_id),
-        )
-        conn.execute("DELETE FROM nodes WHERE id=?", (file_node_id,))
-        self._v2_delete_nodes(conn, [file_node_id])
-
-        def delete_nodes(node_ids: set) -> None:
-            if not node_ids:
-                return
-            placeholders = ",".join("?" * len(node_ids))
-            params = list(node_ids)
-            conn.execute(
-                f"DELETE FROM chunks WHERE source_node IN ({placeholders})", params
-            )
-            conn.execute(
-                f"DELETE FROM edges WHERE from_node IN ({placeholders}) OR to_node IN ({placeholders})",
-                params * 2,
-            )
-            conn.execute(f"DELETE FROM nodes WHERE id IN ({placeholders})", params)
-            self._v2_delete_nodes(conn, params)
-
-        delete_nodes(owned_ids)
-
-        removable_auto_ids: set = set()
-        for node_id in auto_candidate_ids:
-            remaining_edges = conn.execute(
-                "SELECT from_node, to_node FROM edges WHERE from_node=? OR to_node=?",
-                (node_id, node_id),
-            ).fetchall()
-            if all(
-                (
-                    row["from_node"] in auto_candidate_ids
-                    and row["to_node"] in auto_candidate_ids
-                )
-                for row in remaining_edges
-            ):
-                removable_auto_ids.add(node_id)
-        delete_nodes(removable_auto_ids)
-        if source_id:
-            self._cleanup_local_graph_orphans(conn, str(source_id))
-
-    def _cleanup_local_graph_orphans(
-        self, conn: sqlite3.Connection, source_id: str
-    ) -> None:
-        while True:
-            folder_rows = conn.execute(
-                "SELECT id, metadata_json FROM nodes WHERE type='Folder'"
-            ).fetchall()
-            leaf_ids = []
-            for row in folder_rows:
-                metadata = _safe_loads(row["metadata_json"])
-                if metadata.get("source_id") != source_id:
-                    continue
-                has_children = conn.execute(
-                    "SELECT 1 FROM edges WHERE from_node=? LIMIT 1",
-                    (row["id"],),
-                ).fetchone()
-                if not has_children:
-                    leaf_ids.append(row["id"])
-            if not leaf_ids:
-                break
-            placeholders = ",".join("?" * len(leaf_ids))
-            conn.execute(
-                f"DELETE FROM edges WHERE from_node IN ({placeholders}) OR to_node IN ({placeholders})",
-                leaf_ids * 2,
-            )
-            conn.execute(f"DELETE FROM nodes WHERE id IN ({placeholders})", leaf_ids)
-            self._v2_delete_nodes(conn, leaf_ids)
-
-        for node_type in ("Drive", "Computer"):
-            rows = conn.execute(
-                "SELECT id FROM nodes WHERE type=?", (node_type,)
-            ).fetchall()
-            removable = []
-            for row in rows:
-                has_children = conn.execute(
-                    "SELECT 1 FROM edges WHERE from_node=? LIMIT 1",
-                    (row["id"],),
-                ).fetchone()
-                if not has_children:
-                    removable.append(row["id"])
-            if removable:
-                placeholders = ",".join("?" * len(removable))
-                conn.execute(
-                    f"DELETE FROM edges WHERE from_node IN ({placeholders}) OR to_node IN ({placeholders})",
-                    removable * 2,
-                )
-                conn.execute(
-                    f"DELETE FROM nodes WHERE id IN ({placeholders})", removable
-                )
-                self._v2_delete_nodes(conn, removable)
-
-    def _local_file_index_has_extracted_text(self, row: sqlite3.Row) -> bool:
-        metadata = _safe_loads(row["metadata_json"])
-        parser = metadata.get("parser") if isinstance(metadata, dict) else {}
-        if not isinstance(parser, dict):
-            return False
-        try:
-            return int(parser.get("extracted_chars") or 0) > 0
-        except (TypeError, ValueError):
-            return False
-
-    def index_local_folder(
-        self,
-        path: Path,
-        *,
-        include_ocr: bool = False,
-        watch_enabled: bool = False,
-        user_email: Optional[str] = None,
-        consent: Optional[Dict[str, Any]] = None,
-        max_files: int = 5_000,
-    ) -> Dict[str, Any]:
-        """Read approved files from a local folder and connect them to Graph RAG."""
-        root = Path(path).expanduser().resolve()
-        if not root.exists():
-            raise ValueError(f"경로가 존재하지 않습니다: {path}")
-        if not root.is_dir():
-            raise ValueError(f"폴더가 아닙니다: {path}")
-
-        os_type = _current_os_type()
-        drive_id = _drive_id_for_path(root)
-        source_id = f"source:{_path_fingerprint(root)}"
-        now = _now()
-        max_files = max(1, min(int(max_files or 5_000), 50_000))
-        consent_payload = {
-            "approved_at": now,
-            "approved_by": user_email,
-            "knowledge_source": True,
-            "include_ocr": bool(include_ocr),
-            "watch_enabled": bool(watch_enabled),
-            "sensitive_files_default_excluded": True,
-            **(consent or {}),
-        }
-        counts: Counter = Counter()
-        seen_relative_paths: set = set()
-        indexed_nodes: List[str] = []
-        errors: List[Dict[str, str]] = []
-        limit_reached = False
-
-        with self._connect() as conn:
-            conn.execute(
-                """
-                    INSERT INTO knowledge_sources(
-                      id, root_path, os_type, drive_id, label, status, include_ocr,
-                      watch_enabled, consent_json, created_at, updated_at, last_scanned_at
-                    )
-                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-                    ON CONFLICT(id) DO UPDATE SET
-                      root_path=excluded.root_path,
-                      os_type=excluded.os_type,
-                      drive_id=excluded.drive_id,
-                      label=excluded.label,
-                      status=excluded.status,
-                      include_ocr=excluded.include_ocr,
-                      watch_enabled=excluded.watch_enabled,
-                      consent_json=excluded.consent_json,
-                      updated_at=excluded.updated_at,
-                      last_scanned_at=excluded.last_scanned_at
-                    """,
-                (
-                    source_id,
-                    str(root),
-                    os_type,
-                    drive_id,
-                    root.name or str(root),
-                    "scanning",
-                    1 if include_ocr else 0,
-                    1 if watch_enabled else 0,
-                    _json(consent_payload),
-                    now,
-                    now,
-                    now,
-                ),
-            )
-
-            for entry in self._iter_local_scan_entries(root, max_files=max_files):
-                kind = entry["kind"]
-                file_path = entry["path"]
-                if kind == "limit_reached":
-                    counts["limit_reached"] += 1
-                    limit_reached = True
-                    break
-                if kind in {"excluded_dir", "excluded"}:
-                    counts["excluded"] += 1
-                    continue
-                if kind in {"inaccessible_dir", "inaccessible_file"}:
-                    counts["failed"] += 1
-                    errors.append(
-                        {
-                            "path": str(file_path),
-                            "error": entry.get("reason", "inaccessible"),
-                        }
-                    )
-                    continue
-                if kind != "file":
-                    continue
-
-                stat = entry["stat"]
-                try:
-                    relative_path = file_path.relative_to(root).as_posix()
-                except ValueError:
-                    relative_path = file_path.name
-                seen_relative_paths.add(relative_path)
-                modified_at = _safe_iso_from_stat_mtime(stat.st_mtime)
-                existing = conn.execute(
-                    """
-                        SELECT size_bytes, modified_at, sha256, graph_node_id, status, metadata_json
-                        FROM local_file_index
-                        WHERE source_id=? AND relative_path=?
-                        """,
-                    (source_id, relative_path),
-                ).fetchone()
-                decision = self._local_file_decision(file_path, root, stat)
-                parser_type = decision["parser_type"]
-                if not decision["indexable"]:
-                    counts[decision["status"]] += 1
-                    if existing and existing["graph_node_id"]:
-                        self._delete_local_file_graph(conn, existing["graph_node_id"])
-                    self._upsert_local_file_index(
-                        conn,
-                        source_id=source_id,
-                        root=root,
-                        file_path=file_path,
-                        stat=stat,
-                        os_type=os_type,
-                        drive_id=drive_id,
-                        status=decision["status"],
-                        parser_type=parser_type,
-                        metadata={
-                            "reason": decision["reason"],
-                            "category": decision["category"],
-                        },
-                    )
-                    continue
-
-                if (
-                    existing
-                    and existing["status"] == "indexed"
-                    and existing["graph_node_id"]
-                    and self._local_file_index_has_extracted_text(existing)
-                    and existing["size_bytes"] == stat.st_size
-                    and existing["modified_at"] == modified_at
-                ):
-                    counts["skipped_unchanged"] += 1
-                    self._upsert_local_file_index(
-                        conn,
-                        source_id=source_id,
-                        root=root,
-                        file_path=file_path,
-                        stat=stat,
-                        os_type=os_type,
-                        drive_id=drive_id,
-                        status="indexed",
-                        parser_type=parser_type,
-                        sha256=existing["sha256"],
-                        graph_node_id=existing["graph_node_id"],
-                        metadata={
-                            **_safe_loads(existing["metadata_json"]),
-                            "category": decision["category"],
-                            "unchanged": True,
-                        },
-                    )
-                    continue
-
-                try:
-                    data = file_path.read_bytes()
-                    digest = _sha256_bytes(data)
-                except Exception as exc:
-                    counts["failed"] += 1
-                    errors.append({"path": str(file_path), "error": str(exc)})
-                    if existing and existing["graph_node_id"]:
-                        self._delete_local_file_graph(conn, existing["graph_node_id"])
-                    self._upsert_local_file_index(
-                        conn,
-                        source_id=source_id,
-                        root=root,
-                        file_path=file_path,
-                        stat=stat,
-                        os_type=os_type,
-                        drive_id=drive_id,
-                        status="failed",
-                        parser_type=parser_type,
-                        error_message=str(exc),
-                        metadata={"category": decision["category"]},
-                    )
-                    continue
-
-                if (
-                    existing
-                    and existing["sha256"] == digest
-                    and existing["graph_node_id"]
-                    and self._local_file_index_has_extracted_text(existing)
-                ):
-                    counts["skipped_unchanged"] += 1
-                    self._upsert_local_file_index(
-                        conn,
-                        source_id=source_id,
-                        root=root,
-                        file_path=file_path,
-                        stat=stat,
-                        os_type=os_type,
-                        drive_id=drive_id,
-                        status="indexed",
-                        parser_type=parser_type,
-                        sha256=digest,
-                        graph_node_id=existing["graph_node_id"],
-                        metadata={
-                            **_safe_loads(existing["metadata_json"]),
-                            "category": decision["category"],
-                            "sha256_unchanged": True,
-                        },
-                    )
-                    continue
-
-                try:
-                    text, parser_meta = self._extract_local_file_text(
-                        file_path,
-                        decision["category"],
-                        include_ocr=include_ocr,
-                    )
-                    text = _clean_text(text)
-                    parser_meta = {**parser_meta, "extracted_chars": len(text)}
-                    if not text:
-                        counts["skipped_empty_text"] += 1
-                        if existing and existing["graph_node_id"]:
-                            self._delete_local_file_graph(
-                                conn, existing["graph_node_id"]
-                            )
-                        self._upsert_local_file_index(
-                            conn,
-                            source_id=source_id,
-                            root=root,
-                            file_path=file_path,
-                            stat=stat,
-                            os_type=os_type,
-                            drive_id=drive_id,
-                            status="skipped_empty_text",
-                            parser_type=parser_type,
-                            sha256=digest,
-                            error_message="텍스트 추출 결과가 비어 있습니다.",
-                            metadata={
-                                "category": decision["category"],
-                                "parser": parser_meta,
-                            },
-                        )
-                        continue
-                    graph_node_id = self._upsert_local_file_node(
-                        conn,
-                        source_id=source_id,
-                        root=root,
-                        file_path=file_path,
-                        stat=stat,
-                        os_type=os_type,
-                        drive_id=drive_id,
-                        sha256=digest,
-                        category=decision["category"],
-                        parser_type=parser_type,
-                        text=text,
-                        parser_meta=parser_meta,
-                    )
-                    self._upsert_local_file_index(
-                        conn,
-                        source_id=source_id,
-                        root=root,
-                        file_path=file_path,
-                        stat=stat,
-                        os_type=os_type,
-                        drive_id=drive_id,
-                        status="indexed",
-                        parser_type=parser_type,
-                        sha256=digest,
-                        graph_node_id=graph_node_id,
-                        metadata={
-                            "category": decision["category"],
-                            "parser": parser_meta,
-                        },
-                    )
-                    counts["indexed"] += 1
-                    indexed_nodes.append(graph_node_id)
-                except Exception as exc:
-                    counts["failed"] += 1
-                    errors.append({"path": str(file_path), "error": str(exc)})
-                    if existing and existing["graph_node_id"]:
-                        self._delete_local_file_graph(conn, existing["graph_node_id"])
-                    self._upsert_local_file_index(
-                        conn,
-                        source_id=source_id,
-                        root=root,
-                        file_path=file_path,
-                        stat=stat,
-                        os_type=os_type,
-                        drive_id=drive_id,
-                        status="failed",
-                        parser_type=parser_type,
-                        sha256=digest,
-                        error_message=str(exc),
-                        metadata={"category": decision["category"]},
-                    )
-
-            if not limit_reached:
-                existing_rows = {
-                    row["relative_path"]: row["graph_node_id"]
-                    for row in conn.execute(
-                        "SELECT relative_path, graph_node_id FROM local_file_index WHERE source_id=?",
-                        (source_id,),
-                    )
-                }
-                deleted_paths = set(existing_rows) - seen_relative_paths
-                for relative_path in deleted_paths:
-                    self._delete_local_file_graph(
-                        conn, existing_rows.get(relative_path)
-                    )
-                    conn.execute(
-                        """
-                            UPDATE local_file_index
-                            SET status='deleted', deleted=1, last_scanned_at=?, error_message=NULL, graph_node_id=NULL
-                            WHERE source_id=? AND relative_path=?
-                            """,
-                        (_now(), source_id, relative_path),
-                    )
-                counts["deleted"] = len(deleted_paths)
-            conn.execute(
-                """
-                    UPDATE knowledge_sources
-                    SET status='active', updated_at=?, last_scanned_at=?
-                    WHERE id=?
-                    """,
-                (_now(), _now(), source_id),
-            )
-
-        return {
-            "status": "ok",
-            "source": {
-                "id": source_id,
-                "root_path": str(root),
-                "os_type": os_type,
-                "drive_id": drive_id,
-                "include_ocr": bool(include_ocr),
-                "watch_enabled": bool(watch_enabled),
-            },
-            "counts": dict(counts),
-            "indexed_nodes": indexed_nodes[:100],
-            "errors": errors[:50],
-            "notice": "Lattice AI는 사용자가 선택한 폴더만 AI 지식으로 변환합니다.",
-        }
+warnings.warn(
+    "latticeai.brain.discovery is deprecated; import lattice_brain.graph.discovery instead",
+    DeprecationWarning,
+    stacklevel=2,
+)
+sys.modules[__name__] = _impl