docs for abstract agent and worker

Former-commit-id: cb80a408a0

docs/swarms/agents/abstract_agent.md

@@ -0,0 +1,90 @@
+`AbsractAgent` Class: A Deep Dive
+========================
+
+The `AbstractAgent` class is a fundamental building block in the design of AI systems. It encapsulates the behavior of an AI entity, allowing it to interact with other agents and perform actions. The class is designed to be flexible and extensible, enabling the creation of agents with diverse behaviors.
+
+## Architecture
+------------
+
+The architecture of the `AbstractAgent` class is centered around three main components: the agent's name, tools, and memory.
+
+-   The `name` is a string that uniquely identifies the agent. This is crucial for communication between agents and for tracking their actions.
+
+-   The `tools` are a list of `Tool` objects that the agent uses to perform its tasks. These could include various AI models, data processing utilities, or any other resources that the agent needs to function. The `tools` method is used to initialize these tools.
+
+-   The `memory` is a `Memory` object that the agent uses to store and retrieve information. This could be used, for example, to remember past actions or to store the state of the environment. The `memory` method is used to initialize the memory.
+
+The `AbstractAgent` class also includes several methods that define the agent's behavior. These methods are designed to be overridden in subclasses to implement specific behaviors.
+
+## Methods
+-------
+
+### `reset`
+
+The `reset` method is used to reset the agent's state. This could involve clearing the agent's memory, resetting its tools, or any other actions necessary to bring the agent back to its initial state. This method is abstract and must be overridden in subclasses.
+
+### `run` and `_arun`
+
+The `run` method is used to execute a task. The task is represented as a string, which could be a command, a query, or any other form of instruction that the agent can interpret. The `_arun` method is the asynchronous version of `run`, allowing tasks to be executed concurrently.
+
+### `chat` and `_achat`
+
+The `chat` method is used for communication between agents. It takes a list of messages as input, where each message is a dictionary. The `_achat` method is the asynchronous version of `chat`, allowing messages to be sent and received concurrently.
+
+### `step` and `_astep`
+
+The `step` method is used to advance the agent's state by one step in response to a message. The `_astep` method is the asynchronous version of `step`, allowing the agent's state to be updated concurrently.
+
+## Usage E#xamples
+--------------
+
+### Example 1: Creating an Agent
+
+```
+from swarms.agents.base import AbtractAgent
+
+agent = Agent(name="Agent1")
+print(agent.name)  # Output: Agent1
+```
+
+
+In this example, we create an instance of `AbstractAgent` named "Agent1" and print its name.
+
+### Example 2: Initializing Tools and Memory
+
+```
+from swarms.agents.base import AbtractAgent
+
+agent = Agent(name="Agent1")
+tools = [Tool1(), Tool2(), Tool3()]
+memory_store = Memory()
+
+agent.tools(tools)
+agent.memory(memory_store)
+```
+
+
+In this example, we initialize the tools and memory of "Agent1". The tools are a list of `Tool` instances, and the memory is a `Memory` instance.
+
+### Example 3: Running an Agent
+
+```
+from swarms.agents.base import AbtractAgent
+
+agent = Agent(name="Agent1")
+task = "Task1"
+
+agent.run(task)
+```
+
+
+In this example, we run "Agent1" with a task named "Task1".
+
+Notes
+-----
+
+-   The `AbstractAgent` class is an abstract class, which means it cannot be instantiated directly. Instead, it should be subclassed, and at least the `reset`, `run`, `chat`, and `step` methods should be overridden.
+-   The `run`, `chat`, and `step` methods are designed to be flexible and can be adapted to a wide range of tasks and behaviors. For example, the `run` method could be used to execute a machine learning model, the `chat` method could be used to send and receive messages in a chatbot, and the `step` method could be used to update the agent's state in a reinforcement learning environment.
+-   The `_arun`, `_achat`, and `_astep` methods are asynchronous versions of the `run`, `chat`, and `step` methods, respectively. They return a coroutine that can be awaited using the `await` keyword. This allows multiple tasks to be executed concurrently, improving the efficiency of the agent.
+-   The `tools` and `memory` methods are used to initialize the agent's tools and memory, respectively. These methods can be overridden in subclasses to initialize specific tools and memory structures.
+-   The `reset` method is used to reset the agent's state. This method can be overridden in subclasses to define specific reset behaviors. For example, in a reinforcement learning agent, the

docs/swarms/workers/base.md

