swarms 7.7.8__py3-none-any.whl → 7.7.9__py3-none-any.whl

swarms/structs/council_judge.py

@@ -0,0 +1,456 @@
+from typing import Dict, Tuple
+from functools import lru_cache
+import multiprocessing
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from swarms.structs.agent import Agent
+from swarms.structs.conversation import Conversation
+from loguru import logger
+
+
+class EvaluationError(Exception):
+    """Base exception for evaluation-related errors."""
+
+    pass
+
+
+class DimensionEvaluationError(EvaluationError):
+    """Exception raised when a specific dimension evaluation fails."""
+
+    pass
+
+
+class AggregationError(EvaluationError):
+    """Exception raised when aggregation of evaluations fails."""
+
+    pass
+
+
+# Define evaluation dimensions and their evaluation goals
+EVAL_DIMENSIONS: Dict[str, str] = {
+    "accuracy": """Evaluate the factual correctness of the model's response with high precision:
+1. Verify all claims against authoritative sources
+2. Check for outdated information or temporal inconsistencies
+3. Identify any technical inaccuracies or misrepresentations
+4. Flag unsupported assertions or speculative statements
+5. Note any contradictions within the response itself
+6. Assess the reliability of cited sources or references""",
+    "helpfulness": """Assess the practical utility and problem-solving effectiveness:
+1. Evaluate if the response directly addresses the user's core question
+2. Check if the solution is actionable and implementable
+3. Assess whether the response provides necessary context and prerequisites
+4. Verify if the response anticipates and addresses potential follow-up questions
+5. Evaluate if the response includes relevant examples or analogies
+6. Check if the response provides appropriate warnings or limitations""",
+    "harmlessness": """Evaluate the safety and ethical considerations:
+1. Check for any harmful stereotypes or biases
+2. Identify potential misuse or dangerous applications
+3. Assess if the response promotes unsafe practices
+4. Evaluate the appropriateness of the content for different audiences
+5. Check for any offensive language or insensitive content
+6. Assess if the response includes appropriate disclaimers""",
+    "coherence": """Analyze the structural and logical quality:
+1. Evaluate the organization and flow of information
+2. Check for clear topic sentences and transitions
+3. Assess the consistency of terminology and definitions
+4. Verify logical progression of ideas
+5. Check for clear paragraph structure
+6. Evaluate the use of examples and supporting evidence""",
+    "conciseness": """Assess the efficiency and precision of communication:
+1. Identify redundant or repetitive information
+2. Check for unnecessary qualifiers or hedges
+3. Evaluate if the response could be more direct
+4. Assess the balance between detail and brevity
+5. Check for filler content or unnecessary context
+6. Evaluate if the response stays focused on key points""",
+    "instruction_adherence": """Evaluate alignment with user requirements:
+1. Check if all aspects of the prompt are addressed
+2. Verify if the response stays within specified constraints
+3. Assess if the format matches requested output type
+4. Check if the response maintains appropriate scope
+5. Verify if the response follows any specific guidelines
+6. Assess if the response meets implicit expectations""",
+}
+
+
+@lru_cache(maxsize=128)
+def judge_system_prompt() -> str:
+    """
+    Returns the system prompt for judge agents.
+    Cached to avoid repeated string creation.
+
+    Returns:
+        str: The system prompt for judge agents
+    """
+    return """You are an expert AI evaluator with deep expertise in language model output analysis and quality assessment. Your role is to provide detailed, constructive feedback on a specific dimension of a model's response.
+
+Key Responsibilities:
+1. Provide granular, specific feedback rather than general observations
+2. Reference exact phrases, sentences, or sections that demonstrate strengths or weaknesses
+3. Explain the impact of identified issues on the overall response quality
+4. Suggest specific improvements with concrete examples
+5. Maintain a professional, constructive tone throughout
+6. Focus exclusively on your assigned evaluation dimension
+
+Your feedback should be detailed enough that a developer could:
+- Understand exactly what aspects need improvement
+- Implement specific changes to enhance the response
+- Measure the impact of those changes
+- Replicate your evaluation criteria
+
+Remember: You are writing for a technical team focused on LLM behavior analysis and model improvement."""
+
+
+@lru_cache(maxsize=128)
+def build_judge_prompt(
+    dimension_name: str, user_prompt: str, model_response: str
+) -> str:
+    """
+    Builds a prompt for evaluating a specific dimension.
+    Cached to avoid repeated string creation for same inputs.
+
+    Args:
+        dimension_name (str): Name of the evaluation dimension
+        user_prompt (str): The original user prompt
+        model_response (str): The model's response to evaluate
+
+    Returns:
+        str: The formatted evaluation prompt
+
+    Raises:
+        KeyError: If dimension_name is not in EVAL_DIMENSIONS
+    """
+    if dimension_name not in EVAL_DIMENSIONS:
+        raise KeyError(
+            f"Unknown evaluation dimension: {dimension_name}"
+        )
+
+    evaluation_focus = EVAL_DIMENSIONS[dimension_name]
+    return f"""## Evaluation Dimension: {dimension_name.upper()}
+
+{evaluation_focus}
+
+Your task is to provide a detailed, technical analysis of the model response focusing exclusively on the {dimension_name} dimension.
+
+Guidelines:
+1. Be specific and reference exact parts of the response
+2. Explain the reasoning behind your observations
+3. Provide concrete examples of both strengths and weaknesses
+4. Suggest specific improvements where applicable
+5. Maintain a technical, analytical tone
+
+--- BEGIN USER PROMPT ---
+{user_prompt}
+--- END USER PROMPT ---
+
+--- BEGIN MODEL RESPONSE ---
+{model_response}
+--- END MODEL RESPONSE ---
+
+### Technical Analysis ({dimension_name.upper()} Dimension):
+Provide a comprehensive analysis that would be valuable for model improvement."""
+
+
+@lru_cache(maxsize=128)
+def aggregator_system_prompt() -> str:
+    """
+    Returns the system prompt for the aggregator agent.
+    Cached to avoid repeated string creation.
+
+    Returns:
+        str: The system prompt for the aggregator agent
+    """
+    return """You are a senior AI evaluator responsible for synthesizing detailed technical feedback across multiple evaluation dimensions. Your role is to create a comprehensive analysis report that helps the development team understand and improve the model's performance.
+
+Key Responsibilities:
+1. Identify patterns and correlations across different dimensions
+2. Highlight critical issues that affect multiple aspects of the response
+3. Prioritize feedback based on impact and severity
+4. Provide actionable recommendations for improvement
+5. Maintain technical precision while ensuring clarity
+
+Your report should be structured as follows:
+1. Executive Summary
+   - Key strengths and weaknesses
+   - Critical issues requiring immediate attention
+   - Overall assessment
+
+2. Detailed Analysis
+   - Cross-dimensional patterns
+   - Specific examples and their implications
+   - Technical impact assessment
+
+3. Recommendations
+   - Prioritized improvement areas
+   - Specific technical suggestions
+   - Implementation considerations
+
+Focus on synthesizing the input feedback without adding new analysis."""
+
+
+def build_aggregation_prompt(rationales: Dict[str, str]) -> str:
+    """
+    Builds the prompt for aggregating evaluation results.
+
+    Args:
+        rationales (Dict[str, str]): Dictionary mapping dimension names to their evaluation results
+
+    Returns:
+        str: The formatted aggregation prompt
+    """
+    aggregation_input = "### MULTI-DIMENSION TECHNICAL ANALYSIS:\n"
+    for dim, text in rationales.items():
+        aggregation_input += (
+            f"\n--- {dim.upper()} ANALYSIS ---\n{text.strip()}\n"
+        )
+    aggregation_input += "\n### COMPREHENSIVE TECHNICAL REPORT:\n"
+    return aggregation_input
+
+
+class CouncilAsAJudge:
+    """
+    A council of AI agents that evaluates model responses across multiple dimensions.
+
+    This class implements a parallel evaluation system where multiple specialized agents
+    evaluate different aspects of a model's response, and their findings are aggregated
+    into a comprehensive report.
+
+    Attributes:
+        id (str): Unique identifier for the council
+        name (str): Display name of the council
+        description (str): Description of the council's purpose
+        model_name (str): Name of the model to use for evaluations
+        output_type (str): Type of output to return
+        judge_agents (Dict[str, Agent]): Dictionary of dimension-specific judge agents
+        aggregator_agent (Agent): Agent responsible for aggregating evaluations
+        conversation (Conversation): Conversation history tracker
+        max_workers (int): Maximum number of worker threads for parallel execution
+    """
+
+    def __init__(
+        self,
+        id: str = "CouncilAsAJudge",
+        name: str = "CouncilAsAJudge",
+        description: str = "Evaluates the model's response across multiple dimensions",
+        model_name: str = "gpt-4o-mini",
+        output_type: str = "string",
+        cache_size: int = 128,
+    ):
+        """
+        Initialize the CouncilAsAJudge.
+
+        Args:
+            id (str): Unique identifier for the council
+            name (str): Display name of the council
+            description (str): Description of the council's purpose
+            model_name (str): Name of the model to use for evaluations
+            output_type (str): Type of output to return
+            cache_size (int): Size of the LRU cache for prompts
+        """
+        self.id = id
+        self.name = name
+        self.description = description
+        self.model_name = model_name
+        self.output_type = output_type
+        self.judge_agents = self._create_judges()
+        self.aggregator_agent = self._create_aggregator()
+        self.conversation = Conversation()
+
+        # Calculate optimal number of workers (75% of available CPU cores)
+        total_cores = multiprocessing.cpu_count()
+        self.max_workers = max(1, int(total_cores * 0.75))
+        logger.info(
+            f"Using {self.max_workers} worker threads out of {total_cores} CPU cores"
+        )
+
+        # Configure caching
+        self._configure_caching(cache_size)
+
+    def _configure_caching(self, cache_size: int) -> None:
+        """
+        Configure caching for frequently used functions.
+
+        Args:
+            cache_size (int): Size of the LRU cache
+        """
+        # Update cache sizes for cached functions
+        judge_system_prompt.cache_info = (
+            lambda: None
+        )  # Reset cache info
+        build_judge_prompt.cache_info = lambda: None
+        aggregator_system_prompt.cache_info = lambda: None
+
+        # Set new cache sizes
+        judge_system_prompt.__wrapped__.__wrapped__ = lru_cache(
+            maxsize=cache_size
+        )(judge_system_prompt.__wrapped__)
+        build_judge_prompt.__wrapped__.__wrapped__ = lru_cache(
+            maxsize=cache_size
+        )(build_judge_prompt.__wrapped__)
+        aggregator_system_prompt.__wrapped__.__wrapped__ = lru_cache(
+            maxsize=cache_size
+        )(aggregator_system_prompt.__wrapped__)
+
+    def _create_judges(self) -> Dict[str, Agent]:
+        """
+        Create judge agents for each evaluation dimension.
+
+        Returns:
+            Dict[str, Agent]: Dictionary mapping dimension names to judge agents
+
+        Raises:
+            RuntimeError: If agent creation fails
+        """
+        try:
+            return {
+                dim: Agent(
+                    agent_name=f"{dim}_judge",
+                    system_prompt=judge_system_prompt(),
+                    model_name=self.model_name,
+                    max_loops=1,
+                    autosave=False,
+                    dashboard=False,
+                    verbose=False,
+                    dynamic_temperature_enabled=True,
+                )
+                for dim in EVAL_DIMENSIONS
+            }
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to create judge agents: {str(e)}"
+            )
+
+    def _create_aggregator(self) -> Agent:
+        """
+        Create the aggregator agent.
+
+        Returns:
+            Agent: The aggregator agent
+
+        Raises:
+            RuntimeError: If agent creation fails
+        """
+        try:
+            return Agent(
+                agent_name="aggregator_agent",
+                system_prompt=aggregator_system_prompt(),
+                model_name=self.model_name,
+                max_loops=1,
+                autosave=False,
+                dashboard=False,
+                verbose=False,
+                dynamic_temperature_enabled=True,
+            )
+        except Exception as e:
+            raise RuntimeError(
+                f"Failed to create aggregator agent: {str(e)}"
+            )
+
+    def _evaluate_dimension(
+        self,
+        dim: str,
+        agent: Agent,
+        user_prompt: str,
+        model_response: str,
+    ) -> Tuple[str, str]:
+        """
+        Evaluate a single dimension of the model response.
+
+        Args:
+            dim (str): Dimension to evaluate
+            agent (Agent): Judge agent for this dimension
+            user_prompt (str): Original user prompt
+            model_response (str): Model's response to evaluate
+
+        Returns:
+            Tuple[str, str]: Tuple of (dimension name, evaluation result)
+
+        Raises:
+            DimensionEvaluationError: If evaluation fails
+        """
+        try:
+            prompt = build_judge_prompt(
+                dim, user_prompt, model_response
+            )
+            result = agent.run(prompt)
+
+            self.conversation.add(
+                role=agent.agent_name,
+                content=result,
+            )
+
+            return dim, result.strip()
+        except Exception as e:
+            raise DimensionEvaluationError(
+                f"Failed to evaluate dimension {dim}: {str(e)}"
+            )
+
+    def run(self, task: str, model_response: str) -> None:
+        """
+        Run the evaluation process using ThreadPoolExecutor.
+
+        Args:
+            task (str): Original user prompt
+            model_response (str): Model's response to evaluate
+
+        Raises:
+            EvaluationError: If evaluation process fails
+        """
+        logger.info(
+            f"🧠 Running CouncilAsAJudge in parallel mode with {self.max_workers} workers...\n"
+        )
+
+        try:
+            # Create tasks for all dimensions
+            tasks = [
+                (dim, agent, task, model_response)
+                for dim, agent in self.judge_agents.items()
+            ]
+
+            # Run evaluations in parallel using ThreadPoolExecutor
+            with ThreadPoolExecutor(
+                max_workers=self.max_workers
+            ) as executor:
+                # Submit all tasks
+                future_to_dim = {
+                    executor.submit(
+                        self._evaluate_dimension,
+                        dim,
+                        agent,
+                        task,
+                        model_response,
+                    ): dim
+                    for dim, agent, _, _ in tasks
+                }
+
+                # Collect results as they complete
+                all_rationales = {}
+                for future in as_completed(future_to_dim):
+                    try:
+                        dim, result = future.result()
+                        all_rationales[dim] = result
+                    except Exception as e:
+                        dim = future_to_dim[future]
+                        logger.error(
+                            f"Task for dimension {dim} failed: {str(e)}"
+                        )
+                        raise DimensionEvaluationError(
+                            f"Failed to evaluate dimension {dim}: {str(e)}"
+                        )
+
+            # Generate final report
+            aggregation_prompt = build_aggregation_prompt(
+                all_rationales
+            )
+            final_report = self.aggregator_agent.run(
+                aggregation_prompt
+            )
+
+            self.conversation.add(
+                role=self.aggregator_agent.agent_name,
+                content=final_report,
+            )
+
+        except Exception as e:
+            raise EvaluationError(
+                f"Evaluation process failed: {str(e)}"
+            )

