refactor: make online entities generic over state and configuration types

Introduce generic type parameters for state and configuration across the
online detection module to improve type safety and enable better integration
with future visualization components.

Small changes in ShewhartControlChartConfiguration (add __repr__)

Author: Desiment

pysatl_cpd/_typing.py

@@ -9,11 +9,9 @@
 __license__ = "SPDX-License-Identifier: MIT"
 
 
-from typing import Any
-
 import numpy as np
 
-type NumPyNumber = np.floating[Any] | np.integer[Any]
+type NumPyNumber = np.float64
 """Type alias for NumPy numeric types."""
 
 type Number = NumPyNumber | int | float

pysatl_cpd/online/ionline_algorithm.py

@@ -7,12 +7,9 @@
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
-from typing import TypeVar
 
 from pysatl_cpd._typing import Number
 
-T = TypeVar("T")
-
 
 @dataclass(kw_only=True, frozen=True)
 class OnlineAlgorithmState:
@@ -51,7 +48,7 @@ class OnlineAlgorithmConfiguration:
     learning_period_size: int = 0
 
 
-class OnlineAlgorithm[T](ABC):
+class OnlineAlgorithm[T, ConfigurationT: OnlineAlgorithmConfiguration, StateT: OnlineAlgorithmState](ABC):
     """
     Abstract base class for online change-point detection algorithms.
 
@@ -103,7 +100,7 @@ def name(self) -> str:
 
     @property
     @abstractmethod
-    def configuration(self) -> OnlineAlgorithmConfiguration:
+    def configuration(self) -> ConfigurationT:
         """
         Configuration parameters of the algorithm.
 
@@ -115,7 +112,7 @@ def configuration(self) -> OnlineAlgorithmConfiguration:
         raise NotImplementedError
 
     @property
-    def state(self) -> OnlineAlgorithmState | None:
+    def state(self) -> StateT | None:
         """
         Current internal state snapshot of the algorithm.
 
@@ -147,6 +144,7 @@ def process(self, observation: T) -> Number:
         """
         raise NotImplementedError
 
+    @abstractmethod
     def reset(self) -> None:
         """
         Reset the algorithm to its initial state.

pysatl_cpd/online/online_cpd_solver.py

@@ -8,17 +8,14 @@
 
 import time
 from collections.abc import Iterator
-from typing import TypeVar
 
 from pysatl_cpd._typing import Number
 from pysatl_cpd.data_providers import DataProvider
-from pysatl_cpd.online.ionline_algorithm import OnlineAlgorithm
+from pysatl_cpd.online.ionline_algorithm import OnlineAlgorithm, OnlineAlgorithmConfiguration, OnlineAlgorithmState
 from pysatl_cpd.online.online_detection_trace import OnlineDetectionStepResult
 
-T = TypeVar("T")
 
-
-class OnlineCpdSolver[T]:
+class OnlineCpdSolver[T, ConfugrationT: OnlineAlgorithmConfiguration, StateT: OnlineAlgorithmState]:
     """
     Sequential executor for online change-point detection.
 
