truthound 1.0.8__py3-none-any.whl

truthound/checkpoint/analytics/analyzers/base.py

@@ -0,0 +1,270 @@
+"""Base trend analyzer implementation.
+
+Provides abstract base class with common analysis functionality.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import Any
+
+from truthound.checkpoint.analytics.protocols import (
+    TrendAnalyzerProtocol,
+    TimeSeriesPoint,
+    TrendResult,
+    TrendDirection,
+    AnomalyResult,
+    AnomalyType,
+    ForecastResult,
+    AnalyzerError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class BaseTrendAnalyzer(ABC):
+    """Abstract base class for trend analyzers.
+
+    Provides common functionality including:
+    - Statistical calculations
+    - Linear regression
+    - Percentile computation
+
+    Subclasses must implement the analysis methods.
+    """
+
+    def __init__(
+        self,
+        name: str | None = None,
+        min_samples: int = 3,
+    ) -> None:
+        """Initialize analyzer.
+
+        Args:
+            name: Analyzer name.
+            min_samples: Minimum samples required for analysis.
+        """
+        self._name = name or self.__class__.__name__
+        self._min_samples = min_samples
+
+    @property
+    def name(self) -> str:
+        """Get analyzer name."""
+        return self._name
+
+    @abstractmethod
+    def analyze(self, points: list[TimeSeriesPoint]) -> TrendResult:
+        """Analyze trend in time series."""
+        pass
+
+    @abstractmethod
+    def detect_anomalies(
+        self,
+        points: list[TimeSeriesPoint],
+        threshold: float = 2.0,
+    ) -> list[AnomalyResult]:
+        """Detect anomalies in time series."""
+        pass
+
+    @abstractmethod
+    def forecast(
+        self,
+        points: list[TimeSeriesPoint],
+        periods: int,
+    ) -> ForecastResult:
+        """Forecast future values."""
+        pass
+
+    # Statistical helper methods
+
+    def _compute_mean(self, values: list[float]) -> float:
+        """Compute mean of values."""
+        if not values:
+            return 0.0
+        return sum(values) / len(values)
+
+    def _compute_std_dev(self, values: list[float], mean: float | None = None) -> float:
+        """Compute standard deviation."""
+        if len(values) < 2:
+            return 0.0
+
+        if mean is None:
+            mean = self._compute_mean(values)
+
+        variance = sum((v - mean) ** 2 for v in values) / len(values)
+        return math.sqrt(variance)
+
+    def _compute_z_score(self, value: float, mean: float, std_dev: float) -> float:
+        """Compute Z-score for a value."""
+        if std_dev == 0:
+            return 0.0
+        return (value - mean) / std_dev
+
+    def _compute_percentile(self, values: list[float], percentile: float) -> float:
+        """Compute percentile of values.
+
+        Args:
+            values: Values to analyze.
+            percentile: Percentile (0-100).
+
+        Returns:
+            Percentile value.
+        """
+        if not values:
+            return 0.0
+
+        sorted_values = sorted(values)
+        n = len(sorted_values)
+        k = (n - 1) * (percentile / 100)
+        f = math.floor(k)
+        c = math.ceil(k)
+
+        if f == c:
+            return sorted_values[int(k)]
+
+        return sorted_values[f] * (c - k) + sorted_values[c] * (k - f)
+
+    def _compute_percentiles(
+        self,
+        values: list[float],
+        percentiles: list[float] = [50, 90, 95, 99],
+    ) -> dict[str, float]:
+        """Compute multiple percentiles."""
+        return {
+            f"p{int(p)}": self._compute_percentile(values, p)
+            for p in percentiles
+        }
+
+    def _linear_regression(
+        self,
+        x_values: list[float],
+        y_values: list[float],
+    ) -> tuple[float, float, float]:
+        """Perform simple linear regression.
+
+        Args:
+            x_values: Independent variable values.
+            y_values: Dependent variable values.
+
+        Returns:
+            Tuple of (slope, intercept, r_squared).
+        """
+        n = len(x_values)
+        if n < 2:
+            return 0.0, 0.0, 0.0
+
+        x_mean = sum(x_values) / n
+        y_mean = sum(y_values) / n
+
+        # Calculate slope
+        numerator = sum((x - x_mean) * (y - y_mean) for x, y in zip(x_values, y_values))
+        denominator = sum((x - x_mean) ** 2 for x in x_values)
+
+        if denominator == 0:
+            return 0.0, y_mean, 0.0
+
+        slope = numerator / denominator
+        intercept = y_mean - slope * x_mean
+
+        # Calculate R-squared
+        y_pred = [slope * x + intercept for x in x_values]
+        ss_res = sum((y - yp) ** 2 for y, yp in zip(y_values, y_pred))
+        ss_tot = sum((y - y_mean) ** 2 for y in y_values)
+
+        r_squared = 1 - (ss_res / ss_tot) if ss_tot != 0 else 0.0
+
+        return slope, intercept, r_squared
+
+    def _points_to_xy(
+        self,
+        points: list[TimeSeriesPoint],
+    ) -> tuple[list[float], list[float]]:
+        """Convert points to x, y arrays for regression.
+
+        Uses timestamps as x values (seconds since first point).
+
+        Args:
+            points: Time series points.
+
+        Returns:
+            Tuple of (x_values, y_values).
+        """
+        if not points:
+            return [], []
+
+        sorted_points = sorted(points, key=lambda p: p.timestamp)
+        base_time = sorted_points[0].timestamp
+
+        x_values = [
+            (p.timestamp - base_time).total_seconds()
+            for p in sorted_points
+        ]
+        y_values = [p.value for p in sorted_points]
+
+        return x_values, y_values
+
+    def _determine_direction(
+        self,
+        slope: float,
+        std_dev: float,
+        threshold: float = 0.01,
+    ) -> TrendDirection:
+        """Determine trend direction from slope.
+
+        Args:
+            slope: Linear regression slope.
+            std_dev: Standard deviation of values.
+            threshold: Slope threshold relative to std_dev.
+
+        Returns:
+            Trend direction.
+        """
+        if std_dev == 0:
+            return TrendDirection.STABLE
+
+        # Normalize slope by standard deviation
+        normalized_slope = abs(slope) / std_dev if std_dev > 0 else 0
+
+        if normalized_slope < threshold:
+            return TrendDirection.STABLE
+        elif slope > 0:
+            return TrendDirection.INCREASING
+        else:
+            return TrendDirection.DECREASING
+
+    def _compute_change_percent(
+        self,
+        first_value: float,
+        last_value: float,
+    ) -> float:
+        """Compute percentage change between first and last value."""
+        if first_value == 0:
+            return 0.0 if last_value == 0 else float("inf")
+        return ((last_value - first_value) / abs(first_value)) * 100
+
+    def _compute_confidence(
+        self,
+        r_squared: float,
+        sample_count: int,
+        min_samples: int = 10,
+    ) -> float:
+        """Compute confidence score for trend analysis.
+
+        Args:
+            r_squared: R-squared value from regression.
+            sample_count: Number of samples.
+            min_samples: Minimum samples for full confidence.
+
+        Returns:
+            Confidence score (0.0 to 1.0).
+        """
+        # Penalize for too few samples
+        sample_factor = min(sample_count / min_samples, 1.0)
+
+        # Combine R-squared with sample factor
+        confidence = r_squared * sample_factor
+
+        return max(0.0, min(1.0, confidence))

truthound/checkpoint/analytics/analyzers/forecast.py

@@ -0,0 +1,421 @@
+"""Simple forecaster implementation.
+
+Provides basic time series forecasting using moving averages
+and exponential smoothing.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from datetime import datetime, timedelta
+from typing import Any
+
+from truthound.checkpoint.analytics.protocols import (
+    TimeSeriesPoint,
+    TrendResult,
+    TrendDirection,
+    AnomalyResult,
+    ForecastResult,
+    AnalyzerError,
+)
+from truthound.checkpoint.analytics.analyzers.base import BaseTrendAnalyzer
+
+logger = logging.getLogger(__name__)
+
+
+class SimpleForecaster(BaseTrendAnalyzer):
+    """Simple time series forecaster.
+
+    Supports multiple forecasting methods:
+    - Linear extrapolation
+    - Moving average
+    - Simple exponential smoothing
+    - Double exponential smoothing (Holt's method)
+
+    Example:
+        >>> forecaster = SimpleForecaster(method="exponential")
+        >>>
+        >>> # Forecast next 5 periods
+        >>> forecast = forecaster.forecast(points, periods=5)
+        >>> for p in forecast.predictions:
+        ...     print(f"{p.timestamp}: {p.value}")
+    """
+
+    METHODS = ["linear", "moving_avg", "exponential", "holt"]
+
+    def __init__(
+        self,
+        name: str = "simple_forecaster",
+        method: str = "exponential",
+        min_samples: int = 5,
+        alpha: float = 0.3,
+        beta: float = 0.1,
+        window_size: int = 5,
+    ) -> None:
+        """Initialize forecaster.
+
+        Args:
+            name: Forecaster name.
+            method: Forecasting method.
+            min_samples: Minimum samples required.
+            alpha: Smoothing parameter for exponential methods.
+            beta: Trend smoothing parameter for Holt's method.
+            window_size: Window size for moving average.
+        """
+        super().__init__(name=name, min_samples=min_samples)
+        self._method = method.lower()
+        self._alpha = alpha
+        self._beta = beta
+        self._window_size = window_size
+
+        if self._method not in self.METHODS:
+            raise ValueError(f"Unknown method: {method}. Valid methods: {self.METHODS}")
+
+    def analyze(self, points: list[TimeSeriesPoint]) -> TrendResult:
+        """Analyze trend using linear regression."""
+        if len(points) < self._min_samples:
+            return TrendResult(
+                direction=TrendDirection.STABLE,
+                slope=0.0,
+                confidence=0.0,
+                change_percent=0.0,
+                period_start=points[0].timestamp if points else datetime.now(),
+                period_end=points[-1].timestamp if points else datetime.now(),
+                sample_count=len(points),
+            )
+
+        sorted_points = sorted(points, key=lambda p: p.timestamp)
+        x_values, y_values = self._points_to_xy(sorted_points)
+        slope, intercept, r_squared = self._linear_regression(x_values, y_values)
+
+        mean = self._compute_mean(y_values)
+        std_dev = self._compute_std_dev(y_values, mean)
+        direction = self._determine_direction(slope, std_dev)
+        change_percent = self._compute_change_percent(y_values[0], y_values[-1])
+        confidence = self._compute_confidence(r_squared, len(points))
+
+        return TrendResult(
+            direction=direction,
+            slope=slope,
+            confidence=confidence,
+            change_percent=change_percent,
+            period_start=sorted_points[0].timestamp,
+            period_end=sorted_points[-1].timestamp,
+            r_squared=r_squared,
+            sample_count=len(points),
+        )
+
+    def detect_anomalies(
+        self,
+        points: list[TimeSeriesPoint],
+        threshold: float = 2.0,
+    ) -> list[AnomalyResult]:
+        """Detect anomalies based on forecast error."""
+        # Use one-step-ahead forecast errors for anomaly detection
+        if len(points) < self._min_samples + 1:
+            return []
+
+        sorted_points = sorted(points, key=lambda p: p.timestamp)
+        anomalies = []
+
+        # Compute forecast errors
+        errors = []
+        for i in range(self._min_samples, len(sorted_points)):
+            history = sorted_points[:i]
+            actual = sorted_points[i]
+
+            forecast = self.forecast(history, periods=1)
+            if forecast.predictions:
+                predicted = forecast.predictions[0].value
+                error = actual.value - predicted
+                errors.append((actual, predicted, error))
+
+        if not errors:
+            return []
+
+        # Compute error statistics
+        error_values = [e[2] for e in errors]
+        mean_error = self._compute_mean(error_values)
+        std_error = self._compute_std_dev(error_values, mean_error)
+
+        if std_error == 0:
+            return []
+
+        from truthound.checkpoint.analytics.protocols import AnomalyType
+
+        for actual, predicted, error in errors:
+            z_score = (error - mean_error) / std_error
+
+            if abs(z_score) > threshold:
+                anomaly_type = AnomalyType.SPIKE if z_score > 0 else AnomalyType.DROP
+                severity = min(abs(z_score) / (threshold * 2), 1.0)
+
+                anomalies.append(AnomalyResult(
+                    timestamp=actual.timestamp,
+                    anomaly_type=anomaly_type,
+                    value=actual.value,
+                    expected_value=predicted,
+                    deviation=z_score,
+                    severity=severity,
+                    labels=actual.labels,
+                ))
+
+        return anomalies
+
+    def forecast(
+        self,
+        points: list[TimeSeriesPoint],
+        periods: int,
+    ) -> ForecastResult:
+        """Generate forecast using configured method.
+
+        Args:
+            points: Historical time series points.
+            periods: Number of periods to forecast.
+
+        Returns:
+            Forecast result.
+        """
+        if len(points) < self._min_samples:
+            return ForecastResult(
+                predictions=[],
+                confidence_lower=[],
+                confidence_upper=[],
+                method=self._method,
+                horizon=periods,
+            )
+
+        if self._method == "linear":
+            return self._forecast_linear(points, periods)
+        elif self._method == "moving_avg":
+            return self._forecast_moving_avg(points, periods)
+        elif self._method == "exponential":
+            return self._forecast_exponential(points, periods)
+        elif self._method == "holt":
+            return self._forecast_holt(points, periods)
+        else:
+            return self._forecast_linear(points, periods)
+
+    def _forecast_linear(
+        self,
+        points: list[TimeSeriesPoint],
+        periods: int,
+    ) -> ForecastResult:
+        """Forecast using linear extrapolation."""
+        sorted_points = sorted(points, key=lambda p: p.timestamp)
+        x_values, y_values = self._points_to_xy(sorted_points)
+        slope, intercept, _ = self._linear_regression(x_values, y_values)
+
+        avg_interval = self._estimate_interval(sorted_points)
+        std_dev = self._compute_std_dev(y_values)
+
+        last_x = x_values[-1]
+        last_time = sorted_points[-1].timestamp
+
+        predictions, lower, upper = self._generate_predictions(
+            last_x, last_time, periods, avg_interval,
+            lambda x: slope * x + intercept,
+            std_dev,
+        )
+
+        return ForecastResult(
+            predictions=predictions,
+            confidence_lower=lower,
+            confidence_upper=upper,
+            method="linear",
+            horizon=periods,
+        )
+
+    def _forecast_moving_avg(
+        self,
+        points: list[TimeSeriesPoint],
+        periods: int,
+    ) -> ForecastResult:
+        """Forecast using simple moving average."""
+        sorted_points = sorted(points, key=lambda p: p.timestamp)
+        values = [p.value for p in sorted_points]
+
+        # Use last window_size values for forecast
+        window = values[-self._window_size:]
+        forecast_value = sum(window) / len(window)
+        std_dev = self._compute_std_dev(window)
+
+        avg_interval = self._estimate_interval(sorted_points)
+        last_time = sorted_points[-1].timestamp
+
+        predictions = []
+        lower = []
+        upper = []
+
+        for i in range(1, periods + 1):
+            future_time = last_time + timedelta(seconds=avg_interval * i)
+            interval = std_dev * 1.96
+
+            predictions.append(TimeSeriesPoint(
+                timestamp=future_time,
+                value=forecast_value,
+                metadata={"forecast": True, "method": "moving_avg"},
+            ))
+            lower.append(forecast_value - interval)
+            upper.append(forecast_value + interval)
+
+        return ForecastResult(
+            predictions=predictions,
+            confidence_lower=lower,
+            confidence_upper=upper,
+            method="moving_avg",
+            horizon=periods,
+        )
+
+    def _forecast_exponential(
+        self,
+        points: list[TimeSeriesPoint],
+        periods: int,
+    ) -> ForecastResult:
+        """Forecast using simple exponential smoothing."""
+        sorted_points = sorted(points, key=lambda p: p.timestamp)
+        values = [p.value for p in sorted_points]
+
+        # Apply exponential smoothing
+        level = values[0]
+        for value in values[1:]:
+            level = self._alpha * value + (1 - self._alpha) * level
+
+        # Estimate forecast error
+        errors = []
+        temp_level = values[0]
+        for value in values[1:]:
+            errors.append(value - temp_level)
+            temp_level = self._alpha * value + (1 - self._alpha) * temp_level
+
+        std_error = self._compute_std_dev(errors) if errors else 0
+
+        avg_interval = self._estimate_interval(sorted_points)
+        last_time = sorted_points[-1].timestamp
+
+        predictions = []
+        lower = []
+        upper = []
+
+        for i in range(1, periods + 1):
+            future_time = last_time + timedelta(seconds=avg_interval * i)
+            # Error grows with forecast horizon
+            interval = std_error * 1.96 * math.sqrt(i)
+
+            predictions.append(TimeSeriesPoint(
+                timestamp=future_time,
+                value=level,
+                metadata={"forecast": True, "method": "exponential"},
+            ))
+            lower.append(level - interval)
+            upper.append(level + interval)
+
+        return ForecastResult(
+            predictions=predictions,
+            confidence_lower=lower,
+            confidence_upper=upper,
+            method="exponential",
+            horizon=periods,
+        )
+
+    def _forecast_holt(
+        self,
+        points: list[TimeSeriesPoint],
+        periods: int,
+    ) -> ForecastResult:
+        """Forecast using Holt's linear method (double exponential smoothing)."""
+        sorted_points = sorted(points, key=lambda p: p.timestamp)
+        values = [p.value for p in sorted_points]
+
+        if len(values) < 2:
+            return self._forecast_exponential(points, periods)
+
+        # Initialize level and trend
+        level = values[0]
+        trend = values[1] - values[0]
+
+        # Apply double exponential smoothing
+        for value in values[1:]:
+            last_level = level
+            level = self._alpha * value + (1 - self._alpha) * (level + trend)
+            trend = self._beta * (level - last_level) + (1 - self._beta) * trend
+
+        # Estimate forecast error
+        errors = []
+        temp_level = values[0]
+        temp_trend = values[1] - values[0]
+        for i, value in enumerate(values[1:]):
+            forecast = temp_level + temp_trend
+            errors.append(value - forecast)
+            last_level = temp_level
+            temp_level = self._alpha * value + (1 - self._alpha) * (temp_level + temp_trend)
+            temp_trend = self._beta * (temp_level - last_level) + (1 - self._beta) * temp_trend
+
+        std_error = self._compute_std_dev(errors) if errors else 0
+
+        avg_interval = self._estimate_interval(sorted_points)
+        last_time = sorted_points[-1].timestamp
+
+        predictions = []
+        lower = []
+        upper = []
+
+        for i in range(1, periods + 1):
+            future_time = last_time + timedelta(seconds=avg_interval * i)
+            predicted_value = level + trend * i
+            interval = std_error * 1.96 * math.sqrt(i)
+
+            predictions.append(TimeSeriesPoint(
+                timestamp=future_time,
+                value=predicted_value,
+                metadata={"forecast": True, "method": "holt"},
+            ))
+            lower.append(predicted_value - interval)
+            upper.append(predicted_value + interval)
+
+        return ForecastResult(
+            predictions=predictions,
+            confidence_lower=lower,
+            confidence_upper=upper,
+            method="holt",
+            horizon=periods,
+        )
+
+    def _estimate_interval(self, points: list[TimeSeriesPoint]) -> float:
+        """Estimate average interval between points."""
+        if len(points) < 2:
+            return 3600.0  # Default 1 hour
+
+        total_time = (points[-1].timestamp - points[0].timestamp).total_seconds()
+        return total_time / (len(points) - 1)
+
+    def _generate_predictions(
+        self,
+        last_x: float,
+        last_time: datetime,
+        periods: int,
+        interval: float,
+        forecast_fn,
+        std_dev: float,
+    ) -> tuple[list[TimeSeriesPoint], list[float], list[float]]:
+        """Generate prediction points with confidence intervals."""
+        predictions = []
+        lower = []
+        upper = []
+
+        for i in range(1, periods + 1):
+            future_x = last_x + interval * i
+            future_time = last_time + timedelta(seconds=interval * i)
+            predicted = forecast_fn(future_x)
+            conf_interval = std_dev * 1.96 * (1 + 0.1 * i)
+
+            predictions.append(TimeSeriesPoint(
+                timestamp=future_time,
+                value=predicted,
+                metadata={"forecast": True},
+            ))
+            lower.append(predicted - conf_interval)
+            upper.append(predicted + conf_interval)
+
+        return predictions, lower, upper