swarms/structs/deep_research_swarm.py

@@ -271,28 +271,11 @@ OUTPUT REQUIREMENTS:
 Remember: Your goal is to make complex information accessible while maintaining accuracy and depth. Prioritize clarity without sacrificing important nuance or detail."""
 
 
-# Initialize the research agent
-research_agent = Agent(
-    agent_name="Deep-Research-Agent",
-    agent_description="Specialized agent for conducting comprehensive research across multiple domains",
-    system_prompt=RESEARCH_AGENT_PROMPT,
-    max_loops=1,  # Allow multiple iterations for thorough research
-    tools_list_dictionary=tools,
-    model_name="gpt-4o-mini",
-)
-
-
-reasoning_duo = ReasoningDuo(
-    system_prompt=SUMMARIZATION_AGENT_PROMPT, output_type="string"
-)
-
-
 class DeepResearchSwarm:
     def __init__(
         self,
         name: str = "DeepResearchSwarm",
         description: str = "A swarm that conducts comprehensive research across multiple domains",
-        research_agent: Agent = research_agent,
         max_loops: int = 1,
         nice_print: bool = True,
         output_type: str = "json",
@@ -303,7 +286,6 @@ class DeepResearchSwarm:
     ):
         self.name = name
         self.description = description
-        self.research_agent = research_agent
         self.max_loops = max_loops
         self.nice_print = nice_print
         self.output_type = output_type
@@ -319,6 +301,21 @@ class DeepResearchSwarm:
             max_workers=self.max_workers
         )
 
+        # Initialize the research agent
+        self.research_agent = Agent(
+            agent_name="Deep-Research-Agent",
+            agent_description="Specialized agent for conducting comprehensive research across multiple domains",
+            system_prompt=RESEARCH_AGENT_PROMPT,
+            max_loops=1,  # Allow multiple iterations for thorough research
+            tools_list_dictionary=tools,
+            model_name="gpt-4o-mini",
+        )
+
+        self.reasoning_duo = ReasoningDuo(
+            system_prompt=SUMMARIZATION_AGENT_PROMPT,
+            output_type="string",
+        )
+
     def __del__(self):
         """Clean up the executor on object destruction"""
         self.executor.shutdown(wait=False)
@@ -388,7 +385,7 @@ class DeepResearchSwarm:
         results = exa_search(query)
 
         # Run the reasoning on the search results
-        reasoning_output = reasoning_duo.run(results)
+        reasoning_output = self.reasoning_duo.run(results)
 
         return (results, reasoning_output)
 
@@ -426,7 +423,7 @@ class DeepResearchSwarm:
 
                 # Add reasoning output to conversation
                 self.conversation.add(
-                    role=reasoning_duo.agent_name,
+                    role=self.reasoning_duo.agent_name,
                     content=reasoning_output,
                 )
             except Exception as e:
@@ -438,12 +435,12 @@ class DeepResearchSwarm:
 
         # Once all query processing is complete, generate the final summary
         # This step runs after all queries to ensure it summarizes all results
-        final_summary = reasoning_duo.run(
+        final_summary = self.reasoning_duo.run(
             f"Generate an extensive report of the following content: {self.conversation.get_str()}"
         )
 
         self.conversation.add(
-            role=reasoning_duo.agent_name,
+            role=self.reasoning_duo.agent_name,
             content=final_summary,
         )
 

swarms/structs/malt.py

@@ -58,12 +58,6 @@ You are a world-renowned mathematician with an extensive background in multiple
 Your response should be as comprehensive as possible, leaving no room for ambiguity, and it should reflect your mastery in constructing original mathematical arguments.
 """
 
