Package: cogment
cogment-py-sdkCogmentis an innovative open source AI platform designed to leverage the advent of AI to benefit humankind through human-AI collaboration developed byAI Redefined. Cogment enables AI researchers and engineers to build, train and operate AI agents in simulated or real environments shared with humans. For the full user documentation visithttps://docs.cogment.aiThis module,cogment-py-sdk, is the Python SDK for making use of Cogment when working with Python. It's full documentation can be consulted athttps://docs.cogment.ai/cogment/cogment-api-reference/python/.DevelopersPrerequisitesMake sure you have the following installed:Python>=3.7, <3.11Install dependenciesWe recommend using a virtualenv to isolate your dependencies. On most unix flavors you create and activate this by running the following:$python-mvenv.venv$source.venv/bin/activateonce you are finished with the virtualenv you can deactivate it by running:$deactivateInstall the dependencies, including downloading and building the cogment protobuf API by running the following:$pipinstall-rrequirements.txt$python-msetupdevelopThe second line will call the followingsetup.pycommands to deal with the cogment API (those can also be called seprately)$python-msetupretrieve_cogment_api$python-msetupbuild_cogment_api_protosDefine used Cogment protobuf APIThe version of the used cogment protobuf API is defined in the.cogment-api.yamlfile at the root of the repository. The following can be defined:cogment_version: "latest", is the default, it retrieves the api from thelatestCogment 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.protoshould be at${cogment_api_path}/common.proto); if set, this overridescogment_version.After any change, do not forget to runpip install -e .for it to be taken into account.TestsIntegration testsThese tests launch and use Cogment, by default they'll use they'll download and use the latest released version of Cogment.$pytest--launch-orchestratorThe following environment can be defined to change this behavior, either directly in the terminal or in a.envfile located at the root of the repository:COGMENT_PATH="/path/to/cogment"# local path to cogment binaryCOGMENT_VERSION="v2.2.0"# cogment version to downloadLintRun thepycodestyleusing$pycodestyleRun themypytype annotations checks using$mypy.Check conflicting dependencies with "popular" Python packages./scripts/check_dependencies_conflicts.shThis 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 packageBuild the source packagepython -m buildRelease processPeople having mainteners rights of the repository can follow these steps to release a versionMAJOR.MINOR.PATCH. The versioning scheme followsSemantic Versioning.Run./scripts/create_release_branch.sh MAJOR.MINOR.PATCHto create the release branch and update the version of the package,On the release branch, check and update the changelog if needed,Make sure./.cogment-api.yamlspecifies fixed version to ensure rebuildability,Make sure everything's fine on CI,Run./scripts/tag_release.sh MAJOR.MINOR.PATCHto create the specific version section in the changelog, merge the release branch inmain, create the release tag and update thedevelopbranch with those.The rest, publishing the package to PyPI and updating the mirror repositories, is handled directly by the CI.ChangelogAll notable changes to this project will be documented in this file.The format is based onKeep a Changelogand this project adheres toSemantic Versioning.Unreleasedv2.10.1 - 2024-01-06FixedUpdatesgrpcioto work with python 3.10 on macOS.v2.10.0 - 2023-11-28AddedAbility to define metadata in theContextconstructor, they will be passed to all grpc calls.Support for SSL grpc endpoints without a private key.Fixedcontext.get_controller([...]),context.get_datastore([...]),context.get_model_registry_v2([...])can always be awaited.v2.9.0 - 2023-11-14Added'Status' RPC support for all servicesFixedMissing directory service type in APIv2.8.3 - 2023-08-22FixedUpgraded to support PyYaml up to 6.0.1 asv5 was brokenby the release of cython 3.v2.8.2 - 2023-07-10FixedReturn None when no data is availble in datastore contentv2.8.1 - 2023-06-06FixedUse the most recent directory entry when there are duplicatesSelf IP address discovery functionality is now working on macOSv2.8.0 - 2023-04-21AddedOption 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 directoryAbility to specify trial properties for 'Datastore.all_trials()' and 'Datastore.get_trials()'Ability to specify trial ids for 'Datastore.all_trials()'ChangedEnable warning and error logging even if user did not define a logging handlerWarn user when no logging handler is defined (i.e. proper logging is disabled)Better self IP address discovery functionalityv2.7.1 - 2023-03-06FixedDeadlock in 'wait_for_newer' method of LatestModelv2.7.0 - 2023-02-28ChangedFacility to track latest models automatically in the Model RegistryAdded'properties' attribute to TrialParameters and TrialInfov2.6.0 - 2023-02-03ChangedPrometheus service is disabled by defaultAddedModel Registry methoditeration_updatesto stream/push new model iterationsParameterwait_for_trials(for Datastore methodall_trials) to wait for new trialsv2.5.0 - 2023-01-26FixedIn Datastore reward could be returned as 'None' instead of 0.0AddedSimplified interface for Model Registry (context.get_model_registry_v2)v2.4.1 - 2022-12-02Support and dependency check for python 3.10v2.4.0 - 2022-11-18Added'COGMENT_LOG_LEVEL' environment variableModel Registry clientFixedPort parameter needs to be an intContext datastore request with default endpointv2.3.0 - 2022-09-20FixedReward tick ID was hard coded to -1ChangedDeprecation warning are only logged onceAdded'Version' grpc method for pre-trial hooksOut-of-sync flag in datalog samplesParameter 'nb_buffered_ticks'Support for actor disconnection and response timeout parametersGlobal Directory integrationSupport for self registration to the DirectoryUse environment variable for Directory access detailsv2.2.2 - 2022-06-20FixedGenerate to handle multiple imports properlyOutput deprecated warning for use of 'snapshot' in received observationv2.2.1 - 2022-05-27FixedFix install of the package from a wheelChangedReplace poetry centric build process with modern setuptoolsv2.2.0 - 2022-05-07AddedIntroducecogment.generate.generate, a function making the code generation previously available throughpython -m cogment.generateaccessible as a function.ChangedIntegration tests are now able to install the Cogment CLI on their own.Integration tests no longer uses a Docker image.FixedFix integration test junit report output.v2.1.1 - 2022-04-11FixedFixed a typo in the TrialParameter "environemnt_name" to "environment_name"v2.1.0 - 2022-03-25ChangedUpdate of gRPC version to >=1.42 & <1.45Deprecatecogment.LogParamsDeprecate current way to usePrehookSessionDeprecate Session 'event_loop', renamed to 'all_events'Deprecate DatalogSession 'get_all_samples' renamed 'all_samples'Standardize string ouput of classesAddedcogment.TrialParametersandcogment.ActorParametersAdd ability to provide parameters on trial start callDatastore SDKFixedFix the failure of the cogment package caused by the partial removal of gRPC 1.45 from pypiv2.0.2 - 2022-01-03v2.0.1 - 2022-01-03v2.0.0 - 2022-01-03v2.0.0-rc3 - 2021-12-16Changedcogment.generate now requires semantic argumentsv2.0.0-rc2 - 2021-12-10ChangedCleanup user outputRequire grpc protocol url for endpointsv2.0.0-rc1 - 2021-12-01ChangedMajor internal changes to match API 2.0Minor use changes to match API 2.0 and improve usabilityv1.3.1 - 2021-11-18ChangedRestrict 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.1FixedAdded expanation for strict 1.38 requirement on grpcio-tools.Enable pre-trial hooks to set a trial's environment's implementation inprehook_session.environment_implementation.v1.3.0 - 2021-09-23AddedAddpython -m cogment.generateto compile the protobuf files and generatecog_settings.pyfor a cogment project.
This is designed as a replacement for thecogment generatecommand for python cogment components.ChangedUpdate grpc version used to 1.38.1Better management of exception in user implementation coroutinev1.2.0 - 2021-06-23ChangedThe 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 forcogment.Context.
IfNoneis passed prometheus metrics are disabled entirely.PassingNoneas theprometheus_portin the constructor forcogment.Contextdisables the launch of the Prometheus server.v1.1.1 - 2021-06-17ChangedUpdate copyright notice to use the legal name of AI Redefined Inc.FixedExit datalog loop on receiving the trialendedstateSimulatenous trials with client actorsFix index in RecvAction to match the actor listv1.1.0 - 2021-06-04ChangedInternal update to changeassertinto more useful statementsInternal update to add__str__to user accessible classesImprove log outputImprove/add error reportingAddedAdd functionget_remote_versionsto controller retrieving the remote versions including api and orchestrator versions.v1.0.0 - 2021-05-10Initial public release.ChangedUsingcaretrequirements for the dependencies of the library to avoid conflicts (cf.https://python-poetry.org/docs/dependency-specification/#caret-requirements)FixedEnvironment can now receive messagesv1.0.0-beta3 - 2021-04-26FixedBreaking ChangeFixController.get_actors(), now properly retrieves the actor in a given trial, the function is nowasync.Fix unecessary exception thrown inwatch_trialwhen async is cancelledAddedAddController.get_trial_info()to retrieve the information of a given trial.v1.0.0-beta2 - 2021-04-15ChangedAdd a bit of code to make sure we are running in an asyncio taskEventType.FINALevents do not contain data anymoreFix when replies areNoneAddraw_trial_paramsin the datalog sessionFixedactor implementations metrics are now reported underimpl_namev1.0.0-beta1 - 2021-04-07Initial beta release, no more breaking changes should be introduced.v1.0.0-alpha12 - 2021-04-01ChangedRename ActorClassidtonameFixedRemove unusedfeedback_spaceparameters fromActorClass.v1.0.0-alpha11 - 2021-03-30Technical release, updating dependencies to fixed versions.v1.0.0-alpha10 - 2021-03-30AddedLog exporter is now available: trials param, observations, rewards, messages of every trials are sent to the log exporter service.ChangedThe value returned from aRecvReward.all_sourceis now a classRecvRewardSourceinstead of a tupleRemoved parameteruser_idfromstart_trial(it was not necessary)v1.0.0-alpha9 - 2021-03-10AddedBreakingIntroduceController, 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, ...) usingController.watch_trials.v1.0.0-alpha8 - 2021-02-26ChangedSession event loops now return classesv1.0.0-alpha7 - 2021-02-19v1.0.0-alpha6 - 2021-02-17ChangedRemoval of "feedback" in rewards.Changes to allow for TLS communication.v1.0.0-alpha5 - 2021-01-28AddedManage errors and exceptions at end of trialDebug logging at critical pointsAdd access to the complete actor configuration from prehook implementationsFixedFix the instanciation of prehooksFix the environment "Final" flag not being set in some casesv1.0.0-alpha4 - 2021-01-26AddedCatching exceptions that normally occur at the end of trialsFixedFix a crash occuring at the end of a trial in service actor implementations involving aKeyError.tick_id was not being updatedv1.0.0-alpha3 - 2021-01-11ChangedCreate better errors around handling of implementation namesAddedSupport messsagesAvoid silent crashes by catching and logging exceptions thrown in async task and user codeCancel tasks properly when they raise exceptionsDebug logging in strategic placesFixedSend actions list to environment (as documented)Store actor class name (string) for user facing session value and hide internal dataClient servicer codeFix prometheus serverv1.0.0-alpha2 - 2020-12-09FixedAdd missing cogment protobuf api files to the generated package.v1.0.0-alpha1 - 2020-12-07Initial alpha release, expect some breaking changes.