quantnodes 3.0.0__py3-none-any.whl

QuantNodes/monitor/monitor/drift.py

@@ -0,0 +1,190 @@
+# coding=utf-8
+"""漂移检测器 - 三种检测算法"""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+from ..storage.models import DriftAlert, PerformanceSnapshot
+from ..storage.repository import DriftAlertRepository, PerformanceRepository
+
+
+class DriftDetector:
+    """漂移检测器
+
+    支持三种检测:
+    1. KS检验: 收益率分布是否发生变化
+    2. 夏普比率下降: 夏普比率是否显著下降
+    3. 最大回撤超标: 最大回撤是否超过预设阈值
+    """
+
+    def __init__(
+        self,
+        alert_repo: DriftAlertRepository,
+        perf_repo: PerformanceRepository,
+        ks_threshold: float = 0.05,
+        sharpe_drop_pct: float = 0.3,
+        max_drawdown_limit: float = -0.20,
+    ):
+        self.alert_repo = alert_repo
+        self.perf_repo = perf_repo
+        self.ks_threshold = ks_threshold
+        self.sharpe_drop_pct = sharpe_drop_pct
+        self.max_drawdown_limit = max_drawdown_limit
+
+    def detect_ks_drift(
+        self,
+        current_returns: List[float],
+        baseline_returns: List[float],
+        strategy_name: str,
+    ) -> Optional[DriftAlert]:
+        """KS检验: 收益率分布是否发生变化
+
+        使用 scipy.stats.ks_2samp 检验两个样本是否来自同一分布。
+        p_value < threshold → 分布发生显著变化 → 漂移。
+        """
+        if len(current_returns) < 5 or len(baseline_returns) < 5:
+            return None
+
+        try:
+            from scipy.stats import ks_2samp
+            statistic, p_value = ks_2samp(current_returns, baseline_returns)
+        except ImportError:
+            return None
+
+        if p_value < self.ks_threshold:
+            severity = "critical" if p_value < 0.01 else "warning"
+            alert = DriftAlert(
+                strategy_name=strategy_name,
+                alert_type="ks_test",
+                severity=severity,
+                metric_name="return_distribution",
+                current_value=statistic,
+                p_value=p_value,
+                message=(
+                    f"收益分布发生漂移 (KS statistic={statistic:.4f}, "
+                    f"p_value={p_value:.4f} < {self.ks_threshold})"
+                ),
+            )
+            self.alert_repo.create_alert(alert)
+            return alert
+        return None
+
+    def detect_sharpe_drop(
+        self,
+        current_snapshot: PerformanceSnapshot,
+        baseline_snapshot: Optional[PerformanceSnapshot],
+        strategy_name: str,
+    ) -> Optional[DriftAlert]:
+        """夏普比率下降检测
+
+        当前夏普 < 基线夏普 * (1 - drop_pct) → 告警。
+        """
+        if baseline_snapshot is None or current_snapshot.sharpe_ratio is None:
+            return None
+
+        baseline_sharpe = baseline_snapshot.sharpe_ratio
+        current_sharpe = current_snapshot.sharpe_ratio
+
+        if baseline_sharpe is None or baseline_sharpe <= 0:
+            return None
+
+        threshold = baseline_sharpe * (1 - self.sharpe_drop_pct)
+        if current_sharpe < threshold:
+            drop_pct = (baseline_sharpe - current_sharpe) / baseline_sharpe
+            severity = "critical" if drop_pct > 0.5 else "warning"
+            alert = DriftAlert(
+                strategy_name=strategy_name,
+                alert_type="sharpe_drop",
+                severity=severity,
+                metric_name="sharpe_ratio",
+                current_value=current_sharpe,
+                baseline_value=baseline_sharpe,
+                message=(
+                    f"夏普比率下降 {drop_pct:.1%} "
+                    f"(当前={current_sharpe:.4f}, 基线={baseline_sharpe:.4f}, "
+                    f"阈值={threshold:.4f})"
+                ),
+            )
+            self.alert_repo.create_alert(alert)
+            return alert
+        return None
+
+    def detect_drawdown_breach(
+        self,
+        current_snapshot: PerformanceSnapshot,
+        strategy_name: str,
+    ) -> Optional[DriftAlert]:
+        """最大回撤超标检测
+
+        |current_dd| > max_allowed_dd → 告警。
+        """
+        if current_snapshot.max_drawdown is None:
+            return None
+
+        current_dd = current_snapshot.max_drawdown
+        if abs(current_dd) > abs(self.max_drawdown_limit):
+            critical_threshold = abs(self.max_drawdown_limit) * 1.5
+            severity = (
+                "critical" if abs(current_dd) > critical_threshold else "warning"
+            )
+            alert = DriftAlert(
+                strategy_name=strategy_name,
+                alert_type="drawdown_breach",
+                severity=severity,
+                metric_name="max_drawdown",
+                current_value=current_dd,
+                baseline_value=self.max_drawdown_limit,
+                message=(
+                    f"最大回撤超标 "
+                    f"(当前={current_dd:.4f}, 限制={self.max_drawdown_limit:.4f})"
+                ),
+            )
+            self.alert_repo.create_alert(alert)
+            return alert
+        return None
+
+    def run_all_checks(
+        self,
+        strategy_name: str,
+        current_returns: Optional[List[float]] = None,
+    ) -> List[DriftAlert]:
+        """运行所有漂移检测
+
+        Args:
+            strategy_name: 策略名称
+            current_returns: 当前收益率序列 (用于KS检验)
+
+        Returns:
+            触发的告警列表
+        """
+        alerts = []
+
+        # 获取最新快照和基线
+        current = self.perf_repo.get_latest(strategy_name)
+        baseline = self.perf_repo.get_baseline(strategy_name)
+
+        if current is None:
+            return alerts
+
+        # 1. KS检验
+        if current_returns and baseline:
+            baseline_returns_str = baseline.daily_returns
+            if baseline_returns_str:
+                import json
+                baseline_returns = json.loads(baseline_returns_str)
+                alert = self.detect_ks_drift(current_returns, baseline_returns, strategy_name)
+                if alert:
+                    alerts.append(alert)
+
+        # 2. 夏普比率下降
+        alert = self.detect_sharpe_drop(current, baseline, strategy_name)
+        if alert:
+            alerts.append(alert)
+
+        # 3. 最大回撤超标
+        alert = self.detect_drawdown_breach(current, strategy_name)
+        if alert:
+            alerts.append(alert)
+
+        return alerts

