Documentation

Read the official documentation.

Overview

This package allows you to define personas that have a vocabulary which define how to generate varying, coherent text.

Features include:

• 💬 Generate speech using defined personas
  • Personas can articulate concepts as words, phrases, and sentences
• 👍 Simple yet flexible API
  • Use the helpers below to build personas quickly and easily
• 🤖 Great for chatbots, game NPCs, and more!
  • Create personas for a variety of purposes.

Donate

If this project helped you, please consider buying me a coffee or sponsoring me. Your support is much appreciated!

Table of Contents

• Documentation
• Overview
  • Features include:
• Donate
• Table of Contents
• Installation
• Quick Start
• Vocab Helper Functions
  • say
  • capitalize
  • sb
  • sa
  • sba
  • capSay
  • choose
    • A note on functions:
  • weighted
  • chance
  • cycle
  • maybe
  • param
  • ifThen
  • ifNot
  • ifElse
  • doFirst
  • render
• TypeScript
• Icon Attribution
• Contributing
• ⭐ Found It Helpful? Star It!
• License

Installation

npm i articulate-nlg

Quick Start

import { Persona } from "articulate-nlg";

In short:

• Define a "Persona" that has a vocabulary which defines how to generate coherent text.
• Vocabularies use key strings that represent concepts, and function values that return the text to be generated.
• Vocab concepts can be cross-referenced, making for interesting results.

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

See the example below:

import { Persona } from "articulate-nlg";

class Dog extends Persona {
  createVocab = () => {
    // Persona helper functions, for convenience.
    const say = this.say;
    const capitalize = this.capitalize;
    const capSay = this.capSay;
    const choose = this.choose;
    const chance = this.chance;
    const cycle = this.cycle;
    const param = this.param;
    const ifElse = this.ifElse;

    // Return an object containing strings mapped to functions,
    // which return the text.
    return {
      greet: () => choose("woof", "bark", "sniff sniff", "wag tail"),
      master: () =>
        ifElse("name", capitalize(param("name")), "bringer of food"),
      emoji: () =>
        cycle({ group: "emoji" }, "👅", "🐶", "🐾", "💩", "🐩", "🐕‍"),
      // This concept cross-references greet, master, and emoji using say().
      welcomeHome: () =>
        capSay("greet") +
        "! Welcome home, " +
        say("master") +
        "! " +
        say("emoji")
    };
  };

  // Create and set the vocab for Dog.
  vocab = this.createVocab();
}

// Create "max", a new Dog persona.
let max = new Dog();