@@ -55,7 +52,7 @@ class OnlineCpdSolver[T]:
     def __init__(
         self,
         data_provider: DataProvider[T],
-        algorithm: OnlineAlgorithm[T],
+        algorithm: OnlineAlgorithm[T, ConfugrationT, StateT],
         threshold: float = float("nan"),
         skip_period: int = 0,
         max_runlength: int | None = None,
@@ -92,7 +89,7 @@ def __init__(
 
         self.__in_skip_period = False
 
-    def run(self) -> Iterator[OnlineDetectionStepResult]:
+    def run(self) -> Iterator[OnlineDetectionStepResult[StateT]]:
         """
         Execute the detection loop over all observations.
 

pysatl_cpd/online/online_detection_trace.py

@@ -17,7 +17,7 @@
 
 
 @dataclass(kw_only=True)
-class OnlineDetectionStepResult:
+class OnlineDetectionStepResult[StateT: OnlineAlgorithmState]:
     """
     Result of processing a single observation in online changepoint detection.
 
@@ -49,11 +49,11 @@ class OnlineDetectionStepResult:
     is_in_skip_period: bool = False
     detection_function: Number = float("nan")
     processing_time: Number = float("nan")
-    algorithm_state: OnlineAlgorithmState | None = None
+    algorithm_state: StateT | None = None
 
 
 @dataclass(kw_only=True)
-class OnlineDetectionTrace(DetectionTrace[Number]):
+class OnlineDetectionTrace[StateT: OnlineAlgorithmState](DetectionTrace[Number]):
     """
     Complete trace of online changepoint detection execution.
 
@@ -85,15 +85,15 @@ class OnlineDetectionTrace(DetectionTrace[Number]):
     threshold: Number | None = None
     processing_time: UnivariateNumericArray
     observation_scores: UnivariateNumericArray
-    algorithm_states: list[OnlineAlgorithmState | None]
+    algorithm_states: list[StateT | None]
     detected_changes: list[int]
     skipped_observation: list[int] = field(default_factory=list)
     forced_change_points: list[int] = field(default_factory=list)
 
     @classmethod
     def from_online_detection_steps(
-        cls, threshold: Number | None, steps: Sequence[OnlineDetectionStepResult]
-    ) -> "OnlineDetectionTrace":
+        cls, threshold: Number | None, steps: Sequence[OnlineDetectionStepResult[StateT]]
+    ) -> "OnlineDetectionTrace[StateT]":
         """
         Construct an OnlineDetectionTrace from a sequence of step results.
 

pysatl_cpd/online/shewhart_control_chart.py

@@ -102,7 +102,7 @@ def __repr__(self) -> str:
         return f"w = {self.window_size}"
 
 
-class ShewhartControlChart(OnlineAlgorithm[Number]):
+class ShewhartControlChart(OnlineAlgorithm[Number, ShewhartControlChartConfiguration, ShewhartControlChartState]):
     """
     Shewhart control chart with sliding-window statistic.
 

tests/online/test_ionline_algorithm.py

@@ -12,7 +12,7 @@
 )
 
 
-class ConcreteAlgorithm(OnlineAlgorithm[float]):
+class ConcreteAlgorithm(OnlineAlgorithm[float, OnlineAlgorithmConfiguration, OnlineAlgorithmState]):
     """Concrete implementation of OnlineAlgorithm for testing."""
 
     def __init__(

tests/online/test_online_cpd_solver.py

@@ -29,7 +29,7 @@ def __iter__(self) -> Iterator[T]:
         return iter(self._data)
 
 
-class MockOnlineAlgorithm(OnlineAlgorithm[T]):
+class MockOnlineAlgorithm(OnlineAlgorithm[T, OnlineAlgorithmConfiguration, OnlineAlgorithmState]):
     """Mock online algorithm for testing."""
 
     def __init__(

tests/online/test_online_detection_trace.py

@@ -24,7 +24,7 @@ class TestOnlineDetectionStepResult:
 
     def test_default_values(self) -> None:
         """Test default values for all fields."""
-        result = OnlineDetectionStepResult()
+        result = OnlineDetectionStepResult[OnlineAlgorithmState]()
 
         assert result.step_num == 0
         assert result.is_change_point is False
@@ -60,7 +60,7 @@ class TestOnlineDetectionTrace:
     """Test suite for OnlineDetectionTrace."""
 
     @pytest.fixture
-    def sample_steps(self) -> list[OnlineDetectionStepResult]:
+    def sample_steps(self) -> list[OnlineDetectionStepResult[MockAlgorithmState]]:
         """Create sample step results for testing."""
         state1 = MockAlgorithmState()
         state2 = MockAlgorithmState()
@@ -104,7 +104,9 @@ def sample_steps(self) -> list[OnlineDetectionStepResult]:
             ),
         ]
 
-    def test_from_online_detection_steps(self, sample_steps: list[OnlineDetectionStepResult]) -> None:
+    def test_from_online_detection_steps(
+        self, sample_steps: list[OnlineDetectionStepResult[MockAlgorithmState]]
+    ) -> None:
         """Test constructing OnlineDetectionTrace from step results."""
         trace = OnlineDetectionTrace.from_online_detection_steps(threshold=0.5, steps=sample_steps)
 
@@ -126,7 +128,7 @@ def test_from_online_detection_steps(self, sample_steps: list[OnlineDetectionSte
         assert trace.algorithm_states[3] is None
 
     def test_from_online_detection_steps_with_none_threshold(
-        self, sample_steps: list[OnlineDetectionStepResult]
+        self, sample_steps: list[OnlineDetectionStepResult[MockAlgorithmState]]
     ) -> None:
         """Test constructing trace with None threshold."""
         trace = OnlineDetectionTrace.from_online_detection_steps(threshold=None, steps=sample_steps)
@@ -136,7 +138,7 @@ def test_from_online_detection_steps_with_none_threshold(
 
     def test_from_online_detection_steps_empty(self) -> None:
         """Test constructing trace from empty step sequence."""
-        trace = OnlineDetectionTrace.from_online_detection_steps(threshold=0.5, steps=[])
+        trace = OnlineDetectionTrace[MockAlgorithmState].from_online_detection_steps(threshold=0.5, steps=[])
 
         assert trace.threshold == 0.5
         assert isinstance(trace.observation_scores, np.ndarray)
@@ -150,7 +152,7 @@ def test_from_online_detection_steps_empty(self) -> None:
 
     def test_from_online_detection_steps_no_detections(self) -> None:
         """Test constructing trace with no changepoints."""
-        steps: list[OnlineDetectionStepResult] = [
+        steps: list[OnlineDetectionStepResult[MockAlgorithmState]] = [
             OnlineDetectionStepResult(
                 step_num=i,
                 is_change_point=False,
@@ -208,7 +210,7 @@ def test_inherits_from_detection_trace(self) -> None:
             UnivariateNumericArray, np.array([0.001, 0.002, 0.003], dtype=np.float64)
         )
 
-        trace = OnlineDetectionTrace(
+        trace = OnlineDetectionTrace[MockAlgorithmState](
             threshold=0.5,
             observation_scores=observation_scores,
             processing_time=processing_times,
@@ -222,7 +224,7 @@ def test_inherits_from_detection_trace(self) -> None:
 
     def test_multiple_detection_types(self) -> None:
         """Test trace with multiple detection types overlapping."""
-        steps: list[OnlineDetectionStepResult] = [
+        steps: list[OnlineDetectionStepResult[MockAlgorithmState]] = [
             OnlineDetectionStepResult(
                 step_num=i,
                 is_change_point=(i == 2),
@@ -244,7 +246,7 @@ def test_multiple_detection_types(self) -> None:
 
     def test_ndarray_dtype_preservation(self) -> None:
         """Test that NumPy arrays preserve float64 dtype."""
-        steps: list[OnlineDetectionStepResult] = [
+        steps: list[OnlineDetectionStepResult[MockAlgorithmState]] = [
             OnlineDetectionStepResult(
                 step_num=i,
                 is_change_point=False,
@@ -271,15 +273,15 @@ def test_skipped_observation_default_mutable(self) -> None:
             UnivariateNumericArray, np.array([0.001, 0.002], dtype=np.float64)
         )
 
-        trace1 = OnlineDetectionTrace(
+        trace1 = OnlineDetectionTrace[MockAlgorithmState](
             threshold=0.5,
             observation_scores=observation_scores,
             processing_time=processing_times,
             algorithm_states=[],
             detected_changes=[1],
         )
 
-        trace2 = OnlineDetectionTrace(
+        trace2 = OnlineDetectionTrace[MockAlgorithmState](
             threshold=0.5,
             observation_scores=observation_scores,
             processing_time=processing_times,
@@ -302,15 +304,15 @@ def test_forced_change_points_default_mutable(self) -> None:
             UnivariateNumericArray, np.array([0.001, 0.002], dtype=np.float64)
         )
 
-        trace1 = OnlineDetectionTrace(
+        trace1 = OnlineDetectionTrace[MockAlgorithmState](
             threshold=0.5,
             observation_scores=observation_scores,
             processing_time=processing_times,
             algorithm_states=[],
             detected_changes=[1],
         )
 
-        trace2 = OnlineDetectionTrace(
+        trace2 = OnlineDetectionTrace[MockAlgorithmState](
             threshold=0.5,
             observation_scores=observation_scores,
             processing_time=processing_times,