added readmea + demo

ControllerAtomicFlow.py

@@ -1,19 +1,72 @@
 import json
 from copy import deepcopy
 from typing import Any, Dict, List
-from flow_modules.aiflows.OpenAIChatFlowModule import OpenAIChatAtomicFlow
+from flow_modules.aiflows.ChatFlowModule import ChatAtomicFlow
 
 from dataclasses import dataclass
 
 
 @dataclass
 class Command:
+    """ The command class is used to store the information about the commands that the user can give to the controller.
+    
+    :param name: The name of the command.
+    :type name: str
+    :param description: The description of the command.
+    :type description: str
+    :param input_args: The input arguments of the command.
+    :type input_args: List[str]
+    """
     name: str
     description: str
     input_args: List[str]
 
 
-class ControllerAtomicFlow(OpenAIChatAtomicFlow):
+class ControllerAtomicFlow(ChatAtomicFlow):
+    """ The ControllerAtomicFlow is an atomic flow that, given an observation and a goal, can call a set of commands and arguments which are then usually executed by an ExecutorAtomicFlow (branching flow).
+
+        *Configuration Parameters*
+        
+        - `name` (str): The name of the flow. Default: "ControllerFlow"
+        - `description` (str): A description of the flow. This description is used to generate the help message of the flow.
+        Default: "Proposes the next action to take towards achieving the goal, and prepares the input for the executor."
+        - `enable_cache` (bool): Whether to enable caching or not. Default: True
+        - `commands` (List[Dict[str,Any]]): A list of commands that the controller can call. Default: []
+        - `finish` (Dict[str,Any]): The configuration of the finish command. Default parameters: No default parameters.
+        - `system_message_prompt_template` (Dict[str, Any]): The prompt template used to generate the system message.
+        By default, it's type is flows.prompt_template.JinjaPrompt. It's default parameters are:
+            - `template` (str): The template of the prompt. Default: see ControllerAtomicFlow.yaml for the default template.
+            - `input_variables` (List[str]): The input variables of the prompt. Default: ["commands"]. Note that the commands are the commands of the executor 
+            (subflows of branching flow) and are actually to the system prompt template via the `_build_commands_manual` function of this class.
+        - `human_message_prompt_template` (Dict[str, Any]): The prompt template of the human/user message (message used everytime the except the first time in).
+        It's passed as the user message to the LLM. By default its of type flows.prompt_template.JinjaPrompt and has the following parameters:
+            - `template` (str): The template of the prompt. Default: see ControllerAtomicFlow.yaml for the default template.
+            - `input_variables` (List[str]): The input variables of the prompt. Default: ["observation"]
+        - init_human_message_prompt_template` (Dict[str, Any]):  The prompt template of the human/user message used to initialize the conversation
+        (first time in). It is used to generate the human message. It's passed as the user message to the LLM.
+        By default its of type flows.prompt_template.JinjaPrompt and has the following parameters:
+            - `template` (str): The template of the prompt. Default: see ControllerAtomicFlow.yaml for the default template.
+            - `input_variables` (List[str]): The input variables of the prompt. Default: ["goal"]
+        - All other parameters are inherited from the default configuration of ChatAtomicFlow (see Flowcard, i.e. README.md, of ChatAtomicFlowModule).
+        
+        *Initial Input Interface (this is the interface used the first time the flow is called)*:
+        - `goal` (str): The goal of the controller. Usually asked by the user/human (e.g. "I want to know the occupation and birth date of Michael Jordan.")
+        
+        *Input Interface (this is the interface used after the first time the flow is called)*:
+        - `observation` (str): The observation of the controller's previous action. Usually the response of the ExecutorAtomicFlow (e.g. "The result of a wikipedia search (if the ExecutorAtomicFlow has a WikipediaExecutorAtomicFlow).")
+        
+        *Output Interface:*
+        - `thought` (str): The thought of the controller on what to do next (which command to call)
+        - `reasoning` (str): The reasoning of the controller on why it thinks the command it wants to call is the right one
+        - `criticism` (str): The criticism of the controller of it's thinking process
+        - `command` (str): The command to the executor chooses to call
+        - `command_args` (Dict[str, Any]): The arguments of the command to call
+            
+        :param commands: The commands that the controller can call (typically the commands of the executor).
+        :type commands: List[Command]
+        :param \**kwargs: The parameters specific to the ChatAtomicFlow.
+        :type \**kwargs: Dict[str, Any]
+    """
     def __init__(self, commands: List[Command], **kwargs):
         super().__init__(**kwargs)
         self.system_message_prompt_template = self.system_message_prompt_template.partial(
@@ -22,6 +75,13 @@ class ControllerAtomicFlow(OpenAIChatAtomicFlow):
 
     @staticmethod
     def _build_commands_manual(commands: List[Command]) -> str:
+        """ This method writes the commands that the ControllerAtomicFlow in string to pass it to the system_message_prompt_template.
+        
+        :param commands: The commands that the controller can call.
+        :type commands: List[Command]
+        :return: The string containing the commands.
+        :rtype: str
+        """
         ret = ""
         for i, command in enumerate(commands):
             command_input_json_schema = json.dumps(
@@ -31,6 +91,13 @@ class ControllerAtomicFlow(OpenAIChatAtomicFlow):
 
     @classmethod
     def instantiate_from_config(cls, config):
+        """ This method instantiates the flow from a configuration file.
+        
+        :param config: The configuration of the flow.
+        :type config: Dict[str, Any]
+        :return: The instantiated flow.
+        :rtype: ControllerAtomicFlow
+        """
         flow_config = deepcopy(config)
 
         kwargs = {"flow_config": flow_config}
@@ -51,6 +118,13 @@ class ControllerAtomicFlow(OpenAIChatAtomicFlow):
         return cls(**kwargs)
 
     def run(self, input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """ This method runs the flow. Note that the response of the LLM is in the JSON format, but it's not a hard constraint (it can hallucinate and return an invalid JSON)
+        
+        :param input_data: The input data of the flow.
+        :type input_data: Dict[str, Any]
+        :return: The output data of the flow (thought, reasoning, criticism, command, command_args)
+        :rtype: Dict[str, Any]
+        """
         api_output = super().run(input_data)["api_output"].strip()
         response = json.loads(api_output)
         return response

ControllerAtomicFlow.yaml

@@ -58,6 +58,8 @@ system_message_prompt_template:
     "thought": "thought",
     "reasoning": "reasoning",
     "plan": "- short bulleted\n- list that conveys\n- long-term plan",
+    "criticism": "constructive self-criticism",
+    "speak": "thoughts summary to say to user",
     "command": "command name",
     "command_args": {
         "arg name": "value"

ControllerExecutorFlow.py

@@ -10,7 +10,62 @@ log = logging.get_logger(__name__)
 
 
 class ControllerExecutorFlow(CircularFlow):
+    """ This class implements a ControllerExecutorFlow. It's composed of a ControllerAtomicFlow and an ExecutorFlow.
+    Where typically the ControllerAtomicFlow is uses a LLM to decide which command to call and the ExecutorFlow (branching flow) is used to execute the command.
+    
+    It contains the following subflows:
+    
+    - A Controller Atomic Flow: It is a flow that to decides which command to get closer to completing it's task of accomplishing a given goal.
+    - An Executor Flow: It is a branching flow that uses the executes the command instructed by the ControllerAtomicFlow.
+        
+    An illustration of the flow is as follows:
+        
+           goal -----|-----> ControllerFlow----->|-----> (anwser,status)
+                     ^                           |
+                     |                           |
+                     |                           v
+                     |<----- ExecutorFlow <------|
+                     
+    *Configuration Parameters*:
+    
+    - `name` (str): The name of the flow. Default: "CtrlEx"
+    - `description` (str): A description of the flow. This description is used to generate the help message of the flow.
+    Default: "ControllerExecutor (i.e., MRKL, ReAct) interaction implementation with Flows
+    that approaches the problem solving in two phases: one Flow chooses the next step and another Flow executes it.
+    This is repeated until the controller Flow concludes on an answer."
+    - `max_rounds` (int): The maximum number of rounds the flow can run for. 
+    Default: 30.
+    - `subflows_config` (Dict[str,Any]): A dictionary of the subflows configurations. Default:
+        - `Controller`: The configuration of the Controller Flow. By default, it a ControllerAtomicFlow. Default parameters:
+            - `finish` (Dict[str,Any]): The configuration of the finish command. Default parameters:
+                - `description` (str): The description of the command.
+                Default: "Signal that the objective has been satisfied, and returns the answer to the user."
+                - `input_args` (List[str]): The input arguments of the command. Default: ["answer"]
+            -  All other parameters are inherited from the default configuration of ControllerAtomicFlow (see ControllerAtomicFlow)
+        - `Executor`: The configuration of the Executor Flow. By default, it's a BranchingFlow. There are no default parameters, the flow
+        parameter to to be defined is:
+            - `subflows_config` (Dict[str,Any]): A dictionary of the configuration of the subflows of the branching flow.
+            These subflows are typically also the possible commands of the Controller Flow. Default: []
+    - `early_exit_key` (str): The key that is used to exit the flow. Default: "EARLY_EXIT"
+    - `topology` (str): The topology of the flow which is "circular". 
+    By default, the topology is the one shown in the illustration above
+    (the topology is also described in ControllerExecutorFlow.yaml).
+             
+                     
+    *Input Interface*:
+        
+    - `goal` (str): The goal of the controller. Usually asked by the user/human (e.g. "I want to know the occupation and birth date of Michael Jordan.")
+    
+    *Output Interface*:
+    
+    - `answer` (str): The answer of the flow to the query (e.g. "Michael Jordan is a basketball player and business man. He was born on February 17, 1963.")
+    - `status` (str): The status of the flow. It can be "finished" or "unfinished". If the status is "unfinished", it's usually because the maximum amount of rounds was reached before the model found an answer.
+    
+    :param flow_config: The configuration of the flow (see Configuration Parameters).
+    :param subflows: A list of subflows. Required when instantiating the subflow programmatically (it replaces subflows_config from flow_config).                                  
+    """
     def _on_reach_max_round(self):
+        """ This method is called when the flow reaches the maximum amount of rounds. It updates the state of the flow and starts the process of terminating the flow."""
         self._state_update_dict({
             "answer": "The maximum amount of rounds was reached before the model found an answer.",
             "status": "unfinished"
@@ -18,6 +73,14 @@ class ControllerExecutorFlow(CircularFlow):
 
     @CircularFlow.output_msg_payload_processor
     def detect_finish_or_continue(self, output_payload: Dict[str, Any], src_flow: ControllerAtomicFlow) -> Dict[str, Any]:
+        """ This method is called when the ExecutorAtomicFlow receives a message from the ControllerAtomicFlow. It checks if the flow should finish or continue.
+        
+        :param output_payload: The output payload of the ControllerAtomicFlow.
+        :type output_payload: Dict[str, Any]
+        :param src_flow: The ControllerAtomicFlow.
+        :type src_flow: ControllerAtomicFlow
+        :return: The output payload of the ControllerAtomicFlow.
+        """
         command = output_payload["command"]
         if command == "finish":
             return {

ControllerExecutorFlow.yaml

@@ -21,9 +21,7 @@ subflows_config:
 #      wiki_search:
 #        description: "Performs a search on Wikipedia."
 #        input_args: ["search_term"]
-#      ddg_search:
-#        description: "Query the search engine DuckDuckGo."
-#        input_args: ["query"]
+
 
   Executor:
     _target_: flows.base_flows.BranchingFlow.instantiate_from_default_config
@@ -31,10 +29,7 @@ subflows_config:
 #    subflows_config:
 #      wiki_search:
 #        _target_: .WikiSearchAtomicFlow.instantiate_from_default_config
-#      ddg_search:
-#        _target_: flows.application_flows.LCToolFlowModule.LCToolFlow.instantiate_from_default_config
-#        backend:
-#          _target_: langchain.tools.DuckDuckGoSearchRun
+
 
 early_exit_key: "EARLY_EXIT"
 

README.md

@@ -1,5 +1,366 @@
----
-license: mit
----
+# Table of Contents
+
+* [ControllerAtomicFlow](#ControllerAtomicFlow)
+  * [Command](#ControllerAtomicFlow.Command)
+  * [ControllerAtomicFlow](#ControllerAtomicFlow.ControllerAtomicFlow)
+    * [instantiate\_from\_config](#ControllerAtomicFlow.ControllerAtomicFlow.instantiate_from_config)
+    * [run](#ControllerAtomicFlow.ControllerAtomicFlow.run)
+* [\_\_init\_\_](#__init__)
+* [WikiSearchAtomicFlow](#WikiSearchAtomicFlow)
+  * [WikiSearchAtomicFlow](#WikiSearchAtomicFlow.WikiSearchAtomicFlow)
+    * [run](#WikiSearchAtomicFlow.WikiSearchAtomicFlow.run)
+* [wikipediaAPI](#wikipediaAPI)
+  * [WikipediaAPIWrapper](#wikipediaAPI.WikipediaAPIWrapper)
+    * [validate\_environment](#wikipediaAPI.WikipediaAPIWrapper.validate_environment)
+    * [run](#wikipediaAPI.WikipediaAPIWrapper.run)
+    * [search\_page\_titles](#wikipediaAPI.WikipediaAPIWrapper.search_page_titles)
+* [ControllerExecutorFlow](#ControllerExecutorFlow)
+  * [ControllerExecutorFlow](#ControllerExecutorFlow.ControllerExecutorFlow)
+    * [detect\_finish\_or\_continue](#ControllerExecutorFlow.ControllerExecutorFlow.detect_finish_or_continue)
+
+<a id="ControllerAtomicFlow"></a>
+
+# ControllerAtomicFlow
+
+<a id="ControllerAtomicFlow.Command"></a>
+
+## Command Objects
+
+```python
+@dataclass
+class Command()
+```
+
+The command class is used to store the information about the commands that the user can give to the controller.
+
+**Arguments**:
+
+- `name` (`str`): The name of the command.
+- `description` (`str`): The description of the command.
+- `input_args` (`List[str]`): The input arguments of the command.
+
+<a id="ControllerAtomicFlow.ControllerAtomicFlow"></a>
+
+## ControllerAtomicFlow Objects
+
+```python
+class ControllerAtomicFlow(ChatAtomicFlow)
+```
+
+The ControllerAtomicFlow is an atomic flow that, given an observation and a goal, can call a set of commands and arguments which are then usually executed by an ExecutorAtomicFlow (branching flow).
+
+*Configuration Parameters*
+
+- `name` (str): The name of the flow. Default: "ControllerFlow"
+- `description` (str): A description of the flow. This description is used to generate the help message of the flow.
+Default: "Proposes the next action to take towards achieving the goal, and prepares the input for the executor."
+- `enable_cache` (bool): Whether to enable caching or not. Default: True
+- `commands` (List[Dict[str,Any]]): A list of commands that the controller can call. Default: []
+- `finish` (Dict[str,Any]): The configuration of the finish command. Default parameters: No default parameters.
+- `system_message_prompt_template` (Dict[str, Any]): The prompt template used to generate the system message.
+By default, it's type is flows.prompt_template.JinjaPrompt. It's default parameters are:
+    - `template` (str): The template of the prompt. Default: see ControllerAtomicFlow.yaml for the default template.
+    - `input_variables` (List[str]): The input variables of the prompt. Default: ["commands"]. Note that the commands are the commands of the executor 
+    (subflows of branching flow) and are actually to the system prompt template via the `_build_commands_manual` function of this class.
+- `human_message_prompt_template` (Dict[str, Any]): The prompt template of the human/user message (message used everytime the except the first time in).
+It's passed as the user message to the LLM. By default its of type flows.prompt_template.JinjaPrompt and has the following parameters:
+    - `template` (str): The template of the prompt. Default: see ControllerAtomicFlow.yaml for the default template.
+    - `input_variables` (List[str]): The input variables of the prompt. Default: ["observation"]
+- init_human_message_prompt_template` (Dict[str, Any]):  The prompt template of the human/user message used to initialize the conversation
+(first time in). It is used to generate the human message. It's passed as the user message to the LLM.
+By default its of type flows.prompt_template.JinjaPrompt and has the following parameters:
+    - `template` (str): The template of the prompt. Default: see ControllerAtomicFlow.yaml for the default template.
+    - `input_variables` (List[str]): The input variables of the prompt. Default: ["goal"]
+- All other parameters are inherited from the default configuration of ChatAtomicFlow (see Flowcard, i.e. README.md, of ChatAtomicFlowModule).
+
+*Initial Input Interface (this is the interface used the first time the flow is called)*:
+- `goal` (str): The goal of the controller. Usually asked by the user/human (e.g. "I want to know the occupation and birth date of Michael Jordan.")
+
+*Input Interface (this is the interface used after the first time the flow is called)*:
+- `observation` (str): The observation of the controller's previous action. Usually the response of the ExecutorAtomicFlow (e.g. "The result of a wikipedia search (if the ExecutorAtomicFlow has a WikipediaExecutorAtomicFlow).")
+
+*Output Interface:*
+- `thought` (str): The thought of the controller on what to do next (which command to call)
+- `reasoning` (str): The reasoning of the controller on why it thinks the command it wants to call is the right one
+- `criticism` (str): The criticism of the controller of it's thinking process
+- `command` (str): The command to the executor chooses to call
+- `command_args` (Dict[str, Any]): The arguments of the command to call
+
+**Arguments**:
+
+- `commands` (`List[Command]`): The commands that the controller can call (typically the commands of the executor).
+- `\**kwargs` (`Dict[str, Any]`): The parameters specific to the ChatAtomicFlow.
+
+<a id="ControllerAtomicFlow.ControllerAtomicFlow.instantiate_from_config"></a>
+
+#### instantiate\_from\_config
+
+```python
+@classmethod
+def instantiate_from_config(cls, config)
+```
+
+This method instantiates the flow from a configuration file.
+
+**Arguments**:
+
+- `config` (`Dict[str, Any]`): The configuration of the flow.
+
+**Returns**:
+
+`ControllerAtomicFlow`: The instantiated flow.
+
+<a id="ControllerAtomicFlow.ControllerAtomicFlow.run"></a>
+
+#### run
+
+```python
+def run(input_data: Dict[str, Any]) -> Dict[str, Any]
+```
+
+This method runs the flow. Note that the response of the LLM is in the JSON format, but it's not a hard constraint (it can hallucinate and return an invalid JSON)
+
+**Arguments**:
+
+- `input_data` (`Dict[str, Any]`): The input data of the flow.
+
+**Returns**:
+
+`Dict[str, Any]`: The output data of the flow (thought, reasoning, criticism, command, command_args)
+
+<a id="__init__"></a>
+
+# \_\_init\_\_
+
+<a id="WikiSearchAtomicFlow"></a>
+
+# WikiSearchAtomicFlow
+
+<a id="WikiSearchAtomicFlow.WikiSearchAtomicFlow"></a>
+
+## WikiSearchAtomicFlow Objects
+
+```python
+class WikiSearchAtomicFlow(AtomicFlow)
+```
+
+This class implements a WikiSearch Atomic Flow. It's used to execute a Wikipedia search and get page summaries.
+
+*Configuration Parameters*:
+
+- `name` (str): The name of the flow. Default: "WikiSearchAtomicFlow"
+- `description` (str): A description of the flow. This description is used to generate the help message of the flow.
+Default: "A Flow that queries the wikipedia API for a page content."
+- `lang` (str): The language of the Wikipedia page. Default: "en"
+- `top_k_results` (int): The number of top results to return. Default: 5
+- `doc_content_chars_max` (int): The maximum number of characters of the content of the Wikipedia page. Default: 3000
+- Other parameters are inherited from the default configuration of AtomicFlow (see AtomicFlow)
+
+*input_interface*:
+
+    - `search_term` (str): The search term to search for.
+
+*output_interface*:
+
+    - `wiki_content` (str): The content of the Wikipedia page.
+
+**Arguments**:
+
+- `\**kwargs`: The keyword arguments passed to the AtomicFlow constructor
+
+<a id="WikiSearchAtomicFlow.WikiSearchAtomicFlow.run"></a>
+
+#### run
+
+```python
+def run(input_data: Dict[str, Any]) -> Dict[str, Any]
+```
+
+Runs the WikiSearch Atomic Flow. It's used to execute a Wikipedia search and get page summaries.
+
+**Arguments**:
+
+- `input_data` (`Dict[str, Any]`): The input data dictionary
+
+**Returns**:
+
+`Dict[str, Any]`: The output data dictionary
+
+<a id="wikipediaAPI"></a>
+
+# wikipediaAPI
+
+Util that calls Wikipedia. references: https://github.com/hwchase17/langchain/blob/9b615022e2b6a3591347ad77a3e21aad6cf24c49/docs/extras/modules/agents/tools/integrations/wikipedia.ipynb#L36
+
+<a id="wikipediaAPI.WikipediaAPIWrapper"></a>
+
+## WikipediaAPIWrapper Objects
+
+```python
+class WikipediaAPIWrapper(BaseModel)
+```
+
+Wrapper around WikipediaAPI.
+
+To use, you should have the ``wikipedia`` python package installed.
+This wrapper will use the Wikipedia API to conduct searches and
+fetch page summaries. By default, it will return the page summaries
+of the top-k results.
+It limits the Document content by doc_content_chars_max.
+
+**Arguments**:
+
+- `top_k_results` (`int`): The number of results to return.
+- `lang` (`str`): The language to use for the Wikipedia API.
+- `doc_content_chars_max` (`int`): The maximum number of characters in the Document content.
+
+<a id="wikipediaAPI.WikipediaAPIWrapper.validate_environment"></a>
+
+#### validate\_environment
+
+```python
+@root_validator()
+def validate_environment(cls, values: Dict) -> Dict
+```
+
+Validate that the python package exists in environment.
+
+**Arguments**:
+
+- `values` (`Dict`): The values to validate.
+
+**Raises**:
+
+- `ImportError`: If the package is not installed.
+
+**Returns**:
+
+`Dict`: The validated values.
+
+<a id="wikipediaAPI.WikipediaAPIWrapper.run"></a>
+
+#### run
+
+```python
+def run(query: str) -> str
+```
+
+Run Wikipedia search and get page summaries.
+
+**Arguments**:
+
+- `query` (`str`): The query to search for.
+
+**Returns**:
+
+`str`: The page summaries.
+
+<a id="wikipediaAPI.WikipediaAPIWrapper.search_page_titles"></a>
+
+#### search\_page\_titles
+
+```python
+def search_page_titles(query: str) -> List[str]
+```
+
+Run Wikipedia search and get page summaries.
+
+**Arguments**:
+
+- `query` (`str`): The query to search for.
+
+**Returns**:
+
+`List[str]`: The page titles.
+
+<a id="ControllerExecutorFlow"></a>
+
+# ControllerExecutorFlow
+
+<a id="ControllerExecutorFlow.ControllerExecutorFlow"></a>
+
+## ControllerExecutorFlow Objects
+
+```python
+class ControllerExecutorFlow(CircularFlow)
+```
+
+This class implements a ControllerExecutorFlow. It's composed of a ControllerAtomicFlow and an ExecutorFlow.
+
+Where typically the ControllerAtomicFlow is uses a LLM to decide which command to call and the ExecutorFlow (branching flow) is used to execute the command.
+
+It contains the following subflows:
+
+- A Controller Atomic Flow: It is a flow that to decides which command to get closer to completing it's task of accomplishing a given goal.
+- An Executor Flow: It is a branching flow that uses the executes the command instructed by the ControllerAtomicFlow.
+
+An illustration of the flow is as follows:
+
+       goal -----|-----> ControllerFlow----->|-----> (anwser,status)
+                 ^                           |
+                 |                           |
+                 |                           v
+                 |<----- ExecutorFlow <------|
+
+*Configuration Parameters*:
+
+- `name` (str): The name of the flow. Default: "CtrlEx"
+- `description` (str): A description of the flow. This description is used to generate the help message of the flow.
+Default: "ControllerExecutor (i.e., MRKL, ReAct) interaction implementation with Flows
+that approaches the problem solving in two phases: one Flow chooses the next step and another Flow executes it.
+This is repeated until the controller Flow concludes on an answer."
+- `max_rounds` (int): The maximum number of rounds the flow can run for. 
+Default: 30.
+- `subflows_config` (Dict[str,Any]): A dictionary of the subflows configurations. Default:
+    - `Controller`: The configuration of the Controller Flow. By default, it a ControllerAtomicFlow. Default parameters:
+        - `finish` (Dict[str,Any]): The configuration of the finish command. Default parameters:
+            - `description` (str): The description of the command.
+            Default: "Signal that the objective has been satisfied, and returns the answer to the user."
+            - `input_args` (List[str]): The input arguments of the command. Default: ["answer"]
+        -  All other parameters are inherited from the default configuration of ControllerAtomicFlow (see ControllerAtomicFlow)
+    - `Executor`: The configuration of the Executor Flow. By default, it's a BranchingFlow. There are no default parameters, the flow
+    parameter to to be defined is:
+        - `subflows_config` (Dict[str,Any]): A dictionary of the configuration of the subflows of the branching flow.
+        These subflows are typically also the possible commands of the Controller Flow. Default: []
+- `early_exit_key` (str): The key that is used to exit the flow. Default: "EARLY_EXIT"
+- `topology` (str): The topology of the flow which is "circular". 
+By default, the topology is the one shown in the illustration above
+(the topology is also described in ControllerExecutorFlow.yaml).
+
+
+*Input Interface*:
+
+- `goal` (str): The goal of the controller. Usually asked by the user/human (e.g. "I want to know the occupation and birth date of Michael Jordan.")
+
+*Output Interface*:
+
+- `answer` (str): The answer of the flow to the query (e.g. "Michael Jordan is a basketball player and business man. He was born on February 17, 1963.")
+- `status` (str): The status of the flow. It can be "finished" or "unfinished". If the status is "unfinished", it's usually because the maximum amount of rounds was reached before the model found an answer.
+
+**Arguments**:
+
+- `flow_config`: The configuration of the flow (see Configuration Parameters).
+- `subflows`: A list of subflows. Required when instantiating the subflow programmatically (it replaces subflows_config from flow_config).
+
+<a id="ControllerExecutorFlow.ControllerExecutorFlow.detect_finish_or_continue"></a>
+
+#### detect\_finish\_or\_continue
+
+```python
+@CircularFlow.output_msg_payload_processor
+def detect_finish_or_continue(
+        output_payload: Dict[str, Any],
+        src_flow: ControllerAtomicFlow) -> Dict[str, Any]
+```
+
+This method is called when the ExecutorAtomicFlow receives a message from the ControllerAtomicFlow. It checks if the flow should finish or continue.
+
+**Arguments**:
+
+- `output_payload` (`Dict[str, Any]`): The output payload of the ControllerAtomicFlow.
+- `src_flow` (`ControllerAtomicFlow`): The ControllerAtomicFlow.
+
+**Returns**:
+
+The output payload of the ControllerAtomicFlow.
 
-# ToDo

WikiSearchAtomicFlow.py

@@ -11,6 +11,28 @@ log = logging.get_logger(__name__)
 
 
 class WikiSearchAtomicFlow(AtomicFlow):
+    """ This class implements a WikiSearch Atomic Flow. It's used to execute a Wikipedia search and get page summaries.
+    
+    *Configuration Parameters*:
+    
+    - `name` (str): The name of the flow. Default: "WikiSearchAtomicFlow"
+    - `description` (str): A description of the flow. This description is used to generate the help message of the flow.
+    Default: "A Flow that queries the wikipedia API for a page content."
+    - `lang` (str): The language of the Wikipedia page. Default: "en"
+    - `top_k_results` (int): The number of top results to return. Default: 5
+    - `doc_content_chars_max` (int): The maximum number of characters of the content of the Wikipedia page. Default: 3000
+    - Other parameters are inherited from the default configuration of AtomicFlow (see AtomicFlow)
+    
+    *input_interface*:
+    
+        - `search_term` (str): The search term to search for.
+        
+    *output_interface*:
+    
+        - `wiki_content` (str): The content of the Wikipedia page.
+        
+    :param \**kwargs: The keyword arguments passed to the AtomicFlow constructor
+    """
     REQUIRED_KEYS_CONFIG = ["lang", "top_k_results", "doc_content_chars_max"]
     REQUIRED_KEYS_CONSTRUCTOR = []
 
@@ -23,6 +45,13 @@ class WikiSearchAtomicFlow(AtomicFlow):
 
     def run(self,
             input_data: Dict[str, Any]) -> Dict[str, Any]:
+        """ Runs the WikiSearch Atomic Flow. It's used to execute a Wikipedia search and get page summaries.
+        
+        :param input_data: The input data dictionary
+        :type input_data: Dict[str, Any]
+        :return: The output data dictionary
+        :rtype: Dict[str, Any]
+        """
 
         # ~~~ Process input ~~~
         term = input_data.get("search_term", None)

__init__.py

@@ -1,6 +1,6 @@
 # ~~~ Specify the dependencies ~~~
 dependencies = [
-    {"url": "aiflows/OpenAIChatFlowModule", "revision": "eeec09b71e967ce426553e2300c5689f6ea6a662"},
+    {"url": "aiflows/ChatFlowModule", "revision": "a749ad10ed39776ba6721c37d0dc22af49ca0f17"},
 ]
 from flows import flow_verse
 

demo.yaml

@@ -0,0 +1,27 @@
+flow:
+  _target_: aiflows.ControllerExecutorFlowModule.ControllerExecutorFlow.instantiate_from_default_config
+  max_rounds: 30
+
+  ### Subflows specification
+  subflows_config:
+    Controller:
+      _target_: aiflows.ControllerExecutorFlowModule.ControllerAtomicFlow.instantiate_from_default_config
+      commands:
+        wiki_search:
+          description: "Performs a search on Wikipedia."
+          input_args: [ "search_term" ]
+        finish:
+          description: "Signal that the objective has been satisfied, and returns the answer to the user."
+          input_args: [ "answer" ]
+      backend:
+        _target_: flows.backends.llm_lite.LiteLLMBackend
+        api_infos: ???
+        model_name: 
+          openai: "gpt-3.5-turbo"
+          azure: "azure/gpt-4"
+
+    Executor:
+      _target_: flows.base_flows.BranchingFlow.instantiate_from_default_config
+      subflows_config:
+        wiki_search:
+          _target_: aiflows.ControllerExecutorFlowModule.WikiSearchAtomicFlow.instantiate_from_default_config

pip_requirements.txt

@@ -1 +1 @@
-duckduckgo-search==3.9.2
+wikipedia==1.4.0

run.py

@@ -0,0 +1,77 @@
+import os
+
+import hydra
+
+import flows
+from flows.flow_launchers import FlowLauncher
+from flows.backends.api_info import ApiInfo
+from flows.utils.general_helpers import read_yaml_file
+
+from flows import logging
+from flows.flow_cache import CACHING_PARAMETERS, clear_cache
+
+CACHING_PARAMETERS.do_caching = False  # Set to True in order to disable caching
+# clear_cache() # Uncomment this line to clear the cache
+
+logging.set_verbosity_debug()
+
+dependencies = [
+    {"url": "aiflows/ControllerExecutorFlowModule", "revision": os.getcwd()},
+]
+from flows import flow_verse
+
+flow_verse.sync_dependencies(dependencies)
+
+if __name__ == "__main__":
+    # ~~~ Set the API information ~~~
+    # OpenAI backend
+    api_information = [ApiInfo(backend_used="openai",
+                              api_key = os.getenv("OPENAI_API_KEY"))]
+    # Azure backend
+    # api_information = ApiInfo(backend_used = "azure",
+    #                           api_base = os.getenv("AZURE_API_BASE"),
+    #                           api_key = os.getenv("AZURE_OPENAI_KEY"),
+    #                           api_version =  os.getenv("AZURE_API_VERSION") )
+
+    path_to_output_file = None
+    # path_to_output_file = "output.jsonl"  # Uncomment this line to save the output to disk
+    
+    root_dir = "."
+    cfg_path = os.path.join(root_dir, "demo.yaml")
+    cfg = read_yaml_file(cfg_path)
+    # print(cfg["flow"].keys())
+    cfg["flow"]["subflows_config"]["Controller"]["backend"]["api_infos"] = api_information
+    
+    # ~~~ Instantiate the Flow ~~~
+    flow_with_interfaces = {
+        "flow": hydra.utils.instantiate(cfg['flow'], _recursive_=False, _convert_="partial"),
+        "input_interface": (
+            None
+            if cfg.get( "input_interface", None) is None
+            else hydra.utils.instantiate(cfg['input_interface'], _recursive_=False)
+        ),
+        "output_interface": (
+            None
+            if cfg.get( "output_interface", None) is None
+            else hydra.utils.instantiate(cfg['output_interface'], _recursive_=False)
+        ),
+    }
+
+    # ~~~ Get the data ~~~
+    # This can be a list of samples
+    # data = {"id": 0, "goal": "Answer the following question: What is the population of Canada?"}  # Uses wikipedia
+    data = {"id": 0, "goal": "Answer the following question: Who was the NBA champion in 2023?"}
+
+    # ~~~ Run inference ~~~
+    path_to_output_file = None
+    # path_to_output_file = "output.jsonl"  # Uncomment this line to save the output to disk
+
+    _, outputs = FlowLauncher.launch(
+        flow_with_interfaces=flow_with_interfaces,
+        data=data,
+        path_to_output_file=path_to_output_file
+    )
+
+    # ~~~ Print the output ~~~
+    flow_output_data = outputs[0]
+    print(flow_output_data)

wikipediaAPI.py

@@ -17,6 +17,14 @@ class WikipediaAPIWrapper(BaseModel):
     fetch page summaries. By default, it will return the page summaries
     of the top-k results.
     It limits the Document content by doc_content_chars_max.
+    
+    :param top_k_results: The number of results to return.
+    :type top_k_results: int
+    :param lang: The language to use for the Wikipedia API.
+    :type lang: str
+    :param doc_content_chars_max: The maximum number of characters in the Document content.
+    :type doc_content_chars_max: int
+    :wiki_client: The Wikipedia API client.
     """
 
     wiki_client: Any
@@ -26,7 +34,14 @@ class WikipediaAPIWrapper(BaseModel):
 
     @root_validator()
     def validate_environment(cls, values: Dict) -> Dict:
-        """Validate that the python package exists in environment."""
+        """Validate that the python package exists in environment.
+        
+        :param values: The values to validate.
+        :type values: Dict
+        :return: The validated values.
+        :rtype: Dict
+        :raises ImportError: If the package is not installed.
+        """
         try:
             import wikipedia
 
@@ -40,7 +55,13 @@ class WikipediaAPIWrapper(BaseModel):
         return values
 
     def run(self, query: str) -> str:
-        """Run Wikipedia search and get page summaries."""
+        """Run Wikipedia search and get page summaries.
+        
+        :param query: The query to search for.
+        :type query: str
+        :return: The page summaries.
+        :rtype: str
+        """
 
         page_titles = self.search_page_titles(query)
         summaries = []
@@ -53,6 +74,13 @@ class WikipediaAPIWrapper(BaseModel):
         return "\n\n".join(summaries)[: self.doc_content_chars_max]
 
     def _fetch_page(self, page: str) -> Optional[str]:
+        """ Fetch page content from Wikipedia. 
+        
+        :param page: The page to fetch.
+        :type page: str
+        :return: The page content.
+        :rtype: Optional[str]
+        """
         try:
             return self.wiki_client.page(title=page, auto_suggest=False).content[: self.doc_content_chars_max]
         except (
@@ -62,7 +90,13 @@ class WikipediaAPIWrapper(BaseModel):
             return None
 
     def search_page_titles(self, query: str) -> List[str]:
-        """Run Wikipedia search and get page summaries."""
+        """Run Wikipedia search and get page summaries.
+        
+        :param query: The query to search for.
+        :type query: str
+        :return: The page titles.
+        :rtype: List[str]
+        """
 
         return self.wiki_client.search(query[:WIKIPEDIA_MAX_QUERY_LENGTH])[:self.top_k_results]
 
@@ -98,6 +132,15 @@ class WikipediaAPIWrapper(BaseModel):
 
     @staticmethod
     def _formatted_page_summary(page_title: str, wiki_page: Any) -> Optional[str]:
+        """ Format the page and summary in a single string. 
+        
+        :param page_title: The page title.
+        :type page_title: str
+        :param wiki_page: The Wikipedia page.
+        :type wiki_page: Any
+        :return: The formatted page summary.
+        :rtype: Optional[str]
+        """
         return f"Page: {page_title}\nSummary: {wiki_page.summary}"
 
     # def load(self, query: str) -> List[Document]: