@cogment/cogment-js-sdk

@cogment/cogment-js-sdk

Table of contents

• Links
• Usage
• Docker
  • Docker Setup
  • Docker Testing
• Non-docker
  • Setup
  • Testing

Links

• cogment.ai
• Repository
• API Documentation
• Code of Conduct
• License
• Changelog
• Contributing
• Open Core Development
• Coding guidelines
• Updating Cogment
• Sentimental Versioning
• Test Report
• Coverage Report
• Webpack Bundle Report
• cogjs-cli
• Semantic Versioning

Usage

Install the package:

npm install @cogment/cogment-js-sdk

The test suite embeds a working Cogment application. Parts of the example application pertinent to the js-sdk test suite:

• an echo actor
• an environment
• configuration pre-hook - a gRPC service, configured in cogment.yaml
• cogment.yaml - the configuration entrypoint into Cogment and is used to generate language specific static configuration files.
• data.proto - application specific protobufs that represent trial entities (eg: observation space, actor action space, etc) in addition to other utility protobufs needed by the user, you!

The ActorSession.test.ts is the most feature complete example of a working cogment application and is documented to be read as such.

Examples follow.

Instantiate a CogmentService

import {createService} from 'cogment';
import cogSettings from './CogSettings';

const cogmentService = createService({
  cogSettings,
});

Start and stop a trial

import {createService} from 'cogment';
import cogSettings from './CogSettings';

const cogmentService = createService({
  cogSettings,
});

const trialController = cogmentService.createTrialController();

const {trialId} = await trialController.startTrial('unique-id');
return trialController.terminateTrial(trialId);

Register an actor and join the trial

import {createService, TrialActor} from 'cogment';
import cogSettings from './CogSettings';
import {ClientAction, Observation} from './data_pb';

const cogmentService = createService({
  cogSettings,
});

const trialActor: TrialActor = {
  name: 'client_actor',
  actorClass: 'client',
};

cogmentService.registerActor<ClientAction, Observation, never>(
  trialActor,
  async (actorSession) => {
    // Actor implementation here.
  },
);

const trialController = cogmentService.createTrialController();
const {trialId} = await trialController.startTrial(trialActor.name);
await trialController.joinTrial(trialId, trialActor);
return trialController.terminateTrial(trialId);

Watch for trial state changes

import {createService} from 'cogment';
import cogSettings from './CogSettings';

const cogmentService = createService({
  cogSettings,
});

const trialController = cogmentService.createTrialController();

for await (const trialListEntry of trialController.watchTrials([
  0,
  1,
  2,
  3,
  4,
  5,
])) {
  // Do stuff!
}

Development Workflow

Docker

Docker Setup

1. Clone the repository:

   git clone https://github.com/cogment/cogment-js-sdk.git
   

2. Build the docker container:

   docker-compose build cogment-js-sdk
   

3. Initialize the repository:

   docker-compose run cogment-js-sdk npm run init
   

Docker Testing

1. Start the embeded cogment app

   bin/up.bash
   

2. Run all tests

   docker-compose run cogment-js-sdk npm run test
   

Non-docker

Setup

1. Clone the repository:

   git clone https://github.com/cogment/cogment-js-sdk.git
   

2. Install node (check .node-version for the appropriate version). The recommended way to manage node distributions is through nvm (node version manager):

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash
   source ~/.nvm/nvm.sh
   cd /path/to/cogment-js-sdk
   nvm install
   

3. Initialize the repository:

   npm run init
   

Testing

1. Change the contents of .cogmentrc.js from

   module.exports = {
     connection: {
       http: 'http://grpcwebproxy:8080',
     },
     logger: {
       level: 'debug',
     },
   };
   

   To

   module.exports = {
     connection: {
       http: 'http://localhost:8080',
     },
     logger: {
       level: 'debug',
     },
   };
   

2. Start the embeded cogment app

   bin/up.bash
   

3. Do one of the following:

• To run the test suite once:

  npm run test
  

• To watch for changes and rerun tests automatically in your console:

  npm run test:watch
  

• To launch the majestic test ui to run / watch / visualize tests:

  npm run test:ui
  

Changelog

1.25.1-beta.1 (2021-04-16)

Bug Fixes

• gh-pages: run typedoc as part of semantic-release (75242bb)