nl3 - Natural Language Triples

Gemnasium build status coverage coverage npm version

Chat

nl3 is a natural language triple library, used for parsing triples from plain english. Currently nl3 is best at generating triples from simple short phrases that contain the Subject, Predicate and Object in order.

What is a triple?

A triple is a data structure that represents a Subject, Predicate and Object or S P O.

More Information

TLDR;

var nl3 = require('nl3')({
/**
* Specifies valid triples in plain english ex: 'Subject Predicate Object'.
* All values will be singularized.
* @type {Array}
*/
  grammar: [
    'users message users'
  ],
/**
* Extend your vocabulary by mapping word stems to existing predicates.
* @type {Object}
*/
  vocabulary: {
    msg: 'message',     // user bob msgs user tom
    messag: 'message',  // user bob messaged user jill
    contact: 'message'  // user bob contacted user bill
  }
});

The client returned is able to parse these queries.

nl3.parse('user jack msg user jill');
nl3.parse('user jack msgs user jill');
nl3.parse('user jack messaged user jill');
nl3.parse('user jack contacted user jill');
nl3.parse('user jack contacts user jill');

All of which will have the same output.

{
  subject: {
    type: 'user',
    value: 'jack'
  },
  predicate: {
    value: 'message'
  },
  object: {
    type: 'user',
    value: 'jill'
  }
}

Installation

$ npm install nl3 --save

Development Scripts

Before running any development scripts, be sure to first install the dev modules.

$ npm install nl3 --save --dev

Build Documentation

Outputs code documentation files to the ./doc/api folder.

$ npm run doc

Static Analysis

Outputs static analysis files to the ./doc/analysis folder.

$ npm run analyze

Test + Coverage

Outputs code coverage files to the ./doc/coverage folder.

$ npm run test

CURRENT COVERAGE REPORT

codecov.io

API

nl3(options)

Create an nl3 instance.

parameters:

returns: a new instance of the nl3 client.

Example

var nl3 = require('nl3')({
/**
* Specify valid triples in plain english ex: 'Subject Predicate Object'.
* The Subject, Predicate and Object will be will be singularized, if presented in any tense.
* @type {Array}
*/
  grammar: [
    'users message users'
  ],
/**
* Extend the vocabulary of your predicates by mapping word stems to existing predicates within your grammar.
* @type {Object}
*/
  vocabulary: {
    msg: 'message',     // user bob msgs user tom
    messag: 'message',  // user bob messaged user jill
    contact: 'message'  // user bob contacted user bill
  }
});

nl3.parse( text )

parameters:

Example

var nl3 = require('nl3')({
  grammar: [
    'users message users'
  ],
  vocabulary: {
    contact: 'message', // user bob contacted user bill
  }
});

function print (description, triple) {
  console.log(
    description + ' =', JSON.stringify(triple, null, '  ');
  );
};

print( 'user jack contacts user jill', nl3.parse('user jack contacts user jill') );

print( 'users who message user jill', nl3.parse('users who message user jill') );

returns:

user jack contacts user jill = {
  "subject": {
    "type": "user",
    "value": "jack"

  },
  "predicate": {
    "value": "message"
  },
  "object": {
    "type": "user",
    "value": "jill"
  }
}
users who message user jill = {
  "subject": {
    "type": "user"
  },
  "predicate": {
    "value": "message"
  },
  "object": {
    "type": "user",
    "value": "jill"
  }
}

vNext

Support for natural random order queries, these are not in (SPO) order, such as messages that user bob created (OSP), created messages by user jill (POS), created by user jill messages (PSO), (SO) user jills messages, (OS) messages for user jill.

  nl3.parse('users that follow user 42');
  nl3.parse('users followed by user 42');
  nl3.parse('messages from user 42');
  nl3.parse('messages by user 32');

The Backlog...