timkam/js-son

Light-weight reasoning-loop agent library for JavaScript

js-son's Issues

Enable generation of JS doc

Docs Generating JS doc still fails because of unused legacy code. Remove the dead code and make sure the JS doc can be generated.

Examples: change JS-son dependency from file to actual package

Having relative package imports can cause problems when running npm publish https://npm.community/t/npm-publish-hangs-on-prepack/3800. Also it can be confusing for users that the examples make use of the local version and do not download the latest published version from the registry.

Implement example: Integration with WoT Scripting API

Implement an example for agent-oriented things in the context of the Web of Things (WoT) Scripting API. A reference implementation is available at https://github.com/eclipse/thingweb.node-wot.

Minor refactoring / clean up

There are some minor style issues to clean up, see refactoring branch.

Implement support for custom belief revision function

At the moment, the initial handling of a JS-son agent's belief update is somewhat dictated by the environment, i.e., a JS-son agent executes it as follows:

this.beliefs = {
      ...this.beliefs,
      ...beliefs
    }

Here, beliefs are the beliefs the agent gets handed over from the environment. As we can see, these beliefs overwrite all beliefs with the same key that the agent has held before.

This enhancement will implement support of a belief revision function that a) addresses this issue, allowing the agent to reject updates from the environment and b) providing a first-class abstraction for belief revision as a first step in the agent's reasoning loop.

The update will be backwards compatible, i.e., the default belief revision function will be along this line:

(oldBeliefs, newBeliefs) => ({ ...oldBeliefs, ...newBeliefs })

Add additional default belief revision features

For example:

• Monotonic behavior (mostly for illustration purposes)
• Priority value-based revision
• Possibly taking ideas from signals or mergician, e.g. for follow-up tickets.

Enable agent instantiation with configuration object

The agent function has seven parameters, many of which are optional. It makes sense to allow for a configuration using a single configuration object so that users don't need to worry about parameter order or pass undefined to "skip" an optional parameter.

Old package name still in README

At the top of the README, the old package name is used. Change js-son to js-son-agent.

Update usage instructions in README

The usage instructions in the README are incomplete and outdated.
Improve the instructions, possibly by using an example as can be found in the test specifications.

Allow for additional parameters in Environment's state update and state filter functions

The current functions for state update and state filter (i.e., deciding which state properties are provided to an agent) lack parameters for some use cases:

1. stateFilter should be called with an agent's ID, so different agents can get different state updates.

2. update should be called with the current state, so properties of the current state can be manipulated.

Add example: website

Add an example that shows how to use JS-son in the context of a website/web application.

Add Node.js example: Belief-Desire-Intention-Plan

Add a simple Node.js example project that illustrates the Belief-Desire-Intention-Plan approach.

Provide generic learning capabilities for JS-son agents

Possibly as an extension to not add bloat to the core

Document: dependencies

js-son only has dev dependencies; i.e. adding it as a dependency does not require any additional library. This is worth mentioning in the README.

Allow access to beliefs in plan bodies

At the moment, it is not possible to access beliefs in the body of a plan. This should be possible.

Transpile node module with Babel

At the moment, JS-son does not bundle/transpile the source code. This means that it only works with state-of-the-art JavaScript execution environments (and it is generally inconvenient for users). It makes sense to set up a proper build process with Babel.js compilation/transpilation.

Implement abstractions for goal deliberation

Goal-based reasoning loop:
Agent revises beliefs, then goals
Plans are attached to goals,
i.e., triggered if the corresponding goal is active

Add simple Node.js example: Belief-Plan

Add a simple Node.js example project that illustrates the Belief-Plan approach.

Change entry point

The current entry point--index.js in the root directory just "forwards" imports from src/js-son and can be removed if the entry point in package.json is adjusted accordingly.

Add further contribution guidelines

Contributors should:

• Add/update tests.
• Add/update JS doc comments.
• Ensure ESLint does not show any error and warnings.
• Reference issues in their commits and branch names.

Add grid world environment

To improve the out-of-the-box capabilities of JS-son, add a grid-world environment plus a running multi-agent example for agents that act in such an environment.

Activate integration with Travis-CI

The configuration file has already been added. Add the batch and make sure the CI is green.

Decrease code duplication in test cases

To test the different JS-son components, we often use only slightly different code for generating, agents, BDI-plan sets, and environments. Move this code into a dedicated module and get rid of unnecessary duplication.

Add Sphinx documentation

