[NOTICKET] feat(cluster): name example members per cluster

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/tools/analytics/cluster.py

@@ -47,6 +47,9 @@ _RANDOM_STATE = 42
 _WEAK_SILHOUETTE = 0.25
 # Chart column name (internal; never collides with user data).
 _CLUSTER_COL = "cluster"
+# Members named per cluster, most typical (nearest its centre) first. The test demo
+# answer said "cluster 1: 67 units" and could not say WHICH units.
+_MAX_MEMBERS = 15
 
 
 class NotEnoughDataError(ValueError):
@@ -68,6 +71,11 @@ class ClusterInput(BaseModel):
         description=f"Number of clusters; omit to choose automatically between "
         f"{_K_MIN} and {_K_MAX} by silhouette score.",
     )
+    label_columns: list[str] | None = Field(
+        None, description="Identifier columns (e.g. unit/equipment no.) used to NAME each "
+        "cluster's members. Never fed to the model; omit to use the table's most varied "
+        "text column."
+    )
 
 
 DESCRIPTION = build_description(
@@ -82,7 +90,8 @@ DESCRIPTION = build_description(
         "the user wants totals per an EXISTING category column -> analyze_aggregate",
     ],
     output="the chosen k with its silhouette score, one profile row per cluster "
-    "(size, share, per-column means), and a scatter coloured by cluster.",
+    "(size, share, per-column means, its most typical members by name), and a scatter "
+    "coloured by cluster.",
     examples=[
         "ada berapa kelompok pelanggan berdasarkan demografi?",
         "what natural groups are in this data?",
@@ -128,19 +137,63 @@ def _fit_kmeans(x: np.ndarray, k_values: list[int], random_state: int):
     return best[0], best[1], best[2], scores
 
 
-def _profiles(frame: pd.DataFrame, labels: np.ndarray, column_ids: list[str]) -> list[dict]:
-    """One row per cluster: size, share of rows, and the mean of each column."""
+def _default_labels(df: pd.DataFrame, column_ids: list[str]) -> list[str]:
+    """The most varied text column not being clustered (e.g. `eqm_no`), or none."""
+    text = [
+        c for c in df.columns
+        if c not in column_ids
+        and (pd.api.types.is_object_dtype(df[c]) or pd.api.types.is_string_dtype(df[c]))
+    ]
+    return [max(text, key=lambda c: df[c].nunique())] if text else []
+
+
+def _member_names(
+    df: pd.DataFrame, frame: pd.DataFrame, labels: np.ndarray, label_columns: list[str]
+) -> dict[int, list[str]]:
+    """Per cluster, up to _MAX_MEMBERS distinct row names, nearest the centre first.
+
+    Distance is measured on standardised columns (as the fit saw them), so a column
+    with large units does not decide who is "typical". Names repeat when rows are
+    unit-months (local run 2 Nov); each is listed once, at its most typical row.
+    """
+    x = frame.to_numpy(dtype=float)
+    std = x.std(axis=0)
+    x = (x - x.mean(axis=0)) / np.where(std == 0, 1.0, std)
+    names = df.loc[frame.index, label_columns].astype(str).agg(" · ".join, axis=1).to_numpy()
+    out: dict[int, list[str]] = {}
+    for label in sorted(set(labels.tolist())):
+        mask = labels == label
+        dist = np.linalg.norm(x[mask] - x[mask].mean(axis=0), axis=1)
+        ordered = dict.fromkeys(names[mask][np.argsort(dist, kind="stable")].tolist())
+        out[int(label)] = list(ordered)[:_MAX_MEMBERS]
+    return out
+
+
+def _profiles(
+    frame: pd.DataFrame,
+    labels: np.ndarray,
+    column_ids: list[str],
+    members: dict[int, list[str]] | None = None,
+) -> list[dict]:
+    """One row per cluster: size, share of rows, the mean of each column and, when
+    rows can be named, its most typical members."""
     total = len(labels)
     out: list[dict] = []
     for label in sorted(set(labels.tolist())):
-        members = frame[labels == label]
+        rows = frame[labels == label]
         profile: dict[str, object] = {
             "cluster": int(label),
-            "size": int(len(members)),
-            "share": round(len(members) / total, 4) if total else 0.0,
+            "size": int(len(rows)),
+            "share": round(len(rows) / total, 4) if total else 0.0,
         }
         for col in column_ids:
-            profile[col] = _clean(members[col].mean())
+            profile[col] = _clean(rows[col].mean())
+        if members is not None:
+            # A bounded, most-typical-first SAMPLE, named so (local run 2 Nov: a bare
+            # `members` list of 15 was presented as the whole group of 109). `size`
+            # stays the true row count.
+            profile["example_members"] = members[int(label)]
+            profile["members_shown"] = len(members[int(label)])
         out.append(profile)
     return out
 
@@ -149,9 +202,14 @@ async def analyze_cluster(
     df: pd.DataFrame,
     column_ids: list[str],
     k: int | None = None,
+    label_columns: list[str] | None = None,
 ) -> dict[str, object]:
     """Group rows by `column_ids` with KMeans, choosing k by silhouette when unset.
 
+    `label_columns` name each cluster's members (never fed to the model); when omitted
+    the table's most varied text column is used, and with none the profiles carry no
+    `example_members`.
+
     Async ONLY so the fit search can be offloaded via `run_fit`; everything else is
     synchronous compute. `data` is materialised upstream (Pattern A) and arrives as
     `df`.
@@ -167,7 +225,8 @@ async def analyze_cluster(
     """
     if not column_ids:
         raise EmptyColumnSelectionError("column_ids must name at least one numeric column")
-    missing = [c for c in column_ids if c not in df.columns]
+    names_by = list(label_columns) if label_columns else _default_labels(df, column_ids)
+    missing = [c for c in column_ids + names_by if c not in df.columns]
     if missing:
         raise ColumnNotFoundError(f"columns not found: {missing}")
 
@@ -242,7 +301,10 @@ async def analyze_cluster(
             "weak": silhouette <= _WEAK_SILHOUETTE,
         },
         "silhouette_by_k": by_k,
-        "clusters": _profiles(frame, labels, capped),
+        "clusters": _profiles(
+            frame, labels, capped,
+            _member_names(df, frame, labels, names_by) if names_by else None,
+        ),
         "caveats": caveats,
         "charts": [chart],
     }