Skip to content

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:

  1. git (latest)
  2. python (>= 3.10)

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.

Thanks for contributing!