Skip to content

Commit

Permalink
[DOCS]
Browse files Browse the repository at this point in the history
  • Loading branch information
Kye Gomez authored and Kye Gomez committed Jul 11, 2024
1 parent 57f2679 commit 7091518
Show file tree
Hide file tree
Showing 9 changed files with 589 additions and 201 deletions.
191 changes: 59 additions & 132 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
@@ -1,155 +1,82 @@
# Contributing to Swarms 🛠️

Thank you for your interest in contributing to Swarms!
Thank you for your interest in contributing to Swarms! This guide will help you get started with your contribution.

We are actively improving this library to reduce the amount of work you need to do to solve common computer vision problems.
## Essential Steps for Contributing

## Contribution Guidelines
### 1. Fork and Clone the Repository

We welcome contributions to:

1. Add a new feature to the library (guidance below).
2. Improve our documentation and add examples to make it clear how to leverage the swarms library.
3. Report bugs and issues in the project.
4. Submit a request for a new feature.
5. Improve our test coverage.

### Contributing Features ✨

Swarms is designed to provide modular building blocks to build scalable swarms of autonomous agents!

Before you contribute a new feature, consider submitting an Issue to discuss the feature so the community can weigh in and assist.

### Requirements:
- New class and or function Module with documentation in docstrings with error handling
- Tests using pytest in tests folder in the same module folder
- Documentation in the docs/swarms/module_name folder and then added into the mkdocs.yml


## How to Contribute Changes

First, fork this repository to your own GitHub account. Click "fork" in the top corner of the `swarms` repository to get started:

Then, run `git clone` to download the project code to your computer.

Move to a new branch using the `git checkout` command:

```bash
git checkout -b <your_branch_name>
```

The name you choose for your branch should describe the change you want to make (i.e. `line-counter-docs`).

Make any changes you want to the project code, then run the following commands to commit your changes:

```bash
git add .
git commit -m "Your commit message"
git push -u origin main
```

