%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 [![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 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 . ## 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 [![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 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 . ## 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 [![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 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 . ## 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 * Tue May 30 2023 Python_Bot - 2.8.0-1 - Package Spec generated