Contribute to `prompto`

Everyone is welcome to contribute to prompto and we value a wide range of contributions from code contributions or bug reports to documentation improvements. In particular, while prompto is a tool to support querying API endpoints asynchronously, there are several APIs that we have not implemented. We don’t have access to every APIs and so we need your help to implement them! We are also open to new ideas and suggestions for the library.

This note aims to capture some of the practices adopted during the development of prompto with a view of making development easier and process of contributing to the library as smooth as possible.

It is not intended as a set of hard-and-fast rules * there will always be exceptions, and we definitely don’t want to deter anyone from contributing, rather we hope that this will develop into a set of helpful guidelines, and additions/corrections to this document are always welcome!

Note that this guide was inspired by the transformers guide to contributing.

Ways to contribute

There are many ways to contribute to prompto:

Adding new APIs and models - see the guide on how to add new APIs and models
Improving the documentation - see the building docs section for more details on how to build the documentation locally
Contribute to the examples and creating tutorials
Submitting bug reports or feature requests
Fixing bugs or implementing new features

To see any open issues or to submit a new issue, you can visit the issues page.

Branching and making a pull request

Development should mostly take place on individual branches that are branched off main. When you are ready to merge your changes, you can create a pull request to merge your branch into main.

To start contributing, you can follow these steps:

Fork the repository You can fork the repository by clicking on the Fork button on the top right of the repository page.

Clone your fork of repository

git clone git@github.com:<your Github handle>/prompto.git
cd prompto
git remote add upstream https://github.com/alan-turing-institute/prompto.git

Create a development environment in a new virtual environment * see setting up a development environment section for more details.
Create a new branch for your changes
```
git checkout -b my-new-feature
```
Make your changes You may also want to make sure your code is up-to-date with the original repository by rebasing your branch before making a pull request:
```
git fetch upstream
git rebase upstream/main
```
Ensure that your changes are tested You can run the tests using:
```
python -m pytest
```
Install pre-commit hooks * see formatting and pre-commit hooks section for more details. You can install the pre-commit hooks by running:
```
pre-commit install
```
Commit your changes and open a Pull Request
```
git add <files-with-your-changes>
git commit -m "Add new feature"
```
Do remember to write good commit messages to communicate your changes.
Push your changes to your fork and make a pull request Note may also want to make sure your code is up-to-date with the original repository by rebasing your branch before making a pull request:
```
git fetch upstream
git rebase upstream/main
```
Then push your changes to your fork:
```
git push -u origin my-new-feature
```
You can now go to your fork of the repository on Github and create a pull request from your branch to the main branch of the original repository.

Formatting and `pre-commit` hooks

We use pre-commit which will automatically format your code and run some basic checks before you commit to ensure that the code is formatted correctly. You can install the pre-commit hooks by running:

pip install pre-commit  # or brew install pre-commit on macOS
pre-commit install  # will install a pre-commit hook into the git repo

After doing this, each time you commit, some linters will be applied to format the codebase. You can also/alternatively run pre-commit run --all-files to run the checks.

Setting up a development environment

If you’d like to set up a development environment for prompto, you can follow the steps below:

Clone the repository (or a fork of the repository if you are planning to contribute to the library * see the branching and making a pull request section for more details)
```
git clone git@github.com:alan-turing-institute/prompto.git
```
Navigate to Project Directory
```
cd prompto
```
Set up a development environment (in a virtual environment)
```
pip install -e ".[dev]"
```
This will install the dependencies required for development. Note that there are groups for different models that you can install as well. For example, if you want to install the dependencies for the OpenAI and Gemini models, you can run:
```
pip install -e ".[dev,openai,gemini]"
```

Using poetry

prompto uses Poetry for dependency management. If you prefer to use Poetry for dependency management, you can instead run the following to set up the development environment:

Install Poetry If you haven’t installed Poetry yet, you can install it by following the instructions here.
Create and activate a Poetry Environment
```
poetry shell
```
This will create a virtual environment and activate it. You can also use another virtual environment manager, such as venv or conda for this step if you prefer.
Install dependencies
```
poetry install --extras dev
```
To install further groups, you can use multiple --extras or -E flags, or you can specify them in quotes:
```
poetry install --extras "dev openai gemini"
```
or
```
poetry install -E dev -E openai -E gemini
```
Refer to the Poetry documentation for more information on installing dependencies.

Building docs

We’re always looking for improvements to the documentation that make it more clear and accurate. Please let us know how the documentation can be improved such as typos and any content that is missing, unclear or inaccurate. We’ll be happy to make the changes or help you make a contribution if you’re interested!

We currently use MkDocs to build the documentation. To build the documentation, you can run:

mkdocs serve

This will start a local server that you can access at http://127.0.0.1:8088 to view the documentation. You can make changes to the documentation in the docs directory and the changes will be reflected in the local server.

Contribute to prompto