epures

Story grammar generation

A story grammar generation library written in ES6. This is a repackaging of the client-side library tracery.

My goal is to provide more tests and structure to the project to make it scalable, and to document interesting usecases properly. I would also like it to be able to support more languages such as French, Spanish and German.

History

This is a 2018 update of Kate and George work on the tracery grammar generation library published two years ago. Since then it is unmaintained, but new opportunities in the chatbot area make it interesting for server side usage.

This library must be used with Node.js 6 Boron, or above:

• this LTS version will be active until April 2018, see LTS Schedule,
• if you stick to that version, it will also allow you to use it with Cloud Functions for popular usecases with Actions on Google and Dialogflow.

Setup

$ npm install epures --save

Usage

See the samples folder for more usecases.

Running with Node.js

Basic example

$ node samples/quickstart.js

var epures = require('epures')
 
var grammar = epures.createGrammar({
  'animal': ['panda','fox','capybara','iguana'],
  'emotion': ['sad','happy','angry','jealous'],
  'origin':['I am #emotion.a# #animal#.'],
})
 
grammar.addModifiers(epures.modifiers.en_US)
 
console.log(grammar.flatten('#origin#'))
 
// I am an angry fox.

Integrating external sources of data

You can use the ES6 generator syntax to generate grammars with realistic data.

$ node samples/faker-data.js

const faker = require('faker/locale/en')
const epures = require('../index')
 
const getSamples = epures.generators.getSamples
 
const rawData = {
  bs: getSamples(20, faker.company.bs),
  catchPhraseDescriptor: getSamples(20, faker.company.catchPhraseDescriptor),
  catchPhraseAdjective: getSamples(20, faker.company.catchPhraseAdjective),
  catchPhraseNoun: getSamples(20, faker.company.catchPhraseNoun),
  bsAdjective: getSamples(20, faker.company.bsAdjective),
  origin: ['You can try our #bs# with #catchPhraseAdjective.lowerCase.a# #catchPhraseDescriptor# #catchPhraseNoun#.']
}
const grammar = epures.createGrammar(rawData)
 
grammar.addModifiers(epures.modifiers.en_US)
 
console.log(grammar.flatten('#origin#'))
 
// You can try our vertical visualize vortals with a streamlined even-keeled emulation.

Custom modifier

A modifier is a JavaScript object grouping a list a functions mapping string to string.

The base collection of modifiers supports common transformations on strings from the library VocaJS and is available for in various localizations. Feel free to add more supported language to contribute to the library!

You can reuse existing modifiers using epures.modifiers or define your own like in this example.

$ node samples/custom-modifier.js

const epures = require('../index')
 
const grammar = epures.createGrammar({
  animal: ['panda', 'fox', 'capybara', 'iguana'],
  emotion: ['sad', 'happy', 'angry', 'jealous'],
  origin: ['The #animal# is #emotion.passwordify#.']
})
 
const myModifier = {
  passwordify: s => new Array(s.length + 1).join('*')
}
 
grammar.addModifiers(myModifier)
 
console.log(grammar.flatten('#origin#'))
 
// The iguana is *****.

More usecases

More usecases can be found in the unit tests. You will also find more detailed information in the documentation.

Running with the browser

A bundle library can be generated using Webpack. Just include the epures.min.js file in the HTML, and use the library.

npm run build

$ open /samples/quickstart.html

<script src="https://cdn.jsdelivr.net/npm/epures/dist/epures.min.js"></script>
 
<script>
  const grammar = epures.createGrammar({
    animal: ['panda', 'fox', 'capybara', 'iguana'],
    emotion: ['sad', 'happy', 'angry', 'jealous'],
    origin: ['I am #emotion.a# #animal#.']
  })
 
  grammar.addModifiers(epures.modifiers.en_US)
 
  console.log(grammar.flatten('#origin#'))
</script> 

Contributions

Changes and improvements are welcome! Feel free to fork and open a pull request into master.

Roadmap

• Fix the build (use xo, ava packages and Modern JS)
• Webpack support for client-side code.
• Merge existing unit tests (test1, test2)
• Better documentation using /samples
• Add support for more languages (notably French, German and Spanish). See faker.js for file structure and samples.
• Add tests for the /utils classes
• Add support for command line usage
• Add support for Dialogflow import formats

Bugs

• Check why UglifyJsPlugin breaks the library
• Check why 'Maximum call stack size exceeded' in the Create a grammar that can itself create valid grammars unit test. Appears randomly. Restarting Travis job solves the problem.

Running the tests

You can lint the code and run all unit tests using that script.

npm test

To run tests for only one file, I would suggest you using the ava command. For example, if you work on the English modifier only modifiers/en_US/base.js, a good practice is to run the corresponding test continuously.

ava modifiers/en_US/base.test.js --watch

Publishing

npm version [patch, minor, major]
npm publish

License

epures is licensed under the Apache 2.0 License.

References

• Kate Compton - Tracery tutorial, check also the original source code
• Nicole He - Voice Technology is an Opportunity to Make Weird Stuff, check also the source code
• Chris Umbel - Natural library
• Dmitri Pavlutin - Voca library
• Steve Worswick - Mitsuku chatbot