diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-cogment.spec | 1567 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 1569 insertions, 0 deletions
@@ -0,0 +1 @@ +/cogment-2.8.0.tar.gz diff --git a/python-cogment.spec b/python-cogment.spec new file mode 100644 index 0000000..c78fd2a --- /dev/null +++ b/python-cogment.spec @@ -0,0 +1,1567 @@ +%global _empty_manifest_terminate_build 0 +Name: python-cogment +Version: 2.8.0 +Release: 1 +Summary: Cogment python SDK +License: Apache Software License +URL: https://cogment.ai +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/b9/53/c3181c668e83baff92053de071b3aba8ef3f671a850b834f523c7c801a23/cogment-2.8.0.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 + +[](https://pypi.org/project/cogment/) [](./LICENSE) [](./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.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 + +[](https://pypi.org/project/cogment/) [](./LICENSE) [](./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.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 + +[](https://pypi.org/project/cogment/) [](./LICENSE) [](./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.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.0 + +%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 +* Mon May 15 2023 Python_Bot <Python_Bot@openeuler.org> - 2.8.0-1 +- Package Spec generated @@ -0,0 +1 @@ +a21728d0e202e419e887c140d4636fc9 cogment-2.8.0.tar.gz |