nlp-router

A means to associate metadata or calls with patterns of speech so that when text is analyzed, a match is provided (along with a level of confidence) so that the program can determine a course of action in response.

Designed for use with deftly-bot but generic enough to be used with other approaches. Deftly's declarative resource approach coupled with the initialization process performs the router's initialization which may seem otherwise tedious.

Consider stealing the code (modlo, fount, deftly) to provide your own means of creating a way to associate patterns of speech with methods to be dispatched on matches.

What problem it attempts to solve

Observations of support and operational tooling that makes use of chat interfaces is that it is very difficult to remember specific command patterns and incantations.

This leads not only to command misses and frequent command list invocations (littering the common channel) but can have unintended outcomes.

By utilizing natural speech processing the focus can be on specific keywords, synonyms and possible patterns for a valid request. This follows the paradigm, "be liberal in what you accept".

Chat interfaces are far more welcoming and powerful when they don't expect people to provide explicit/perfect incantations and punish them for omissions, transpositions, and typos.

What it is not

A typical "router" pattern that can be plugged into an HTTP or message dispatch stack directly.

Patterns of Speech

This same table is available in a single document here

| Tag | Description | Example | |:--------:|:-----------:|:-------:| | , | Comma | , | | : | Mid-sent punctuation | :,; | | . | Sent-final punctuation | ., !, ? | | " | quote | " | | ( | Left paren | ( | | ) | Right paren | ) | | # | Pound sign | # | | CC | Coordinating conjunction | and, but, or | | CD | Cardinal number | one, two, 1, 2 | | DT | Determiner | the, some | | EX | Existential there | there | | FW | Foreign word | mon dieu | | IN | Preposition | of, in, by | | JJ | Adjective | big | | JJR | Adjective comparitive | bigger | | JJS | Adjective superlative | biggest | | LS | List item maker | 1, One | | MD | Modal | can, should | | NN | Noun, singular or mass | dog | | NNP | Proper noun, singular | Edingburgh | | NNPS | Proper noun, plural | Smiths | | NNS | Noun, plural | dogs | | PDT | Predeterminer | all, both | | POS | Possessive ending | 's | | PP | Personal pronoun | I, you, she | | PRP$ | Possessive pronoun | my, one's | | RB | Adverb | quickly, not | | RBR | Adverb, comparative | faster | | RBS | Adverb, superlative | fastest | | RP | Particle | up, off | | SYM | Symbol | %, +, & | | TO | 'to' | to | | UH | Interjection | oh, oops | | VB | Verb, base form | eat | | VBD | Verb, past tense | ate | | VBG | Verb, gerund | eating | | VBN | Verb, past part | eaten | | VBP | Verb, present | eat | | VBZ | Verb, present | eats | | WDT | Wh-determiner | which, that | | WP | Wh pronoun | who, what | | WP$ | Possessive-Wh | whose | | WRB | Wh-adverb | how, where |

API

The API supports adding, retrieving, changing the value of, and evaluating rule definitions.

addRule (name, definition, value)

Adds a rule to the router and returns a promise that either resolves to the current rank for the rule or rejects with validation errors.

const rank = router.addRule(
  'checkStatus', 
  {}
  engine.checkStatus
)

// rank is the current order of the rule provided

changeValue (name, value)

Changes the value associated with the rule.

router.changeValue('myRule', engine.someNewMethod)

deleteRule (name)

Returns an array with a boolean indicating whether a matching rule was deleted and an integer indicating the number of rules left in the router.

const [deleted, remaining] = router.deleteRule('myRule')

getRule (name)

Returns the rule definition for the name. undefined is returned if the name does not match.

const rule = router.getRule('myRule')

getRank (name)

Returns the current rank for the rule. If the rule name does not match an existing rule, a -1 is returned.

const rank = router.getRank('myRule')

evaluate (sentence)

Evaluates a sentence for a potential match and, if there is a match, returns data extracted from the sentence as well as the value. If no match is found, undefined is returned.

const match = router.evaluate('my voice is my passport verify me')
// match will have the properties `data` and `value`

// it's more likely that you'd want to feed the match into a 
// dispatcher, but YMMV
match.value(match.data.values)

data returned in match

The data returned in the match will contain the properties:

• sentiment - 'positive'|'neutral'|'mixed'|'negative'
• confidence - %
• degree - %
• dirtiness - %
• ordered - true|false
• politeness - %
• tense - 'past'|'present'
• tokens - the full token array extracted during sentence analysis
• type - 'declarative'|'imperative'|'interrogative'
• values - a hash of name/value pairs extracted

Each token has the following properties:

• abbreviation - true|false
• acronym - true|false
• alt - alternate text for the tag's value
• entity - either undefined or a hash with the following details:
  • alt - alternate text content
  • value - the value of the entity detected
  • type - 'unknown'|'email'|'ip'|etc.
• plural - true|false
• pos - part of speech tag,
• value - text content for the tag,
• verb - true|false