From 9332a256aa08527d2d40cc475215260acdb9ab37 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Fri, 1 Aug 2025 20:31:03 +0300 Subject: [PATCH 01/28] Add files via upload --- ...archical_structured_communication_swarm.py | 690 ++++++++++++++++++ 1 file changed, 690 insertions(+) create mode 100644 swarms/structs/hierarchical_structured_communication_swarm.py diff --git a/swarms/structs/hierarchical_structured_communication_swarm.py b/swarms/structs/hierarchical_structured_communication_swarm.py new file mode 100644 index 00000000..09c8150f --- /dev/null +++ b/swarms/structs/hierarchical_structured_communication_swarm.py @@ -0,0 +1,690 @@ +""" +Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems + +This implementation is based on the research paper: +"Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems" +arXiv:2502.11098 + +The framework consists of: +1. Structured Communication Protocol - Context-rich communication with message, background, and intermediate output +2. Hierarchical Refinement System - Evaluation team with supervisor coordination +3. Graph-based Agent Orchestration - Dynamic communication pathways + +Key Features: +- Structured communication with Message (M_ij), Background (B_ij), and Intermediate Output (I_ij) +- Hierarchical evaluation team with supervisor coordination +- Dynamic graph-based agent routing +- Context preservation and shared memory +""" + +import traceback +from typing import Any, Callable, Dict, List, Literal, Optional, Union +from dataclasses import dataclass +from enum import Enum + +from pydantic import BaseModel, Field + +from swarms.structs.agent import Agent +from swarms.structs.base_swarm import BaseSwarm +from swarms.structs.conversation import Conversation +from swarms.utils.loguru_logger import initialize_logger +from swarms.utils.output_types import OutputType + +logger = initialize_logger(log_folder="hierarchical_structured_communication_swarm") + + +class CommunicationType(str, Enum): + """Types of communication in the structured protocol""" + MESSAGE = "message" # M_ij: Specific task instructions + BACKGROUND = "background" # B_ij: Context and problem background + INTERMEDIATE_OUTPUT = "intermediate_output" # I_ij: Intermediate results + + +class AgentRole(str, Enum): + """Roles for agents in the hierarchical system""" + SUPERVISOR = "supervisor" + GENERATOR = "generator" + EVALUATOR = "evaluator" + REFINER = "refiner" + COORDINATOR = "coordinator" + + +@dataclass +class StructuredMessage: + """Structured communication message following HierarchicalStructuredComm protocol""" + message: str = Field(description="Specific task instructions (M_ij)") + background: str = Field(description="Context and problem background (B_ij)") + intermediate_output: str = Field(description="Intermediate results (I_ij)") + sender: str = Field(description="Name of the sending agent") + recipient: str = Field(description="Name of the receiving agent") + timestamp: Optional[str] = None + + +class HierarchicalOrder(BaseModel): + """Order structure for hierarchical task assignment""" + agent_name: str = Field(description="Name of the agent to receive the task") + task: str = Field(description="Specific task description") + communication_type: CommunicationType = Field( + default=CommunicationType.MESSAGE, + description="Type of communication to use" + ) + background_context: str = Field( + default="", + description="Background context for the task" + ) + intermediate_output: str = Field( + default="", + description="Intermediate output to pass along" + ) + + +class EvaluationResult(BaseModel): + """Result from evaluation team member""" + evaluator_name: str = Field(description="Name of the evaluator") + criterion: str = Field(description="Evaluation criterion") + score: float = Field(description="Evaluation score") + feedback: str = Field(description="Detailed feedback") + confidence: float = Field(description="Confidence in evaluation") + + +class HierarchicalStructuredCommunicationSwarm(BaseSwarm): + """ + Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems + + This framework implements the HierarchicalStructuredComm approach with: + 1. Structured Communication Protocol + 2. Hierarchical Refinement System + 3. Graph-based Agent Orchestration + + Architecture: + - Supervisor Agent: Coordinates the overall workflow + - Generator Agents: Create initial content/solutions + - Evaluator Team: Hierarchical evaluation with supervisor + - Refiner Agents: Improve solutions based on feedback + """ + + def __init__( + self, + name: str = "HierarchicalStructuredCommunicationSwarm", + description: str = "Talk Structurally, Act Hierarchically Framework", + supervisor: Optional[Union[Agent, Callable, Any]] = None, + generators: List[Union[Agent, Callable, Any]] = None, + evaluators: List[Union[Agent, Callable, Any]] = None, + refiners: List[Union[Agent, Callable, Any]] = None, + evaluation_supervisor: Optional[Union[Agent, Callable, Any]] = None, + max_loops: int = 3, + output_type: OutputType = "dict-all-except-first", + supervisor_name: str = "Supervisor", + evaluation_supervisor_name: str = "EvaluationSupervisor", + verbose: bool = False, + enable_structured_communication: bool = True, + enable_hierarchical_evaluation: bool = True, + shared_memory: bool = True, + *args, + **kwargs, + ): + """ + Initialize the HierarchicalStructuredCommunicationSwarm + + Args: + name: Name of the swarm + description: Description of the swarm + supervisor: Main supervisor agent + generators: List of generator agents + evaluators: List of evaluator agents + refiners: List of refiner agents + evaluation_supervisor: Supervisor for evaluation team + max_loops: Maximum number of refinement loops + output_type: Type of output format + supervisor_name: Name for the supervisor agent + evaluation_supervisor_name: Name for evaluation supervisor + verbose: Enable verbose logging + enable_structured_communication: Enable structured communication protocol + enable_hierarchical_evaluation: Enable hierarchical evaluation system + shared_memory: Enable shared memory between agents + """ + # Initialize the swarm components first + self.name = name + self.description = description + self.supervisor = supervisor + self.generators = generators or [] + self.evaluators = evaluators or [] + self.refiners = refiners or [] + self.evaluation_supervisor = evaluation_supervisor + self.max_loops = max_loops + self.output_type = output_type + self.supervisor_name = supervisor_name + self.evaluation_supervisor_name = evaluation_supervisor_name + self.verbose = verbose + self.enable_structured_communication = enable_structured_communication + self.enable_hierarchical_evaluation = enable_hierarchical_evaluation + self.shared_memory = shared_memory + + # Communication and state management + self.conversation_history: List[StructuredMessage] = [] + self.intermediate_outputs: Dict[str, str] = {} + self.evaluation_results: List[EvaluationResult] = [] + + # Initialize the swarm components + self.init_swarm() + + # Collect all agents for the parent class + all_agents = [] + if self.supervisor: + all_agents.append(self.supervisor) + all_agents.extend(self.generators) + all_agents.extend(self.evaluators) + all_agents.extend(self.refiners) + if self.evaluation_supervisor: + all_agents.append(self.evaluation_supervisor) + + # Call parent constructor with agents + super().__init__(agents=all_agents, *args, **kwargs) + + def init_swarm(self): + """Initialize the swarm components""" + logger.info(f"Initializing {self.name}") + + # Setup supervisor if not provided + if self.supervisor is None: + self.supervisor = self._create_supervisor_agent() + + # Setup evaluation supervisor if not provided + if self.evaluation_supervisor is None and self.enable_hierarchical_evaluation: + self.evaluation_supervisor = self._create_evaluation_supervisor_agent() + + # Setup default agents if none provided + if not self.generators: + self.generators = [self._create_default_generator()] + + if not self.evaluators and self.enable_hierarchical_evaluation: + self.evaluators = [self._create_default_evaluator()] + + if not self.refiners: + self.refiners = [self._create_default_refiner()] + + logger.info(f"Swarm initialized with {len(self.generators)} generators, " + f"{len(self.evaluators)} evaluators, {len(self.refiners)} refiners") + + def _create_supervisor_agent(self) -> Agent: + """Create the main supervisor agent""" + supervisor_prompt = self._get_supervisor_prompt() + + return Agent( + agent_name=self.supervisor_name, + system_prompt=supervisor_prompt, + model_name="gpt-4o-mini", + verbose=self.verbose, + # Ollama configuration + openai_api_base="http://localhost:11434/v1", + openai_api_key="ollama", + reliability_check=False + ) + + def _create_evaluation_supervisor_agent(self) -> Agent: + """Create the evaluation team supervisor""" + eval_supervisor_prompt = self._get_evaluation_supervisor_prompt() + + return Agent( + agent_name=self.evaluation_supervisor_name, + system_prompt=eval_supervisor_prompt, + model_name="gpt-4o-mini", + verbose=self.verbose, + # Ollama configuration + openai_api_base="http://localhost:11434/v1", + openai_api_key="ollama", + reliability_check=False + ) + + def _create_default_generator(self) -> Agent: + """Create a default generator agent""" + generator_prompt = self._get_generator_prompt() + + return Agent( + agent_name="Generator", + system_prompt=generator_prompt, + model_name="gpt-4o-mini", + verbose=self.verbose, + # Ollama configuration + openai_api_base="http://localhost:11434/v1", + openai_api_key="ollama", + reliability_check=False + ) + + def _create_default_evaluator(self) -> Agent: + """Create a default evaluator agent""" + evaluator_prompt = self._get_evaluator_prompt() + + return Agent( + agent_name="Evaluator", + system_prompt=evaluator_prompt, + model_name="gpt-4o-mini", + verbose=self.verbose, + # Ollama configuration + openai_api_base="http://localhost:11434/v1", + openai_api_key="ollama", + reliability_check=False + ) + + def _create_default_refiner(self) -> Agent: + """Create a default refiner agent""" + refiner_prompt = self._get_refiner_prompt() + + return Agent( + agent_name="Refiner", + system_prompt=refiner_prompt, + model_name="gpt-4o-mini", + verbose=self.verbose, + # Ollama configuration + openai_api_base="http://localhost:11434/v1", + openai_api_key="ollama", + reliability_check=False + ) + + def _get_supervisor_prompt(self) -> str: + """Get the supervisor system prompt""" + return f""" +You are the {self.supervisor_name} in a Talk Structurally, Act Hierarchically framework. + +Your responsibilities: +1. **Structured Communication**: Use the structured communication protocol with: + - Message (M_ij): Specific task instructions + - Background (B_ij): Context and problem background + - Intermediate Output (I_ij): Intermediate results + +2. **Task Orchestration**: Coordinate between generator, evaluator, and refiner agents + +3. **Workflow Management**: Manage the iterative refinement process + +Available agents: +- Generators: {[agent.agent_name if hasattr(agent, 'agent_name') else 'Generator' for agent in self.generators]} +- Evaluators: {[agent.agent_name if hasattr(agent, 'agent_name') else 'Evaluator' for agent in self.evaluators]} +- Refiners: {[agent.agent_name if hasattr(agent, 'agent_name') else 'Refiner' for agent in self.refiners]} + +Always provide structured communication with clear message, background context, and intermediate outputs. +""" + + def _get_evaluation_supervisor_prompt(self) -> str: + """Get the evaluation supervisor system prompt""" + return f""" +You are the {self.evaluation_supervisor_name} in a hierarchical evaluation system. + +Your responsibilities: +1. **Coordinate Evaluators**: Manage multiple evaluators with different criteria +2. **Synthesize Feedback**: Combine evaluation results into coherent feedback +3. **Provide Summarized Results**: Give concise, actionable feedback to the main supervisor + +Evaluation criteria to coordinate: +- Accuracy and correctness +- Completeness and coverage +- Clarity and coherence +- Relevance and appropriateness + +Always provide summarized, coordinated feedback that balances diverse evaluator inputs. +""" + + def _get_generator_prompt(self) -> str: + """Get the generator agent system prompt""" + return """ +You are a Generator agent in a Talk Structurally, Act Hierarchically framework. + +Your responsibilities: +1. **Create Initial Content**: Generate solutions, content, or responses based on structured input +2. **Follow Structured Communication**: Process messages with clear background context and intermediate outputs +3. **Provide Detailed Output**: Generate comprehensive, well-structured responses + +When receiving tasks: +- Pay attention to the specific message (M_ij) +- Consider the background context (B_ij) +- Build upon intermediate outputs (I_ij) if provided +- Provide your own intermediate output for the next agent + +Always structure your response clearly and provide sufficient detail for evaluation. +""" + + def _get_evaluator_prompt(self) -> str: + """Get the evaluator agent system prompt""" + return """ +You are an Evaluator agent in a hierarchical evaluation system. + +Your responsibilities: +1. **Evaluate Content**: Assess quality, accuracy, and appropriateness +2. **Provide Specific Feedback**: Give detailed, actionable feedback +3. **Score Performance**: Provide numerical scores with justification + +Evaluation criteria: +- Accuracy and correctness +- Completeness and coverage +- Clarity and coherence +- Relevance and appropriateness + +Always provide: +- Specific evaluation criterion +- Numerical score (0-10) +- Detailed feedback +- Confidence level (0-1) +""" + + def _get_refiner_prompt(self) -> str: + """Get the refiner agent system prompt""" + return """ +You are a Refiner agent in a Talk Structurally, Act Hierarchically framework. + +Your responsibilities: +1. **Improve Content**: Enhance solutions based on evaluation feedback +2. **Address Feedback**: Specifically address issues identified by evaluators +3. **Maintain Quality**: Ensure improvements maintain or enhance overall quality + +When refining: +- Consider all evaluation feedback +- Address specific issues mentioned +- Maintain the core strengths of the original +- Provide clear justification for changes + +Always explain your refinements and how they address the evaluation feedback. +""" + + def send_structured_message( + self, + sender: str, + recipient: str, + message: str, + background: str = "", + intermediate_output: str = "" + ) -> StructuredMessage: + """ + Send a structured message following the HierarchicalStructuredComm protocol + + Args: + sender: Name of the sending agent + recipient: Name of the receiving agent + message: Specific task message (M_ij) + background: Background context (B_ij) + intermediate_output: Intermediate output (I_ij) + + Returns: + StructuredMessage object + """ + structured_msg = StructuredMessage( + message=message, + background=background, + intermediate_output=intermediate_output, + sender=sender, + recipient=recipient + ) + + self.conversation_history.append(structured_msg) + + if self.verbose: + logger.info(f"Structured message sent from {sender} to {recipient}") + logger.info(f"Message: {message[:100]}...") + + return structured_msg + + def run_hierarchical_evaluation( + self, + content: str, + evaluation_criteria: List[str] = None + ) -> List[EvaluationResult]: + """ + Run hierarchical evaluation with multiple evaluators + + Args: + content: Content to evaluate + evaluation_criteria: List of evaluation criteria + + Returns: + List of evaluation results + """ + if not self.enable_hierarchical_evaluation: + return [] + + if evaluation_criteria is None: + evaluation_criteria = ["accuracy", "completeness", "clarity", "relevance"] + + results = [] + + # Run evaluations in parallel + for i, evaluator in enumerate(self.evaluators): + criterion = evaluation_criteria[i % len(evaluation_criteria)] + + # Create structured message for evaluator + eval_message = f"Evaluate the following content based on {criterion} criterion" + eval_background = f"Evaluation criterion: {criterion}\nContent to evaluate: {content}" + + structured_msg = self.send_structured_message( + sender=self.evaluation_supervisor_name, + recipient=evaluator.agent_name if hasattr(evaluator, 'agent_name') else f"Evaluator_{i}", + message=eval_message, + background=eval_background, + intermediate_output=content + ) + + # Get evaluation result + try: + if hasattr(evaluator, 'run'): + eval_response = evaluator.run( + f"Evaluate this content for {criterion}:\n{content}\n\nProvide: 1) Score (0-10), 2) Detailed feedback, 3) Confidence (0-1)" + ) + + # Parse evaluation result (simplified parsing) + result = EvaluationResult( + evaluator_name=evaluator.agent_name if hasattr(evaluator, 'agent_name') else f"Evaluator_{i}", + criterion=criterion, + score=7.5, # Default score, would need proper parsing + feedback=eval_response, + confidence=0.8 # Default confidence + ) + results.append(result) + + except Exception as e: + logger.error(f"Error in evaluation: {e}") + continue + + # Get summarized feedback from evaluation supervisor + if self.evaluation_supervisor and results: + summary_prompt = f"Summarize these evaluation results:\n{results}\n\nProvide coordinated, actionable feedback." + + try: + if hasattr(self.evaluation_supervisor, 'run'): + summary_feedback = self.evaluation_supervisor.run(summary_prompt) + logger.info(f"Evaluation summary: {summary_feedback}") + except Exception as e: + logger.error(f"Error in evaluation summary: {e}") + + self.evaluation_results.extend(results) + return results + + def step(self, task: str, img: str = None, *args, **kwargs): + """ + Execute one step of the HierarchicalStructuredComm workflow + + Args: + task: Task to execute + img: Optional image input + + Returns: + Step result + """ + try: + logger.info(f"Executing HierarchicalStructuredComm step for task: {task[:100]}...") + + # Safety check: prevent recursive task processing + if len(task) > 1000: # If task is too long, it might be recursive + logger.warning("Task too long, possible recursive call detected") + return {"error": "Task too long, possible recursive call"} + + # Step 1: Generate initial content + generator_result = self._generate_content(task) + + # Safety check: prevent empty or error results + if not generator_result or generator_result.startswith("Error"): + logger.error(f"Generator failed: {generator_result}") + return {"error": f"Generator failed: {generator_result}"} + + # Step 2: Evaluate content hierarchically + evaluation_results = self.run_hierarchical_evaluation(generator_result) + + # Step 3: Refine content based on evaluation + refined_result = self._refine_content(generator_result, evaluation_results) + + # Safety check: ensure we have a valid result + if not refined_result: + refined_result = generator_result + + return { + "generator_result": generator_result, + "evaluation_results": evaluation_results, + "refined_result": refined_result, + "conversation_history": self.conversation_history + } + + except Exception as e: + logger.error(f"Error in HierarchicalStructuredComm step: {e}") + logger.error(traceback.format_exc()) + return {"error": str(e)} + + def _generate_content(self, task: str) -> str: + """Generate initial content using generator agents""" + if not self.generators: + return "No generators available" + + # Use first generator for initial content + generator = self.generators[0] + + # Create structured message + message = f"Generate content for the following task: {task}" + background = f"Task context: {task}\n\nProvide comprehensive, well-structured content." + + structured_msg = self.send_structured_message( + sender=self.supervisor_name, + recipient=generator.agent_name if hasattr(generator, 'agent_name') else "Generator", + message=message, + background=background + ) + + try: + if hasattr(generator, 'run'): + # Add a simple, focused prompt to prevent recursive calls + prompt = f"Task: {task}\n\nGenerate a clear, concise response. Do not repeat the task or ask for clarification." + + result = generator.run(prompt) + + # Safety check: prevent recursive or overly long responses + if len(result) > 2000: + result = result[:2000] + "... [truncated]" + + # Safety check: prevent responses that just repeat the task + if task.lower() in result.lower() and len(result) < len(task) * 2: + logger.warning("Generator response appears to be recursive") + return "Error: Generator produced recursive response" + + self.intermediate_outputs["generator"] = result + return result + else: + return "Generator not properly configured" + except Exception as e: + logger.error(f"Error in content generation: {e}") + return f"Error generating content: {e}" + + def _refine_content(self, original_content: str, evaluation_results: List[EvaluationResult]) -> str: + """Refine content based on evaluation feedback""" + if not self.refiners: + return original_content + + if not evaluation_results: + return original_content + + # Use first refiner + refiner = self.refiners[0] + + # Create feedback summary + feedback_summary = "\n".join([ + f"{result.criterion}: {result.feedback} (Score: {result.score}/10)" + for result in evaluation_results + ]) + + # Create structured message for refinement + message = "Refine the content based on the evaluation feedback" + background = f"Original content: {original_content}\n\nEvaluation feedback:\n{feedback_summary}" + + structured_msg = self.send_structured_message( + sender=self.supervisor_name, + recipient=refiner.agent_name if hasattr(refiner, 'agent_name') else "Refiner", + message=message, + background=background, + intermediate_output=original_content + ) + + try: + if hasattr(refiner, 'run'): + refinement_prompt = f""" +Original content: +{original_content} + +Evaluation feedback: +{feedback_summary} + +Please refine the content to address the feedback while maintaining its core strengths. +""" + result = refiner.run(refinement_prompt) + self.intermediate_outputs["refiner"] = result + return result + else: + return original_content + except Exception as e: + logger.error(f"Error in content refinement: {e}") + return original_content + + def run(self, task: str, img: str = None, *args, **kwargs): + """ + Run the complete HierarchicalStructuredComm workflow + + Args: + task: Task to execute + img: Optional image input + + Returns: + Final result + """ + logger.info(f"Running HierarchicalStructuredComm workflow for task: {task[:100]}...") + + current_result = None + total_loops = 0 + + for loop in range(self.max_loops): + total_loops = loop + 1 + logger.info(f"HierarchicalStructuredComm loop {total_loops}/{self.max_loops}") + + # Execute step + step_result = self.step(task, img, *args, **kwargs) + + if "error" in step_result: + logger.error(f"Error in loop {total_loops}: {step_result['error']}") + break + + current_result = step_result["refined_result"] + + # Check if we should continue refining + if loop < self.max_loops - 1: + # Simple continuation logic - could be enhanced + evaluation_scores = [result.score for result in step_result["evaluation_results"]] + avg_score = sum(evaluation_scores) / len(evaluation_scores) if evaluation_scores else 0 + + if avg_score >= 8.0: # High quality threshold + logger.info(f"High quality achieved (avg score: {avg_score:.2f}), stopping refinement") + break + + return { + "final_result": current_result, + "total_loops": total_loops, + "conversation_history": self.conversation_history, + "evaluation_results": self.evaluation_results, + "intermediate_outputs": self.intermediate_outputs + } + + def __str__(self): + return f"HierarchicalStructuredCommunicationSwarm(name={self.name}, generators={len(self.generators)}, evaluators={len(self.evaluators)}, refiners={len(self.refiners)})" + + def __repr__(self): + return self.__str__() \ No newline at end of file From 228696873cbe6973f42fc583d27089f7625680c9 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Fri, 1 Aug 2025 20:31:36 +0300 Subject: [PATCH 02/28] Add files via upload --- ...chical_structured_communication_schemas.py | 430 ++++++++++++++++++ 1 file changed, 430 insertions(+) create mode 100644 swarms/schemas/hierarchical_structured_communication_schemas.py diff --git a/swarms/schemas/hierarchical_structured_communication_schemas.py b/swarms/schemas/hierarchical_structured_communication_schemas.py new file mode 100644 index 00000000..bf18fdff --- /dev/null +++ b/swarms/schemas/hierarchical_structured_communication_schemas.py @@ -0,0 +1,430 @@ +""" +Schemas for Talk Structurally, Act Hierarchically Framework + +This module defines the Pydantic schemas used in the TalkHierarchical framework +for structured communication and hierarchical evaluation. +""" + +from typing import Dict, List, Optional, Union +from pydantic import BaseModel, Field +from enum import Enum + + +class CommunicationType(str, Enum): + """Types of communication in the structured protocol""" + MESSAGE = "message" # M_ij: Specific task instructions + BACKGROUND = "background" # B_ij: Context and problem background + INTERMEDIATE_OUTPUT = "intermediate_output" # I_ij: Intermediate results + + +class AgentRole(str, Enum): + """Roles for agents in the hierarchical system""" + SUPERVISOR = "supervisor" + GENERATOR = "generator" + EVALUATOR = "evaluator" + REFINER = "refiner" + COORDINATOR = "coordinator" + + +class StructuredMessageSchema(BaseModel): + """Schema for structured communication messages""" + message: str = Field( + description="Specific task instructions (M_ij)", + min_length=1 + ) + background: str = Field( + description="Context and problem background (B_ij)", + default="" + ) + intermediate_output: str = Field( + description="Intermediate results (I_ij)", + default="" + ) + sender: str = Field( + description="Name of the sending agent", + min_length=1 + ) + recipient: str = Field( + description="Name of the receiving agent", + min_length=1 + ) + timestamp: Optional[str] = Field( + description="Timestamp of the message", + default=None + ) + communication_type: CommunicationType = Field( + description="Type of communication", + default=CommunicationType.MESSAGE + ) + + +class HierarchicalOrderSchema(BaseModel): + """Schema for hierarchical task orders""" + agent_name: str = Field( + description="Name of the agent to receive the task", + min_length=1 + ) + task: str = Field( + description="Specific task description", + min_length=1 + ) + communication_type: CommunicationType = Field( + description="Type of communication to use", + default=CommunicationType.MESSAGE + ) + background_context: str = Field( + description="Background context for the task", + default="" + ) + intermediate_output: str = Field( + description="Intermediate output to pass along", + default="" + ) + priority: int = Field( + description="Task priority (1-10, higher is more important)", + default=5, + ge=1, + le=10 + ) + + +class EvaluationCriterionSchema(BaseModel): + """Schema for evaluation criteria""" + name: str = Field( + description="Name of the evaluation criterion", + min_length=1 + ) + description: str = Field( + description="Description of what this criterion evaluates", + min_length=1 + ) + weight: float = Field( + description="Weight of this criterion in overall evaluation (0-1)", + default=1.0, + ge=0.0, + le=1.0 + ) + scale: str = Field( + description="Scale for evaluation (e.g., '0-10', 'A-F', 'Poor-Excellent')", + default="0-10" + ) + + +class EvaluationResultSchema(BaseModel): + """Schema for evaluation results""" + evaluator_name: str = Field( + description="Name of the evaluator", + min_length=1 + ) + criterion: str = Field( + description="Evaluation criterion", + min_length=1 + ) + score: float = Field( + description="Evaluation score", + ge=0.0 + ) + feedback: str = Field( + description="Detailed feedback", + min_length=1 + ) + confidence: float = Field( + description="Confidence in evaluation (0-1)", + ge=0.0, + le=1.0 + ) + reasoning: str = Field( + description="Reasoning behind the evaluation", + default="" + ) + suggestions: List[str] = Field( + description="Suggestions for improvement", + default=[] + ) + + +class EvaluationSummarySchema(BaseModel): + """Schema for evaluation summaries""" + overall_score: float = Field( + description="Overall evaluation score", + ge=0.0 + ) + criterion_scores: Dict[str, float] = Field( + description="Scores for each criterion", + default={} + ) + strengths: List[str] = Field( + description="Identified strengths", + default=[] + ) + weaknesses: List[str] = Field( + description="Identified weaknesses", + default=[] + ) + recommendations: List[str] = Field( + description="Recommendations for improvement", + default=[] + ) + confidence: float = Field( + description="Overall confidence in evaluation", + ge=0.0, + le=1.0 + ) + + +class AgentConfigSchema(BaseModel): + """Schema for agent configuration""" + name: str = Field( + description="Name of the agent", + min_length=1 + ) + role: AgentRole = Field( + description="Role of the agent in the system" + ) + model_name: str = Field( + description="Model to use for this agent", + default="gpt-4o-mini" + ) + system_prompt: str = Field( + description="System prompt for the agent", + min_length=1 + ) + tools: List[str] = Field( + description="Tools available to this agent", + default=[] + ) + capabilities: List[str] = Field( + description="Capabilities of this agent", + default=[] + ) + evaluation_criteria: List[str] = Field( + description="Evaluation criteria this agent can assess", + default=[] + ) + + +class TalkHierarchicalConfigSchema(BaseModel): + """Schema for TalkHierarchical swarm configuration""" + name: str = Field( + description="Name of the swarm", + default="TalkHierarchicalSwarm" + ) + description: str = Field( + description="Description of the swarm", + default="Talk Structurally, Act Hierarchically Framework" + ) + max_loops: int = Field( + description="Maximum number of refinement loops", + default=3, + ge=1 + ) + enable_structured_communication: bool = Field( + description="Enable structured communication protocol", + default=True + ) + enable_hierarchical_evaluation: bool = Field( + description="Enable hierarchical evaluation system", + default=True + ) + shared_memory: bool = Field( + description="Enable shared memory between agents", + default=True + ) + evaluation_criteria: List[EvaluationCriterionSchema] = Field( + description="Evaluation criteria for the system", + default=[] + ) + agents: List[AgentConfigSchema] = Field( + description="Configuration for all agents", + default=[] + ) + quality_threshold: float = Field( + description="Quality threshold for stopping refinement", + default=8.0, + ge=0.0, + le=10.0 + ) + + +class TalkHierarchicalStateSchema(BaseModel): + """Schema for TalkHierarchical swarm state""" + conversation_history: List[StructuredMessageSchema] = Field( + description="History of structured messages", + default=[] + ) + intermediate_outputs: Dict[str, str] = Field( + description="Intermediate outputs from agents", + default={} + ) + evaluation_results: List[EvaluationResultSchema] = Field( + description="Results from evaluations", + default=[] + ) + current_loop: int = Field( + description="Current refinement loop", + default=0 + ) + task: str = Field( + description="Current task being processed", + default="" + ) + final_result: Optional[str] = Field( + description="Final result of the workflow", + default=None + ) + + +class TalkHierarchicalResponseSchema(BaseModel): + """Schema for TalkHierarchical swarm response""" + final_result: str = Field( + description="Final result of the workflow" + ) + total_loops: int = Field( + description="Total number of loops executed", + ge=1 + ) + conversation_history: List[StructuredMessageSchema] = Field( + description="Complete conversation history" + ) + evaluation_results: List[EvaluationResultSchema] = Field( + description="All evaluation results" + ) + intermediate_outputs: Dict[str, str] = Field( + description="All intermediate outputs" + ) + evaluation_summary: Optional[EvaluationSummarySchema] = Field( + description="Summary of evaluations", + default=None + ) + performance_metrics: Dict[str, Union[float, int, str]] = Field( + description="Performance metrics", + default={} + ) + + +class GraphNodeSchema(BaseModel): + """Schema for graph nodes in agent orchestration""" + node_id: str = Field( + description="Unique identifier for the node", + min_length=1 + ) + agent_name: str = Field( + description="Name of the agent at this node", + min_length=1 + ) + role: AgentRole = Field( + description="Role of the agent" + ) + capabilities: List[str] = Field( + description="Capabilities of this node", + default=[] + ) + connections: List[str] = Field( + description="IDs of connected nodes", + default=[] + ) + conditions: Dict[str, str] = Field( + description="Conditions for routing to this node", + default={} + ) + + +class GraphSchema(BaseModel): + """Schema for agent orchestration graph""" + nodes: List[GraphNodeSchema] = Field( + description="Nodes in the graph", + default=[] + ) + start_node: str = Field( + description="ID of the start node", + min_length=1 + ) + end_nodes: List[str] = Field( + description="IDs of end nodes", + default=[] + ) + routing_rules: Dict[str, str] = Field( + description="Rules for routing between nodes", + default={} + ) + max_depth: int = Field( + description="Maximum depth of the graph", + default=10, + ge=1 + ) + + +# Response schemas for different agent types +class GeneratorResponseSchema(BaseModel): + """Schema for generator agent responses""" + content: str = Field( + description="Generated content", + min_length=1 + ) + intermediate_output: str = Field( + description="Intermediate output for next agent", + default="" + ) + reasoning: str = Field( + description="Reasoning behind the generation", + default="" + ) + confidence: float = Field( + description="Confidence in the generated content", + ge=0.0, + le=1.0 + ) + + +class EvaluatorResponseSchema(BaseModel): + """Schema for evaluator agent responses""" + criterion: str = Field( + description="Evaluation criterion", + min_length=1 + ) + score: float = Field( + description="Evaluation score", + ge=0.0 + ) + feedback: str = Field( + description="Detailed feedback", + min_length=1 + ) + confidence: float = Field( + description="Confidence in evaluation", + ge=0.0, + le=1.0 + ) + reasoning: str = Field( + description="Reasoning behind the evaluation", + default="" + ) + suggestions: List[str] = Field( + description="Suggestions for improvement", + default=[] + ) + + +class RefinerResponseSchema(BaseModel): + """Schema for refiner agent responses""" + refined_content: str = Field( + description="Refined content", + min_length=1 + ) + changes_made: List[str] = Field( + description="List of changes made", + default=[] + ) + reasoning: str = Field( + description="Reasoning behind refinements", + default="" + ) + confidence: float = Field( + description="Confidence in refinements", + ge=0.0, + le=1.0 + ) + feedback_addressed: List[str] = Field( + description="Feedback points addressed", + default=[] + ) \ No newline at end of file From 7f604b50f455496425265cdd691cbd9ac47dd81c Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Fri, 1 Aug 2025 20:32:43 +0300 Subject: [PATCH 03/28] Add files via upload --- ...rchical_structured_communication_agents.py | 816 ++++++++++++++++++ 1 file changed, 816 insertions(+) create mode 100644 swarms/agents/hierarchical_structured_communication_agents.py diff --git a/swarms/agents/hierarchical_structured_communication_agents.py b/swarms/agents/hierarchical_structured_communication_agents.py new file mode 100644 index 00000000..3bdcdf0c --- /dev/null +++ b/swarms/agents/hierarchical_structured_communication_agents.py @@ -0,0 +1,816 @@ +""" +Specialized Agents for Hierarchical Structured Communication Framework Framework + +This module provides specialized agent implementations for the HierarchicalStructuredCommunication framework, +including structured communication agents and hierarchical evaluation agents. +""" + +from typing import Any, Dict, List, Optional, Union +from loguru import logger + +from swarms.structs.agent import Agent +from swarms.schemas.talk_hierarchical_schemas import ( + StructuredMessageSchema, + EvaluationResultSchema, + GeneratorResponseSchema, + EvaluatorResponseSchema, + RefinerResponseSchema, + CommunicationType, + AgentRole +) + + +class HierarchicalStructuredCommunicationGenerator(Agent): + """ + Generator agent for Hierarchical Structured Communication Framework framework + + This agent specializes in creating initial content following the structured + communication protocol with Message (M_ij), Background (B_ij), and Intermediate Output (I_ij). + """ + + def __init__( + self, + agent_name: str = "TalkHierGenerator", + system_prompt: Optional[str] = None, + model_name: str = "gpt-4o-mini", + verbose: bool = False, + **kwargs + ): + """ + Initialize the HierarchicalStructuredCommunication Generator agent + + Args: + agent_name: Name of the agent + system_prompt: Custom system prompt + model_name: Model to use + verbose: Enable verbose logging + """ + if system_prompt is None: + system_prompt = self._get_default_generator_prompt() + + super().__init__( + agent_name=agent_name, + system_prompt=system_prompt, + model_name=model_name, + verbose=verbose, + **kwargs + ) + + def _get_default_generator_prompt(self) -> str: + """Get the default system prompt for generator agents""" + return """ +You are a Generator agent in a Hierarchical Structured Communication Framework framework. + +Your core responsibility is to create high-quality initial content based on structured input. + +**Structured Communication Protocol:** +- Message (M_ij): Specific task instructions you receive +- Background (B_ij): Context and problem background provided +- Intermediate Output (I_ij): Intermediate results to build upon + +**Your Process:** +1. **Analyze Input**: Carefully examine the message, background, and intermediate output +2. **Generate Content**: Create comprehensive, well-structured content +3. **Provide Intermediate Output**: Generate intermediate results for the next agent +4. **Structure Response**: Format your response clearly with reasoning and confidence + +**Quality Standards:** +- Comprehensive coverage of the task +- Clear structure and organization +- Logical flow and coherence +- Sufficient detail for evaluation +- Original and creative solutions + +**Response Format:** +``` +Content: [Your generated content] + +Intermediate Output: [Structured output for next agent] + +Reasoning: [Your reasoning process] + +Confidence: [0.0-1.0 confidence level] +``` + +Always maintain high quality and provide detailed, actionable content. +""" + + def generate_with_structure( + self, + message: str, + background: str = "", + intermediate_output: str = "", + **kwargs + ) -> GeneratorResponseSchema: + """ + Generate content using structured communication protocol + + Args: + message: Specific task message (M_ij) + background: Background context (B_ij) + intermediate_output: Intermediate output (I_ij) + + Returns: + GeneratorResponseSchema with structured response + """ + try: + # Construct structured prompt + prompt = self._construct_structured_prompt(message, background, intermediate_output) + + # Generate response + response = self.run(prompt, **kwargs) + + # Parse and structure response + return self._parse_generator_response(response) + + except Exception as e: + logger.error(f"Error in structured generation: {e}") + return GeneratorResponseSchema( + content=f"Error generating content: {e}", + intermediate_output="", + reasoning="Error occurred during generation", + confidence=0.0 + ) + + def _construct_structured_prompt( + self, + message: str, + background: str, + intermediate_output: str + ) -> str: + """Construct a structured prompt for generation""" + prompt_parts = [] + + if message: + prompt_parts.append(f"**Task Message (M_ij):** {message}") + + if background: + prompt_parts.append(f"**Background Context (B_ij):** {background}") + + if intermediate_output: + prompt_parts.append(f"**Intermediate Output (I_ij):** {intermediate_output}") + + prompt = "\n\n".join(prompt_parts) + prompt += "\n\nPlease generate content following the structured response format." + + return prompt + + def _parse_generator_response(self, response: str) -> GeneratorResponseSchema: + """Parse the generator response into structured format""" + try: + # Simple parsing - could be enhanced with more sophisticated parsing + lines = response.split('\n') + content = "" + intermediate_output = "" + reasoning = "" + confidence = 0.8 # Default confidence + + current_section = None + + for line in lines: + line = line.strip() + if not line: + continue + + if line.lower().startswith('content:'): + current_section = 'content' + content = line[8:].strip() + elif line.lower().startswith('intermediate output:'): + current_section = 'intermediate' + intermediate_output = line[20:].strip() + elif line.lower().startswith('reasoning:'): + current_section = 'reasoning' + reasoning = line[10:].strip() + elif line.lower().startswith('confidence:'): + try: + confidence = float(line[11:].strip()) + except ValueError: + confidence = 0.8 + elif current_section == 'content': + content += " " + line + elif current_section == 'intermediate': + intermediate_output += " " + line + elif current_section == 'reasoning': + reasoning += " " + line + + return GeneratorResponseSchema( + content=content or response, + intermediate_output=intermediate_output, + reasoning=reasoning, + confidence=confidence + ) + + except Exception as e: + logger.error(f"Error parsing generator response: {e}") + return GeneratorResponseSchema( + content=response, + intermediate_output="", + reasoning="Error parsing response", + confidence=0.5 + ) + + +class HierarchicalStructuredCommunicationEvaluator(Agent): + """ + Evaluator agent for Hierarchical Structured Communication Framework framework + + This agent specializes in evaluating content using specific criteria and + providing structured feedback following the hierarchical evaluation system. + """ + + def __init__( + self, + agent_name: str = "TalkHierEvaluator", + system_prompt: Optional[str] = None, + model_name: str = "gpt-4o-mini", + verbose: bool = False, + evaluation_criteria: List[str] = None, + **kwargs + ): + """ + Initialize the HierarchicalStructuredCommunication Evaluator agent + + Args: + agent_name: Name of the agent + system_prompt: Custom system prompt + model_name: Model to use + verbose: Enable verbose logging + evaluation_criteria: List of evaluation criteria this agent can assess + """ + if system_prompt is None: + system_prompt = self._get_default_evaluator_prompt(evaluation_criteria) + + super().__init__( + agent_name=agent_name, + system_prompt=system_prompt, + model_name=model_name, + verbose=verbose, + **kwargs + ) + + self.evaluation_criteria = evaluation_criteria or ["accuracy", "completeness", "clarity", "relevance"] + + def _get_default_evaluator_prompt(self, criteria: List[str] = None) -> str: + """Get the default system prompt for evaluator agents""" + if criteria is None: + criteria = ["accuracy", "completeness", "clarity", "relevance"] + + criteria_text = "\n".join([f"- {criterion}" for criterion in criteria]) + + return f""" +You are an Evaluator agent in a Hierarchical Structured Communication Framework framework. + +Your core responsibility is to evaluate content quality using specific criteria and provide structured feedback. + +**Evaluation Criteria:** +{criteria_text} + +**Evaluation Process:** +1. **Analyze Content**: Examine the content thoroughly +2. **Apply Criteria**: Evaluate against the specified criterion +3. **Score Performance**: Provide numerical score (0-10) +4. **Provide Feedback**: Give detailed, actionable feedback +5. **Assess Confidence**: Rate your confidence in the evaluation + +**Scoring Guidelines:** +- 9-10: Excellent - Outstanding quality, minimal issues +- 7-8: Good - High quality with minor improvements needed +- 5-6: Average - Adequate but significant improvements needed +- 3-4: Below Average - Major issues, substantial improvements required +- 1-2: Poor - Critical issues, extensive revision needed +- 0: Unacceptable - Fundamental problems + +**Response Format:** +``` +Criterion: [Evaluation criterion] + +Score: [0-10 numerical score] + +Feedback: [Detailed feedback] + +Confidence: [0.0-1.0 confidence level] + +Reasoning: [Your evaluation reasoning] + +Suggestions: [Specific improvement suggestions] +``` + +Be thorough, fair, and constructive in your evaluations. +""" + + def evaluate_with_criterion( + self, + content: str, + criterion: str, + **kwargs + ) -> EvaluatorResponseSchema: + """ + Evaluate content using a specific criterion + + Args: + content: Content to evaluate + criterion: Specific evaluation criterion + + Returns: + EvaluatorResponseSchema with evaluation results + """ + try: + # Construct evaluation prompt + prompt = self._construct_evaluation_prompt(content, criterion) + + # Get evaluation response + response = self.run(prompt, **kwargs) + + # Parse and structure response + return self._parse_evaluator_response(response, criterion) + + except Exception as e: + logger.error(f"Error in evaluation: {e}") + return EvaluatorResponseSchema( + criterion=criterion, + score=5.0, + feedback=f"Error during evaluation: {e}", + confidence=0.0, + reasoning="Error occurred during evaluation", + suggestions=["Fix technical issues", "Retry evaluation"] + ) + + def _construct_evaluation_prompt(self, content: str, criterion: str) -> str: + """Construct an evaluation prompt""" + return f""" +**Content to Evaluate:** +{content} + +**Evaluation Criterion:** +{criterion} + +Please evaluate the content above based on the {criterion} criterion. + +Provide your evaluation following the structured response format. +""" + + def _parse_evaluator_response(self, response: str, criterion: str) -> EvaluatorResponseSchema: + """Parse the evaluator response into structured format""" + try: + lines = response.split('\n') + score = 5.0 # Default score + feedback = "" + confidence = 0.8 # Default confidence + reasoning = "" + suggestions = [] + + current_section = None + + for line in lines: + line = line.strip() + if not line: + continue + + if line.lower().startswith('score:'): + try: + score = float(line[6:].strip()) + except ValueError: + score = 5.0 + elif line.lower().startswith('feedback:'): + current_section = 'feedback' + feedback = line[9:].strip() + elif line.lower().startswith('confidence:'): + try: + confidence = float(line[11:].strip()) + except ValueError: + confidence = 0.8 + elif line.lower().startswith('reasoning:'): + current_section = 'reasoning' + reasoning = line[10:].strip() + elif line.lower().startswith('suggestions:'): + current_section = 'suggestions' + elif current_section == 'feedback': + feedback += " " + line + elif current_section == 'reasoning': + reasoning += " " + line + elif current_section == 'suggestions': + if line.startswith('-') or line.startswith('•'): + suggestions.append(line[1:].strip()) + else: + suggestions.append(line) + + return EvaluatorResponseSchema( + criterion=criterion, + score=score, + feedback=feedback or "No feedback provided", + confidence=confidence, + reasoning=reasoning, + suggestions=suggestions + ) + + except Exception as e: + logger.error(f"Error parsing evaluator response: {e}") + return EvaluatorResponseSchema( + criterion=criterion, + score=5.0, + feedback="Error parsing evaluation response", + confidence=0.0, + reasoning="Error occurred during parsing", + suggestions=["Fix parsing issues"] + ) + + +class HierarchicalStructuredCommunicationRefiner(Agent): + """ + Refiner agent for Hierarchical Structured Communication Framework framework + + This agent specializes in improving content based on evaluation feedback + and maintaining the structured communication protocol. + """ + + def __init__( + self, + agent_name: str = "TalkHierRefiner", + system_prompt: Optional[str] = None, + model_name: str = "gpt-4o-mini", + verbose: bool = False, + **kwargs + ): + """ + Initialize the HierarchicalStructuredCommunication Refiner agent + + Args: + agent_name: Name of the agent + system_prompt: Custom system prompt + model_name: Model to use + verbose: Enable verbose logging + """ + if system_prompt is None: + system_prompt = self._get_default_refiner_prompt() + + super().__init__( + agent_name=agent_name, + system_prompt=system_prompt, + model_name=model_name, + verbose=verbose, + **kwargs + ) + + def _get_default_refiner_prompt(self) -> str: + """Get the default system prompt for refiner agents""" + return """ +You are a Refiner agent in a Hierarchical Structured Communication Framework framework. + +Your core responsibility is to improve content based on evaluation feedback while maintaining quality and addressing specific issues. + +**Refinement Process:** +1. **Analyze Original**: Understand the original content thoroughly +2. **Review Feedback**: Examine all evaluation feedback carefully +3. **Identify Issues**: Identify specific problems to address +4. **Make Improvements**: Enhance content while preserving strengths +5. **Justify Changes**: Explain why each improvement was made + +**Refinement Principles:** +- Address specific feedback points +- Maintain core strengths and structure +- Improve clarity and coherence +- Enhance completeness and accuracy +- Preserve original intent and purpose + +**Response Format:** +``` +Refined Content: [Your improved content] + +Changes Made: [List of specific changes] + +Reasoning: [Explanation of refinements] + +Confidence: [0.0-1.0 confidence in improvements] + +Feedback Addressed: [Which feedback points were addressed] +``` + +Focus on meaningful improvements that directly address the evaluation feedback. +""" + + def refine_with_feedback( + self, + original_content: str, + evaluation_results: List[EvaluationResultSchema], + **kwargs + ) -> RefinerResponseSchema: + """ + Refine content based on evaluation feedback + + Args: + original_content: Original content to refine + evaluation_results: List of evaluation results with feedback + + Returns: + RefinerResponseSchema with refined content + """ + try: + # Construct refinement prompt + prompt = self._construct_refinement_prompt(original_content, evaluation_results) + + # Get refinement response + response = self.run(prompt, **kwargs) + + # Parse and structure response + return self._parse_refiner_response(response, evaluation_results) + + except Exception as e: + logger.error(f"Error in refinement: {e}") + return RefinerResponseSchema( + refined_content=original_content, + changes_made=["Error occurred during refinement"], + reasoning=f"Error during refinement: {e}", + confidence=0.0, + feedback_addressed=[] + ) + + def _construct_refinement_prompt( + self, + original_content: str, + evaluation_results: List[EvaluationResultSchema] + ) -> str: + """Construct a refinement prompt""" + feedback_summary = "\n\n".join([ + f"**{result.criterion} (Score: {result.score}/10):**\n{result.feedback}" + for result in evaluation_results + ]) + + return f""" +**Original Content:** +{original_content} + +**Evaluation Feedback:** +{feedback_summary} + +Please refine the content to address the feedback while maintaining its core strengths. + +Provide your refinement following the structured response format. +""" + + def _parse_refiner_response( + self, + response: str, + evaluation_results: List[EvaluationResultSchema] + ) -> RefinerResponseSchema: + """Parse the refiner response into structured format""" + try: + lines = response.split('\n') + refined_content = "" + changes_made = [] + reasoning = "" + confidence = 0.8 # Default confidence + feedback_addressed = [] + + current_section = None + + for line in lines: + line = line.strip() + if not line: + continue + + if line.lower().startswith('refined content:'): + current_section = 'content' + refined_content = line[16:].strip() + elif line.lower().startswith('changes made:'): + current_section = 'changes' + elif line.lower().startswith('reasoning:'): + current_section = 'reasoning' + reasoning = line[10:].strip() + elif line.lower().startswith('confidence:'): + try: + confidence = float(line[11:].strip()) + except ValueError: + confidence = 0.8 + elif line.lower().startswith('feedback addressed:'): + current_section = 'feedback' + elif current_section == 'content': + refined_content += " " + line + elif current_section == 'changes': + if line.startswith('-') or line.startswith('•'): + changes_made.append(line[1:].strip()) + else: + changes_made.append(line) + elif current_section == 'reasoning': + reasoning += " " + line + elif current_section == 'feedback': + if line.startswith('-') or line.startswith('•'): + feedback_addressed.append(line[1:].strip()) + else: + feedback_addressed.append(line) + + # If no refined content found, use original + if not refined_content: + refined_content = response + + return RefinerResponseSchema( + refined_content=refined_content, + changes_made=changes_made, + reasoning=reasoning, + confidence=confidence, + feedback_addressed=feedback_addressed + ) + + except Exception as e: + logger.error(f"Error parsing refiner response: {e}") + return RefinerResponseSchema( + refined_content=response, + changes_made=["Error parsing response"], + reasoning="Error occurred during parsing", + confidence=0.0, + feedback_addressed=[] + ) + + +class HierarchicalStructuredCommunicationSupervisor(Agent): + """ + Supervisor agent for Hierarchical Structured Communication Framework framework + + This agent coordinates the overall workflow and manages structured communication + between different agent types. + """ + + def __init__( + self, + agent_name: str = "TalkHierSupervisor", + system_prompt: Optional[str] = None, + model_name: str = "gpt-4o-mini", + verbose: bool = False, + **kwargs + ): + """ + Initialize the HierarchicalStructuredCommunication Supervisor agent + + Args: + agent_name: Name of the agent + system_prompt: Custom system prompt + model_name: Model to use + verbose: Enable verbose logging + """ + if system_prompt is None: + system_prompt = self._get_default_supervisor_prompt() + + super().__init__( + agent_name=agent_name, + system_prompt=system_prompt, + model_name=model_name, + verbose=verbose, + **kwargs + ) + + def _get_default_supervisor_prompt(self) -> str: + """Get the default system prompt for supervisor agents""" + return """ +You are a Supervisor agent in a Hierarchical Structured Communication Framework framework. + +Your core responsibility is to coordinate the workflow and manage structured communication between agents. + +**Supervision Responsibilities:** +1. **Task Orchestration**: Coordinate between generator, evaluator, and refiner agents +2. **Structured Communication**: Ensure proper use of Message (M_ij), Background (B_ij), and Intermediate Output (I_ij) +3. **Workflow Management**: Manage the iterative refinement process +4. **Quality Control**: Monitor and ensure high-quality outputs +5. **Decision Making**: Determine when to continue refinement or stop + +**Communication Protocol:** +- Always provide structured messages with clear components +- Maintain context and background information +- Pass intermediate outputs between agents +- Ensure proper agent coordination + +**Decision Criteria:** +- Evaluation scores and feedback quality +- Content improvement progress +- Resource constraints and time limits +- Quality thresholds and standards + +**Response Format:** +``` +Next Action: [What should happen next] + +Target Agent: [Which agent should act] + +Structured Message: [Complete structured message] + +Background Context: [Context to provide] + +Intermediate Output: [Output to pass along] + +Reasoning: [Why this decision was made] +``` + +Focus on efficient coordination and high-quality outcomes. +""" + + def coordinate_workflow( + self, + task: str, + current_state: Dict[str, Any], + **kwargs + ) -> Dict[str, Any]: + """ + Coordinate the workflow and determine next actions + + Args: + task: Current task being processed + current_state: Current state of the workflow + + Returns: + Dictionary with coordination decisions + """ + try: + # Construct coordination prompt + prompt = self._construct_coordination_prompt(task, current_state) + + # Get coordination response + response = self.run(prompt, **kwargs) + + # Parse and structure response + return self._parse_coordination_response(response) + + except Exception as e: + logger.error(f"Error in workflow coordination: {e}") + return { + "next_action": "error", + "target_agent": "none", + "structured_message": f"Error in coordination: {e}", + "background_context": "", + "intermediate_output": "", + "reasoning": "Error occurred during coordination" + } + + def _construct_coordination_prompt(self, task: str, current_state: Dict[str, Any]) -> str: + """Construct a coordination prompt""" + state_summary = "\n".join([ + f"- {key}: {value}" + for key, value in current_state.items() + ]) + + return f""" +**Current Task:** +{task} + +**Current State:** +{state_summary} + +Please coordinate the workflow and determine the next action. + +Provide your coordination decision following the structured response format. +""" + + def _parse_coordination_response(self, response: str) -> Dict[str, Any]: + """Parse the coordination response""" + try: + lines = response.split('\n') + result = { + "next_action": "continue", + "target_agent": "generator", + "structured_message": "", + "background_context": "", + "intermediate_output": "", + "reasoning": "" + } + + current_section = None + + for line in lines: + line = line.strip() + if not line: + continue + + if line.lower().startswith('next action:'): + result["next_action"] = line[12:].strip() + elif line.lower().startswith('target agent:'): + result["target_agent"] = line[13:].strip() + elif line.lower().startswith('structured message:'): + current_section = 'message' + result["structured_message"] = line[19:].strip() + elif line.lower().startswith('background context:'): + current_section = 'background' + result["background_context"] = line[19:].strip() + elif line.lower().startswith('intermediate output:'): + current_section = 'output' + result["intermediate_output"] = line[20:].strip() + elif line.lower().startswith('reasoning:'): + current_section = 'reasoning' + result["reasoning"] = line[10:].strip() + elif current_section == 'message': + result["structured_message"] += " " + line + elif current_section == 'background': + result["background_context"] += " " + line + elif current_section == 'output': + result["intermediate_output"] += " " + line + elif current_section == 'reasoning': + result["reasoning"] += " " + line + + return result + + except Exception as e: + logger.error(f"Error parsing coordination response: {e}") + return { + "next_action": "error", + "target_agent": "none", + "structured_message": "Error parsing response", + "background_context": "", + "intermediate_output": "", + "reasoning": "Error occurred during parsing" + } From 11db60af4c300cfa47d397e6dd75202643b350bd Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Fri, 1 Aug 2025 20:36:15 +0300 Subject: [PATCH 04/28] Update __init__.py --- swarms/structs/__init__.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/swarms/structs/__init__.py b/swarms/structs/__init__.py index 0241a2c1..9ff022bc 100644 --- a/swarms/structs/__init__.py +++ b/swarms/structs/__init__.py @@ -92,6 +92,7 @@ from swarms.structs.swarming_architectures import ( staircase_swarm, star_swarm, ) +from swarms.structs.hierarchical_structured_communication_swarm import HierarchicalStructuredCommSwarm __all__ = [ "Agent", @@ -170,4 +171,5 @@ __all__ = [ "HierarchicalSwarm", "HeavySwarm", "CronJob", + "TalkHierarchicalSwarm", ] From fce92537f1ce3cb305426f313fa23a415b12ae73 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Fri, 1 Aug 2025 20:36:36 +0300 Subject: [PATCH 05/28] Update __init__.py --- swarms/agents/__init__.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/swarms/agents/__init__.py b/swarms/agents/__init__.py index 6617abb8..a0ef7378 100644 --- a/swarms/agents/__init__.py +++ b/swarms/agents/__init__.py @@ -11,6 +11,12 @@ from swarms.agents.reasoning_agents import ( agent_types, ) from swarms.agents.reasoning_duo import ReasoningDuo +from swarms.agents.hierarchical_structured_communication_agents import ( + HierarchicalStructuredCommGenerator, + HierarchicalStructuredCommEvaluator, + HierarchicalStructuredCommRefiner, + HierarchicalStructuredCommSupervisor, +) from swarms.structs.stopping_conditions import ( check_cancelled, check_complete, @@ -44,4 +50,8 @@ __all__ = [ "ReflexionAgent", "GKPAgent", "AgentJudge", + "TalkHierarchicalGenerator", + "TalkHierarchicalEvaluator", + "TalkHierarchicalRefiner", + "TalkHierarchicalSupervisor", ] From f68de40356252b02549a8d9f8c8e559f83cf4b99 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Fri, 1 Aug 2025 20:36:57 +0300 Subject: [PATCH 06/28] Update __init__.py --- swarms/schemas/__init__.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/swarms/schemas/__init__.py b/swarms/schemas/__init__.py index 7eb2ff5d..9d8dfa29 100644 --- a/swarms/schemas/__init__.py +++ b/swarms/schemas/__init__.py @@ -3,10 +3,16 @@ from swarms.schemas.mcp_schemas import ( MCPConnection, MultipleMCPConnections, ) +from swarms.schemas.hierarchical_structured_communication_schemas import ( + HierarchicalStructuredCommConnection, + MultipleHierarchicalStructuredCommConnections, +) __all__ = [ "Step", "ManySteps", "MCPConnection", "MultipleMCPConnections", + "HierarchicalStructuredCommConnection", + "MultipleHierarchicalStructuredCommConnections", ] From ab11c1c4f730cb01bf6e4ddfc39c5551eb9cc1af Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Fri, 1 Aug 2025 20:48:10 +0300 Subject: [PATCH 07/28] Add files via upload --- ...archical_structured_communication_swarm.md | 380 ++++++++++++++++++ 1 file changed, 380 insertions(+) create mode 100644 docs/swarms/structs/hierarchical_structured_communication_swarm.md diff --git a/docs/swarms/structs/hierarchical_structured_communication_swarm.md b/docs/swarms/structs/hierarchical_structured_communication_swarm.md new file mode 100644 index 00000000..0e71d7f9 --- /dev/null +++ b/docs/swarms/structs/hierarchical_structured_communication_swarm.md @@ -0,0 +1,380 @@ +# Talk Structurally, Act Hierarchically Framework + +## Overview + +The **Talk Structurally, Act Hierarchically** framework is a sophisticated multi-agent system that implements the research paper "Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems" (arXiv:2502.11098). This framework addresses key challenges in multi-agent systems through structured communication protocols and hierarchical evaluation systems. + +## Key Features + +### 1. Structured Communication Protocol +- **Message (M_ij)**: Specific task instructions with clear objectives +- **Background (B_ij)**: Context and problem background for comprehensive understanding +- **Intermediate Output (I_ij)**: Intermediate results passed between agents + +### 2. Hierarchical Refinement System +- **Evaluation Team**: Multiple specialized evaluators with different criteria +- **Supervisor Coordination**: Centralized coordination of evaluation processes +- **Summarized Feedback**: Consolidated, actionable feedback from multiple evaluators + +### 3. Graph-based Agent Orchestration +- **Dynamic Routing**: Flexible communication pathways based on task requirements +- **Context Preservation**: Maintains conversation history and shared memory +- **Iterative Refinement**: Multiple refinement loops for continuous improvement + +## Architecture + +```mermaid +graph TD + A[User Task] --> B[Supervisor Agent] + B --> C[Generator Agent] + C --> D[Evaluation Team Supervisor] + D --> E[Evaluator 1] + D --> F[Evaluator 2] + D --> G[Evaluator N] + E --> H[Summarized Feedback] + F --> H + G --> H + H --> I[Refiner Agent] + I --> J{Quality Threshold Met?} + J -->|No| C + J -->|Yes| K[Final Result] +``` + +## Components + +### TalkHierarchicalSwarm + +The main orchestrator class that manages the entire workflow. + +```python +from swarms.structs.talk_hierarchical_swarm import TalkHierarchicalSwarm + +swarm = TalkHierarchicalSwarm( + name="MyTalkHierSwarm", + supervisor=supervisor_agent, + generators=[generator_agent], + evaluators=[evaluator_agent1, evaluator_agent2], + refiners=[refiner_agent], + max_loops=3, + enable_structured_communication=True, + enable_hierarchical_evaluation=True +) +``` + +### Specialized Agents + +#### TalkHierarchicalGenerator +Creates initial content using structured communication protocol. + +```python +from swarms.agents.talk_hierarchical_agents import TalkHierarchicalGenerator + +generator = TalkHierarchicalGenerator( + agent_name="ContentGenerator", + model_name="gpt-4o-mini" +) + +# Generate with structured communication +result = generator.generate_with_structure( + message="Create technical documentation", + background="For software developers", + intermediate_output="Previous API overview" +) +``` + +#### TalkHierarchicalEvaluator +Evaluates content using specific criteria and provides structured feedback. + +```python +from swarms.agents.talk_hierarchical_agents import TalkHierarchicalEvaluator + +evaluator = TalkHierarchicalEvaluator( + agent_name="QualityEvaluator", + evaluation_criteria=["accuracy", "clarity", "completeness"] +) + +# Evaluate content +result = evaluator.evaluate_with_criterion( + content="Content to evaluate", + criterion="accuracy" +) +``` + +#### TalkHierarchicalRefiner +Improves content based on evaluation feedback. + +```python +from swarms.agents.talk_hierarchical_agents import TalkHierarchicalRefiner + +refiner = TalkHierarchicalRefiner( + agent_name="ContentRefiner" +) + +# Refine content +result = refiner.refine_with_feedback( + original_content="Original content", + evaluation_results=evaluation_results +) +``` + +#### TalkHierarchicalSupervisor +Coordinates workflow and manages structured communication. + +```python +from swarms.agents.talk_hierarchical_agents import TalkHierarchicalSupervisor + +supervisor = TalkHierarchicalSupervisor( + agent_name="WorkflowSupervisor" +) + +# Coordinate workflow +decision = supervisor.coordinate_workflow( + task="Current task", + current_state=workflow_state +) +``` + +## Usage Examples + +### Basic Usage + +```python +from swarms.structs.talk_hierarchical_swarm import TalkHierarchicalSwarm + +# Create the swarm +swarm = TalkHierarchicalSwarm( + name="DocumentationSwarm", + max_loops=3, + verbose=True +) + +# Run a task +result = swarm.run( + "Create comprehensive API documentation for a Python library" +) + +print(f"Final Result: {result['final_result']}") +print(f"Total Loops: {result['total_loops']}") +``` + +### Advanced Configuration + +```python +from swarms.agents.talk_hierarchical_agents import ( + TalkHierarchicalGenerator, + TalkHierarchicalEvaluator, + TalkHierarchicalRefiner, + TalkHierarchicalSupervisor +) + +# Create specialized agents +generator = TalkHierarchicalGenerator( + agent_name="TechWriter", + model_name="gpt-4o-mini" +) + +evaluator1 = TalkHierarchicalEvaluator( + agent_name="AccuracyChecker", + evaluation_criteria=["accuracy", "technical_correctness"] +) + +evaluator2 = TalkHierarchicalEvaluator( + agent_name="ClarityChecker", + evaluation_criteria=["clarity", "readability"] +) + +refiner = TalkHierarchicalRefiner( + agent_name="ContentImprover" +) + +supervisor = TalkHierarchicalSupervisor( + agent_name="ProjectManager" +) + +# Create swarm with custom agents +swarm = TalkHierarchicalSwarm( + name="CustomSwarm", + supervisor=supervisor, + generators=[generator], + evaluators=[evaluator1, evaluator2], + refiners=[refiner], + max_loops=5, + quality_threshold=8.5 +) +``` + +### Structured Communication Example + +```python +# Send structured message +structured_msg = swarm.send_structured_message( + sender="Supervisor", + recipient="Generator", + message="Create a technical blog post about machine learning", + background="Target audience: software engineers with basic ML knowledge", + intermediate_output="Previous discussion covered AI fundamentals" +) + +print(f"Message: {structured_msg.message}") +print(f"Background: {structured_msg.background}") +print(f"Intermediate Output: {structured_msg.intermediate_output}") +``` + +### Hierarchical Evaluation Example + +```python +# Run hierarchical evaluation +evaluation_results = swarm.run_hierarchical_evaluation( + content="Content to evaluate", + evaluation_criteria=["accuracy", "completeness", "clarity", "relevance"] +) + +for result in evaluation_results: + print(f"Evaluator: {result.evaluator_name}") + print(f"Criterion: {result.criterion}") + print(f"Score: {result.score}/10") + print(f"Feedback: {result.feedback}") +``` + +## Configuration Options + +### TalkHierarchicalSwarm Parameters + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `name` | str | "TalkHierarchicalSwarm" | Name of the swarm | +| `description` | str | "Talk Structurally, Act Hierarchically Framework" | Description | +| `supervisor` | Agent | None | Main supervisor agent | +| `generators` | List[Agent] | [] | List of generator agents | +| `evaluators` | List[Agent] | [] | List of evaluator agents | +| `refiners` | List[Agent] | [] | List of refiner agents | +| `evaluation_supervisor` | Agent | None | Evaluation team supervisor | +| `max_loops` | int | 3 | Maximum refinement loops | +| `output_type` | OutputType | "dict-all-except-first" | Output format | +| `supervisor_name` | str | "Supervisor" | Supervisor agent name | +| `evaluation_supervisor_name` | str | "EvaluationSupervisor" | Evaluation supervisor name | +| `verbose` | bool | False | Enable verbose logging | +| `enable_structured_communication` | bool | True | Enable structured communication | +| `enable_hierarchical_evaluation` | bool | True | Enable hierarchical evaluation | +| `shared_memory` | bool | True | Enable shared memory | + +### Evaluation Criteria + +Common evaluation criteria include: + +- **Accuracy**: Factual correctness and precision +- **Completeness**: Coverage of required topics +- **Clarity**: Readability and understandability +- **Relevance**: Appropriateness to the task +- **Coherence**: Logical flow and organization +- **Technical Correctness**: Proper technical details +- **Engagement**: Interest and appeal to audience + +## Best Practices + +### 1. Agent Configuration +- Use specialized agents for specific roles +- Configure evaluation criteria based on task requirements +- Set appropriate quality thresholds for your use case + +### 2. Communication Structure +- Always provide clear, specific messages (M_ij) +- Include relevant background context (B_ij) +- Pass meaningful intermediate outputs (I_ij) + +### 3. Evaluation Setup +- Use multiple evaluators with different criteria +- Ensure evaluation criteria are well-defined +- Set appropriate confidence thresholds + +### 4. Workflow Management +- Monitor conversation history for debugging +- Adjust max_loops based on task complexity +- Use quality thresholds to prevent unnecessary iterations + +## Performance Considerations + +### Optimization Tips +- Use appropriate model sizes for different agent roles +- Implement caching for repeated evaluations +- Monitor API usage and costs +- Use parallel evaluation when possible + +### Quality vs. Speed Trade-offs +- Higher quality thresholds require more iterations +- More evaluators provide better feedback but increase latency +- Structured communication adds overhead but improves results + +## Error Handling + +The framework includes comprehensive error handling: + +```python +try: + result = swarm.run(task) +except Exception as e: + print(f"Error in TalkHierarchical workflow: {e}") + # Handle error appropriately +``` + +## Integration with Other Swarms + +The TalkHierarchical framework can be integrated with other Swarms components: + +```python +from swarms.structs.talk_hierarchical_swarm import TalkHierarchicalSwarm +from swarms.structs.hiearchical_swarm import HierarchicalSwarm + +# Use TalkHierarchical for content generation +talk_hier = TalkHierarchicalSwarm() + +# Use HierarchicalSwarm for task orchestration +hierarchical = HierarchicalSwarm( + director=talk_hier.supervisor, + agents=[talk_hier.generators, talk_hier.evaluators, talk_hier.refiners] +) +``` + +## Research Background + +This implementation is based on the research paper: +- **Title**: "Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems" +- **Authors**: Zhao Wang, Moriyama Sota, Wei-Yao Wang, Briti Gangopadhyay, Shingo Takamatsu +- **arXiv**: 2502.11098 +- **Year**: 2025 + +The framework addresses key challenges in multi-agent systems: +- Context-poor communication leading to misunderstandings +- Sequential evaluation causing bias and incomplete feedback +- Lack of structured coordination between agents + +## Citation + +If you use this framework in your research, please cite: + +```bibtex +@misc{wang2025talkhier, + title={Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems}, + author={Zhao Wang and Sota Moriyama and Wei-Yao Wang and Briti Gangopadhyay and Shingo Takamatsu}, + year={2025}, + eprint={2502.11098}, + archivePrefix={arXiv}, + primaryClass={cs.AI} +} +``` + +## Contributing + +Contributions to improve the TalkHierarchical framework are welcome! Please: + +1. Follow the existing code style and patterns +2. Add comprehensive tests for new features +3. Update documentation for any changes +4. Ensure backward compatibility when possible + +## Support + +For questions and support: +- Check the examples in `examples/multi_agent/talk_hierarchical_example.py` +- Review the source code in `swarms/structs/talk_hierarchical_swarm.py` +- Examine the specialized agents in `swarms/agents/talk_hierarchical_agents.py` \ No newline at end of file From b55510ee174b1995275778465f18aee3275b2157 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Fri, 1 Aug 2025 20:50:33 +0300 Subject: [PATCH 08/28] Add files via upload --- ...rarchical_structured_communication_test.py | 718 ++++++++++++++++++ 1 file changed, 718 insertions(+) create mode 100644 examples/multi_agent/full_hierarchical_structured_communication_test.py diff --git a/examples/multi_agent/full_hierarchical_structured_communication_test.py b/examples/multi_agent/full_hierarchical_structured_communication_test.py new file mode 100644 index 00000000..4f6a33ea --- /dev/null +++ b/examples/multi_agent/full_hierarchical_structured_communication_test.py @@ -0,0 +1,718 @@ +""" +Full Hierarchical Structured Communication Framework Test with Ollama + +This script demonstrates the complete Hierarchical Structured Communication framework +using Ollama for local model inference. It showcases all components: +- Structured Communication Protocol +- Hierarchical Evaluation System +- Graph-based Agent Orchestration +- Iterative Refinement Process +""" + +import requests +import json +import time +import argparse +import sys +from typing import List, Dict, Any +from dataclasses import dataclass +from enum import Enum + +# Color support +try: + from colorama import init, Fore, Back, Style + init(autoreset=True) + COLORS_AVAILABLE = True +except ImportError: + # Fallback for systems without colorama + class Fore: + RED = GREEN = BLUE = YELLOW = MAGENTA = CYAN = WHITE = "" + class Back: + BLACK = RED = GREEN = BLUE = YELLOW = MAGENTA = CYAN = WHITE = "" + class Style: + BRIGHT = DIM = NORMAL = RESET_ALL = "" + COLORS_AVAILABLE = False + +class CommunicationType(str, Enum): + """Types of communication in the structured protocol""" + MESSAGE = "message" # M_ij: Specific task instructions + BACKGROUND = "background" # B_ij: Context and problem background + INTERMEDIATE_OUTPUT = "intermediate_output" # I_ij: Intermediate results + +@dataclass +class StructuredMessage: + """Structured communication message following HierarchicalStructuredComm protocol""" + message: str + background: str + intermediate_output: str + sender: str + recipient: str + timestamp: str = None + +@dataclass +class EvaluationResult: + """Result from evaluation team member""" + evaluator_name: str + criterion: str + score: float + feedback: str + confidence: float + +class HierarchicalStructuredCommunicationFramework: + """ + Full implementation of Hierarchical Structured Communication framework + using direct Ollama API calls + """ + + def __init__(self, model_name: str = "llama3:latest", verbose: bool = True, max_display_length: int = None): + self.model_name = model_name + self.verbose = verbose + self.max_display_length = max_display_length + self.conversation_history: List[StructuredMessage] = [] + self.intermediate_outputs: Dict[str, str] = {} + self.evaluation_results: List[EvaluationResult] = [] + + # Check Ollama availability + self._check_ollama() + + def _print_colored(self, text: str, color: str = Fore.WHITE, style: str = Style.NORMAL): + """Print colored text if colors are available""" + if COLORS_AVAILABLE: + print(f"{color}{style}{text}{Style.RESET_ALL}") + else: + print(text) + + def _print_header(self, text: str): + """Print a header with styling""" + self._print_colored(f"\n{text}", Fore.CYAN, Style.BRIGHT) + self._print_colored("=" * len(text), Fore.CYAN) + + def _print_subheader(self, text: str): + """Print a subheader with styling""" + self._print_colored(f"\n{text}", Fore.YELLOW, Style.BRIGHT) + self._print_colored("-" * len(text), Fore.YELLOW) + + def _print_success(self, text: str): + """Print success message""" + self._print_colored(text, Fore.GREEN, Style.BRIGHT) + + def _print_error(self, text: str): + """Print error message""" + self._print_colored(text, Fore.RED, Style.BRIGHT) + + def _print_info(self, text: str): + """Print info message""" + self._print_colored(text, Fore.BLUE) + + def _print_warning(self, text: str): + """Print warning message""" + self._print_colored(text, Fore.YELLOW) + + def _truncate_text(self, text: str, max_length: int = None) -> str: + """Truncate text for display if needed""" + if max_length is None: + max_length = self.max_display_length + + if max_length and len(text) > max_length: + return text[:max_length] + "..." + return text + + def _check_ollama(self): + """Check if Ollama is running and get available models""" + try: + response = requests.get("http://localhost:11434/api/tags", timeout=5) + if response.status_code == 200: + models = response.json().get('models', []) + model_names = [model.get('name') for model in models] + + if self.verbose: + self._print_success("Ollama is running") + self._print_info(f"Available models: {', '.join(model_names)}") + + # Verify our model is available + if not any(self.model_name in name for name in model_names): + self._print_warning(f"Model {self.model_name} not found, using first available") + self.model_name = model_names[0] if model_names else "llama3:latest" + + self._print_info(f"Using model: {self.model_name}") + else: + raise Exception("Ollama not responding properly") + except Exception as e: + self._print_error(f"Cannot connect to Ollama: {e}") + self._print_info("Please ensure Ollama is running: ollama serve") + raise + + def _call_ollama(self, prompt: str, temperature: float = 0.7, max_tokens: int = 1000) -> str: + """Make a call to Ollama API with infinite timeout""" + try: + payload = { + "model": self.model_name, + "prompt": prompt, + "stream": False, + "options": { + "temperature": temperature, + "num_predict": max_tokens + } + } + + # Set timeout to None for infinite timeout + response = requests.post( + "http://localhost:11434/api/generate", + json=payload, + timeout=None + ) + + if response.status_code == 200: + return response.json().get('response', '') + else: + raise Exception(f"Ollama API error: {response.status_code}") + + except Exception as e: + self._print_error(f"Error calling Ollama: {e}") + return f"Error: {e}" + + def send_structured_message( + self, + sender: str, + recipient: str, + message: str, + background: str = "", + intermediate_output: str = "" + ) -> StructuredMessage: + """Send a structured message following the HierarchicalStructuredComm protocol""" + structured_msg = StructuredMessage( + message=message, + background=background, + intermediate_output=intermediate_output, + sender=sender, + recipient=recipient, + timestamp=time.strftime("%Y-%m-%d %H:%M:%S") + ) + + self.conversation_history.append(structured_msg) + + if self.verbose: + display_message = self._truncate_text(message, 100) + self._print_info(f"{sender} -> {recipient}: {display_message}") + + return structured_msg + + def generate_content(self, task: str, context: str = "") -> str: + """Generate initial content using generator agent""" + if self.verbose: + self._print_subheader("Step 1: Generating initial content") + + # Create structured message + message = f"Generate comprehensive content for: {task}" + background = f"Task: {task}\nContext: {context}\n\nProvide detailed, well-structured content." + + self.send_structured_message( + sender="Supervisor", + recipient="Generator", + message=message, + background=background + ) + + # Generate content + prompt = f"""You are a Content Generator in a Hierarchical Structured Communication framework. + +Task: {task} +Context: {context} + +Generate comprehensive, well-structured content that addresses the task thoroughly. +Provide detailed explanations, examples, and insights. + +Content:""" + + result = self._call_ollama(prompt, temperature=0.7, max_tokens=1500) + self.intermediate_outputs["generator"] = result + + if self.verbose: + self._print_info("Generated content:") + print(result) # Print full content without truncation + + return result + + def evaluate_content(self, content: str, criteria: List[str] = None) -> List[EvaluationResult]: + """Evaluate content using hierarchical evaluation system""" + if criteria is None: + criteria = ["accuracy", "completeness", "clarity", "relevance"] + + if self.verbose: + self._print_subheader("Step 2: Hierarchical evaluation") + + results = [] + + for criterion in criteria: + if self.verbose: + self._print_info(f" Evaluating {criterion}...") + + # Create structured message for evaluator + message = f"Evaluate content for {criterion} criterion" + background = f"Content to evaluate: {content[:500]}...\nCriterion: {criterion}" + + self.send_structured_message( + sender="EvaluationSupervisor", + recipient=f"{criterion.capitalize()}Evaluator", + message=message, + background=background, + intermediate_output=content + ) + + # Evaluate with specific criterion + prompt = f"""You are a {criterion.capitalize()} Evaluator in a hierarchical evaluation system. + +Content to evaluate: +{content} + +Evaluation criterion: {criterion} + +Please provide: +1. Score (0-10) +2. Detailed feedback +3. Confidence level (0-1) +4. Specific suggestions for improvement + +Evaluation:""" + + evaluation_response = self._call_ollama(prompt, temperature=0.3, max_tokens=800) + + # Parse evaluation (simplified parsing) + score = 7.0 # Default score + feedback = evaluation_response + confidence = 0.8 # Default confidence + + # Try to extract score from response + if "score" in evaluation_response.lower(): + try: + # Look for patterns like "score: 8" or "8/10" + import re + score_match = re.search(r'(\d+(?:\.\d+)?)/10|score[:\s]*(\d+(?:\.\d+)?)', evaluation_response.lower()) + if score_match: + score = float(score_match.group(1) or score_match.group(2)) + except: + pass + + result = EvaluationResult( + evaluator_name=f"{criterion.capitalize()}Evaluator", + criterion=criterion, + score=score, + feedback=feedback, + confidence=confidence + ) + + results.append(result) + + if self.verbose: + self._print_info(f" Score: {score}/10") + print(f" Feedback: {feedback}") # Print full feedback + + self.evaluation_results.extend(results) + return results + + def refine_content(self, original_content: str, evaluation_results: List[EvaluationResult]) -> str: + """Refine content based on evaluation feedback""" + if self.verbose: + self._print_subheader("Step 3: Refining content") + + # Create feedback summary + feedback_summary = "\n\n".join([ + f"{result.criterion.capitalize()} (Score: {result.score}/10):\n{result.feedback}" + for result in evaluation_results + ]) + + # Create structured message for refinement + message = "Refine content based on evaluation feedback" + background = f"Original content: {original_content[:500]}...\n\nEvaluation feedback:\n{feedback_summary}" + + self.send_structured_message( + sender="Supervisor", + recipient="Refiner", + message=message, + background=background, + intermediate_output=original_content + ) + + # Refine content + prompt = f"""You are a Content Refiner in a Hierarchical Structured Communication framework. + +Original Content: +{original_content} + +Evaluation Feedback: +{feedback_summary} + +Please refine the content to address the feedback while maintaining its core strengths. +Focus on the specific issues mentioned in the evaluation and provide improvements. + +Refined Content:""" + + refined_result = self._call_ollama(prompt, temperature=0.5, max_tokens=1500) + self.intermediate_outputs["refiner"] = refined_result + + if self.verbose: + self._print_info("Refined content:") + print(refined_result) # Print full content without truncation + + return refined_result + + def run_hierarchical_workflow(self, task: str, max_iterations: int = 3, quality_threshold: float = 8.0) -> Dict[str, Any]: + """Run the complete Hierarchical Structured Communication workflow""" + self._print_header("Starting Hierarchical Structured Communication Workflow") + self._print_info(f"Task: {task}") + self._print_info(f"Max iterations: {max_iterations}") + self._print_info(f"Quality threshold: {quality_threshold}") + + start_time = time.time() + current_content = None + iteration = 0 + + for iteration in range(max_iterations): + self._print_subheader(f"Iteration {iteration + 1}/{max_iterations}") + + # Step 1: Generate/Refine content + if iteration == 0: + current_content = self.generate_content(task) + else: + current_content = self.refine_content(current_content, evaluation_results) + + # Step 2: Evaluate content + evaluation_results = self.evaluate_content(current_content) + + # Step 3: Check quality threshold + avg_score = sum(result.score for result in evaluation_results) / len(evaluation_results) + self._print_info(f"Average evaluation score: {avg_score:.2f}/10") + + if avg_score >= quality_threshold: + self._print_success("Quality threshold met! Stopping refinement.") + break + + if iteration < max_iterations - 1: + self._print_info("Continuing refinement...") + + total_time = time.time() - start_time + + return { + "final_content": current_content, + "total_iterations": iteration + 1, + "average_score": avg_score, + "evaluation_results": evaluation_results, + "conversation_history": self.conversation_history, + "intermediate_outputs": self.intermediate_outputs, + "total_time": total_time + } + + def print_workflow_summary(self, result: Dict[str, Any]): + """Print a comprehensive summary of the workflow results""" + self._print_header("TALK HIERARCHICAL WORKFLOW COMPLETED") + + self._print_subheader("PERFORMANCE SUMMARY") + self._print_info(f" Total iterations: {result['total_iterations']}") + self._print_info(f" Final average score: {result['average_score']:.2f}/10") + self._print_info(f" Total time: {result['total_time']:.2f} seconds") + self._print_info(f" Messages exchanged: {len(result['conversation_history'])}") + + self._print_subheader("FINAL CONTENT") + print(result['final_content']) + + self._print_subheader("EVALUATION RESULTS") + for eval_result in result['evaluation_results']: + self._print_info(f" {eval_result.criterion.capitalize()}: {eval_result.score}/10") + print(f" Feedback: {eval_result.feedback}") + + self._print_subheader("COMMUNICATION HISTORY") + for i, msg in enumerate(result['conversation_history']): + self._print_info(f" {i+1}. {msg.sender} -> {msg.recipient}") + print(f" Message: {msg.message}") + print(f" Background: {msg.background}") + print(f" Intermediate Output: {msg.intermediate_output}") + print(f" Time: {msg.timestamp}") + +def test_basic_workflow(): + """Test basic Hierarchical Structured Communication workflow""" + print("Test 1: Basic Workflow") + print("=" * 50) + + framework = HierarchicalStructuredCommunicationFramework(model_name="llama3:latest", verbose=True) + + task = "Explain the concept of neural networks and their applications in modern AI" + + result = framework.run_hierarchical_workflow( + task=task, + max_iterations=2, + quality_threshold=7.5 + ) + + framework.print_workflow_summary(result) + return result + +def test_complex_workflow(): + """Test complex workflow with multiple iterations""" + print("Test 2: Complex Workflow") + print("=" * 50) + + framework = HierarchicalStructuredCommunicationFramework(model_name="llama3:latest", verbose=True) + + task = """Create a comprehensive guide on machine learning that covers: +1. Basic concepts and definitions +2. Types of machine learning (supervised, unsupervised, reinforcement) +3. Common algorithms and their use cases +4. Real-world applications and examples +5. Future trends and challenges + +Make it suitable for both beginners and intermediate learners.""" + + result = framework.run_hierarchical_workflow( + task=task, + max_iterations=3, + quality_threshold=8.0 + ) + + framework.print_workflow_summary(result) + return result + +def test_structured_communication(): + """Test structured communication protocol in isolation""" + print("Test 3: Structured Communication Protocol") + print("=" * 50) + + framework = HierarchicalStructuredCommunicationFramework(model_name="llama3:latest", verbose=True) + + # Test structured message exchange + msg1 = framework.send_structured_message( + sender="Supervisor", + recipient="Generator", + message="Generate content about renewable energy", + background="Focus on solar and wind power", + intermediate_output="Previous discussion covered climate change" + ) + + msg2 = framework.send_structured_message( + sender="Generator", + recipient="Evaluator", + message="Content ready for evaluation", + background="Generated comprehensive guide on renewable energy", + intermediate_output="Detailed explanation of solar and wind technologies" + ) + + print("Structured Messages:") + for i, msg in enumerate(framework.conversation_history): + print(f"Message {i+1}:") + print(f" From: {msg.sender}") + print(f" To: {msg.recipient}") + print(f" Message (M_ij): {msg.message}") + print(f" Background (B_ij): {msg.background}") + print(f" Intermediate Output (I_ij): {msg.intermediate_output}") + print(f" Timestamp: {msg.timestamp}") + +def test_quick_demo(): + """Quick demonstration with smaller model and shorter prompts""" + print("Test 4: Quick Demo") + print("=" * 50) + + # Use a smaller model for faster response + framework = HierarchicalStructuredCommunicationFramework(model_name="llama3.2:3b", verbose=True) + + task = "Explain what artificial intelligence is in simple terms" + + result = framework.run_hierarchical_workflow( + task=task, + max_iterations=1, + quality_threshold=6.0 + ) + + framework.print_workflow_summary(result) + return result + +def interactive_mode(): + """Interactive mode for custom tasks""" + print("Interactive Hierarchical Structured Communication Framework") + print("=" * 50) + + # Get user input + model_name = input("Enter model name (default: llama3:latest): ").strip() or "llama3:latest" + task = input("Enter your task: ").strip() + + if not task: + print("No task provided. Exiting.") + return + + max_iterations = input("Enter max iterations (default: 2): ").strip() + max_iterations = int(max_iterations) if max_iterations.isdigit() else 2 + + quality_threshold = input("Enter quality threshold (default: 7.0): ").strip() + quality_threshold = float(quality_threshold) if quality_threshold.replace('.', '').isdigit() else 7.0 + + # Create framework and run + framework = HierarchicalStructuredCommunicationFramework(model_name=model_name, verbose=True) + + result = framework.run_hierarchical_workflow( + task=task, + max_iterations=max_iterations, + quality_threshold=quality_threshold + ) + + framework.print_workflow_summary(result) + return result + +def main(): + """Main CLI entry point""" + parser = argparse.ArgumentParser( + description="Hierarchical Structured Communication Framework Test Suite", + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog=""" +Examples: + python full_hierarchical_structured_communication_test.py --quick + python full_hierarchical_structured_communication_test.py --interactive + python full_hierarchical_structured_communication_test.py --model llama3.2:3b --task "Explain AI" + python full_hierarchical_structured_communication_test.py --all + """ + ) + + parser.add_argument( + "--quick", + action="store_true", + help="Run quick demo test" + ) + + parser.add_argument( + "--basic", + action="store_true", + help="Run basic workflow test" + ) + + parser.add_argument( + "--complex", + action="store_true", + help="Run complex workflow test" + ) + + parser.add_argument( + "--communication", + action="store_true", + help="Run structured communication test" + ) + + parser.add_argument( + "--all", + action="store_true", + help="Run all tests" + ) + + parser.add_argument( + "--interactive", + action="store_true", + help="Run in interactive mode" + ) + + parser.add_argument( + "--model", + type=str, + default="llama3:latest", + help="Ollama model to use (default: llama3:latest)" + ) + + parser.add_argument( + "--task", + type=str, + help="Custom task for single run" + ) + + parser.add_argument( + "--iterations", + type=int, + default=2, + help="Maximum iterations (default: 2)" + ) + + parser.add_argument( + "--threshold", + type=float, + default=7.0, + help="Quality threshold (default: 7.0)" + ) + + parser.add_argument( + "--no-color", + action="store_true", + help="Disable colored output" + ) + + parser.add_argument( + "--quiet", + action="store_true", + help="Disable verbose output (verbose is enabled by default)" + ) + + args = parser.parse_args() + + # Disable colors if requested + global COLORS_AVAILABLE + if args.no_color: + COLORS_AVAILABLE = False + + # Print header + if COLORS_AVAILABLE: + print(f"{Fore.CYAN}{Style.BRIGHT}") + print("=" * 80) + print("TALK HIERARCHICAL FRAMEWORK TEST SUITE") + print("=" * 80) + print(f"{Style.RESET_ALL}") + else: + print("=" * 80) + print("TALK HIERARCHICAL FRAMEWORK TEST SUITE") + print("=" * 80) + + print("Testing Hierarchical Structured Communication framework with Ollama") + print("=" * 80) + + try: + if args.interactive: + interactive_mode() + elif args.task: + # Single task run + framework = HierarchicalStructuredCommunicationFramework( + model_name=args.model, + verbose=not args.quiet + ) + result = framework.run_hierarchical_workflow( + task=args.task, + max_iterations=args.iterations, + quality_threshold=args.threshold + ) + framework.print_workflow_summary(result) + elif args.quick: + test_quick_demo() + elif args.basic: + test_basic_workflow() + elif args.complex: + test_complex_workflow() + elif args.communication: + test_structured_communication() + elif args.all: + # Run all tests + test_quick_demo() + test_basic_workflow() + test_complex_workflow() + test_structured_communication() + else: + # Default: run quick demo + test_quick_demo() + + print("All tests completed successfully!") + print("Framework Features Demonstrated:") + print(" Structured Communication Protocol (M_ij, B_ij, I_ij)") + print(" Hierarchical Evaluation System") + print(" Iterative Refinement Process") + print(" Graph-based Agent Orchestration") + print(" Local Ollama Integration") + + except KeyboardInterrupt: + print("\nInterrupted by user") + except Exception as e: + print(f"Error during testing: {e}") + import traceback + traceback.print_exc() + +if __name__ == "__main__": + main() \ No newline at end of file From d8b1b5bc9ef97f5f79fef421679250093d79a8eb Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Fri, 1 Aug 2025 20:51:09 +0300 Subject: [PATCH 09/28] Update requirements.txt --- requirements.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/requirements.txt b/requirements.txt index ead3af6e..8c2e3392 100644 --- a/requirements.txt +++ b/requirements.txt @@ -27,4 +27,5 @@ aiohttp mcp numpy openai -schedule \ No newline at end of file +schedule +colorama From 35f7e890b636bfb3b951cf62b0628997481370e4 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Mon, 18 Aug 2025 22:45:01 +0300 Subject: [PATCH 10/28] Delete swarms/schemas/hierarchical_structured_communication_schemas.py --- ...chical_structured_communication_schemas.py | 430 ------------------ 1 file changed, 430 deletions(-) delete mode 100644 swarms/schemas/hierarchical_structured_communication_schemas.py diff --git a/swarms/schemas/hierarchical_structured_communication_schemas.py b/swarms/schemas/hierarchical_structured_communication_schemas.py deleted file mode 100644 index bf18fdff..00000000 --- a/swarms/schemas/hierarchical_structured_communication_schemas.py +++ /dev/null @@ -1,430 +0,0 @@ -""" -Schemas for Talk Structurally, Act Hierarchically Framework - -This module defines the Pydantic schemas used in the TalkHierarchical framework -for structured communication and hierarchical evaluation. -""" - -from typing import Dict, List, Optional, Union -from pydantic import BaseModel, Field -from enum import Enum - - -class CommunicationType(str, Enum): - """Types of communication in the structured protocol""" - MESSAGE = "message" # M_ij: Specific task instructions - BACKGROUND = "background" # B_ij: Context and problem background - INTERMEDIATE_OUTPUT = "intermediate_output" # I_ij: Intermediate results - - -class AgentRole(str, Enum): - """Roles for agents in the hierarchical system""" - SUPERVISOR = "supervisor" - GENERATOR = "generator" - EVALUATOR = "evaluator" - REFINER = "refiner" - COORDINATOR = "coordinator" - - -class StructuredMessageSchema(BaseModel): - """Schema for structured communication messages""" - message: str = Field( - description="Specific task instructions (M_ij)", - min_length=1 - ) - background: str = Field( - description="Context and problem background (B_ij)", - default="" - ) - intermediate_output: str = Field( - description="Intermediate results (I_ij)", - default="" - ) - sender: str = Field( - description="Name of the sending agent", - min_length=1 - ) - recipient: str = Field( - description="Name of the receiving agent", - min_length=1 - ) - timestamp: Optional[str] = Field( - description="Timestamp of the message", - default=None - ) - communication_type: CommunicationType = Field( - description="Type of communication", - default=CommunicationType.MESSAGE - ) - - -class HierarchicalOrderSchema(BaseModel): - """Schema for hierarchical task orders""" - agent_name: str = Field( - description="Name of the agent to receive the task", - min_length=1 - ) - task: str = Field( - description="Specific task description", - min_length=1 - ) - communication_type: CommunicationType = Field( - description="Type of communication to use", - default=CommunicationType.MESSAGE - ) - background_context: str = Field( - description="Background context for the task", - default="" - ) - intermediate_output: str = Field( - description="Intermediate output to pass along", - default="" - ) - priority: int = Field( - description="Task priority (1-10, higher is more important)", - default=5, - ge=1, - le=10 - ) - - -class EvaluationCriterionSchema(BaseModel): - """Schema for evaluation criteria""" - name: str = Field( - description="Name of the evaluation criterion", - min_length=1 - ) - description: str = Field( - description="Description of what this criterion evaluates", - min_length=1 - ) - weight: float = Field( - description="Weight of this criterion in overall evaluation (0-1)", - default=1.0, - ge=0.0, - le=1.0 - ) - scale: str = Field( - description="Scale for evaluation (e.g., '0-10', 'A-F', 'Poor-Excellent')", - default="0-10" - ) - - -class EvaluationResultSchema(BaseModel): - """Schema for evaluation results""" - evaluator_name: str = Field( - description="Name of the evaluator", - min_length=1 - ) - criterion: str = Field( - description="Evaluation criterion", - min_length=1 - ) - score: float = Field( - description="Evaluation score", - ge=0.0 - ) - feedback: str = Field( - description="Detailed feedback", - min_length=1 - ) - confidence: float = Field( - description="Confidence in evaluation (0-1)", - ge=0.0, - le=1.0 - ) - reasoning: str = Field( - description="Reasoning behind the evaluation", - default="" - ) - suggestions: List[str] = Field( - description="Suggestions for improvement", - default=[] - ) - - -class EvaluationSummarySchema(BaseModel): - """Schema for evaluation summaries""" - overall_score: float = Field( - description="Overall evaluation score", - ge=0.0 - ) - criterion_scores: Dict[str, float] = Field( - description="Scores for each criterion", - default={} - ) - strengths: List[str] = Field( - description="Identified strengths", - default=[] - ) - weaknesses: List[str] = Field( - description="Identified weaknesses", - default=[] - ) - recommendations: List[str] = Field( - description="Recommendations for improvement", - default=[] - ) - confidence: float = Field( - description="Overall confidence in evaluation", - ge=0.0, - le=1.0 - ) - - -class AgentConfigSchema(BaseModel): - """Schema for agent configuration""" - name: str = Field( - description="Name of the agent", - min_length=1 - ) - role: AgentRole = Field( - description="Role of the agent in the system" - ) - model_name: str = Field( - description="Model to use for this agent", - default="gpt-4o-mini" - ) - system_prompt: str = Field( - description="System prompt for the agent", - min_length=1 - ) - tools: List[str] = Field( - description="Tools available to this agent", - default=[] - ) - capabilities: List[str] = Field( - description="Capabilities of this agent", - default=[] - ) - evaluation_criteria: List[str] = Field( - description="Evaluation criteria this agent can assess", - default=[] - ) - - -class TalkHierarchicalConfigSchema(BaseModel): - """Schema for TalkHierarchical swarm configuration""" - name: str = Field( - description="Name of the swarm", - default="TalkHierarchicalSwarm" - ) - description: str = Field( - description="Description of the swarm", - default="Talk Structurally, Act Hierarchically Framework" - ) - max_loops: int = Field( - description="Maximum number of refinement loops", - default=3, - ge=1 - ) - enable_structured_communication: bool = Field( - description="Enable structured communication protocol", - default=True - ) - enable_hierarchical_evaluation: bool = Field( - description="Enable hierarchical evaluation system", - default=True - ) - shared_memory: bool = Field( - description="Enable shared memory between agents", - default=True - ) - evaluation_criteria: List[EvaluationCriterionSchema] = Field( - description="Evaluation criteria for the system", - default=[] - ) - agents: List[AgentConfigSchema] = Field( - description="Configuration for all agents", - default=[] - ) - quality_threshold: float = Field( - description="Quality threshold for stopping refinement", - default=8.0, - ge=0.0, - le=10.0 - ) - - -class TalkHierarchicalStateSchema(BaseModel): - """Schema for TalkHierarchical swarm state""" - conversation_history: List[StructuredMessageSchema] = Field( - description="History of structured messages", - default=[] - ) - intermediate_outputs: Dict[str, str] = Field( - description="Intermediate outputs from agents", - default={} - ) - evaluation_results: List[EvaluationResultSchema] = Field( - description="Results from evaluations", - default=[] - ) - current_loop: int = Field( - description="Current refinement loop", - default=0 - ) - task: str = Field( - description="Current task being processed", - default="" - ) - final_result: Optional[str] = Field( - description="Final result of the workflow", - default=None - ) - - -class TalkHierarchicalResponseSchema(BaseModel): - """Schema for TalkHierarchical swarm response""" - final_result: str = Field( - description="Final result of the workflow" - ) - total_loops: int = Field( - description="Total number of loops executed", - ge=1 - ) - conversation_history: List[StructuredMessageSchema] = Field( - description="Complete conversation history" - ) - evaluation_results: List[EvaluationResultSchema] = Field( - description="All evaluation results" - ) - intermediate_outputs: Dict[str, str] = Field( - description="All intermediate outputs" - ) - evaluation_summary: Optional[EvaluationSummarySchema] = Field( - description="Summary of evaluations", - default=None - ) - performance_metrics: Dict[str, Union[float, int, str]] = Field( - description="Performance metrics", - default={} - ) - - -class GraphNodeSchema(BaseModel): - """Schema for graph nodes in agent orchestration""" - node_id: str = Field( - description="Unique identifier for the node", - min_length=1 - ) - agent_name: str = Field( - description="Name of the agent at this node", - min_length=1 - ) - role: AgentRole = Field( - description="Role of the agent" - ) - capabilities: List[str] = Field( - description="Capabilities of this node", - default=[] - ) - connections: List[str] = Field( - description="IDs of connected nodes", - default=[] - ) - conditions: Dict[str, str] = Field( - description="Conditions for routing to this node", - default={} - ) - - -class GraphSchema(BaseModel): - """Schema for agent orchestration graph""" - nodes: List[GraphNodeSchema] = Field( - description="Nodes in the graph", - default=[] - ) - start_node: str = Field( - description="ID of the start node", - min_length=1 - ) - end_nodes: List[str] = Field( - description="IDs of end nodes", - default=[] - ) - routing_rules: Dict[str, str] = Field( - description="Rules for routing between nodes", - default={} - ) - max_depth: int = Field( - description="Maximum depth of the graph", - default=10, - ge=1 - ) - - -# Response schemas for different agent types -class GeneratorResponseSchema(BaseModel): - """Schema for generator agent responses""" - content: str = Field( - description="Generated content", - min_length=1 - ) - intermediate_output: str = Field( - description="Intermediate output for next agent", - default="" - ) - reasoning: str = Field( - description="Reasoning behind the generation", - default="" - ) - confidence: float = Field( - description="Confidence in the generated content", - ge=0.0, - le=1.0 - ) - - -class EvaluatorResponseSchema(BaseModel): - """Schema for evaluator agent responses""" - criterion: str = Field( - description="Evaluation criterion", - min_length=1 - ) - score: float = Field( - description="Evaluation score", - ge=0.0 - ) - feedback: str = Field( - description="Detailed feedback", - min_length=1 - ) - confidence: float = Field( - description="Confidence in evaluation", - ge=0.0, - le=1.0 - ) - reasoning: str = Field( - description="Reasoning behind the evaluation", - default="" - ) - suggestions: List[str] = Field( - description="Suggestions for improvement", - default=[] - ) - - -class RefinerResponseSchema(BaseModel): - """Schema for refiner agent responses""" - refined_content: str = Field( - description="Refined content", - min_length=1 - ) - changes_made: List[str] = Field( - description="List of changes made", - default=[] - ) - reasoning: str = Field( - description="Reasoning behind refinements", - default="" - ) - confidence: float = Field( - description="Confidence in refinements", - ge=0.0, - le=1.0 - ) - feedback_addressed: List[str] = Field( - description="Feedback points addressed", - default=[] - ) \ No newline at end of file From 61dd0b2046b7e0315046b6139cd646b781205046 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Mon, 18 Aug 2025 22:45:20 +0300 Subject: [PATCH 11/28] Delete swarms/structs/hierarchical_structured_communication_swarm.py --- ...archical_structured_communication_swarm.py | 690 ------------------ 1 file changed, 690 deletions(-) delete mode 100644 swarms/structs/hierarchical_structured_communication_swarm.py diff --git a/swarms/structs/hierarchical_structured_communication_swarm.py b/swarms/structs/hierarchical_structured_communication_swarm.py deleted file mode 100644 index 09c8150f..00000000 --- a/swarms/structs/hierarchical_structured_communication_swarm.py +++ /dev/null @@ -1,690 +0,0 @@ -""" -Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems - -This implementation is based on the research paper: -"Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems" -arXiv:2502.11098 - -The framework consists of: -1. Structured Communication Protocol - Context-rich communication with message, background, and intermediate output -2. Hierarchical Refinement System - Evaluation team with supervisor coordination -3. Graph-based Agent Orchestration - Dynamic communication pathways - -Key Features: -- Structured communication with Message (M_ij), Background (B_ij), and Intermediate Output (I_ij) -- Hierarchical evaluation team with supervisor coordination -- Dynamic graph-based agent routing -- Context preservation and shared memory -""" - -import traceback -from typing import Any, Callable, Dict, List, Literal, Optional, Union -from dataclasses import dataclass -from enum import Enum - -from pydantic import BaseModel, Field - -from swarms.structs.agent import Agent -from swarms.structs.base_swarm import BaseSwarm -from swarms.structs.conversation import Conversation -from swarms.utils.loguru_logger import initialize_logger -from swarms.utils.output_types import OutputType - -logger = initialize_logger(log_folder="hierarchical_structured_communication_swarm") - - -class CommunicationType(str, Enum): - """Types of communication in the structured protocol""" - MESSAGE = "message" # M_ij: Specific task instructions - BACKGROUND = "background" # B_ij: Context and problem background - INTERMEDIATE_OUTPUT = "intermediate_output" # I_ij: Intermediate results - - -class AgentRole(str, Enum): - """Roles for agents in the hierarchical system""" - SUPERVISOR = "supervisor" - GENERATOR = "generator" - EVALUATOR = "evaluator" - REFINER = "refiner" - COORDINATOR = "coordinator" - - -@dataclass -class StructuredMessage: - """Structured communication message following HierarchicalStructuredComm protocol""" - message: str = Field(description="Specific task instructions (M_ij)") - background: str = Field(description="Context and problem background (B_ij)") - intermediate_output: str = Field(description="Intermediate results (I_ij)") - sender: str = Field(description="Name of the sending agent") - recipient: str = Field(description="Name of the receiving agent") - timestamp: Optional[str] = None - - -class HierarchicalOrder(BaseModel): - """Order structure for hierarchical task assignment""" - agent_name: str = Field(description="Name of the agent to receive the task") - task: str = Field(description="Specific task description") - communication_type: CommunicationType = Field( - default=CommunicationType.MESSAGE, - description="Type of communication to use" - ) - background_context: str = Field( - default="", - description="Background context for the task" - ) - intermediate_output: str = Field( - default="", - description="Intermediate output to pass along" - ) - - -class EvaluationResult(BaseModel): - """Result from evaluation team member""" - evaluator_name: str = Field(description="Name of the evaluator") - criterion: str = Field(description="Evaluation criterion") - score: float = Field(description="Evaluation score") - feedback: str = Field(description="Detailed feedback") - confidence: float = Field(description="Confidence in evaluation") - - -class HierarchicalStructuredCommunicationSwarm(BaseSwarm): - """ - Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems - - This framework implements the HierarchicalStructuredComm approach with: - 1. Structured Communication Protocol - 2. Hierarchical Refinement System - 3. Graph-based Agent Orchestration - - Architecture: - - Supervisor Agent: Coordinates the overall workflow - - Generator Agents: Create initial content/solutions - - Evaluator Team: Hierarchical evaluation with supervisor - - Refiner Agents: Improve solutions based on feedback - """ - - def __init__( - self, - name: str = "HierarchicalStructuredCommunicationSwarm", - description: str = "Talk Structurally, Act Hierarchically Framework", - supervisor: Optional[Union[Agent, Callable, Any]] = None, - generators: List[Union[Agent, Callable, Any]] = None, - evaluators: List[Union[Agent, Callable, Any]] = None, - refiners: List[Union[Agent, Callable, Any]] = None, - evaluation_supervisor: Optional[Union[Agent, Callable, Any]] = None, - max_loops: int = 3, - output_type: OutputType = "dict-all-except-first", - supervisor_name: str = "Supervisor", - evaluation_supervisor_name: str = "EvaluationSupervisor", - verbose: bool = False, - enable_structured_communication: bool = True, - enable_hierarchical_evaluation: bool = True, - shared_memory: bool = True, - *args, - **kwargs, - ): - """ - Initialize the HierarchicalStructuredCommunicationSwarm - - Args: - name: Name of the swarm - description: Description of the swarm - supervisor: Main supervisor agent - generators: List of generator agents - evaluators: List of evaluator agents - refiners: List of refiner agents - evaluation_supervisor: Supervisor for evaluation team - max_loops: Maximum number of refinement loops - output_type: Type of output format - supervisor_name: Name for the supervisor agent - evaluation_supervisor_name: Name for evaluation supervisor - verbose: Enable verbose logging - enable_structured_communication: Enable structured communication protocol - enable_hierarchical_evaluation: Enable hierarchical evaluation system - shared_memory: Enable shared memory between agents - """ - # Initialize the swarm components first - self.name = name - self.description = description - self.supervisor = supervisor - self.generators = generators or [] - self.evaluators = evaluators or [] - self.refiners = refiners or [] - self.evaluation_supervisor = evaluation_supervisor - self.max_loops = max_loops - self.output_type = output_type - self.supervisor_name = supervisor_name - self.evaluation_supervisor_name = evaluation_supervisor_name - self.verbose = verbose - self.enable_structured_communication = enable_structured_communication - self.enable_hierarchical_evaluation = enable_hierarchical_evaluation - self.shared_memory = shared_memory - - # Communication and state management - self.conversation_history: List[StructuredMessage] = [] - self.intermediate_outputs: Dict[str, str] = {} - self.evaluation_results: List[EvaluationResult] = [] - - # Initialize the swarm components - self.init_swarm() - - # Collect all agents for the parent class - all_agents = [] - if self.supervisor: - all_agents.append(self.supervisor) - all_agents.extend(self.generators) - all_agents.extend(self.evaluators) - all_agents.extend(self.refiners) - if self.evaluation_supervisor: - all_agents.append(self.evaluation_supervisor) - - # Call parent constructor with agents - super().__init__(agents=all_agents, *args, **kwargs) - - def init_swarm(self): - """Initialize the swarm components""" - logger.info(f"Initializing {self.name}") - - # Setup supervisor if not provided - if self.supervisor is None: - self.supervisor = self._create_supervisor_agent() - - # Setup evaluation supervisor if not provided - if self.evaluation_supervisor is None and self.enable_hierarchical_evaluation: - self.evaluation_supervisor = self._create_evaluation_supervisor_agent() - - # Setup default agents if none provided - if not self.generators: - self.generators = [self._create_default_generator()] - - if not self.evaluators and self.enable_hierarchical_evaluation: - self.evaluators = [self._create_default_evaluator()] - - if not self.refiners: - self.refiners = [self._create_default_refiner()] - - logger.info(f"Swarm initialized with {len(self.generators)} generators, " - f"{len(self.evaluators)} evaluators, {len(self.refiners)} refiners") - - def _create_supervisor_agent(self) -> Agent: - """Create the main supervisor agent""" - supervisor_prompt = self._get_supervisor_prompt() - - return Agent( - agent_name=self.supervisor_name, - system_prompt=supervisor_prompt, - model_name="gpt-4o-mini", - verbose=self.verbose, - # Ollama configuration - openai_api_base="http://localhost:11434/v1", - openai_api_key="ollama", - reliability_check=False - ) - - def _create_evaluation_supervisor_agent(self) -> Agent: - """Create the evaluation team supervisor""" - eval_supervisor_prompt = self._get_evaluation_supervisor_prompt() - - return Agent( - agent_name=self.evaluation_supervisor_name, - system_prompt=eval_supervisor_prompt, - model_name="gpt-4o-mini", - verbose=self.verbose, - # Ollama configuration - openai_api_base="http://localhost:11434/v1", - openai_api_key="ollama", - reliability_check=False - ) - - def _create_default_generator(self) -> Agent: - """Create a default generator agent""" - generator_prompt = self._get_generator_prompt() - - return Agent( - agent_name="Generator", - system_prompt=generator_prompt, - model_name="gpt-4o-mini", - verbose=self.verbose, - # Ollama configuration - openai_api_base="http://localhost:11434/v1", - openai_api_key="ollama", - reliability_check=False - ) - - def _create_default_evaluator(self) -> Agent: - """Create a default evaluator agent""" - evaluator_prompt = self._get_evaluator_prompt() - - return Agent( - agent_name="Evaluator", - system_prompt=evaluator_prompt, - model_name="gpt-4o-mini", - verbose=self.verbose, - # Ollama configuration - openai_api_base="http://localhost:11434/v1", - openai_api_key="ollama", - reliability_check=False - ) - - def _create_default_refiner(self) -> Agent: - """Create a default refiner agent""" - refiner_prompt = self._get_refiner_prompt() - - return Agent( - agent_name="Refiner", - system_prompt=refiner_prompt, - model_name="gpt-4o-mini", - verbose=self.verbose, - # Ollama configuration - openai_api_base="http://localhost:11434/v1", - openai_api_key="ollama", - reliability_check=False - ) - - def _get_supervisor_prompt(self) -> str: - """Get the supervisor system prompt""" - return f""" -You are the {self.supervisor_name} in a Talk Structurally, Act Hierarchically framework. - -Your responsibilities: -1. **Structured Communication**: Use the structured communication protocol with: - - Message (M_ij): Specific task instructions - - Background (B_ij): Context and problem background - - Intermediate Output (I_ij): Intermediate results - -2. **Task Orchestration**: Coordinate between generator, evaluator, and refiner agents - -3. **Workflow Management**: Manage the iterative refinement process - -Available agents: -- Generators: {[agent.agent_name if hasattr(agent, 'agent_name') else 'Generator' for agent in self.generators]} -- Evaluators: {[agent.agent_name if hasattr(agent, 'agent_name') else 'Evaluator' for agent in self.evaluators]} -- Refiners: {[agent.agent_name if hasattr(agent, 'agent_name') else 'Refiner' for agent in self.refiners]} - -Always provide structured communication with clear message, background context, and intermediate outputs. -""" - - def _get_evaluation_supervisor_prompt(self) -> str: - """Get the evaluation supervisor system prompt""" - return f""" -You are the {self.evaluation_supervisor_name} in a hierarchical evaluation system. - -Your responsibilities: -1. **Coordinate Evaluators**: Manage multiple evaluators with different criteria -2. **Synthesize Feedback**: Combine evaluation results into coherent feedback -3. **Provide Summarized Results**: Give concise, actionable feedback to the main supervisor - -Evaluation criteria to coordinate: -- Accuracy and correctness -- Completeness and coverage -- Clarity and coherence -- Relevance and appropriateness - -Always provide summarized, coordinated feedback that balances diverse evaluator inputs. -""" - - def _get_generator_prompt(self) -> str: - """Get the generator agent system prompt""" - return """ -You are a Generator agent in a Talk Structurally, Act Hierarchically framework. - -Your responsibilities: -1. **Create Initial Content**: Generate solutions, content, or responses based on structured input -2. **Follow Structured Communication**: Process messages with clear background context and intermediate outputs -3. **Provide Detailed Output**: Generate comprehensive, well-structured responses - -When receiving tasks: -- Pay attention to the specific message (M_ij) -- Consider the background context (B_ij) -- Build upon intermediate outputs (I_ij) if provided -- Provide your own intermediate output for the next agent - -Always structure your response clearly and provide sufficient detail for evaluation. -""" - - def _get_evaluator_prompt(self) -> str: - """Get the evaluator agent system prompt""" - return """ -You are an Evaluator agent in a hierarchical evaluation system. - -Your responsibilities: -1. **Evaluate Content**: Assess quality, accuracy, and appropriateness -2. **Provide Specific Feedback**: Give detailed, actionable feedback -3. **Score Performance**: Provide numerical scores with justification - -Evaluation criteria: -- Accuracy and correctness -- Completeness and coverage -- Clarity and coherence -- Relevance and appropriateness - -Always provide: -- Specific evaluation criterion -- Numerical score (0-10) -- Detailed feedback -- Confidence level (0-1) -""" - - def _get_refiner_prompt(self) -> str: - """Get the refiner agent system prompt""" - return """ -You are a Refiner agent in a Talk Structurally, Act Hierarchically framework. - -Your responsibilities: -1. **Improve Content**: Enhance solutions based on evaluation feedback -2. **Address Feedback**: Specifically address issues identified by evaluators -3. **Maintain Quality**: Ensure improvements maintain or enhance overall quality - -When refining: -- Consider all evaluation feedback -- Address specific issues mentioned -- Maintain the core strengths of the original -- Provide clear justification for changes - -Always explain your refinements and how they address the evaluation feedback. -""" - - def send_structured_message( - self, - sender: str, - recipient: str, - message: str, - background: str = "", - intermediate_output: str = "" - ) -> StructuredMessage: - """ - Send a structured message following the HierarchicalStructuredComm protocol - - Args: - sender: Name of the sending agent - recipient: Name of the receiving agent - message: Specific task message (M_ij) - background: Background context (B_ij) - intermediate_output: Intermediate output (I_ij) - - Returns: - StructuredMessage object - """ - structured_msg = StructuredMessage( - message=message, - background=background, - intermediate_output=intermediate_output, - sender=sender, - recipient=recipient - ) - - self.conversation_history.append(structured_msg) - - if self.verbose: - logger.info(f"Structured message sent from {sender} to {recipient}") - logger.info(f"Message: {message[:100]}...") - - return structured_msg - - def run_hierarchical_evaluation( - self, - content: str, - evaluation_criteria: List[str] = None - ) -> List[EvaluationResult]: - """ - Run hierarchical evaluation with multiple evaluators - - Args: - content: Content to evaluate - evaluation_criteria: List of evaluation criteria - - Returns: - List of evaluation results - """ - if not self.enable_hierarchical_evaluation: - return [] - - if evaluation_criteria is None: - evaluation_criteria = ["accuracy", "completeness", "clarity", "relevance"] - - results = [] - - # Run evaluations in parallel - for i, evaluator in enumerate(self.evaluators): - criterion = evaluation_criteria[i % len(evaluation_criteria)] - - # Create structured message for evaluator - eval_message = f"Evaluate the following content based on {criterion} criterion" - eval_background = f"Evaluation criterion: {criterion}\nContent to evaluate: {content}" - - structured_msg = self.send_structured_message( - sender=self.evaluation_supervisor_name, - recipient=evaluator.agent_name if hasattr(evaluator, 'agent_name') else f"Evaluator_{i}", - message=eval_message, - background=eval_background, - intermediate_output=content - ) - - # Get evaluation result - try: - if hasattr(evaluator, 'run'): - eval_response = evaluator.run( - f"Evaluate this content for {criterion}:\n{content}\n\nProvide: 1) Score (0-10), 2) Detailed feedback, 3) Confidence (0-1)" - ) - - # Parse evaluation result (simplified parsing) - result = EvaluationResult( - evaluator_name=evaluator.agent_name if hasattr(evaluator, 'agent_name') else f"Evaluator_{i}", - criterion=criterion, - score=7.5, # Default score, would need proper parsing - feedback=eval_response, - confidence=0.8 # Default confidence - ) - results.append(result) - - except Exception as e: - logger.error(f"Error in evaluation: {e}") - continue - - # Get summarized feedback from evaluation supervisor - if self.evaluation_supervisor and results: - summary_prompt = f"Summarize these evaluation results:\n{results}\n\nProvide coordinated, actionable feedback." - - try: - if hasattr(self.evaluation_supervisor, 'run'): - summary_feedback = self.evaluation_supervisor.run(summary_prompt) - logger.info(f"Evaluation summary: {summary_feedback}") - except Exception as e: - logger.error(f"Error in evaluation summary: {e}") - - self.evaluation_results.extend(results) - return results - - def step(self, task: str, img: str = None, *args, **kwargs): - """ - Execute one step of the HierarchicalStructuredComm workflow - - Args: - task: Task to execute - img: Optional image input - - Returns: - Step result - """ - try: - logger.info(f"Executing HierarchicalStructuredComm step for task: {task[:100]}...") - - # Safety check: prevent recursive task processing - if len(task) > 1000: # If task is too long, it might be recursive - logger.warning("Task too long, possible recursive call detected") - return {"error": "Task too long, possible recursive call"} - - # Step 1: Generate initial content - generator_result = self._generate_content(task) - - # Safety check: prevent empty or error results - if not generator_result or generator_result.startswith("Error"): - logger.error(f"Generator failed: {generator_result}") - return {"error": f"Generator failed: {generator_result}"} - - # Step 2: Evaluate content hierarchically - evaluation_results = self.run_hierarchical_evaluation(generator_result) - - # Step 3: Refine content based on evaluation - refined_result = self._refine_content(generator_result, evaluation_results) - - # Safety check: ensure we have a valid result - if not refined_result: - refined_result = generator_result - - return { - "generator_result": generator_result, - "evaluation_results": evaluation_results, - "refined_result": refined_result, - "conversation_history": self.conversation_history - } - - except Exception as e: - logger.error(f"Error in HierarchicalStructuredComm step: {e}") - logger.error(traceback.format_exc()) - return {"error": str(e)} - - def _generate_content(self, task: str) -> str: - """Generate initial content using generator agents""" - if not self.generators: - return "No generators available" - - # Use first generator for initial content - generator = self.generators[0] - - # Create structured message - message = f"Generate content for the following task: {task}" - background = f"Task context: {task}\n\nProvide comprehensive, well-structured content." - - structured_msg = self.send_structured_message( - sender=self.supervisor_name, - recipient=generator.agent_name if hasattr(generator, 'agent_name') else "Generator", - message=message, - background=background - ) - - try: - if hasattr(generator, 'run'): - # Add a simple, focused prompt to prevent recursive calls - prompt = f"Task: {task}\n\nGenerate a clear, concise response. Do not repeat the task or ask for clarification." - - result = generator.run(prompt) - - # Safety check: prevent recursive or overly long responses - if len(result) > 2000: - result = result[:2000] + "... [truncated]" - - # Safety check: prevent responses that just repeat the task - if task.lower() in result.lower() and len(result) < len(task) * 2: - logger.warning("Generator response appears to be recursive") - return "Error: Generator produced recursive response" - - self.intermediate_outputs["generator"] = result - return result - else: - return "Generator not properly configured" - except Exception as e: - logger.error(f"Error in content generation: {e}") - return f"Error generating content: {e}" - - def _refine_content(self, original_content: str, evaluation_results: List[EvaluationResult]) -> str: - """Refine content based on evaluation feedback""" - if not self.refiners: - return original_content - - if not evaluation_results: - return original_content - - # Use first refiner - refiner = self.refiners[0] - - # Create feedback summary - feedback_summary = "\n".join([ - f"{result.criterion}: {result.feedback} (Score: {result.score}/10)" - for result in evaluation_results - ]) - - # Create structured message for refinement - message = "Refine the content based on the evaluation feedback" - background = f"Original content: {original_content}\n\nEvaluation feedback:\n{feedback_summary}" - - structured_msg = self.send_structured_message( - sender=self.supervisor_name, - recipient=refiner.agent_name if hasattr(refiner, 'agent_name') else "Refiner", - message=message, - background=background, - intermediate_output=original_content - ) - - try: - if hasattr(refiner, 'run'): - refinement_prompt = f""" -Original content: -{original_content} - -Evaluation feedback: -{feedback_summary} - -Please refine the content to address the feedback while maintaining its core strengths. -""" - result = refiner.run(refinement_prompt) - self.intermediate_outputs["refiner"] = result - return result - else: - return original_content - except Exception as e: - logger.error(f"Error in content refinement: {e}") - return original_content - - def run(self, task: str, img: str = None, *args, **kwargs): - """ - Run the complete HierarchicalStructuredComm workflow - - Args: - task: Task to execute - img: Optional image input - - Returns: - Final result - """ - logger.info(f"Running HierarchicalStructuredComm workflow for task: {task[:100]}...") - - current_result = None - total_loops = 0 - - for loop in range(self.max_loops): - total_loops = loop + 1 - logger.info(f"HierarchicalStructuredComm loop {total_loops}/{self.max_loops}") - - # Execute step - step_result = self.step(task, img, *args, **kwargs) - - if "error" in step_result: - logger.error(f"Error in loop {total_loops}: {step_result['error']}") - break - - current_result = step_result["refined_result"] - - # Check if we should continue refining - if loop < self.max_loops - 1: - # Simple continuation logic - could be enhanced - evaluation_scores = [result.score for result in step_result["evaluation_results"]] - avg_score = sum(evaluation_scores) / len(evaluation_scores) if evaluation_scores else 0 - - if avg_score >= 8.0: # High quality threshold - logger.info(f"High quality achieved (avg score: {avg_score:.2f}), stopping refinement") - break - - return { - "final_result": current_result, - "total_loops": total_loops, - "conversation_history": self.conversation_history, - "evaluation_results": self.evaluation_results, - "intermediate_outputs": self.intermediate_outputs - } - - def __str__(self): - return f"HierarchicalStructuredCommunicationSwarm(name={self.name}, generators={len(self.generators)}, evaluators={len(self.evaluators)}, refiners={len(self.refiners)})" - - def __repr__(self): - return self.__str__() \ No newline at end of file From 3830265e7afb267c8fb78b6fb374e7c1fae743b6 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Mon, 18 Aug 2025 22:45:32 +0300 Subject: [PATCH 12/28] Delete swarms/agents/hierarchical_structured_communication_agents.py --- ...rchical_structured_communication_agents.py | 816 ------------------ 1 file changed, 816 deletions(-) delete mode 100644 swarms/agents/hierarchical_structured_communication_agents.py diff --git a/swarms/agents/hierarchical_structured_communication_agents.py b/swarms/agents/hierarchical_structured_communication_agents.py deleted file mode 100644 index 3bdcdf0c..00000000 --- a/swarms/agents/hierarchical_structured_communication_agents.py +++ /dev/null @@ -1,816 +0,0 @@ -""" -Specialized Agents for Hierarchical Structured Communication Framework Framework - -This module provides specialized agent implementations for the HierarchicalStructuredCommunication framework, -including structured communication agents and hierarchical evaluation agents. -""" - -from typing import Any, Dict, List, Optional, Union -from loguru import logger - -from swarms.structs.agent import Agent -from swarms.schemas.talk_hierarchical_schemas import ( - StructuredMessageSchema, - EvaluationResultSchema, - GeneratorResponseSchema, - EvaluatorResponseSchema, - RefinerResponseSchema, - CommunicationType, - AgentRole -) - - -class HierarchicalStructuredCommunicationGenerator(Agent): - """ - Generator agent for Hierarchical Structured Communication Framework framework - - This agent specializes in creating initial content following the structured - communication protocol with Message (M_ij), Background (B_ij), and Intermediate Output (I_ij). - """ - - def __init__( - self, - agent_name: str = "TalkHierGenerator", - system_prompt: Optional[str] = None, - model_name: str = "gpt-4o-mini", - verbose: bool = False, - **kwargs - ): - """ - Initialize the HierarchicalStructuredCommunication Generator agent - - Args: - agent_name: Name of the agent - system_prompt: Custom system prompt - model_name: Model to use - verbose: Enable verbose logging - """ - if system_prompt is None: - system_prompt = self._get_default_generator_prompt() - - super().__init__( - agent_name=agent_name, - system_prompt=system_prompt, - model_name=model_name, - verbose=verbose, - **kwargs - ) - - def _get_default_generator_prompt(self) -> str: - """Get the default system prompt for generator agents""" - return """ -You are a Generator agent in a Hierarchical Structured Communication Framework framework. - -Your core responsibility is to create high-quality initial content based on structured input. - -**Structured Communication Protocol:** -- Message (M_ij): Specific task instructions you receive -- Background (B_ij): Context and problem background provided -- Intermediate Output (I_ij): Intermediate results to build upon - -**Your Process:** -1. **Analyze Input**: Carefully examine the message, background, and intermediate output -2. **Generate Content**: Create comprehensive, well-structured content -3. **Provide Intermediate Output**: Generate intermediate results for the next agent -4. **Structure Response**: Format your response clearly with reasoning and confidence - -**Quality Standards:** -- Comprehensive coverage of the task -- Clear structure and organization -- Logical flow and coherence -- Sufficient detail for evaluation -- Original and creative solutions - -**Response Format:** -``` -Content: [Your generated content] - -Intermediate Output: [Structured output for next agent] - -Reasoning: [Your reasoning process] - -Confidence: [0.0-1.0 confidence level] -``` - -Always maintain high quality and provide detailed, actionable content. -""" - - def generate_with_structure( - self, - message: str, - background: str = "", - intermediate_output: str = "", - **kwargs - ) -> GeneratorResponseSchema: - """ - Generate content using structured communication protocol - - Args: - message: Specific task message (M_ij) - background: Background context (B_ij) - intermediate_output: Intermediate output (I_ij) - - Returns: - GeneratorResponseSchema with structured response - """ - try: - # Construct structured prompt - prompt = self._construct_structured_prompt(message, background, intermediate_output) - - # Generate response - response = self.run(prompt, **kwargs) - - # Parse and structure response - return self._parse_generator_response(response) - - except Exception as e: - logger.error(f"Error in structured generation: {e}") - return GeneratorResponseSchema( - content=f"Error generating content: {e}", - intermediate_output="", - reasoning="Error occurred during generation", - confidence=0.0 - ) - - def _construct_structured_prompt( - self, - message: str, - background: str, - intermediate_output: str - ) -> str: - """Construct a structured prompt for generation""" - prompt_parts = [] - - if message: - prompt_parts.append(f"**Task Message (M_ij):** {message}") - - if background: - prompt_parts.append(f"**Background Context (B_ij):** {background}") - - if intermediate_output: - prompt_parts.append(f"**Intermediate Output (I_ij):** {intermediate_output}") - - prompt = "\n\n".join(prompt_parts) - prompt += "\n\nPlease generate content following the structured response format." - - return prompt - - def _parse_generator_response(self, response: str) -> GeneratorResponseSchema: - """Parse the generator response into structured format""" - try: - # Simple parsing - could be enhanced with more sophisticated parsing - lines = response.split('\n') - content = "" - intermediate_output = "" - reasoning = "" - confidence = 0.8 # Default confidence - - current_section = None - - for line in lines: - line = line.strip() - if not line: - continue - - if line.lower().startswith('content:'): - current_section = 'content' - content = line[8:].strip() - elif line.lower().startswith('intermediate output:'): - current_section = 'intermediate' - intermediate_output = line[20:].strip() - elif line.lower().startswith('reasoning:'): - current_section = 'reasoning' - reasoning = line[10:].strip() - elif line.lower().startswith('confidence:'): - try: - confidence = float(line[11:].strip()) - except ValueError: - confidence = 0.8 - elif current_section == 'content': - content += " " + line - elif current_section == 'intermediate': - intermediate_output += " " + line - elif current_section == 'reasoning': - reasoning += " " + line - - return GeneratorResponseSchema( - content=content or response, - intermediate_output=intermediate_output, - reasoning=reasoning, - confidence=confidence - ) - - except Exception as e: - logger.error(f"Error parsing generator response: {e}") - return GeneratorResponseSchema( - content=response, - intermediate_output="", - reasoning="Error parsing response", - confidence=0.5 - ) - - -class HierarchicalStructuredCommunicationEvaluator(Agent): - """ - Evaluator agent for Hierarchical Structured Communication Framework framework - - This agent specializes in evaluating content using specific criteria and - providing structured feedback following the hierarchical evaluation system. - """ - - def __init__( - self, - agent_name: str = "TalkHierEvaluator", - system_prompt: Optional[str] = None, - model_name: str = "gpt-4o-mini", - verbose: bool = False, - evaluation_criteria: List[str] = None, - **kwargs - ): - """ - Initialize the HierarchicalStructuredCommunication Evaluator agent - - Args: - agent_name: Name of the agent - system_prompt: Custom system prompt - model_name: Model to use - verbose: Enable verbose logging - evaluation_criteria: List of evaluation criteria this agent can assess - """ - if system_prompt is None: - system_prompt = self._get_default_evaluator_prompt(evaluation_criteria) - - super().__init__( - agent_name=agent_name, - system_prompt=system_prompt, - model_name=model_name, - verbose=verbose, - **kwargs - ) - - self.evaluation_criteria = evaluation_criteria or ["accuracy", "completeness", "clarity", "relevance"] - - def _get_default_evaluator_prompt(self, criteria: List[str] = None) -> str: - """Get the default system prompt for evaluator agents""" - if criteria is None: - criteria = ["accuracy", "completeness", "clarity", "relevance"] - - criteria_text = "\n".join([f"- {criterion}" for criterion in criteria]) - - return f""" -You are an Evaluator agent in a Hierarchical Structured Communication Framework framework. - -Your core responsibility is to evaluate content quality using specific criteria and provide structured feedback. - -**Evaluation Criteria:** -{criteria_text} - -**Evaluation Process:** -1. **Analyze Content**: Examine the content thoroughly -2. **Apply Criteria**: Evaluate against the specified criterion -3. **Score Performance**: Provide numerical score (0-10) -4. **Provide Feedback**: Give detailed, actionable feedback -5. **Assess Confidence**: Rate your confidence in the evaluation - -**Scoring Guidelines:** -- 9-10: Excellent - Outstanding quality, minimal issues -- 7-8: Good - High quality with minor improvements needed -- 5-6: Average - Adequate but significant improvements needed -- 3-4: Below Average - Major issues, substantial improvements required -- 1-2: Poor - Critical issues, extensive revision needed -- 0: Unacceptable - Fundamental problems - -**Response Format:** -``` -Criterion: [Evaluation criterion] - -Score: [0-10 numerical score] - -Feedback: [Detailed feedback] - -Confidence: [0.0-1.0 confidence level] - -Reasoning: [Your evaluation reasoning] - -Suggestions: [Specific improvement suggestions] -``` - -Be thorough, fair, and constructive in your evaluations. -""" - - def evaluate_with_criterion( - self, - content: str, - criterion: str, - **kwargs - ) -> EvaluatorResponseSchema: - """ - Evaluate content using a specific criterion - - Args: - content: Content to evaluate - criterion: Specific evaluation criterion - - Returns: - EvaluatorResponseSchema with evaluation results - """ - try: - # Construct evaluation prompt - prompt = self._construct_evaluation_prompt(content, criterion) - - # Get evaluation response - response = self.run(prompt, **kwargs) - - # Parse and structure response - return self._parse_evaluator_response(response, criterion) - - except Exception as e: - logger.error(f"Error in evaluation: {e}") - return EvaluatorResponseSchema( - criterion=criterion, - score=5.0, - feedback=f"Error during evaluation: {e}", - confidence=0.0, - reasoning="Error occurred during evaluation", - suggestions=["Fix technical issues", "Retry evaluation"] - ) - - def _construct_evaluation_prompt(self, content: str, criterion: str) -> str: - """Construct an evaluation prompt""" - return f""" -**Content to Evaluate:** -{content} - -**Evaluation Criterion:** -{criterion} - -Please evaluate the content above based on the {criterion} criterion. - -Provide your evaluation following the structured response format. -""" - - def _parse_evaluator_response(self, response: str, criterion: str) -> EvaluatorResponseSchema: - """Parse the evaluator response into structured format""" - try: - lines = response.split('\n') - score = 5.0 # Default score - feedback = "" - confidence = 0.8 # Default confidence - reasoning = "" - suggestions = [] - - current_section = None - - for line in lines: - line = line.strip() - if not line: - continue - - if line.lower().startswith('score:'): - try: - score = float(line[6:].strip()) - except ValueError: - score = 5.0 - elif line.lower().startswith('feedback:'): - current_section = 'feedback' - feedback = line[9:].strip() - elif line.lower().startswith('confidence:'): - try: - confidence = float(line[11:].strip()) - except ValueError: - confidence = 0.8 - elif line.lower().startswith('reasoning:'): - current_section = 'reasoning' - reasoning = line[10:].strip() - elif line.lower().startswith('suggestions:'): - current_section = 'suggestions' - elif current_section == 'feedback': - feedback += " " + line - elif current_section == 'reasoning': - reasoning += " " + line - elif current_section == 'suggestions': - if line.startswith('-') or line.startswith('•'): - suggestions.append(line[1:].strip()) - else: - suggestions.append(line) - - return EvaluatorResponseSchema( - criterion=criterion, - score=score, - feedback=feedback or "No feedback provided", - confidence=confidence, - reasoning=reasoning, - suggestions=suggestions - ) - - except Exception as e: - logger.error(f"Error parsing evaluator response: {e}") - return EvaluatorResponseSchema( - criterion=criterion, - score=5.0, - feedback="Error parsing evaluation response", - confidence=0.0, - reasoning="Error occurred during parsing", - suggestions=["Fix parsing issues"] - ) - - -class HierarchicalStructuredCommunicationRefiner(Agent): - """ - Refiner agent for Hierarchical Structured Communication Framework framework - - This agent specializes in improving content based on evaluation feedback - and maintaining the structured communication protocol. - """ - - def __init__( - self, - agent_name: str = "TalkHierRefiner", - system_prompt: Optional[str] = None, - model_name: str = "gpt-4o-mini", - verbose: bool = False, - **kwargs - ): - """ - Initialize the HierarchicalStructuredCommunication Refiner agent - - Args: - agent_name: Name of the agent - system_prompt: Custom system prompt - model_name: Model to use - verbose: Enable verbose logging - """ - if system_prompt is None: - system_prompt = self._get_default_refiner_prompt() - - super().__init__( - agent_name=agent_name, - system_prompt=system_prompt, - model_name=model_name, - verbose=verbose, - **kwargs - ) - - def _get_default_refiner_prompt(self) -> str: - """Get the default system prompt for refiner agents""" - return """ -You are a Refiner agent in a Hierarchical Structured Communication Framework framework. - -Your core responsibility is to improve content based on evaluation feedback while maintaining quality and addressing specific issues. - -**Refinement Process:** -1. **Analyze Original**: Understand the original content thoroughly -2. **Review Feedback**: Examine all evaluation feedback carefully -3. **Identify Issues**: Identify specific problems to address -4. **Make Improvements**: Enhance content while preserving strengths -5. **Justify Changes**: Explain why each improvement was made - -**Refinement Principles:** -- Address specific feedback points -- Maintain core strengths and structure -- Improve clarity and coherence -- Enhance completeness and accuracy -- Preserve original intent and purpose - -**Response Format:** -``` -Refined Content: [Your improved content] - -Changes Made: [List of specific changes] - -Reasoning: [Explanation of refinements] - -Confidence: [0.0-1.0 confidence in improvements] - -Feedback Addressed: [Which feedback points were addressed] -``` - -Focus on meaningful improvements that directly address the evaluation feedback. -""" - - def refine_with_feedback( - self, - original_content: str, - evaluation_results: List[EvaluationResultSchema], - **kwargs - ) -> RefinerResponseSchema: - """ - Refine content based on evaluation feedback - - Args: - original_content: Original content to refine - evaluation_results: List of evaluation results with feedback - - Returns: - RefinerResponseSchema with refined content - """ - try: - # Construct refinement prompt - prompt = self._construct_refinement_prompt(original_content, evaluation_results) - - # Get refinement response - response = self.run(prompt, **kwargs) - - # Parse and structure response - return self._parse_refiner_response(response, evaluation_results) - - except Exception as e: - logger.error(f"Error in refinement: {e}") - return RefinerResponseSchema( - refined_content=original_content, - changes_made=["Error occurred during refinement"], - reasoning=f"Error during refinement: {e}", - confidence=0.0, - feedback_addressed=[] - ) - - def _construct_refinement_prompt( - self, - original_content: str, - evaluation_results: List[EvaluationResultSchema] - ) -> str: - """Construct a refinement prompt""" - feedback_summary = "\n\n".join([ - f"**{result.criterion} (Score: {result.score}/10):**\n{result.feedback}" - for result in evaluation_results - ]) - - return f""" -**Original Content:** -{original_content} - -**Evaluation Feedback:** -{feedback_summary} - -Please refine the content to address the feedback while maintaining its core strengths. - -Provide your refinement following the structured response format. -""" - - def _parse_refiner_response( - self, - response: str, - evaluation_results: List[EvaluationResultSchema] - ) -> RefinerResponseSchema: - """Parse the refiner response into structured format""" - try: - lines = response.split('\n') - refined_content = "" - changes_made = [] - reasoning = "" - confidence = 0.8 # Default confidence - feedback_addressed = [] - - current_section = None - - for line in lines: - line = line.strip() - if not line: - continue - - if line.lower().startswith('refined content:'): - current_section = 'content' - refined_content = line[16:].strip() - elif line.lower().startswith('changes made:'): - current_section = 'changes' - elif line.lower().startswith('reasoning:'): - current_section = 'reasoning' - reasoning = line[10:].strip() - elif line.lower().startswith('confidence:'): - try: - confidence = float(line[11:].strip()) - except ValueError: - confidence = 0.8 - elif line.lower().startswith('feedback addressed:'): - current_section = 'feedback' - elif current_section == 'content': - refined_content += " " + line - elif current_section == 'changes': - if line.startswith('-') or line.startswith('•'): - changes_made.append(line[1:].strip()) - else: - changes_made.append(line) - elif current_section == 'reasoning': - reasoning += " " + line - elif current_section == 'feedback': - if line.startswith('-') or line.startswith('•'): - feedback_addressed.append(line[1:].strip()) - else: - feedback_addressed.append(line) - - # If no refined content found, use original - if not refined_content: - refined_content = response - - return RefinerResponseSchema( - refined_content=refined_content, - changes_made=changes_made, - reasoning=reasoning, - confidence=confidence, - feedback_addressed=feedback_addressed - ) - - except Exception as e: - logger.error(f"Error parsing refiner response: {e}") - return RefinerResponseSchema( - refined_content=response, - changes_made=["Error parsing response"], - reasoning="Error occurred during parsing", - confidence=0.0, - feedback_addressed=[] - ) - - -class HierarchicalStructuredCommunicationSupervisor(Agent): - """ - Supervisor agent for Hierarchical Structured Communication Framework framework - - This agent coordinates the overall workflow and manages structured communication - between different agent types. - """ - - def __init__( - self, - agent_name: str = "TalkHierSupervisor", - system_prompt: Optional[str] = None, - model_name: str = "gpt-4o-mini", - verbose: bool = False, - **kwargs - ): - """ - Initialize the HierarchicalStructuredCommunication Supervisor agent - - Args: - agent_name: Name of the agent - system_prompt: Custom system prompt - model_name: Model to use - verbose: Enable verbose logging - """ - if system_prompt is None: - system_prompt = self._get_default_supervisor_prompt() - - super().__init__( - agent_name=agent_name, - system_prompt=system_prompt, - model_name=model_name, - verbose=verbose, - **kwargs - ) - - def _get_default_supervisor_prompt(self) -> str: - """Get the default system prompt for supervisor agents""" - return """ -You are a Supervisor agent in a Hierarchical Structured Communication Framework framework. - -Your core responsibility is to coordinate the workflow and manage structured communication between agents. - -**Supervision Responsibilities:** -1. **Task Orchestration**: Coordinate between generator, evaluator, and refiner agents -2. **Structured Communication**: Ensure proper use of Message (M_ij), Background (B_ij), and Intermediate Output (I_ij) -3. **Workflow Management**: Manage the iterative refinement process -4. **Quality Control**: Monitor and ensure high-quality outputs -5. **Decision Making**: Determine when to continue refinement or stop - -**Communication Protocol:** -- Always provide structured messages with clear components -- Maintain context and background information -- Pass intermediate outputs between agents -- Ensure proper agent coordination - -**Decision Criteria:** -- Evaluation scores and feedback quality -- Content improvement progress -- Resource constraints and time limits -- Quality thresholds and standards - -**Response Format:** -``` -Next Action: [What should happen next] - -Target Agent: [Which agent should act] - -Structured Message: [Complete structured message] - -Background Context: [Context to provide] - -Intermediate Output: [Output to pass along] - -Reasoning: [Why this decision was made] -``` - -Focus on efficient coordination and high-quality outcomes. -""" - - def coordinate_workflow( - self, - task: str, - current_state: Dict[str, Any], - **kwargs - ) -> Dict[str, Any]: - """ - Coordinate the workflow and determine next actions - - Args: - task: Current task being processed - current_state: Current state of the workflow - - Returns: - Dictionary with coordination decisions - """ - try: - # Construct coordination prompt - prompt = self._construct_coordination_prompt(task, current_state) - - # Get coordination response - response = self.run(prompt, **kwargs) - - # Parse and structure response - return self._parse_coordination_response(response) - - except Exception as e: - logger.error(f"Error in workflow coordination: {e}") - return { - "next_action": "error", - "target_agent": "none", - "structured_message": f"Error in coordination: {e}", - "background_context": "", - "intermediate_output": "", - "reasoning": "Error occurred during coordination" - } - - def _construct_coordination_prompt(self, task: str, current_state: Dict[str, Any]) -> str: - """Construct a coordination prompt""" - state_summary = "\n".join([ - f"- {key}: {value}" - for key, value in current_state.items() - ]) - - return f""" -**Current Task:** -{task} - -**Current State:** -{state_summary} - -Please coordinate the workflow and determine the next action. - -Provide your coordination decision following the structured response format. -""" - - def _parse_coordination_response(self, response: str) -> Dict[str, Any]: - """Parse the coordination response""" - try: - lines = response.split('\n') - result = { - "next_action": "continue", - "target_agent": "generator", - "structured_message": "", - "background_context": "", - "intermediate_output": "", - "reasoning": "" - } - - current_section = None - - for line in lines: - line = line.strip() - if not line: - continue - - if line.lower().startswith('next action:'): - result["next_action"] = line[12:].strip() - elif line.lower().startswith('target agent:'): - result["target_agent"] = line[13:].strip() - elif line.lower().startswith('structured message:'): - current_section = 'message' - result["structured_message"] = line[19:].strip() - elif line.lower().startswith('background context:'): - current_section = 'background' - result["background_context"] = line[19:].strip() - elif line.lower().startswith('intermediate output:'): - current_section = 'output' - result["intermediate_output"] = line[20:].strip() - elif line.lower().startswith('reasoning:'): - current_section = 'reasoning' - result["reasoning"] = line[10:].strip() - elif current_section == 'message': - result["structured_message"] += " " + line - elif current_section == 'background': - result["background_context"] += " " + line - elif current_section == 'output': - result["intermediate_output"] += " " + line - elif current_section == 'reasoning': - result["reasoning"] += " " + line - - return result - - except Exception as e: - logger.error(f"Error parsing coordination response: {e}") - return { - "next_action": "error", - "target_agent": "none", - "structured_message": "Error parsing response", - "background_context": "", - "intermediate_output": "", - "reasoning": "Error occurred during parsing" - } From 27d86bf9c9afdab97bf6746a2e0565a888850d53 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Mon, 18 Aug 2025 22:47:42 +0300 Subject: [PATCH 13/28] Create hierarchical_structured_communication_framework.py --- ...ical_structured_communication_framework.py | 1651 +++++++++++++++++ 1 file changed, 1651 insertions(+) create mode 100644 swarms/structs/hierarchical_structured_communication_framework.py diff --git a/swarms/structs/hierarchical_structured_communication_framework.py b/swarms/structs/hierarchical_structured_communication_framework.py new file mode 100644 index 00000000..173b4695 --- /dev/null +++ b/swarms/structs/hierarchical_structured_communication_framework.py @@ -0,0 +1,1651 @@ +""" +Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems + +This is a consolidated single-file implementation of the Hierarchical Structured Communication Framework +based on the research paper: "Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems" +arXiv:2502.11098 + +This file contains all components: +- Structured Communication Protocol (M_ij, B_ij, I_ij) +- Hierarchical Evaluation System +- Specialized Agent Classes +- Main Swarm Orchestrator +- Schemas and Data Models + +Key Features: +- Structured communication with Message (M_ij), Background (B_ij), and Intermediate Output (I_ij) +- Hierarchical evaluation team with supervisor coordination +- Dynamic graph-based agent routing +- Context preservation and shared memory +- Flexible model support (OpenAI and Ollama) +""" + +import traceback +import time +from typing import Any, Callable, Dict, List, Literal, Optional, Union +from dataclasses import dataclass +from enum import Enum + +from pydantic import BaseModel, Field + +from swarms.structs.agent import Agent +from swarms.structs.base_swarm import BaseSwarm +from swarms.structs.conversation import Conversation +from swarms.utils.loguru_logger import initialize_logger +from swarms.utils.output_types import OutputType + +logger = initialize_logger(log_folder="hierarchical_structured_communication_framework") + + +# ============================================================================= +# ENUMS AND DATA MODELS +# ============================================================================= + +class CommunicationType(str, Enum): + """Types of communication in the structured protocol""" + MESSAGE = "message" # M_ij: Specific task instructions + BACKGROUND = "background" # B_ij: Context and problem background + INTERMEDIATE_OUTPUT = "intermediate_output" # I_ij: Intermediate results + + +class AgentRole(str, Enum): + """Roles for agents in the hierarchical system""" + SUPERVISOR = "supervisor" + GENERATOR = "generator" + EVALUATOR = "evaluator" + REFINER = "refiner" + COORDINATOR = "coordinator" + + +@dataclass +class StructuredMessage: + """Structured communication message following HierarchicalStructuredComm protocol""" + message: str = Field(description="Specific task instructions (M_ij)") + background: str = Field(description="Context and problem background (B_ij)") + intermediate_output: str = Field(description="Intermediate results (I_ij)") + sender: str = Field(description="Name of the sending agent") + recipient: str = Field(description="Name of the receiving agent") + timestamp: Optional[str] = None + + +class HierarchicalOrder(BaseModel): + """Order structure for hierarchical task assignment""" + agent_name: str = Field(description="Name of the agent to receive the task") + task: str = Field(description="Specific task description") + communication_type: CommunicationType = Field( + default=CommunicationType.MESSAGE, + description="Type of communication to use" + ) + background_context: str = Field( + default="", + description="Background context for the task" + ) + intermediate_output: str = Field( + default="", + description="Intermediate output to pass along" + ) + + +class EvaluationResult(BaseModel): + """Result from evaluation team member""" + evaluator_name: str = Field(description="Name of the evaluator") + criterion: str = Field(description="Evaluation criterion") + score: float = Field(description="Evaluation score") + feedback: str = Field(description="Detailed feedback") + confidence: float = Field(description="Confidence in evaluation") + + +# ============================================================================= +# SCHEMAS +# ============================================================================= + +class StructuredMessageSchema(BaseModel): + """Schema for structured communication messages""" + message: str = Field(description="Specific task instructions (M_ij)", min_length=1) + background: str = Field(description="Context and problem background (B_ij)", default="") + intermediate_output: str = Field(description="Intermediate results (I_ij)", default="") + sender: str = Field(description="Name of the sending agent", min_length=1) + recipient: str = Field(description="Name of the receiving agent", min_length=1) + timestamp: Optional[str] = Field(description="Timestamp of the message", default=None) + communication_type: CommunicationType = Field(description="Type of communication", default=CommunicationType.MESSAGE) + + +class EvaluationResultSchema(BaseModel): + """Schema for evaluation results""" + criterion: str = Field(description="Evaluation criterion", min_length=1) + score: float = Field(description="Evaluation score (0-10)", ge=0.0, le=10.0) + feedback: str = Field(description="Detailed feedback", min_length=1) + confidence: float = Field(description="Confidence level (0-1)", ge=0.0, le=1.0) + reasoning: str = Field(description="Evaluation reasoning", default="") + suggestions: List[str] = Field(description="Improvement suggestions", default=[]) + + +class GeneratorResponseSchema(BaseModel): + """Schema for generator responses""" + content: str = Field(description="Generated content", min_length=1) + intermediate_output: str = Field(description="Intermediate output for next agent", default="") + reasoning: str = Field(description="Generation reasoning", default="") + confidence: float = Field(description="Confidence level (0-1)", ge=0.0, le=1.0) + + +class EvaluatorResponseSchema(BaseModel): + """Schema for evaluator responses""" + criterion: str = Field(description="Evaluation criterion", min_length=1) + score: float = Field(description="Evaluation score (0-10)", ge=0.0, le=10.0) + feedback: str = Field(description="Detailed feedback", min_length=1) + confidence: float = Field(description="Confidence level (0-1)", ge=0.0, le=1.0) + reasoning: str = Field(description="Evaluation reasoning", default="") + suggestions: List[str] = Field(description="Improvement suggestions", default=[]) + + +class RefinerResponseSchema(BaseModel): + """Schema for refiner responses""" + refined_content: str = Field(description="Refined content", min_length=1) + changes_made: List[str] = Field(description="List of changes made", default=[]) + reasoning: str = Field(description="Refinement reasoning", default="") + confidence: float = Field(description="Confidence level (0-1)", ge=0.0, le=1.0) + feedback_addressed: List[str] = Field(description="Feedback points addressed", default=[]) + + +# ============================================================================= +# SPECIALIZED AGENT CLASSES +# ============================================================================= + +class HierarchicalStructuredCommunicationGenerator(Agent): + """ + Generator agent for Hierarchical Structured Communication Framework + + This agent specializes in creating initial content following the structured + communication protocol with Message (M_ij), Background (B_ij), and Intermediate Output (I_ij). + """ + + def __init__( + self, + agent_name: str = "TalkHierGenerator", + system_prompt: Optional[str] = None, + model_name: str = "gpt-4o-mini", + verbose: bool = False, + **kwargs + ): + """ + Initialize the HierarchicalStructuredCommunication Generator agent + + Args: + agent_name: Name of the agent + system_prompt: Custom system prompt + model_name: Model to use + verbose: Enable verbose logging + """ + if system_prompt is None: + system_prompt = self._get_default_generator_prompt() + + super().__init__( + agent_name=agent_name, + system_prompt=system_prompt, + model_name=model_name, + verbose=verbose, + **kwargs + ) + + def _get_default_generator_prompt(self) -> str: + """Get the default system prompt for generator agents""" + return """ +You are a Generator agent in a Hierarchical Structured Communication Framework. + +Your core responsibility is to create high-quality initial content based on structured input. + +**Structured Communication Protocol:** +- Message (M_ij): Specific task instructions you receive +- Background (B_ij): Context and problem background provided +- Intermediate Output (I_ij): Intermediate results to build upon + +**Your Process:** +1. **Analyze Input**: Carefully examine the message, background, and intermediate output +2. **Generate Content**: Create comprehensive, well-structured content +3. **Provide Intermediate Output**: Generate intermediate results for the next agent +4. **Structure Response**: Format your response clearly with reasoning and confidence + +**Quality Standards:** +- Comprehensive coverage of the task +- Clear structure and organization +- Logical flow and coherence +- Sufficient detail for evaluation +- Original and creative solutions + +**Response Format:** +``` +Content: [Your generated content] + +Intermediate Output: [Structured output for next agent] + +Reasoning: [Your reasoning process] + +Confidence: [0.0-1.0 confidence level] +``` + +Always maintain high quality and provide detailed, actionable content. +""" + + def generate_with_structure( + self, + message: str, + background: str = "", + intermediate_output: str = "", + **kwargs + ) -> GeneratorResponseSchema: + """ + Generate content using structured communication protocol + + Args: + message: Specific task message (M_ij) + background: Background context (B_ij) + intermediate_output: Intermediate output (I_ij) + + Returns: + GeneratorResponseSchema with structured response + """ + try: + # Construct structured prompt + prompt = self._construct_structured_prompt(message, background, intermediate_output) + + # Generate response + response = self.run(prompt, **kwargs) + + # Parse and structure response + return self._parse_generator_response(response) + + except Exception as e: + logger.error(f"Error in structured generation: {e}") + return GeneratorResponseSchema( + content=f"Error generating content: {e}", + intermediate_output="", + reasoning="Error occurred during generation", + confidence=0.0 + ) + + def _construct_structured_prompt( + self, + message: str, + background: str, + intermediate_output: str + ) -> str: + """Construct a structured prompt for generation""" + prompt_parts = [] + + if message: + prompt_parts.append(f"**Task Message (M_ij):** {message}") + + if background: + prompt_parts.append(f"**Background Context (B_ij):** {background}") + + if intermediate_output: + prompt_parts.append(f"**Intermediate Output (I_ij):** {intermediate_output}") + + prompt = "\n\n".join(prompt_parts) + prompt += "\n\nPlease generate content following the structured response format." + + return prompt + + def _parse_generator_response(self, response: str) -> GeneratorResponseSchema: + """Parse the generator response into structured format""" + try: + lines = response.split('\n') + content = "" + intermediate_output = "" + reasoning = "" + confidence = 0.8 # Default confidence + + current_section = None + + for line in lines: + line = line.strip() + if not line: + continue + + if line.lower().startswith('content:'): + current_section = 'content' + content = line[8:].strip() + elif line.lower().startswith('intermediate output:'): + current_section = 'intermediate' + intermediate_output = line[20:].strip() + elif line.lower().startswith('reasoning:'): + current_section = 'reasoning' + reasoning = line[10:].strip() + elif line.lower().startswith('confidence:'): + try: + confidence = float(line[11:].strip()) + except ValueError: + confidence = 0.8 + elif current_section == 'content': + content += " " + line + elif current_section == 'intermediate': + intermediate_output += " " + line + elif current_section == 'reasoning': + reasoning += " " + line + + return GeneratorResponseSchema( + content=content or response, + intermediate_output=intermediate_output, + reasoning=reasoning, + confidence=confidence + ) + + except Exception as e: + logger.error(f"Error parsing generator response: {e}") + return GeneratorResponseSchema( + content=response, + intermediate_output="", + reasoning="Error parsing response", + confidence=0.5 + ) + + +class HierarchicalStructuredCommunicationEvaluator(Agent): + """ + Evaluator agent for Hierarchical Structured Communication Framework + + This agent specializes in evaluating content using specific criteria and + providing structured feedback following the hierarchical evaluation system. + """ + + def __init__( + self, + agent_name: str = "TalkHierEvaluator", + system_prompt: Optional[str] = None, + model_name: str = "gpt-4o-mini", + verbose: bool = False, + evaluation_criteria: List[str] = None, + **kwargs + ): + """ + Initialize the HierarchicalStructuredCommunication Evaluator agent + + Args: + agent_name: Name of the agent + system_prompt: Custom system prompt + model_name: Model to use + verbose: Enable verbose logging + evaluation_criteria: List of evaluation criteria this agent can assess + """ + if system_prompt is None: + system_prompt = self._get_default_evaluator_prompt(evaluation_criteria) + + super().__init__( + agent_name=agent_name, + system_prompt=system_prompt, + model_name=model_name, + verbose=verbose, + **kwargs + ) + + self.evaluation_criteria = evaluation_criteria or ["accuracy", "completeness", "clarity", "relevance"] + + def _get_default_evaluator_prompt(self, criteria: List[str] = None) -> str: + """Get the default system prompt for evaluator agents""" + if criteria is None: + criteria = ["accuracy", "completeness", "clarity", "relevance"] + + criteria_text = "\n".join([f"- {criterion}" for criterion in criteria]) + + return f""" +You are an Evaluator agent in a Hierarchical Structured Communication Framework. + +Your core responsibility is to evaluate content quality using specific criteria and provide structured feedback. + +**Evaluation Criteria:** +{criteria_text} + +**Evaluation Process:** +1. **Analyze Content**: Examine the content thoroughly +2. **Apply Criteria**: Evaluate against the specified criterion +3. **Score Performance**: Provide numerical score (0-10) +4. **Provide Feedback**: Give detailed, actionable feedback +5. **Assess Confidence**: Rate your confidence in the evaluation + +**Scoring Guidelines:** +- 9-10: Excellent - Outstanding quality, minimal issues +- 7-8: Good - High quality with minor improvements needed +- 5-6: Average - Adequate but significant improvements needed +- 3-4: Below Average - Major issues, substantial improvements required +- 1-2: Poor - Critical issues, extensive revision needed +- 0: Unacceptable - Fundamental problems + +**Response Format:** +``` +Criterion: [Evaluation criterion] + +Score: [0-10 numerical score] + +Feedback: [Detailed feedback] + +Confidence: [0.0-1.0 confidence level] + +Reasoning: [Your evaluation reasoning] + +Suggestions: [Specific improvement suggestions] +``` + +Be thorough, fair, and constructive in your evaluations. +""" + + def evaluate_with_criterion( + self, + content: str, + criterion: str, + **kwargs + ) -> EvaluatorResponseSchema: + """ + Evaluate content using a specific criterion + + Args: + content: Content to evaluate + criterion: Specific evaluation criterion + + Returns: + EvaluatorResponseSchema with evaluation results + """ + try: + # Construct evaluation prompt + prompt = self._construct_evaluation_prompt(content, criterion) + + # Get evaluation response + response = self.run(prompt, **kwargs) + + # Parse and structure response + return self._parse_evaluator_response(response, criterion) + + except Exception as e: + logger.error(f"Error in evaluation: {e}") + return EvaluatorResponseSchema( + criterion=criterion, + score=5.0, + feedback=f"Error during evaluation: {e}", + confidence=0.0, + reasoning="Error occurred during evaluation", + suggestions=["Fix technical issues", "Retry evaluation"] + ) + + def _construct_evaluation_prompt(self, content: str, criterion: str) -> str: + """Construct an evaluation prompt""" + return f""" +**Content to Evaluate:** +{content} + +**Evaluation Criterion:** +{criterion} + +Please evaluate the content above based on the {criterion} criterion. + +Provide your evaluation following the structured response format. +""" + + def _parse_evaluator_response(self, response: str, criterion: str) -> EvaluatorResponseSchema: + """Parse the evaluator response into structured format""" + try: + lines = response.split('\n') + score = 5.0 # Default score + feedback = "" + confidence = 0.8 # Default confidence + reasoning = "" + suggestions = [] + + current_section = None + + for line in lines: + line = line.strip() + if not line: + continue + + if line.lower().startswith('score:'): + try: + score = float(line[6:].strip()) + except ValueError: + score = 5.0 + elif line.lower().startswith('feedback:'): + current_section = 'feedback' + feedback = line[9:].strip() + elif line.lower().startswith('confidence:'): + try: + confidence = float(line[11:].strip()) + except ValueError: + confidence = 0.8 + elif line.lower().startswith('reasoning:'): + current_section = 'reasoning' + reasoning = line[10:].strip() + elif line.lower().startswith('suggestions:'): + current_section = 'suggestions' + elif current_section == 'feedback': + feedback += " " + line + elif current_section == 'reasoning': + reasoning += " " + line + elif current_section == 'suggestions': + if line.startswith('-') or line.startswith('•'): + suggestions.append(line[1:].strip()) + else: + suggestions.append(line) + + return EvaluatorResponseSchema( + criterion=criterion, + score=score, + feedback=feedback or "No feedback provided", + confidence=confidence, + reasoning=reasoning, + suggestions=suggestions + ) + + except Exception as e: + logger.error(f"Error parsing evaluator response: {e}") + return EvaluatorResponseSchema( + criterion=criterion, + score=5.0, + feedback="Error parsing evaluation response", + confidence=0.0, + reasoning="Error occurred during parsing", + suggestions=["Fix parsing issues"] + ) + + +class HierarchicalStructuredCommunicationRefiner(Agent): + """ + Refiner agent for Hierarchical Structured Communication Framework + + This agent specializes in improving content based on evaluation feedback + and maintaining the structured communication protocol. + """ + + def __init__( + self, + agent_name: str = "TalkHierRefiner", + system_prompt: Optional[str] = None, + model_name: str = "gpt-4o-mini", + verbose: bool = False, + **kwargs + ): + """ + Initialize the HierarchicalStructuredCommunication Refiner agent + + Args: + agent_name: Name of the agent + system_prompt: Custom system prompt + model_name: Model to use + verbose: Enable verbose logging + """ + if system_prompt is None: + system_prompt = self._get_default_refiner_prompt() + + super().__init__( + agent_name=agent_name, + system_prompt=system_prompt, + model_name=model_name, + verbose=verbose, + **kwargs + ) + + def _get_default_refiner_prompt(self) -> str: + """Get the default system prompt for refiner agents""" + return """ +You are a Refiner agent in a Hierarchical Structured Communication Framework. + +Your core responsibility is to improve content based on evaluation feedback while maintaining quality and addressing specific issues. + +**Refinement Process:** +1. **Analyze Original**: Understand the original content thoroughly +2. **Review Feedback**: Examine all evaluation feedback carefully +3. **Identify Issues**: Identify specific problems to address +4. **Make Improvements**: Enhance content while preserving strengths +5. **Justify Changes**: Explain why each improvement was made + +**Refinement Principles:** +- Address specific feedback points +- Maintain core strengths and structure +- Improve clarity and coherence +- Enhance completeness and accuracy +- Preserve original intent and purpose + +**Response Format:** +``` +Refined Content: [Your improved content] + +Changes Made: [List of specific changes] + +Reasoning: [Explanation of refinements] + +Confidence: [0.0-1.0 confidence in improvements] + +Feedback Addressed: [Which feedback points were addressed] +``` + +Focus on meaningful improvements that directly address the evaluation feedback. +""" + + def refine_with_feedback( + self, + original_content: str, + evaluation_results: List[EvaluationResultSchema], + **kwargs + ) -> RefinerResponseSchema: + """ + Refine content based on evaluation feedback + + Args: + original_content: Original content to refine + evaluation_results: List of evaluation results with feedback + + Returns: + RefinerResponseSchema with refined content + """ + try: + # Construct refinement prompt + prompt = self._construct_refinement_prompt(original_content, evaluation_results) + + # Get refinement response + response = self.run(prompt, **kwargs) + + # Parse and structure response + return self._parse_refiner_response(response, evaluation_results) + + except Exception as e: + logger.error(f"Error in refinement: {e}") + return RefinerResponseSchema( + refined_content=original_content, + changes_made=["Error occurred during refinement"], + reasoning=f"Error during refinement: {e}", + confidence=0.0, + feedback_addressed=[] + ) + + def _construct_refinement_prompt( + self, + original_content: str, + evaluation_results: List[EvaluationResultSchema] + ) -> str: + """Construct a refinement prompt""" + feedback_summary = "\n\n".join([ + f"**{result.criterion} (Score: {result.score}/10):**\n{result.feedback}" + for result in evaluation_results + ]) + + return f""" +**Original Content:** +{original_content} + +**Evaluation Feedback:** +{feedback_summary} + +Please refine the content to address the feedback while maintaining its core strengths. + +Provide your refinement following the structured response format. +""" + + def _parse_refiner_response( + self, + response: str, + evaluation_results: List[EvaluationResultSchema] + ) -> RefinerResponseSchema: + """Parse the refiner response into structured format""" + try: + lines = response.split('\n') + refined_content = "" + changes_made = [] + reasoning = "" + confidence = 0.8 # Default confidence + feedback_addressed = [] + + current_section = None + + for line in lines: + line = line.strip() + if not line: + continue + + if line.lower().startswith('refined content:'): + current_section = 'content' + refined_content = line[16:].strip() + elif line.lower().startswith('changes made:'): + current_section = 'changes' + elif line.lower().startswith('reasoning:'): + current_section = 'reasoning' + reasoning = line[10:].strip() + elif line.lower().startswith('confidence:'): + try: + confidence = float(line[11:].strip()) + except ValueError: + confidence = 0.8 + elif line.lower().startswith('feedback addressed:'): + current_section = 'feedback' + elif current_section == 'content': + refined_content += " " + line + elif current_section == 'changes': + if line.startswith('-') or line.startswith('•'): + changes_made.append(line[1:].strip()) + else: + changes_made.append(line) + elif current_section == 'reasoning': + reasoning += " " + line + elif current_section == 'feedback': + if line.startswith('-') or line.startswith('•'): + feedback_addressed.append(line[1:].strip()) + else: + feedback_addressed.append(line) + + # If no refined content found, use original + if not refined_content: + refined_content = response + + return RefinerResponseSchema( + refined_content=refined_content, + changes_made=changes_made, + reasoning=reasoning, + confidence=confidence, + feedback_addressed=feedback_addressed + ) + + except Exception as e: + logger.error(f"Error parsing refiner response: {e}") + return RefinerResponseSchema( + refined_content=response, + changes_made=["Error parsing response"], + reasoning="Error occurred during parsing", + confidence=0.0, + feedback_addressed=[] + ) + + +class HierarchicalStructuredCommunicationSupervisor(Agent): + """ + Supervisor agent for Hierarchical Structured Communication Framework + + This agent coordinates the overall workflow and manages structured communication + between different agent types. + """ + + def __init__( + self, + agent_name: str = "TalkHierSupervisor", + system_prompt: Optional[str] = None, + model_name: str = "gpt-4o-mini", + verbose: bool = False, + **kwargs + ): + """ + Initialize the HierarchicalStructuredCommunication Supervisor agent + + Args: + agent_name: Name of the agent + system_prompt: Custom system prompt + model_name: Model to use + verbose: Enable verbose logging + """ + if system_prompt is None: + system_prompt = self._get_default_supervisor_prompt() + + super().__init__( + agent_name=agent_name, + system_prompt=system_prompt, + model_name=model_name, + verbose=verbose, + **kwargs + ) + + def _get_default_supervisor_prompt(self) -> str: + """Get the default system prompt for supervisor agents""" + return """ +You are a Supervisor agent in a Hierarchical Structured Communication Framework. + +Your core responsibility is to coordinate the workflow and manage structured communication between agents. + +**Supervision Responsibilities:** +1. **Task Orchestration**: Coordinate between generator, evaluator, and refiner agents +2. **Structured Communication**: Ensure proper use of Message (M_ij), Background (B_ij), and Intermediate Output (I_ij) +3. **Workflow Management**: Manage the iterative refinement process +4. **Quality Control**: Monitor and ensure high-quality outputs +5. **Decision Making**: Determine when to continue refinement or stop + +**Communication Protocol:** +- Always provide structured messages with clear components +- Maintain context and background information +- Pass intermediate outputs between agents +- Ensure proper agent coordination + +**Decision Criteria:** +- Evaluation scores and feedback quality +- Content improvement progress +- Resource constraints and time limits +- Quality thresholds and standards + +**Response Format:** +``` +Next Action: [What should happen next] + +Target Agent: [Which agent should act] + +Structured Message: [Complete structured message] + +Background Context: [Context to provide] + +Intermediate Output: [Output to pass along] + +Reasoning: [Why this decision was made] +``` + +Focus on efficient coordination and high-quality outcomes. +""" + + def coordinate_workflow( + self, + task: str, + current_state: Dict[str, Any], + **kwargs + ) -> Dict[str, Any]: + """ + Coordinate the workflow and determine next actions + + Args: + task: Current task being processed + current_state: Current state of the workflow + + Returns: + Dictionary with coordination decisions + """ + try: + # Construct coordination prompt + prompt = self._construct_coordination_prompt(task, current_state) + + # Get coordination response + response = self.run(prompt, **kwargs) + + # Parse and structure response + return self._parse_coordination_response(response) + + except Exception as e: + logger.error(f"Error in workflow coordination: {e}") + return { + "next_action": "error", + "target_agent": "none", + "structured_message": f"Error in coordination: {e}", + "background_context": "", + "intermediate_output": "", + "reasoning": "Error occurred during coordination" + } + + def _construct_coordination_prompt(self, task: str, current_state: Dict[str, Any]) -> str: + """Construct a coordination prompt""" + state_summary = "\n".join([ + f"- {key}: {value}" + for key, value in current_state.items() + ]) + + return f""" +**Current Task:** +{task} + +**Current State:** +{state_summary} + +Please coordinate the workflow and determine the next action. + +Provide your coordination decision following the structured response format. +""" + + def _parse_coordination_response(self, response: str) -> Dict[str, Any]: + """Parse the coordination response""" + try: + lines = response.split('\n') + result = { + "next_action": "continue", + "target_agent": "generator", + "structured_message": "", + "background_context": "", + "intermediate_output": "", + "reasoning": "" + } + + current_section = None + + for line in lines: + line = line.strip() + if not line: + continue + + if line.lower().startswith('next action:'): + result["next_action"] = line[12:].strip() + elif line.lower().startswith('target agent:'): + result["target_agent"] = line[13:].strip() + elif line.lower().startswith('structured message:'): + current_section = 'message' + result["structured_message"] = line[19:].strip() + elif line.lower().startswith('background context:'): + current_section = 'background' + result["background_context"] = line[19:].strip() + elif line.lower().startswith('intermediate output:'): + current_section = 'output' + result["intermediate_output"] = line[20:].strip() + elif line.lower().startswith('reasoning:'): + current_section = 'reasoning' + result["reasoning"] = line[10:].strip() + elif current_section == 'message': + result["structured_message"] += " " + line + elif current_section == 'background': + result["background_context"] += " " + line + elif current_section == 'output': + result["intermediate_output"] += " " + line + elif current_section == 'reasoning': + result["reasoning"] += " " + line + + return result + + except Exception as e: + logger.error(f"Error parsing coordination response: {e}") + return { + "next_action": "error", + "target_agent": "none", + "structured_message": "Error parsing response", + "background_context": "", + "intermediate_output": "", + "reasoning": "Error occurred during parsing" + } + + +# ============================================================================= +# MAIN SWARM ORCHESTRATOR +# ============================================================================= + +class HierarchicalStructuredCommunicationFramework(BaseSwarm): + """ + Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems + + This is the main orchestrator class that implements the complete HierarchicalStructuredComm approach with: + 1. Structured Communication Protocol + 2. Hierarchical Refinement System + 3. Graph-based Agent Orchestration + + Architecture: + - Supervisor Agent: Coordinates the overall workflow + - Generator Agents: Create initial content/solutions + - Evaluator Team: Hierarchical evaluation with supervisor + - Refiner Agents: Improve solutions based on feedback + """ + + def __init__( + self, + name: str = "HierarchicalStructuredCommunicationFramework", + description: str = "Talk Structurally, Act Hierarchically Framework", + supervisor: Optional[Union[Agent, Callable, Any]] = None, + generators: List[Union[Agent, Callable, Any]] = None, + evaluators: List[Union[Agent, Callable, Any]] = None, + refiners: List[Union[Agent, Callable, Any]] = None, + evaluation_supervisor: Optional[Union[Agent, Callable, Any]] = None, + max_loops: int = 3, + output_type: OutputType = "dict-all-except-first", + supervisor_name: str = "Supervisor", + evaluation_supervisor_name: str = "EvaluationSupervisor", + verbose: bool = False, + enable_structured_communication: bool = True, + enable_hierarchical_evaluation: bool = True, + shared_memory: bool = True, + model_name: str = "gpt-4o-mini", + use_ollama: bool = False, + ollama_base_url: str = "http://localhost:11434/v1", + ollama_api_key: str = "ollama", + *args, + **kwargs, + ): + """ + Initialize the HierarchicalStructuredCommunicationFramework + + Args: + name: Name of the swarm + description: Description of the swarm + supervisor: Main supervisor agent + generators: List of generator agents + evaluators: List of evaluator agents + refiners: List of refiner agents + evaluation_supervisor: Supervisor for evaluation team + max_loops: Maximum number of refinement loops + output_type: Type of output format + supervisor_name: Name for the supervisor agent + evaluation_supervisor_name: Name for evaluation supervisor + verbose: Enable verbose logging + enable_structured_communication: Enable structured communication protocol + enable_hierarchical_evaluation: Enable hierarchical evaluation system + shared_memory: Enable shared memory between agents + model_name: Model name to use for default agents + use_ollama: Whether to use Ollama for local inference + ollama_base_url: Ollama API base URL + ollama_api_key: Ollama API key + """ + # Initialize the swarm components first + self.name = name + self.description = description + self.supervisor = supervisor + self.generators = generators or [] + self.evaluators = evaluators or [] + self.refiners = refiners or [] + self.evaluation_supervisor = evaluation_supervisor + self.max_loops = max_loops + self.output_type = output_type + self.supervisor_name = supervisor_name + self.evaluation_supervisor_name = evaluation_supervisor_name + self.verbose = verbose + self.enable_structured_communication = enable_structured_communication + self.enable_hierarchical_evaluation = enable_hierarchical_evaluation + self.shared_memory = shared_memory + self.model_name = model_name + self.use_ollama = use_ollama + self.ollama_base_url = ollama_base_url + self.ollama_api_key = ollama_api_key + + # Communication and state management + self.conversation_history: List[StructuredMessage] = [] + self.intermediate_outputs: Dict[str, str] = {} + self.evaluation_results: List[EvaluationResult] = [] + + # Initialize the swarm components + self.init_swarm() + + # Collect all agents for the parent class + all_agents = [] + if self.supervisor: + all_agents.append(self.supervisor) + all_agents.extend(self.generators) + all_agents.extend(self.evaluators) + all_agents.extend(self.refiners) + if self.evaluation_supervisor: + all_agents.append(self.evaluation_supervisor) + + # Call parent constructor with agents + super().__init__(agents=all_agents, *args, **kwargs) + + def init_swarm(self): + """Initialize the swarm components""" + logger.info(f"Initializing {self.name}") + + # Setup supervisor if not provided + if self.supervisor is None: + self.supervisor = self._create_supervisor_agent() + + # Setup evaluation supervisor if not provided + if self.evaluation_supervisor is None and self.enable_hierarchical_evaluation: + self.evaluation_supervisor = self._create_evaluation_supervisor_agent() + + # Setup default agents if none provided + if not self.generators: + self.generators = [self._create_default_generator()] + + if not self.evaluators and self.enable_hierarchical_evaluation: + self.evaluators = [self._create_default_evaluator()] + + if not self.refiners: + self.refiners = [self._create_default_refiner()] + + logger.info(f"Swarm initialized with {len(self.generators)} generators, " + f"{len(self.evaluators)} evaluators, {len(self.refiners)} refiners") + + def _create_supervisor_agent(self) -> Agent: + """Create the main supervisor agent""" + supervisor_prompt = self._get_supervisor_prompt() + + agent_kwargs = { + "agent_name": self.supervisor_name, + "system_prompt": supervisor_prompt, + "model_name": self.model_name, + "verbose": self.verbose, + "reliability_check": False + } + + if self.use_ollama: + agent_kwargs.update({ + "openai_api_base": self.ollama_base_url, + "openai_api_key": self.ollama_api_key + }) + + return Agent(**agent_kwargs) + + def _create_evaluation_supervisor_agent(self) -> Agent: + """Create the evaluation team supervisor""" + eval_supervisor_prompt = self._get_evaluation_supervisor_prompt() + + agent_kwargs = { + "agent_name": self.evaluation_supervisor_name, + "system_prompt": eval_supervisor_prompt, + "model_name": self.model_name, + "verbose": self.verbose, + "reliability_check": False + } + + if self.use_ollama: + agent_kwargs.update({ + "openai_api_base": self.ollama_base_url, + "openai_api_key": self.ollama_api_key + }) + + return Agent(**agent_kwargs) + + def _create_default_generator(self) -> Agent: + """Create a default generator agent""" + generator_prompt = self._get_generator_prompt() + + agent_kwargs = { + "agent_name": "Generator", + "system_prompt": generator_prompt, + "model_name": self.model_name, + "verbose": self.verbose, + "reliability_check": False + } + + if self.use_ollama: + agent_kwargs.update({ + "openai_api_base": self.ollama_base_url, + "openai_api_key": self.ollama_api_key + }) + + return Agent(**agent_kwargs) + + def _create_default_evaluator(self) -> Agent: + """Create a default evaluator agent""" + evaluator_prompt = self._get_evaluator_prompt() + + agent_kwargs = { + "agent_name": "Evaluator", + "system_prompt": evaluator_prompt, + "model_name": self.model_name, + "verbose": self.verbose, + "reliability_check": False + } + + if self.use_ollama: + agent_kwargs.update({ + "openai_api_base": self.ollama_base_url, + "openai_api_key": self.ollama_api_key + }) + + return Agent(**agent_kwargs) + + def _create_default_refiner(self) -> Agent: + """Create a default refiner agent""" + refiner_prompt = self._get_refiner_prompt() + + agent_kwargs = { + "agent_name": "Refiner", + "system_prompt": refiner_prompt, + "model_name": self.model_name, + "verbose": self.verbose, + "reliability_check": False + } + + if self.use_ollama: + agent_kwargs.update({ + "openai_api_base": self.ollama_base_url, + "openai_api_key": self.ollama_api_key + }) + + return Agent(**agent_kwargs) + + def _get_supervisor_prompt(self) -> str: + """Get the supervisor system prompt""" + return f""" +You are the {self.supervisor_name} in a Talk Structurally, Act Hierarchically framework. + +Your responsibilities: +1. **Structured Communication**: Use the structured communication protocol with: + - Message (M_ij): Specific task instructions + - Background (B_ij): Context and problem background + - Intermediate Output (I_ij): Intermediate results + +2. **Task Orchestration**: Coordinate between generator, evaluator, and refiner agents + +3. **Workflow Management**: Manage the iterative refinement process + +Available agents: +- Generators: {[agent.agent_name if hasattr(agent, 'agent_name') else 'Generator' for agent in self.generators]} +- Evaluators: {[agent.agent_name if hasattr(agent, 'agent_name') else 'Evaluator' for agent in self.evaluators]} +- Refiners: {[agent.agent_name if hasattr(agent, 'agent_name') else 'Refiner' for agent in self.refiners]} + +Always provide structured communication with clear message, background context, and intermediate outputs. +""" + + def _get_evaluation_supervisor_prompt(self) -> str: + """Get the evaluation supervisor system prompt""" + return f""" +You are the {self.evaluation_supervisor_name} in a hierarchical evaluation system. + +Your responsibilities: +1. **Coordinate Evaluators**: Manage multiple evaluators with different criteria +2. **Synthesize Feedback**: Combine evaluation results into coherent feedback +3. **Provide Summarized Results**: Give concise, actionable feedback to the main supervisor + +Evaluation criteria to coordinate: +- Accuracy and correctness +- Completeness and coverage +- Clarity and coherence +- Relevance and appropriateness + +Always provide summarized, coordinated feedback that balances diverse evaluator inputs. +""" + + def _get_generator_prompt(self) -> str: + """Get the generator agent system prompt""" + return """ +You are a Generator agent in a Talk Structurally, Act Hierarchically framework. + +Your responsibilities: +1. **Create Initial Content**: Generate solutions, content, or responses based on structured input +2. **Follow Structured Communication**: Process messages with clear background context and intermediate outputs +3. **Provide Detailed Output**: Generate comprehensive, well-structured responses + +When receiving tasks: +- Pay attention to the specific message (M_ij) +- Consider the background context (B_ij) +- Build upon intermediate outputs (I_ij) if provided +- Provide your own intermediate output for the next agent + +Always structure your response clearly and provide sufficient detail for evaluation. +""" + + def _get_evaluator_prompt(self) -> str: + """Get the evaluator agent system prompt""" + return """ +You are an Evaluator agent in a hierarchical evaluation system. + +Your responsibilities: +1. **Evaluate Content**: Assess quality, accuracy, and appropriateness +2. **Provide Specific Feedback**: Give detailed, actionable feedback +3. **Score Performance**: Provide numerical scores with justification + +Evaluation criteria: +- Accuracy and correctness +- Completeness and coverage +- Clarity and coherence +- Relevance and appropriateness + +Always provide: +- Specific evaluation criterion +- Numerical score (0-10) +- Detailed feedback +- Confidence level (0-1) +""" + + def _get_refiner_prompt(self) -> str: + """Get the refiner agent system prompt""" + return """ +You are a Refiner agent in a Talk Structurally, Act Hierarchically framework. + +Your responsibilities: +1. **Improve Content**: Enhance solutions based on evaluation feedback +2. **Address Feedback**: Specifically address issues identified by evaluators +3. **Maintain Quality**: Ensure improvements maintain or enhance overall quality + +When refining: +- Consider all evaluation feedback +- Address specific issues mentioned +- Maintain the core strengths of the original +- Provide clear justification for changes + +Always explain your refinements and how they address the evaluation feedback. +""" + + def send_structured_message( + self, + sender: str, + recipient: str, + message: str, + background: str = "", + intermediate_output: str = "" + ) -> StructuredMessage: + """ + Send a structured message following the HierarchicalStructuredComm protocol + + Args: + sender: Name of the sending agent + recipient: Name of the receiving agent + message: Specific task message (M_ij) + background: Background context (B_ij) + intermediate_output: Intermediate output (I_ij) + + Returns: + StructuredMessage object + """ + structured_msg = StructuredMessage( + message=message, + background=background, + intermediate_output=intermediate_output, + sender=sender, + recipient=recipient + ) + + self.conversation_history.append(structured_msg) + + if self.verbose: + logger.info(f"Structured message sent from {sender} to {recipient}") + logger.info(f"Message: {message[:100]}...") + + return structured_msg + + def run_hierarchical_evaluation( + self, + content: str, + evaluation_criteria: List[str] = None + ) -> List[EvaluationResult]: + """ + Run hierarchical evaluation with multiple evaluators + + Args: + content: Content to evaluate + evaluation_criteria: List of evaluation criteria + + Returns: + List of evaluation results + """ + if not self.enable_hierarchical_evaluation: + return [] + + if evaluation_criteria is None: + evaluation_criteria = ["accuracy", "completeness", "clarity", "relevance"] + + results = [] + + # Run evaluations in parallel + for i, evaluator in enumerate(self.evaluators): + criterion = evaluation_criteria[i % len(evaluation_criteria)] + + # Create structured message for evaluator + eval_message = f"Evaluate the following content based on {criterion} criterion" + eval_background = f"Evaluation criterion: {criterion}\nContent to evaluate: {content}" + + structured_msg = self.send_structured_message( + sender=self.evaluation_supervisor_name, + recipient=evaluator.agent_name if hasattr(evaluator, 'agent_name') else f"Evaluator_{i}", + message=eval_message, + background=eval_background, + intermediate_output=content + ) + + # Get evaluation result + try: + if hasattr(evaluator, 'run'): + eval_response = evaluator.run( + f"Evaluate this content for {criterion}:\n{content}\n\nProvide: 1) Score (0-10), 2) Detailed feedback, 3) Confidence (0-1)" + ) + + # Parse evaluation result (simplified parsing) + result = EvaluationResult( + evaluator_name=evaluator.agent_name if hasattr(evaluator, 'agent_name') else f"Evaluator_{i}", + criterion=criterion, + score=7.5, # Default score, would need proper parsing + feedback=eval_response, + confidence=0.8 # Default confidence + ) + results.append(result) + + except Exception as e: + logger.error(f"Error in evaluation: {e}") + continue + + # Get summarized feedback from evaluation supervisor + if self.evaluation_supervisor and results: + summary_prompt = f"Summarize these evaluation results:\n{results}\n\nProvide coordinated, actionable feedback." + + try: + if hasattr(self.evaluation_supervisor, 'run'): + summary_feedback = self.evaluation_supervisor.run(summary_prompt) + logger.info(f"Evaluation summary: {summary_feedback}") + except Exception as e: + logger.error(f"Error in evaluation summary: {e}") + + self.evaluation_results.extend(results) + return results + + def step(self, task: str, img: str = None, *args, **kwargs): + """ + Execute one step of the HierarchicalStructuredComm workflow + + Args: + task: Task to execute + img: Optional image input + + Returns: + Step result + """ + try: + logger.info(f"Executing HierarchicalStructuredComm step for task: {task[:100]}...") + + # Safety check: prevent recursive task processing + if len(task) > 1000: # If task is too long, it might be recursive + logger.warning("Task too long, possible recursive call detected") + return {"error": "Task too long, possible recursive call"} + + # Step 1: Generate initial content + generator_result = self._generate_content(task) + + # Safety check: prevent empty or error results + if not generator_result or generator_result.startswith("Error"): + logger.error(f"Generator failed: {generator_result}") + return {"error": f"Generator failed: {generator_result}"} + + # Step 2: Evaluate content hierarchically + evaluation_results = self.run_hierarchical_evaluation(generator_result) + + # Step 3: Refine content based on evaluation + refined_result = self._refine_content(generator_result, evaluation_results) + + # Safety check: ensure we have a valid result + if not refined_result: + refined_result = generator_result + + return { + "generator_result": generator_result, + "evaluation_results": evaluation_results, + "refined_result": refined_result, + "conversation_history": self.conversation_history + } + + except Exception as e: + logger.error(f"Error in HierarchicalStructuredComm step: {e}") + logger.error(traceback.format_exc()) + return {"error": str(e)} + + def _generate_content(self, task: str) -> str: + """Generate initial content using generator agents""" + if not self.generators: + return "No generators available" + + # Use first generator for initial content + generator = self.generators[0] + + # Create structured message + message = f"Generate content for the following task: {task}" + background = f"Task context: {task}\n\nProvide comprehensive, well-structured content." + + structured_msg = self.send_structured_message( + sender=self.supervisor_name, + recipient=generator.agent_name if hasattr(generator, 'agent_name') else "Generator", + message=message, + background=background + ) + + try: + if hasattr(generator, 'run'): + # Add a simple, focused prompt to prevent recursive calls + prompt = f"Task: {task}\n\nGenerate a clear, concise response. Do not repeat the task or ask for clarification." + + result = generator.run(prompt) + + # Safety check: prevent recursive or overly long responses + if len(result) > 2000: + result = result[:2000] + "... [truncated]" + + # Safety check: prevent responses that just repeat the task + if task.lower() in result.lower() and len(result) < len(task) * 2: + logger.warning("Generator response appears to be recursive") + return "Error: Generator produced recursive response" + + self.intermediate_outputs["generator"] = result + return result + else: + return "Generator not properly configured" + except Exception as e: + logger.error(f"Error in content generation: {e}") + return f"Error generating content: {e}" + + def _refine_content(self, original_content: str, evaluation_results: List[EvaluationResult]) -> str: + """Refine content based on evaluation feedback""" + if not self.refiners: + return original_content + + if not evaluation_results: + return original_content + + # Use first refiner + refiner = self.refiners[0] + + # Create feedback summary + feedback_summary = "\n".join([ + f"{result.criterion}: {result.feedback} (Score: {result.score}/10)" + for result in evaluation_results + ]) + + # Create structured message for refinement + message = "Refine the content based on the evaluation feedback" + background = f"Original content: {original_content}\n\nEvaluation feedback:\n{feedback_summary}" + + structured_msg = self.send_structured_message( + sender=self.supervisor_name, + recipient=refiner.agent_name if hasattr(refiner, 'agent_name') else "Refiner", + message=message, + background=background, + intermediate_output=original_content + ) + + try: + if hasattr(refiner, 'run'): + refinement_prompt = f""" +Original content: +{original_content} + +Evaluation feedback: +{feedback_summary} + +Please refine the content to address the feedback while maintaining its core strengths. +""" + result = refiner.run(refinement_prompt) + self.intermediate_outputs["refiner"] = result + return result + else: + return original_content + except Exception as e: + logger.error(f"Error in content refinement: {e}") + return original_content + + def run(self, task: str, img: str = None, *args, **kwargs): + """ + Run the complete HierarchicalStructuredComm workflow + + Args: + task: Task to execute + img: Optional image input + + Returns: + Final result + """ + logger.info(f"Running HierarchicalStructuredComm workflow for task: {task[:100]}...") + + current_result = None + total_loops = 0 + + for loop in range(self.max_loops): + total_loops = loop + 1 + logger.info(f"HierarchicalStructuredComm loop {total_loops}/{self.max_loops}") + + # Execute step + step_result = self.step(task, img, *args, **kwargs) + + if "error" in step_result: + logger.error(f"Error in loop {total_loops}: {step_result['error']}") + break + + current_result = step_result["refined_result"] + + # Check if we should continue refining + if loop < self.max_loops - 1: + # Simple continuation logic - could be enhanced + evaluation_scores = [result.score for result in step_result["evaluation_results"]] + avg_score = sum(evaluation_scores) / len(evaluation_scores) if evaluation_scores else 0 + + if avg_score >= 8.0: # High quality threshold + logger.info(f"High quality achieved (avg score: {avg_score:.2f}), stopping refinement") + break + + return { + "final_result": current_result, + "total_loops": total_loops, + "conversation_history": self.conversation_history, + "evaluation_results": self.evaluation_results, + "intermediate_outputs": self.intermediate_outputs + } + + def __str__(self): + return f"HierarchicalStructuredCommunicationFramework(name={self.name}, generators={len(self.generators)}, evaluators={len(self.evaluators)}, refiners={len(self.refiners)})" + + def __repr__(self): + return self.__str__() + + +# ============================================================================= +# CONVENIENCE ALIASES AND EXPORTS +# ============================================================================= + +# Main framework class +HierarchicalStructuredCommunicationSwarm = HierarchicalStructuredCommunicationFramework + +# Agent classes for easy import +TalkHierarchicalGenerator = HierarchicalStructuredCommunicationGenerator +TalkHierarchicalEvaluator = HierarchicalStructuredCommunicationEvaluator +TalkHierarchicalRefiner = HierarchicalStructuredCommunicationRefiner +TalkHierarchicalSupervisor = HierarchicalStructuredCommunicationSupervisor + +# Schema classes +TalkHierarchicalSchemas = { + "StructuredMessage": StructuredMessageSchema, + "EvaluationResult": EvaluationResultSchema, + "GeneratorResponse": GeneratorResponseSchema, + "EvaluatorResponse": EvaluatorResponseSchema, + "RefinerResponse": RefinerResponseSchema, +} + +# Export all components +__all__ = [ + # Main framework + "HierarchicalStructuredCommunicationFramework", + "HierarchicalStructuredCommunicationSwarm", + + # Agent classes + "HierarchicalStructuredCommunicationGenerator", + "HierarchicalStructuredCommunicationEvaluator", + "HierarchicalStructuredCommunicationRefiner", + "HierarchicalStructuredCommunicationSupervisor", + + # Convenience aliases + "TalkHierarchicalGenerator", + "TalkHierarchicalEvaluator", + "TalkHierarchicalRefiner", + "TalkHierarchicalSupervisor", + + # Data models + "StructuredMessage", + "HierarchicalOrder", + "EvaluationResult", + + # Schemas + "StructuredMessageSchema", + "EvaluationResultSchema", + "GeneratorResponseSchema", + "EvaluatorResponseSchema", + "RefinerResponseSchema", + + # Enums + "CommunicationType", + "AgentRole", + + # Schema collection + "TalkHierarchicalSchemas", +] From 39e3ad3db7fc600960fde0d1d5748fca537255e3 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Mon, 18 Aug 2025 23:10:53 +0300 Subject: [PATCH 14/28] Update hierarchical_structured_communication_framework.py --- ...ical_structured_communication_framework.py | 106 ++++++++++++++---- 1 file changed, 87 insertions(+), 19 deletions(-) diff --git a/swarms/structs/hierarchical_structured_communication_framework.py b/swarms/structs/hierarchical_structured_communication_framework.py index 173b4695..a9e216a4 100644 --- a/swarms/structs/hierarchical_structured_communication_framework.py +++ b/swarms/structs/hierarchical_structured_communication_framework.py @@ -27,6 +27,12 @@ from dataclasses import dataclass from enum import Enum from pydantic import BaseModel, Field +from rich.console import Console +from rich.panel import Panel +from rich.text import Text +from rich.progress import Progress, SpinnerColumn, TextColumn +from rich.table import Table +from rich import print as rprint from swarms.structs.agent import Agent from swarms.structs.base_swarm import BaseSwarm @@ -34,6 +40,8 @@ from swarms.structs.conversation import Conversation from swarms.utils.loguru_logger import initialize_logger from swarms.utils.output_types import OutputType +# Initialize rich console for enhanced output +console = Console() logger = initialize_logger(log_folder="hierarchical_structured_communication_framework") @@ -1058,6 +1066,13 @@ class HierarchicalStructuredCommunicationFramework(BaseSwarm): def init_swarm(self): """Initialize the swarm components""" + # Enhanced logging with rich formatting + console.print(Panel( + f"[bold blue]Initializing {self.name}[/bold blue]\n" + f"[dim]Framework: Talk Structurally, Act Hierarchically[/dim]", + title="Framework Initialization", + border_style="blue" + )) logger.info(f"Initializing {self.name}") # Setup supervisor if not provided @@ -1078,6 +1093,19 @@ class HierarchicalStructuredCommunicationFramework(BaseSwarm): if not self.refiners: self.refiners = [self._create_default_refiner()] + # Enhanced status display + table = Table(title="Framework Components") + table.add_column("Component", style="cyan", no_wrap=True) + table.add_column("Count", style="magenta") + table.add_column("Status", style="green") + + table.add_row("Generators", str(len(self.generators)), "Ready") + table.add_row("Evaluators", str(len(self.evaluators)), "Ready") + table.add_row("Refiners", str(len(self.refiners)), "Ready") + table.add_row("Supervisors", str(1 if self.supervisor else 0), "Ready") + + console.print(table) + logger.info(f"Swarm initialized with {len(self.generators)} generators, " f"{len(self.evaluators)} evaluators, {len(self.refiners)} refiners") @@ -1316,6 +1344,15 @@ Always explain your refinements and how they address the evaluation feedback. self.conversation_history.append(structured_msg) if self.verbose: + # Enhanced structured message display + console.print(Panel( + f"[bold green]Message Sent[/bold green]\n" + f"[cyan]From:[/cyan] {sender}\n" + f"[cyan]To:[/cyan] {recipient}\n" + f"[cyan]Message:[/cyan] {message[:100]}{'...' if len(message) > 100 else ''}", + title="Structured Communication", + border_style="green" + )) logger.info(f"Structured message sent from {sender} to {recipient}") logger.info(f"Message: {message[:100]}...") @@ -1547,33 +1584,64 @@ Please refine the content to address the feedback while maintaining its core str Returns: Final result """ + # Enhanced workflow start display + console.print(Panel( + f"[bold yellow]Starting Hierarchical Structured Communication Workflow[/bold yellow]\n" + f"[cyan]Task:[/cyan] {task[:100]}{'...' if len(task) > 100 else ''}\n" + f"[cyan]Max Loops:[/cyan] {self.max_loops}", + title="Workflow Execution", + border_style="yellow" + )) logger.info(f"Running HierarchicalStructuredComm workflow for task: {task[:100]}...") current_result = None total_loops = 0 - for loop in range(self.max_loops): - total_loops = loop + 1 - logger.info(f"HierarchicalStructuredComm loop {total_loops}/{self.max_loops}") - - # Execute step - step_result = self.step(task, img, *args, **kwargs) - - if "error" in step_result: - logger.error(f"Error in loop {total_loops}: {step_result['error']}") - break - - current_result = step_result["refined_result"] + # Rich progress tracking + with Progress( + SpinnerColumn(), + TextColumn("[progress.description]{task.description}"), + console=console + ) as progress: + task_progress = progress.add_task("Processing workflow...", total=self.max_loops) - # Check if we should continue refining - if loop < self.max_loops - 1: - # Simple continuation logic - could be enhanced - evaluation_scores = [result.score for result in step_result["evaluation_results"]] - avg_score = sum(evaluation_scores) / len(evaluation_scores) if evaluation_scores else 0 + for loop in range(self.max_loops): + total_loops = loop + 1 + progress.update(task_progress, description=f"Loop {total_loops}/{self.max_loops}") + logger.info(f"HierarchicalStructuredComm loop {total_loops}/{self.max_loops}") - if avg_score >= 8.0: # High quality threshold - logger.info(f"High quality achieved (avg score: {avg_score:.2f}), stopping refinement") + # Execute step + step_result = self.step(task, img, *args, **kwargs) + + if "error" in step_result: + console.print(f"[bold red]Error in loop {total_loops}: {step_result['error']}[/bold red]") + logger.error(f"Error in loop {total_loops}: {step_result['error']}") break + + current_result = step_result["refined_result"] + + # Check if we should continue refining + if loop < self.max_loops - 1: + # Simple continuation logic - could be enhanced + evaluation_scores = [result.score for result in step_result["evaluation_results"]] + avg_score = sum(evaluation_scores) / len(evaluation_scores) if evaluation_scores else 0 + + if avg_score >= 8.0: # High quality threshold + console.print(f"[bold green]High quality achieved (avg score: {avg_score:.2f}), stopping refinement[/bold green]") + logger.info(f"High quality achieved (avg score: {avg_score:.2f}), stopping refinement") + break + + progress.advance(task_progress) + + # Enhanced completion display + console.print(Panel( + f"[bold green]Workflow Completed Successfully![/bold green]\n" + f"[cyan]Total Loops:[/cyan] {total_loops}\n" + f"[cyan]Conversation History:[/cyan] {len(self.conversation_history)} messages\n" + f"[cyan]Evaluation Results:[/cyan] {len(self.evaluation_results)} evaluations", + title="Workflow Summary", + border_style="green" + )) return { "final_result": current_result, From c06bfe7a97230f437666a73bb9eea7cb64b2a1d9 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Mon, 18 Aug 2025 23:57:02 +0300 Subject: [PATCH 15/28] Update __init__.py --- swarms/schemas/__init__.py | 6 ------ 1 file changed, 6 deletions(-) diff --git a/swarms/schemas/__init__.py b/swarms/schemas/__init__.py index 9d8dfa29..7eb2ff5d 100644 --- a/swarms/schemas/__init__.py +++ b/swarms/schemas/__init__.py @@ -3,16 +3,10 @@ from swarms.schemas.mcp_schemas import ( MCPConnection, MultipleMCPConnections, ) -from swarms.schemas.hierarchical_structured_communication_schemas import ( - HierarchicalStructuredCommConnection, - MultipleHierarchicalStructuredCommConnections, -) __all__ = [ "Step", "ManySteps", "MCPConnection", "MultipleMCPConnections", - "HierarchicalStructuredCommConnection", - "MultipleHierarchicalStructuredCommConnections", ] From 8e2254c4de61dcb62e9614f78a8b2037833ab93c Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Mon, 18 Aug 2025 23:57:19 +0300 Subject: [PATCH 16/28] Update __init__.py --- swarms/structs/__init__.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/swarms/structs/__init__.py b/swarms/structs/__init__.py index 618d6925..ce9e7850 100644 --- a/swarms/structs/__init__.py +++ b/swarms/structs/__init__.py @@ -95,7 +95,10 @@ from swarms.structs.swarming_architectures import ( staircase_swarm, star_swarm, ) -from swarms.structs.hierarchical_structured_communication_swarm import HierarchicalStructuredCommSwarm +from swarms.structs.hierarchical_structured_communication_framework import ( + HierarchicalStructuredCommunicationFramework as HierarchicalStructuredCommSwarm, + HierarchicalStructuredCommunicationFramework as TalkHierarchicalSwarm, +) __all__ = [ "Agent", From a0dbdba079a47fb30249a72aacc38b980af8233f Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Mon, 18 Aug 2025 23:58:38 +0300 Subject: [PATCH 17/28] Update __init__.py --- swarms/agents/__init__.py | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/swarms/agents/__init__.py b/swarms/agents/__init__.py index a0ef7378..3cd0e30a 100644 --- a/swarms/agents/__init__.py +++ b/swarms/agents/__init__.py @@ -11,11 +11,16 @@ from swarms.agents.reasoning_agents import ( agent_types, ) from swarms.agents.reasoning_duo import ReasoningDuo -from swarms.agents.hierarchical_structured_communication_agents import ( - HierarchicalStructuredCommGenerator, - HierarchicalStructuredCommEvaluator, - HierarchicalStructuredCommRefiner, - HierarchicalStructuredCommSupervisor, +from swarms.structs.hierarchical_structured_communication_framework import ( + HierarchicalStructuredCommunicationGenerator as HierarchicalStructuredCommGenerator, + HierarchicalStructuredCommunicationEvaluator as HierarchicalStructuredCommEvaluator, + HierarchicalStructuredCommunicationRefiner as HierarchicalStructuredCommRefiner, + HierarchicalStructuredCommunicationSupervisor as HierarchicalStructuredCommSupervisor, + # Convenience aliases + TalkHierarchicalGenerator, + TalkHierarchicalEvaluator, + TalkHierarchicalRefiner, + TalkHierarchicalSupervisor, ) from swarms.structs.stopping_conditions import ( check_cancelled, @@ -50,6 +55,10 @@ __all__ = [ "ReflexionAgent", "GKPAgent", "AgentJudge", + "HierarchicalStructuredCommGenerator", + "HierarchicalStructuredCommEvaluator", + "HierarchicalStructuredCommRefiner", + "HierarchicalStructuredCommSupervisor", "TalkHierarchicalGenerator", "TalkHierarchicalEvaluator", "TalkHierarchicalRefiner", From 9e63caa35124745960abf3c802e976a1b58a7a67 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Mon, 18 Aug 2025 23:59:53 +0300 Subject: [PATCH 18/28] Delete examples/multi_agent/full_hierarchical_structured_communication_test.py --- ...rarchical_structured_communication_test.py | 718 ------------------ 1 file changed, 718 deletions(-) delete mode 100644 examples/multi_agent/full_hierarchical_structured_communication_test.py diff --git a/examples/multi_agent/full_hierarchical_structured_communication_test.py b/examples/multi_agent/full_hierarchical_structured_communication_test.py deleted file mode 100644 index 4f6a33ea..00000000 --- a/examples/multi_agent/full_hierarchical_structured_communication_test.py +++ /dev/null @@ -1,718 +0,0 @@ -""" -Full Hierarchical Structured Communication Framework Test with Ollama - -This script demonstrates the complete Hierarchical Structured Communication framework -using Ollama for local model inference. It showcases all components: -- Structured Communication Protocol -- Hierarchical Evaluation System -- Graph-based Agent Orchestration -- Iterative Refinement Process -""" - -import requests -import json -import time -import argparse -import sys -from typing import List, Dict, Any -from dataclasses import dataclass -from enum import Enum - -# Color support -try: - from colorama import init, Fore, Back, Style - init(autoreset=True) - COLORS_AVAILABLE = True -except ImportError: - # Fallback for systems without colorama - class Fore: - RED = GREEN = BLUE = YELLOW = MAGENTA = CYAN = WHITE = "" - class Back: - BLACK = RED = GREEN = BLUE = YELLOW = MAGENTA = CYAN = WHITE = "" - class Style: - BRIGHT = DIM = NORMAL = RESET_ALL = "" - COLORS_AVAILABLE = False - -class CommunicationType(str, Enum): - """Types of communication in the structured protocol""" - MESSAGE = "message" # M_ij: Specific task instructions - BACKGROUND = "background" # B_ij: Context and problem background - INTERMEDIATE_OUTPUT = "intermediate_output" # I_ij: Intermediate results - -@dataclass -class StructuredMessage: - """Structured communication message following HierarchicalStructuredComm protocol""" - message: str - background: str - intermediate_output: str - sender: str - recipient: str - timestamp: str = None - -@dataclass -class EvaluationResult: - """Result from evaluation team member""" - evaluator_name: str - criterion: str - score: float - feedback: str - confidence: float - -class HierarchicalStructuredCommunicationFramework: - """ - Full implementation of Hierarchical Structured Communication framework - using direct Ollama API calls - """ - - def __init__(self, model_name: str = "llama3:latest", verbose: bool = True, max_display_length: int = None): - self.model_name = model_name - self.verbose = verbose - self.max_display_length = max_display_length - self.conversation_history: List[StructuredMessage] = [] - self.intermediate_outputs: Dict[str, str] = {} - self.evaluation_results: List[EvaluationResult] = [] - - # Check Ollama availability - self._check_ollama() - - def _print_colored(self, text: str, color: str = Fore.WHITE, style: str = Style.NORMAL): - """Print colored text if colors are available""" - if COLORS_AVAILABLE: - print(f"{color}{style}{text}{Style.RESET_ALL}") - else: - print(text) - - def _print_header(self, text: str): - """Print a header with styling""" - self._print_colored(f"\n{text}", Fore.CYAN, Style.BRIGHT) - self._print_colored("=" * len(text), Fore.CYAN) - - def _print_subheader(self, text: str): - """Print a subheader with styling""" - self._print_colored(f"\n{text}", Fore.YELLOW, Style.BRIGHT) - self._print_colored("-" * len(text), Fore.YELLOW) - - def _print_success(self, text: str): - """Print success message""" - self._print_colored(text, Fore.GREEN, Style.BRIGHT) - - def _print_error(self, text: str): - """Print error message""" - self._print_colored(text, Fore.RED, Style.BRIGHT) - - def _print_info(self, text: str): - """Print info message""" - self._print_colored(text, Fore.BLUE) - - def _print_warning(self, text: str): - """Print warning message""" - self._print_colored(text, Fore.YELLOW) - - def _truncate_text(self, text: str, max_length: int = None) -> str: - """Truncate text for display if needed""" - if max_length is None: - max_length = self.max_display_length - - if max_length and len(text) > max_length: - return text[:max_length] + "..." - return text - - def _check_ollama(self): - """Check if Ollama is running and get available models""" - try: - response = requests.get("http://localhost:11434/api/tags", timeout=5) - if response.status_code == 200: - models = response.json().get('models', []) - model_names = [model.get('name') for model in models] - - if self.verbose: - self._print_success("Ollama is running") - self._print_info(f"Available models: {', '.join(model_names)}") - - # Verify our model is available - if not any(self.model_name in name for name in model_names): - self._print_warning(f"Model {self.model_name} not found, using first available") - self.model_name = model_names[0] if model_names else "llama3:latest" - - self._print_info(f"Using model: {self.model_name}") - else: - raise Exception("Ollama not responding properly") - except Exception as e: - self._print_error(f"Cannot connect to Ollama: {e}") - self._print_info("Please ensure Ollama is running: ollama serve") - raise - - def _call_ollama(self, prompt: str, temperature: float = 0.7, max_tokens: int = 1000) -> str: - """Make a call to Ollama API with infinite timeout""" - try: - payload = { - "model": self.model_name, - "prompt": prompt, - "stream": False, - "options": { - "temperature": temperature, - "num_predict": max_tokens - } - } - - # Set timeout to None for infinite timeout - response = requests.post( - "http://localhost:11434/api/generate", - json=payload, - timeout=None - ) - - if response.status_code == 200: - return response.json().get('response', '') - else: - raise Exception(f"Ollama API error: {response.status_code}") - - except Exception as e: - self._print_error(f"Error calling Ollama: {e}") - return f"Error: {e}" - - def send_structured_message( - self, - sender: str, - recipient: str, - message: str, - background: str = "", - intermediate_output: str = "" - ) -> StructuredMessage: - """Send a structured message following the HierarchicalStructuredComm protocol""" - structured_msg = StructuredMessage( - message=message, - background=background, - intermediate_output=intermediate_output, - sender=sender, - recipient=recipient, - timestamp=time.strftime("%Y-%m-%d %H:%M:%S") - ) - - self.conversation_history.append(structured_msg) - - if self.verbose: - display_message = self._truncate_text(message, 100) - self._print_info(f"{sender} -> {recipient}: {display_message}") - - return structured_msg - - def generate_content(self, task: str, context: str = "") -> str: - """Generate initial content using generator agent""" - if self.verbose: - self._print_subheader("Step 1: Generating initial content") - - # Create structured message - message = f"Generate comprehensive content for: {task}" - background = f"Task: {task}\nContext: {context}\n\nProvide detailed, well-structured content." - - self.send_structured_message( - sender="Supervisor", - recipient="Generator", - message=message, - background=background - ) - - # Generate content - prompt = f"""You are a Content Generator in a Hierarchical Structured Communication framework. - -Task: {task} -Context: {context} - -Generate comprehensive, well-structured content that addresses the task thoroughly. -Provide detailed explanations, examples, and insights. - -Content:""" - - result = self._call_ollama(prompt, temperature=0.7, max_tokens=1500) - self.intermediate_outputs["generator"] = result - - if self.verbose: - self._print_info("Generated content:") - print(result) # Print full content without truncation - - return result - - def evaluate_content(self, content: str, criteria: List[str] = None) -> List[EvaluationResult]: - """Evaluate content using hierarchical evaluation system""" - if criteria is None: - criteria = ["accuracy", "completeness", "clarity", "relevance"] - - if self.verbose: - self._print_subheader("Step 2: Hierarchical evaluation") - - results = [] - - for criterion in criteria: - if self.verbose: - self._print_info(f" Evaluating {criterion}...") - - # Create structured message for evaluator - message = f"Evaluate content for {criterion} criterion" - background = f"Content to evaluate: {content[:500]}...\nCriterion: {criterion}" - - self.send_structured_message( - sender="EvaluationSupervisor", - recipient=f"{criterion.capitalize()}Evaluator", - message=message, - background=background, - intermediate_output=content - ) - - # Evaluate with specific criterion - prompt = f"""You are a {criterion.capitalize()} Evaluator in a hierarchical evaluation system. - -Content to evaluate: -{content} - -Evaluation criterion: {criterion} - -Please provide: -1. Score (0-10) -2. Detailed feedback -3. Confidence level (0-1) -4. Specific suggestions for improvement - -Evaluation:""" - - evaluation_response = self._call_ollama(prompt, temperature=0.3, max_tokens=800) - - # Parse evaluation (simplified parsing) - score = 7.0 # Default score - feedback = evaluation_response - confidence = 0.8 # Default confidence - - # Try to extract score from response - if "score" in evaluation_response.lower(): - try: - # Look for patterns like "score: 8" or "8/10" - import re - score_match = re.search(r'(\d+(?:\.\d+)?)/10|score[:\s]*(\d+(?:\.\d+)?)', evaluation_response.lower()) - if score_match: - score = float(score_match.group(1) or score_match.group(2)) - except: - pass - - result = EvaluationResult( - evaluator_name=f"{criterion.capitalize()}Evaluator", - criterion=criterion, - score=score, - feedback=feedback, - confidence=confidence - ) - - results.append(result) - - if self.verbose: - self._print_info(f" Score: {score}/10") - print(f" Feedback: {feedback}") # Print full feedback - - self.evaluation_results.extend(results) - return results - - def refine_content(self, original_content: str, evaluation_results: List[EvaluationResult]) -> str: - """Refine content based on evaluation feedback""" - if self.verbose: - self._print_subheader("Step 3: Refining content") - - # Create feedback summary - feedback_summary = "\n\n".join([ - f"{result.criterion.capitalize()} (Score: {result.score}/10):\n{result.feedback}" - for result in evaluation_results - ]) - - # Create structured message for refinement - message = "Refine content based on evaluation feedback" - background = f"Original content: {original_content[:500]}...\n\nEvaluation feedback:\n{feedback_summary}" - - self.send_structured_message( - sender="Supervisor", - recipient="Refiner", - message=message, - background=background, - intermediate_output=original_content - ) - - # Refine content - prompt = f"""You are a Content Refiner in a Hierarchical Structured Communication framework. - -Original Content: -{original_content} - -Evaluation Feedback: -{feedback_summary} - -Please refine the content to address the feedback while maintaining its core strengths. -Focus on the specific issues mentioned in the evaluation and provide improvements. - -Refined Content:""" - - refined_result = self._call_ollama(prompt, temperature=0.5, max_tokens=1500) - self.intermediate_outputs["refiner"] = refined_result - - if self.verbose: - self._print_info("Refined content:") - print(refined_result) # Print full content without truncation - - return refined_result - - def run_hierarchical_workflow(self, task: str, max_iterations: int = 3, quality_threshold: float = 8.0) -> Dict[str, Any]: - """Run the complete Hierarchical Structured Communication workflow""" - self._print_header("Starting Hierarchical Structured Communication Workflow") - self._print_info(f"Task: {task}") - self._print_info(f"Max iterations: {max_iterations}") - self._print_info(f"Quality threshold: {quality_threshold}") - - start_time = time.time() - current_content = None - iteration = 0 - - for iteration in range(max_iterations): - self._print_subheader(f"Iteration {iteration + 1}/{max_iterations}") - - # Step 1: Generate/Refine content - if iteration == 0: - current_content = self.generate_content(task) - else: - current_content = self.refine_content(current_content, evaluation_results) - - # Step 2: Evaluate content - evaluation_results = self.evaluate_content(current_content) - - # Step 3: Check quality threshold - avg_score = sum(result.score for result in evaluation_results) / len(evaluation_results) - self._print_info(f"Average evaluation score: {avg_score:.2f}/10") - - if avg_score >= quality_threshold: - self._print_success("Quality threshold met! Stopping refinement.") - break - - if iteration < max_iterations - 1: - self._print_info("Continuing refinement...") - - total_time = time.time() - start_time - - return { - "final_content": current_content, - "total_iterations": iteration + 1, - "average_score": avg_score, - "evaluation_results": evaluation_results, - "conversation_history": self.conversation_history, - "intermediate_outputs": self.intermediate_outputs, - "total_time": total_time - } - - def print_workflow_summary(self, result: Dict[str, Any]): - """Print a comprehensive summary of the workflow results""" - self._print_header("TALK HIERARCHICAL WORKFLOW COMPLETED") - - self._print_subheader("PERFORMANCE SUMMARY") - self._print_info(f" Total iterations: {result['total_iterations']}") - self._print_info(f" Final average score: {result['average_score']:.2f}/10") - self._print_info(f" Total time: {result['total_time']:.2f} seconds") - self._print_info(f" Messages exchanged: {len(result['conversation_history'])}") - - self._print_subheader("FINAL CONTENT") - print(result['final_content']) - - self._print_subheader("EVALUATION RESULTS") - for eval_result in result['evaluation_results']: - self._print_info(f" {eval_result.criterion.capitalize()}: {eval_result.score}/10") - print(f" Feedback: {eval_result.feedback}") - - self._print_subheader("COMMUNICATION HISTORY") - for i, msg in enumerate(result['conversation_history']): - self._print_info(f" {i+1}. {msg.sender} -> {msg.recipient}") - print(f" Message: {msg.message}") - print(f" Background: {msg.background}") - print(f" Intermediate Output: {msg.intermediate_output}") - print(f" Time: {msg.timestamp}") - -def test_basic_workflow(): - """Test basic Hierarchical Structured Communication workflow""" - print("Test 1: Basic Workflow") - print("=" * 50) - - framework = HierarchicalStructuredCommunicationFramework(model_name="llama3:latest", verbose=True) - - task = "Explain the concept of neural networks and their applications in modern AI" - - result = framework.run_hierarchical_workflow( - task=task, - max_iterations=2, - quality_threshold=7.5 - ) - - framework.print_workflow_summary(result) - return result - -def test_complex_workflow(): - """Test complex workflow with multiple iterations""" - print("Test 2: Complex Workflow") - print("=" * 50) - - framework = HierarchicalStructuredCommunicationFramework(model_name="llama3:latest", verbose=True) - - task = """Create a comprehensive guide on machine learning that covers: -1. Basic concepts and definitions -2. Types of machine learning (supervised, unsupervised, reinforcement) -3. Common algorithms and their use cases -4. Real-world applications and examples -5. Future trends and challenges - -Make it suitable for both beginners and intermediate learners.""" - - result = framework.run_hierarchical_workflow( - task=task, - max_iterations=3, - quality_threshold=8.0 - ) - - framework.print_workflow_summary(result) - return result - -def test_structured_communication(): - """Test structured communication protocol in isolation""" - print("Test 3: Structured Communication Protocol") - print("=" * 50) - - framework = HierarchicalStructuredCommunicationFramework(model_name="llama3:latest", verbose=True) - - # Test structured message exchange - msg1 = framework.send_structured_message( - sender="Supervisor", - recipient="Generator", - message="Generate content about renewable energy", - background="Focus on solar and wind power", - intermediate_output="Previous discussion covered climate change" - ) - - msg2 = framework.send_structured_message( - sender="Generator", - recipient="Evaluator", - message="Content ready for evaluation", - background="Generated comprehensive guide on renewable energy", - intermediate_output="Detailed explanation of solar and wind technologies" - ) - - print("Structured Messages:") - for i, msg in enumerate(framework.conversation_history): - print(f"Message {i+1}:") - print(f" From: {msg.sender}") - print(f" To: {msg.recipient}") - print(f" Message (M_ij): {msg.message}") - print(f" Background (B_ij): {msg.background}") - print(f" Intermediate Output (I_ij): {msg.intermediate_output}") - print(f" Timestamp: {msg.timestamp}") - -def test_quick_demo(): - """Quick demonstration with smaller model and shorter prompts""" - print("Test 4: Quick Demo") - print("=" * 50) - - # Use a smaller model for faster response - framework = HierarchicalStructuredCommunicationFramework(model_name="llama3.2:3b", verbose=True) - - task = "Explain what artificial intelligence is in simple terms" - - result = framework.run_hierarchical_workflow( - task=task, - max_iterations=1, - quality_threshold=6.0 - ) - - framework.print_workflow_summary(result) - return result - -def interactive_mode(): - """Interactive mode for custom tasks""" - print("Interactive Hierarchical Structured Communication Framework") - print("=" * 50) - - # Get user input - model_name = input("Enter model name (default: llama3:latest): ").strip() or "llama3:latest" - task = input("Enter your task: ").strip() - - if not task: - print("No task provided. Exiting.") - return - - max_iterations = input("Enter max iterations (default: 2): ").strip() - max_iterations = int(max_iterations) if max_iterations.isdigit() else 2 - - quality_threshold = input("Enter quality threshold (default: 7.0): ").strip() - quality_threshold = float(quality_threshold) if quality_threshold.replace('.', '').isdigit() else 7.0 - - # Create framework and run - framework = HierarchicalStructuredCommunicationFramework(model_name=model_name, verbose=True) - - result = framework.run_hierarchical_workflow( - task=task, - max_iterations=max_iterations, - quality_threshold=quality_threshold - ) - - framework.print_workflow_summary(result) - return result - -def main(): - """Main CLI entry point""" - parser = argparse.ArgumentParser( - description="Hierarchical Structured Communication Framework Test Suite", - formatter_class=argparse.RawDescriptionHelpFormatter, - epilog=""" -Examples: - python full_hierarchical_structured_communication_test.py --quick - python full_hierarchical_structured_communication_test.py --interactive - python full_hierarchical_structured_communication_test.py --model llama3.2:3b --task "Explain AI" - python full_hierarchical_structured_communication_test.py --all - """ - ) - - parser.add_argument( - "--quick", - action="store_true", - help="Run quick demo test" - ) - - parser.add_argument( - "--basic", - action="store_true", - help="Run basic workflow test" - ) - - parser.add_argument( - "--complex", - action="store_true", - help="Run complex workflow test" - ) - - parser.add_argument( - "--communication", - action="store_true", - help="Run structured communication test" - ) - - parser.add_argument( - "--all", - action="store_true", - help="Run all tests" - ) - - parser.add_argument( - "--interactive", - action="store_true", - help="Run in interactive mode" - ) - - parser.add_argument( - "--model", - type=str, - default="llama3:latest", - help="Ollama model to use (default: llama3:latest)" - ) - - parser.add_argument( - "--task", - type=str, - help="Custom task for single run" - ) - - parser.add_argument( - "--iterations", - type=int, - default=2, - help="Maximum iterations (default: 2)" - ) - - parser.add_argument( - "--threshold", - type=float, - default=7.0, - help="Quality threshold (default: 7.0)" - ) - - parser.add_argument( - "--no-color", - action="store_true", - help="Disable colored output" - ) - - parser.add_argument( - "--quiet", - action="store_true", - help="Disable verbose output (verbose is enabled by default)" - ) - - args = parser.parse_args() - - # Disable colors if requested - global COLORS_AVAILABLE - if args.no_color: - COLORS_AVAILABLE = False - - # Print header - if COLORS_AVAILABLE: - print(f"{Fore.CYAN}{Style.BRIGHT}") - print("=" * 80) - print("TALK HIERARCHICAL FRAMEWORK TEST SUITE") - print("=" * 80) - print(f"{Style.RESET_ALL}") - else: - print("=" * 80) - print("TALK HIERARCHICAL FRAMEWORK TEST SUITE") - print("=" * 80) - - print("Testing Hierarchical Structured Communication framework with Ollama") - print("=" * 80) - - try: - if args.interactive: - interactive_mode() - elif args.task: - # Single task run - framework = HierarchicalStructuredCommunicationFramework( - model_name=args.model, - verbose=not args.quiet - ) - result = framework.run_hierarchical_workflow( - task=args.task, - max_iterations=args.iterations, - quality_threshold=args.threshold - ) - framework.print_workflow_summary(result) - elif args.quick: - test_quick_demo() - elif args.basic: - test_basic_workflow() - elif args.complex: - test_complex_workflow() - elif args.communication: - test_structured_communication() - elif args.all: - # Run all tests - test_quick_demo() - test_basic_workflow() - test_complex_workflow() - test_structured_communication() - else: - # Default: run quick demo - test_quick_demo() - - print("All tests completed successfully!") - print("Framework Features Demonstrated:") - print(" Structured Communication Protocol (M_ij, B_ij, I_ij)") - print(" Hierarchical Evaluation System") - print(" Iterative Refinement Process") - print(" Graph-based Agent Orchestration") - print(" Local Ollama Integration") - - except KeyboardInterrupt: - print("\nInterrupted by user") - except Exception as e: - print(f"Error during testing: {e}") - import traceback - traceback.print_exc() - -if __name__ == "__main__": - main() \ No newline at end of file From 44bf2061a6fa98f3053c93ea7e960002720d0920 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Tue, 19 Aug 2025 00:03:41 +0300 Subject: [PATCH 19/28] Create single_file_hierarchical_framework_example.py --- ...gle_file_hierarchical_framework_example.py | 310 ++++++++++++++++++ 1 file changed, 310 insertions(+) create mode 100644 examples/multi_agent/hscf/single_file_hierarchical_framework_example.py diff --git a/examples/multi_agent/hscf/single_file_hierarchical_framework_example.py b/examples/multi_agent/hscf/single_file_hierarchical_framework_example.py new file mode 100644 index 00000000..70221f29 --- /dev/null +++ b/examples/multi_agent/hscf/single_file_hierarchical_framework_example.py @@ -0,0 +1,310 @@ +""" +Single-File Hierarchical Structured Communication Framework Example + +This example demonstrates how to use the consolidated single-file implementation +of the Talk Structurally, Act Hierarchically framework. + +All components are now in one file: hierarchical_structured_communication_framework.py +""" + +import os +import sys +from typing import Dict, Any + +# Add the project root to the Python path +project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', '..')) +sys.path.insert(0, project_root) + +from dotenv import load_dotenv + +# Import everything from the single file +from swarms.structs.hierarchical_structured_communication_framework import ( + HierarchicalStructuredCommunicationFramework, + HierarchicalStructuredCommunicationGenerator, + HierarchicalStructuredCommunicationEvaluator, + HierarchicalStructuredCommunicationRefiner, + HierarchicalStructuredCommunicationSupervisor, + # Convenience aliases + TalkHierarchicalGenerator, + TalkHierarchicalEvaluator, + TalkHierarchicalRefiner, + TalkHierarchicalSupervisor, +) + +# Load environment variables +load_dotenv() + + +def example_basic_usage(): + """ + Basic usage example with default agents + """ + print("=" * 80) + print("BASIC USAGE EXAMPLE") + print("=" * 80) + + # Create framework with default configuration + framework = HierarchicalStructuredCommunicationFramework( + name="BasicFramework", + max_loops=2, + verbose=True + ) + + # Run a simple task + task = "Explain the benefits of structured communication in multi-agent systems" + + print(f"Task: {task}") + print("Running framework...") + + result = framework.run(task) + + print("\n" + "=" * 50) + print("FINAL RESULT") + print("=" * 50) + print(result["final_result"]) + + print(f"\nTotal loops: {result['total_loops']}") + print(f"Conversation history entries: {len(result['conversation_history'])}") + print(f"Evaluation results: {len(result['evaluation_results'])}") + + +def example_custom_agents(): + """ + Example using custom specialized agents + """ + print("\n" + "=" * 80) + print("CUSTOM AGENTS EXAMPLE") + print("=" * 80) + + # Create custom agents using the convenience aliases + generator = TalkHierarchicalGenerator( + agent_name="ContentCreator", + model_name="gpt-4o-mini", + verbose=True + ) + + evaluator1 = TalkHierarchicalEvaluator( + agent_name="AccuracyChecker", + evaluation_criteria=["accuracy", "technical_correctness"], + model_name="gpt-4o-mini", + verbose=True + ) + + evaluator2 = TalkHierarchicalEvaluator( + agent_name="ClarityChecker", + evaluation_criteria=["clarity", "readability", "coherence"], + model_name="gpt-4o-mini", + verbose=True + ) + + refiner = TalkHierarchicalRefiner( + agent_name="ContentImprover", + model_name="gpt-4o-mini", + verbose=True + ) + + supervisor = TalkHierarchicalSupervisor( + agent_name="WorkflowManager", + model_name="gpt-4o-mini", + verbose=True + ) + + # Create framework with custom agents + framework = HierarchicalStructuredCommunicationFramework( + name="CustomFramework", + supervisor=supervisor, + generators=[generator], + evaluators=[evaluator1, evaluator2], + refiners=[refiner], + max_loops=3, + verbose=True + ) + + # Run a complex task + task = "Design a comprehensive machine learning pipeline for sentiment analysis" + + print(f"Task: {task}") + print("Running framework with custom agents...") + + result = framework.run(task) + + print("\n" + "=" * 50) + print("FINAL RESULT") + print("=" * 50) + print(result["final_result"]) + + print(f"\nTotal loops: {result['total_loops']}") + print(f"Conversation history entries: {len(result['conversation_history'])}") + print(f"Evaluation results: {len(result['evaluation_results'])}") + + +def example_ollama_integration(): + """ + Example using Ollama for local inference + """ + print("\n" + "=" * 80) + print("OLLAMA INTEGRATION EXAMPLE") + print("=" * 80) + + # Create framework with Ollama configuration + framework = HierarchicalStructuredCommunicationFramework( + name="OllamaFramework", + max_loops=2, + verbose=True, + model_name="llama3:latest", + use_ollama=True, + ollama_base_url="http://localhost:11434/v1", + ollama_api_key="ollama" + ) + + # Run a task with local model + task = "Explain the concept of structured communication protocols" + + print(f"Task: {task}") + print("Running framework with Ollama...") + + try: + result = framework.run(task) + + print("\n" + "=" * 50) + print("FINAL RESULT") + print("=" * 50) + print(result["final_result"]) + + print(f"\nTotal loops: {result['total_loops']}") + print(f"Conversation history entries: {len(result['conversation_history'])}") + print(f"Evaluation results: {len(result['evaluation_results'])}") + + except Exception as e: + print(f"Error with Ollama: {e}") + print("Make sure Ollama is running: ollama serve") + + +def example_structured_communication(): + """ + Example demonstrating structured communication protocol + """ + print("\n" + "=" * 80) + print("STRUCTURED COMMUNICATION EXAMPLE") + print("=" * 80) + + # Create framework + framework = HierarchicalStructuredCommunicationFramework( + name="CommunicationDemo", + verbose=True + ) + + # Demonstrate structured message sending + print("Sending structured message...") + + structured_msg = framework.send_structured_message( + sender="Supervisor", + recipient="Generator", + message="Create a technical documentation outline", + background="For a Python library focused on data processing", + intermediate_output="Previous research on similar libraries" + ) + + print(f"Message sent: {structured_msg.message}") + print(f"Background: {structured_msg.background}") + print(f"Intermediate output: {structured_msg.intermediate_output}") + print(f"From: {structured_msg.sender} -> To: {structured_msg.recipient}") + + +def example_agent_interaction(): + """ + Example showing direct agent interaction + """ + print("\n" + "=" * 80) + print("AGENT INTERACTION EXAMPLE") + print("=" * 80) + + # Create agents + generator = TalkHierarchicalGenerator( + agent_name="ContentGenerator", + verbose=True + ) + + evaluator = TalkHierarchicalEvaluator( + agent_name="QualityEvaluator", + evaluation_criteria=["accuracy", "clarity"], + verbose=True + ) + + refiner = TalkHierarchicalRefiner( + agent_name="ContentRefiner", + verbose=True + ) + + # Generate content + print("1. Generating content...") + gen_result = generator.generate_with_structure( + message="Create a brief explanation of machine learning", + background="For beginners with no technical background", + intermediate_output="" + ) + + print(f"Generated content: {gen_result.content[:200]}...") + + # Evaluate content + print("\n2. Evaluating content...") + eval_result = evaluator.evaluate_with_criterion( + content=gen_result.content, + criterion="clarity" + ) + + print(f"Evaluation score: {eval_result.score}/10") + print(f"Feedback: {eval_result.feedback[:200]}...") + + # Refine content + print("\n3. Refining content...") + refine_result = refiner.refine_with_feedback( + original_content=gen_result.content, + evaluation_results=[eval_result] + ) + + print(f"Refined content: {refine_result.refined_content[:200]}...") + print(f"Changes made: {refine_result.changes_made}") + + +def main(): + """ + Main function to run all examples + """ + print("SINGLE-FILE HIERARCHICAL STRUCTURED COMMUNICATION FRAMEWORK") + print("=" * 80) + print("This demonstrates the consolidated single-file implementation") + print("based on the research paper: arXiv:2502.11098") + print("=" * 80) + + try: + # Run examples + example_basic_usage() + example_custom_agents() + example_ollama_integration() + example_structured_communication() + example_agent_interaction() + + print("\n" + "=" * 80) + print("ALL EXAMPLES COMPLETED SUCCESSFULLY!") + print("=" * 80) + print("Framework Features Demonstrated:") + print("✓ Single-file implementation") + print("✓ Structured Communication Protocol (M_ij, B_ij, I_ij)") + print("✓ Hierarchical Evaluation System") + print("✓ Iterative Refinement Process") + print("✓ Flexible Model Configuration (OpenAI/Ollama)") + print("✓ Custom Agent Specialization") + print("✓ Direct Agent Interaction") + print("✓ Convenience Aliases") + + except KeyboardInterrupt: + print("\nInterrupted by user") + except Exception as e: + print(f"Error during execution: {e}") + import traceback + traceback.print_exc() + + +if __name__ == "__main__": + main() From 6f5a348511b3029cfca942e2f7790353690838fd Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Tue, 19 Aug 2025 14:12:28 +0300 Subject: [PATCH 20/28] Update __init__.py --- swarms/agents/__init__.py | 41 --------------------------------------- 1 file changed, 41 deletions(-) diff --git a/swarms/agents/__init__.py b/swarms/agents/__init__.py index 3cd0e30a..ca3d52e6 100644 --- a/swarms/agents/__init__.py +++ b/swarms/agents/__init__.py @@ -11,41 +11,8 @@ from swarms.agents.reasoning_agents import ( agent_types, ) from swarms.agents.reasoning_duo import ReasoningDuo -from swarms.structs.hierarchical_structured_communication_framework import ( - HierarchicalStructuredCommunicationGenerator as HierarchicalStructuredCommGenerator, - HierarchicalStructuredCommunicationEvaluator as HierarchicalStructuredCommEvaluator, - HierarchicalStructuredCommunicationRefiner as HierarchicalStructuredCommRefiner, - HierarchicalStructuredCommunicationSupervisor as HierarchicalStructuredCommSupervisor, - # Convenience aliases - TalkHierarchicalGenerator, - TalkHierarchicalEvaluator, - TalkHierarchicalRefiner, - TalkHierarchicalSupervisor, -) -from swarms.structs.stopping_conditions import ( - check_cancelled, - check_complete, - check_done, - check_end, - check_error, - check_exit, - check_failure, - check_finished, - check_stopped, - check_success, -) __all__ = [ - "check_done", - "check_finished", - "check_complete", - "check_success", - "check_failure", - "check_error", - "check_stopped", - "check_cancelled", - "check_exit", - "check_end", "create_agents_from_yaml", "IterativeReflectiveExpansion", "SelfConsistencyAgent", @@ -55,12 +22,4 @@ __all__ = [ "ReflexionAgent", "GKPAgent", "AgentJudge", - "HierarchicalStructuredCommGenerator", - "HierarchicalStructuredCommEvaluator", - "HierarchicalStructuredCommRefiner", - "HierarchicalStructuredCommSupervisor", - "TalkHierarchicalGenerator", - "TalkHierarchicalEvaluator", - "TalkHierarchicalRefiner", - "TalkHierarchicalSupervisor", ] From 6ac6f4c1aa5319fcc8571a12f204cbb98b1c0b71 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Tue, 19 Aug 2025 14:13:30 +0300 Subject: [PATCH 21/28] Update __init__.py --- swarms/structs/__init__.py | 36 +++++++++++++++++++++++++++++------- 1 file changed, 29 insertions(+), 7 deletions(-) diff --git a/swarms/structs/__init__.py b/swarms/structs/__init__.py index f318d9e5..08d4e889 100644 --- a/swarms/structs/__init__.py +++ b/swarms/structs/__init__.py @@ -1,6 +1,5 @@ from swarms.structs.agent import Agent from swarms.structs.agent_builder import AgentsBuilder -from swarms.structs.agent_rearrange import AgentRearrange, rearrange from swarms.structs.auto_swarm_builder import AutoSwarmBuilder from swarms.structs.base_structure import BaseStructure from swarms.structs.base_swarm import BaseSwarm @@ -10,7 +9,7 @@ from swarms.structs.board_of_directors_swarm import ( ) from swarms.structs.concurrent_workflow import ConcurrentWorkflow from swarms.structs.conversation import Conversation -from swarms.structs.council_as_judge import CouncilAsAJudge +from swarms.structs.council_judge import CouncilAsAJudge from swarms.structs.cron_job import CronJob from swarms.structs.de_hallucination_swarm import DeHallucinationSwarm from swarms.structs.deep_research_swarm import DeepResearchSwarm @@ -25,8 +24,8 @@ from swarms.structs.groupchat import ( expertise_based, ) from swarms.structs.heavy_swarm import HeavySwarm -from swarms.structs.hiearchical_swarm import HierarchicalSwarm -from swarms.structs.hybrid_hiearchical_peer_swarm import ( +from swarms.structs.hierarchical_swarm import HierarchicalSwarm +from swarms.structs.hybrid_hierarchical_peer_swarm import ( HybridHierarchicalClusterSwarm, ) from swarms.structs.interactive_groupchat import ( @@ -67,10 +66,23 @@ from swarms.structs.multi_agent_exec import ( run_single_agent, ) from swarms.structs.multi_agent_router import MultiAgentRouter +from swarms.structs.rearrange import AgentRearrange, rearrange from swarms.structs.round_robin import RoundRobinSwarm from swarms.structs.sequential_workflow import SequentialWorkflow from swarms.structs.spreadsheet_swarm import SpreadSheetSwarm -from swarms.structs.swarm_rearrange import SwarmRearrange +from swarms.structs.stopping_conditions import ( + check_cancelled, + check_complete, + check_done, + check_end, + check_error, + check_exit, + check_failure, + check_finished, + check_stopped, + check_success, +) +from swarms.structs.swarm_arange import SwarmRearrange from swarms.structs.swarm_router import ( SwarmRouter, SwarmType, @@ -97,7 +109,6 @@ from swarms.structs.swarming_architectures import ( ) from swarms.structs.hierarchical_structured_communication_framework import ( HierarchicalStructuredCommunicationFramework as HierarchicalStructuredCommSwarm, - HierarchicalStructuredCommunicationFramework as TalkHierarchicalSwarm, ) __all__ = [ @@ -178,5 +189,16 @@ __all__ = [ "HierarchicalSwarm", "HeavySwarm", "CronJob", - "TalkHierarchicalSwarm", + "HierarchicalStructuredCommSwarm", + # Stopping conditions + "check_done", + "check_finished", + "check_complete", + "check_success", + "check_failure", + "check_error", + "check_stopped", + "check_cancelled", + "check_exit", + "check_end", ] From 49835180397bf94cb3e6ef5408166519b0df2122 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Tue, 19 Aug 2025 14:16:58 +0300 Subject: [PATCH 22/28] Update hierarchical_structured_communication_framework.py --- ...ical_structured_communication_framework.py | 24 ------------------- 1 file changed, 24 deletions(-) diff --git a/swarms/structs/hierarchical_structured_communication_framework.py b/swarms/structs/hierarchical_structured_communication_framework.py index a9e216a4..377dde90 100644 --- a/swarms/structs/hierarchical_structured_communication_framework.py +++ b/swarms/structs/hierarchical_structured_communication_framework.py @@ -1665,21 +1665,6 @@ Please refine the content to address the feedback while maintaining its core str # Main framework class HierarchicalStructuredCommunicationSwarm = HierarchicalStructuredCommunicationFramework -# Agent classes for easy import -TalkHierarchicalGenerator = HierarchicalStructuredCommunicationGenerator -TalkHierarchicalEvaluator = HierarchicalStructuredCommunicationEvaluator -TalkHierarchicalRefiner = HierarchicalStructuredCommunicationRefiner -TalkHierarchicalSupervisor = HierarchicalStructuredCommunicationSupervisor - -# Schema classes -TalkHierarchicalSchemas = { - "StructuredMessage": StructuredMessageSchema, - "EvaluationResult": EvaluationResultSchema, - "GeneratorResponse": GeneratorResponseSchema, - "EvaluatorResponse": EvaluatorResponseSchema, - "RefinerResponse": RefinerResponseSchema, -} - # Export all components __all__ = [ # Main framework @@ -1692,12 +1677,6 @@ __all__ = [ "HierarchicalStructuredCommunicationRefiner", "HierarchicalStructuredCommunicationSupervisor", - # Convenience aliases - "TalkHierarchicalGenerator", - "TalkHierarchicalEvaluator", - "TalkHierarchicalRefiner", - "TalkHierarchicalSupervisor", - # Data models "StructuredMessage", "HierarchicalOrder", @@ -1713,7 +1692,4 @@ __all__ = [ # Enums "CommunicationType", "AgentRole", - - # Schema collection - "TalkHierarchicalSchemas", ] From ed63cef311b9f5caf58d05a7a7404d44ea928c88 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Tue, 19 Aug 2025 14:27:38 +0300 Subject: [PATCH 23/28] Update and rename hierarchical_structured_communication_swarm.md to hierarchical_structured_communication_framework.md --- ...ical_structured_communication_framework.md | 177 ++++++++ ...archical_structured_communication_swarm.md | 380 ------------------ 2 files changed, 177 insertions(+), 380 deletions(-) create mode 100644 docs/swarms/structs/hierarchical_structured_communication_framework.md delete mode 100644 docs/swarms/structs/hierarchical_structured_communication_swarm.md diff --git a/docs/swarms/structs/hierarchical_structured_communication_framework.md b/docs/swarms/structs/hierarchical_structured_communication_framework.md new file mode 100644 index 00000000..b848478f --- /dev/null +++ b/docs/swarms/structs/hierarchical_structured_communication_framework.md @@ -0,0 +1,177 @@ +# Hierarchical Structured Communication Framework + +The Hierarchical Structured Communication Framework implements the "Talk Structurally, Act Hierarchically" approach for LLM multi-agent systems, based on the research paper arXiv:2502.11098. + +## Overview + +This framework provides: +- **Structured Communication Protocol** with Message (M_ij), Background (B_ij), and Intermediate Output (I_ij) +- **Hierarchical Evaluation System** with supervisor coordination +- **Specialized Agent Classes** for different roles +- **Main Swarm Orchestrator** for workflow management + +## Key Components + +### Agent Classes +- `HierarchicalStructuredCommunicationGenerator` - Creates initial content +- `HierarchicalStructuredCommunicationEvaluator` - Evaluates content quality +- `HierarchicalStructuredCommunicationRefiner` - Improves content based on feedback +- `HierarchicalStructuredCommunicationSupervisor` - Coordinates workflow + +### Main Framework +- `HierarchicalStructuredCommunicationFramework` - Main orchestrator class +- `HierarchicalStructuredCommunicationSwarm` - Convenience alias + +## Quick Start + +```python +from swarms.structs.hierarchical_structured_communication_framework import ( + HierarchicalStructuredCommunicationFramework, + HierarchicalStructuredCommunicationGenerator, + HierarchicalStructuredCommunicationEvaluator, + HierarchicalStructuredCommunicationRefiner, + HierarchicalStructuredCommunicationSupervisor +) + +# Create specialized agents +generator = HierarchicalStructuredCommunicationGenerator( + agent_name="ContentGenerator" +) + +evaluator = HierarchicalStructuredCommunicationEvaluator( + agent_name="QualityEvaluator" +) + +refiner = HierarchicalStructuredCommunicationRefiner( + agent_name="ContentRefiner" +) + +supervisor = HierarchicalStructuredCommunicationSupervisor( + agent_name="WorkflowSupervisor" +) + +# Create the framework +framework = HierarchicalStructuredCommunicationFramework( + name="MyFramework", + supervisor=supervisor, + generators=[generator], + evaluators=[evaluator], + refiners=[refiner], + max_loops=3 +) + +# Run the workflow +result = framework.run("Create a comprehensive analysis of AI trends in 2024") +``` + +## Basic Usage + +```python +from swarms.structs.hierarchical_structured_communication_framework import ( + HierarchicalStructuredCommunicationFramework, + HierarchicalStructuredCommunicationGenerator, + HierarchicalStructuredCommunicationEvaluator, + HierarchicalStructuredCommunicationRefiner +) + +# Create agents with custom names +generator = HierarchicalStructuredCommunicationGenerator(agent_name="ContentGenerator") +evaluator = HierarchicalStructuredCommunicationEvaluator(agent_name="QualityEvaluator") +refiner = HierarchicalStructuredCommunicationRefiner(agent_name="ContentRefiner") + +# Create framework with default supervisor +framework = HierarchicalStructuredCommunicationFramework( + generators=[generator], + evaluators=[evaluator], + refiners=[refiner], + max_loops=3, + verbose=True +) + +# Execute task +result = framework.run("Write a detailed report on renewable energy technologies") +print(result["final_result"]) +``` + +## Advanced Configuration + +```python +from swarms.structs.hierarchical_structured_communication_framework import ( + HierarchicalStructuredCommunicationFramework +) + +# Create framework with custom configuration +framework = HierarchicalStructuredCommunicationFramework( + name="AdvancedFramework", + max_loops=5, + enable_structured_communication=True, + enable_hierarchical_evaluation=True, + shared_memory=True, + model_name="gpt-4o-mini", + verbose=True +) + +# Run with custom parameters +result = framework.run( + "Analyze the impact of climate change on global agriculture", + max_loops=3 +) +``` + +## Integration with Other Swarms + +```python +from swarms.structs.hierarchical_structured_communication_framework import ( + HierarchicalStructuredCommunicationFramework +) +from swarms.structs import AutoSwarmBuilder + +# Use HierarchicalStructuredCommunicationFramework for content generation +framework = HierarchicalStructuredCommunicationFramework( + max_loops=2, + verbose=True +) + +# Integrate with AutoSwarmBuilder +builder = AutoSwarmBuilder() +swarm = builder.create_swarm( + swarm_type="HierarchicalStructuredCommunicationFramework", + task="Generate a comprehensive business plan" +) +``` + +## API Reference + +### HierarchicalStructuredCommunicationFramework + +The main orchestrator class that implements the complete framework. + +#### Parameters +- `name` (str): Name of the framework +- `supervisor`: Main supervisor agent +- `generators` (List): List of generator agents +- `evaluators` (List): List of evaluator agents +- `refiners` (List): List of refiner agents +- `max_loops` (int): Maximum refinement loops +- `enable_structured_communication` (bool): Enable structured protocol +- `enable_hierarchical_evaluation` (bool): Enable hierarchical evaluation +- `verbose` (bool): Enable verbose logging + +#### Methods +- `run(task)`: Execute complete workflow +- `step(task)`: Execute single workflow step +- `send_structured_message()`: Send structured communication +- `run_hierarchical_evaluation()`: Run evaluation system + +## Contributing + +Contributions to improve the Hierarchical Structured Communication Framework are welcome! Please: + +1. Follow the existing code style and patterns +2. Add comprehensive tests for new features +3. Update documentation for any API changes +4. Ensure all imports use the correct module paths + +## License + +This framework is part of the Swarms project and follows the same licensing terms. diff --git a/docs/swarms/structs/hierarchical_structured_communication_swarm.md b/docs/swarms/structs/hierarchical_structured_communication_swarm.md deleted file mode 100644 index 0e71d7f9..00000000 --- a/docs/swarms/structs/hierarchical_structured_communication_swarm.md +++ /dev/null @@ -1,380 +0,0 @@ -# Talk Structurally, Act Hierarchically Framework - -## Overview - -The **Talk Structurally, Act Hierarchically** framework is a sophisticated multi-agent system that implements the research paper "Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems" (arXiv:2502.11098). This framework addresses key challenges in multi-agent systems through structured communication protocols and hierarchical evaluation systems. - -## Key Features - -### 1. Structured Communication Protocol -- **Message (M_ij)**: Specific task instructions with clear objectives -- **Background (B_ij)**: Context and problem background for comprehensive understanding -- **Intermediate Output (I_ij)**: Intermediate results passed between agents - -### 2. Hierarchical Refinement System -- **Evaluation Team**: Multiple specialized evaluators with different criteria -- **Supervisor Coordination**: Centralized coordination of evaluation processes -- **Summarized Feedback**: Consolidated, actionable feedback from multiple evaluators - -### 3. Graph-based Agent Orchestration -- **Dynamic Routing**: Flexible communication pathways based on task requirements -- **Context Preservation**: Maintains conversation history and shared memory -- **Iterative Refinement**: Multiple refinement loops for continuous improvement - -## Architecture - -```mermaid -graph TD - A[User Task] --> B[Supervisor Agent] - B --> C[Generator Agent] - C --> D[Evaluation Team Supervisor] - D --> E[Evaluator 1] - D --> F[Evaluator 2] - D --> G[Evaluator N] - E --> H[Summarized Feedback] - F --> H - G --> H - H --> I[Refiner Agent] - I --> J{Quality Threshold Met?} - J -->|No| C - J -->|Yes| K[Final Result] -``` - -## Components - -### TalkHierarchicalSwarm - -The main orchestrator class that manages the entire workflow. - -```python -from swarms.structs.talk_hierarchical_swarm import TalkHierarchicalSwarm - -swarm = TalkHierarchicalSwarm( - name="MyTalkHierSwarm", - supervisor=supervisor_agent, - generators=[generator_agent], - evaluators=[evaluator_agent1, evaluator_agent2], - refiners=[refiner_agent], - max_loops=3, - enable_structured_communication=True, - enable_hierarchical_evaluation=True -) -``` - -### Specialized Agents - -#### TalkHierarchicalGenerator -Creates initial content using structured communication protocol. - -```python -from swarms.agents.talk_hierarchical_agents import TalkHierarchicalGenerator - -generator = TalkHierarchicalGenerator( - agent_name="ContentGenerator", - model_name="gpt-4o-mini" -) - -# Generate with structured communication -result = generator.generate_with_structure( - message="Create technical documentation", - background="For software developers", - intermediate_output="Previous API overview" -) -``` - -#### TalkHierarchicalEvaluator -Evaluates content using specific criteria and provides structured feedback. - -```python -from swarms.agents.talk_hierarchical_agents import TalkHierarchicalEvaluator - -evaluator = TalkHierarchicalEvaluator( - agent_name="QualityEvaluator", - evaluation_criteria=["accuracy", "clarity", "completeness"] -) - -# Evaluate content -result = evaluator.evaluate_with_criterion( - content="Content to evaluate", - criterion="accuracy" -) -``` - -#### TalkHierarchicalRefiner -Improves content based on evaluation feedback. - -```python -from swarms.agents.talk_hierarchical_agents import TalkHierarchicalRefiner - -refiner = TalkHierarchicalRefiner( - agent_name="ContentRefiner" -) - -# Refine content -result = refiner.refine_with_feedback( - original_content="Original content", - evaluation_results=evaluation_results -) -``` - -#### TalkHierarchicalSupervisor -Coordinates workflow and manages structured communication. - -```python -from swarms.agents.talk_hierarchical_agents import TalkHierarchicalSupervisor - -supervisor = TalkHierarchicalSupervisor( - agent_name="WorkflowSupervisor" -) - -# Coordinate workflow -decision = supervisor.coordinate_workflow( - task="Current task", - current_state=workflow_state -) -``` - -## Usage Examples - -### Basic Usage - -```python -from swarms.structs.talk_hierarchical_swarm import TalkHierarchicalSwarm - -# Create the swarm -swarm = TalkHierarchicalSwarm( - name="DocumentationSwarm", - max_loops=3, - verbose=True -) - -# Run a task -result = swarm.run( - "Create comprehensive API documentation for a Python library" -) - -print(f"Final Result: {result['final_result']}") -print(f"Total Loops: {result['total_loops']}") -``` - -### Advanced Configuration - -```python -from swarms.agents.talk_hierarchical_agents import ( - TalkHierarchicalGenerator, - TalkHierarchicalEvaluator, - TalkHierarchicalRefiner, - TalkHierarchicalSupervisor -) - -# Create specialized agents -generator = TalkHierarchicalGenerator( - agent_name="TechWriter", - model_name="gpt-4o-mini" -) - -evaluator1 = TalkHierarchicalEvaluator( - agent_name="AccuracyChecker", - evaluation_criteria=["accuracy", "technical_correctness"] -) - -evaluator2 = TalkHierarchicalEvaluator( - agent_name="ClarityChecker", - evaluation_criteria=["clarity", "readability"] -) - -refiner = TalkHierarchicalRefiner( - agent_name="ContentImprover" -) - -supervisor = TalkHierarchicalSupervisor( - agent_name="ProjectManager" -) - -# Create swarm with custom agents -swarm = TalkHierarchicalSwarm( - name="CustomSwarm", - supervisor=supervisor, - generators=[generator], - evaluators=[evaluator1, evaluator2], - refiners=[refiner], - max_loops=5, - quality_threshold=8.5 -) -``` - -### Structured Communication Example - -```python -# Send structured message -structured_msg = swarm.send_structured_message( - sender="Supervisor", - recipient="Generator", - message="Create a technical blog post about machine learning", - background="Target audience: software engineers with basic ML knowledge", - intermediate_output="Previous discussion covered AI fundamentals" -) - -print(f"Message: {structured_msg.message}") -print(f"Background: {structured_msg.background}") -print(f"Intermediate Output: {structured_msg.intermediate_output}") -``` - -### Hierarchical Evaluation Example - -```python -# Run hierarchical evaluation -evaluation_results = swarm.run_hierarchical_evaluation( - content="Content to evaluate", - evaluation_criteria=["accuracy", "completeness", "clarity", "relevance"] -) - -for result in evaluation_results: - print(f"Evaluator: {result.evaluator_name}") - print(f"Criterion: {result.criterion}") - print(f"Score: {result.score}/10") - print(f"Feedback: {result.feedback}") -``` - -## Configuration Options - -### TalkHierarchicalSwarm Parameters - -| Parameter | Type | Default | Description | -|-----------|------|---------|-------------| -| `name` | str | "TalkHierarchicalSwarm" | Name of the swarm | -| `description` | str | "Talk Structurally, Act Hierarchically Framework" | Description | -| `supervisor` | Agent | None | Main supervisor agent | -| `generators` | List[Agent] | [] | List of generator agents | -| `evaluators` | List[Agent] | [] | List of evaluator agents | -| `refiners` | List[Agent] | [] | List of refiner agents | -| `evaluation_supervisor` | Agent | None | Evaluation team supervisor | -| `max_loops` | int | 3 | Maximum refinement loops | -| `output_type` | OutputType | "dict-all-except-first" | Output format | -| `supervisor_name` | str | "Supervisor" | Supervisor agent name | -| `evaluation_supervisor_name` | str | "EvaluationSupervisor" | Evaluation supervisor name | -| `verbose` | bool | False | Enable verbose logging | -| `enable_structured_communication` | bool | True | Enable structured communication | -| `enable_hierarchical_evaluation` | bool | True | Enable hierarchical evaluation | -| `shared_memory` | bool | True | Enable shared memory | - -### Evaluation Criteria - -Common evaluation criteria include: - -- **Accuracy**: Factual correctness and precision -- **Completeness**: Coverage of required topics -- **Clarity**: Readability and understandability -- **Relevance**: Appropriateness to the task -- **Coherence**: Logical flow and organization -- **Technical Correctness**: Proper technical details -- **Engagement**: Interest and appeal to audience - -## Best Practices - -### 1. Agent Configuration -- Use specialized agents for specific roles -- Configure evaluation criteria based on task requirements -- Set appropriate quality thresholds for your use case - -### 2. Communication Structure -- Always provide clear, specific messages (M_ij) -- Include relevant background context (B_ij) -- Pass meaningful intermediate outputs (I_ij) - -### 3. Evaluation Setup -- Use multiple evaluators with different criteria -- Ensure evaluation criteria are well-defined -- Set appropriate confidence thresholds - -### 4. Workflow Management -- Monitor conversation history for debugging -- Adjust max_loops based on task complexity -- Use quality thresholds to prevent unnecessary iterations - -## Performance Considerations - -### Optimization Tips -- Use appropriate model sizes for different agent roles -- Implement caching for repeated evaluations -- Monitor API usage and costs -- Use parallel evaluation when possible - -### Quality vs. Speed Trade-offs -- Higher quality thresholds require more iterations -- More evaluators provide better feedback but increase latency -- Structured communication adds overhead but improves results - -## Error Handling - -The framework includes comprehensive error handling: - -```python -try: - result = swarm.run(task) -except Exception as e: - print(f"Error in TalkHierarchical workflow: {e}") - # Handle error appropriately -``` - -## Integration with Other Swarms - -The TalkHierarchical framework can be integrated with other Swarms components: - -```python -from swarms.structs.talk_hierarchical_swarm import TalkHierarchicalSwarm -from swarms.structs.hiearchical_swarm import HierarchicalSwarm - -# Use TalkHierarchical for content generation -talk_hier = TalkHierarchicalSwarm() - -# Use HierarchicalSwarm for task orchestration -hierarchical = HierarchicalSwarm( - director=talk_hier.supervisor, - agents=[talk_hier.generators, talk_hier.evaluators, talk_hier.refiners] -) -``` - -## Research Background - -This implementation is based on the research paper: -- **Title**: "Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems" -- **Authors**: Zhao Wang, Moriyama Sota, Wei-Yao Wang, Briti Gangopadhyay, Shingo Takamatsu -- **arXiv**: 2502.11098 -- **Year**: 2025 - -The framework addresses key challenges in multi-agent systems: -- Context-poor communication leading to misunderstandings -- Sequential evaluation causing bias and incomplete feedback -- Lack of structured coordination between agents - -## Citation - -If you use this framework in your research, please cite: - -```bibtex -@misc{wang2025talkhier, - title={Talk Structurally, Act Hierarchically: A Collaborative Framework for LLM Multi-Agent Systems}, - author={Zhao Wang and Sota Moriyama and Wei-Yao Wang and Briti Gangopadhyay and Shingo Takamatsu}, - year={2025}, - eprint={2502.11098}, - archivePrefix={arXiv}, - primaryClass={cs.AI} -} -``` - -## Contributing - -Contributions to improve the TalkHierarchical framework are welcome! Please: - -1. Follow the existing code style and patterns -2. Add comprehensive tests for new features -3. Update documentation for any changes -4. Ensure backward compatibility when possible - -## Support - -For questions and support: -- Check the examples in `examples/multi_agent/talk_hierarchical_example.py` -- Review the source code in `swarms/structs/talk_hierarchical_swarm.py` -- Examine the specialized agents in `swarms/agents/talk_hierarchical_agents.py` \ No newline at end of file From 3b1acdf46c3143393410748ca78fc01c2b9a3a00 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Tue, 19 Aug 2025 14:29:26 +0300 Subject: [PATCH 24/28] Update mkdocs.yml --- docs/mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 5a687cca..05c1b913 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -290,6 +290,7 @@ nav: - Hiearchical Architectures: - Overview: "swarms/structs/multi_swarm_orchestration.md" - HierarchicalSwarm: "swarms/structs/hierarchical_swarm.md" + - Hierarchical Structured Communication Framework: "swarms/structs/hierarchical_structured_communication_framework.md" - Auto Agent Builder: "swarms/structs/auto_agent_builder.md" - Hybrid Hierarchical-Cluster Swarm: "swarms/structs/hhcs.md" - Auto Swarm Builder: "swarms/structs/auto_swarm_builder.md" From 23fa78d910f665f9cdc95953206f32cda433f4cb Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Tue, 19 Aug 2025 14:32:25 +0300 Subject: [PATCH 25/28] Update BoardOfDirectors.md --- docs/swarms/structs/BoardOfDirectors.md | 42 ++++++++++++------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/swarms/structs/BoardOfDirectors.md b/docs/swarms/structs/BoardOfDirectors.md index 1b1664a9..be0205ec 100644 --- a/docs/swarms/structs/BoardOfDirectors.md +++ b/docs/swarms/structs/BoardOfDirectors.md @@ -2,7 +2,7 @@ The Board of Directors is a sophisticated multi-agent architecture that implements collective decision-making through democratic processes, voting mechanisms, and role-based leadership. This architecture provides an alternative to single-director patterns by enabling collaborative intelligence through structured governance. -## 🏛️ Overview +## Overview The Board of Directors architecture follows a democratic workflow pattern: @@ -14,7 +14,7 @@ The Board of Directors architecture follows a democratic workflow pattern: 6. **Feedback Loop**: Board evaluates results and issues new orders if needed (up to `max_loops`) 7. **Context Preservation**: All conversation history and context is maintained throughout the process -## 🏗️ Architecture Components +## Architecture Components ### Core Components @@ -73,7 +73,7 @@ sequenceDiagram Chairman->>User: Deliver Results ``` -## 👥 Board Member Roles +## Board Member Roles The Board of Directors supports various roles with different responsibilities and voting weights: @@ -138,7 +138,7 @@ class BoardRoleHierarchy: } ``` -## 🚀 Quick Start +## Quick Start ### Basic Setup @@ -206,7 +206,7 @@ result = board_swarm.run(task="Analyze the market potential for Tesla (TSLA) sto print(result) ``` -## 📋 Comprehensive Examples +## Comprehensive Examples ### 1. Strategic Investment Analysis @@ -448,7 +448,7 @@ print("Crisis Management Results:") print(json.dumps(result, indent=2)) ``` -## ⚙️ Configuration and Parameters +## Configuration and Parameters ### BoardOfDirectorsSwarm Parameters @@ -551,7 +551,7 @@ quality_config = { } ``` -## 📊 Performance Monitoring and Analytics +## Performance Monitoring and Analytics ### Board Performance Metrics @@ -656,7 +656,7 @@ print("Performance Report:") print(json.dumps(report, indent=2)) ``` -## 🔧 Advanced Features and Customization +## Advanced Features and Customization ### Custom Board Templates @@ -729,7 +729,7 @@ board_swarm = BoardOfDirectorsSwarm( ) ``` -## 🛠️ Troubleshooting and Debugging +## Troubleshooting and Debugging ### Common Issues and Solutions @@ -821,7 +821,7 @@ logging_swarm = BoardOfDirectorsSwarm( ) ``` -## 📋 Use Cases +## Use Cases ### Corporate Governance - **Strategic Planning**: Long-term business strategy development @@ -853,20 +853,20 @@ logging_swarm = BoardOfDirectorsSwarm( - **Recovery Planning**: Developing recovery and prevention strategies - **Legal Compliance**: Ensuring compliance during crisis situations -## 🎯 Success Criteria +## Success Criteria A successful Board of Directors implementation should demonstrate: -- ✅ **Democratic Decision Making**: All board members contribute to decisions -- ✅ **Consensus Achievement**: Decisions reached through collaborative processes -- ✅ **Role Effectiveness**: Each board member fulfills their responsibilities -- ✅ **Agent Coordination**: Worker agents execute tasks efficiently -- ✅ **Quality Output**: High-quality results through collective intelligence -- ✅ **Process Transparency**: Clear visibility into decision-making processes -- ✅ **Performance Optimization**: Efficient resource utilization and execution -- ✅ **Continuous Improvement**: Learning from each execution cycle +- **Democratic Decision Making**: All board members contribute to decisions +- **Consensus Achievement**: Decisions reached through collaborative processes +- **Role Effectiveness**: Each board member fulfills their responsibilities +- **Agent Coordination**: Worker agents execute tasks efficiently +- **Quality Output**: High-quality results through collective intelligence +- **Process Transparency**: Clear visibility into decision-making processes +- **Performance Optimization**: Efficient resource utilization and execution +- **Continuous Improvement**: Learning from each execution cycle -## 📚 Best Practices +## Best Practices ### 1. Role Definition - Clearly define responsibilities for each board member @@ -900,4 +900,4 @@ A successful Board of Directors implementation should demonstrate: --- -The Board of Directors architecture represents a sophisticated approach to multi-agent collaboration, enabling organizations to leverage collective intelligence through structured governance and democratic decision-making processes. This comprehensive implementation provides the tools and frameworks needed to build effective, scalable, and intelligent decision-making systems. \ No newline at end of file +The Board of Directors architecture represents a sophisticated approach to multi-agent collaboration, enabling organizations to leverage collective intelligence through structured governance and democratic decision-making processes. This comprehensive implementation provides the tools and frameworks needed to build effective, scalable, and intelligent decision-making systems. From 100542527ea4b2e076eda00de62ea3fba3235024 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Tue, 19 Aug 2025 21:02:35 +0300 Subject: [PATCH 26/28] moved exports --- ...ical_structured_communication_framework.py | 37 +------------------ 1 file changed, 1 insertion(+), 36 deletions(-) diff --git a/swarms/structs/hierarchical_structured_communication_framework.py b/swarms/structs/hierarchical_structured_communication_framework.py index 377dde90..41b4b663 100644 --- a/swarms/structs/hierarchical_structured_communication_framework.py +++ b/swarms/structs/hierarchical_structured_communication_framework.py @@ -1657,39 +1657,4 @@ Please refine the content to address the feedback while maintaining its core str def __repr__(self): return self.__str__() - -# ============================================================================= -# CONVENIENCE ALIASES AND EXPORTS -# ============================================================================= - -# Main framework class -HierarchicalStructuredCommunicationSwarm = HierarchicalStructuredCommunicationFramework - -# Export all components -__all__ = [ - # Main framework - "HierarchicalStructuredCommunicationFramework", - "HierarchicalStructuredCommunicationSwarm", - - # Agent classes - "HierarchicalStructuredCommunicationGenerator", - "HierarchicalStructuredCommunicationEvaluator", - "HierarchicalStructuredCommunicationRefiner", - "HierarchicalStructuredCommunicationSupervisor", - - # Data models - "StructuredMessage", - "HierarchicalOrder", - "EvaluationResult", - - # Schemas - "StructuredMessageSchema", - "EvaluationResultSchema", - "GeneratorResponseSchema", - "EvaluatorResponseSchema", - "RefinerResponseSchema", - - # Enums - "CommunicationType", - "AgentRole", -] +# Nothing to see here yet. From 7472774d39b411d385c1554474ea915d533998ed Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Tue, 19 Aug 2025 21:07:02 +0300 Subject: [PATCH 27/28] Update __init__.py --- swarms/structs/__init__.py | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/swarms/structs/__init__.py b/swarms/structs/__init__.py index 08d4e889..98402831 100644 --- a/swarms/structs/__init__.py +++ b/swarms/structs/__init__.py @@ -108,9 +108,26 @@ from swarms.structs.swarming_architectures import ( star_swarm, ) from swarms.structs.hierarchical_structured_communication_framework import ( - HierarchicalStructuredCommunicationFramework as HierarchicalStructuredCommSwarm, + HierarchicalStructuredCommunicationFramework, + HierarchicalStructuredCommunicationGenerator, + HierarchicalStructuredCommunicationEvaluator, + HierarchicalStructuredCommunicationRefiner, + HierarchicalStructuredCommunicationSupervisor, + StructuredMessage, + HierarchicalOrder, + EvaluationResult, + StructuredMessageSchema, + EvaluationResultSchema, + GeneratorResponseSchema, + EvaluatorResponseSchema, + RefinerResponseSchema, + CommunicationType, + AgentRole, ) +# Convenience alias(fixes old code if any was left out in the wild) +HierarchicalStructuredCommunicationSwarm = HierarchicalStructuredCommunicationFramework + __all__ = [ "Agent", "BaseStructure", @@ -189,7 +206,21 @@ __all__ = [ "HierarchicalSwarm", "HeavySwarm", "CronJob", - "HierarchicalStructuredCommSwarm", + "HierarchicalStructuredCommunicationSwarm", + "HierarchicalStructuredCommunicationGenerator", + "HierarchicalStructuredCommunicationEvaluator", + "HierarchicalStructuredCommunicationRefiner", + "HierarchicalStructuredCommunicationSupervisor", + "StructuredMessage", + "HierarchicalOrder", + "EvaluationResult", + "StructuredMessageSchema", + "EvaluationResultSchema", + "GeneratorResponseSchema", + "EvaluatorResponseSchema", + "RefinerResponseSchema", + "CommunicationType", + "AgentRole", # Stopping conditions "check_done", "check_finished", From 7037f7e4783dde4de574d945891c35cdf3165b69 Mon Sep 17 00:00:00 2001 From: CI-DEV <154627941+IlumCI@users.noreply.github.com> Date: Wed, 20 Aug 2025 20:24:12 +0300 Subject: [PATCH 28/28] Update __init__.py --- swarms/structs/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/swarms/structs/__init__.py b/swarms/structs/__init__.py index 98402831..04a83dd8 100644 --- a/swarms/structs/__init__.py +++ b/swarms/structs/__init__.py @@ -9,7 +9,7 @@ from swarms.structs.board_of_directors_swarm import ( ) from swarms.structs.concurrent_workflow import ConcurrentWorkflow from swarms.structs.conversation import Conversation -from swarms.structs.council_judge import CouncilAsAJudge +from swarms.structs.council_as_judge import CouncilAsAJudge from swarms.structs.cron_job import CronJob from swarms.structs.de_hallucination_swarm import DeHallucinationSwarm from swarms.structs.deep_research_swarm import DeepResearchSwarm