QuantNodes/monitor/scheduler/__init__.py

@@ -0,0 +1,4 @@
+from .scheduler import StrategyScheduler
+from .runner import StrategyRunner
+
+__all__ = ["StrategyScheduler", "StrategyRunner"]

QuantNodes/monitor/scheduler/runner.py

@@ -0,0 +1,133 @@
+# coding=utf-8
+"""策略执行器 - 被调度器调用"""
+
+from __future__ import annotations
+
+import logging
+import traceback
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Dict, Any
+
+from ..storage.models import StrategyRun
+from ..storage.repository import DatabaseManager, StrategyRunRepository
+from ..monitor.collector import MetricsCollector
+from ..monitor.drift import DriftDetector
+from ..monitor.alerter import Alerter
+
+logger = logging.getLogger(__name__)
+
+
+class StrategyRunner:
+    """策略执行器
+
+    被调度器调用，执行策略并记录结果。
+    """
+
+    def __init__(
+        self,
+        run_repo: StrategyRunRepository,
+        metrics_collector: MetricsCollector,
+        drift_detector: DriftDetector,
+        alerter: Alerter,
+    ):
+        self.run_repo = run_repo
+        self.collector = metrics_collector
+        self.drift_detector = drift_detector
+        self.alerter = alerter
+
+    @classmethod
+    def from_default_db(cls, db_path: str = "~/.quantnodes/monitor.db") -> StrategyRunner:
+        """从默认数据库创建StrategyRunner"""
+        db = DatabaseManager(db_path)
+        db.connect()
+        run_repo = StrategyRunRepository(db)
+        from ..storage.repository import PerformanceRepository, DriftAlertRepository
+        perf_repo = PerformanceRepository(db)
+        alert_repo = DriftAlertRepository(db)
+        collector = MetricsCollector(perf_repo)
+        drift = DriftDetector(alert_repo, perf_repo)
+        alerter = Alerter(alert_repo)
+        return cls(run_repo, collector, drift, alerter)
+
+    def run_strategy(
+        self,
+        strategy_name: str,
+        config_path: str,
+        run_type: str = "sample_out",
+        version: str = None,
+    ) -> Optional[Dict[str, Any]]:
+        """执行策略并记录结果
+
+        Args:
+            strategy_name: 策略名称
+            config_path: YAML配置文件路径
+            run_type: 运行类型 (backtest/live/sample_out)
+            version: 策略版本号
+
+        Returns:
+            执行结果字典
+        """
+        # 读取配置快照
+        config_snapshot = ""
+        try:
+            config_snapshot = Path(config_path).read_text(encoding="utf-8")
+        except Exception:
+            pass
+
+        # 创建运行记录
+        run = StrategyRun(
+            strategy_name=strategy_name,
+            run_type=run_type,
+            status="running",
+            strategy_version=version,
+            start_time=datetime.now(),
+            config_snapshot=config_snapshot,
+        )
+        run_id = self.run_repo.create(run)
+
+        try:
+            # 执行回测
+            statistics = self._execute_backtest(config_path)
+
+            # 更新运行记录
+            self.run_repo.update_status(run_id, "success", statistics=statistics)
+
+            # 采集绩效指标
+            if statistics:
+                self.collector.collect_from_backtest(strategy_name, statistics)
+
+                # 运行漂移检测
+                alerts = self.drift_detector.run_all_checks(strategy_name)
+                if alerts:
+                    logger.warning(
+                        f"Strategy {strategy_name}: {len(alerts)} drift alerts"
+                    )
+
+            logger.info(f"Strategy {strategy_name} completed successfully")
+            return {
+                "status": "success",
+                "run_id": run_id,
+                "statistics": statistics,
+                "alerts": [a.message for a in alerts] if alerts else [],
+            }
+
+        except Exception as e:
+            error_msg = traceback.format_exc()
+            self.run_repo.update_status(run_id, "failed", error_message=error_msg)
+            logger.error(f"Strategy {strategy_name} failed: {e}")
+            return {
+                "status": "failed",
+                "run_id": run_id,
+                "error": str(e),
+            }
+
+    def _execute_backtest(self, config_path: str) -> Optional[Dict[str, Any]]:
+        """执行回测"""
+        from QuantNodes.agent.config.loader import ConfigLoader
+
+        loader = ConfigLoader()
+        config = loader.load(config_path)
+
+        # TODO: integrate ConfigBacktestTool when stub is ready
+        return {"status": "completed", "config": config.name}

