quantnodes 3.0.0__py3-none-any.whl

QuantNodes/monitor/storage/repository.py

@@ -0,0 +1,407 @@
+# coding=utf-8
+"""监控数据仓储层 - SQLite CRUD操作"""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import date, datetime, timedelta
+from pathlib import Path
+from typing import Optional, List
+
+from QuantNodes.core.path_utils import ensure_parent
+
+from .models import (
+    StrategyRun, PerformanceSnapshot, DriftAlert, StrategyVersion,
+)
+
+# SQLite建表DDL
+_CREATE_TABLES = """
+CREATE TABLE IF NOT EXISTS strategy_runs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    strategy_name TEXT NOT NULL,
+    strategy_version TEXT,
+    run_type TEXT NOT NULL,
+    start_time TIMESTAMP,
+    end_time TIMESTAMP,
+    status TEXT NOT NULL,
+    config_snapshot TEXT,
+    statistics TEXT,
+    error_message TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS performance_snapshots (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    strategy_name TEXT NOT NULL,
+    snapshot_date DATE NOT NULL,
+    sharpe_ratio REAL,
+    sortino_ratio REAL,
+    max_drawdown REAL,
+    annualized_return REAL,
+    annualized_volatility REAL,
+    win_rate REAL,
+    profit_factor REAL,
+    total_trades INTEGER,
+    daily_returns TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(strategy_name, snapshot_date)
+);
+
+CREATE TABLE IF NOT EXISTS drift_alerts (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    strategy_name TEXT NOT NULL,
+    alert_type TEXT NOT NULL,
+    severity TEXT NOT NULL,
+    metric_name TEXT,
+    current_value REAL,
+    baseline_value REAL,
+    p_value REAL,
+    message TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    acknowledged BOOLEAN DEFAULT FALSE
+);
+
+CREATE TABLE IF NOT EXISTS strategy_versions (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    strategy_name TEXT NOT NULL,
+    version TEXT NOT NULL,
+    commit_hash TEXT,
+    config_snapshot TEXT NOT NULL,
+    description TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    UNIQUE(strategy_name, version)
+);
+"""
+
+
+class DatabaseManager:
+    """SQLite数据库管理器"""
+
+    def __init__(self, db_path: str = "~/.quantnodes/monitor.db"):
+        self.db_path = Path(db_path).expanduser()
+        ensure_parent(self.db_path)
+        self._conn: Optional[sqlite3.Connection] = None
+
+    def connect(self) -> sqlite3.Connection:
+        if self._conn is None:
+            self._conn = sqlite3.connect(str(self.db_path))
+            self._conn.row_factory = sqlite3.Row
+            self._conn.execute("PRAGMA journal_mode=WAL")
+            self._conn.execute("PRAGMA foreign_keys=ON")
+            self._create_tables()
+        return self._conn
+
+    def _create_tables(self):
+        self._conn.executescript(_CREATE_TABLES)
+
+    def close(self):
+        if self._conn:
+            self._conn.close()
+            self._conn = None
+
+    def __enter__(self):
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+
+    @property
+    def conn(self) -> sqlite3.Connection:
+        if self._conn is None:
+            self.connect()
+        return self._conn
+
+
+class StrategyRunRepository:
+    """策略运行记录仓储"""
+
+    def __init__(self, db: DatabaseManager):
+        self.db = db
+
+    def create(self, run: StrategyRun) -> int:
+        cur = self.db.conn.execute(
+            """INSERT INTO strategy_runs
+               (strategy_name, strategy_version, run_type, start_time, end_time,
+                status, config_snapshot, statistics, error_message)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (run.strategy_name, run.strategy_version, run.run_type,
+             run.start_time, run.end_time, run.status,
+             run.config_snapshot, run.statistics, run.error_message),
+        )
+        self.db.conn.commit()
+        return cur.lastrowid
+
+    def get_by_id(self, run_id: int) -> Optional[StrategyRun]:
+        row = self.db.conn.execute(
+            "SELECT * FROM strategy_runs WHERE id = ?", (run_id,)
+        ).fetchone()
+        return self._row_to_run(row) if row else None
+
+    def get_by_strategy(self, strategy_name: str, limit: int = 50) -> List[StrategyRun]:
+        rows = self.db.conn.execute(
+            "SELECT * FROM strategy_runs WHERE strategy_name = ? ORDER BY created_at DESC LIMIT ?",
+            (strategy_name, limit),
+        ).fetchall()
+        return [self._row_to_run(r) for r in rows]
+
+    def update_status(self, run_id: int, status: str,
+                      statistics: dict = None, error_message: str = None) -> None:
+        stats_json = json.dumps(statistics) if statistics else None
+        if status in ("success", "failed"):
+            self.db.conn.execute(
+                """UPDATE strategy_runs
+                   SET status = ?, statistics = ?, error_message = ?, end_time = ?
+                   WHERE id = ?""",
+                (status, stats_json, error_message, datetime.now(), run_id),
+            )
+        else:
+            self.db.conn.execute(
+                "UPDATE strategy_runs SET status = ? WHERE id = ?",
+                (status, run_id),
+            )
+        self.db.conn.commit()
+
+    def delete_old(self, strategy_name: str, keep_count: int = 100) -> int:
+        # SQLite 不支持 OFFSET in DELETE subquery, 使用 LIMIT 方式
+        cur = self.db.conn.execute(
+            """DELETE FROM strategy_runs WHERE id NOT IN (
+                   SELECT id FROM strategy_runs
+                   WHERE strategy_name = ?
+                   ORDER BY created_at DESC
+                   LIMIT ?
+               ) AND strategy_name = ?""",
+            (strategy_name, keep_count, strategy_name),
+        )
+        self.db.conn.commit()
+        return cur.rowcount
+
+    @staticmethod
+    def _row_to_run(row: sqlite3.Row) -> StrategyRun:
+        return StrategyRun(
+            id=row["id"],
+            strategy_name=row["strategy_name"],
+            strategy_version=row["strategy_version"],
+            run_type=row["run_type"],
+            start_time=row["start_time"],
+            end_time=row["end_time"],
+            status=row["status"],
+            config_snapshot=row["config_snapshot"],
+            statistics=row["statistics"],
+            error_message=row["error_message"],
+            created_at=row["created_at"],
+        )
+
+
+class PerformanceRepository:
+    """绩效快照仓储"""
+
+    def __init__(self, db: DatabaseManager):
+        self.db = db
+
+    def save_snapshot(self, snapshot: PerformanceSnapshot) -> int:
+        cur = self.db.conn.execute(
+            """INSERT OR REPLACE INTO performance_snapshots
+               (strategy_name, snapshot_date, sharpe_ratio, sortino_ratio,
+                max_drawdown, annualized_return, annualized_volatility,
+                win_rate, profit_factor, total_trades, daily_returns)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (snapshot.strategy_name, snapshot.snapshot_date,
+             snapshot.sharpe_ratio, snapshot.sortino_ratio,
+             snapshot.max_drawdown, snapshot.annualized_return,
+             snapshot.annualized_volatility, snapshot.win_rate,
+             snapshot.profit_factor, snapshot.total_trades,
+             snapshot.daily_returns),
+        )
+        self.db.conn.commit()
+        return cur.lastrowid
+
+    def get_latest(self, strategy_name: str) -> Optional[PerformanceSnapshot]:
+        row = self.db.conn.execute(
+            """SELECT * FROM performance_snapshots
+               WHERE strategy_name = ? ORDER BY snapshot_date DESC LIMIT 1""",
+            (strategy_name,),
+        ).fetchone()
+        return self._row_to_snapshot(row) if row else None
+
+    def get_history(self, strategy_name: str, days: int = 30) -> List[PerformanceSnapshot]:
+        cutoff = date.today() - timedelta(days=days)
+        rows = self.db.conn.execute(
+            """SELECT * FROM performance_snapshots
+               WHERE strategy_name = ? AND snapshot_date >= ?
+               ORDER BY snapshot_date""",
+            (strategy_name, cutoff.isoformat()),
+        ).fetchall()
+        return [self._row_to_snapshot(r) for r in rows]
+
+    def get_baseline(self, strategy_name: str, days: int = 252) -> Optional[PerformanceSnapshot]:
+        cutoff = date.today() - timedelta(days=days)
+        rows = self.db.conn.execute(
+            """SELECT * FROM performance_snapshots
+               WHERE strategy_name = ? AND snapshot_date >= ?
+               ORDER BY snapshot_date""",
+            (strategy_name, cutoff.isoformat()),
+        ).fetchall()
+        if not rows:
+            return None
+        snapshots = [self._row_to_snapshot(r) for r in rows]
+        return self._average_snapshots(snapshots)
+
+    @staticmethod
+    def _average_snapshots(snapshots: List[PerformanceSnapshot]) -> PerformanceSnapshot:
+        n = len(snapshots)
+        s = snapshots[0]
+        return PerformanceSnapshot(
+            strategy_name=s.strategy_name,
+            snapshot_date=s.snapshot_date,
+            sharpe_ratio=sum(s.sharpe_ratio or 0 for s in snapshots) / n,
+            sortino_ratio=sum(s.sortino_ratio or 0 for s in snapshots) / n,
+            max_drawdown=sum(s.max_drawdown or 0 for s in snapshots) / n,
+            annualized_return=sum(s.annualized_return or 0 for s in snapshots) / n,
+            annualized_volatility=sum(s.annualized_volatility or 0 for s in snapshots) / n,
+            win_rate=sum(s.win_rate or 0 for s in snapshots) / n,
+            profit_factor=sum(s.profit_factor or 0 for s in snapshots) / n,
+            total_trades=sum(s.total_trades or 0 for s in snapshots) // n,
+        )
+
+    @staticmethod
+    def _row_to_snapshot(row: sqlite3.Row) -> PerformanceSnapshot:
+        return PerformanceSnapshot(
+            id=row["id"],
+            strategy_name=row["strategy_name"],
+            snapshot_date=row["snapshot_date"],
+            sharpe_ratio=row["sharpe_ratio"],
+            sortino_ratio=row["sortino_ratio"],
+            max_drawdown=row["max_drawdown"],
+            annualized_return=row["annualized_return"],
+            annualized_volatility=row["annualized_volatility"],
+            win_rate=row["win_rate"],
+            profit_factor=row["profit_factor"],
+            total_trades=row["total_trades"],
+            daily_returns=row["daily_returns"],
+            created_at=row["created_at"],
+        )
+
+
+class DriftAlertRepository:
+    """漂移告警仓储"""
+
+    def __init__(self, db: DatabaseManager):
+        self.db = db
+
+    def create_alert(self, alert: DriftAlert) -> int:
+        cur = self.db.conn.execute(
+            """INSERT INTO drift_alerts
+               (strategy_name, alert_type, severity, metric_name,
+                current_value, baseline_value, p_value, message, acknowledged)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (alert.strategy_name, alert.alert_type, alert.severity,
+             alert.metric_name, alert.current_value, alert.baseline_value,
+             alert.p_value, alert.message, alert.acknowledged),
+        )
+        self.db.conn.commit()
+        return cur.lastrowid
+
+    def get_pending(self, strategy_name: str = None) -> List[DriftAlert]:
+        if strategy_name:
+            rows = self.db.conn.execute(
+                """SELECT * FROM drift_alerts
+                   WHERE strategy_name = ? AND acknowledged = 0
+                   ORDER BY created_at DESC""",
+                (strategy_name,),
+            ).fetchall()
+        else:
+            rows = self.db.conn.execute(
+                """SELECT * FROM drift_alerts
+                   WHERE acknowledged = 0 ORDER BY created_at DESC"""
+            ).fetchall()
+        return [self._row_to_alert(r) for r in rows]
+
+    def acknowledge(self, alert_id: int) -> None:
+        self.db.conn.execute(
+            "UPDATE drift_alerts SET acknowledged = 1 WHERE id = ?",
+            (alert_id,),
+        )
+        self.db.conn.commit()
+
+    def get_history(self, strategy_name: str, days: int = 30) -> List[DriftAlert]:
+        cutoff = datetime.now() - timedelta(days=days)
+        rows = self.db.conn.execute(
+            """SELECT * FROM drift_alerts
+               WHERE strategy_name = ? AND created_at >= ?
+               ORDER BY created_at DESC""",
+            (strategy_name, cutoff),
+        ).fetchall()
+        return [self._row_to_alert(r) for r in rows]
+
+    @staticmethod
+    def _row_to_alert(row: sqlite3.Row) -> DriftAlert:
+        return DriftAlert(
+            id=row["id"],
+            strategy_name=row["strategy_name"],
+            alert_type=row["alert_type"],
+            severity=row["severity"],
+            metric_name=row["metric_name"],
+            current_value=row["current_value"],
+            baseline_value=row["baseline_value"],
+            p_value=row["p_value"],
+            message=row["message"],
+            acknowledged=bool(row["acknowledged"]),
+            created_at=row["created_at"],
+        )
+
+
+class VersionRepository:
+    """策略版本仓储"""
+
+    def __init__(self, db: DatabaseManager):
+        self.db = db
+
+    def save_version(self, version: StrategyVersion) -> int:
+        cur = self.db.conn.execute(
+            """INSERT OR REPLACE INTO strategy_versions
+               (strategy_name, version, commit_hash, config_snapshot, description)
+               VALUES (?, ?, ?, ?, ?)""",
+            (version.strategy_name, version.version,
+             version.commit_hash, version.config_snapshot,
+             version.description),
+        )
+        self.db.conn.commit()
+        return cur.lastrowid
+
+    def get_version(self, strategy_name: str, version: str) -> Optional[StrategyVersion]:
+        row = self.db.conn.execute(
+            """SELECT * FROM strategy_versions
+               WHERE strategy_name = ? AND version = ?""",
+            (strategy_name, version),
+        ).fetchone()
+        return self._row_to_version(row) if row else None
+
+    def list_versions(self, strategy_name: str) -> List[StrategyVersion]:
+        rows = self.db.conn.execute(
+            """SELECT * FROM strategy_versions
+               WHERE strategy_name = ? ORDER BY id DESC""",
+            (strategy_name,),
+        ).fetchall()
+        return [self._row_to_version(r) for r in rows]
+
+    def get_latest(self, strategy_name: str) -> Optional[StrategyVersion]:
+        row = self.db.conn.execute(
+            """SELECT * FROM strategy_versions
+               WHERE strategy_name = ? ORDER BY id DESC LIMIT 1""",
+            (strategy_name,),
+        ).fetchone()
+        return self._row_to_version(row) if row else None
+
+    @staticmethod
+    def _row_to_version(row: sqlite3.Row) -> StrategyVersion:
+        return StrategyVersion(
+            id=row["id"],
+            strategy_name=row["strategy_name"],
+            version=row["version"],
+            commit_hash=row["commit_hash"],
+            config_snapshot=row["config_snapshot"],
+            description=row["description"],
+            created_at=row["created_at"],
+        )

QuantNodes/monitor/version/__init__.py

@@ -0,0 +1,4 @@
+from .version_manager import VersionManager
+from .diff import ConfigDiffer
+
+__all__ = ["VersionManager", "ConfigDiffer"]

QuantNodes/monitor/version/diff.py

@@ -0,0 +1,81 @@
+# coding=utf-8
+"""YAML配置差异对比"""
+
+from __future__ import annotations
+
+import difflib
+from typing import Dict, Any, List, Tuple
+
+
+class ConfigDiffer:
+    """YAML配置差异对比"""
+
+    def diff_configs_text(self, config1_text: str, config2_text: str) -> List[str]:
+        """对比两个YAML文本的差异
+
+        Returns:
+            unified diff 行列表
+        """
+        lines1 = config1_text.splitlines(keepends=True)
+        lines2 = config2_text.splitlines(keepends=True)
+        return list(difflib.unified_diff(
+            lines1, lines2,
+            fromfile="version_a", tofile="version_b",
+            lineterm="",
+        ))
+
+    def diff_configs(
+        self, config1: Dict[str, Any], config2: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """对比两个配置字典的差异
+
+        Returns:
+            结构化差异: {"added": [...], "removed": [...], "changed": [...]}
+        """
+        added = []
+        removed = []
+        changed = []
+
+        all_keys = set(list(config1.keys()) + list(config2.keys()))
+        for key in sorted(all_keys):
+            if key not in config1:
+                added.append({"key": "data." + key, "value": config2[key]})
+            elif key not in config2:
+                removed.append({"key": "data." + key, "value": config1[key]})
+            elif config1[key] != config2[key]:
+                changed.append({
+                    "key": "data." + key,
+                    "old": config1[key],
+                    "new": config2[key],
+                })
+
+        return {"added": added, "removed": removed, "changed": changed}
+
+    def format_diff(self, diff_lines: List[str]) -> str:
+        """格式化差异为可读文本"""
+        if not diff_lines:
+            return "无差异"
+        return "\n".join(diff_lines)
+
+    def validate_rollback_safe(self, diff_result: Dict[str, Any]) -> Tuple[bool, List[str]]:
+        """检查回滚是否安全
+
+        不安全条件:
+        - 删除了关键配置 (data.source, data.table)
+        - 修改了数据源
+
+        Returns:
+            (是否安全, 风险说明列表)
+        """
+        risks = []
+        for item in diff_result.get("removed", []):
+            key = item["key"]
+            if key in ("data.source", "data.table", "data.conn_ini"):
+                risks.append(f"删除了关键配置: {key}")
+
+        for item in diff_result.get("changed", []):
+            key = item["key"]
+            if key in ("data.source", "data.table"):
+                risks.append(f"修改了数据源配置: {key} ({item['old']} → {item['new']})")
+
+        return (len(risks) == 0, risks)

QuantNodes/monitor/version/version_manager.py

@@ -0,0 +1,182 @@
+# coding=utf-8
+"""基于Git的策略版本管理"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import List, Optional
+
+from ..storage.models import StrategyVersion
+from ..storage.repository import VersionRepository
+from .diff import ConfigDiffer
+from QuantNodes.core.path_utils import ensure_dir
+
+
+class VersionManager:
+    """基于Git的策略版本管理
+
+    每个策略对应Git仓库中的一个目录:
+    ~/.quantnodes/strategies/{strategy_name}/
+    """
+
+    def __init__(
+        self,
+        version_repo: VersionRepository,
+        strategies_dir: str = "~/.quantnodes/strategies",
+    ):
+        self.repo = version_repo
+        self.strategies_dir = Path(strategies_dir).expanduser()
+        ensure_dir(self.strategies_dir)
+        self.differ = ConfigDiffer()
+        self._init_repo()
+
+    def _init_repo(self):
+        """初始化Git仓库 (如不存在)"""
+        git_dir = self.strategies_dir / ".git"
+        if not git_dir.exists():
+            import subprocess
+            subprocess.run(
+                ["git", "init"],
+                cwd=str(self.strategies_dir),
+                capture_output=True,
+                check=False,
+            )
+            # 配置 git user
+            subprocess.run(
+                ["git", "config", "user.email", "quantnodes@local"],
+                cwd=str(self.strategies_dir),
+                capture_output=True,
+                check=False,
+            )
+            subprocess.run(
+                ["git", "config", "user.name", "QuantNodes"],
+                cwd=str(self.strategies_dir),
+                capture_output=True,
+                check=False,
+            )
+            # 创建 .gitignore
+            gitignore = self.strategies_dir / ".gitignore"
+            if not gitignore.exists():
+                gitignore.write_text("__pycache__/\n*.pyc\n")
+
+    def save_version(
+        self,
+        strategy_name: str,
+        config_path: str,
+        description: str = "",
+    ) -> StrategyVersion:
+        """保存策略版本
+
+        1. 复制YAML到 strategies/{name}/
+        2. git add + commit
+        3. 保存到数据库
+        """
+        strategy_dir = self.strategies_dir / strategy_name
+        ensure_dir(strategy_dir)
+
+        # 确定版本号
+        existing = self.repo.list_versions(strategy_name)
+        version_num = len(existing) + 1
+        version_str = f"v{version_num}"
+
+        # 复制YAML配置
+        src = Path(config_path).expanduser()
+        dst = strategy_dir / f"{strategy_name}_{version_str}.yaml"
+        shutil.copy2(str(src), str(dst))
+
+        # Git commit
+        commit_msg = f"version {version_str}: {description or strategy_name}"
+        commit_hash = self._git_commit(strategy_dir, commit_msg)
+
+        # 同时保存为 current
+        current_dst = strategy_dir / f"{strategy_name}_current.yaml"
+        shutil.copy2(str(src), str(current_dst))
+        self._git_commit(strategy_dir, f"update current: {strategy_name}")
+
+        # 保存到数据库
+        config_content = src.read_text(encoding="utf-8")
+        sv = StrategyVersion(
+            strategy_name=strategy_name,
+            version=version_str,
+            commit_hash=commit_hash,
+            config_snapshot=config_content,
+            description=description,
+        )
+        sv.id = self.repo.save_version(sv)
+        return sv
+
+    def list_versions(self, strategy_name: str) -> List[StrategyVersion]:
+        """列出策略所有版本"""
+        return self.repo.list_versions(strategy_name)
+
+    def get_version(self, strategy_name: str, version: str) -> Optional[StrategyVersion]:
+        """获取指定版本的配置"""
+        return self.repo.get_version(strategy_name, version)
+
+    def diff_versions(self, strategy_name: str, v1: str, v2: str) -> str:
+        """对比两个版本的差异"""
+        ver1 = self.repo.get_version(strategy_name, v1)
+        ver2 = self.repo.get_version(strategy_name, v2)
+        if not ver1 or not ver2:
+            return f"版本不存在: {v1} 或 {v2}"
+        return self.differ.format_diff(
+            self.differ.diff_configs_text(ver1.config_snapshot, ver2.config_snapshot)
+        )
+
+    def rollback(self, strategy_name: str, target_version: str) -> Optional[StrategyVersion]:
+        """回滚到指定版本"""
+        target = self.repo.get_version(strategy_name, target_version)
+        if not target:
+            return None
+
+        # 写入 current.yaml
+        strategy_dir = self.strategies_dir / strategy_name
+        ensure_dir(strategy_dir)
+        current_path = strategy_dir / f"{strategy_name}_current.yaml"
+        current_path.write_text(target.config_snapshot, encoding="utf-8")
+
+        # Git commit
+        self._git_commit(strategy_dir, f"rollback to {target_version}")
+
+        # 创建新版本记录
+        new_ver_num = len(self.repo.list_versions(strategy_name)) + 1
+        new_version = f"v{new_ver_num}"
+        sv = StrategyVersion(
+            strategy_name=strategy_name,
+            version=new_version,
+            commit_hash=self._git_head(strategy_dir),
+            config_snapshot=target.config_snapshot,
+            description=f"rollback to {target_version}",
+        )
+        sv.id = self.repo.save_version(sv)
+        return sv
+
+    def get_current_version(self, strategy_name: str) -> Optional[str]:
+        """获取当前最新版本号"""
+        latest = self.repo.get_latest(strategy_name)
+        return latest.version if latest else None
+
+    def _git_commit(self, repo_dir: Path, message: str) -> str:
+        """执行 git add + commit，返回 commit hash"""
+        import subprocess
+
+        subprocess.run(
+            ["git", "add", "-A"],
+            cwd=str(repo_dir), capture_output=True, check=False,
+        )
+        subprocess.run(
+            ["git", "commit", "-m", message, "--allow-empty"],
+            cwd=str(repo_dir), capture_output=True, check=False,
+        )
+        return self._git_head(repo_dir)
+
+    @staticmethod
+    def _git_head(repo_dir: Path) -> str:
+        """获取当前 HEAD commit hash"""
+        import subprocess
+        result = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=str(repo_dir), capture_output=True, text=True, check=False,
+        )
+        return result.stdout.strip()[:8] if result.returncode == 0 else "unknown"