Add termination signal detection for insufficient analysis results

- Detect when analysis results cannot answer group comparison queries
- Add termination_recommended and termination_reason fields to tool results
- Include detailed limitations and solution suggestions in summary
- Mark termination recommendation when all groups are 'default' (cannot perform group comparison)
- Provide clear guidance in summary for planner to identify when to terminate (not as error)

octotools/tools/cell_state_analyzer_multi/tool.py

@@ -508,14 +508,46 @@ class Cell_State_Analyzer_Multi_Tool(BaseTool):
         adata.write(adata_path)
         
         # Generate summary based on analysis type
+        # Check if results are sufficient to answer group comparison queries
+        insufficient_for_comparison = False
+        comparison_limitations = []
+        termination_recommended = False
+        termination_reason = None
+        
+        if is_single_group:
+            insufficient_for_comparison = True
+            comparison_limitations.append("All cells are labeled as 'default' - no group labels available for comparison")
+            # If query requires group comparison, recommend termination
+            termination_recommended = True
+            termination_reason = (
+                "**Cannot perform group comparison analysis:** All cells are in a single group ('default'). "
+                "Group comparison queries cannot be answered with the current data.\n\n"
+                "**Recommendation:** Terminate analysis and inform user that group labels are required for comparison queries.\n\n"
+                "**Solution:** Provide treatment/group labels when uploading images to enable group comparison analysis."
+            )
+        
+        if num_crops < 10:
+            insufficient_for_comparison = True
+            comparison_limitations.append(f"Very small sample size ({num_crops} cells) - may be insufficient for robust statistical comparisons")
+        
+        if use_zero_shot and not history:
+            comparison_limitations.append("Zero-shot inference mode (no training) - features may not be optimal for comparison")
+        
         if is_single_group:
             summary = f"Single-group analysis completed. {num_crops} cells analyzed. "
             summary += f"{len(history)} epochs trained" if history else "Zero-shot inference (no training)"
-            summary += ". Group comparison not available (all cells in single group)."
+            summary += "\n\n⚠️ **Limitations for Group Comparison Queries:**\n"
+            summary += "- All cells are in a single group ('default') - group comparison analysis cannot be performed\n"
+            summary += "- To enable group comparison, provide treatment/group labels when uploading images\n"
+            summary += "- Current analysis provides single-group clustering and UMAP visualization only"
+            if termination_recommended:
+                summary += f"\n\n🛑 **Termination Recommendation:**\n{termination_reason}"
         else:
             summary = f"Multi-group analysis completed. {num_crops} cells across {len(unique_groups)} groups. "
             summary += f"{len(history)} epochs trained" if history else "Zero-shot inference (no training)"
             summary += f". Groups: {', '.join(sorted(unique_groups))}"
+            if comparison_limitations:
+                summary += "\n\n⚠️ **Note:** " + "; ".join(comparison_limitations)
         
         return {
             "summary": summary,
@@ -529,7 +561,11 @@ class Cell_State_Analyzer_Multi_Tool(BaseTool):
             "cluster_resolution": cluster_resolution,
             "analysis_type": "cell_state_analysis",
             "num_groups": len(unique_groups),
-            "groups": sorted(unique_groups) if not is_single_group else ["default"]
+            "groups": sorted(unique_groups) if not is_single_group else ["default"],
+            "insufficient_for_comparison": insufficient_for_comparison,
+            "comparison_limitations": comparison_limitations if comparison_limitations else None,
+            "termination_recommended": termination_recommended,
+            "termination_reason": termination_reason
         }
 
 

octotools/tools/cell_state_analyzer_single/tool.py

@@ -474,8 +474,52 @@ class Cell_State_Analyzer_Single_Tool(BaseTool):
         adata_path = os.path.join(output_dir, "cell_state_analyzed.h5ad")
         adata.write(adata_path)
         
+        # Check if results are sufficient for group comparison queries
+        unique_groups = set(groups_extracted if len(groups_extracted) == adata.n_obs else groups[:adata.n_obs])
+        is_single_group = len(unique_groups) == 1
+        insufficient_for_comparison = False
+        comparison_limitations = []
+        termination_recommended = False
+        termination_reason = None
+        
+        if is_single_group:
+            insufficient_for_comparison = True
+            comparison_limitations.append("All cells are labeled as 'default' - no group labels available for comparison")
+            # If query requires group comparison, recommend termination
+            termination_recommended = True
+            termination_reason = (
+                "**Cannot perform group comparison analysis:** All cells are in a single group ('default'). "
+                "Group comparison queries cannot be answered with the current data.\n\n"
+                "**Recommendation:** Terminate analysis and inform user that group labels are required for comparison queries.\n\n"
+                "**Solution:** Provide treatment/group labels when uploading images to enable group comparison analysis."
+            )
+        
+        if num_crops < 10:
+            insufficient_for_comparison = True
+            comparison_limitations.append(f"Very small sample size ({num_crops} cells) - may be insufficient for robust statistical comparisons")
+        
+        if use_zero_shot and not history:
+            comparison_limitations.append("Zero-shot inference mode (no training) - features may not be optimal for comparison")
+        
+        # Generate summary
+        if is_single_group:
+            summary = f"Single-group analysis completed. {num_crops} cells analyzed. "
+            summary += f"{len(history)} epochs trained" if history else "Zero-shot inference (no training)"
+            summary += "\n\n⚠️ **Limitations for Group Comparison Queries:**\n"
+            summary += "- All cells are in a single group ('default') - group comparison analysis cannot be performed\n"
+            summary += "- To enable group comparison, provide treatment/group labels when uploading images\n"
+            summary += "- Current analysis provides single-group clustering and UMAP visualization only"
+            if termination_recommended:
+                summary += f"\n\n🛑 **Termination Recommendation:**\n{termination_reason}"
+        else:
+            summary = f"Multi-group analysis completed. {num_crops} cells across {len(unique_groups)} groups. "
+            summary += f"{len(history)} epochs trained" if history else "Zero-shot inference (no training)"
+            summary += f". Groups: {', '.join(sorted(unique_groups))}"
+            if comparison_limitations:
+                summary += "\n\n⚠️ **Note:** " + "; ".join(comparison_limitations)
+        
         return {
-            "summary": f"Analysis completed. {num_crops} cells, {len(history)} epochs" if history else f"Zero-shot: {num_crops} cells",
+            "summary": summary,
             "cell_count": num_crops,
             "mode": "training" if not use_zero_shot else "zero-shot",
             "epochs_trained": len(history),
@@ -484,7 +528,13 @@ class Cell_State_Analyzer_Single_Tool(BaseTool):
             "deliverables": [adata_path] + ([loss_path] if history and loss_path else []),
             "cluster_key": cluster_key,
             "cluster_resolution": cluster_resolution,
-            "analysis_type": "cell_state_analysis"
+            "analysis_type": "cell_state_analysis",
+            "num_groups": len(unique_groups),
+            "groups": sorted(unique_groups) if not is_single_group else ["default"],
+            "insufficient_for_comparison": insufficient_for_comparison,
+            "comparison_limitations": comparison_limitations if comparison_limitations else None,
+            "termination_recommended": termination_recommended,
+            "termination_reason": termination_reason
         }