From 74a22f5e65862841c207a4eda8f84c3ca4820cd3 Mon Sep 17 00:00:00 2001 From: Your Name Date: Mon, 16 Sep 2024 23:01:49 -0400 Subject: [PATCH] [DOCS][CLEANUP] --- docs/swarms/structs/artifactupload.md | 49 -------------- docs/swarms/structs/stepinput.md | 64 ------------------- docs/swarms/structs/taskinput.md | 84 ------------------------ docs/swarms/tools/decorator.md | 92 --------------------------- 4 files changed, 289 deletions(-) delete mode 100644 docs/swarms/structs/artifactupload.md delete mode 100644 docs/swarms/structs/stepinput.md delete mode 100644 docs/swarms/structs/taskinput.md delete mode 100644 docs/swarms/tools/decorator.md diff --git a/docs/swarms/structs/artifactupload.md b/docs/swarms/structs/artifactupload.md deleted file mode 100644 index 90b30f58..00000000 --- a/docs/swarms/structs/artifactupload.md +++ /dev/null @@ -1,49 +0,0 @@ -# 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. diff --git a/docs/swarms/structs/stepinput.md b/docs/swarms/structs/stepinput.md deleted file mode 100644 index 4d7d340c..00000000 --- a/docs/swarms/structs/stepinput.md +++ /dev/null @@ -1,64 +0,0 @@ -# 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 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 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 import StepInput - -file_path = "config.json" -with open(file_path) 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. diff --git a/docs/swarms/structs/taskinput.md b/docs/swarms/structs/taskinput.md deleted file mode 100644 index 8e9ed33f..00000000 --- a/docs/swarms/structs/taskinput.md +++ /dev/null @@ -1,84 +0,0 @@ -## 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. diff --git a/docs/swarms/tools/decorator.md b/docs/swarms/tools/decorator.md deleted file mode 100644 index 5d4acb13..00000000 --- a/docs/swarms/tools/decorator.md +++ /dev/null @@ -1,92 +0,0 @@ - -# Tool Decorator Documentation - -## Module Overview - -The `tool` decorator is designed to enhance functions by automatically generating an OpenAI function schema based on the function's signature and provided metadata. This schema can be outputted in different formats based on the decorator's arguments. The primary use of this decorator is to facilitate the integration of Python functions with external systems that require structured metadata, making it ideal for creating machine-readable descriptions of functions. - -## Key Features - -- **Automatic Schema Generation:** Generates a schema based on the function's signature. -- **Flexible Output Formats:** Supports returning the schema as a dictionary, string, or YAML (if integrated). -- **Logging Support:** Includes logging of function calls and errors, aiding in debugging and monitoring. - -## Installation and Setup - -Before using the `tool` decorator, ensure that the required libraries are installed and configured. Here’s a basic setup: - -```bash -$ pip install -U swarms -``` - -## Decorator Definition - -### Signature - -```python -def tool(name: str = None, description: str = None, return_dict: bool = True, verbose: bool = True, return_string: bool = False, return_yaml: bool = False): -``` - -### Parameters - -| Parameter | Type | Default | Description | -|------------------|---------|---------|--------------------------------------------------------| -| `name` | str | None | Name of the OpenAI function. Optional. | -| `description` | str | None | Description of the OpenAI function. Optional. | -| `return_dict` | bool | True | Whether to return the schema as a dictionary. | -| `verbose` | bool | True | Enables verbose output. | -| `return_string` | bool | False | Whether to return the schema as a string. | -| `return_yaml` | bool | False | Whether to return the schema in YAML format. | - -## Functionality and Usage - -### Basic Usage - -Here is an example of using the `tool` decorator to enhance a simple function: - -```python -@tool(name="ExampleFunction", description="Demonstrates the use of the tool decorator") -def example_function(param1: int, param2: str): - print(f"Received param1: {param1}, param2: {param2}") - -example_function(123, "abc") -``` - -### Advanced Usage - -#### Returning Schema as String - -To get the schema as a string instead of a dictionary: - -```python -@tool(name="StringSchemaFunction", description="Returns schema as string", return_dict=False, return_string=True) -def another_function(): - pass - -print(another_function()) # Outputs the schema as a string -``` - -#### Handling Exceptions - -Demonstrating error handling with the decorator: - -```python -@tool(name="ErrorHandlingFunction", description="Handles errors gracefully") -def error_prone_function(): - raise ValueError("An example error") - -try: - error_prone_function() -except Exception as e: - print(f"Caught an error: {e}") -``` - -## Additional Information and Tips - -- **Logging:** The decorator logs all function calls and exceptions. Make sure to configure the `loguru` logger accordingly to capture these logs. -- **Assertion Errors:** The decorator performs type checks on the arguments, and if the types do not match, it will raise an assertion error. - -## References - -- For more on decorators: [Python Decorators Documentation](https://docs.python.org/3/glossary.html#term-decorator) -- Loguru library for logging: [Loguru Documentation](https://loguru.readthedocs.io/en/stable/)