A model-backed generative text library for JavaScript.
Latest commit 4359cc8 Nov 5, 2016 @sequitur Allow using a custom rng
Failed to load latest commit information.
demo Better error message when running out of phrases Jan 30, 2016
docs Allow using a custom rng Nov 5, 2016
lib Allow using a custom rng Nov 5, 2016
test Allow using a custom rng Nov 5, 2016
.gitattributes Initial commit Jan 25, 2016
.gitignore Update gitignore Jan 29, 2016
.travis.yml Fix test on null value Jan 25, 2016
LICENSE Initial commit Jan 25, 2016
README.md Update README Jan 29, 2016
gulpfile.js Implement generator-specific builtins Jul 1, 2016



NPM version Build Status Dependency Status Documentation Status

A model-backed generative text grammar tool for javascript. Improv is similar to Tracery in that it can generate random, procedurally generated text recursively. Also like Tracery, Improv includes some basic templating functionality.

Unlike Tracery, however, Improv generators refer to models to build text. This allows for more sophisticated text generation by referencing an underlying world model.


Improv is an npm module, but it should work fine in a browser environment through Webpack or Browserify.

$ npm install --save improv

Quick Example

import Improv from './lib/index.js';

const spec = {
  animal: {
    groups: [
        tags: [['class', 'mammal']],
        phrases: ['dog', 'cat']
        tags: [['class', 'bird']],
        phrases: ['parrot']
  root: {
    groups: [
        tags: [],
        phrases: [
          '[name]: I have a [:animal] who is [#2-7] years old.'

const improv = new Improv(spec, {
  filters: [Improv.filters.mismatchFilter()]

const bob = { name: 'Bob' };
const alice = { name: 'Alice', tags: [['class', 'mammal']] };
const carol = { name: 'Carol', tags: [['class', 'bird']] };

const lines = [
  improv.gen('root', bob),
  improv.gen('root', alice),
  improv.gen('root', carol)

/* Should produce something like:
  Bob: I have a dog who is 3 years old.
  Alice: I have a cat who is 2 years old.
  Carol: I have a parrot who is 5 years old.



Full API documentation at Read the Docs.

Caveats and Known Issues

Improv does absolutely no validation or security checking of anything, so for the love of God don't pass user-submitted data into it.

Improv is still in active development and the API will change in the future as the library evolves.


MIT © Bruno Dias