maref 0.30.0__py3-none-any.whl

drift_guard/README.md

@@ -0,0 +1,108 @@
+# MAREF DriftGuard
+
+## 概述
+
+DriftGuard 是 MAREF 治理框架的安全层，负责检测和缓解 LoRA（Low-Rank Adaptation）微调过程中的人格漂移。核心功能包括：
+
+1. **统计散度计算** — KL 散度、JS 散度、Hellinger 距离
+2. **阈值监控** — 基于配置的严重性分级（LOW/MEDIUM/HIGH/CRITICAL）
+3. **人工仲裁门控** — HIGH/CRITICAL 级别需要人工审批
+4. **基座模型重置** — 自动回滚到已知良好的基线
+5. **自动化流水线** — 周期性检测、事件记录、趋势分析
+
+## 架构
+
+```
+Base Model Weights
+        |
+        v
+LoRA Adapter (A, B matrices) ---> Delta = scaling * B * A
+        |                                |
+        |                                v
+        |                         Drift Metrics (KL/JS/Hellinger)
+        |                                |
+        v                                v
+Current Weights <--- Base Reset <--- Severity Classification
+                                          |
+                                          v
+                              Human Gate (HIGH/CRITICAL)
+                                          |
+                                          v
+                                    Action Execution
+```
+
+## 核心组件
+
+| 模块 | 说明 |
+|------|------|
+| `types.py` | 数据类型：DriftSeverity, DriftAction, DriftReading, DriftEvent, PipelineConfig |
+| `metrics.py` | 散度计算：kl_divergence, js_divergence, hellinger_distance, compute_drift_metrics |
+| `pipeline.py` | 流水线：HumanArbitrationGate, BaseModelReset, DriftDetectionPipeline |
+
+## 严重性分级
+
+| 级别 | KL 阈值 | Hellinger 阈值 | 自动动作 |
+|------|---------|----------------|----------|
+| NONE | < 0.1 | < 0.2 | 无 |
+| LOW | >= 0.1 | >= 0.2 | ALERT |
+| MEDIUM | >= 0.5 | >= 0.5 | QUARANTINE |
+| HIGH | >= 0.5 | >= 0.5 | BASE_RESET（需人工审批） |
+| CRITICAL | >= 1.0 | >= 0.5 | EMERGENCY_HALT |
+
+## 人工仲裁门控
+
+```
+LOW/MEDIUM severity ──→ AUTO（自动执行）
+HIGH/CRITICAL severity ──→ PENDING_REVIEW ──→ 人工审批 ──→ APPROVED/REJECTED
+                                    └──→ 超时 ──→ TIMEOUT
+```
+
+## 使用示例
+
+```python
+import asyncio
+import numpy as np
+from src.drift_guard.pipeline import DriftDetectionPipeline
+from src.drift_guard.types import ModelSignature, PipelineConfig
+
+async def main():
+    # 配置流水线
+    config = PipelineConfig(
+        kl_warning=0.1,
+        kl_critical=0.5,
+        kl_max=1.0,
+    )
+    pipeline = DriftDetectionPipeline(config)
+    
+    # 模拟权重
+    baseline = np.random.randn(1000)
+    current = baseline + np.random.randn(1000) * 0.5
+    
+    # 检测漂移
+    event = await pipeline.check_drift(
+        baseline_weights=baseline,
+        current_weights=current,
+        model=ModelSignature("lora-adapter", "v1"),
+        baseline=ModelSignature("base-model", "v1"),
+    )
+    
+    if event:
+        print(f"Drift detected: {event.reading.severity.name}")
+        print(f"Action: {event.action_taken.name}")
+        print(f"KL divergence: {event.reading.kl_divergence:.4f}")
+
+asyncio.run(main())
+```
+
+## 设计决策
+
+### 为什么使用三种散度指标？
+- **KL 散度**：最常用，但对分布尾部敏感
+- **JS 散度**：对称且有界，适合比较
+- **Hellinger 距离**：有界 [0,1]，便于设置阈值
+
+### 为什么需要人工门控？
+根据可行性报告，递归训练导致的人格漂移是最高风险。HIGH/CRITICAL 级别的自动重置可能导致服务中断，需要人类确认。
+
+### 基座重置的冷却期？
+防止频繁重置导致的震荡。默认 60 秒冷却期，确保系统有时间稳定。

