Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
118 lines (84 loc) · 3.97 KB

CONTRIBUTING.md

File metadata and controls

118 lines (84 loc) · 3.97 KB

Contributing

Thank you for your interest in contributing to the project! Here are some useful instructions for getting you started.

Installation

  1. Clone the repository:

    git clone https://github.com/CogStack/cogstack-model-gateway.git
cd cogstack-model-gateway

  2. Install Poetry if you haven't already:

    curl -sSL https://install.python-poetry.org | python3 -

  3. Activate a virtual environment e.g. using pyenv or directly with Poetry like below:

    eval $(poetry env activate)

  4. Install the project dependencies:

    poetry install --with dev --with migrations
# explicitly install the CogStackModel Gateway client for development
poetry install -P client --with dev

Pre-commit Hooks

We use pre-commit hooks to ensure code quality. To set them up, follow these steps:

  1. Install the pre-commit hooks to your local Git repository:

    pre-commit install

  2. (optional) To run the pre-commit hooks manually on all files, use:

    pre-commit run --all-files

Running

The recommended way to run the project locally for development is by using the provided Docker Compose overrides to build the images from the local codebase and spin up the required services, running the following command from the project root:

docker compose up --build

In order to include pgAdmin and the observability stack as part of the local setup, you can explicitly provide their corresponding profiles at startup:

docker compose --profile o11y --profile debug up --build

To run the project locally, the run_local.py script is provided as a shortcut for spinning up the required external services (e.g. PostgreSQL, RabbitMQ, MinIO) as Docker containers and starting the Gateway, Scheduler, and Ripper as separate processes on the host machine. It also watches for changes in the codebase and restarts the services when necessary. Before running the script, ensure you have configured the environment with the required variables, as described in the Installation section of the README, and then execute the following inside the virtual environment:

python run_local.py

Note that the script is meant as a convenience tool for local development, therefore coming with no quality guarantees, and should not be used in production.

Testing

To run the tests, execute the following command inside the virtual environment:

pytest

Python Client

A Python client is provided in to simplify interaction with the CogStack Model Gateway. It abstracts task submission, polling, and result retrieval, providing both high-level and low-level APIs. The client is async by default, but a synchronous version is also available for easier experimentation.

The Python package is managed and built using Poetry, with dynamic versioning. To build and publish the client package, first make sure that the commit from which you are building is tagged with the desired version number, which will be used by Poetry to set the package version automatically. Then, inside the client directory, run the following commands:

poetry build
poetry publish

Please ensure you have the necessary permissions to publish the package to PyPI and that you have correctly configured Poetry with your PyPI credentials.

On Mac

If you're running the integration tests on Mac you may need to take some additional steps to ensure that the host machine can access the Docker containers. This is because Docker for Mac runs in a virtual machine and, as a result, the containers are not directly accessible from the host. Given that the services running as part of the integration tests use IP addresses to communicate with the containers, an easy solution to avoid manual configuration would be using a tool like docker-mac-net-connect.