console.log(max.articulate("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.
console.log(max.articulate("greet"));
// "woof", "bark", "sniff sniff", or "wag tail"

// If you reference a concept that's not understood, you'll get
// an empty string back and a warning will be printed.
console.log(max.articulate("meow"));
// ""

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

// And if not provided, can fall back on a default using the
// ifElse helper. See the function value for master above.
console.log(max.articulate("master"));
// "bringer of food"

Vocab Helper Functions

The following helper functions are available in the Persona class. Use these to aid in generating interesting results when defining a vocabulary.

say

say (vocabKey: string): string

Articulates the concept with the vocab key provided. This function will generate the text for that vocab key.

capitalize

capitalize (text: string | () => string | {t: string | () => string, w: weight}): string

Capitalizes the first letter of the provided text.

sb

sb (text: string | () => string | {t: string | () => string, w: weight}): string

Returns the provided text with a space before it.

sa

sa (text: string | () => string | {t: string | () => string, w: weight}): string

Returns the provided text with a space after it.

sba

sba (text: string | () => string | {t: string | () => string, w: weight}): string

Returns the provided text with a space before and after it.

capSay

capSay (vocabKey: string): string

Convenience function that calls capitalize(say(vocabKey)) to both articulate a concept and then capitalize the resulting text.

choose

choose (...texts: (string | () => string | {t: string | () => string, w: weight})[]): string

Chooses one of the the provided texts or functions at random. Weights can be specified in the format {t: text or function, w: weight}, or by using the weighted() function (recommended). Weights default to 1 if not specified.

Along with say(), this function is at the heart of this NLG library.

A note on functions:

If you pass a function, the function will be called and returned as a string. Using functions can significantly speed up articulation as text resolution will be deferred until the moment the text is needed.

Using functions is overkill for lower-level concepts. I recommend using functions for higher-level concepts (which nest lots of calls to choose()), and that you use function shorthand.

For example, this concept is slower because each choose() call is resolved before making the actual choice:

  myConcept: choose(
      choose(...),
      choose(...),
      ...
    )

And this concept is faster because the functions defer the individual choose() calls until after the choice is made:

  myConcept: choose(
      () => choose(...),
      () => choose(...),
      ...
    )

weighted

weighted (text: string | () => string, weight: number = 1): {t: text, w: weight}

Convenience function that returns an object with the text (or function) and weight, for use with the choose() and cycle() functions. The returned object will be in the format {t: text or function, w: weight}. If you pass a function, it must return a string.

Weights default to 1 if not specified.

chance

chance (text: string | () => string, chance: number): string

Return the provided text given the chance provided, from 0 to 1, or empty string otherwise.

For instance, a chance of 0.8 would mean an 80% chance the provided text was returned, and a 20% chance of empty string.

If the value provided is a function, that function will be called and its string return value would be returned if chosen.

cycle

cycle (group: {group: name}, ...texts: (text: string | () => string | {t: string | () => string, w: weight})[]): string

Uses choose() to randomly select one of the provided texts, but ensures that the selected item is not repeated until all remaining items have been chosen. Items can be weighted, and can be functions that return strings.

The first argument is an object containing a group name for the items you'd like to cycle: {group: name}

Use this function to keep a degree of randomness while ensuring the text doesn't repeat too often.

maybe

maybe (text: string | () => string | {t: string | () => string, w: weight}): string

Returns the text provided 50% of the time, and empty string 50% of the time.

You can pass multiple texts. In that case, there's a 50% chance of empty string, or one of your texts being chosen using choose(). Texts can either be a string, weighted, or a function that returns a string.

param

param (paramKey: string): string

Returns text for the value of the param key provided. The param value can be a string, function, number, etc.

Param functions must return a string. If the param value is not a string or function, it is concatenated with "" and returned as a string.

ifThen

ifThen (paramKey: string, then: (text: string | () => string)): string

Returns the provided then text if the value of the param key is truthy, and returns empty string otherwise.

ifNot

ifNot (paramKey: string, then: (text: string | () => string)): string

Returns the provided then text if the value of the param key is falsy, and returns empty string otherwise.

ifElse

ifElse (paramKey: string, then: (text: string | () => string), otherwise: (text: string | () => string)): string

Returns the provided then text if the value of the param key is truthy, and returns the otherwise string otherwise.

doFirst

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

Returns the text for the first param value that is truthy, or the default text if none are. defaultText is optional and defaults to empty string.

Use this to avoid deeply nested ifElse() calls.

Text values can be either strings or functions that return strings.

render

render (val: any): string

Renders the provided value as a string.

• If it's a string, it'll be returned.
• If it's a function, it'll be called and its value will be recursively rendered and returned.
• If it's weighted text, its text property t will be recursively rendered and returned.
• If it's none of the above but truthy, it'll be concatenated with empty string and returned.
• If it's falsy, empty string will be returned.

This function is called on all texts for the other helper functions and is included mainly for reference. You likely won't need to call it directly.

TypeScript

Type definitions have been included for TypeScript support.

Icon Attribution

Favicon by Twemoji.

Contributing

Open source software is awesome and so are you. 😎

Feel free to submit a pull request for bugs or additions, and make sure to update tests as appropriate. If you find a mistake in the docs, send a PR! Even the smallest changes help.

For major changes, open an issue first to discuss what you'd like to change.

⭐ Found It Helpful? Star It!

If you found this project helpful, let the community know by giving it a star: 👉⭐

License

See LICENSE.md.