cogment-py-sdk

Cogment is an innovative open source AI platform designed to leverage the advent of AI to benefit humankind through human-AI collaboration developed by AI Redefined. Cogment enables AI researchers and engineers to build, train and operate AI agents in simulated or real environments shared with humans. For the full user documentation visit https://docs.cogment.ai

This module, cogment-py-sdk, is the Python SDK for making use of Cogment when working with Python. It's full documentation can be consulted at https://docs.cogment.ai/cogment/cogment-api-reference/python/.

Developers

Prerequisites

Make sure you have the following installed:

Python >=3.7, <3.11

Install dependencies

We recommend using a virtualenv to isolate your dependencies. On most unix flavors you create and activate this by running the following:

$ python -m venv .venv
$ source .venv/bin/activate

once you are finished with the virtualenv you can deactivate it by running:

$ deactivate

Install the dependencies, including downloading and building the cogment protobuf API by running the following:

$ pip install -r requirements.txt
$ python -m setup develop

The second line will call the following setup.py commands to deal with the cogment API (those can also be called seprately)

$ python -m setup retrieve_cogment_api
$ python -m setup build_cogment_api_protos

Define used Cogment protobuf API

The version of the used cogment protobuf API is defined in the .cogment-api.yaml file at the root of the repository. The following can be defined:

cogment_version: "latest", is the default, it retrieves the api from the latest Cogment release (excluding pre-releases),
cogment_version: "vMAJOR.MINOR.PATCH[-PRERELEASE]", retrieves the api from any Cogment release.
cogment_api_path: "../RELATIVE/PATH/TO/LOCAL/COGMENT/INSTALL/include/cogment/api", retrieves a local version of the api found at the given path (e.g. common.proto should be at ${cogment_api_path}/common.proto); if set, this overrides cogment_version.

After any change, do not forget to run pip install -e . for it to be taken into account.

Tests

Integration tests

These tests launch and use Cogment, by default they'll use they'll download and use the latest released version of Cogment.

$ pytest --launch-orchestrator

The following environment can be defined to change this behavior, either directly in the terminal or in a .env file located at the root of the repository:

COGMENT_PATH="/path/to/cogment" # local path to cogment binary
COGMENT_VERSION="v2.2.0" # cogment version to download

Lint

Run the pycodestyle using

$ pycodestyle

Run the mypy type annotations checks using

$ mypy .

Check conflicting dependencies with "popular" Python packages

./scripts/check_dependencies_conflicts.sh

This script will check for conflicts required by the cogment-py-sdk and the popular Python packages in the AI/ML/Data ecosystem.

Build the source package

python -m build

Release process

People having mainteners rights of the repository can follow these steps to release a version MAJOR.MINOR.PATCH. The versioning scheme follows Semantic Versioning.

Run ./scripts/create_release_branch.sh MAJOR.MINOR.PATCH to create the release branch and update the version of the package,
On the release branch, check and update the changelog if needed,
Make sure ./.cogment-api.yaml specifies fixed version to ensure rebuildability,
Make sure everything's fine on CI,
Run ./scripts/tag_release.sh MAJOR.MINOR.PATCH to create the specific version section in the changelog, merge the release branch in main, create the release tag and update the develop branch with those.

The rest, publishing the package to PyPI and updating the mirror repositories, is handled directly by the CI.