@cogment/cogment-js-sdk

cogment-js-sdk

Cogment 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. 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-js-sdk, is the Javascript SDK for making use of Cogment when working with Javascript. It's full documentation can be consulted at https://docs.cogment.ai/cogment/cogment-api-reference/javascript/modules/.

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

• Clone the repository:

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

• Build the docker container:

  docker-compose build cogment-js-sdk
  

• Initialize the repository:

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

Docker Testing

• Start the embeded cogment app

  bin/up.bash
  

• Run all tests

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

Non-docker

Setup

• Clone the repository:

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

• 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
  

• Initialize the repository:

  npm run init
  

Testing

• 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',
    },
  };
  

• Start the embeded cogment app

  bin/up.bash
  

• 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
  

Release process

People having maintainers rights of the repository can follow these steps to release a version MAJOR.MINOR.PATCH. The versioning scheme follows Semantic Versioning.

• Run ./scripts/create_release_branch.sh automatically compute and update the version of the package, create the release branch and update the changelog from the commit history,
• On the release branch, check and update the changelog if needed, update internal dependencies as described here, and make sure everything's fine on CI,
• 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 packages to dockerhub and updating the mirror repositories, is handled directly by the CI.

Changelog

1.25.3 (2021-06-14)

Bug Fixes

• package.json: typings export fixed (069d82c)