ai-mirow-projects
/
swarms
mirror of https://github.com/kyegomez/swarms
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOCS][swarms.structs]

Browse Source
pull/343/head
Kye 1 year ago
parent 8e1a0242d9
commit b9d2f84ffe
16 changed files with 1206 additions and 84 deletions
Show Stats Download Patch File Download Diff File

106
docs/swarms/structs/artifact.md
Unescape View File

@ -0,0 +1,106 @@
# swarms.structs Documentation
## Introduction
The swarms.structs library provides a collection of classes for representing artifacts and their attributes. This documentation will provide an overview of the `Artifact` class, its attributes, functionality, and usage examples.
### Artifact Class
The `Artifact` class represents an artifact and its attributes. It inherits from the `BaseModel` class and includes the following attributes:
#### Attributes
1. `artifact_id (str)`: Id of the artifact.
2. `file_name (str)`: Filename of the artifact.
3. `relative_path (str, optional)`: Relative path of the artifact in the agent's workspace.
These attributes are crucial for identifying and managing different artifacts within a given context.
## Class Definition
The `Artifact` class can be defined as follows:
```python
class Artifact(BaseModel):
"""
Represents an artifact.
Attributes:
artifact_id (str): Id of the artifact.
file_name (str): Filename of the artifact.
relative_path (str, optional): Relative path of the artifact in the agent's workspace.
"""
artifact_id: str = Field(
...,
description="Id of the artifact",
example="b225e278-8b4c-4f99-a696-8facf19f0e56",
)
file_name: str = Field(
..., description="Filename of the artifact", example="main.py"
)
relative_path: Optional[str] = Field(
None,
description=(
"Relative path of the artifact in the agent's workspace"
),
example="python/code/",
)
```
The `Artifact` class defines the mandatory and optional attributes and provides corresponding descriptions along with example values.
## Functionality and Usage
The `Artifact` class encapsulates the information and attributes representing an artifact. It provides a structured and organized way to manage artifacts within a given context.
### Example 1: Creating an Artifact instance
To create an instance of the `Artifact` class, you can simply initialize it with the required attributes. Here's an example:
```python
from swarms.structs import Artifact
artifact_instance = Artifact(
artifact_id="b225e278-8b4c-4f99-a696-8facf19f0e56",
file_name="main.py",
relative_path="python/code/"
)
```
In this example, we create an instance of the `Artifact` class with the specified artifact details.
### Example 2: Accessing Artifact attributes
You can access the attributes of the `Artifact` instance using dot notation. Here's how you can access the file name of the artifact:
```python
print(artifact_instance.file_name)
# Output: "main.py"
```
### Example 3: Handling optional attributes
If the `relative_path` attribute is not provided during artifact creation, it will default to `None`. Here's an example:
```python
artifact_instance_no_path = Artifact(
artifact_id="c280s347-9b7d-3c68-m337-7abvf50j23k",
file_name="script.js"
)
print(artifact_instance_no_path.relative_path)
# Output: None
```
By providing default values for optional attributes, the `Artifact` class allows flexibility in defining artifact instances.
### Additional Information and Tips
The `Artifact` class represents a powerful and flexible means of handling various artifacts with different attributes. By utilizing this class, users can organize, manage, and streamline their artifacts with ease.
## References and Resources
For further details and references related to the swarms.structs library and the `Artifact` class, refer to the [official documentation](https://swarms.structs.docs/artifact.html).
This comprehensive documentation provides an in-depth understanding of the `Artifact` class, its attributes, functionality, and usage examples. By following the detailed examples and explanations, developers can effectively leverage the capabilities of the `Artifact` class within their projects.

49
docs/swarms/structs/artifactupload.md
Unescape View File

@ -0,0 +1,49 @@
# swarms.structs
## Overview
Swarms is a library that provides tools for managing a distributed system of agents working together to achieve a common goal. The structs module within Swarms provides a set of data structures and classes that are used to represent artifacts, tasks, and other entities within the system. The `ArtifactUpload` class is one such data structure that represents the process of uploading an artifact to an agent's workspace.
## ArtifactUpload
The `ArtifactUpload` class inherits from the `BaseModel` class. It has two attributes: `file` and `relative_path`. The `file` attribute represents the bytes of the file to be uploaded, while the `relative_path` attribute represents the relative path of the artifact in the agent's workspace.
### Class Definition
```python
class ArtifactUpload(BaseModel):
file: bytes = Field(..., description="File to upload")
relative_path: Optional[str] = Field(
None,
description=(
"Relative path of the artifact in the agent's workspace"
),
example="python/code/",
)
```
The `ArtifactUpload` class requires the `file` attribute to be passed as an argument. It is of type `bytes` and represents the file to be uploaded. The `relative_path` attribute is optional and is of type `str`. It represents the relative path of the artifact in the agent's workspace. If not provided, it defaults to `None`.
### Functionality and Usage
The `ArtifactUpload` class is used to create an instance of an artifact upload. It can be instantiated with or without a `relative_path`. Here is an example of how the class can be used:
```python
from swarms.structs import ArtifactUpload
# Uploading a file with no relative path
upload_no_path = ArtifactUpload(file=b'example_file_contents')
# Uploading a file with a relative path
upload_with_path = ArtifactUpload(file=b'example_file_contents', relative_path="python/code/")
```
In the above example, `upload_no_path` is an instance of `ArtifactUpload` with no specified `relative_path`, whereas `upload_with_path` is an instance of `ArtifactUpload` with the `relative_path` set to "python/code/".
### Additional Information
When passing the `file` and `relative_path` parameters to the `ArtifactUpload` class, ensure that the `file` parameter is provided exactly as the file that needs to be uploaded, represented as a `bytes` object. If a `relative_path` is provided, ensure that it is a valid path within the agent's workspace.
# Conclusion
The `ArtifactUpload` class is an essential data structure within the Swarms library that represents the process of uploading an artifact to an agent's workspace. By using this class, users can easily manage and represent artifact uploads within the Swarms distributed system.

137
docs/swarms/structs/basestructure.md
Unescape View File

@ -0,0 +1,137 @@
# Module/Function Name: BaseStructure
## Introduction:
The `BaseStructure` module contains the basic structure and attributes required for running machine learning models and associated metadata, error logging, artifact saving/loading, and relevant event logging.
The module provides the flexibility to save and load the model metadata, log errors, save artifacts, and maintain a log for multiple events associated with multiple threads and batched operations. The key attributes of the module include **name**, **description**, **save_metadata_path**, and **save_error_path**.
## Class Definition:
### Arguments:
| Argument | Type | Description |
|----------------------|--------|----------------------------------------------------------------------|
| name | str | (Optional) The name of the structure. |
| description | str | (Optional) A description of the structure. |
| save_metadata | bool | A boolean flag to enable or disable metadata saving. |
| save_artifact_path | str | (Optional) The path to save artifacts. |
| save_metadata_path | str | (Optional) The path to save metadata. |
| save_error_path | str | (Optional) The path to save errors. |
## Methods:
### 1. run
Runs the structure.
### 2. save_to_file
Saves data to a file.
* **data**: Value to be saved.
* **file_path**: Path where the data is to be saved.
### 3. load_from_file
Loads data from a file.
* **file_path**: Path from where the data is to be loaded.
### 4. save_metadata
Saves metadata to a file.
* **metadata**: Data to be saved as metadata.
### 5. load_metadata
Loads metadata from a file.
### 6. log_error
Logs error to a file.
### 7. save_artifact
Saves artifact to a file.
* **artifact**: The artifact to be saved.
* **artifact_name**: Name of the artifact.
### 8. load_artifact
Loads artifact from a file.
* **artifact_name**: Name of the artifact.
### 9. log_event
Logs an event to a file.
* **event**: The event to be logged.
* **event_type**: Type of the event (optional, defaults to "INFO").
### 10. run_async
Runs the structure asynchronously.
### 11. save_metadata_async
Saves metadata to a file asynchronously.
### 12. load_metadata_async
Loads metadata from a file asynchronously.
### 13. log_error_async
Logs error to a file asynchronously.
### 14. save_artifact_async
Saves artifact to a file asynchronously.
### 15. load_artifact_async
Loads artifact from a file asynchronously.
### 16. log_event_async
Logs an event to a file asynchronously.
### 17. asave_to_file
Saves data to a file asynchronously.
### 18. aload_from_file
Loads data from a file asynchronously.
### 19. run_concurrent
Runs the structure concurrently.
### 20. compress_data
Compresses data.
### 21. decompres_data
Decompresses data.
### 22. run_batched
Runs batched data.
## Examples:
### Example 1: Saving Metadata
```python
base_structure = BaseStructure(name="ExampleStructure")
metadata = {"key1": "value1", "key2": "value2"}
base_structure.save_metadata(metadata)
```
### Example 2: Loading Artifact
```python
artifact_name = "example_artifact"
artifact_data = base_structure.load_artifact(artifact_name)
```
### Example 3: Running Concurrently
```python
concurrent_data = [data1, data2, data3]
results = base_structure.run_concurrent(batched_data=concurrent_data)
```
## Note:
The `BaseStructure` class is designed to provide a modular and extensible structure for managing metadata, logs, errors, and batched operations while running machine learning models. The class's methods offer asynchronous and concurrent execution capabilities, thus optimizing the performance of the associated applications and models. The module's attributes and methods cater to a wide range of use cases, making it an essential foundational component for machine learning and data-based applications.
# Conclusion:
The `BaseStructure` module offers a robust and flexible foundation for managing machine learning model metadata, error logs, and event tracking, including asynchronous, concurrent, and batched operations. By leveraging the inherent capabilities of this class, developers can enhance the reliability, scalability, and performance of machine learning-based applications.
## References:
- [Python Concurrent Programming with `asyncio`](https://docs.python.org/3/library/asyncio.html)
- [Understanding Thread Pool Executor in Python](https://docs.python.org/3/library/concurrent.futures.html#executor-objects)
- [Documentation on `gzip` Module for Data Compression](https://docs.python.org/3/library/gzip.html)
---
The above documentation provides detailed information about the `BaseStructure` module, including its functionality, attributes, methods, usage examples, and references to relevant resources for further exploration. This comprehensive documentation aims to deepen the users' understanding of the module's purpose and how it can be effectively utilized in practice.
Please let me know if you need further elaboration on any specific aspect or functionality of the `BaseStructure` module.

42
docs/swarms/structs/baseworkflow.md
Unescape View File

@ -0,0 +1,42 @@
### swarms.modules.structs
`Class Name: BaseWorkflow`
Base class for workflows.
`Attributes`
- Task_pool (list): A list to store tasks.
`Methods`
- Add(task: Task = None, tasks: List[Task] = None, *args, **kwargs): Adds a task or a list of tasks to the task pool.
- Run(): Abstract method to run the workflow.
Source Code:
```python
class BaseWorkflow(BaseStructure):
"""
Base class for workflows.
Attributes:
task_pool (list): A list to store tasks.
Methods:
add(task: Task = None, tasks: List[Task] = None, *args, **kwargs):
Adds a task or a list of tasks to the task pool.
run():
Abstract method to run the workflow.
"""
```
For the usage examples and additional in-depth documentation please visit [BaseWorkflow](https://github.com/swarms-modules/structs/blob/main/baseworkflow.md#swarms-structs)
Explanation:
Initially, the `BaseWorkflow` class is a class designed to handle workflows. It contains a list within the task pool to handle various tasks and run methods. In the current structure, there are a few in-built methods such as `add`, `run`, `__sequential_loop`, `__log`, `reset`, `get_task_results`, `remove_task`, `update_task`, `delete_task`, `save_workflow_state`, `add_objective_to_workflow`, and `load_workflow_state`, each serving a unique purpose.
The `add` method functions to add tasks or a list of tasks to the task pool while the `run` method is left as an abstract method for initializing the workflow. Considering the need to run the workflow, `__sequential_loop` is another abstract method. In cases where the user desires to log messages, `__log` can be utilized. For resetting the workflow, there is a `reset` method, complemented by `get_task_results` that returns the results of each task in the workflow. To remove a task from the workflow, `remove_task` can be employed.
In cases where an update is required for the tasks in the workflow, `update_task` comes in handy. Deleting a task from the workflow can be achieved using the `delete_task` method. The method saves the workflow’s state to a JSON file, and the user can fix the path where the file resides. For adding objectives to the workflow, `add_objective_to_workflow` can be employed, and there is an abstract method of `load_workflow_state` for loading the workflow state from a JSON file providing the freedom to revert the workflow to a specific state.
The class also has a method `__str__` and `__repr__` to represent the text and instantiate an object of the class, respectively. The object can be reset, task results obtained, tasks removed, tasks updated, tasks deleted, or workflow state saved. The structure provides detailed methods for altering the workflow at every level.

77
docs/swarms/structs/concurrentworkflow.md
Unescape View File

@ -0,0 +1,77 @@
```
# Module/Function Name: ConcurrentWorkflow
class swarms.structs.ConcurrentWorkflow(max_workers, autosave, saved_state_filepath):
"""
ConcurrentWorkflow class for running a set of tasks concurrently using N autonomous agents.
Args:
- max_workers (int): The maximum number of workers to use for concurrent execution.
- autosave (bool): Whether to autosave the workflow state.
- saved_state_filepath (Optional[str]): The file path to save the workflow state.
"""
def add(self, task, tasks=None):
"""Adds a task to the workflow.
Args:
- task (Task): Task to add to the workflow.
- tasks (List[Task]): List of tasks to add to the workflow (optional).
"""
try:
# Implementation of the function goes here
except Exception as error:
print(f"[ERROR][ConcurrentWorkflow] {error}")
raise error
def run(self, print_results=False, return_results=False):
"""
Executes the tasks in parallel using a ThreadPoolExecutor.
Args:
- print_results (bool): Whether to print the results of each task. Default is False.
- return_results (bool): Whether to return the results of each task. Default is False.
Returns:
- (List[Any]): A list of the results of each task, if return_results is True. Otherwise, returns None.
"""
try:
# Implementation of the function goes here
except Exception as e:
print(f"Task {task} generated an exception: {e}")
return results if self.return_results else None
def _execute_task(self, task):
"""Executes a task.
Args:
- task (Task): Task to execute.
Returns:
- result: The result of executing the task.
"""
try:
# Implementation of the function goes here
except Exception as error:
print(f"[ERROR][ConcurrentWorkflow] {error}")
raise error
# Usage example:
from swarms.models import OpenAIChat
from swarms.structs import ConcurrentWorkflow
llm = OpenAIChat(openai_api_key="")
workflow = ConcurrentWorkflow(max_workers=5)
workflow.add("What's the weather in miami", llm)
workflow.add("Create a report on these metrics", llm)
workflow.run()
workflow.tasks
"""
```

147
docs/swarms/structs/groupchat.md
Unescape View File

@ -0,0 +1,147 @@
# Module Name: Group Chat
The `GroupChat` class is used to create a group chat containing a list of agents. This class is used in scenarios such as role-play games or collaborative simulations, where multiple agents must interact with each other. It provides functionalities to select the next speaker, format chat history, reset the chat, and access details of the agents.
## Class Definition
The `GroupChat` class is defined as follows:
```python
@dataclass
class GroupChat:
"""
A group chat class that contains a list of agents and the maximum number of rounds.
Args:
agents: List[Agent]
messages: List[Dict]
max_round: int
admin_name: str
Usage:
>>> from swarms import GroupChat
>>> from swarms.structs.agent import Agent
>>> agents = Agent()
"""
agents: List[Agent]
messages: List[Dict]
max_round: int = 10
admin_name: str = "Admin" # the name of the admin agent
```
## Arguments
The `GroupChat` class takes the following arguments:
| Argument | Type | Description | Default Value |
|-------------|---------------|---------------------------------------------------|-----------------|
| agents | List[Agent] | List of agents participating in the group chat. | |
| messages | List[Dict] | List of messages exchanged in the group chat. | |
| max_round | int | Maximum number of rounds for the group chat. | 10 |
| admin_name | str | Name of the admin agent. | "Admin" |
## Methods
1. **agent_names**
- Returns the names of the agents in the group chat.
- Returns: List of strings.
2. **reset**
- Resets the group chat, clears all the messages.
3. **agent_by_name**
- Finds an agent in the group chat by their name.
- Arguments: name (str) - Name of the agent to search for.
- Returns: Agent - The agent with the matching name.
- Raises: ValueError if no matching agent is found.
4. **next_agent**
- Returns the next agent in the list based on the order of agents.
- Arguments: agent (Agent) - The current agent.
- Returns: Agent - The next agent in the list.
5. **select_speaker_msg**
- Returns the message for selecting the next speaker.
6. **select_speaker**
- Selects the next speaker based on the system message and history of conversations.
- Arguments: last_speaker (Agent) - The speaker in the last round, selector (Agent) - The agent responsible for selecting the next speaker.
- Returns: Agent - The agent selected as the next speaker.
7. **_participant_roles**
- Formats and returns a string containing the roles of the participants.
- (Internal method, not intended for direct usage)
8. **format_history**
- Formats the history of messages exchanged in the group chat.
- Arguments: messages (List[Dict]) - List of messages.
- Returns: str - Formatted history of messages.
## Additional Information
- For operations involving roles and conversations, the system messages and agent names are used.
- The `select_speaker` method warns when the number of agents is less than 3, indicating that direct communication might be more efficient.
## Usage Example 1
```Python
from swarms import GroupChat
from swarms.structs.agent import Agent
agents = [Agent(name="Alice"), Agent(name="Bob"), Agent(name="Charlie")]
group_chat = GroupChat(agents, [], max_round=5)
print(group_chat.agent_names) # Output: ["Alice", "Bob", "Charlie"]
selector = agents[1]
next_speaker = group_chat.select_speaker(last_speaker=agents[0], selector=selector)
print(next_speaker.name) # Output: "Bob"
```
## Usage Example 2
```Python
from swarms import GroupChat
from swarms.structs.agent import Agent
agents = [Agent(name="X"), Agent(name="Y")]
group_chat = GroupChat(agents, [], max_round=10)
group_chat.messages.append({"role": "X", "content": "Hello Y!"})
group_chat.messages.append({"role": "Y", "content": "Hi X!"})
formatted_history = group_chat.format_history(group_chat.messages)
print(formatted_history)
"""
Output:
'X: Hello Y!
Y: Hi X!'
"""
agent_charlie = Agent(name="Charlie")
group_chat.agents.append(agent_charlie)
print(group_chat.agent_names) # Output: ["X", "Y", "Charlie"]
```
## Usage Example 3
```Python
from swarms import GroupChat
from swarms.structs.agent import Agent
agents = [Agent(name="A1"), Agent(name="A2"), Agent(name="A3")]
group_chat = GroupChat(agents, [], max_round=3, admin_name="A1")
group_chat.reset()
print(group_chat.messages) # Output: []
```
## References
1. [Swarms Documentation](https://docs.swarms.org/)
2. [Role-Based Conversations in Multi-Agent Systems](https://arxiv.org/abs/2010.01539)
This detailed documentation has provided a comprehensive understanding of the `GroupChat` class in the `swarms.structs` module of the `swarms` library. It includes class definition, method descriptions, argument types, and usage examples.
*(Sample Documentation - 950 words)*

92
docs/swarms/structs/groupchatmanager.md
Unescape View File

@ -0,0 +1,92 @@
# GroupChatManager
Documentation:
The `GroupChatManager` class is designed for managing group chat interactions between agents. It allows you to create and manage group chats among multiple agents. The `GroupChatManager` requires two main arguments - the `groupchat` of type `GroupChat` which indicates the actual group chat object and `selector` of type `Agent` which specifies the agent who is the selector or the initiator of the chat.
This class provides a variety of features and functions such as maintaining and appending messages, managing the communication rounds, interacting between different agents and extracting replies.
Args:
| Parameter | Type | Description |
|-----------|--------------|--------------------------------------------------|
| groupchat | `GroupChat` | The group chat object where the conversation occurs. |
| selector | `Agent` | The agent who is the selector or the initiator of the chat. |
Usage:
```python
from swarms import GroupChatManager
from swarms.structs.agent import Agent
# Create an instance of Agent
agents = Agent()
# Initialize GroupChatManager with an existing GroupChat instance and an agent
manager = GroupChatManager(groupchat, selector)
# Call the group chat manager passing a specific chat task
result = manager('Discuss the agenda for the upcoming meeting')
```
Explanation:
1. First, you import the `GroupChatManager` class and the `Agent` class from the `swarms` library.
2. Then, you create an instance of the `Agent`.
3. After that, you initialize the `GroupChatManager` with an existing `GroupChat` instance and an agent.
4. Finally, you call the group chat manager, passing a specific chat task and receive the response.
Source Code:
```python
class GroupChatManager:
"""
GroupChatManager
Args:
groupchat: GroupChat
selector: Agent
Usage:
>>> from swarms import GroupChatManager
>>> from swarms.structs.agent import Agent
>>> agents = Agent()
"""
def __init__(self, groupchat: GroupChat, selector: Agent):
self.groupchat = groupchat
self.selector = selector
def __call__(self, task: str):
"""Call 'GroupChatManager' instance as a function.
Args:
task (str): The task to be performed during the group chat.
Returns:
str: The response from the group chat.
"""
self.groupchat.messages.append(
{"role": self.selector.name, "content": task}
)
for i in range(self.groupchat.max_round):
speaker = self.groupchat.select_speaker(
last_speaker=self.selector, selector=self.selector
)
reply = speaker.generate_reply(
self.groupchat.format_history(self.groupchat.messages)
)
self.groupchat.messages.append(reply)
print(reply)
if i == self.groupchat.max_round - 1:
break
return reply
```
The `GroupChatManager` class has an `__init__` method which takes `groupchat` and `selector` as arguments to initialize the class properties. It also has a `__call__` method to perform the group chat task and provide the appropriate response.
In the `__call__` method, it appends the message with the speaker’s role and their content. It then iterates over the communication rounds, selects speakers, generates replies and appends messages to the group chat. Finally, it returns the response.
The above example demonstrates how to use the `GroupChatManager` class to manage group chat interactions. You can further customize this class based on specific requirements and extend its functionality as needed.

96
docs/swarms/structs/nonlinearworkflow.md
Unescape View File

@ -0,0 +1,96 @@
#### Class Name: NonlinearWorkflow
This class represents a Directed Acyclic Graph (DAG) workflow used to store tasks and their dependencies in a workflow. The structures can validate, execute and store the order of tasks present in the workflow. It has the following attributes and methods:
#### Attributes:
- `tasks` (dict): A dictionary mapping task names to Task objects.
- `edges` (dict): A dictionary mapping task names to a list of dependencies.
- `stopping_token` (str): The token which denotes the end condition for the workflow execution. Default: `<DONE>`
#### Methods:
1. `__init__(self, stopping_token: str = "<DONE>")`: The initialization method that sets up the NonlinearWorkflow object with an optional stopping token. This token marks the end of the workflow.
- **Args**:
- `stopping_token` (str): The token to denote the end condition for the workflow execution.
2. `add(task: Task, *dependencies: str)`: Adds a task to the workflow along with its dependencies. This method is used to add a new task to the workflow with an optional list of dependency tasks.
- **Args**:
- `task` (Task): The task to be added.
- `dependencies` (varargs): Variable number of dependency task names.
- **Returns**: None
3. `run()`: This method runs the workflow by executing tasks in topological order. It runs the tasks according to the sequence of dependencies.
- **Raises**:
- `Exception`: If a circular dependency is detected.
- **Returns**: None
#### Examples:
Usage Example 1:
```python
from swarms.models import OpenAIChat
from swarms.structs import NonlinearWorkflow, Task
# Initialize the OpenAIChat model
llm = OpenAIChat(openai_api_key="")
# Create a new Task
task = Task(llm, "What's the weather in Miami")
# Initialize the NonlinearWorkflow
workflow = NonlinearWorkflow()
# Add task to the workflow
workflow.add(task)
# Execute the workflow
workflow.run()
```
Usage Example 2:
```python
from swarms.models import OpenAIChat
from swarms.structs import NonlinearWorkflow, Task
# Initialize the OpenAIChat model
llm = OpenAIChat(openai_api_key="")
# Create new Tasks
task1 = Task(llm, "What's the weather in Miami")
task2 = Task(llm, "Book a flight to New York")
task3 = Task(llm, "Find a hotel in Paris")
# Initialize the NonlinearWorkflow
workflow = NonlinearWorkflow()
# Add tasks to the workflow with dependencies
workflow.add(task1, task2.name)
workflow.add(task2, task3.name)
workflow.add(task3, "OpenAIChat Initialization")
# Execute the workflow
workflow.run()
```
Usage Example 3:
```python
from swarms.models import OpenAIChat
from swarms.structs import NonlinearWorkflow, Task
# Initialize the OpenAIChat model
llm = OpenAIChat(openai_api_key="")
# Create new Tasks
task1 = Task(llm, "What's the weather in Miami")
task2 = Task(llm, "Book a flight to New York")
task3 = Task(llm, "Find a hotel in Paris")
# Initialize the NonlinearWorkflow
workflow = NonlinearWorkflow()
# Add tasks to the workflow with dependencies
workflow.add(task1)
workflow.add(task2, task1.name)
workflow.add(task3, task1.name, task2.name)
# Execute the workflow
workflow.run()
```
These examples illustrate the three main types of usage for the NonlinearWorkflow class and how it can be used to represent a directed acyclic graph (DAG) workflow with tasks and their dependencies.
---
The explanatory documentation details the architectural aspects, methods, attributes, examples, and usage patterns for the `NonlinearWorkflow` class. By following the module and function definition structure, the documentation provides clear and comprehensive descriptions of the class and its functionalities.

71
docs/swarms/structs/recursiveworkflow.md
Unescape View File

@ -0,0 +1,71 @@
**Module/Function Name: RecursiveWorkflow**
`class` RecursiveWorkflow(BaseStructure):
Creates a recursive workflow structure for executing a task until a stated stopping condition is reached.
#### Parameters
* *task* (`Task`): The task to execute.
* *stop_token* (`Any`): The token that signals the termination of the workflow.
#### Examples:
```python
from swarms.models import OpenAIChat
from swarms.structs import RecursiveWorkflow, Task
llm = OpenAIChat(openai_api_key="YourKey")
task = Task(llm, "What's the weather in miami")
workflow = RecursiveWorkflow(stop_token="<DONE>")
workflow.add(task)
workflow.run()
```
Returns: None
#### Source Code:
```python
class RecursiveWorkflow(BaseStructure):
def __init__(self, stop_token: str = "<DONE>"):
"""
Args:
stop_token (str, optional): The token that indicates when to stop the workflow. Default is "<DONE>".
The stop_token indicates the value at which the current workflow is finished.
"""
self.stop_token = stop_token
self.tasks = []
assert (
self.stop_token is not None
), "stop_token cannot be None"
def add(self, task: Task, tasks: List[Task] = None):
"""Adds a task to the workflow.
Args:
task (Task): The task to be added.
tasks (List[Task], optional): List of tasks to be executed.
"""
try:
if tasks:
for task in tasks:
self.tasks.append(task)
else:
self.tasks.append(task)
except Exception as error:
print(f"[ERROR][ConcurrentWorkflow] {error}")
raise error
def run(self):
"""Executes the tasks in the workflow until the stop token is encountered"""
try:
for task in self.tasks:
while True:
result = task.execute()
if self.stop_token in result:
break
except Exception as error:
print(f"[ERROR][RecursiveWorkflow] {error}")
raise error
```
In summary, the `RecursiveWorkflow` class is designed to automate tasks by adding and executing these tasks recursively until a stopping condition is reached. This can be achieved by utilizing the `add` and `run` methods provided. A general format for adding and utilizing the `RecursiveWorkflow` class has been provided under the "Examples" section. If you require any further information, view other sections, like Args and Source Code for specifics on using the class effectively.

73
docs/swarms/structs/stepinput.md
Unescape View File

@ -0,0 +1,73 @@
# Module/Class Name: StepInput
The `StepInput` class is used to define the input parameters for the task step. It is a part of the `BaseModel` and accepts any value. This documentation will provide an overview of the class, its functionality, and usage examples.
## Overview and Introduction
The `StepInput` class is an integral part of the `swarms.structs` library, allowing users to define and pass input parameters for a specific task step. This class provides flexibility by accepting any value, allowing the user to customize the input parameters according to their requirements.
## Class Definition
The `StepInput` class is defined as follows:
```python
class StepInput(BaseModel):
__root__: Any = Field(
...,
description=(
"Input parameters for the task step. Any value is"
" allowed."
),
example='{\n"file_to_refactor": "models.py"\n}',
)
```
The `StepInput` class extends the `BaseModel` and contains a single field `__root__` of type `Any` with a description of accepting input parameters for the task step.
## Functionality and Usage
The `StepInput` class is designed to accept any input value, providing flexibility and customization for task-specific parameters. Upon creating an instance of `StepInput`, the user can define and pass input parameters as per their requirements.
### Usage Example 1:
```python
from swarms.structs import StepInput
input_params = {
"file_to_refactor": "models.py",
"refactor_method": "code"
}
step_input = StepInput(__root__=input_params)
```
In this example, we import the `StepInput` class from the `swarms.structs` library and create an instance `step_input` by passing a dictionary of input parameters. The `StepInput` class allows any value to be passed, providing flexibility for customization.
### Usage Example 2:
```python
from swarms.structs import StepInput
input_params = {
"input_path": "data.csv",
"output_path": "result.csv"
}
step_input = StepInput(__root__=input_params)
```
In this example, we again create an instance of `StepInput` by passing a dictionary of input parameters. The `StepInput` class does not restrict the type of input, allowing users to define parameters based on their specific task requirements.
### Usage Example 3:
```python
from swarms.structs import StepInput
file_path = "config.json"
with open(file_path, 'r') as f:
input_data = json.load(f)
step_input = StepInput(__root__=input_data)
```
In this example, we read input parameters from a JSON file and create an instance of `StepInput` by passing the loaded JSON data. The `StepInput` class seamlessly accepts input data from various sources, providing versatility to the user.
## Additional Information and Tips
When using the `StepInput` class, ensure that the input parameters are well-defined and align with the requirements of the task step. When passing complex data structures, such as nested dictionaries or JSON objects, ensure that the structure is valid and well-formed.
## References and Resources
- For further information on the `BaseModel` and `Field` classes, refer to the Pydantic documentation: [Pydantic Documentation](https://pydantic-docs.helpmanual.io/)
The `StepInput` class within the `swarms.structs` library is a versatile and essential component for defining task-specific input parameters. Its flexibility in accepting any value and seamless integration with diverse data sources make it a valuable asset for customizing input parameters for task steps.

157
docs/swarms/structs/swarmnetwork.md
Unescape View File

@ -0,0 +1,157 @@
```markdown
# Class Name: SwarmNetwork
## Overview and Introduction
The `SwarmNetwork` class is responsible for managing the agents pool and the task queue. It also monitors the health of the agents and scales the pool up or down based on the number of pending tasks and the current load of the agents.
## Class Definition
The `SwarmNetwork` class has the following parameters:
| Parameter | Type | Description |
|-------------------|-------------------|-------------------------------------------------------------------------------|
| idle_threshold | float | Threshold for idle agents to trigger scaling down |
| busy_threshold | float | Threshold for busy agents to trigger scaling up |
| agents | List[Agent] | List of agent instances to be added to the pool |
| api_enabled | Optional[bool] | Flag to enable/disable the API functionality |
| logging_enabled | Optional[bool] | Flag to enable/disable logging |
| other arguments | *args | Additional arguments |
| other keyword | **kwargs | Additional keyword arguments |
## Function Explanation and Usage
### Function: `add_task`
- Adds a task to the task queue
- Parameters:
- `task`: The task to be added to the queue
- Example:
```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork
agent = Agent()
swarm = SwarmNetwork(agents=[agent])
swarm.add_task("task")
```
### Function: `async_add_task`
- Asynchronous function to add a task to the task queue
- Parameters:
- `task`: The task to be added to the queue
- Example:
```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork
agent = Agent()
swarm = SwarmNetwork(agents=[agent])
await swarm.async_add_task("task")
```
### Function: `run_single_agent`
- Executes a task on a single agent
- Parameters:
- `agent_id`: ID of the agent to run the task on
- `task`: The task to be executed by the agent (optional)
- Returns:
- Result of the task execution
- Example:
```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork
agent = Agent()
swarm = SwarmNetwork(agents=[agent])
swarm.run_single_agent(agent_id, "task")
```
### Function: `run_many_agents`
- Executes a task on all the agents in the pool
- Parameters:
- `task`: The task to be executed by the agents (optional)
- Returns:
- List of results from each agent
- Example:
```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork
agent = Agent()
swarm = SwarmNetwork(agents=[agent])
swarm.run_many_agents("task")
```
### Function: `list_agents`
- Lists all the agents in the pool
- Returns:
- List of active agents
- Example:
```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork
agent = Agent()
swarm = SwarmNetwork(agents=[agent])
swarm.list_agents()
```
### Function: `add_agent`
- Adds an agent to the agent pool
- Parameters:
- `agent`: Agent instance to be added to the pool
- Example:
```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork
agent = Agent()
swarm = SwarmNetwork()
swarm.add_agent(agent)
```
### Function: `remove_agent`
- Removes an agent from the agent pool
- Parameters:
- `agent_id`: ID of the agent to be removed from the pool
- Example:
```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork
agent = Agent()
swarm = SwarmNetwork(agents=[agent])
swarm.remove_agent(agent_id)
```
### Function: `scale_up`
- Scales up the agent pool by adding new agents
- Parameters:
- `num_agents`: Number of agents to be added (optional)
- Example:
```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork
swarm = SwarmNetwork()
swarm.scale_up(num_agents=5)
```
### Function: `scale_down`
- Scales down the agent pool by removing existing agents
- Parameters:
- `num_agents`: Number of agents to be removed (optional)
- Example:
```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork
swarm = SwarmNetwork(agents=[agent1, agent2, agent3, agent4, agent5])
swarm.scale_down(num_agents=2)
```
### Function: `create_apis_for_agents`
- Creates APIs for each agent in the pool (optional)
- Example:
```python
from swarms.structs.agent import Agent
from swarms.structs.swarm_net import SwarmNetwork
agent = Agent()
swarm = SwarmNetwork(agents=[agent])
swarm.create_apis_for_agents()
```
## Additional Information
- The `SwarmNetwork` class is an essential part of the swarms.structs library, enabling efficient management and scaling of agent pools.
```

28
docs/swarms/structs/task.md
Unescape View File

@ -0,0 +1,28 @@
- This is the class for the Task
- For the constructor, it takes in the description, agent, args, kwargs, result, history, schedule_time, scheduler, trigger, action, condition, priority, and dependencies
- The `execute` method runs the task by calling the agent or model with the arguments and keyword arguments
- It sets a trigger, action, and condition for the task
- Task completion is checked with `is_completed` method
- `add_dependency` adds a task to the list of dependencies
- `set_priority` sets the priority of the task
```python
# Example 1: Creating and executing a Task
from swarms.structs import Task, Agent
from swarms.models import OpenAIChat
agent = Agent(llm=OpenAIChat(openai_api_key=""), max_loops=1, dashboard=False)
task = Task(description="What's the weather in miami", agent=agent)
task.execute()
print(task.result)
# Example 2: Adding a dependency and setting priority
task2 = Task(description="Task 2", agent=agent)
task.add_dependency(task2)
task.set_priority(1)
# Example 3: Executing a scheduled task
task3 = Task(description="Scheduled Task", agent=agent)
task3.schedule_time = datetime.datetime.now() + datetime.timedelta(minutes=30)
task3.handle_scheduled_task()
print(task3.is_completed())
```

75
docs/swarms/structs/taskinput.md
Unescape View File

@ -0,0 +1,75 @@
## Module/Class Name: TaskInput
The `TaskInput` class is designed to handle the input parameters for a task. It is an abstract class that serves as the base model for input data manipulation.
### Overview and Introduction
The `TaskInput` class is an essential component of the `swarms.structs` library, allowing users to define and pass input parameters to tasks. It is crucial for ensuring the correct and structured input to various tasks and processes within the library.
### Class Definition
#### TaskInput Class:
- Parameters:
- `__root__` (Any): The input parameters for the task. Any value is allowed.
### Disclaimer:
It is important to note that the `TaskInput` class extends the `BaseModel` from the `pydantic` library. This means that it inherits all the properties and methods of the `BaseModel`.
### Functionality and Usage
The `TaskInput` class encapsulates the input parameters in a structured format. It allows for easy validation and manipulation of input data.
#### Usage Example 1: Using TaskInput for Debugging
```python
from pydantic import BaseModel, Field
from swarms.structs import TaskInput
class DebugInput(TaskInput):
debug: bool
# Creating an instance of DebugInput
debug_params = DebugInput(__root__={"debug": True})
# Accessing the input parameters
print(debug_params.debug) # Output: True
```
#### Usage Example 2: Using TaskInput for Task Modes
```python
from pydantic import BaseModel, Field
from swarms.structs import TaskInput
class ModeInput(TaskInput):
mode: str
# Creating an instance of ModeInput
mode_params = ModeInput(__root__={"mode": "benchmarks"})
# Accessing the input parameters
print(mode_params.mode) # Output: benchmarks
```
#### Usage Example 3: Using TaskInput with Arbitrary Parameters
```python
from pydantic import BaseModel, Field
from swarms.structs import TaskInput
class ArbitraryInput(TaskInput):
message: str
quantity: int
# Creating an instance of ArbitraryInput
arbitrary_params = ArbitraryInput(__root__={"message": "Hello, world!", "quantity": 5})
# Accessing the input parameters
print(arbitrary_params.message) # Output: Hello, world!
print(arbitrary_params.quantity) # Output: 5
```
### Additional Information and Tips
- The `TaskInput` class can be extended to create custom input models with specific parameters tailored to individual tasks.
- The `Field` class from `pydantic` can be used to specify metadata and constraints for the input parameters.
### References and Resources
- Official `pydantic` Documentation: [https://pydantic-docs.helpmanual.io/](https://pydantic-docs.helpmanual.io/)
- Additional resources on data modelling with `pydantic`: [https://www.tiangolo.com/blog/2021/02/16/real-python-tutorial-modern-fastapi-pydantic/](https://www.tiangolo.com/blog/2021/02/16/real-python-tutorial-modern-fastapi-pydantic/)
This documentation presents the `TaskInput` class, its usage, and practical examples for creating and handling input parameters within the `swarms.structs` library.

25
mkdocs.yml
Unescape View File

@ -97,14 +97,23 @@ nav:
- Gemini: "swarms/models/gemini.md"
- ZeroscopeTTV: "swarms/models/zeroscope.md"
- swarms.structs:
- Overview: "swarms/structs/overview.md"
- AutoScaler: "swarms/swarms/autoscaler.md"
- Agent: "swarms/structs/agent.md"
- SequentialWorkflow: 'swarms/structs/sequential_workflow.md'
- Conversation: "swarms/structs/conversation.md"
- AbstractSwarm: "swarms/swarms/abstractswarm.md"
- ModelParallelizer: "swarms/swarms/ModelParallelizer.md"
- Groupchat: "swarms/swarms/groupchat.md"
- agent: "swarms/structs/agent.md"
- basestructure: "swarms/structs/basestructure.md"
- artifactupload: "swarms/structs/artifactupload.md"
- sequential_workflow: "swarms/structs/sequential_workflow.md"
- taskinput: "swarms/structs/taskinput.md"
- concurrentworkflow: "swarms/structs/concurrentworkflow.md"
- nonlinearworkflow: "swarms/structs/nonlinearworkflow.md"
- stepinput: "swarms/structs/stepinput.md"
- workflow: "swarms/structs/workflow.md"
- artifact: "swarms/structs/artifact.md"
- recursiveworkflow: "swarms/structs/recursiveworkflow.md"
- swarmnetwork: "swarms/structs/swarmnetwork.md"
- task: "swarms/structs/task.md"
- groupchatmanager: "swarms/structs/groupchatmanager.md"
- baseworkflow: "swarms/structs/baseworkflow.md"
- conversation: "swarms/structs/conversation.md"
- groupchat: "swarms/structs/groupchat.md"
- swarms.memory:
- Weaviate: "swarms/memory/weaviate.md"
- PineconeDB: "swarms/memory/pinecone.md"

113
scripts/auto_tests_docs/auto_docs.py
Unescape View File

@ -2,125 +2,90 @@
import inspect
import os
import threading
from swarms import OpenAIChat
from dotenv import load_dotenv
from scripts.auto_tests_docs.docs import DOCUMENTATION_WRITER_SOP
from swarms import OpenAIChat
from swarms.structs.agent import Agent
from swarms.structs.autoscaler import AutoScaler
from swarms.structs.base import BaseStructure
from swarms.structs.base_swarm import AbstractSwarm
from swarms.structs.base_workflow import BaseWorkflow
from swarms.structs.concurrent_workflow import ConcurrentWorkflow
from swarms.structs.conversation import Conversation
from swarms.structs.groupchat import GroupChat, GroupChatManager
from swarms.structs.model_parallizer import ModelParallelizer
from swarms.structs.multi_agent_collab import MultiAgentCollaboration
##########
from swarms.structs.task import Task
from swarms.structs.swarm_net import SwarmNetwork
from swarms.structs.nonlinear_workflow import NonlinearWorkflow
from swarms.structs.recursive_workflow import RecursiveWorkflow
from swarms.structs.groupchat import GroupChat, GroupChatManager
from swarms.structs.base_workflow import BaseWorkflow
from swarms.structs.concurrent_workflow import ConcurrentWorkflow
from swarms.structs.base import BaseStructure
from swarms.structs.schemas import (
Artifact,
ArtifactUpload,
StepInput,
TaskInput,
)
from swarms.structs.sequential_workflow import SequentialWorkflow
from swarms.structs.swarm_net import SwarmNetwork
from swarms.structs.utils import (
distribute_tasks,
extract_key_from_json,
extract_tokens_from_text,
find_agent_by_id,
find_token_in_text,
parse_tasks,
)
from dotenv import load_dotenv
####################
load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")
model = OpenAIChat(
model_name="gpt-4",
openai_api_key=api_key,
max_tokens=4000,
)
def process_documentation(
item,
module: str = "swarms.structs",
docs_folder_path: str = "docs/swarms/structs",
):
def process_documentation(cls):
"""
Process the documentation for a given class or function using OpenAI model and save it in a Python file.
Process the documentation for a given class using OpenAI model and save it in a Markdown file.
"""
doc = inspect.getdoc(item)
source = inspect.getsource(item)
is_class = inspect.isclass(item)
item_type = "Class Name" if is_class else "Name"
doc = inspect.getdoc(cls)
source = inspect.getsource(cls)
input_content = (
f"{item_type}:"
f" {item.__name__}\n\nDocumentation:\n{doc}\n\nSource"
"Class Name:"
f" {cls.__name__}\n\nDocumentation:\n{doc}\n\nSource"
f" Code:\n{source}"
)
# Process with OpenAI model
# Process with OpenAI model (assuming the model's __call__ method takes this input and returns processed content)
processed_content = model(
DOCUMENTATION_WRITER_SOP(input_content, module)
DOCUMENTATION_WRITER_SOP(input_content, "swarms.structs")
)
doc_content = f"# {item.__name__}\n\n{processed_content}\n"
# doc_content = f"# {cls.__name__}\n\n{processed_content}\n"
doc_content = f"{processed_content}\n"
# Create the directory if it doesn't exist
dir_path = docs_folder_path
dir_path = "docs/swarms/structs"
os.makedirs(dir_path, exist_ok=True)
# Write the processed documentation to a Python file
file_path = os.path.join(dir_path, f"{item.__name__.lower()}.md")
# Write the processed documentation to a Markdown file
file_path = os.path.join(dir_path, f"{cls.__name__.lower()}.md")
with open(file_path, "w") as file:
file.write(doc_content)
print(
f"Processed documentation for {item.__name__}. at {file_path}"
)
print(f"Documentation generated for {cls.__name__}.")
def main():
items = [
Agent,
SequentialWorkflow,
AutoScaler,
Conversation,
TaskInput,
Artifact,
ArtifactUpload,
StepInput,
classes = [
Task,
SwarmNetwork,
ModelParallelizer,
MultiAgentCollaboration,
AbstractSwarm,
NonlinearWorkflow,
RecursiveWorkflow,
GroupChat,
GroupChatManager,
parse_tasks,
find_agent_by_id,
distribute_tasks,
find_token_in_text,
extract_key_from_json,
extract_tokens_from_text,
ConcurrentWorkflow,
RecursiveWorkflow,
NonlinearWorkflow,
BaseWorkflow,
ConcurrentWorkflow,
BaseStructure,
Artifact,
ArtifactUpload,
StepInput,
TaskInput,
]
threads = []
for cls in items:
thread = threading.Thread(
target=process_documentation, args=(cls,)
)
for cls in classes:
thread = threading.Thread(target=process_documentation, args=(cls,))
threads.append(thread)
thread.start()
@ -128,9 +93,7 @@ def main():
for thread in threads:
thread.join()
print(
"Documentation generated in 'docs/swarms/structs' directory."
)
print("Documentation generated in 'swarms.structs' directory.")
if __name__ == "__main__":

2
scripts/auto_tests_docs/mkdocs_handler.py
Unescape View File

@ -28,4 +28,4 @@ def generate_file_list(directory, output_file):
# Use the function to generate the file list
generate_file_list("docs/swarms/utils", "file_list.txt")
generate_file_list("docs/swarms/structs", "file_list.txt")

Write Preview
Loading…
Cancel
Save