path: root/python-cogment.spec

%global _empty_manifest_terminate_build 0
Name:		python-cogment
Version:	2.8.1
Release:	1
Summary:	Cogment python SDK
License:	Apache Software License
URL:		https://cogment.ai
Source0:	https://mirrors.aliyun.com/pypi/web/packages/8d/0e/b890fad1860f3d38d75a5287d9cfefb59e189220860f22f901ccd1888b29/cogment-2.8.1.tar.gz
BuildArch:	noarch

Requires:	python3-grpcio
Requires:	python3-grpcio-reflection
Requires:	python3-protobuf
Requires:	python3-prometheus-client
Requires:	python3-PyYaml
Requires:	python3-grpcio-tools
Requires:	python3-click

%description
# cogment-py-sdk

[![Latest final release](https://img.shields.io/pypi/v/cogment?style=flat-square)](https://pypi.org/project/cogment/) [![Apache 2 License](https://img.shields.io/badge/license-Apache%202-green?style=flat-square)](./LICENSE) [![Changelog](https://img.shields.io/badge/-Changelog%20-blueviolet?style=flat-square)](./CHANGELOG.md)

[Cogment](https://cogment.ai) 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](https://ai-r.com). 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](https://www.python.org) >=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:

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

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

```console
$ deactivate
```

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

```console
$ 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)

```console
$ 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.

```console
$ 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:

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

### Lint

Run the `pycodestyle` using

```console
$ pycodestyle
```

Run the `mypy` type annotations checks using

```console
$ mypy cogment/
```

### Check conflicting dependencies with "popular" Python packages

```console
./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

Build the source package

```console
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](http://semver.org/spec/v2.0.0.html).

1. Run `./scripts/create_release_branch.sh MAJOR.MINOR.PATCH` to create the release branch and update the version of the package,
2. On the release branch, check and update the changelog if needed,
3. Make sure `./.cogment-api.yaml` specifies fixed version to ensure rebuildability,
4. Make sure everything's fine on CI,
5. 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.

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

## Unreleased

## v2.8.1 - 2023-06-06

## Fixed

- Use the most recent directory entry when there are duplicates
- Self IP address discovery functionality is now working on macOS

## v2.8.0 - 2023-04-21

### Added

- Option to request full info (not just id and state) from 'watch_trials'
- Ability to use the SDK without spec (cog_settings)
- Automatic port selection for 'Context.serve_all_registered()'
- Ability to specify an explicit host to register a service to the directory
- Ability to specify trial properties for 'Datastore.all_trials()' and 'Datastore.get_trials()'
- Ability to specify trial ids for 'Datastore.all_trials()'

### Changed

- Enable warning and error logging even if user did not define a logging handler
- Warn user when no logging handler is defined (i.e. proper logging is disabled)
- Better self IP address discovery functionality

## v2.7.1 - 2023-03-06

## Fixed

- Deadlock in 'wait_for_newer' method of LatestModel

## v2.7.0 - 2023-02-28

### Changed

- Facility to track latest models automatically in the Model Registry

### Added

- 'properties' attribute to TrialParameters and TrialInfo

## v2.6.0 - 2023-02-03

### Changed

- Prometheus service is disabled by default

### Added

- Model Registry method `iteration_updates` to stream/push new model iterations
- Parameter `wait_for_trials` (for Datastore method `all_trials`) to wait for new trials

## v2.5.0 - 2023-01-26

## Fixed

- In Datastore reward could be returned as 'None' instead of 0.0

### Added

- Simplified interface for Model Registry (context.get_model_registry_v2)

## v2.4.1 - 2022-12-02

- Support and dependency check for python 3.10

## v2.4.0 - 2022-11-18

### Added

- 'COGMENT_LOG_LEVEL' environment variable
- Model Registry client

## Fixed

- Port parameter needs to be an int
- Context datastore request with default endpoint

## v2.3.0 - 2022-09-20

## Fixed

- Reward tick ID was hard coded to -1

### Changed

- Deprecation warning are only logged once

### Added

- 'Version' grpc method for pre-trial hooks
- Out-of-sync flag in datalog samples
- Parameter 'nb_buffered_ticks'
- Support for actor disconnection and response timeout parameters
- Global Directory integration
- Support for self registration to the Directory
- Use environment variable for Directory access details

## v2.2.2 - 2022-06-20

## Fixed

- Generate to handle multiple imports properly
- Output deprecated warning for use of 'snapshot' in received observation

## v2.2.1 - 2022-05-27

## Fixed

- Fix install of the package from a wheel

### Changed

- Replace poetry centric build process with modern setuptools

## v2.2.0 - 2022-05-07

### Added

- Introduce `cogment.generate.generate`, a function making the code generation previously available through `python -m cogment.generate` accessible as a function.

### Changed

- Integration tests are now able to install the Cogment CLI on their own.
- Integration tests no longer uses a Docker image.

## Fixed

- Fix integration test junit report output.

## v2.1.1 - 2022-04-11

## Fixed

- Fixed a typo in the TrialParameter "environemnt_name" to "environment_name"

## v2.1.0 - 2022-03-25

### Changed

- Update of gRPC version to >=1.42 & <1.45
- Deprecate `cogment.LogParams`
- Deprecate current way to use `PrehookSession`
- Deprecate Session 'event_loop', renamed to 'all_events'
- Deprecate DatalogSession 'get_all_samples' renamed 'all_samples'
- Standardize string ouput of classes

### Added

- `cogment.TrialParameters` and `cogment.ActorParameters`
- Add ability to provide parameters on trial start call
- Datastore SDK

## Fixed

- Fix the failure of the cogment package caused by the partial removal of gRPC 1.45 from pypi

## v2.0.2 - 2022-01-03

## v2.0.1 - 2022-01-03

## v2.0.0 - 2022-01-03

## v2.0.0-rc3 - 2021-12-16

### Changed

- cogment.generate now requires semantic arguments

## v2.0.0-rc2 - 2021-12-10

### Changed

- Cleanup user output
- Require grpc protocol url for endpoints

## v2.0.0-rc1 - 2021-12-01

### Changed

- Major internal changes to match API 2.0
- Minor use changes to match API 2.0 and improve usability

## v1.3.1 - 2021-11-18

### Changed

- Restrict the SDK to python >= 3.7 and <3.10 to maintain compatiblity with tensorflow ^2.7.0.
- Update the cogment api to v1.0.0 to v1.2.1

### Fixed

- Added expanation for strict 1.38 requirement on grpcio-tools.
- Enable pre-trial hooks to set a trial's environment's implementation in `prehook_session.environment_implementation`.

## v1.3.0 - 2021-09-23

### Added

- Add `python -m cogment.generate` to compile the protobuf files and generate `cog_settings.py` for a cogment project.
  This is designed as a replacement for the `cogment generate` command for python cogment components.

### Changed

- Update grpc version used to 1.38.1
- Better management of exception in user implementation coroutine

## v1.2.0 - 2021-06-23

### Changed

- The default Prometheus registry is now used by default, it was previously a custom built registry.
  Furthermore, any prometheus registry can be passed to the constructor for `cogment.Context`.
  If `None` is passed prometheus metrics are disabled entirely.
- Passing `None` as the `prometheus_port` in the constructor for `cogment.Context` disables the launch of the Prometheus server.

## v1.1.1 - 2021-06-17

### Changed

- Update copyright notice to use the legal name of AI Redefined Inc.

### Fixed

- Exit datalog loop on receiving the trial `ended` state
- Simulatenous trials with client actors
- Fix index in RecvAction to match the actor list

## v1.1.0 - 2021-06-04

### Changed

- Internal update to change `assert` into more useful statements
- Internal update to add `__str__` to user accessible classes
- Improve log output
- Improve/add error reporting

### Added

- Add function `get_remote_versions` to controller retrieving the remote versions including api and orchestrator versions.

## v1.0.0 - 2021-05-10

- Initial public release.

### Changed

- Using _caret_ requirements for the dependencies of the library to avoid conflicts (cf. https://python-poetry.org/docs/dependency-specification/#caret-requirements)

### Fixed

- Environment can now receive messages

## v1.0.0-beta3 - 2021-04-26

### Fixed

- **Breaking Change** Fix `Controller.get_actors()`, now properly retrieves the actor in a given trial, the function is now `async`.
- Fix unecessary exception thrown in `watch_trial` when async is cancelled

### Added

- Add `Controller.get_trial_info()` to retrieve the information of a given trial.

## v1.0.0-beta2 - 2021-04-15

### Changed

- Add a bit of code to make sure we are running in an asyncio task
- `EventType.FINAL` events do not contain data anymore
- Fix when replies are `None`
- Add `raw_trial_params` in the datalog session

### Fixed

- actor implementations metrics are now reported under `impl_name`

## v1.0.0-beta1 - 2021-04-07

- Initial beta release, no more breaking changes should be introduced.

## v1.0.0-alpha12 - 2021-04-01

### Changed

- Rename ActorClass `id` to `name`

### Fixed

- Remove unused `feedback_space` parameters from `ActorClass`.

## v1.0.0-alpha11 - 2021-03-30

- Technical release, updating dependencies to fixed versions.

## v1.0.0-alpha10 - 2021-03-30

### Added

- Log exporter is now available: trials param, observations, rewards, messages of every trials are sent to the log exporter service.

### Changed

- The value returned from a `RecvReward.all_source` is now a class `RecvRewardSource` instead of a tuple
- Removed parameter `user_id` from `start_trial` (it was not necessary)

## v1.0.0-alpha9 - 2021-03-10

### Added

- **Breaking** Introduce `Controller`, built for a given orchestrator endpoint it can be used to start and terminate trials. Previous ways of accessing the same such are discontinued.
- Introduce the ability to listen for trial events (startup, ending, ...) using `Controller.watch_trials`.

## v1.0.0-alpha8 - 2021-02-26

### Changed

- Session event loops now return classes

## v1.0.0-alpha7 - 2021-02-19

## v1.0.0-alpha6 - 2021-02-17

### Changed

- Removal of "feedback" in rewards.
- Changes to allow for TLS communication.

## v1.0.0-alpha5 - 2021-01-28

### Added

- Manage errors and exceptions at end of trial
- Debug logging at critical points
- Add access to the complete actor configuration from prehook implementations

### Fixed

- Fix the instanciation of prehooks
- Fix the environment "Final" flag not being set in some cases

## v1.0.0-alpha4 - 2021-01-26

### Added

- Catching exceptions that normally occur at the end of trials

### Fixed

- Fix a crash occuring at the end of a trial in service actor implementations involving a `KeyError`.
- tick_id was not being updated

## v1.0.0-alpha3 - 2021-01-11

### Changed

- Create better errors around handling of implementation names

### Added

- Support messsages
- Avoid silent crashes by catching and logging exceptions thrown in async task and user code
- Cancel tasks properly when they raise exceptions
- Debug logging in strategic places

### Fixed

- Send actions list to environment (as documented)
- Store actor class name (string) for user facing session value and hide internal data
- Client servicer code
- Fix prometheus server

## v1.0.0-alpha2 - 2020-12-09

### Fixed

- Add missing cogment protobuf api files to the generated package.

## v1.0.0-alpha1 - 2020-12-07

- Initial alpha release, expect some breaking changes.


%package -n python3-cogment
Summary:	Cogment python SDK
Provides:	python-cogment
BuildRequires:	python3-devel
BuildRequires:	python3-setuptools
BuildRequires:	python3-pip
%description -n python3-cogment
# cogment-py-sdk

[![Latest final release](https://img.shields.io/pypi/v/cogment?style=flat-square)](https://pypi.org/project/cogment/) [![Apache 2 License](https://img.shields.io/badge/license-Apache%202-green?style=flat-square)](./LICENSE) [![Changelog](https://img.shields.io/badge/-Changelog%20-blueviolet?style=flat-square)](./CHANGELOG.md)

[Cogment](https://cogment.ai) 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](https://ai-r.com). 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](https://www.python.org) >=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:

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

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

```console
$ deactivate
```

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

```console
$ 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)

```console
$ 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.

```console
$ 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:

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

### Lint

Run the `pycodestyle` using

```console
$ pycodestyle
```

Run the `mypy` type annotations checks using

```console
$ mypy cogment/
```

### Check conflicting dependencies with "popular" Python packages

```console
./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

Build the source package

```console
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](http://semver.org/spec/v2.0.0.html).

1. Run `./scripts/create_release_branch.sh MAJOR.MINOR.PATCH` to create the release branch and update the version of the package,
2. On the release branch, check and update the changelog if needed,
3. Make sure `./.cogment-api.yaml` specifies fixed version to ensure rebuildability,
4. Make sure everything's fine on CI,
5. 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.

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

## Unreleased

## v2.8.1 - 2023-06-06

## Fixed

- Use the most recent directory entry when there are duplicates
- Self IP address discovery functionality is now working on macOS

## v2.8.0 - 2023-04-21

### Added

- Option to request full info (not just id and state) from 'watch_trials'
- Ability to use the SDK without spec (cog_settings)
- Automatic port selection for 'Context.serve_all_registered()'
- Ability to specify an explicit host to register a service to the directory
- Ability to specify trial properties for 'Datastore.all_trials()' and 'Datastore.get_trials()'
- Ability to specify trial ids for 'Datastore.all_trials()'

### Changed

- Enable warning and error logging even if user did not define a logging handler
- Warn user when no logging handler is defined (i.e. proper logging is disabled)
- Better self IP address discovery functionality

## v2.7.1 - 2023-03-06

## Fixed

- Deadlock in 'wait_for_newer' method of LatestModel

## v2.7.0 - 2023-02-28

### Changed

- Facility to track latest models automatically in the Model Registry

### Added

- 'properties' attribute to TrialParameters and TrialInfo

## v2.6.0 - 2023-02-03

### Changed

- Prometheus service is disabled by default

### Added

- Model Registry method `iteration_updates` to stream/push new model iterations
- Parameter `wait_for_trials` (for Datastore method `all_trials`) to wait for new trials

## v2.5.0 - 2023-01-26

## Fixed

- In Datastore reward could be returned as 'None' instead of 0.0

### Added

- Simplified interface for Model Registry (context.get_model_registry_v2)

## v2.4.1 - 2022-12-02

- Support and dependency check for python 3.10

## v2.4.0 - 2022-11-18

### Added

- 'COGMENT_LOG_LEVEL' environment variable
- Model Registry client

## Fixed

- Port parameter needs to be an int
- Context datastore request with default endpoint

## v2.3.0 - 2022-09-20

## Fixed

- Reward tick ID was hard coded to -1

### Changed

- Deprecation warning are only logged once

### Added

- 'Version' grpc method for pre-trial hooks
- Out-of-sync flag in datalog samples
- Parameter 'nb_buffered_ticks'
- Support for actor disconnection and response timeout parameters
- Global Directory integration
- Support for self registration to the Directory
- Use environment variable for Directory access details

## v2.2.2 - 2022-06-20

## Fixed

- Generate to handle multiple imports properly
- Output deprecated warning for use of 'snapshot' in received observation

## v2.2.1 - 2022-05-27

## Fixed

- Fix install of the package from a wheel

### Changed

- Replace poetry centric build process with modern setuptools

## v2.2.0 - 2022-05-07

### Added

- Introduce `cogment.generate.generate`, a function making the code generation previously available through `python -m cogment.generate` accessible as a function.

### Changed

- Integration tests are now able to install the Cogment CLI on their own.
- Integration tests no longer uses a Docker image.

## Fixed

- Fix integration test junit report output.

## v2.1.1 - 2022-04-11

## Fixed

- Fixed a typo in the TrialParameter "environemnt_name" to "environment_name"

## v2.1.0 - 2022-03-25

### Changed

- Update of gRPC version to >=1.42 & <1.45
- Deprecate `cogment.LogParams`
- Deprecate current way to use `PrehookSession`
- Deprecate Session 'event_loop', renamed to 'all_events'
- Deprecate DatalogSession 'get_all_samples' renamed 'all_samples'
- Standardize string ouput of classes

### Added

- `cogment.TrialParameters` and `cogment.ActorParameters`
- Add ability to provide parameters on trial start call
- Datastore SDK

## Fixed

- Fix the failure of the cogment package caused by the partial removal of gRPC 1.45 from pypi

## v2.0.2 - 2022-01-03

## v2.0.1 - 2022-01-03

## v2.0.0 - 2022-01-03

## v2.0.0-rc3 - 2021-12-16

### Changed

- cogment.generate now requires semantic arguments

## v2.0.0-rc2 - 2021-12-10

### Changed

- Cleanup user output
- Require grpc protocol url for endpoints

## v2.0.0-rc1 - 2021-12-01

### Changed

- Major internal changes to match API 2.0
- Minor use changes to match API 2.0 and improve usability

## v1.3.1 - 2021-11-18

### Changed

- Restrict the SDK to python >= 3.7 and <3.10 to maintain compatiblity with tensorflow ^2.7.0.
- Update the cogment api to v1.0.0 to v1.2.1

### Fixed

- Added expanation for strict 1.38 requirement on grpcio-tools.
- Enable pre-trial hooks to set a trial's environment's implementation in `prehook_session.environment_implementation`.

## v1.3.0 - 2021-09-23

### Added

- Add `python -m cogment.generate` to compile the protobuf files and generate `cog_settings.py` for a cogment project.
  This is designed as a replacement for the `cogment generate` command for python cogment components.

### Changed

- Update grpc version used to 1.38.1
- Better management of exception in user implementation coroutine

## v1.2.0 - 2021-06-23

### Changed

- The default Prometheus registry is now used by default, it was previously a custom built registry.
  Furthermore, any prometheus registry can be passed to the constructor for `cogment.Context`.
  If `None` is passed prometheus metrics are disabled entirely.
- Passing `None` as the `prometheus_port` in the constructor for `cogment.Context` disables the launch of the Prometheus server.

## v1.1.1 - 2021-06-17

### Changed

- Update copyright notice to use the legal name of AI Redefined Inc.

### Fixed

- Exit datalog loop on receiving the trial `ended` state
- Simulatenous trials with client actors
- Fix index in RecvAction to match the actor list

## v1.1.0 - 2021-06-04

### Changed

- Internal update to change `assert` into more useful statements
- Internal update to add `__str__` to user accessible classes
- Improve log output
- Improve/add error reporting

### Added

- Add function `get_remote_versions` to controller retrieving the remote versions including api and orchestrator versions.

## v1.0.0 - 2021-05-10

- Initial public release.

### Changed

- Using _caret_ requirements for the dependencies of the library to avoid conflicts (cf. https://python-poetry.org/docs/dependency-specification/#caret-requirements)

### Fixed

- Environment can now receive messages

## v1.0.0-beta3 - 2021-04-26

### Fixed

- **Breaking Change** Fix `Controller.get_actors()`, now properly retrieves the actor in a given trial, the function is now `async`.
- Fix unecessary exception thrown in `watch_trial` when async is cancelled

### Added

- Add `Controller.get_trial_info()` to retrieve the information of a given trial.

## v1.0.0-beta2 - 2021-04-15

### Changed

- Add a bit of code to make sure we are running in an asyncio task
- `EventType.FINAL` events do not contain data anymore
- Fix when replies are `None`
- Add `raw_trial_params` in the datalog session

### Fixed

- actor implementations metrics are now reported under `impl_name`

## v1.0.0-beta1 - 2021-04-07

- Initial beta release, no more breaking changes should be introduced.

## v1.0.0-alpha12 - 2021-04-01

### Changed

- Rename ActorClass `id` to `name`

### Fixed

- Remove unused `feedback_space` parameters from `ActorClass`.

## v1.0.0-alpha11 - 2021-03-30

- Technical release, updating dependencies to fixed versions.

## v1.0.0-alpha10 - 2021-03-30

### Added

- Log exporter is now available: trials param, observations, rewards, messages of every trials are sent to the log exporter service.

### Changed

- The value returned from a `RecvReward.all_source` is now a class `RecvRewardSource` instead of a tuple
- Removed parameter `user_id` from `start_trial` (it was not necessary)

## v1.0.0-alpha9 - 2021-03-10

### Added

- **Breaking** Introduce `Controller`, built for a given orchestrator endpoint it can be used to start and terminate trials. Previous ways of accessing the same such are discontinued.
- Introduce the ability to listen for trial events (startup, ending, ...) using `Controller.watch_trials`.

## v1.0.0-alpha8 - 2021-02-26

### Changed

- Session event loops now return classes

## v1.0.0-alpha7 - 2021-02-19

## v1.0.0-alpha6 - 2021-02-17

### Changed

- Removal of "feedback" in rewards.
- Changes to allow for TLS communication.

## v1.0.0-alpha5 - 2021-01-28

### Added

- Manage errors and exceptions at end of trial
- Debug logging at critical points
- Add access to the complete actor configuration from prehook implementations

### Fixed

- Fix the instanciation of prehooks
- Fix the environment "Final" flag not being set in some cases

## v1.0.0-alpha4 - 2021-01-26

### Added

- Catching exceptions that normally occur at the end of trials

### Fixed

- Fix a crash occuring at the end of a trial in service actor implementations involving a `KeyError`.
- tick_id was not being updated

## v1.0.0-alpha3 - 2021-01-11

### Changed

- Create better errors around handling of implementation names

### Added

- Support messsages
- Avoid silent crashes by catching and logging exceptions thrown in async task and user code
- Cancel tasks properly when they raise exceptions
- Debug logging in strategic places

### Fixed

- Send actions list to environment (as documented)
- Store actor class name (string) for user facing session value and hide internal data
- Client servicer code
- Fix prometheus server

## v1.0.0-alpha2 - 2020-12-09

### Fixed

- Add missing cogment protobuf api files to the generated package.

## v1.0.0-alpha1 - 2020-12-07

- Initial alpha release, expect some breaking changes.


%package help
Summary:	Development documents and examples for cogment
Provides:	python3-cogment-doc
%description help
# cogment-py-sdk

[![Latest final release](https://img.shields.io/pypi/v/cogment?style=flat-square)](https://pypi.org/project/cogment/) [![Apache 2 License](https://img.shields.io/badge/license-Apache%202-green?style=flat-square)](./LICENSE) [![Changelog](https://img.shields.io/badge/-Changelog%20-blueviolet?style=flat-square)](./CHANGELOG.md)

[Cogment](https://cogment.ai) 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](https://ai-r.com). 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](https://www.python.org) >=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:

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

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

```console
$ deactivate
```

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

```console
$ 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)

```console
$ 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.

```console
$ 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:

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

### Lint

Run the `pycodestyle` using

```console
$ pycodestyle
```

Run the `mypy` type annotations checks using

```console
$ mypy cogment/
```

### Check conflicting dependencies with "popular" Python packages

```console
./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

Build the source package

```console
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](http://semver.org/spec/v2.0.0.html).

1. Run `./scripts/create_release_branch.sh MAJOR.MINOR.PATCH` to create the release branch and update the version of the package,
2. On the release branch, check and update the changelog if needed,
3. Make sure `./.cogment-api.yaml` specifies fixed version to ensure rebuildability,
4. Make sure everything's fine on CI,
5. 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.

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).

## Unreleased

## v2.8.1 - 2023-06-06

## Fixed

- Use the most recent directory entry when there are duplicates
- Self IP address discovery functionality is now working on macOS

## v2.8.0 - 2023-04-21

### Added

- Option to request full info (not just id and state) from 'watch_trials'
- Ability to use the SDK without spec (cog_settings)
- Automatic port selection for 'Context.serve_all_registered()'
- Ability to specify an explicit host to register a service to the directory
- Ability to specify trial properties for 'Datastore.all_trials()' and 'Datastore.get_trials()'
- Ability to specify trial ids for 'Datastore.all_trials()'

### Changed

- Enable warning and error logging even if user did not define a logging handler
- Warn user when no logging handler is defined (i.e. proper logging is disabled)
- Better self IP address discovery functionality

## v2.7.1 - 2023-03-06

## Fixed

- Deadlock in 'wait_for_newer' method of LatestModel

## v2.7.0 - 2023-02-28

### Changed

- Facility to track latest models automatically in the Model Registry

### Added

- 'properties' attribute to TrialParameters and TrialInfo

## v2.6.0 - 2023-02-03

### Changed

- Prometheus service is disabled by default

### Added

- Model Registry method `iteration_updates` to stream/push new model iterations
- Parameter `wait_for_trials` (for Datastore method `all_trials`) to wait for new trials

## v2.5.0 - 2023-01-26

## Fixed

- In Datastore reward could be returned as 'None' instead of 0.0

### Added

- Simplified interface for Model Registry (context.get_model_registry_v2)

## v2.4.1 - 2022-12-02

- Support and dependency check for python 3.10

## v2.4.0 - 2022-11-18

### Added

- 'COGMENT_LOG_LEVEL' environment variable
- Model Registry client

## Fixed

- Port parameter needs to be an int
- Context datastore request with default endpoint

## v2.3.0 - 2022-09-20

## Fixed

- Reward tick ID was hard coded to -1

### Changed

- Deprecation warning are only logged once

### Added

- 'Version' grpc method for pre-trial hooks
- Out-of-sync flag in datalog samples
- Parameter 'nb_buffered_ticks'
- Support for actor disconnection and response timeout parameters
- Global Directory integration
- Support for self registration to the Directory
- Use environment variable for Directory access details

## v2.2.2 - 2022-06-20

## Fixed

- Generate to handle multiple imports properly
- Output deprecated warning for use of 'snapshot' in received observation

## v2.2.1 - 2022-05-27

## Fixed

- Fix install of the package from a wheel

### Changed

- Replace poetry centric build process with modern setuptools

## v2.2.0 - 2022-05-07

### Added

- Introduce `cogment.generate.generate`, a function making the code generation previously available through `python -m cogment.generate` accessible as a function.

### Changed

- Integration tests are now able to install the Cogment CLI on their own.
- Integration tests no longer uses a Docker image.

## Fixed

- Fix integration test junit report output.

## v2.1.1 - 2022-04-11

## Fixed

- Fixed a typo in the TrialParameter "environemnt_name" to "environment_name"

## v2.1.0 - 2022-03-25

### Changed

- Update of gRPC version to >=1.42 & <1.45
- Deprecate `cogment.LogParams`
- Deprecate current way to use `PrehookSession`
- Deprecate Session 'event_loop', renamed to 'all_events'
- Deprecate DatalogSession 'get_all_samples' renamed 'all_samples'
- Standardize string ouput of classes

### Added

- `cogment.TrialParameters` and `cogment.ActorParameters`
- Add ability to provide parameters on trial start call
- Datastore SDK

## Fixed

- Fix the failure of the cogment package caused by the partial removal of gRPC 1.45 from pypi

## v2.0.2 - 2022-01-03

## v2.0.1 - 2022-01-03

## v2.0.0 - 2022-01-03

## v2.0.0-rc3 - 2021-12-16

### Changed

- cogment.generate now requires semantic arguments

## v2.0.0-rc2 - 2021-12-10

### Changed

- Cleanup user output
- Require grpc protocol url for endpoints

## v2.0.0-rc1 - 2021-12-01

### Changed

- Major internal changes to match API 2.0
- Minor use changes to match API 2.0 and improve usability

## v1.3.1 - 2021-11-18

### Changed

- Restrict the SDK to python >= 3.7 and <3.10 to maintain compatiblity with tensorflow ^2.7.0.
- Update the cogment api to v1.0.0 to v1.2.1

### Fixed

- Added expanation for strict 1.38 requirement on grpcio-tools.
- Enable pre-trial hooks to set a trial's environment's implementation in `prehook_session.environment_implementation`.

## v1.3.0 - 2021-09-23

### Added

- Add `python -m cogment.generate` to compile the protobuf files and generate `cog_settings.py` for a cogment project.
  This is designed as a replacement for the `cogment generate` command for python cogment components.

### Changed

- Update grpc version used to 1.38.1
- Better management of exception in user implementation coroutine

## v1.2.0 - 2021-06-23

### Changed

- The default Prometheus registry is now used by default, it was previously a custom built registry.
  Furthermore, any prometheus registry can be passed to the constructor for `cogment.Context`.
  If `None` is passed prometheus metrics are disabled entirely.
- Passing `None` as the `prometheus_port` in the constructor for `cogment.Context` disables the launch of the Prometheus server.

## v1.1.1 - 2021-06-17

### Changed

- Update copyright notice to use the legal name of AI Redefined Inc.

### Fixed

- Exit datalog loop on receiving the trial `ended` state
- Simulatenous trials with client actors
- Fix index in RecvAction to match the actor list

## v1.1.0 - 2021-06-04

### Changed

- Internal update to change `assert` into more useful statements
- Internal update to add `__str__` to user accessible classes
- Improve log output
- Improve/add error reporting

### Added

- Add function `get_remote_versions` to controller retrieving the remote versions including api and orchestrator versions.

## v1.0.0 - 2021-05-10

- Initial public release.

### Changed

- Using _caret_ requirements for the dependencies of the library to avoid conflicts (cf. https://python-poetry.org/docs/dependency-specification/#caret-requirements)

### Fixed

- Environment can now receive messages

## v1.0.0-beta3 - 2021-04-26

### Fixed

- **Breaking Change** Fix `Controller.get_actors()`, now properly retrieves the actor in a given trial, the function is now `async`.
- Fix unecessary exception thrown in `watch_trial` when async is cancelled

### Added

- Add `Controller.get_trial_info()` to retrieve the information of a given trial.

## v1.0.0-beta2 - 2021-04-15

### Changed

- Add a bit of code to make sure we are running in an asyncio task
- `EventType.FINAL` events do not contain data anymore
- Fix when replies are `None`
- Add `raw_trial_params` in the datalog session

### Fixed

- actor implementations metrics are now reported under `impl_name`

## v1.0.0-beta1 - 2021-04-07

- Initial beta release, no more breaking changes should be introduced.

## v1.0.0-alpha12 - 2021-04-01

### Changed

- Rename ActorClass `id` to `name`

### Fixed

- Remove unused `feedback_space` parameters from `ActorClass`.

## v1.0.0-alpha11 - 2021-03-30

- Technical release, updating dependencies to fixed versions.

## v1.0.0-alpha10 - 2021-03-30

### Added

- Log exporter is now available: trials param, observations, rewards, messages of every trials are sent to the log exporter service.

### Changed

- The value returned from a `RecvReward.all_source` is now a class `RecvRewardSource` instead of a tuple
- Removed parameter `user_id` from `start_trial` (it was not necessary)

## v1.0.0-alpha9 - 2021-03-10

### Added

- **Breaking** Introduce `Controller`, built for a given orchestrator endpoint it can be used to start and terminate trials. Previous ways of accessing the same such are discontinued.
- Introduce the ability to listen for trial events (startup, ending, ...) using `Controller.watch_trials`.

## v1.0.0-alpha8 - 2021-02-26

### Changed

- Session event loops now return classes

## v1.0.0-alpha7 - 2021-02-19

## v1.0.0-alpha6 - 2021-02-17

### Changed

- Removal of "feedback" in rewards.
- Changes to allow for TLS communication.

## v1.0.0-alpha5 - 2021-01-28

### Added

- Manage errors and exceptions at end of trial
- Debug logging at critical points
- Add access to the complete actor configuration from prehook implementations

### Fixed

- Fix the instanciation of prehooks
- Fix the environment "Final" flag not being set in some cases

## v1.0.0-alpha4 - 2021-01-26

### Added

- Catching exceptions that normally occur at the end of trials

### Fixed

- Fix a crash occuring at the end of a trial in service actor implementations involving a `KeyError`.
- tick_id was not being updated

## v1.0.0-alpha3 - 2021-01-11

### Changed

- Create better errors around handling of implementation names

### Added

- Support messsages
- Avoid silent crashes by catching and logging exceptions thrown in async task and user code
- Cancel tasks properly when they raise exceptions
- Debug logging in strategic places

### Fixed

- Send actions list to environment (as documented)
- Store actor class name (string) for user facing session value and hide internal data
- Client servicer code
- Fix prometheus server

## v1.0.0-alpha2 - 2020-12-09

### Fixed

- Add missing cogment protobuf api files to the generated package.

## v1.0.0-alpha1 - 2020-12-07

- Initial alpha release, expect some breaking changes.


%prep
%autosetup -n cogment-2.8.1

%build
%py3_build

%install
%py3_install
install -d -m755 %{buildroot}/%{_pkgdocdir}
if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi
if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi
if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi
if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi
pushd %{buildroot}
if [ -d usr/lib ]; then
	find usr/lib -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/lib64 ]; then
	find usr/lib64 -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/bin ]; then
	find usr/bin -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
if [ -d usr/sbin ]; then
	find usr/sbin -type f -printf "\"/%h/%f\"\n" >> filelist.lst
fi
touch doclist.lst
if [ -d usr/share/man ]; then
	find usr/share/man -type f -printf "\"/%h/%f.gz\"\n" >> doclist.lst
fi
popd
mv %{buildroot}/filelist.lst .
mv %{buildroot}/doclist.lst .

%files -n python3-cogment -f filelist.lst
%dir %{python3_sitelib}/*

%files help -f doclist.lst
%{_docdir}/*

%changelog
* Thu Jun 08 2023 Python_Bot <Python_Bot@openeuler.org> - 2.8.1-1
- Package Spec generated