articulate-nlg

Articulate NLG

A natural language generator (NLG) that articulates concepts as words, phrases, and sentences.

This TypeScript project is available in JavaScript via npm as an ES6 or CommonJS import.

Installation

Via npm (requires Node.js):

$ npm i articulate-nlg

Usage

ES6 import:

import Persona, { VocabHelpers } from "articulate-nlg";

CommonJS import:

const Persona = require("articulate-nlg").default;
const VocabHelpers = require("articulate-nlg").VocabHelpers;

In short:

• Define "personas" that have vocabularies which can randomly generate coherent text.
• Vocabularies use key strings that represent concepts, and values that represent the text to be generated.
• Concepts can be cross-referenced, making for interesting and sometimes unexpected results.

A persona requires a vocabulary, which defines the text that can be generated. Vocabularies for a persona are defined as key value string pairs in a JS object.

The underlying templating engine is mustache.js, and all key values are actually Mustache partials. However, this library provides helper functions so you most likely won't need to write any mustache.js syntax! You can still use it if you'd like, though, but do so at your own peril.

Vocab concepts can be cross-referenced. Just make sure you avoid circular references, which will cause an infinite loop.

One you construct a Persona, call say("conceptName") on the persona to generate text for that concept!

See the example below:

import Persona, { VocabHelpers } from "articulate-nlg";
const choose = VocabHelpers.choose;
const capitalize = VocabHelpers.capitalize;
//const maybe = VocabHelpers.maybe;
const say = VocabHelpers.say;
const param = VocabHelpers.param;
//const ifThen = VocabHelpers.ifThen;
//const ifNot = VocabHelpers.ifNot;
const ifElse = VocabHelpers.ifElse;
//const doFirst = VocabHelpers.doFirst;

// Here we have the greet, master, emoji, and welcomeHome concepts.
// Each concept maps to the text that's to be generated.
// Helper functions generate the templating syntax for you automatically.
let dogVocab = {
  greet: choose(["woof", "bark", "sniff sniff", "wag tail"]),
  master: ifElse("name", capitalize(param("name")), "bringer of food"),
  emoji: choose("👅", "🐶", "🐾", "💩", "🐩", "🐕‍"]),
  // This concept cross-references greet, master, and emoji using say().
  welcomeHome: capitalize(say("greet")) + "! Welcome home, " + 
               say("master") + "! " + say("emoji")
};

let max = new Persona(dogVocab);

max.say("welcomeHome");
// This will generate text like following:
// Sniff sniff! Welcome home, bringer of food! 🐾
// Woof! Welcome home, bringer of food! 👅
// Wag tail! Welcome home, bringer of food! 💩
// Etc.

// This will articulate the "greet" concept.
max.say("greet");
// "woof", "bark", "sniff sniff", or "wag tail"

// If you reference a concept that's not understood, you'll get
// an empty string back.
max.say("wubalubadubdub");
// ""

// Params can be used in the vocab, too. Here, the "master" 
// concept uses a name if provided.
max.say("master", { name: "justin" });
// "Justin"
max.say("welcomeHome", { name: "justin" });
// Sniff sniff! Welcome home, Justin! 🐩

// And if not provided, can fall back on a default using the 
// ifElse helper. See the vocab above.
max.say("master");
// "Bringer of food"

Vocab Helper Functions

The vocab helper functions abstract away the templating syntax for the underlying templating engine. These can (and should!) be used instead of mustache.js syntax whenever possible.

See the mustache.js documentation for reference on the syntax if you must (heh heh). If there's something really fancy you want to do that this library doesn't have a helper for, go for it.

Where possible, it is recommended that you use helper functions over mustache.js syntax to define your persona.

The following helper functions are available in VocabHelpers:

• capitalize(text: string)

Creates a template for capitalization. Capitalizes the first letter of the text after passing it though the templating engine.

• choose(texts: (string|{v:value,w:weight})[])

Creates a template for random choice. This chooses one of the items at random. Takes a mixed array of strings or weighted objects in the format {v: value, w: weight}.

You cannot use a | character in any of the texts. If you need this character, use say("pipe") and have the "pipe" key map to "|".

Each text item is passed through the templating engine. This means you can use other helpers, like say().

• choose(["apple", "orange", say("meat")]) -> Randomly selects apple, orange, or whatever meat articulates as.

You can specify weights using {v: value, w: weight} objects instead of strings, where v is the text to articulate and w is the weight value. Weights default to 1 if not provided.

• choose([{v: "apple" w: 3}, "orange", "banana"]) -> apple has a 60% chance, orange and banana each have a 20% chance (default weight of 1).

• maybe(text: string)

Creates a template that results in a 50/50 choice between an empty string or the provided text. The same as using choose(["", text]).

The provided text is passed through the templating engine.

You cannot use a | character in the text. If you need this character, use say("pipe") and have the "pipe" key map to "|".

• say(vocabKey: string)

Creates a template that cross-references another vocab key.

• capSay(vocabKey: string)

Creates a template that cross-references another vocab key and capitalizes it. Equivalent to capitalize(say(vocabKey)).

• param(paramKey: string)

Creates a template that references the value of a parameter. If it's a string, it will be part of the resulting text output.

The value of the param is not passed through the templating engine.

• ifThen(paramKey: string, thenText: string)

Creates a template that uses the provided thenText if the param key exists and is not falsy.

The provided text is passed through the templating engine.

• ifNot(paramKey: string, thenText: string)

Creates a template that uses the provided thenText if the param key doesn't exist or is falsy.

The provided text is passed through the templating engine.

• ifElse(paramKey: string, thenText: string, elseText: string)

Creates a template with both ifThen() and ifNot() templates for the given param key.

The provided text is passed through the templating engine.

• doFirst(paramTextPairs: {p: paramKey, t: text}[], defaultText: string = "")

Creates a template that uses ifElse() templates for each pair provided until true. If no param keys are truthy, the defaultText is used (defaults to empty string).

The provided text is passed through the templating engine.

Note on Nesting

You cannot nest the same function wrapper in itself. If, say, you need to nest choose() within choose(), you should create a separate vocab key with the function and reference it in the original one like so: say("nameOfVocabKey"). A safety check is built into these functions to prevent nesting and a warning will be printed to the console if you do nest them on accident.

TypeScript Support

This is a TypeScript project. Type definitions are available in: dist/index.d.ts.

ISC License

Copyright 2019 Justin Mahar

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.