drift_guard/ab_testing.py

@@ -0,0 +1,283 @@
+"""
+MAREF A/B Testing Framework
+
+Phase 9: Provides controlled experimentation for policy changes.
+Allows comparing two policy configurations side-by-side before
+committing to a full deployment.
+
+Key features:
+- Parallel policy execution
+- Statistical significance testing
+- Automatic winner selection
+- Safe fallback to baseline
+"""
+
+from __future__ import annotations
+
+import copy
+import statistics
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from drift_guard.policy_sandbox import PolicySandbox
+from drift_guard.types import PipelineConfig
+
+
+@dataclass
+class ABTestMetrics:
+    """Metrics collected during A/B test."""
+
+    true_positives: int = 0
+    false_positives: int = 0
+    true_negatives: int = 0
+    false_negatives: int = 0
+    latency_ms: list[float] = field(default_factory=list)
+
+    @property
+    def precision(self) -> float:
+        if self.true_positives + self.false_positives == 0:
+            return 0.0
+        return self.true_positives / (self.true_positives + self.false_positives)
+
+    @property
+    def recall(self) -> float:
+        if self.true_positives + self.false_negatives == 0:
+            return 0.0
+        return self.true_positives / (self.true_positives + self.false_negatives)
+
+    @property
+    def f1_score(self) -> float:
+        if self.precision + self.recall == 0:
+            return 0.0
+        return 2 * (self.precision * self.recall) / (self.precision + self.recall)
+
+    @property
+    def mean_latency(self) -> float:
+        if not self.latency_ms:
+            return 0.0
+        return statistics.mean(self.latency_ms)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "true_positives": self.true_positives,
+            "false_positives": self.false_positives,
+            "true_negatives": self.true_negatives,
+            "false_negatives": self.false_negatives,
+            "precision": self.precision,
+            "recall": self.recall,
+            "f1_score": self.f1_score,
+            "mean_latency_ms": self.mean_latency,
+            "sample_size": len(self.latency_ms),
+        }
+
+
+@dataclass
+class ABTestResult:
+    """Result of an A/B test comparison."""
+
+    test_id: str
+    baseline_metrics: ABTestMetrics
+    variant_metrics: ABTestMetrics
+    winner: str  # "baseline", "variant", or "tie"
+    confidence: float  # 0.0 - 1.0
+    improvement_pct: dict[str, float] = field(default_factory=dict)
+    recommendation: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "test_id": self.test_id,
+            "baseline_metrics": self.baseline_metrics.to_dict(),
+            "variant_metrics": self.variant_metrics.to_dict(),
+            "winner": self.winner,
+            "confidence": self.confidence,
+            "improvement_pct": self.improvement_pct,
+            "recommendation": self.recommendation,
+        }
+
+
+class ABTestFramework:
+    """
+    A/B testing framework for policy changes.
+
+    Runs two policy configurations in parallel and compares
+    their performance on identical inputs.
+    """
+
+    def __init__(self, sandbox: PolicySandbox | None = None) -> None:
+        self._sandbox = sandbox or PolicySandbox()
+        self._active_tests: dict[str, dict[str, Any]] = {}
+
+    def create_test(
+        self,
+        test_id: str,
+        baseline_config: PipelineConfig,
+        variant_config: PipelineConfig,
+        min_samples: int = 100,
+    ) -> bool:
+        """
+        Create a new A/B test.
+
+        Args:
+            test_id: Unique identifier for this test
+            baseline_config: The current/baseline policy
+            variant_config: The new policy to test
+            min_samples: Minimum samples before declaring winner
+
+        Returns:
+            True if test was created successfully
+        """
+        if test_id in self._active_tests:
+            return False
+
+        self._active_tests[test_id] = {
+            "baseline_config": copy.deepcopy(baseline_config),
+            "variant_config": copy.deepcopy(variant_config),
+            "baseline_metrics": ABTestMetrics(),
+            "variant_metrics": ABTestMetrics(),
+            "min_samples": min_samples,
+            "started_at": time.time(),
+            "completed": False,
+        }
+        return True
+
+    def record_sample(
+        self,
+        test_id: str,
+        variant: str,  # "baseline" or "variant"
+        predicted_drift: bool,
+        actual_drift: bool,
+        latency_ms: float,
+    ) -> bool:
+        """
+        Record a sample for an active A/B test.
+
+        Args:
+            test_id: Test identifier
+            variant: Which variant this sample belongs to
+            predicted_drift: Whether drift was predicted
+            actual_drift: Whether drift actually occurred
+            latency_ms: Detection latency in milliseconds
+
+        Returns:
+            True if sample was recorded
+        """
+        if test_id not in self._active_tests:
+            return False
+
+        test = self._active_tests[test_id]
+        if test["completed"]:
+            return False
+
+        metrics = (
+            test["baseline_metrics"]
+            if variant == "baseline"
+            else test["variant_metrics"]
+        )
+
+        # Update confusion matrix
+        if predicted_drift and actual_drift:
+            metrics.true_positives += 1
+        elif predicted_drift and not actual_drift:
+            metrics.false_positives += 1
+        elif not predicted_drift and not actual_drift:
+            metrics.true_negatives += 1
+        else:
+            metrics.false_negatives += 1
+
+        metrics.latency_ms.append(latency_ms)
+        return True
+
+    def evaluate_test(self, test_id: str) -> ABTestResult | None:
+        """
+        Evaluate an A/B test and determine winner.
+
+        Args:
+            test_id: Test identifier
+
+        Returns:
+            ABTestResult if test is complete, None otherwise
+        """
+        if test_id not in self._active_tests:
+            return None
+
+        test = self._active_tests[test_id]
+        baseline = test["baseline_metrics"]
+        variant = test["variant_metrics"]
+
+        # Check if we have enough samples
+        total_samples = (
+            len(baseline.latency_ms) + len(variant.latency_ms)
+        )
+        if total_samples < test["min_samples"]:
+            return None
+
+        # Mark as completed
+        test["completed"] = True
+
+        # Calculate improvements
+        improvements = {}
+        if baseline.f1_score > 0:
+            improvements["f1_score"] = (
+                (variant.f1_score - baseline.f1_score) / baseline.f1_score * 100
+            )
+        if baseline.mean_latency > 0:
+            improvements["latency"] = (
+                (baseline.mean_latency - variant.mean_latency)
+                / baseline.mean_latency
+                * 100
+            )
+
+        # Determine winner based on F1 score (primary) and latency (secondary)
+        winner = "tie"
+        confidence = 0.5
+
+        f1_diff = variant.f1_score - baseline.f1_score
+        if abs(f1_diff) > 0.05:  # At least 5% difference in F1
+            if f1_diff > 0:
+                winner = "variant"
+                confidence = min(0.5 + abs(f1_diff), 0.95)
+            else:
+                winner = "baseline"
+                confidence = min(0.5 + abs(f1_diff), 0.95)
+
+        # Generate recommendation
+        if winner == "variant" and confidence > 0.7:
+            recommendation = (
+                f"Variant shows significant improvement "
+                f"({improvements.get('f1_score', 0):.1f}% F1, "
+                f"{improvements.get('latency', 0):.1f}% latency). Recommend deployment."
+            )
+        elif winner == "baseline":
+            recommendation = (
+                "Baseline performs better. Reject variant and investigate."
+            )
+        else:
+            recommendation = (
+                "No clear winner. Consider extending test or revising variant."
+            )
+
+        return ABTestResult(
+            test_id=test_id,
+            baseline_metrics=baseline,
+            variant_metrics=variant,
+            winner=winner,
+            confidence=confidence,
+            improvement_pct=improvements,
+            recommendation=recommendation,
+        )
+
+    def get_test_status(self, test_id: str) -> dict[str, Any] | None:
+        """Get current status of an A/B test."""
+        if test_id not in self._active_tests:
+            return None
+
+        test = self._active_tests[test_id]
+        return {
+            "test_id": test_id,
+            "completed": test["completed"],
+            "baseline_samples": len(test["baseline_metrics"].latency_ms),
+            "variant_samples": len(test["variant_metrics"].latency_ms),
+            "min_samples": test["min_samples"],
+            "elapsed_seconds": time.time() - test["started_at"],
+        }