@@ -0,0 +1,258 @@
+# AbstractWorker Class
+====================
+
+The `AbstractWorker` class is an abstract class for AI workers. An AI worker can communicate with other workers and perform actions. Different workers can differ in what actions they perform in the `receive` method.
+
+## Class Definition
+----------------
+
+```
+class AbstractWorker:
+    """(In preview) An abstract class for AI worker.
+
+    An worker can communicate with other workers and perform actions.
+    Different workers can differ in what actions they perform in the `receive` method.
+    """
+```
+
+
+## Initialization
+--------------
+
+The `AbstractWorker` class is initialized with a single parameter:
+
+-   `name` (str): The name of the worker.
+
+```
+def __init__(
+    self,
+    name: str,
+):
+    """
+    Args:
+        name (str): name of the worker.
+    """
+    self._name = name
+```
+
+
+## Properties
+----------
+
+The `AbstractWorker` class has a single property:
+
+-   `name`: Returns the name of the worker.
+
+```
+@property
+def name(self):
+    """Get the name of the worker."""
+    return self._name
+```
+
+
+## Methods
+-------
+
+The `AbstractWorker` class has several methods:
+
+### `run`
+
+The `run` method is used to run the worker agent once. It takes a single parameter:
+
+-   `task` (str): The task to be run.
+
+```
+def run(
+    self,
+    task: str
+):
+    """Run the worker agent once"""
+```
+
+
+### `send`
+
+The `send` method is used to send a message to another worker. It takes three parameters:
+
+-   `message` (Union[Dict, str]): The message to be sent.
+-   `recipient` (AbstractWorker): The recipient of the message.
+-   `request_reply` (Optional[bool]): If set to `True`, the method will request a reply from the recipient.
+
+```
+def send(
+    self,
+    message: Union[Dict, str],
+    recipient: AbstractWorker,
+    request_reply: Optional[bool] = None
+):
+    """(Abstract method) Send a message to another worker."""
+```
+
+
+### `a_send`
+
+The `a_send` method is the asynchronous version of the `send` method. It takes the same parameters as the `send` method.
+
+```
+async def a_send(
+    self,
+    message: Union[Dict, str],
+    recipient: AbstractWorker,
+    request_reply: Optional[bool] = None
+):
+    """(Abstract async method) Send a message to another worker."""
+```
+
+
+### `receive`
+
+The `receive` method is used to receive a message from another worker. It takes three parameters:
+
+-   `message` (Union[Dict, str]): The message to be received.
+-   `sender` (AbstractWorker): The sender of the message.
+-   `request_reply` (Optional[bool]): If set to `True`, the method will request a reply from the sender.
+
+```
+def receive(
+    self,
+    message: Union[Dict, str],
+    sender: AbstractWorker,
+    request_reply: Optional[bool] = None
+):
+    """(Abstract method) Receive a message from another worker."""
+```
+
+
+### `a_receive`
+
+The `a_receive` method is the asynchronous version of the `receive` method. It takes the same parameters as the `receive` method.
+
+```
+async def a_receive(
+    self,
+    message: Union[Dict, str],
+    sender: AbstractWorker,
+    request_reply: Optional[bool] = None
+):
+    """(Abstract async method) Receive a message from another worker."""
+```
+
+
+### `reset`
+
+The `reset` method is used to reset the worker.
+
+```
+def reset(self):
+    """(Abstract method) Reset the worker."""
+```
+
+
+### `generate_reply`
+
+The `generate_reply` method is used to generate a reply based on the received messages. It takes two parameters:
+
+-   `messages` (Optional[List[Dict]]): A list of messages received.
+-   `sender` (AbstractWorker): The sender of the messages.
+
+The method returns a string, a dictionary, or `None`. If `None` is returned, no reply is generated.
+
+```
+def generate_reply(
+    self,
+    messages: Optional[List[Dict]] = None,
+    sender: AbstractWorker,
+    **kwargs,
+) -> Union[str, Dict, None]:
+    """(Abstract method) Generate a reply based on the received messages.
+
+    Args:
+        messages (list[dict]): a list of messages received.
+        sender: sender of an Agent instance.
+    Returns:
+        str or dict or None: the generated reply. If None, no reply is generated.
+    """
+```
+
+
+### `a_generate_reply`
+
+The `a_generate_reply` method is the asynchronous version of the `generate_reply` method. It
+
+takes the same parameters as the `generate_reply` method.
+
+```
+async def a_generate_reply(
+    self,
+    messages: Optional[List[Dict]] = None,
+    sender: AbstractWorker,
+    **kwargs,
+) -> Union[str, Dict, None]:
+    """(Abstract async method) Generate a reply based on the received messages.
+
+    Args:
+        messages (list[dict]): a list of messages received.
+        sender: sender of an Agent instance.
+    Returns:
+        str or dict or None: the generated reply. If None, no reply is generated.
+    """
+```
+
+
+Usage Examples
+--------------
+
+### Example 1: Creating an AbstractWorker
+
+```
+from swarms.worker.base import AbstractWorker
+
+worker = AbstractWorker(name="Worker1")
+print(worker.name)  # Output: Worker1
+```
+
+
+In this example, we create an instance of `AbstractWorker` named "Worker1" and print its name.
+
+### Example 2: Sending a Message
+
+```
+from swarms.worker.base import AbstractWorker
+
+worker1 = AbstractWorker(name="Worker1")
+worker2 = AbstractWorker(name="Worker2")
+
+message = {"content": "Hello, Worker2!"}
+worker1.send(message, worker2)
+```
+
+
+In this example, "Worker1" sends a message to "Worker2". The message is a dictionary with a single key-value pair.
+
+### Example 3: Receiving a Message
+
+```
+from swarms.worker.base import AbstractWorker
+
+worker1 = AbstractWorker(name="Worker1")
+worker2 = AbstractWorker(name="Worker2")
+
+message = {"content": "Hello, Worker2!"}
+worker1.send(message, worker2)
+
+received_message = worker2.receive(message, worker1)
+print(received_message)  # Output: {"content": "Hello, Worker2!"}
+```
+
+
+In this example, "Worker1" sends a message to "Worker2". "Worker2" then receives the message and prints it.
+
+Notes
+-----
+
+-   The `AbstractWorker` class is an abstract class, which means it cannot be instantiated directly. Instead, it should be subclassed, and at least the `send`, `receive`, `reset`, and `generate_reply` methods should be overridden.
+-   The `send` and `receive` methods are abstract methods, which means they must be implemented in any subclass of `AbstractWorker`.
+-   The `a_send`, `a_receive`, and `a_generate_reply` methods are asynchronous methods, which means they return a coroutine that can be awaited using the `await` keyword.
+-   The `generate_reply` method is used to generate a reply based on the received messages. The exact implementation of this method will depend on the specific requirements of your application.
+-   The `reset` method is used to reset the state of the worker. The exact implementation of this method will depend on the specific requirements of your application.

