crca 1.4.0__py3-none-any.whl

templates/drift_detection.py

@@ -0,0 +1,325 @@
+"""Drift detection using ruptures library for change-point detection.
+
+Provides advanced change-point detection beyond simple CUSUM,
+supporting multiple change points and per-metric detection.
+"""
+
+from typing import Any, Dict, List, Optional, Tuple
+import numpy as np
+from loguru import logger
+
+# Try to import ruptures
+try:
+    import ruptures as rpt
+    RUPTURES_AVAILABLE = True
+except ImportError:
+    RUPTURES_AVAILABLE = False
+    logger.warning("ruptures not available - drift detection will use CUSUM only")
+
+
+class DriftDetector:
+    """Change-point detection using ruptures library.
+    
+    Supports multiple change-point detection algorithms:
+    - Pelt: Optimal segmentation (penalized likelihood)
+    - Dynp: Dynamic programming (exact solution)
+    - Binseg: Binary segmentation (fast approximation)
+    """
+    
+    def __init__(
+        self,
+        algorithm: str = "pelt",
+        min_size: int = 2,
+        penalty: float = 10.0,
+        model: str = "rbf"
+    ):
+        """
+        Initialize drift detector.
+        
+        Args:
+            algorithm: Detection algorithm ("pelt", "dynp", "binseg")
+            min_size: Minimum segment size
+            penalty: Penalty parameter for Pelt
+            model: Change-point model ("rbf", "l2", "l1", "normal", "ar")
+        """
+        self.algorithm = algorithm
+        self.min_size = min_size
+        self.penalty = penalty
+        self.model = model
+        self.detectors: Dict[str, Any] = {}  # Per-metric detectors
+        self.change_points: Dict[str, List[int]] = {}  # Per-metric change points
+        self.confidence_scores: Dict[str, List[float]] = {}  # Per-metric confidence
+    
+    def detect_changepoints(
+        self,
+        metric_name: str,
+        metric_history: List[float],
+        min_history: int = 10
+    ) -> Tuple[List[int], List[float]]:
+        """
+        Detect change points in metric history.
+        
+        Args:
+            metric_name: Name of the metric
+            metric_history: Historical values of the metric
+            min_history: Minimum history length required
+            
+        Returns:
+            Tuple of (change_point_indices, confidence_scores)
+        """
+        if not RUPTURES_AVAILABLE:
+            return [], []
+        
+        if len(metric_history) < min_history:
+            return [], []
+        
+        try:
+            # Convert to numpy array
+            signal = np.array(metric_history).reshape(-1, 1)
+            
+            # Initialize detector if needed
+            if metric_name not in self.detectors:
+                if self.algorithm == "pelt":
+                    self.detectors[metric_name] = rpt.Pelt(model=self.model, min_size=self.min_size).fit(signal)
+                elif self.algorithm == "dynp":
+                    self.detectors[metric_name] = rpt.Dynp(model=self.model, min_size=self.min_size).fit(signal)
+                elif self.algorithm == "binseg":
+                    self.detectors[metric_name] = rpt.Binseg(model=self.model, min_size=self.min_size).fit(signal)
+                else:
+                    logger.warning(f"Unknown algorithm {self.algorithm}, using Pelt")
+                    self.detectors[metric_name] = rpt.Pelt(model=self.model, min_size=self.min_size).fit(signal)
+            else:
+                # Update detector with new data
+                self.detectors[metric_name].fit(signal)
+            
+            # Detect change points
+            detector = self.detectors[metric_name]
+            
+            if self.algorithm == "pelt":
+                change_points = detector.predict(pen=self.penalty)
+            elif self.algorithm == "dynp":
+                # For Dynp, need to specify number of change points
+                # Use penalty to estimate number
+                n_bkps = max(1, int(len(signal) / (self.penalty * 10)))
+                change_points = detector.predict(n_bkps=n_bkps)
+            elif self.algorithm == "binseg":
+                n_bkps = max(1, int(len(signal) / (self.penalty * 10)))
+                change_points = detector.predict(n_bkps=n_bkps)
+            else:
+                change_points = []
+            
+            # Remove last point (end of signal) if present
+            if change_points and change_points[-1] == len(signal):
+                change_points = change_points[:-1]
+            
+            # Compute confidence scores (simplified: based on segment variance differences)
+            confidence_scores = []
+            for cp in change_points:
+                if cp > 0 and cp < len(signal):
+                    # Compare variance before and after change point
+                    before = signal[:cp]
+                    after = signal[cp:]
+                    var_before = np.var(before) if len(before) > 1 else 0.0
+                    var_after = np.var(after) if len(after) > 1 else 0.0
+                    # Confidence based on variance difference
+                    confidence = min(1.0, abs(var_after - var_before) / (np.var(signal) + 1e-6))
+                    confidence_scores.append(confidence)
+                else:
+                    confidence_scores.append(0.0)
+            
+            # Store results
+            self.change_points[metric_name] = change_points
+            self.confidence_scores[metric_name] = confidence_scores
+            
+            return change_points, confidence_scores
+            
+        except Exception as e:
+            logger.error(f"Change-point detection failed for {metric_name}: {e}")
+            return [], []
+    
+    def characterize_segment(
+        self,
+        metric_name: str,
+        metric_history: List[float],
+        change_points: List[int]
+    ) -> List[Dict[str, Any]]:
+        """
+        Characterize segments between change points.
+        
+        Args:
+            metric_name: Name of the metric
+            metric_history: Historical values
+            change_points: List of change point indices
+            
+        Returns:
+            List of segment characterizations
+        """
+        if not change_points:
+            return []
+        
+        segments = []
+        signal = np.array(metric_history)
+        
+        prev_cp = 0
+        for cp in change_points + [len(signal)]:
+            segment = signal[prev_cp:cp]
+            if len(segment) > 0:
+                trend_val = float(np.polyfit(range(len(segment)), segment, 1)[0]) if len(segment) > 1 else 0.0
+                segments.append({
+                    "start": prev_cp,
+                    "end": cp,
+                    "mean": float(np.mean(segment)),
+                    "std": float(np.std(segment)),
+                    "trend": trend_val,
+                    "length": len(segment)
+                })
+            prev_cp = cp
+        
+        return segments
+    
+    def detect_drift(
+        self,
+        metric_name: str,
+        metric_history: List[float],
+        threshold: float = 0.7
+    ) -> Tuple[bool, Optional[Dict[str, Any]]]:
+        """
+        Detect if drift has occurred in a metric.
+        
+        Args:
+            metric_name: Name of the metric
+            metric_history: Historical values
+            threshold: Confidence threshold for drift detection
+            
+        Returns:
+            Tuple of (drift_detected, drift_info)
+        """
+        change_points, confidence_scores = self.detect_changepoints(metric_name, metric_history)
+        
+        if not change_points:
+            return False, None
+        
+        # Check if most recent change point has high confidence
+        if confidence_scores:
+            max_confidence = max(confidence_scores)
+            if max_confidence >= threshold:
+                # Get most recent change point
+                recent_cp = change_points[-1]
+                segments = self.characterize_segment(metric_name, metric_history, change_points)
+                
+                drift_info = {
+                    "change_point": recent_cp,
+                    "confidence": max_confidence,
+                    "segments": segments,
+                    "type": self._classify_drift_type(segments) if segments else "unknown"
+                }
+                
+                return True, drift_info
+        
+        return False, None
+    
+    def _classify_drift_type(self, segments: List[Dict[str, Any]]) -> str:
+        """Classify type of drift (mean shift, variance change, trend change)."""
+        if len(segments) < 2:
+            return "unknown"
+        
+        # Compare last two segments
+        last_seg = segments[-1]
+        prev_seg = segments[-2]
+        
+        mean_diff = abs(last_seg["mean"] - prev_seg["mean"])
+        std_diff = abs(last_seg["std"] - prev_seg["std"])
+        trend_diff = abs(last_seg["trend"] - prev_seg["trend"])
+        
+        if mean_diff > std_diff and mean_diff > trend_diff:
+            return "mean_shift"
+        elif std_diff > mean_diff and std_diff > trend_diff:
+            return "variance_change"
+        elif trend_diff > mean_diff and trend_diff > std_diff:
+            return "trend_change"
+        else:
+            return "mixed"
+
+
+class HybridDriftDetector:
+    """Hybrid drift detector combining ruptures and CUSUM.
+    
+    Uses ruptures for change-point detection and CUSUM for continuous monitoring.
+    """
+    
+    def __init__(
+        self,
+        use_ruptures: bool = True,
+        cusum_k: float = 0.5,
+        cusum_h: float = 5.0,
+        ruptures_penalty: float = 10.0
+    ):
+        """
+        Initialize hybrid detector.
+        
+        Args:
+            use_ruptures: Whether to use ruptures for detection
+            cusum_k: CUSUM threshold parameter
+            cusum_h: CUSUM alarm threshold
+            ruptures_penalty: Penalty for ruptures algorithm
+        """
+        self.use_ruptures = use_ruptures and RUPTURES_AVAILABLE
+        self.cusum_k = cusum_k
+        self.cusum_h = cusum_h
+        self.cusum_stat = 0.0
+        
+        if self.use_ruptures:
+            self.ruptures_detector = DriftDetector(penalty=ruptures_penalty)
+        else:
+            self.ruptures_detector = None
+    
+    def update(
+        self,
+        metric_name: str,
+        x_t: float,
+        x_pred: float,
+        metric_history: List[float]
+    ) -> Tuple[bool, Optional[Dict[str, Any]]]:
+        """
+        Update drift detection with new observation.
+        
+        Args:
+            metric_name: Name of the metric
+            x_t: Actual value
+            x_pred: Predicted value
+            metric_history: Historical values
+            
+        Returns:
+            Tuple of (drift_detected, drift_info)
+        """
+        # CUSUM update
+        residual = abs(x_t - x_pred)
+        self.cusum_stat = max(0.0, self.cusum_stat + residual - self.cusum_k)
+        
+        cusum_alarm = self.cusum_stat > self.cusum_h
+        
+        # Ruptures detection (if enabled and enough history)
+        ruptures_drift = False
+        ruptures_info = None
+        
+        if self.use_ruptures and len(metric_history) >= 10:
+            ruptures_drift, ruptures_info = self.ruptures_detector.detect_drift(
+                metric_name, metric_history, threshold=0.7
+            )
+        
+        # Combine results
+        if ruptures_drift or cusum_alarm:
+            drift_info = {
+                "cusum_stat": self.cusum_stat,
+                "cusum_alarm": cusum_alarm,
+                "ruptures_drift": ruptures_drift,
+                "ruptures_info": ruptures_info
+            }
+            return True, drift_info
+        
+        return False, None
+    
+    def reset(self) -> None:
+        """Reset CUSUM statistic."""
+        self.cusum_stat = 0.0
+

