Upload README.md

README.md

@@ -1,3 +1,157 @@
----
-license: mit
----
+# Table of Contents
+
+* [AbstractBossFlow](#AbstractBossFlow)
+  * [AbstractBossFlow](#AbstractBossFlow.AbstractBossFlow)
+    * [instantiate\_from\_config](#AbstractBossFlow.AbstractBossFlow.instantiate_from_config)
+    * [run](#AbstractBossFlow.AbstractBossFlow.run)
+* [CtrlExMemFlow](#CtrlExMemFlow)
+  * [CtrlExMemFlow](#CtrlExMemFlow.CtrlExMemFlow)
+    * [detect\_finish\_or\_continue](#CtrlExMemFlow.CtrlExMemFlow.detect_finish_or_continue)
+* [\_\_init\_\_](#__init__)
+
+<a id="AbstractBossFlow"></a>
+
+# AbstractBossFlow
+
+<a id="AbstractBossFlow.AbstractBossFlow"></a>
+
+## AbstractBossFlow Objects
+
+```python
+class AbstractBossFlow(SequentialFlow, ABC)
+```
+
+This class is an abstraction of memory-planner-controller-executor flow. At a higher level, it is
+
+an abstract agent empowered by multiple language models and subsequent tools like code interpreters, etc.
+It is designed to cooperate with memory management mechanisms, lm-powered planner and controller, and
+arbitrary executors.
+
+*Configuration Parameters*
+
+- `name` (str): Name of the flow.
+- `description` (str): Description of the flow.
+- `memory_files` (dict): A dictionary of memory files. The keys are the names of the memory files and the values
+    are the path to the memory files. Typical memory files include plan, logs, code library.
+- `subflows_config`:
+    - MemoryReading: reads the content of the memory files into the flow states for later use.
+    - Planner: make a step-by-step plan based on the current goal.
+    - CtrlExMem: controller-executor agent with memory reading and memory writing, it will execute the plan generated by the planner.
+- `early_exit_key` (str): The key in the flow state that indicates the early exit condition.
+- `topology` (list) : The topology of the flow.
+
+*Input Interface (expected input)*
+
+- `goal` (str): The goal from the caller (source flow)
+
+*Output Interface (expected output)*
+
+- `result` (str): The result of the flow, the result will be returned to the caller.
+- `summary` (str): The summary of the flow, the summary will be logged into the logs of the caller flow.
+
+**Arguments**:
+
+- `memory_files` (`dict`): A dictionary of memory files. The keys are the names of the memory files and the values are the path to the memory files.
+
+<a id="AbstractBossFlow.AbstractBossFlow.instantiate_from_config"></a>
+
+#### instantiate\_from\_config
+
+```python
+@classmethod
+def instantiate_from_config(cls, config)
+```
+
+This method instantiates the flow from a configuration dictionary.
+
+**Arguments**:
+
+- `config` (`dict`): The configuration dictionary.
+
+<a id="AbstractBossFlow.AbstractBossFlow.run"></a>
+
+#### run
+
+```python
+def run(input_data: Dict[str, Any]) -> Dict[str, Any]
+```
+
+This method runs the flow.
+
+**Arguments**:
+
+- `input_data` (`dict`): The input data, the input_data is supposed to contain 'goal'
+
+<a id="CtrlExMemFlow"></a>
+
+# CtrlExMemFlow
+
+<a id="CtrlExMemFlow.CtrlExMemFlow"></a>
+
+## CtrlExMemFlow Objects
+
+```python
+class CtrlExMemFlow(CircularFlow, ABC)
+```
+
+This class is the controller-executor agent with memory reading and memory writing, it will execute the plan
+generated by the planner. This flow is, at a higher level, a circular flow, it runs until either max_round is
+reached, or the controller decides to early exit (see: detect_finish_or_continue)
+
+The brain of the flow is the controller, the controller decides what action (which branch of the branching flow)
+to take next. The controller can also decide to early exit the flow, in which case the flow will stop. After the
+controller decides what action to take, the controller will pass the action to the executor, the executor will
+execute the action, yielding `result` and `summary`, which respectively will be passed to the controller and the
+memory writer (into logs of the upper layer of flow). Depending on the `result`, the controller will decide what
+action to take next.
+
+*Configuration Parameters*:
+- `name` (str): Name of the flow.
+- `description` (str): Description of the flow.
+- `max_round` (int): The maximum number of rounds the flow will run. Default: 30.
+- `subflows_config` (dict): The configuration of the subflows.
+    - `Controller` (dict): The configuration of the controller. It is important that the target of the controller (instance customizable by the user) and the api information should be specified.
+    - `Executor` (dict): The executor of the flow, it is supposed to be a branching flow. To instantiate the executor, the user needs to specify the subflows of the executor (i.e. the actual tools that can be used by the agent, e.g. a flow for interpreting code)
+    - `MemoryWriting` (dict): The configuration of the memory writer. There is an existing memory writing flow implemented.
+    - 'MemoryReading' (dict): The configuration of the memory reader. There is an existing memory reading flow implemented.
+- `topology` (List): The topology of the subflows, notice that the output interface of the Controller must be implemented and specified.
+
+*Input Interface*:
+- `plan` (str): The plan generated by the planner, the CtrlExMem flow should follow the plan.
+- `memory_files` (dict): mem_name - memfile_path pairs, the memory files that the memory reader will read from.
+- `goal` (str): The goal of the flow
+- `logs` (str): Execution history of the flow, contains all actions taken by each subflow of the flow.
+
+*Output Interface*:
+- `result` (str): The result of the flow, will be returned to the controller of the caller flow.
+- `summary` (str): The summary of the flow, will be written to the logs of the caller flow.
+
+<a id="CtrlExMemFlow.CtrlExMemFlow.detect_finish_or_continue"></a>
+
+#### detect\_finish\_or\_continue
+
+```python
+@abstractmethod
+@CircularFlow.output_msg_payload_processor
+def detect_finish_or_continue(output_payload: Dict[str, Any],
+                              src_flow) -> Dict[str, Any]
+```
+
+This function is called after the Controller, it is used to:
+
+1. Check if the Controller decides to early-exit, if so, implement necessary logics for exiting e.g. drafting result and summary, etc.
+2. For other commands called by the controller, implement necessary logics for the flow to continue e.g. providing necessary information to the branching flow.
+
+**Arguments**:
+
+- `output_payload` (`Dict[str, Any]`): The output payload of the Controller.
+- `src_flow` (`Flow`): The source flow of the Controller.
+
+**Returns**:
+
+The input payload of the Executor.
+
+<a id="__init__"></a>
+
+# \_\_init\_\_
+