merge: testing → main (reconcile 2-week divergence)

decnet/clustering/factory.py

@@ -0,0 +1,46 @@
+"""Clusterer factory.
+
+Returns the active :class:`~decnet.clustering.base.Clusterer` instance.
+Mirrors :mod:`decnet.bus.factory` and :mod:`decnet.web.db.factory`:
+callers obtain the clusterer via :func:`get_clusterer` rather than
+importing a concrete impl directly.
+
+Configuration knobs (env-overridable):
+
+* ``DECNET_CLUSTERER_TYPE`` — which implementation to use. Default
+  ``"connected_components"``. Unknown values raise :class:`ValueError`
+  so a typo in ``decnet.ini`` surfaces immediately rather than silently
+  falling back.
+
+The ``connected_components`` implementation is the v1 production
+clusterer. Other implementations (e.g. an HDBSCAN variant) can land
+here later without churning callers.
+"""
+from __future__ import annotations
+
+import os
+
+from decnet.clustering.base import Clusterer
+
+_KNOWN_CLUSTERERS = ("connected_components",)
+_DEFAULT_CLUSTERER = "connected_components"
+
+
+def get_clusterer() -> Clusterer:
+    """Return the configured clusterer instance.
+
+    Lazy-imports the concrete impl so the base module stays free of
+    implementation-specific dependencies.
+    """
+    name = os.environ.get("DECNET_CLUSTERER_TYPE", _DEFAULT_CLUSTERER).strip().lower()
+    if name == "connected_components":
+        from decnet.clustering.impl.connected_components import (
+            ConnectedComponentsClusterer,
+        )
+        return ConnectedComponentsClusterer()
+    raise ValueError(
+        f"Unknown clusterer: {name!r}. Known: {_KNOWN_CLUSTERERS}"
+    )
+
+
+__all__ = ["get_clusterer"]