-proof_creator_agent = Agent(
-    agent_name="Proof-Creator-Agent",
-    model_name="gpt-4o-mini",
-    max_loops=1,
-    system_prompt=proof_creator_prompt,
-)
 
 # Agent 2: Proof Verifier Agent
 proof_verifier_prompt = """
@@ -92,12 +86,6 @@ You are an esteemed mathematician and veteran academic known for your precise an
 Your review must be exhaustive, ensuring that even the most subtle aspects of the proof are scrutinized in depth.
 """
 
-proof_verifier_agent = Agent(
-    agent_name="Proof-Verifier-Agent",
-    model_name="gpt-4o-mini",
-    max_loops=1,
-    system_prompt=proof_verifier_prompt,
-)
 
 # Agent 3: Proof Refiner Agent
 proof_refiner_prompt = """
@@ -126,13 +114,6 @@ You are an expert in mathematical exposition and refinement with decades of expe
 Your refined proof should be a masterpiece of mathematical writing, addressing all the feedback with detailed revisions and explanations.
 """
 
-proof_refiner_agent = Agent(
-    agent_name="Proof-Refiner-Agent",
-    model_name="gpt-4o-mini",
-    max_loops=1,
-    system_prompt=proof_refiner_prompt,
-)
-
 
 majority_voting_prompt = """
 Engage in a comprehensive and exhaustive majority voting analysis of the following conversation, ensuring a deep and thoughtful examination of the responses provided by each agent. This analysis should not only summarize the responses but also critically engage with the content, context, and implications of each agent's input.
@@ -160,13 +141,6 @@ Please adhere to the following detailed guidelines:
 Throughout your analysis, focus on uncovering clear patterns while being attentive to the subtleties and complexities inherent in the responses. Pay particular attention to the nuances of mathematical contexts where algorithmic thinking may be required, ensuring that your examination is both rigorous and accessible to a diverse audience.
 """
 