It makes sense on the long run to have one set of documentation that includes both JSDoc and high-level usage instructions/tutorials.
For this, we can use Sphinx and sphinx-js--an extension for documenting JavaScript projects with Sphinx.

Web examples cannot be installed because webpack config is missing

When checking out the repo and trying to run the web example in dev mode, we get the following error:
Error: Cannot find module [...]/JS-son/examples/web/build/webpack.config.js
Reason: The build directory is incorrectly ignored.

Integrated goal and belief revision: goals cannot access updated beliefs

Because of a missing this, when combining goal and belief revision, the goal revision function does not access the updated beliefs. Instead, it accesses the "old" beliefs.

Change package name

npm refuses to publish the package: Package name too similar to existing packages.
Rename the package to js-son-agent.

Move CI to circle-ci

For obvious reasons

Bundle with webpack

While JS-son already uses Babel to transpile to legacy-compliant JavaScript, it does not properly bundle the files. Configure a webpack workflow for this.

Specify default preferenceFunction

In many use cases, intentions equal desires, simply because the desire generation function can jump straight to intentions (the intermediate step is in practice not always relevant).
Hence, we should specify a default determinePreferences value for the Agent object type that assumes the generated desires can be fed as intentions straight into the plans.
This default value would be: (beliefs, desires) => desireKey => desires[desireKey](beliefs).

When the update is released, some of the examples should be adjusted as well.

Support all valid JSON data types as beliefs

At the moment JS-son returns a warning when a belief is not a JSON object. Ideally, JS-son should support JSON data types as well, which are:

• string
• number
• array
• boolean
• null

Add integration tests

Add integration tests that require the full library and test a basic example

Game of life example agents have strange neighbors

In the Game of Life example, some agents have strange neighbors, see this line and following in the source code. The problem are agents that are in the left-most and right-most column in the grid world; these wrongly consider the agents on the other outer-most column of the world their neighbors (with an offset of -1, respectively +1. This can be fixed by adding some additional if-clauses.

Add example: data science tool chain

Add an example that shows how to use JS-son in the context of Jupyer notebooks.

Add multi-agent interaction test case

Testing: The multi-agent interaction test case is still missing: https://github.com/TimKam/JS-son/blob/master/spec/src/environment/Environment.spec.js#L81

Run ESlint on Travis-CI

ESlint should run on Travis-CI and cause a test failure if linting errors exist.

Implement out-of-the-box support for message passing from one agent to another

In the current JS-son version, passing a "private" message from one agent to another requires implementing a custom message router. This functionality should be supported out-of-the-box.

Allow agents to manipulate themselves

In the current JS-son version, all updates to an agent's beliefs are processed by the environment first, i.e. an agent can only update its own beliefs by requesting the update through the environment. Updates of plans, desires and preference functions (the preference function generates the agent's intentions based on its desires or beliefs) are not possible.
A new feature is planned to be implemented to change this. Agents should be able to manipulate themselves with no restrictions, directly via their plans. Because this feature enables an extreme degree of dynamic evolution, agents should be configurable to not support this feature.

Add function-as-a-service/serverless example

JS-son agents can easily be deployed to FaaS/serverless environments like Google Cloud.
Add an example that demonstrates this.

Provide built-in support for distributed MAS

At the moment, JS-son is by default an entirely centralized MAS; distributed interactions are not treated as a first-class citizen. This should change, for example by adding the following features:

• Allow distributed agents to connect to JS-son environments.
• Allow peer-to-peer interactions between distributed JS-son agents.

Update entry point

The entry point (index.js) does not yet work, as it does not consider the structure of the JS-son exports. Fix this.

Fix export issue for new goal abstractions

Goal abstractions are currently not exported

Consider current agent beliefs in state update function

The state update function should receive the current agent beliefs as a parameter to allow manipulating them as part of the environments agent belief update.

Web app example: "restart" button triggers game with same start state

When clicking the "restart" button in the Game of Life example web app, a new random start state should be generated. This is not the case; instead the start state is determined during application load. Changing the start state requires reloading the application.

Jupyter example: fix variable handover from Node.js to Python

pixiedust_node features a store command to explicitly handover Node.js variables to Python, see: this blog post. We should use this in the Jupyter example and get rid of the terrible sleep statement. Edit: The store function is deprecated and does not differ from a global variable assignment, which also allows hand-overs. I.e., it is not possible to fix the handover delay problem properly. As a slightly better solution than the current fixed sleep(), we can add a waiting loop:

while not 'histories' in globals():
  time.sleep(1)