templates/examples/causal_agent_template.py

@@ -0,0 +1,309 @@
+"""
+Example: Causal Agent Template
+
+This demonstrates how to create a causal reasoning agent using the template framework.
+This is a simplified example showing the pattern - the full CRCA.py can be refactored
+to use this pattern.
+"""
+
+from typing import Dict, Any, List, Tuple, Optional, Union
+from enum import Enum
+from templates.base_specialized_agent import BaseSpecializedAgent
+from templates.graph_management import GraphManager
+from templates.prediction_framework import PredictionFramework, CounterfactualScenario
+from templates.statistical_methods import StatisticalMethods
+from templates.llm_integration import LLMIntegration, create_default_schema
+
+
+class CausalRelationType(Enum):
+    """Types of causal relationships."""
+    DIRECT = "direct"
+    INDIRECT = "indirect"
+    CONFOUNDING = "confounding"
+    MEDIATING = "mediating"
+    MODERATING = "moderating"
+
+
+class CausalAgentTemplate(BaseSpecializedAgent):
+    """
+    Example causal reasoning agent using the template framework.
+    
+    This demonstrates the pattern for creating specialized agents:
+    1. Inherit from BaseSpecializedAgent
+    2. Use composition with extracted modules
+    3. Implement domain-specific methods
+    """
+
+    def __init__(
+        self,
+        variables: Optional[List[str]] = None,
+        causal_edges: Optional[List[Tuple[str, str]]] = None,
+        max_loops: Optional[Union[int, str]] = 3,
+        agent_name: str = "causal-agent",
+        agent_description: str = "Causal Reasoning Agent",
+        model_name: str = "gpt-4o",
+        use_nonlinear: bool = True,
+        **kwargs,
+    ):
+        """
+        Initialize the causal agent.
+        
+        Args:
+            variables: List of variable names
+            causal_edges: List of (source, target) edge tuples
+            max_loops: Maximum reasoning loops
+            agent_name: Agent identifier
+            agent_description: Agent description
+            model_name: LLM model name
+            use_nonlinear: Whether to use nonlinear prediction
+            **kwargs: Additional arguments
+        """
+        # Initialize base class
+        super().__init__(
+            max_loops=max_loops,
+            agent_name=agent_name,
+            agent_description=agent_description,
+            model_name=model_name,
+            **kwargs,
+        )
+
+        # Initialize graph manager
+        self.graph_manager = GraphManager(graph_type="causal")
+        
+        # Initialize prediction framework
+        self.prediction_framework = PredictionFramework(
+            graph_manager=self.graph_manager,
+            use_nonlinear=use_nonlinear,
+        )
+        
+        # Initialize statistical methods
+        self.statistical_methods = StatisticalMethods(
+            graph_manager=self.graph_manager,
+            prediction_framework=self.prediction_framework,
+            standardization_stats=self.prediction_framework.standardization_stats,
+        )
+        
+        # Initialize LLM integration
+        self.llm_integration = LLMIntegration(
+            agent=self,
+            max_loops=self.domain_max_loops if isinstance(self.domain_max_loops, int) else 3,
+        )
+        
+        # Add variables and edges
+        if variables:
+            self.graph_manager.add_nodes_from(variables)
+        
+        if causal_edges:
+            for source, target in causal_edges:
+                self.add_causal_relationship(source, target)
+
+    def _get_domain_schema(self) -> Optional[Dict[str, Any]]:
+        """Return the causal analysis schema."""
+        return create_default_schema(
+            function_name="generate_causal_analysis",
+            description="Generates structured causal reasoning and counterfactual analysis",
+            properties={
+                "causal_analysis": {
+                    "type": "string",
+                    "description": "Analysis of causal relationships and mechanisms"
+                },
+                "intervention_planning": {
+                    "type": "string",
+                    "description": "Planned interventions to test causal hypotheses"
+                },
+                "counterfactual_scenarios": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "scenario_name": {"type": "string"},
+                            "interventions": {"type": "object"},
+                            "expected_outcomes": {"type": "object"},
+                            "reasoning": {"type": "string"}
+                        }
+                    },
+                    "description": "Multiple counterfactual scenarios to explore"
+                },
+                "causal_strength_assessment": {
+                    "type": "string",
+                    "description": "Assessment of causal relationship strengths and confounders"
+                },
+                "optimal_solution": {
+                    "type": "string",
+                    "description": "Recommended optimal solution based on causal analysis"
+                }
+            },
+            required=[
+                "causal_analysis",
+                "intervention_planning",
+                "counterfactual_scenarios",
+                "causal_strength_assessment",
+                "optimal_solution"
+            ]
+        )
+
+    def _build_domain_prompt(self, task: str) -> str:
+        """Build a causal reasoning prompt."""
+        return (
+            f"You are a Causal Reasoning with Counterfactual Analysis (CR-CA) agent.\n"
+            f"Problem: {task}\n"
+            f"Current causal graph has {len(self.graph_manager.get_nodes())} variables and "
+            f"{len(self.graph_manager.get_edges())} relationships.\n"
+        )
+
+    def _domain_specific_setup(self) -> None:
+        """Set up domain-specific attributes."""
+        # Causal-specific setup can go here
+        pass
+
+    def add_causal_relationship(
+        self,
+        source: str,
+        target: str,
+        strength: float = 1.0,
+        relation_type: CausalRelationType = CausalRelationType.DIRECT,
+        confidence: float = 1.0
+    ) -> None:
+        """Add a causal relationship."""
+        self.graph_manager.add_relationship(
+            source=source,
+            target=target,
+            strength=strength,
+            relation_type=relation_type,
+            confidence=confidence,
+        )
+
+    def predict_outcomes(
+        self,
+        factual_state: Dict[str, float],
+        interventions: Dict[str, float]
+    ) -> Dict[str, float]:
+        """Predict outcomes given state and interventions."""
+        return self.prediction_framework.predict_outcomes(factual_state, interventions)
+
+    def generate_counterfactual_scenarios(
+        self,
+        factual_state: Dict[str, float],
+        target_variables: List[str],
+        max_scenarios: int = 5
+    ) -> List[CounterfactualScenario]:
+        """Generate counterfactual scenarios."""
+        return self.prediction_framework.generate_counterfactual_scenarios(
+            factual_state, target_variables, max_scenarios
+        )
+
+    def run(
+        self,
+        task: Optional[Union[str, Any]] = None,
+        initial_state: Optional[Any] = None,
+        target_variables: Optional[List[str]] = None,
+        max_steps: Union[int, str] = 1,
+        **kwargs,
+    ) -> Dict[str, Any]:
+        """
+        Run the agent with either LLM analysis or state evolution.
+        
+        Args:
+            task: Task string for LLM analysis, or state dict
+            initial_state: Initial state dictionary
+            target_variables: Target variables for counterfactuals
+            max_steps: Maximum evolution steps
+            **kwargs: Additional arguments
+            
+        Returns:
+            Dictionary with results
+        """
+        # LLM-based analysis
+        if task is not None and isinstance(task, str) and initial_state is None and not task.strip().startswith('{'):
+            return self.llm_integration.run_llm_domain_analysis(
+                task,
+                build_prompt_fn=self._build_domain_prompt,
+                post_process_fn=self._post_process_llm_results,
+            )
+
+        # State evolution
+        if task is not None and initial_state is None:
+            initial_state = task
+
+        if not isinstance(initial_state, dict):
+            try:
+                import json
+                parsed = json.loads(initial_state)
+                if isinstance(parsed, dict):
+                    initial_state = parsed
+                else:
+                    return {"error": "initial_state JSON must decode to a dict"}
+            except Exception:
+                return {"error": "initial_state must be a dict or JSON-encoded dict"}
+
+        if target_variables is None:
+            target_variables = self.graph_manager.get_nodes()
+
+        def _resolve_max_steps(value: Union[int, str]) -> int:
+            if isinstance(value, str) and value == "auto":
+                return max(1, len(self.graph_manager.get_nodes()))
+            try:
+                return int(value)
+            except Exception:
+                return max(1, len(self.graph_manager.get_nodes()))
+
+        effective_steps = _resolve_max_steps(max_steps)
+        current_state = initial_state.copy()
+        for step in range(effective_steps):
+            current_state = self.prediction_framework.predict_outcomes(current_state, {})
+
+        self.prediction_framework.ensure_standardization_stats(current_state)
+        counterfactual_scenarios = self.generate_counterfactual_scenarios(
+            current_state,
+            target_variables,
+            max_scenarios=5
+        )
+
+        return {
+            "initial_state": initial_state,
+            "evolved_state": current_state,
+            "counterfactual_scenarios": counterfactual_scenarios,
+            "graph_info": {
+                "nodes": self.graph_manager.get_nodes(),
+                "edges": self.graph_manager.get_edges(),
+                "is_dag": self.graph_manager.is_dag()
+            },
+            "steps": effective_steps
+        }
+
+    def _post_process_llm_results(self, results: Dict[str, Any]) -> Dict[str, Any]:
+        """Post-process LLM analysis results."""
+        default_state = {var: 0.0 for var in self.graph_manager.get_nodes()}
+        self.prediction_framework.ensure_standardization_stats(default_state)
+        counterfactual_scenarios = self.generate_counterfactual_scenarios(
+            default_state,
+            self.graph_manager.get_nodes()[:5],
+            max_scenarios=5
+        )
+        results['counterfactual_scenarios'] = counterfactual_scenarios
+        results['graph_info'] = {
+            'nodes': self.graph_manager.get_nodes(),
+            'edges': self.graph_manager.get_edges(),
+            'is_dag': self.graph_manager.is_dag()
+        }
+        return results
+
+    # Convenience methods that delegate to modules
+    def get_nodes(self) -> List[str]:
+        """Get all nodes."""
+        return self.graph_manager.get_nodes()
+
+    def get_edges(self) -> List[Tuple[str, str]]:
+        """Get all edges."""
+        return self.graph_manager.get_edges()
+
+    def is_dag(self) -> bool:
+        """Check if graph is a DAG."""
+        return self.graph_manager.is_dag()
+
+    def fit_from_dataframe(self, df: Any, variables: List[str], **kwargs) -> None:
+        """Fit model from dataframe."""
+        self.statistical_methods.fit_from_dataframe(df, variables, **kwargs)
+        # Update prediction framework stats
+        self.prediction_framework.standardization_stats = self.statistical_methods.standardization_stats
+