The spec file (typically named
cogment.yaml) is central to every Cogment project that use a Cogment SDK. This file is used to define the specifics of a type of trials. It can also contain data (the
commands section) used by the Cogment CLI tool. A generator tool specific to each SDK takes this file as its main input to, among other things, configure the SDK.
The top level sections in the file are:
- import: Used to import other proto files into the definition of the project
- commands: Optional. Defines commands that can be run by the Cogment CLI
- trial: Define trial speficic properties
- environment: Define environment specific properties
- actor_classes: Define actor specific properties (for each actor class)
In this document, "section" refers to YAML mappings.
The import section is used to specify external data structures, and optionally code, that is referenced in other parts of the file. The referenced files must be in the same folder as the spec file. The import sections are:
proto: List of protobuf definition files. Message types defined in these files are used to communicate between the various components
All Cogment projects will need at least one
proto import to define the data structures exchanged between the various components.
⚠️ N.B. When using message types imported from a
.protofile, types need to be referred through their package namespace, not the filename containing them.
This section is optional and defines commands that can then be executed using the Cogment CLI
run command. The commands will be executed by a sub-shell and thus can be any shell command. The commands can also recursively call Cogment, either built-in CLI commands, or other commands defined here. But care should be taken not to create infinite recursive calls.
cd client && python -m cogment.generate --spec cogment.yaml && cd ..
cd environment && python -m cogment.generate --spec cogment.yaml && cd ..
copy: cogment copy cogment.yaml *.proto params.yaml client environment
start: docker-compose up orchestrator agent env
play: cogment run start && docker-compose run launcher
To run one of these commands, the Cogment CLI command
run must be used, e.g.:
cogment run start. And as such there is no problem differentiating between
cogment run copy and
cogment copy (the latter is the builtin CLI command, and the former is the command defined in the
The cogment command section exists so that commands can be executed in a platform independant manner.
This section defines properties related to the trial and trial management. It has the properties:
config_type: (optional) The protobuf message type (data structure) that will be passed on to the pre-trial hooks.
This section defines properties related to the environment. It has the properties:
config_type: (optional) The protobuf message type used to configure the environment
Arguably the most important section of the spec file, the actor classes section describes the actor types that can be present in the project's trials.
The content of this section is a list of actor classes, each containing the necessary properties to define an actor class. These properties are:
name: The name by which this actor class is known
action: Mapping of properties-
space: The protobuf message type that represents all the possible actions that this actor class can perform (its action space)
observation: Mapping of properties
space: The protobuf message type that represents a snapshot of the data that this actor class has access to (its observation space)
config_type: (optional) Defines the protobuf message type used to configure this actor class
Each actor class should define both an observation and action space as protobuf message types.
- name: BigPlayer
- name: SmallPlayer
- name: Referee