feat(polis): type pipeline outcomes

Make run_pipeline return explicit success or insufficient-data outcomes directly instead of a separate typed endpoint. Add candidate_group_counts for opt-in multi-k k-means results while preserving force_group_count for single forced-k runs.

Author: nicobao

docs/api_reference.md

@@ -149,10 +149,34 @@ use in Scikit-Learn workflows, pipelines, and APIs.
 
 ## Types
 
+### ::: reddwarf.implementations.base.AnalysisSuccess
+    options:
+        show_root_heading: true
+
+### ::: reddwarf.implementations.base.AnalysisInsufficientData
+    options:
+        show_root_heading: true
+
+### ::: reddwarf.implementations.base.InsufficientDataReason
+    options:
+        show_root_heading: true
+
 ### ::: reddwarf.implementations.base.PolisClusteringResult
     options:
         show_root_heading: true
 
+### ::: reddwarf.implementations.base.KMeansCandidatesResult
+    options:
+        show_root_heading: true
+
+### ::: reddwarf.implementations.base.KMeansCandidateSuccess
+    options:
+        show_root_heading: true
+
+### ::: reddwarf.implementations.base.KMeansCandidateInsufficientData
+    options:
+        show_root_heading: true
+
 ### ::: reddwarf.types.agora.RankedRepnessStatement
     options:
         show_root_heading: true

reddwarf/implementations/agora.py

@@ -44,6 +44,11 @@ class AgoraClusteringResult:
 
 
 TypedAgoraClusteringResult = base.AnalysisSuccess[AgoraClusteringResult] | base.AnalysisInsufficientData
+TypedAgoraKMeansCandidatesResult = (
+    base.AnalysisSuccess[base.KMeansCandidatesResult[AgoraClusteringResult]]
+    | base.AnalysisInsufficientData
+)
+TypedAgoraPipelineResult = TypedAgoraClusteringResult | TypedAgoraKMeansCandidatesResult
 
 
 def compute_effective_agreement_gac(
@@ -80,34 +85,21 @@ def compute_effective_agreement_gac(
     return {"agree": agree, "disagree": disagree}
 
 
-def run_pipeline(
-    fdr_rate: float = 0.10,
-    **kwargs,
+def _build_agora_result(
+    *,
+    base_result: base.PolisClusteringResult,
+    mod_out_statement_ids: list[int],
+    fdr_rate: float,
 ) -> AgoraClusteringResult:
-    """
-    Agora clustering pipeline. Runs the base pipeline and adds ranked
-    representative/consensus statements with Benjamini-Hochberg selection.
-
-    Accepts all the same arguments as base.run_pipeline(), plus:
-
-    Args:
-        fdr_rate (float): False discovery rate for Benjamini-Hochberg selection.
-        **kwargs: All arguments forwarded to base.run_pipeline().
-
-    Returns:
-        AgoraClusteringResult: Clustering results with ranked statement outputs.
-    """
-    base_result = base.run_pipeline(**kwargs)
-
     ranked_repness = rank_representative_statements(
         grouped_stats_df=base_result.group_comment_stats,
-        mod_out_statement_ids=kwargs.get("mod_out_statement_ids", []),
+        mod_out_statement_ids=mod_out_statement_ids,
         fdr_rate=fdr_rate,
     )
 
     ranked_consensus = rank_consensus_statements(
         vote_matrix=base_result.raw_vote_matrix,
-        mod_out_statement_ids=kwargs.get("mod_out_statement_ids", []),
+        mod_out_statement_ids=mod_out_statement_ids,
         fdr_rate=fdr_rate,
     )
 
@@ -137,20 +129,63 @@ def run_pipeline(
     )
 
 
-def run_pipeline_typed(**kwargs) -> TypedAgoraClusteringResult:
-    reason = base.get_insufficient_data_reason(
-        votes=kwargs["votes"],
-        mod_out_statement_ids=kwargs.get("mod_out_statement_ids", []),
-        min_user_vote_threshold=kwargs.get("min_user_vote_threshold", 7),
-        keep_participant_ids=kwargs.get("keep_participant_ids", []),
-        force_group_count=kwargs.get("force_group_count"),
-    )
-    if reason is not None:
-        return base.AnalysisInsufficientData(
-            outcome=base.AnalysisOutcome.INSUFFICIENT_DATA,
-            reason=reason,
+def run_pipeline(
+    fdr_rate: float = 0.10,
+    **kwargs,
+) -> TypedAgoraPipelineResult:
+    """
+    Agora clustering pipeline. Runs the base pipeline and adds ranked
+    representative/consensus statements with Benjamini-Hochberg selection.
+
+    Accepts all the same arguments as base.run_pipeline(), plus:
+
+    Args:
+        fdr_rate (float): False discovery rate for Benjamini-Hochberg selection.
+        **kwargs: All arguments forwarded to base.run_pipeline().
+
+    Returns:
+        AnalysisSuccess or AnalysisInsufficientData. On success, `result` contains either
+        AgoraClusteringResult or KMeansCandidatesResult when candidate_group_counts is set.
+    """
+    base_pipeline_result = base.run_pipeline(**kwargs)
+    if base_pipeline_result.outcome == base.AnalysisOutcome.INSUFFICIENT_DATA:
+        return base_pipeline_result
+
+    mod_out_statement_ids = kwargs.get("mod_out_statement_ids", [])
+    if isinstance(base_pipeline_result.result, base.KMeansCandidatesResult):
+        candidates: list[
+            base.KMeansCandidateSuccess[AgoraClusteringResult]
+            | base.KMeansCandidateInsufficientData
+        ] = []
+        for candidate in base_pipeline_result.result.candidates:
+            if candidate.outcome == base.AnalysisOutcome.INSUFFICIENT_DATA:
+                candidates.append(candidate)
+                continue
+            candidates.append(
+                base.KMeansCandidateSuccess(
+                    group_count=candidate.group_count,
+                    outcome=base.AnalysisOutcome.SUCCESS,
+                    silhouette_score=candidate.silhouette_score,
+                    result=_build_agora_result(
+                        base_result=candidate.result,
+                        mod_out_statement_ids=mod_out_statement_ids,
+                        fdr_rate=fdr_rate,
+                    ),
+                )
+            )
+        return base.AnalysisSuccess(
+            outcome=base.AnalysisOutcome.SUCCESS,
+            result=base.KMeansCandidatesResult(
+                projection=base_pipeline_result.result.projection,
+                candidates=candidates,
+            ),
         )
+
     return base.AnalysisSuccess(
         outcome=base.AnalysisOutcome.SUCCESS,
-        result=run_pipeline(**kwargs),
+        result=_build_agora_result(
+            base_result=base_pipeline_result.result,
+            mod_out_statement_ids=mod_out_statement_ids,
+            fdr_rate=fdr_rate,
+        ),
     )