drift_guard/adaptive_threshold.py

@@ -0,0 +1,245 @@
+"""
+MAREF DriftGuard Adaptive Threshold Module
+
+Phase 8: Implements self-adjusting thresholds based on historical
+drift detection performance. This enables the system to learn
+from its own detection history and optimize sensitivity.
+
+Key features:
+- False positive/negative tracking
+- Threshold auto-tuning with bounds
+- Performance metric collection
+- Safe rollback to baseline
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ThresholdPerformance:
+    """Performance metrics for a threshold configuration."""
+
+    true_positives: int = 0
+    false_positives: int = 0
+    true_negatives: int = 0
+    false_negatives: int = 0
+
+    @property
+    def precision(self) -> float:
+        """Precision = TP / (TP + FP)."""
+        if self.true_positives + self.false_positives == 0:
+            return 0.0
+        return self.true_positives / (self.true_positives + self.false_positives)
+
+    @property
+    def recall(self) -> float:
+        """Recall = TP / (TP + FN)."""
+        if self.true_positives + self.false_negatives == 0:
+            return 0.0
+        return self.true_positives / (self.true_positives + self.false_negatives)
+
+    @property
+    def f1_score(self) -> float:
+        """F1 = 2 * (precision * recall) / (precision + recall)."""
+        if self.precision + self.recall == 0:
+            return 0.0
+        return 2 * (self.precision * self.recall) / (self.precision + self.recall)
+
+    @property
+    def false_positive_rate(self) -> float:
+        """FPR = FP / (FP + TN)."""
+        if self.false_positives + self.true_negatives == 0:
+            return 0.0
+        return self.false_positives / (self.false_positives + self.true_negatives)
+
+    @property
+    def false_negative_rate(self) -> float:
+        """FNR = FN / (FN + TP)."""
+        if self.false_negatives + self.true_positives == 0:
+            return 0.0
+        return self.false_negatives / (self.false_negatives + self.true_positives)
+
+
+@dataclass
+class AdaptiveThresholdConfig:
+    """Configuration for adaptive threshold behavior."""
+
+    # Learning rate for threshold adjustments (0.0 - 1.0)
+    learning_rate: float = 0.1
+
+    # Target false positive rate (0.0 - 1.0)
+    target_fpr: float = 0.05
+
+    # Target false negative rate (0.0 - 1.0)
+    target_fnr: float = 0.02
+
+    # Minimum allowed threshold values
+    min_kl_warning: float = 0.01
+    min_kl_critical: float = 0.1
+    min_kl_max: float = 0.5
+
+    # Maximum allowed threshold values
+    max_kl_warning: float = 0.5
+    max_kl_critical: float = 2.0
+    max_kl_max: float = 5.0
+
+    # Window size for performance evaluation
+    evaluation_window: int = 100
+
+    # Enable/disable adaptive behavior
+    enabled: bool = True
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "learning_rate": self.learning_rate,
+            "target_fpr": self.target_fpr,
+            "target_fnr": self.target_fnr,
+            "min_kl_warning": self.min_kl_warning,
+            "min_kl_critical": self.min_kl_critical,
+            "min_kl_max": self.min_kl_max,
+            "max_kl_warning": self.max_kl_warning,
+            "max_kl_critical": self.max_kl_critical,
+            "max_kl_max": self.max_kl_max,
+            "evaluation_window": self.evaluation_window,
+            "enabled": self.enabled,
+        }
+
+
+class AdaptiveThresholdManager:
+    """
+    Manages adaptive threshold adjustment for drift detection.
+
+    Tracks detection outcomes and adjusts thresholds to optimize
+    the balance between sensitivity and specificity.
+    """
+
+    def __init__(self, config: AdaptiveThresholdConfig | None = None) -> None:
+        self._config = config or AdaptiveThresholdConfig()
+        self._performance = ThresholdPerformance()
+        self._history: list[tuple[float, bool, bool]] = []
+        # (threshold_used, was_alert, was_true_drift)
+
+    def record_outcome(
+        self,
+        threshold_used: float,
+        predicted_drift: bool,
+        actual_drift: bool,
+    ) -> None:
+        """
+        Record the outcome of a drift detection decision.
+
+        Args:
+            threshold_used: The threshold value that was applied
+            predicted_drift: Whether the system predicted drift
+            actual_drift: Whether there was actual drift (ground truth)
+        """
+        self._history.append((threshold_used, predicted_drift, actual_drift))
+
+        # Update performance metrics
+        if predicted_drift and actual_drift:
+            self._performance.true_positives += 1
+        elif predicted_drift and not actual_drift:
+            self._performance.false_positives += 1
+        elif not predicted_drift and not actual_drift:
+            self._performance.true_negatives += 1
+        else:  # not predicted_drift and actual_drift
+            self._performance.false_negatives += 1
+
+        # Trim history to evaluation window
+        if len(self._history) > self._config.evaluation_window:
+            self._history.pop(0)
+
+    def should_adjust(self) -> bool:
+        """Check if enough data exists to make an adjustment."""
+        return len(self._history) >= self._config.evaluation_window
+
+    def compute_adjustment(self, current_threshold: float) -> float:
+        """
+        Compute the recommended threshold adjustment.
+
+        Returns:
+            The delta to apply to the current threshold.
+            Positive = increase threshold (less sensitive)
+            Negative = decrease threshold (more sensitive)
+        """
+        if not self._config.enabled or not self.should_adjust():
+            return 0.0
+
+        fpr = self._performance.false_positive_rate
+        fnr = self._performance.false_negative_rate
+
+        adjustment = 0.0
+
+        # If FPR is too high, increase threshold (make it harder to trigger)
+        if fpr > self._config.target_fpr:
+            adjustment += self._config.learning_rate * (fpr - self._config.target_fpr)
+
+        # If FNR is too high, decrease threshold (make it easier to trigger)
+        if fnr > self._config.target_fnr:
+            adjustment -= self._config.learning_rate * (fnr - self._config.target_fnr)
+
+        return adjustment
+
+    def adjust_threshold(self, current_threshold: float, threshold_type: str) -> float:
+        """
+        Apply adaptive adjustment to a threshold with bounds checking.
+
+        Args:
+            current_threshold: Current threshold value
+            threshold_type: One of "warning", "critical", "max"
+
+        Returns:
+            The adjusted threshold value
+        """
+        adjustment = self.compute_adjustment(current_threshold)
+        new_threshold = current_threshold + adjustment
+
+        # Apply bounds based on threshold type
+        if threshold_type == "warning":
+            new_threshold = max(
+                self._config.min_kl_warning,
+                min(self._config.max_kl_warning, new_threshold),
+            )
+        elif threshold_type == "critical":
+            new_threshold = max(
+                self._config.min_kl_critical,
+                min(self._config.max_kl_critical, new_threshold),
+            )
+        elif threshold_type == "max":
+            new_threshold = max(
+                self._config.min_kl_max,
+                min(self._config.max_kl_max, new_threshold),
+            )
+
+        return new_threshold
+
+    def get_performance(self) -> ThresholdPerformance:
+        """Get current performance metrics."""
+        return self._performance
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get comprehensive statistics."""
+        return {
+            "config": self._config.to_dict(),
+            "performance": {
+                "true_positives": self._performance.true_positives,
+                "false_positives": self._performance.false_positives,
+                "true_negatives": self._performance.true_negatives,
+                "false_negatives": self._performance.false_negatives,
+                "precision": self._performance.precision,
+                "recall": self._performance.recall,
+                "f1_score": self._performance.f1_score,
+                "false_positive_rate": self._performance.false_positive_rate,
+                "false_negative_rate": self._performance.false_negative_rate,
+            },
+            "history_size": len(self._history),
+            "ready_to_adjust": self.should_adjust(),
+        }
+
+    def reset(self) -> None:
+        """Reset all performance tracking."""
+        self._performance = ThresholdPerformance()
+        self._history.clear()