kgmodule-utils 0.2.0__py3-none-any.whl

kg_utils/__init__.py

@@ -0,0 +1,10 @@
+"""kg_utils — Shared types, snapshots, and embedding protocol for the KGModule SDK.
+
+Sub-packages:
+    kg_utils.types      — NodeSpec, EdgeSpec, KGExtractor, KGModule, etc.
+    kg_utils.snapshots  — Snapshot, SnapshotManager, SnapshotManifest, etc.
+    kg_utils.embed      — Embedder protocol, DEFAULT_MODEL, KNOWN_MODELS,
+                          kg_model_cache_dir(), resolve_model_path().
+"""
+
+__version__ = "0.1.0"

kg_utils/embed.py

@@ -0,0 +1,131 @@
+"""
+kg_utils.embed — Shared embedding protocol and model-cache convention.
+
+Zero external dependencies (stdlib only).  Concrete implementations
+(SentenceTransformerEmbedder, LlamaCppEmbedder) live in each KG module and in
+kgrag; this module provides only the shared contract they all implement.
+
+Contents
+--------
+Embedder
+    Structural protocol: any object with ``embed_query(text) -> list[float]``
+    satisfies it.  KG modules, kgrag adapters, and tests can type-hint against
+    this without coupling to any specific implementation.
+
+DEFAULT_MODEL
+    Canonical default embedding model for the KGModule stack.
+    ``BAAI/bge-small-en-v1.5`` (384-dim, ~24 MB, no licence restrictions).
+
+KNOWN_MODELS
+    Short alias → HuggingFace repo ID mapping shared by all modules.
+    Lets users write ``"bge-small"`` instead of ``"BAAI/bge-small-en-v1.5"``.
+
+kg_model_cache_dir()
+    Return the system-wide model cache root (``~/.kgrag/models/`` by default).
+    Override with the ``KGRAG_MODEL_DIR`` environment variable.  All KG modules
+    should resolve their model paths through this function so that a single
+    ``KGRAG_MODEL_DIR`` setting redirects every module at once.
+
+    Local fallback convention for standalone use::
+
+        path = kg_model_cache_dir() / model_name.replace("/", "--")
+
+Author: Eric G. Suchanek, PhD
+License: Elastic 2.0
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+
+# ---------------------------------------------------------------------------
+# Shared protocol
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class Embedder(Protocol):
+    """Minimal embedding protocol for the KGModule stack.
+
+    Any object with an ``embed_query`` method satisfies this protocol and can
+    be injected into any KGModule-based KG backend (DocKG, MemoryKG, etc.).
+
+    :method embed_query: Embed a single query string into a float vector.
+    """
+
+    def embed_query(self, text: str) -> list[float]:
+        """Embed a single query string into a dense float vector.
+
+        :param text: The query string to embed.
+        :return: Dense float32 vector as a plain Python list.
+        """
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Shared constants
+# ---------------------------------------------------------------------------
+
+DEFAULT_MODEL: str = "BAAI/bge-small-en-v1.5"
+"""Canonical default embedding model for the KGModule stack (384-dim)."""
+
+KNOWN_MODELS: dict[str, str] = {
+    "default": "BAAI/bge-small-en-v1.5",
+    "bge-small": "BAAI/bge-small-en-v1.5",
+    "bge-small-en-v1.5": "BAAI/bge-small-en-v1.5",
+    "bge-large": "BAAI/bge-large-en-v1.5",
+    "bge-large-en-v1.5": "BAAI/bge-large-en-v1.5",
+    "all-MiniLM-L6-v2": "sentence-transformers/all-MiniLM-L6-v2",
+    "all-mpnet-base-v2": "sentence-transformers/all-mpnet-base-v2",
+    "nomic": "nomic-ai/nomic-embed-text-v1.5",
+    "nomic-v1.5": "nomic-ai/nomic-embed-text-v1.5",
+}
+"""Short alias → HuggingFace repo ID.  Shared by all KG modules and kgrag."""
+
+
+# ---------------------------------------------------------------------------
+# Shared cache path convention
+# ---------------------------------------------------------------------------
+
+
+def kg_model_cache_dir() -> Path:
+    """Return the system-wide embedding model cache root.
+
+    Default: ``~/.kgrag/models/``
+    Override: set ``KGRAG_MODEL_DIR`` environment variable.
+
+    All KG modules should resolve model paths through this function so that a
+    single env-var change redirects every module's cache at once.
+
+    :return: Absolute :class:`~pathlib.Path` to the model cache directory.
+    """
+    env = os.environ.get("KGRAG_MODEL_DIR")
+    if env:
+        return Path(env).resolve()
+    return Path.home() / ".kgrag" / "models"
+
+
+def resolve_model_path(model_name: str, local_fallback: Path | None = None) -> Path:
+    """Return the local cache path for *model_name*.
+
+    Checks the system-wide cache (``kg_model_cache_dir()``) first.  If
+    *local_fallback* is provided and the system cache env var is not set, uses
+    that instead — allowing standalone modules to keep their own local cache
+    while respecting a global override.
+
+    The model name is stored as ``<org>/<model>`` directory structure (matching
+    HuggingFace layout), e.g. ``BAAI/bge-small-en-v1.5`` →
+    ``~/.kgrag/models/BAAI/bge-small-en-v1.5/``.
+
+    :param model_name: HuggingFace model identifier or known alias.
+    :param local_fallback: Per-module fallback directory (used when
+        ``KGRAG_MODEL_DIR`` is not set).
+    :return: Absolute :class:`~pathlib.Path` to the model directory.
+    """
+    resolved = KNOWN_MODELS.get(model_name, model_name)
+    if os.environ.get("KGRAG_MODEL_DIR") or local_fallback is None:
+        return kg_model_cache_dir() / resolved.replace("/", os.sep)
+    return local_fallback / resolved.replace("/", "--")

kg_utils/snapshots/__init__.py

@@ -0,0 +1,16 @@
+"""kg_utils.snapshots — Shared snapshot infrastructure for KG modules.
+
+Provides the canonical data models and manager for capturing, storing, and
+comparing temporal metric snapshots. Individual KG backends (pycode_kg, doc_kg,
+ftree_kg, etc.) import from here instead of maintaining their own copies.
+"""
+
+from kg_utils.snapshots.models import PruneResult, Snapshot, SnapshotManifest
+from kg_utils.snapshots.manager import SnapshotManager
+
+__all__ = [
+    "PruneResult",
+    "Snapshot",
+    "SnapshotManifest",
+    "SnapshotManager",
+]

kg_utils/snapshots/manager.py

@@ -0,0 +1,497 @@
+"""kg_utils/snapshots/manager.py — Snapshot capture, persistence, and comparison.
+
+Usage
+-----
+>>> from kg_utils.snapshots import SnapshotManager
+>>> mgr = SnapshotManager(".codekg/snapshots", package_name="code-kg")
+>>> snapshot = mgr.capture(graph_stats_dict=kg.store.stats())
+>>> mgr.save_snapshot(snapshot)
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import importlib.metadata
+import json
+import subprocess
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from kg_utils.snapshots.models import PruneResult, Snapshot, SnapshotManifest
+
+
+class SnapshotManager:
+    """Manages snapshot capture, persistence, retrieval, and comparison.
+
+    This is the single shared implementation. Domain-specific KG libraries
+    subclass this to override :meth:`_compute_delta` or
+    :meth:`_collect_extra_metrics` when they need domain-specific delta fields
+    or automatic metric collection from SQLite.
+
+    :param snapshots_dir: Directory for snapshot JSON files and manifest.
+    :param package_name: Package name for auto-detecting version
+        (e.g. ``"code-kg"``, ``"doc-kg"``). Defaults to ``"kg-utils"``.
+    :param db_path: Optional SQLite database path for collecting per-module or
+        per-directory node counts via :meth:`_collect_breakdown_counts`.
+    """
+
+    def __init__(
+        self,
+        snapshots_dir: Path | str,
+        *,
+        package_name: str = "kg-utils",
+        db_path: Path | str | None = None,
+    ) -> None:
+        self.snapshots_dir = Path(snapshots_dir)
+        self.snapshots_dir.mkdir(parents=True, exist_ok=True)
+        self.manifest_path = self.snapshots_dir / "manifest.json"
+        self.package_name = package_name
+        self.db_path = Path(db_path) if db_path else None
+
+    # ------------------------------------------------------------------
+    # Package version detection
+    # ------------------------------------------------------------------
+
+    def _package_version(self) -> str:
+        """Return the installed package version, or ``'unknown'``."""
+        try:
+            return importlib.metadata.version(self.package_name)
+        except importlib.metadata.PackageNotFoundError:
+            return "unknown"
+
+    # ------------------------------------------------------------------
+    # Capture & save
+    # ------------------------------------------------------------------
+
+    def capture(
+        self,
+        version: str | None = None,
+        branch: str | None = None,
+        graph_stats_dict: dict[str, Any] | None = None,
+        tree_hash: str = "",
+        hotspots: list[dict[str, Any]] | None = None,
+        issues: list[str] | None = None,
+        **extra_metrics: Any,
+    ) -> Snapshot:
+        """Capture a snapshot from current state.
+
+        ``graph_stats_dict`` is merged with ``extra_metrics`` to form the
+        snapshot's ``metrics`` dict. Pass domain-specific fields as keyword
+        arguments (e.g. ``coverage=0.85``, ``critical_issues=2``).
+
+        :param version: Version string; auto-detected from package if None.
+        :param branch: Git branch; auto-detected if None.
+        :param graph_stats_dict: Output from the KG's ``stats()`` method.
+        :param tree_hash: Git tree hash; auto-detected if not provided.
+        :param hotspots: Top hotspot entries.
+        :param issues: Issue description strings.
+        :param extra_metrics: Additional domain-specific metric fields.
+        :return: New :class:`Snapshot` instance (not yet persisted).
+        """
+        if not version:
+            version = self._package_version()
+        if branch is None:
+            branch = self._get_current_branch()
+        if not tree_hash:
+            tree_hash = self._get_current_tree_hash()
+
+        metrics: dict[str, Any] = dict(graph_stats_dict or {})
+        metrics.update(extra_metrics)
+
+        snapshot = Snapshot(
+            branch=branch,
+            timestamp=datetime.now(UTC).isoformat(),
+            version=version,
+            metrics=metrics,
+            hotspots=hotspots or [],
+            issues=issues or [],
+            tree_hash=tree_hash,
+        )
+
+        prev = self.get_previous(tree_hash)
+        if prev:
+            snapshot.vs_previous = self._compute_delta(snapshot, prev)
+
+        baseline = self.get_baseline()
+        if baseline:
+            snapshot.vs_baseline = self._compute_delta(snapshot, baseline)
+
+        return snapshot
+
+    def save_snapshot(self, snapshot: Snapshot, *, force: bool = False) -> Path | None:
+        """Persist a snapshot to disk and update the manifest.
+
+        Rejects snapshots with zero ``total_nodes`` to protect against
+        saving degenerate (unbuilt) state.
+
+        If ``version`` and ``metrics`` are unchanged from the latest snapshot,
+        the existing entry is refreshed in-place rather than creating a new
+        history entry. Pass ``force=True`` to always create a new entry.
+
+        :param snapshot: Snapshot to save.
+        :param force: If ``True``, always write a new history entry.
+        :return: Path to the saved JSON file, or ``None`` if no-op.
+        :raises ValueError: If ``total_nodes`` is 0.
+        """
+        m = snapshot.metrics
+        total_nodes = (
+            m.get("total_nodes", 0) if isinstance(m, dict) else getattr(m, "total_nodes", 0)
+        )
+        if total_nodes == 0:
+            raise ValueError(
+                "Refusing to save degenerate snapshot with 0 nodes. "
+                "Build the KG before capturing a snapshot."
+            )
+
+        manifest = self.load_manifest()
+
+        # Dedup: refresh latest entry if nothing meaningful changed.
+        if not force and manifest.snapshots:
+            latest_entry = max(manifest.snapshots, key=lambda x: x.get("timestamp", ""))
+            if snapshot.version == latest_entry.get("version", "") and not self._metrics_changed(
+                snapshot.metrics, latest_entry.get("metrics", {})
+            ):
+                old_key = latest_entry["key"]
+                old_file = self.snapshots_dir / latest_entry.get("file", f"{old_key}.json")
+
+                snapshot_file = self.snapshots_dir / f"{snapshot.key}.json"
+                snapshot_file.write_text(
+                    json.dumps(snapshot.to_dict(), indent=2) + "\n", encoding="utf-8"
+                )
+
+                if old_key != snapshot.key and old_file.exists():
+                    old_file.unlink()
+
+                latest_entry["key"] = snapshot.key
+                latest_entry["branch"] = snapshot.branch
+                latest_entry["timestamp"] = snapshot.timestamp
+                latest_entry["file"] = snapshot_file.name
+
+                manifest.last_update = datetime.now(UTC).isoformat()
+                self._save_manifest(manifest)
+                return snapshot_file
+
+        # Normal path: new or changed snapshot.
+        snapshot_file = self.snapshots_dir / f"{snapshot.key}.json"
+        snapshot_file.write_text(json.dumps(snapshot.to_dict(), indent=2) + "\n", encoding="utf-8")
+
+        existing_idx = next(
+            (i for i, s in enumerate(manifest.snapshots) if s.get("key") == snapshot.key),
+            None,
+        )
+
+        manifest_entry: dict[str, Any] = {
+            "key": snapshot.key,
+            "branch": snapshot.branch,
+            "timestamp": snapshot.timestamp,
+            "version": snapshot.version,
+            "file": snapshot_file.name,
+            "metrics": snapshot.metrics,
+            "deltas": {
+                "vs_previous": snapshot.vs_previous,
+                "vs_baseline": snapshot.vs_baseline,
+            },
+        }
+
+        if existing_idx is not None:
+            manifest.snapshots[existing_idx] = manifest_entry
+        else:
+            manifest.snapshots.append(manifest_entry)
+
+        manifest.last_update = datetime.now(UTC).isoformat()
+        self._save_manifest(manifest)
+        return snapshot_file
+
+    # ------------------------------------------------------------------
+    # Loading & listing
+    # ------------------------------------------------------------------
+
+    def load_manifest(self) -> SnapshotManifest:
+        """Load ``manifest.json``; return empty manifest if absent."""
+        if not self.manifest_path.exists():
+            return SnapshotManifest()
+        manifest = SnapshotManifest.from_dict(
+            json.loads(self.manifest_path.read_text(encoding="utf-8"))
+        )
+        # Normalise legacy 'tree_hash' -> 'key'
+        for entry in manifest.snapshots:
+            if "key" not in entry and "tree_hash" in entry:
+                entry["key"] = entry.pop("tree_hash")
+        return manifest
+
+    def _save_manifest(self, manifest: SnapshotManifest) -> None:
+        self.manifest_path.write_text(
+            json.dumps(manifest.to_dict(), indent=2) + "\n", encoding="utf-8"
+        )
+
+    def load_snapshot(self, key: str) -> Snapshot | None:
+        """Load a snapshot by key (tree hash) or ``'latest'``.
+
+        Missing ``vs_previous`` / ``vs_baseline`` deltas are backfilled
+        on-the-fly from manifest metadata.
+        """
+        if key == "latest":
+            manifest = self.load_manifest()
+            if not manifest.snapshots:
+                return None
+            entry = max(manifest.snapshots, key=lambda x: x.get("timestamp", ""))
+            key = entry["key"]
+
+        snapshot_file = self.snapshots_dir / f"{key}.json"
+        if not snapshot_file.exists():
+            return None
+        snap = Snapshot.from_dict(json.loads(snapshot_file.read_text(encoding="utf-8")))
+
+        # Backfill missing deltas from manifest
+        if snap.vs_previous is None or snap.vs_baseline is None:
+            manifest = self.load_manifest()
+            entries = sorted(manifest.snapshots, key=lambda x: x.get("timestamp", ""), reverse=True)
+            idx = next((i for i, s in enumerate(entries) if s.get("key") == key), None)
+
+            if idx is not None:
+                if snap.vs_previous is None and idx + 1 < len(entries):
+                    prev_m = entries[idx + 1].get("metrics", {})
+                    snap.vs_previous = {
+                        "nodes": snap.metrics.get("total_nodes", 0) - prev_m.get("total_nodes", 0),
+                        "edges": snap.metrics.get("total_edges", 0) - prev_m.get("total_edges", 0),
+                    }
+                if snap.vs_baseline is None and entries:
+                    base_m = entries[-1].get("metrics", {})
+                    if entries[-1].get("key") != key:
+                        snap.vs_baseline = {
+                            "nodes": snap.metrics.get("total_nodes", 0)
+                            - base_m.get("total_nodes", 0),
+                            "edges": snap.metrics.get("total_edges", 0)
+                            - base_m.get("total_edges", 0),
+                        }
+        return snap
+
+    def get_previous(self, key: str) -> Snapshot | None:
+        """Get the snapshot immediately before *key* (by timestamp)."""
+        manifest = self.load_manifest()
+        current_ts = next(
+            (s["timestamp"] for s in manifest.snapshots if s.get("key") == key),
+            None,
+        )
+        if not current_ts:
+            return None
+        prev_entry = None
+        for s in sorted(manifest.snapshots, key=lambda x: x["timestamp"], reverse=True):
+            if s["timestamp"] < current_ts:
+                prev_entry = s
+                break
+        return self.load_snapshot(prev_entry["key"]) if prev_entry else None
+
+    def get_baseline(self) -> Snapshot | None:
+        """Get the oldest snapshot (baseline for comparison)."""
+        manifest = self.load_manifest()
+        if not manifest.snapshots:
+            return None
+        baseline_entry = min(manifest.snapshots, key=lambda x: x["timestamp"])
+        return self.load_snapshot(baseline_entry["key"])
+
+    def list_snapshots(
+        self,
+        limit: int | None = None,
+        branch: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """List snapshots in reverse chronological order.
+
+        :param limit: Max number to return; ``None`` = all.
+        :param branch: If provided, filter by branch name.
+        :return: List of snapshot metadata dicts.
+        """
+        manifest = self.load_manifest()
+        all_snaps = sorted(manifest.snapshots, key=lambda x: x["timestamp"], reverse=True)
+
+        if branch is not None:
+            all_snaps = [s for s in all_snaps if s.get("branch") == branch]
+
+        for i, snap in enumerate(all_snaps):
+            if snap.get("deltas", {}).get("vs_previous") is None and i + 1 < len(all_snaps):
+                prev = all_snaps[i + 1]
+                snap.setdefault("deltas", {})["vs_previous"] = self._compute_delta_from_metrics(
+                    snap["metrics"], prev["metrics"]
+                )
+
+        return all_snaps[:limit] if limit else all_snaps
+
+    def diff_snapshots(self, key_a: str, key_b: str) -> dict[str, Any]:
+        """Compare two snapshots side-by-side.
+
+        :param key_a: First snapshot key (tree hash).
+        :param key_b: Second snapshot key (tree hash).
+        :return: Dict with metrics from both and computed deltas.
+        """
+        snap_a = self.load_snapshot(key_a)
+        snap_b = self.load_snapshot(key_b)
+
+        if not snap_a or not snap_b:
+            return {"error": "One or both snapshots not found"}
+
+        all_node_kinds = set(snap_a.metrics.get("node_counts", {})) | set(
+            snap_b.metrics.get("node_counts", {})
+        )
+        all_edge_rels = set(snap_a.metrics.get("edge_counts", {})) | set(
+            snap_b.metrics.get("edge_counts", {})
+        )
+
+        node_counts_delta = {
+            k: snap_b.metrics.get("node_counts", {}).get(k, 0)
+            - snap_a.metrics.get("node_counts", {}).get(k, 0)
+            for k in all_node_kinds
+        }
+        edge_counts_delta = {
+            k: snap_b.metrics.get("edge_counts", {}).get(k, 0)
+            - snap_a.metrics.get("edge_counts", {}).get(k, 0)
+            for k in all_edge_rels
+        }
+
+        return {
+            "a": {"key": snap_a.key, "metrics": snap_a.metrics, "issues": snap_a.issues},
+            "b": {"key": snap_b.key, "metrics": snap_b.metrics, "issues": snap_b.issues},
+            "delta": self._compute_delta(snap_b, snap_a),
+            "node_counts_delta": node_counts_delta,
+            "edge_counts_delta": edge_counts_delta,
+        }
+
+    # ------------------------------------------------------------------
+    # Delta computation — override for domain-specific delta fields
+    # ------------------------------------------------------------------
+
+    def _metrics_changed(self, new_metrics: dict[str, Any], old_metrics: dict[str, Any]) -> bool:
+        """Return ``True`` if metrics represent a meaningful change.
+
+        Override in subclasses to customise.
+        """
+        return new_metrics != old_metrics
+
+    def _compute_delta(self, snap_new: Snapshot, snap_old: Snapshot) -> dict[str, Any]:
+        """Compute metrics delta (new - old).
+
+        Override in subclasses to add domain-specific delta fields.
+        """
+
+        def _to_dict(m: Any) -> dict[str, Any]:
+            if isinstance(m, dict):
+                return m
+            if dataclasses.is_dataclass(m) and not isinstance(m, type):
+                return dataclasses.asdict(m)
+            return {}
+
+        return self._compute_delta_from_metrics(
+            _to_dict(snap_new.metrics), _to_dict(snap_old.metrics)
+        )
+
+    def _compute_delta_from_metrics(
+        self, new_m: dict[str, Any], old_m: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Compute delta from two raw metrics dicts.
+
+        Override in subclasses to add domain-specific delta fields.
+        """
+        return {
+            "nodes": new_m.get("total_nodes", 0) - old_m.get("total_nodes", 0),
+            "edges": new_m.get("total_edges", 0) - old_m.get("total_edges", 0),
+        }
+
+    # ------------------------------------------------------------------
+    # Prune
+    # ------------------------------------------------------------------
+
+    def prune_snapshots(self, *, dry_run: bool = False) -> PruneResult:
+        """Remove vestigial snapshots that carry no new metric information.
+
+        :param dry_run: If ``True``, compute what would be removed without deleting.
+        :return: :class:`PruneResult` summarising the cleanup.
+        """
+        manifest = self.load_manifest()
+        by_time = sorted(manifest.snapshots, key=lambda x: x.get("timestamp", ""))
+
+        removed_keys: list[str] = []
+        broken_keys: list[str] = []
+        orphaned_files: list[str] = []
+
+        # Pass 1: separate valid entries from broken ones.
+        valid: list[dict[str, Any]] = []
+        for entry in by_time:
+            key = entry.get("key", "")
+            fname = entry.get("file", f"{key}.json")
+            if not (self.snapshots_dir / fname).exists():
+                broken_keys.append(key)
+            else:
+                valid.append(entry)
+
+        # Pass 2: flag metric-duplicate interior entries.
+        if len(valid) > 2:
+            kept_metrics = valid[0].get("metrics", {})
+            for entry in valid[1:-1]:
+                m = entry.get("metrics", {})
+                if not self._metrics_changed(m, kept_metrics):
+                    removed_keys.append(entry.get("key", ""))
+                else:
+                    kept_metrics = m
+
+        # Pass 3: find orphaned JSON files.
+        referenced_files = {e.get("file", f"{e.get('key', '')}.json") for e in manifest.snapshots}
+        for path in self.snapshots_dir.glob("*.json"):
+            if path.name == "manifest.json":
+                continue
+            if path.name not in referenced_files:
+                orphaned_files.append(path.name)
+
+        if not dry_run:
+            entry_by_key = {e.get("key"): e for e in manifest.snapshots}
+
+            for key in removed_keys:
+                entry = entry_by_key.get(key, {})
+                fname = entry.get("file", f"{key}.json")
+                p = self.snapshots_dir / fname
+                if p.exists():
+                    p.unlink()
+
+            for fname in orphaned_files:
+                p = self.snapshots_dir / fname
+                if p.exists():
+                    p.unlink()
+
+            drop_keys = set(removed_keys) | set(broken_keys)
+            manifest.snapshots = [e for e in manifest.snapshots if e.get("key") not in drop_keys]
+            manifest.last_update = datetime.now(UTC).isoformat()
+            self._save_manifest(manifest)
+
+        return PruneResult(
+            removed=removed_keys,
+            orphaned_files=orphaned_files,
+            broken_entries=broken_keys,
+            dry_run=dry_run,
+        )
+
+    # ------------------------------------------------------------------
+    # Git helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _get_current_tree_hash() -> str:
+        """Get current git tree hash (HEAD^{tree})."""
+        try:
+            return subprocess.check_output(
+                ["git", "rev-parse", "HEAD^{tree}"],
+                text=True,
+                stderr=subprocess.DEVNULL,
+            ).strip()
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return ""
+
+    @staticmethod
+    def _get_current_branch() -> str:
+        """Get current git branch name."""
+        try:
+            return subprocess.check_output(
+                ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                text=True,
+                stderr=subprocess.DEVNULL,
+            ).strip()
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            return "unknown"