-majority_voting_agent = Agent(
-    agent_name="Majority-Voting-Agent",
-    model_name="gpt-4o-mini",
-    max_loops=1,
-    system_prompt=majority_voting_prompt,
-)
-
 
 class MALT:
     """
@@ -210,6 +184,34 @@ class MALT:
         self.conversation = Conversation()
         logger.debug("Conversation initialized.")
 
+        proof_refiner_agent = Agent(
+            agent_name="Proof-Refiner-Agent",
+            model_name="gpt-4o-mini",
+            max_loops=1,
+            system_prompt=proof_refiner_prompt,
+        )
+
+        proof_verifier_agent = Agent(
+            agent_name="Proof-Verifier-Agent",
+            model_name="gpt-4o-mini",
+            max_loops=1,
+            system_prompt=proof_verifier_prompt,
+        )
+
+        majority_voting_agent = Agent(
+            agent_name="Majority-Voting-Agent",
+            model_name="gpt-4o-mini",
+            max_loops=1,
+            system_prompt=majority_voting_prompt,
+        )
+
+        proof_creator_agent = Agent(
+            agent_name="Proof-Creator-Agent",
+            model_name="gpt-4o-mini",
+            max_loops=1,
+            system_prompt=proof_creator_prompt,
+        )
+
         if preset_agents:
             self.main_agent = proof_creator_agent
             self.refiner_agent = proof_refiner_agent
@@ -304,12 +306,12 @@ class MALT:
         ######################### MAJORITY VOTING #########################
 
         # Majority Voting on the verified outputs
-        majority_voting_verified = majority_voting_agent.run(
+        majority_voting_verified = self.majority_voting_agent.run(
             task=any_to_str(verified_outputs),
         )
 
         self.conversation.add(
-            role=majority_voting_agent.agent_name,
+            role=self.majority_voting_agent.agent_name,
             content=majority_voting_verified,
         )
 

swarms/structs/multi_model_gpu_manager.py

@@ -147,7 +147,7 @@ class ModelMemoryCalculator:
 
     @staticmethod
     def get_huggingface_model_size(
-        model_or_path: Union[str, Any]
+        model_or_path: Union[str, Any],
     ) -> float:
         """
         Calculate the memory size of a Hugging Face model in GB.

swarms/structs/output_types.py

@@ -3,4 +3,4 @@ from swarms.utils.history_output_formatter import (
 )
 
 # Use the OutputType for type annotations
-output_type: OutputType
+output_type: OutputType  # OutputType now includes 'xml'

swarms/structs/swarm_router.py

@@ -121,7 +121,7 @@ class SwarmRouter:
         shared_memory_system (Any, optional): Shared memory system for agents. Defaults to None.
         rules (str, optional): Rules to inject into every agent. Defaults to None.
         documents (List[str], optional): List of document file paths to use. Defaults to empty list.
-        output_type (str, optional): Output format type. Defaults to "string".
+        output_type (str, optional): Output format type. Defaults to "string". Supported: 'str', 'string', 'list', 'json', 'dict', 'yaml', 'xml'.
 
     Attributes:
         name (str): Name identifier for the SwarmRouter instance
@@ -136,7 +136,7 @@ class SwarmRouter:
         shared_memory_system (Any): Shared memory system for agents
         rules (str): Rules injected into every agent
         documents (List[str]): List of document file paths
-        output_type (str): Output format type
+        output_type (str): Output format type. Supported: 'str', 'string', 'list', 'json', 'dict', 'yaml', 'xml'.
         logs (List[SwarmLog]): List of execution logs
         swarm: The instantiated swarm object
 

swarms/tools/mcp_client.py

@@ -7,7 +7,7 @@ from loguru import logger
 
 
 def parse_agent_output(
-    dictionary: Union[str, Dict[Any, Any]]
+    dictionary: Union[str, Dict[Any, Any]],
 ) -> tuple[str, Dict[Any, Any]]:
     """
     Parse agent output into tool name and parameters.