Contributing Guide
Thanks for your interest in contributing to Agent Torch! This guide will show you how to set up your environment and contribute to this library.
Prerequisites
You must have the following software installed:
Once you have installed the above, follow
these instructions
to
fork
and clone
the repository
(AgentTorch/AgentTorch
).
Once you have forked and cloned the repository, you can pick out an issue you want to fix/implement!
Making Changes
Once you have cloned the repository to your computer (say, in
~/Code/AgentTorch
) and picked the issue you want to tackle, create a virtual
environment, install all dependencies, and create a new branch to hold all your
work.
# create a virtual environment
> python -m venv .venv/
# set it up
> . .venv/bin/activate
> pip install -r development.txt
> pip install -e .
# set up the pre commit hooks
> pre-commit install --config pre-commit.yaml
# create a new branch
> git switch master
> git switch --create branch-name
While naming your branch, make sure the name is short and self explanatory.
Once you have created a branch, you can start coding!
Project Structure
The project is structured as follows. The comments written next to the file/folder give a brief explanation of what purpose the file/folder serves.
.
├── agent_torch/
│ ├── helpers/ # defines helper functions used to initialize or work with the state of the simulation.
│ ├── llm/ # contains all the code related to using llms as agents in the simulation
│ ├── __init__.py # exports everything to the world
│ ├── config.py # handles reading and processing the simulation's configuration
│ ├── controller.py # executes the substeps for each episode
│ ├── initializer.py # creates a simulation from a configuration and registry
│ ├── registry.py # registry that stores references to the implementations of the substeps and helper functions
│ ├── runner.py # executes the episodes of the simulation, and handles its state
│ ├── substep.py # contains base classes for the substep observations, actions and transitions
│ └── utils.py # utility functions used throughout the project
├── docs/
│ ├── media/ # assets like screenshots or diagrams inserted in .md files
│ ├── tutorials/ # jupyter notebooks with tutorials and their explanations
│ ├── architecture.md # the framework's architecture
│ └── install.md # instructions on installing the framework
├── models/
│ ├── covid/ # a model simulating disease spread, using the example of covid 19
│ └── predator_prey/ # a simple model used to showcase the features of the framework
├── citation.bib # contains the latex code to use to cite this project
├── contributing.md # this file, helps onboard contributors
├── license.md # contains the license for this project (MIT)
├── readme.md # contains details on the what, why, and how
├── requirements.txt # lists the dependencies of the framework
└── setup.py # defines metadata for the project
Note that after making any code changes, you should run the black
code
formatter, as follows:
> black agent_torch/ tests/
You should also ensure all the unit tests pass, especially if you have made
changes to any files in the agent_torch/
folder.
> pytest -vvv tests/
For any changes to the documentation, run prettier
over the *.md
files after
making changes to them. To preview the generated documentation, run:
> mkdocs serve
Rememeber to add any new pages to the sidebar by editing
mkdocs.yaml
.
If you wish to write a tutorial, write it in a Jupyter Notebook, and then
convert it to a markdown file using nbconvert
:
> pip install nbconvert
> jupyter nbconvert --to markdown <file>.ipynb
> mv <file>.md index.md
Rememeber to move any files that it generates to the
docs/media
folder, and update the hyperlinks in the generated markdown file.
Saving Changes
After you have made changes to the code, you will want to
commit
(basically, Git's version
of save) the changes. To commit the changes you have made locally:
> git add this/folder that-file.js
> git commit --message 'commit-message'
While writing the commit-message
, try to follow the below guidelines:
Prefix the message with type:
, where type
is one of the following
dependending on what the commit does:
fix
: Introduces a bug fix.feat
: Adds a new feature.test
: Any change related to tests.perf
: Any performance related change.meta
: Any change related to the build process, workflows, issue templates, etc.refc
: Any refactoring work.docs
: Any documentation related changes.
Try to keep the first line brief, and less than 60 characters. Describe the change in detail in a new paragraph (double newline after the first line).
Contributing Changes
Once you have committed your changes, you will want to
push
(basically, publish your
changes to GitHub) your commits. To push your changes to your fork:
> git push origin branch-name
If there are changes made to the master
branch of the AgentTorch/AgentTorch
repository, you may wish to merge those changes into your branch. To do so, you
can run the following commands:
> git fetch upstream master
> git merge upstream/master
This will automatically add the changes from master
branch of the
AgentTorch/AgentTorch
repository to the current branch. If you encounter any
merge conflicts, follow
this guide
to resolve them.
Once you have pushed your changes to your fork, follow
these instructions
to open a
pull request
:
Once you have submitted a pull request, the maintainers of the repository will review your pull requests and provide feedback. If they find the work to be satisfactory, they will merge the pull request.