ref(detectors): Add abstract-ish base class for DetectorHandler

src/sentry/grouping/grouptype.py

@@ -1,24 +1,25 @@
 from dataclasses import dataclass
-from typing import TypeVar
 
 from sentry.issues.grouptype import GroupCategory, GroupType
 from sentry.models.group import DEFAULT_TYPE_ID
 from sentry.types.group import PriorityLevel
 from sentry.workflow_engine.endpoints.validators.error_detector import ErrorDetectorValidator
-from sentry.workflow_engine.handlers.detector.base import (
-    DetectorHandler,
-    GroupedDetectorEvaluationResult,
-)
+from sentry.workflow_engine.handlers.detector.base import DetectorHandler
 from sentry.workflow_engine.models.data_source import DataPacket
-from sentry.workflow_engine.types import DetectorSettings
+from sentry.workflow_engine.types import (
+    DetectorEvaluationResult,
+    DetectorGroupKey,
+    DetectorSettings,
+)
 
-T = TypeVar("T")
 
+class ErrorDetectorHandler(DetectorHandler[object]):
+    """Placeholder handler for error group types."""
 
-class ErrorDetectorHandler(DetectorHandler):
-    def evaluate_impl(self, data_packet: DataPacket[T]) -> GroupedDetectorEvaluationResult:
-        # placeholder
-        return GroupedDetectorEvaluationResult(result={}, tainted=False)
+    def evaluate(
+        self, data_packet: DataPacket[object]
+    ) -> dict[DetectorGroupKey, DetectorEvaluationResult]:
+        return {}
 
 
 @dataclass(frozen=True)

src/sentry/workflow_engine/handlers/detector/__init__.py

@@ -1,4 +1,5 @@
 __all__ = [
+    "BaseDetectorHandler",
     "DataPacketEvaluationType",
     "DataPacketType",
     "DetectorHandler",
@@ -9,6 +10,7 @@
 ]
 
 from .base import (
+    BaseDetectorHandler,
     DataPacketEvaluationType,
     DataPacketType,
     DetectorHandler,

src/sentry/workflow_engine/handlers/detector/base.py

@@ -86,11 +86,37 @@ class GroupedDetectorEvaluationResult:
     tainted: bool
 
 
-# TODO - @saponifi3d - Change this class to be a pure ABC and remove the `__init__` method.
-# TODO - @saponifi3d - Once the change is made, we should introduce a `BaseDetector` class to evaluate simple cases
-class DetectorHandler(abc.ABC, Generic[DataPacketType, DataPacketEvaluationType]):
+class DetectorHandler(abc.ABC, Generic[DataPacketType]):
+    """
+    Abstract base class defining the public interface for detector handlers.
+    """
+
     def __init__(self, detector: Detector):
         self.detector = detector
+
+    @abc.abstractmethod
+    def evaluate(
+        self, data_packet: DataPacket[DataPacketType]
+    ) -> dict[DetectorGroupKey, DetectorEvaluationResult]:
+        pass
+
+
+class BaseDetectorHandler(
+    DetectorHandler[DataPacketType],
+    Generic[DataPacketType, DataPacketEvaluationType],
+):
+    """
+    Base implementation class providing shared infrastructure for detector handlers.
+    Includes metrics tracking, condition group loading, and defines abstract methods
+    that concrete handlers must implement.
+
+    DataPacketType is what we've embedded within the data packet.
+    DataPacketEvaluationType is the type of the value to be extracted from the data packet and
+    used to evaluate the conditions on the detector.
+    """
+
+    def __init__(self, detector: Detector):
+        super().__init__(detector)
         if detector.workflow_condition_group_id is not None:
             try:
                 # Check if workflow_condition_group is already prefetched

src/sentry/workflow_engine/handlers/detector/stateful.py

@@ -2,7 +2,7 @@
 import dataclasses
 import logging
 from datetime import timedelta
-from typing import Any, Generic, cast
+from typing import Any, cast
 from uuid import uuid4
 
 from django.conf import settings
@@ -16,9 +16,9 @@
 from sentry.models.group import GroupStatus
 from sentry.utils import metrics, redis
 from sentry.workflow_engine.handlers.detector.base import (
+    BaseDetectorHandler,
     DataPacketEvaluationType,
     DataPacketType,
-    DetectorHandler,
     DetectorOccurrence,
     EventData,
     GroupedDetectorEvaluationResult,
@@ -309,8 +309,7 @@ def get_state_data(
 
 
 class StatefulDetectorHandler(
-    Generic[DataPacketType, DataPacketEvaluationType],
-    DetectorHandler[DataPacketType, DataPacketEvaluationType],
+    BaseDetectorHandler[DataPacketType, DataPacketEvaluationType],
     abc.ABC,
 ):
     """

src/sentry/workflow_engine/models/detector.py

@@ -144,7 +144,7 @@ def group_type(self) -> builtins.type[GroupType]:
         return group_type
 
     @property
-    def detector_handler(self) -> DetectorHandler[Any, Any] | None:
+    def detector_handler(self) -> DetectorHandler[Any] | None:
         group_type = self.group_type
 
         if self.settings.handler is None:

src/sentry/workflow_engine/types.py

@@ -395,7 +395,7 @@ class SnubaQueryDataSourceType(TypedDict):
 
 @dataclass(frozen=True)
 class DetectorSettings:
-    handler: type[DetectorHandler[Any, Any]] | None = None
+    handler: type[DetectorHandler[Any]] | None = None
     validator: type[BaseDetectorTypeValidator] | None = None
     config_schema: dict[str, Any] = field(default_factory=dict)
     filter: Q | None = None

tests/sentry/workflow_engine/endpoints/test_organization_detector_types.py

@@ -14,7 +14,7 @@
 from sentry.testutils.silo import region_silo_test
 from sentry.uptime.grouptype import UptimeDomainCheckFailure
 from sentry.workflow_engine.handlers.detector import (
-    DetectorHandler,
+    BaseDetectorHandler,
     DetectorOccurrence,
     GroupedDetectorEvaluationResult,
 )
@@ -42,7 +42,7 @@ def setUp(self) -> None:
         )
         self.registry_patcher.start()
 
-        class MockDetectorHandler(DetectorHandler[dict[Never, Never], bool]):
+        class MockDetectorHandler(BaseDetectorHandler[dict[Never, Never], bool]):
             def evaluate_impl(
                 self, data_packet: DataPacket[dict[Never, Never]]
             ) -> GroupedDetectorEvaluationResult:

tests/sentry/workflow_engine/handlers/detector/test_base.py

@@ -7,6 +7,7 @@
 from sentry.testutils.abstract import Abstract
 from sentry.types.group import PriorityLevel
 from sentry.workflow_engine.handlers.detector import (
+    BaseDetectorHandler,
     DataPacketEvaluationType,
     DetectorHandler,
     DetectorOccurrence,
@@ -27,7 +28,7 @@
 
 
 def build_mock_occurrence_and_event(
-    handler: DetectorHandler[Any, Any],
+    handler: DetectorHandler[Any],
     value: DataPacketEvaluationType,
     priority: PriorityLevel,
 ) -> tuple[DetectorOccurrence, dict[str, Any]]:
@@ -99,7 +100,7 @@ class NoHandlerGroupType(GroupType):
             category = GroupCategory.METRIC_ALERT.value
             category_v2 = GroupCategory.METRIC_ALERT.value
 
-        class MockDetectorHandler(DetectorHandler[dict[str, Any], int]):
+        class MockDetectorHandler(BaseDetectorHandler[dict[str, Any], int]):
             def evaluate_impl(
                 self, data_packet: DataPacket[dict[str, Any]]
             ) -> GroupedDetectorEvaluationResult:
@@ -123,7 +124,7 @@ def create_occurrence(
             def extract_dedupe_value(self, data_packet: DataPacket[dict[str, Any]]) -> int:
                 return data_packet.packet.get("dedupe", 0)
 
-        class MockDetectorWithUpdateHandler(DetectorHandler[dict[str, Any], int]):
+        class MockDetectorWithUpdateHandler(BaseDetectorHandler[dict[str, Any], int]):
             def evaluate_impl(
                 self, data_packet: DataPacket[dict[str, Any]]
             ) -> GroupedDetectorEvaluationResult: