evoagentx 0.1.0__py3-none-any.whl

evoagentx/__init__.py

@@ -0,0 +1,2 @@
+
+__version__ = '0.1.0'

evoagentx/actions/__init__.py

@@ -0,0 +1,5 @@
+from .action import Action, ActionInput, ActionOutput
+from .code_verification import CodeVerification
+from .code_extraction import CodeExtraction
+
+__all__ = ["Action", "ActionInput", "ActionOutput", "CodeVerification", "CodeExtraction"]

evoagentx/actions/action.py

@@ -0,0 +1,256 @@
+import json
+from pydantic import model_validator 
+from pydantic_core import PydanticUndefined
+from typing import Optional, Type, Tuple, Union, List, Any
+
+from ..core.module import BaseModule
+from ..core.module_utils import get_type_name
+from ..core.registry import MODULE_REGISTRY
+# from ..core.base_config import Parameter
+from ..core.parser import Parser
+from ..core.message import Message
+from ..models.base_model import BaseLLM, LLMOutputParser
+from ..tools.tool import Toolkit 
+from ..prompts.context_extraction import CONTEXT_EXTRACTION
+from ..prompts.template import PromptTemplate  
+
+
+class ActionInput(LLMOutputParser):
+    """Input specification and parsing for actions.
+    
+    This class defines the input requirements for actions and provides methods
+    to generate structured input specifications. It inherits from LLMOutputParser 
+    to allow parsing of LLM outputs into structured inputs for actions.
+    
+    Notes:
+        Parameters in ActionInput should be defined in Pydantic Field format.
+        For optional variables, use format: 
+        var: Optional[int] = Field(default=None, description="xxx")
+        Remember to add `default=None` for optional parameters.
+    """
+
+    @classmethod
+    def get_input_specification(cls, ignore_fields: List[str] = []) -> str:
+        """Generate a JSON specification of the input requirements.
+        
+        Examines the class fields and produces a structured specification of
+        the input parameters, including their types, descriptions, and whether
+        they are required.
+        
+        Args:
+            ignore_fields (List[str]): List of field names to exclude from the specification.
+            
+        Returns:
+            A JSON string containing the input specification, or an empty string
+            if no fields are defined or all are ignored.
+        """
+        fields_info = {}
+        attrs = cls.get_attrs()
+        for field_name, field_info in cls.model_fields.items():
+            if field_name in ignore_fields:
+                continue
+            if field_name not in attrs:
+                continue
+            field_type = get_type_name(field_info.annotation)
+            field_desc = field_info.description if field_info.description is not None else None
+            # field_required = field_info.is_required()
+            field_default = str(field_info.default) if field_info.default is not PydanticUndefined else None
+            field_required = True if field_default is None else False
+            description = field_type + ", "
+            if field_desc is not None:
+                description += (field_desc.strip() + ", ") 
+            description += ("required" if field_required else "optional")
+            if field_default is not None:
+                description += (", Default value: " + field_default)
+            fields_info[field_name] = description
+        
+        if len(fields_info) == 0:
+            return "" 
+        fields_info_str = json.dumps(fields_info, indent=4)
+        return fields_info_str
+        
+    @classmethod
+    def get_required_input_names(cls) -> List[str]:
+        """Get a list of all required input parameter names.
+        
+        Returns:
+            List[str]: Names of all parameters that are required (don't have default values).
+        """
+        required_fields = []
+        attrs = cls.get_attrs()
+        for field_name, field_info in cls.model_fields.items():
+            if field_name not in attrs:
+                continue
+            field_default = field_info.default
+            # A field is required if it doesn't have a default value
+            if field_default is PydanticUndefined:
+                required_fields.append(field_name)
+        return required_fields
+
+
+class ActionOutput(LLMOutputParser):
+    """Output representation for actions.
+    
+    This class handles the structured output of actions, providing methods
+    to convert the output to structured data. It inherits from LLMOutputParser
+    to support parsing of LLM outputs into structured action results.
+    """
+    
+    def to_str(self) -> str:
+        """Convert the output to a formatted JSON string.
+        
+        Returns:
+            A pretty-printed JSON string representation of the structured data.
+        """
+        return json.dumps(self.get_structured_data(), indent=4)
+    
+
+class Action(BaseModule):
+    """Base class for all actions in the EvoAgentX framework.
+    
+    Actions represent discrete operations that can be performed by agents.
+    They define inputs, outputs, and execution behavior, and can optionally
+    use tools to accomplish their tasks.
+    
+    Attributes:
+        name (str): Unique identifier for the action.
+        description (str): Human-readable description of what the action does.
+        prompt (Optional[str]): Optional prompt template for this action.
+        tools (Optional[List[Toolkit]]): Optional list of tools that can be used by this action.
+        inputs_format (Optional[Type[ActionInput]]): Optional class defining the expected input structure.
+        outputs_format (Optional[Type[Parser]]): Optional class defining the expected output structure.
+    """
+
+    name: str
+    description: str
+    prompt: Optional[str] = None
+    prompt_template: Optional[PromptTemplate] = None 
+    tools: Optional[List[Toolkit]] = None # specify the possible tool for the action
+    inputs_format: Optional[Type[ActionInput]] = None # specify the input format of the action
+    outputs_format: Optional[Type[Parser]] = None  # specify the possible structured output format
+
+    def init_module(self):
+        """Initialize the action module.
+        
+        This method is called after the action is instantiated.
+        Subclasses can override this to perform custom initialization.
+        """
+        pass 
+
+    def to_dict(self, exclude_none: bool = True, ignore: List[str] = [], **kwargs) -> dict:
+        """
+        Convert the action to a dictionary for saving.  
+        """
+        data = super().to_dict(exclude_none=exclude_none, ignore=ignore, **kwargs)
+        if self.inputs_format:
+            data["inputs_format"] = self.inputs_format.__name__ 
+        if self.outputs_format:
+            data["outputs_format"] = self.outputs_format.__name__ 
+        # TODO: customize serialization for the tools 
+        return data 
+    
+    @model_validator(mode="before")
+    @classmethod
+    def validate_data(cls, data: Any) -> Any:
+        if "inputs_format" in data and data["inputs_format"] and isinstance(data["inputs_format"], str):
+            # only used when loading from a file
+            data["inputs_format"] = MODULE_REGISTRY.get_module(data["inputs_format"])
+        if "outputs_format" in data and data["outputs_format"] and isinstance(data["outputs_format"], str):
+            # only used when loading from a file
+            data["outputs_format"] = MODULE_REGISTRY.get_module(data["outputs_format"])
+        # TODO: customize loading for the tools
+        return data 
+    
+    def execute(self, llm: Optional[BaseLLM] = None, inputs: Optional[dict] = None, sys_msg: Optional[str]=None, return_prompt: bool = False, **kwargs) -> Optional[Union[Parser, Tuple[Parser, str]]]:
+        """Execute the action to produce a result.
+        
+        This is the main entry point for executing an action. Subclasses must
+        implement this method to define the action's behavior.
+
+        Args:
+            llm (Optional[BaseLLM]): The LLM used to execute the action.
+            inputs (Optional[dict]): Input data for the action execution. The input data should be a dictionary that matches the input format of the provided prompt. 
+                For example, if the prompt contains a variable `{input_var}`, the `inputs` dictionary should have a key `input_var`, otherwise the variable will be set to empty string. 
+            sys_msg (Optional[str]): Optional system message for the LLM.
+            return_prompt (bool): Whether to return the complete prompt passed to the LLM.
+            **kwargs (Any): Additional keyword arguments for the execution.
+        
+        Returns:
+            If `return_prompt` is False, the method returns a Parser object containing the structured result of the action.
+            If `return_prompt` is True, the method returns a tuple containing the Parser object and the complete prompt passed to the LLM.
+        """
+        raise NotImplementedError(f"`execute` function of {type(self).__name__} is not implemented!")
+
+    async def async_execute(self, llm: Optional[BaseLLM] = None, inputs: Optional[dict] = None, sys_msg: Optional[str]=None, return_prompt: bool = False, **kwargs) -> Optional[Union[Parser, Tuple[Parser, str]]]:
+        """
+        Asynchronous execution of the action.
+        
+        This method is the asynchronous counterpart of the `execute` method.
+        It allows the action to be executed asynchronously using an LLM.
+        """
+        raise NotImplementedError(f"`async_execute` function of {type(self).__name__} is not implemented!")
+
+class ContextExtraction(Action):
+    """Action for extracting structured inputs from context.
+    
+    This action analyzes a conversation context to extract relevant information
+    that can be used as inputs for other actions. It uses the LLM to interpret
+    unstructured contextual information and format it according to the target
+    action's input requirements.
+    """
+
+    def __init__(self, **kwargs):
+        name = kwargs.pop("name") if "name" in kwargs else CONTEXT_EXTRACTION["name"]
+        description = kwargs.pop("description") if "description" in kwargs else CONTEXT_EXTRACTION["description"]
+        super().__init__(name=name, description=description, **kwargs)
+
+    def get_context_from_messages(self, messages: List[Message]) -> str:
+        str_context = "\n\n".join([str(msg) for msg in messages])
+        return str_context 
+    
+    def execute(self, llm: Optional[BaseLLM] = None, action: Action = None, context: List[Message] = None, **kwargs) -> Union[dict, None]:
+        """Extract structured inputs for an action from conversation context.
+        
+        This method uses the LLM to analyze the conversation context and extract
+        information that matches the input requirements of the target action.
+        
+        Args:
+            llm: The language model to use for extraction.
+            action: The target action whose input requirements (`inputs_format`) define what to extract.
+            context: List of messages providing the conversation context.
+            **kwargs: Additional keyword arguments.
+            
+        Returns:
+            A dictionary containing the extracted inputs for the target action,
+            or None if extraction is not possible (e.g., if the action doesn't
+            require inputs or if context is missing).
+        """
+        if action is None or context is None:
+            return None
+        
+        action_inputs_cls: Type[ActionInput] = action.inputs_format
+        if action_inputs_cls is None:
+            # the action does not require inputs
+            return None
+        
+        action_inputs_desc = action_inputs_cls.get_input_specification()
+        str_context = self.get_context_from_messages(messages=context)
+
+        if not action_inputs_desc or not str_context:
+            return None
+        
+        prompt = CONTEXT_EXTRACTION["prompt"].format(
+            context=str_context,
+            action_name=action.name, 
+            action_description=action.description,
+            action_inputs=action_inputs_desc
+        )
+
+        action_inputs = llm.generate(
+            prompt=prompt, 
+            system_message=CONTEXT_EXTRACTION["system_prompt"],
+            parser=action_inputs_cls
+        )
+        action_inputs_data = action_inputs.get_structured_data()
+
+        return action_inputs_data

evoagentx/actions/agent_generation.py

@@ -0,0 +1,198 @@
+import re
+from pydantic import Field, model_validator
+from typing import Optional, List
+
+from ..core.logging import logger
+from ..core.module import BaseModule
+from ..core.base_config import Parameter
+from ..models.base_model import BaseLLM
+from .action import Action, ActionInput, ActionOutput
+from ..prompts.agent_generator import AGENT_GENERATION_ACTION
+from ..prompts.tool_calling import AGENT_GENERATION_TOOLS_PROMPT
+from ..utils.utils import normalize_text
+
+class AgentGenerationInput(ActionInput):
+    """
+    Input specification for the agent generation action.
+    """
+
+    goal: str = Field(description="A detailed statement of the workflow's goal, explaining the objectives the entire workflow aims to achieve")
+    workflow: str = Field(description="An overview of the entire workflow, detailing all sub-tasks with their respective names, descriptions, inputs, and outputs")
+    task: str = Field(description="A detailed JSON representation of the sub-task requiring agent generation. It should include the task's name, description, inputs, and outputs.")
+
+    history: Optional[str] = Field(default=None, description="Optional field containing previously selected or generated agents.")
+    suggestion: Optional[str] = Field(default=None, description="Optional suggestions to refine the generated agents.")
+    existing_agents: Optional[str] = Field(default=None, description="Optional field containing the description of predefined agents, including each agent's name, role, and available actions.")
+    tools: Optional[str] = Field(default=None, description="Optional field containing the description of tools that agents can use, including each tool's name and functionality.")
+
+
+class GeneratedAgent(BaseModule):
+    """
+    Representation of a generated agent with validation capabilities.
+    """
+
+    name: str 
+    description: str 
+    inputs: List[Parameter]
+    outputs: List[Parameter]
+    prompt: str
+    tool_names: Optional[List[str]] = None
+
+    @classmethod
+    def find_output_name(cls, text: str, outputs: List[str]):
+        def sim(t1: str, t2: str):
+            t1_words = normalize_text(t1).split()
+            t2_words = normalize_text(t2).split()
+            return len(set(t1_words)&set(t2_words))
+        
+        similarities = [sim(text, output) for output in outputs]
+        max_sim = max(similarities)
+        return outputs[similarities.index(max_sim)]
+
+    @model_validator(mode="after")
+    @classmethod
+    def validate_prompt(cls, agent: 'GeneratedAgent'):
+        """Validate and fix the agent's prompt template.
+        
+        This validator ensures that:
+        1. All input parameters are properly referenced in the prompt
+        2. Input references use the correct format with braces
+        3. All output sections match the defined output parameters
+        
+        If there are mismatches in the output sections, it attempts to
+        fix them by finding the most similar output name.
+        
+        Args:
+            agent: The GeneratedAgent instance to validate.
+            
+        Returns:
+            The validated and potentially modified GeneratedAgent.
+            
+        Raises:
+            ValueError: If inputs are missing from the prompt or output sections don't match the defined outputs.
+        """
+        # check whether all the inputs are present in the prompt 
+        input_names = [inp.name for inp in agent.inputs]
+        prompt_has_inputs = [name in agent.prompt for name in input_names]
+        if not all(prompt_has_inputs):
+            missing_input_names = [name for name, has_input in zip(input_names, prompt_has_inputs) if not has_input]
+            raise ValueError(f'The prompt miss inputs: {missing_input_names}')
+        
+        # check the format of the prompt to make sure it is wrapped in brackets. 
+        pattern = r"### Instructions(.*?)### Output Format"
+        prompt = agent.prompt
+
+        def replace_with_braces(match):
+            instructions = match.group(1)
+            for name in input_names:
+                instructions = re.sub(fr'<input>{{*\b{re.escape(name)}\b}}*</input>', fr'<input>{{{name}}}</input>', instructions)
+            return "### Instructions" + instructions + "### Output Format"
+        
+        modified_prompt = re.sub(pattern, replace_with_braces, prompt, flags=re.DOTALL)
+        agent.prompt = modified_prompt
+
+        # check whether all the outputs are present in the prompt
+        prompt = agent.prompt
+        pattern = r"### Output Format(.*)"
+        outputs_names = [out.name for out in agent.outputs]
+
+        def fix_output_names(match):
+            output_format = match.group(1)
+            matches = re.findall(r"## ([^\n#]+)", output_format, flags=re.DOTALL)
+            generated_outputs = [m.strip() for m in matches if m.strip() != "Thought"]
+            # check the number of generated outputs and agent outputs 
+            if len(generated_outputs) != len(outputs_names):
+                raise ValueError(f"The number of outputs in the prompt is different from that defined in the `outputs` field of the agent. The outputs in the prompt are: {generated_outputs}, while the outputs from the agent's `outputs` field are: {outputs_names}")
+            # check whether the generated output names are the same as agent outputs 
+            for generated_output in generated_outputs:
+                if generated_output not in outputs_names:
+                    most_similar_output_name = cls.find_output_name(text=generated_output, outputs=outputs_names)
+                    output_format = output_format.replace(generated_output, most_similar_output_name)
+                    logger.warning(f"Couldn't find output name in prompt ('{generated_output}') in agent's outputs. Replace it with the most similar agent output: '{most_similar_output_name}'")
+            return "### Output Format" + output_format
+        
+        modified_prompt = re.sub(pattern, fix_output_names, prompt, flags=re.DOTALL)
+        agent.prompt = modified_prompt
+
+        return agent
+
+
+class AgentGenerationOutput(ActionOutput):
+
+    selected_agents: List[str] = Field(description="A list of selected agent's names")
+    generated_agents: List[GeneratedAgent] = Field(description="A list of generated agetns to address a sub-task")
+    
+
+class AgentGeneration(Action):
+    """
+    Action for generating agent specifications for workflow tasks.
+    
+    This action analyzes task requirements and generates appropriate agent
+    specifications, including their prompts, inputs, and outputs. It can either
+    select from existing agents or create new ones tailored to the task.
+    """
+
+    def __init__(self, **kwargs):
+        name = kwargs.pop("name") if "name" in kwargs else AGENT_GENERATION_ACTION["name"]
+        description = kwargs.pop("description") if "description" in kwargs else AGENT_GENERATION_ACTION["description"]
+        prompt = kwargs.pop("prompt") if "prompt" in kwargs else AGENT_GENERATION_ACTION["prompt"]
+        # inputs_format = kwargs.pop("inputs_format") if "inputs_format" in kwargs else AgentGenerationInput
+        # outputs_format = kwargs.pop("outputs_format") if "outputs_format" in kwargs else AgentGenerationOutput
+        inputs_format = kwargs.pop("inputs_format", None) or AgentGenerationInput
+        outputs_format = kwargs.pop("outputs_format", None) or AgentGenerationOutput 
+        tools = kwargs.pop("tools", None)
+        super().__init__(name=name, description=description, prompt=prompt, inputs_format=inputs_format, outputs_format=outputs_format, **kwargs)
+        self.tools = tools
+    
+    def execute(self, llm: Optional[BaseLLM] = None, inputs: Optional[dict] = None, sys_msg: Optional[str]=None, return_prompt: bool = False, **kwargs) -> AgentGenerationOutput:
+        """Execute the agent generation process.
+        
+        This method uses the provided language model to generate agent specifications
+        based on the workflow context and task requirements.
+        
+        Args:
+            llm: The language model to use for generation.
+            inputs: Input data containing workflow and task information.
+            sys_msg: Optional system message for the language model.
+            return_prompt: Whether to return both the generated agents and the prompt used.
+            **kwargs: Additional keyword arguments.
+            
+        Returns:
+            If return_prompt is False (default): The generated agents output.
+            If return_prompt is True: A tuple of (generated agents, prompt used).
+            
+        Raises:
+            ValueError: If the inputs are None or empty.
+        """
+        if not inputs:
+            logger.error("AgentGeneration action received invalid `inputs`: None or empty.")
+            raise ValueError('The `inputs` to AgentGeneration action is None or empty.')
+        
+        inputs_format: AgentGenerationInput = self.inputs_format
+        outputs_format: AgentGenerationOutput = self.outputs_format
+
+        prompt_params_names = inputs_format.get_attrs()
+        prompt_params_values = {param: inputs.get(param, "") for param in prompt_params_names}
+        if self.tools:
+            tool_description = [
+                {
+                    tool.name: [
+                        s["function"]["description"] for s in tool.get_tool_schemas()
+                    ],
+                }
+                for tool in self.tools
+            ]
+            prompt_params_values["tools"] = AGENT_GENERATION_TOOLS_PROMPT.format(tools_description=tool_description)
+        prompt = self.prompt.format(**prompt_params_values)
+        agents = llm.generate(
+            prompt = prompt, 
+            system_message = sys_msg, 
+            parser=outputs_format,
+            parse_mode="json"
+        )
+        
+        if return_prompt:
+            return agents, prompt
+        
+        return agents
+