QuantNodes/monitor/scheduler/scheduler.py

@@ -0,0 +1,184 @@
+# coding=utf-8
+"""基于APScheduler的策略调度器"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import List, Dict, Any
+
+from apscheduler.schedulers.background import BackgroundScheduler
+from apscheduler.jobstores.sqlalchemy import SQLAlchemyJobStore
+from apscheduler.executors.pool import ThreadPoolExecutor
+
+logger = logging.getLogger(__name__)
+
+
+def _run_strategy_job_static(strategy_name: str, config_path: str, **kwargs):
+    """静态函数: 执行策略任务 (避免序列化问题)"""
+    from .runner import StrategyRunner
+    runner = StrategyRunner.from_default_db()
+    runner.run_strategy(strategy_name, config_path, **kwargs)
+
+
+class StrategyScheduler:
+    """基于APScheduler的策略调度器
+
+    支持三种触发方式:
+    - cron: cron表达式定时
+    - interval: 间隔定时
+    - date: 指定时间执行一次
+    """
+
+    def __init__(self, db_path: str = "~/.quantnodes/monitor.db"):
+        db_url = f"sqlite:///{Path(db_path).expanduser()}"
+        self.scheduler = BackgroundScheduler(
+            jobstores={"default": SQLAlchemyJobStore(url=db_url)},
+            executors={"default": ThreadPoolExecutor(max_workers=4)},
+            job_defaults={"coalesce": True, "max_instances": 1},
+        )
+        self._started = False
+
+    def add_cron_job(
+        self,
+        strategy_name: str,
+        cron_expr: str,
+        config_path: str,
+        **kwargs,
+    ) -> str:
+        """添加cron定时任务
+
+        Args:
+            strategy_name: 策略名称 (作为job id)
+            cron_expr: cron表达式, 如 "0 18 * * 1-5"
+            config_path: YAML配置文件路径
+            **kwargs: 传递给StrategyRunner.run_strategy的额外参数
+
+        Returns:
+            job id
+        """
+        job_id = f"strategy_{strategy_name}"
+        parts = cron_expr.split()
+        cron_kwargs = {}
+        if len(parts) >= 5:
+            cron_kwargs = {
+                "minute": parts[0],
+                "hour": parts[1],
+                "day": parts[2],
+                "month": parts[3],
+                "day_of_week": parts[4],
+            }
+
+        self.scheduler.add_job(
+            _run_strategy_job_static,
+            "cron",
+            id=job_id,
+            replace_existing=True,
+            args=[strategy_name, config_path],
+            kwargs=kwargs,
+            **cron_kwargs,
+        )
+        logger.info(f"Added cron job: {job_id} ({cron_expr})")
+        return job_id
+
+    def add_interval_job(
+        self,
+        strategy_name: str,
+        interval_minutes: int,
+        config_path: str,
+        **kwargs,
+    ) -> str:
+        """添加间隔定时任务"""
+        job_id = f"strategy_{strategy_name}"
+        self.scheduler.add_job(
+            _run_strategy_job_static,
+            "interval",
+            id=job_id,
+            replace_existing=True,
+            minutes=interval_minutes,
+            args=[strategy_name, config_path],
+            kwargs=kwargs,
+        )
+        logger.info(f"Added interval job: {job_id} ({interval_minutes}min)")
+        return job_id
+
+    def add_date_job(
+        self,
+        strategy_name: str,
+        run_date,
+        config_path: str,
+        **kwargs,
+    ) -> str:
+        """添加一次性定时任务"""
+        job_id = f"strategy_{strategy_name}_{run_date}"
+        self.scheduler.add_job(
+            _run_strategy_job_static,
+            "date",
+            id=job_id,
+            run_date=run_date,
+            args=[strategy_name, config_path],
+            kwargs=kwargs,
+        )
+        logger.info(f"Added date job: {job_id} ({run_date})")
+        return job_id
+
+    def remove_job(self, strategy_name: str) -> bool:
+        """移除任务"""
+        job_id = f"strategy_{strategy_name}"
+        try:
+            self.scheduler.remove_job(job_id)
+            logger.info(f"Removed job: {job_id}")
+            return True
+        except Exception:
+            return False
+
+    def get_jobs(self) -> List[Dict[str, Any]]:
+        """获取所有任务"""
+        jobs = []
+        for job in self.scheduler.get_jobs():
+            next_run = None
+            try:
+                next_run_time = job.next_run_time
+                if next_run_time:
+                    next_run = str(next_run_time)
+            except Exception:
+                pass
+            jobs.append({
+                "id": job.id,
+                "name": job.name,
+                "next_run_time": next_run,
+                "trigger": str(job.trigger),
+            })
+        return jobs
+
+    def pause_job(self, strategy_name: str) -> bool:
+        """暂停任务"""
+        job_id = f"strategy_{strategy_name}"
+        try:
+            self.scheduler.pause_job(job_id)
+            return True
+        except Exception:
+            return False
+
+    def resume_job(self, strategy_name: str) -> bool:
+        """恢复任务"""
+        job_id = f"strategy_{strategy_name}"
+        try:
+            self.scheduler.resume_job(job_id)
+            return True
+        except Exception:
+            return False
+
+    def start(self):
+        """启动调度器"""
+        if not self._started:
+            self.scheduler.start()
+            self._started = True
+            logger.info("Scheduler started")
+
+    def shutdown(self):
+        """关闭调度器"""
+        if self._started:
+            self.scheduler.shutdown(wait=False)
+            self._started = False
+            logger.info("Scheduler shutdown")

QuantNodes/monitor/storage/__init__.py

@@ -0,0 +1,16 @@
+from .models import (
+    StrategyRun, PerformanceSnapshot, DriftAlert, StrategyVersion,
+)
+from .repository import (
+    DatabaseManager,
+    StrategyRunRepository,
+    PerformanceRepository,
+    DriftAlertRepository,
+    VersionRepository,
+)
+
+__all__ = [
+    "StrategyRun", "PerformanceSnapshot", "DriftAlert", "StrategyVersion",
+    "DatabaseManager", "StrategyRunRepository", "PerformanceRepository",
+    "DriftAlertRepository", "VersionRepository",
+]

QuantNodes/monitor/storage/models.py

@@ -0,0 +1,70 @@
+# coding=utf-8
+"""监控数据模型 - SQLite表结构定义"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date, datetime
+from typing import Optional
+
+
+@dataclass
+class StrategyRun:
+    """策略运行记录"""
+    strategy_name: str
+    run_type: str  # 'backtest' | 'live' | 'sample_out'
+    status: str  # 'running' | 'success' | 'failed'
+    strategy_version: Optional[str] = None
+    start_time: Optional[datetime] = None
+    end_time: Optional[datetime] = None
+    config_snapshot: Optional[str] = None
+    statistics: Optional[str] = None  # JSON字符串
+    error_message: Optional[str] = None
+    id: Optional[int] = None
+    created_at: Optional[datetime] = None
+
+
+@dataclass
+class PerformanceSnapshot:
+    """绩效快照"""
+    strategy_name: str
+    snapshot_date: date
+    sharpe_ratio: Optional[float] = None
+    sortino_ratio: Optional[float] = None
+    max_drawdown: Optional[float] = None
+    annualized_return: Optional[float] = None
+    annualized_volatility: Optional[float] = None
+    win_rate: Optional[float] = None
+    profit_factor: Optional[float] = None
+    total_trades: Optional[int] = None
+    daily_returns: Optional[str] = None  # JSON数组
+    id: Optional[int] = None
+    created_at: Optional[datetime] = None
+
+
+@dataclass
+class DriftAlert:
+    """漂移告警"""
+    strategy_name: str
+    alert_type: str  # 'ks_test' | 'sharpe_drop' | 'drawdown_breach'
+    severity: str  # 'warning' | 'critical'
+    metric_name: Optional[str] = None
+    current_value: Optional[float] = None
+    baseline_value: Optional[float] = None
+    p_value: Optional[float] = None
+    message: Optional[str] = None
+    acknowledged: bool = False
+    id: Optional[int] = None
+    created_at: Optional[datetime] = None
+
+
+@dataclass
+class StrategyVersion:
+    """策略版本"""
+    strategy_name: str
+    version: str
+    config_snapshot: str  # YAML配置内容
+    commit_hash: Optional[str] = None
+    description: Optional[str] = None
+    id: Optional[int] = None
+    created_at: Optional[datetime] = None