# `Flow` Documentation

## Overview

The `Flow` class is a Python module designed to facilitate interactions with a language model, particularly one that operates as an autonomous agent. This class is part of a larger framework aimed at creating conversational agents using advanced language models like GPT-3. It enables you to establish a conversational loop with the model, generate responses, collect feedback, and control the flow of the conversation.

In this documentation, you will learn how to use the `Flow` class effectively, its purpose, and how it can be integrated into your projects.

## Purpose

The `Flow` class serves several key purposes:

1. **Conversational Loop**: It establishes a conversational loop with a language model. This means it allows you to interact with the model in a back-and-forth manner, taking turns in the conversation.

2. **Feedback Collection**: The class allows users to provide feedback on the responses generated by the model. This feedback can be valuable for training and improving the model's responses over time.

3. **Stoppable Conversation**: You can define custom stopping conditions for the conversation, allowing you to stop the interaction based on specific criteria. For example, you can stop the conversation if a certain keyword is detected in the responses.

4. **Retry Mechanism**: The class includes a retry mechanism that can be helpful if there are issues generating responses from the model. It attempts to generate a response multiple times before raising an error.

## Class Definition

The `Flow` class has the following constructor:

```python
class Flow:
    def __init__(
        self,
        llm: Any,
        max_loops: int = 5,
        stopping_condition: Optional[Callable[[str], bool]] = None,
        loop_interval: int = 1,
        retry_attempts: int = 3,
        retry_interval: int = 1,
        interactive: bool = False,
        **kwargs: Any,
    ):
```

### Parameters

- `llm` (Any): The language model with which you want to interact.
- `max_loops` (int): The maximum number of conversation loops. Default is 5.
- `stopping_condition` (Optional[Callable[[str], bool]]): A custom stopping condition function. Default is `None`.
- `loop_interval` (int): The time interval (in seconds) between conversation loops. Default is 1 second.
- `retry_attempts` (int): The number of retry attempts if response generation fails. Default is 3.
- `retry_interval` (int): The time interval (in seconds) between retry attempts. Default is 1 second.
- `interactive` (bool): Set to `True` if the conversation is interactive, meaning the user is involved. Default is `False`.

## Usage

The `Flow` class can be used to create a conversational loop with the language model. Here's how you can use it:

```python
from swarms.structs import Flow

flow = Flow(llm=my_language_model, max_loops=5)

# Define a starting task or message
initial_task = "Hello, can you provide me with some information?"

# Run the conversation loop
final_response = flow.run(initial_task)
```

### Feedback

You can collect feedback during the conversation using the `provide_feedback` method:

```python
flow.provide_feedback("The response was not accurate.")
```

### Stopping Condition

You can define a custom stopping condition using a function. For example, you can stop the conversation if the response contains the word "Stop":

```python
from swarms.structs import Flow

def stop_when_repeats(response: str) -> bool:
    return "Stop" in response.lower()

flow = Flow(llm=my_language_model, max_loops=5, stopping_condition=stop_when_repeats)
```

### Retry Mechanism

If the response generation fails, the class will retry up to the specified number of attempts:

```python
flow = Flow(llm=my_language_model, max_loops=5, retry_attempts=3)
```

## Additional Information

- To save the conversation history to a file, you can use the `save` method.

- To load a previously saved conversation history, you can use the `load` method.

- The class includes methods for bulk running conversations with multiple input sets.

## Examples

Here are three usage examples:

### Example 1: Simple Conversation

```python
from swarms.structs import Flow

flow = Flow(llm=my_language_model, max_loops=5)

# Define a starting task or message
initial_task = "Hello, can you provide me with some information?"

# Run the conversation loop
final_response = flow.run(initial_task)
```

### Example 2: Custom Stopping Condition

```python
from swarms.structs import Flow

def stop_when_repeats(response: str) -> bool:
    return "Stop" in response.lower()

flow = Flow(llm=my_language_model, max_loops=5, stopping_condition=stop_when_repeats)
```

### Example 3: Interactive Conversation

```python
from swarms.structs import Flow

flow = Flow(llm=my_language_model, max_loops=5, interactive=True)

# Provide initial task
initial_task = "Hello, can you tell me a joke?"

# Run the conversation loop
final_response = flow.run(initial_task)
```

## References and Resources

- [GitHub Repository](https://github.com/kyegomez/swarms)

## Conclusion

The `Flow` class provides a powerful way to interact with language models in a conversational manner. By defining custom stopping conditions, collecting feedback, and controlling the flow of the conversation, you can create engaging and interactive applications that make use of advanced language models.