feat: add clustering support across models and notebooks

.github/workflows/build-test.yaml

@@ -32,6 +32,11 @@ jobs:
   pytest:
     needs: react-build-test
     runs-on: ${{ matrix.os }}
+    # Without this a hung test holds the runner for GitHub's six hour default.
+    # The suite takes four to nine minutes depending on the platform, so thirty
+    # leaves plenty of headroom while turning a deadlock into a red job with a
+    # readable log instead of a silent afternoon of runner time.
+    timeout-minutes: 30
     strategy:
       fail-fast: false
       matrix:

DashAI/back/api/api_v1/schemas/converter_params.py

@@ -5,7 +5,7 @@
 
 class ConverterParams(BaseModel):
     order: int = 0
-    params: Dict[str, Union[str, int, float, bool, None]] = None
+    params: Dict[str, Any] = None
     scope: Dict[str, Union[List[int], List[Dict[str, Any]]]] = None
     target: Union[Dict[str, Any], None] = None
 

DashAI/back/converters/base_converter.py

@@ -101,6 +101,45 @@ def get_metadata(cls) -> Dict[str, Any]:
 
         return meta
 
+    def changes_row_count(self) -> bool:
+        """Indicate whether this converter changes the number of dataset rows.
+
+        Samplers (e.g. SMOTE, RandomUnderSampler) return True because they
+        add or remove rows. Most transformers return False.
+
+        Returns
+        -------
+        bool
+            True if the converter may add or remove rows, False otherwise.
+        """
+        return False
+
+    def get_report(self) -> Union[Dict[str, Any], None]:
+        """Return the converter report produced after execution, if any.
+
+        The report complements the transformed dataset with information that
+        helps downstream tools (explorers, visualisations) interpret what the
+        converter did during its pipeline step. Persisted to disk per converter
+        execution. Optional — converters that produce no supplementary
+        information return ``None``.
+
+        Returns
+        -------
+        Dict[str, Any] or None
+            JSON-serializable report dict, or ``None`` when the converter does
+            not produce one.
+        """
+        return None
+
+    def build_report(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """Wrap converter-specific data with the producer converter name.
+
+        Subclasses pass only information that is useful after the conversion
+        has finished. Configuration parameters are already persisted with the
+        converter DB row.
+        """
+        return {"converter": self.__class__.__name__, **data}
+
     @abstractmethod
     def get_output_type(self, column_name: str = None) -> DashAIDataType:
         """Return the DashAI data type produced by this converter for a given column.

DashAI/back/converters/category/clustering.py

@@ -0,0 +1,28 @@
+from typing import Final
+
+from DashAI.back.converters.base_converter import BaseConverter
+from DashAI.back.core.utils import MultilingualString
+from DashAI.back.static.icons import Icon
+
+
+class ClusteringConverter(BaseConverter):
+    """Base class for converters that assign clusters to dataset rows.
+
+    Clustering converters learn an unsupervised grouping from the selected
+    feature columns and typically enrich the dataset with a new categorical
+    column containing the cluster label assigned to each row.
+
+    Use these converters when you want to discover natural groupings in the
+    data or create new features based on similarity, without relying on any target
+    variable.
+    """
+
+    CATEGORY = MultilingualString(
+        en="Clustering",
+        es="Agrupamiento",
+        pt="Agrupamento",
+        de="Clustering",
+        zh="聚类",
+    )
+    ICON: Final[str] = Icon.Psychology.value
+    COLOR: Final[str] = "rgb(72, 149, 239)"