mkdocs.yml

@@ -77,20 +77,22 @@ nav:
     - Hiring: "hiring.md"
 - Swarms:
   - Overview: "swarms/index.md"
-  - AutoScaler: "swarms/swarms/autoscaler.md"
-  - Workers:
+  - swarms.swarms:
+    - AutoScaler: "swarms/swarms/autoscaler.md"
+  - swarms.workers:
     - Overview: "swarms/workers/index.md"
-  - Agents:
-    - Base Models:
-      - Overview: "swarms/models/index.md"
-      - HuggingFaceLLM: "swarms/models/hf.md"
-      - Anthropic: "swarms/models/anthropic.md"
+    - AbstractWorker: "swarms/worker/base.md"
+  - swarms.agents:
+    - AbstractAgent: "swarms/agents/abstract_agent.md"
     - OmniModalAgent: "swarms/agents/omni_agent.md"
+  - swarms.models:
+    - Overview: "swarms/models/index.md"
+    - HuggingFaceLLM: "swarms/models/hf.md"
+    - Anthropic: "swarms/models/anthropic.md"
 - Examples:
     - Overview: "examples/index.md"
     - Agents:
       - OmniAgent: "examples/omni_agent.md"
-      
 - Applications:
     - CustomerSupport: 
       - Overview: "applications/customer_support.md"

swarms/agents/__init__.py

@@ -12,4 +12,4 @@ from swarms.agents.omni_modal_agent import OmniModalAgent
 #utils
 from swarms.agents.message import Message
 from swarms.agents.stream_response import stream
-from swarms.agents.base import Agent
+from swarms.agents.base import AbstractAgent

swarms/agents/base.py

@@ -1,7 +1,7 @@
 from typing import Dict, List, Optional, Union
 
 
-class Agent:
+class AbstractAgent:
     """(In preview) An abstract class for AI agent.
 
     An agent can communicate with other agents and perform actions.

swarms/swarms/simple_swarm.py

@@ -4,9 +4,10 @@ from queue import Queue, PriorityQueue
 class SimpleSwarm:
     def __init__(
        self,
-       num_workers,
-       openai_api_key,
-       ai_name
+       num_workers: int = None,
+       openai_api_key: str = None,
+       ai_name: str = None,
+       rounds: int = 1,
     ):
         """
 
@@ -37,14 +38,14 @@ class SimpleSwarm:
 
         """
         self.workers = [
-            Worker(openai_api_key, ai_name) for _ in range(num_workers)
+            Worker(ai_name, ai_name, openai_api_key) for _ in range(num_workers)
         ]
         self.task_queue = Queue()
         self.priority_queue = PriorityQueue()
     
     def distribute(
         self,
-        task,
+        task: str = None,
         priority=None
     ):
         """Distribute a task to the workers"""

swarms/workers/base.py

@@ -68,7 +68,7 @@ class AbstractWorker:
     def generate_reply(
         self,
         messages: Optional[List[Dict]] = None,
-        sender, #Optional["AbstractWorker"] = None,
+        sender = None, #Optional["AbstractWorker"] = None,
         **kwargs,
     ) -> Union[str, Dict, None]:
         """(Abstract method) Generate a reply based on the received messages.
@@ -83,7 +83,7 @@ class AbstractWorker:
     async def a_generate_reply(
         self,
         messages: Optional[List[Dict]] = None,
-        sender, #Optional["AbstractWorker"] = None,
+        sender = None, #Optional["AbstractWorker"] = None,
         **kwargs,
     ) -> Union[str, Dict, None]:
         """(Abstract async method) Generate a reply based on the received messages.