README.md

# 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\_\_