From 210275c6d28ed24eb259a2b9a4121b4c40f30d6c Mon Sep 17 00:00:00 2001
From: Yiorgis Gozadinos <ggozadinos@gmail.com>
Date: Fri, 12 Sep 2025 12:48:00 +0300
Subject: [PATCH] Analysis and clarification agents

---
 src/haiku/rag/research/analysis_agent.py      | 53 +++++++++++++++++
 src/haiku/rag/research/clarification_agent.py | 58 +++++++++++++++++++
 2 files changed, 111 insertions(+)
 create mode 100644 src/haiku/rag/research/analysis_agent.py
 create mode 100644 src/haiku/rag/research/clarification_agent.py

diff --git a/src/haiku/rag/research/analysis_agent.py b/src/haiku/rag/research/analysis_agent.py
new file mode 100644
index 00000000..dc817bd9
--- /dev/null
+++ b/src/haiku/rag/research/analysis_agent.py
@@ -0,0 +1,53 @@
+"""Analysis agent for content processing and insight extraction."""
+
+from pydantic import BaseModel, Field
+
+from haiku.rag.research.base import BaseResearchAgent
+
+
+class AnalysisResult(BaseModel):
+    """Result of content analysis."""
+
+    key_insights: list[str] = Field(
+        description="Main insights extracted from the documents"
+    )
+    themes: dict[str, list[str]] = Field(description="Themes and related findings")
+    summary: str = Field(description="Consolidated summary of findings")
+    evidence_quality: str = Field(
+        description="Assessment of evidence quality (strong/moderate/weak)"
+    )
+    recommendations: list[str] = Field(
+        description="Suggested next steps or areas for further research"
+    )
+
+
+class AnalysisAgent(BaseResearchAgent):
+    """Agent specialized in content analysis and synthesis."""
+
+    def __init__(self, provider: str, model: str):
+        super().__init__(provider, model, output_type=AnalysisResult)
+
+    def get_system_prompt(self) -> str:
+        return """You are an analysis specialist agent focused on extracting deep insights from search results.
+
+        Your role is to:
+        1. Carefully read and analyze all provided documents
+        2. Extract key insights and important facts
+        3. Identify common themes and patterns across documents
+        4. Synthesize information into a coherent understanding
+        5. Assess the quality and reliability of the evidence
+        6. Identify areas that need further investigation
+
+        Be specific and detailed in your analysis. Focus on:
+        - What the documents actually say (not assumptions)
+        - Connections and contradictions between sources
+        - The strength of the evidence presented
+        - Gaps in the information that need to be filled
+
+        Your analysis should be thorough, critical, and actionable."""
+
+    def register_tools(self) -> None:
+        """Register analysis-specific tools."""
+        # The agent will use its LLM capabilities directly for analysis
+        # No need for hardcoded tools - the structured output will guide the analysis
+        pass
diff --git a/src/haiku/rag/research/clarification_agent.py b/src/haiku/rag/research/clarification_agent.py
new file mode 100644
index 00000000..e4aec7b3
--- /dev/null
+++ b/src/haiku/rag/research/clarification_agent.py
@@ -0,0 +1,58 @@
+"""Clarification agent for gap detection and follow-up question generation."""
+
+from pydantic import BaseModel, Field
+
+from haiku.rag.research.base import BaseResearchAgent
+
+
+class ClarificationResult(BaseModel):
+    """Result of clarification analysis."""
+
+    information_gaps: list[str] = Field(
+        description="Specific missing information identified"
+    )
+    follow_up_questions: list[str] = Field(
+        description="Questions to ask to fill the gaps"
+    )
+    suggested_searches: list[str] = Field(
+        description="Recommended search queries for deeper investigation"
+    )
+    completeness_assessment: str = Field(
+        description="Overall assessment of research completeness"
+    )
+    priority_areas: list[str] = Field(
+        description="Most important areas to investigate next"
+    )
+
+
+class ClarificationAgent(BaseResearchAgent):
+    """Agent specialized in identifying gaps and generating follow-up questions."""
+
+    def __init__(self, provider: str, model: str):
+        super().__init__(provider, model, output_type=ClarificationResult)
+
+    def get_system_prompt(self) -> str:
+        return """You are a clarification specialist agent focused on research completeness and quality.
+
+        Your role is to:
+        1. Critically evaluate what information has been gathered
+        2. Identify what crucial information is still missing
+        3. Detect contradictions or inconsistencies that need resolution
+        4. Generate targeted follow-up questions to fill knowledge gaps
+        5. Suggest specific search queries for deeper investigation
+        6. Assess the overall completeness of the research
+
+        Be thorough and critical in your evaluation. Consider:
+        - What questions remain unanswered?
+        - What assumptions need verification?
+        - What contradictions need resolution?
+        - What perspectives are missing?
+        - What details would strengthen the understanding?
+
+        Your goal is to ensure comprehensive, accurate, and complete research."""
+
+    def register_tools(self) -> None:
+        """Register clarification-specific tools."""
+        # The agent will use its LLM capabilities directly for gap analysis
+        # The structured output will guide the clarification process
+        pass