## 🎨 Code quality
- Follow the following guide on code quality a python guide or your PR will most likely be overlooked: [CLICK HERE](https://google.github.io/styleguide/pyguide.html)



### Pre-commit tool

This project utilizes the [pre-commit](https://pre-commit.com/) tool to maintain code quality and consistency. Before submitting a pull request or making any commits, it is important to run the pre-commit tool to ensure that your changes meet the project's guidelines.


- Install pre-commit (https://pre-commit.com/)

```bash
pip install pre-commit
```

- Check that it's installed

```bash
pre-commit --version
```

Now when you make a git commit, the black code formatter and ruff linter will run.

Furthermore, we have integrated a pre-commit GitHub Action into our workflow. This means that with every pull request opened, the pre-commit checks will be automatically enforced, streamlining the code review process and ensuring that all contributions adhere to our quality standards.

To run the pre-commit tool, follow these steps:

1. Install pre-commit by running the following command: `poetry install`. It will not only install pre-commit but also install all the deps and dev-deps of project

2. Once pre-commit is installed, navigate to the project's root directory.

3. Run the command `pre-commit run --all-files`. This will execute the pre-commit hooks configured for this project against the modified files. If any issues are found, the pre-commit tool will provide feedback on how to resolve them. Make the necessary changes and re-run the pre-commit command until all issues are resolved.

4. You can also install pre-commit as a git hook by execute `pre-commit install`. Every time you made `git commit` pre-commit run automatically for you.


### Docstrings

All new functions and classes in `swarms` should include docstrings. This is a prerequisite for any new functions and classes to be added to the library.

`swarms` adheres to the [Google Python docstring style](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods). Please refer to the style guide while writing docstrings for your contribution.

### Type checking

Then, go back to your fork of the `swarms` repository, click "Pull Requests", and click "New Pull Request".

Make sure the `base` branch is `develop` before submitting your PR.
1. Fork the Swarms repository to your GitHub account by clicking the "Fork" button in the top-right corner of the repository page.
2. Clone your forked repository to your local machine:
```
git clone https://github.com/kyegomez/swarms.git
```

On the next page, review your changes then click "Create pull request":
### 2. Make Changes

Next, write a description for your pull request, and click "Create pull request" again to submit it for review:
1. Create a new branch for your changes:
```
git checkout -b your-branch-name
```
2. Make your desired changes to the codebase.

When creating new functions, please ensure you have the following:
### 3. Commit and Push Changes

1. Docstrings for the function and all parameters.
2. Unit tests for the function.
3. Examples in the documentation for the function.
4. Created an entry in our docs to autogenerate the documentation for the function.
5. Please share a Google Colab with minimal code to test new feature or reproduce PR whenever it is possible. Please ensure that Google Colab can be accessed without any issue.
1. Stage your changes:
```
git add .
```
2. Commit your changes:
```
git commit -m "Your descriptive commit message"
```
3. Push your changes to your fork:
```
git push -u origin your-branch-name
```

All pull requests will be reviewed by the maintainers of the project. We will provide feedback and ask for changes if necessary.
### 4. Create a Pull Request

PRs must pass all tests and linting requirements before they can be merged.
1. Go to the original Swarms repository on GitHub.
2. Click on "Pull Requests" and then "New Pull Request".
3. Select your fork and branch as the compare branch.
4. Click "Create Pull Request".
5. Fill in the pull request description and submit.

## 📝 documentation
## Important Considerations

The `swarms` documentation is stored in a folder called `docs`. The project documentation is built using `mkdocs`.
- Ensure your code follows the project's coding standards.
- Include tests for new features or bug fixes.
- Update documentation as necessary.
- Make sure your branch is up-to-date with the main repository before submitting a pull request.

To run the documentation, install the project requirements with `poetry install dev`. Then, run `mkdocs serve` to start the documentation server.
## Additional Information

You can learn more about mkdocs on the [mkdocs website](https://www.mkdocs.org/).
### Code Quality

## 🧪 tests
- Run all the tests in the tests folder
```pytest```

## Code Quality
`code-quality.sh` runs 4 different code formatters for ultra reliable code cleanup using Autopep8, Black, Ruff, YAPF
1. Open your terminal.
We use pre-commit hooks to maintain code quality. To set up pre-commit:

2. Change directory to where `code-quality.sh` is located using `cd` command:
```sh
cd /path/to/directory
1. Install pre-commit:
```

3. Make sure the script has execute permissions:
```sh
chmod +x code_quality.sh
pip install pre-commit
```

4. Run the script:
```sh
./code-quality.sh
2. Set up the git hook scripts:
```

If the script requires administrative privileges, you might need to run it with `sudo`:
```sh
sudo ./code-quality.sh
```
pre-commit install
```

### Documentation

- We use mkdocs for documentation. To serve the docs locally:
```
mkdocs serve
```

Please replace `/path/to/directory` with the actual path where the `code-quality.sh` script is located on your system.
### Testing

If you're asking for a specific content or functionality inside `code-quality.sh` related to YAPF or other code quality tools, you would need to edit the `code-quality.sh` script to include the desired commands, such as running YAPF on a directory. The contents of `code-quality.sh` would dictate exactly what happens when you run it.
- Run tests using pytest:
```
pytest
```

For more detailed information on code quality, documentation, and testing, please refer to the full contributing guidelines in the repository.
69 changes: 54 additions & 15 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,6 @@ agent.run(

```

-----

### `Agent` + Long Term Memory
`Agent` equipped with quasi-infinite long term memory. Great for long document understanding, analysis, and retrieval.
Expand Down Expand Up @@ -172,7 +171,7 @@ agent.run("Generate a 10,000 word blog on health and wellness.")


```
-----


### `Agent` ++ Long Term Memory ++ Tools!
An LLM equipped with long term memory and tools, a full stack agent capable of automating all and any digital tasks given a good prompt.
Expand Down Expand Up @@ -285,7 +284,7 @@ out = agent("Create a new file for a plan to take over the world.")
print(out)

```
----


### Devin
Implementation of Devin in less than 90 lines of code with several tools:
Expand Down Expand Up @@ -391,7 +390,7 @@ agent = Agent(
out = agent("Create a new file for a plan to take over the world.")
print(out)
```
---------------


### `Agent`with Pydantic BaseModel as Output Type
The following is an example of an agent that intakes a pydantic basemodel and outputs it at the same time:
Expand Down Expand Up @@ -454,28 +453,22 @@ print(f"Generated data: {generated_data}")


```
-----

### Multi Modal Autonomous Agent
Run the agent with multiple modalities useful for various real-world tasks in manufacturing, logistics, and health.

```python
# Description: This is an example of how to use the Agent class to run a multi-modal workflow
import os

from dotenv import load_dotenv

from swarms import GPT4VisionAPI, Agent

# Load the environment variables
load_dotenv()

# Get the API key from the environment
api_key = os.environ.get("OPENAI_API_KEY")

# Initialize the language model
llm = GPT4VisionAPI(
openai_api_key=api_key,
openai_api_key=os.environ.get("OPENAI_API_KEY"),
max_tokens=500,
)

Expand All @@ -490,11 +483,16 @@ img = "assembly_line.jpg"

## Initialize the workflow
agent = Agent(
llm=llm, max_loops="auto", autosave=True, dashboard=True, multi_modal=True
agent_name = "Multi-ModalAgent",
llm=llm,
max_loops="auto",
autosave=True,
dashboard=True,
multi_modal=True
)

# Run the workflow on a task
agent.run(task=task, img=img)
agent.run(task, img)
```
----

Expand Down Expand Up @@ -555,7 +553,7 @@ generated_data = agent.run(task)
print(f"Generated data: {generated_data}")

```
----------------


### `Task`
For deeper control of your agent stack, `Task` is a simple structure for task execution with the `Agent`. Imagine zapier like LLM-based workflow automation.
Expand Down Expand Up @@ -761,8 +759,49 @@ print(output)
## `HierarhicalSwarm`
Coming soon...


## `GraphSwarm`
Coming soon...

```python
import os

from dotenv import load_dotenv

from swarms import Agent, Edge, GraphWorkflow, Node, NodeType, OpenAIChat

load_dotenv()

api_key = os.environ.get("OPENAI_API_KEY")

llm = OpenAIChat(
temperature=0.5, openai_api_key=api_key, max_tokens=4000
)
agent1 = Agent(llm=llm, max_loops=1, autosave=True, dashboard=True)
agent2 = Agent(llm=llm, max_loops=1, autosave=True, dashboard=True)

def sample_task():
print("Running sample task")
return "Task completed"

wf_graph = GraphWorkflow()
wf_graph.add_node(Node(id="agent1", type=NodeType.AGENT, agent=agent1))
wf_graph.add_node(Node(id="agent2", type=NodeType.AGENT, agent=agent2))
wf_graph.add_node(
Node(id="task1", type=NodeType.TASK, callable=sample_task)
)
wf_graph.add_edge(Edge(source="agent1", target="task1"))
wf_graph.add_edge(Edge(source="agent2", target="task1"))

wf_graph.set_entry_points(["agent1", "agent2"])
wf_graph.set_end_points(["task1"])

print(wf_graph.visualize())

# Run the workflow
results = wf_graph.run()
print("Execution results:", results)

```

## `MixtureOfAgents`
This is an implementation from the paper: "Mixture-of-Agents Enhances Large Language Model Capabilities" by together.ai, it achieves SOTA on AlpacaEval 2.0, MT-Bench and FLASK, surpassing GPT-4 Omni. Great for tasks that need to be parallelized and then sequentially fed into another loop
Expand Down
3 changes: 3 additions & 0 deletions docs/mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,9 @@ nav:
# - Redis: "swarms_memory/redis.md"
- Faiss: "swarms_memory/faiss.md"
# - HNSW: "swarms_memory/hnsw.md"
- Swarms Platform:
- Overview: "swarms_platform/index.md"
- Prompts API: "swarms_platform/prompts_api.md"
- References:
- Agent Glossary: "swarms/glossary.md"
- List of The Best Multi-Agent Papers: "swarms/papers.md"
Loading

0 comments on commit 7091518

Please sign in to comment.