UNPKG

@chatopera/manuscript/readme.md

Version:

6.25 kBMarkdownView Raw

1[![Build Status](https://travis-ci.org/superscriptjs/superscript.svg?branch=master)](https://travis-ci.org/superscriptjs/superscript)
2[![Dependencies Status](https://david-dm.org/superscriptjs/superscript.svg)](https://david-dm.org/superscriptjs/superscript)
3[![Slack Chat](https://superscript-slackin.herokuapp.com/badge.svg)](https://superscript-slackin.herokuapp.com/)
4[![Code Climate](https://codeclimate.com/github/silentrob/superscript/badges/gpa.svg)](https://codeclimate.com/github/silentrob/superscript)
5
6# SuperScript
7
8SuperScript is a dialog system and bot engine for creating human-like conversation chat bots. It exposes an expressive script for crafting dialogue and features text-expansion using WordNet and information retrieval using a fact system built on a [Level](https://github.com/Level/level) interface.
9
10Note: This version (v1.x) is designed to work with and tested against the latest Node 6.x and above.
11
12## Why SuperScript?
13
14SuperScript's power comes in its topics and conversations, which mimic typical human conversations. If you're looking to create complex conversations with branching dialogue, or recreate the natural flow of talking about different topics, SuperScript is for you!
15
16## What comes in the box
17
18* Dialog engine.
19* Multi-user platform for easy integration with group chat systems like Slack.
20* Message pipeline with NLP tech such as POS tagging, sentence analysis and question tagging.
21* Extensible plugin architecture to call your own APIs or do your own NLP if you want to!
22* A built in graph database using LevelDB. Each user has their own sub-level, allowing you to define complex relationships between entities.
23* [WordNet](http://wordnet.princeton.edu/), a database for word and concept expansion.
24
25## Install
26
27    npm install superscript
28
29## Getting Started
30
31### bot-init
32
33If you've installed superscript globally (`npm install -g superscript`), a good way to get your new bot up and running is by running the `bot-init` script:
34
35    bot-init myBotName --clients telnet,slack
36
37This will create a bot in a new 'myBotName' folder in your current directory. You can specify the clients you want with the `--clients` flag.
38
39Then all you need to do is run:
40
41```
42cd myBotName
43npm install
44parse
45npm run build
46npm run start-[clientName]
47```
48
49This will start the server. You then need to connect to a client to be able to talk to your bot! If you're using the telnet client, you'll need to open up a new Terminal tab, and run `telnet localhost 2000`.
50
51Note: The `parse` step is a bin script that will compile your SuperScript script. By default, it will look at the `chat` folder in your current directory.
52
53### Clone a template
54
55Alternatively, check out the [`hello-superscript`](https://github.com/silentrob/hello-superscript) repo for a clean starting point to building your own bot. There's no guarantee at present that this is using the latest version of SuperScript.
56
57### Using Heroku's one-click deploy
58
59Thanks to @bmann we now have a one-click deploy to Heroku! More info can be found over at [superscript-heroku](https://github.com/bmann/superscript-heroku).
60
61#### Express Client
62
63[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/bmann/superscript-heroku/tree/master)
64
65#### Slack Client
66
67The slack-client branch creates a superscript powered bot that sits in your Slack. You'll need to create a bot and give it a name in the [Slack apps directory](http://my.slack.com/apps/A0F7YS25R-bots) in order to get a token that lets your bot connect to your Slack.
68
69[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/bmann/superscript-heroku/tree/slack-client)
70
71Creating the bot in the Slack directory means you'll see the bot appear in your Slack as offline. When your server from above is running correctly, the status of the bot will go green, and you can say "Hi" to it and it will respond.
72
73## Upgrading to v1.x
74
75Information on upgrading to v1.x can be found [on the wiki](https://github.com/superscriptjs/superscript/wiki/Upgrading-to-v1).
76
77## Documentation
78
79Visit [superscriptjs.com](http://superscriptjs.com) for all the details on how to get started playing with SuperScript. Or [read the wiki](https://github.com/superscriptjs/superscript/wiki)
80
81### Example Script - Script Authoring
82
83    + hello human
84    - Hello Bot
85
86`+` matches all input types
87
88`-` Is the reply sent back to the user.
89
90
91### Optional and Alternates - Script Authoring
92
93    + [hey] hello (nice|mean) human
94    - Hello Bot
95
96`[]` are for optional words, they may or may not appear in the input match
97
98`()` are alternate words. One MUST appear.
99
100### Capturing results - Script Authoring (wildcards)
101
102    + * should *~2 work *1
103    - I have no idea.
104
105`*` Matches ZERO or more words or tokens
106
107`*~n` Matches ZERO to N words or tokens
108
109`*n` Matches exactly N number of words or tokens
110
111
112## And More
113
114The above is just a tiny fraction of what the system is capable of doing. Please see the [full documentation](http://superscriptjs.com) to learn more.
115
116
117### Additional Resources
118
119* [Sublime Text Syntax Highlighting](https://github.com/mariusursache/superscript-sublimetext)
120* [Atom Syntax Highlighting](https://github.com/DBozhinovski/language-superscript)
121
122### Further Reading
123
124* [Introducing SuperScript](https://medium.com/@rob_ellis/superscript-ce40e9720bef) on Medium
125* [Creating a Chatbot](https://medium.com/@rob_ellis/creating-a-chat-bot-42861e6a2acd) on Medium
126* [Custom Slack chatbot tutorial](https://medium.com/@rob_ellis/slack-superscript-rise-of-the-bots-bba8506a043c) on Medium
127* [SuperScript the big update](https://medium.com/@rob_ellis/superscript-the-big-update-3fa8099ab89a) on Medium
128* [Full Documentation](https://github.com/superscriptjs/superscript/wiki)
129* Follow [@rob_ellis](https://twitter.com/rob_ellis)
130
131### Further Watching
132
133* [Talking to Machines EmpireJS](https://www.youtube.com/watch?v=uKqO6HCKSBg)
134
135## Thanks
136
137SuperScript is based off of a fork of RiveScript with idiom brought in from ChatScript. Without the work of Noah Petherbridge and Bruce Wilcox, this project would not be possible.
138
139## License
140
141[The MIT License (MIT)](LICENSE.md)
142
143Copyright © 2014-2017 Rob Ellis

1	`[![Build Status](https://travis-ci.org/superscriptjs/superscript.svg?branch=master)](https://travis-ci.org/superscriptjs/superscript)`
2	`[![Dependencies Status](https://david-dm.org/superscriptjs/superscript.svg)](https://david-dm.org/superscriptjs/superscript)`
3	`[![Slack Chat](https://superscript-slackin.herokuapp.com/badge.svg)](https://superscript-slackin.herokuapp.com/)`
4	`[![Code Climate](https://codeclimate.com/github/silentrob/superscript/badges/gpa.svg)](https://codeclimate.com/github/silentrob/superscript)`
5
6	`# SuperScript`
7
8	`SuperScript is a dialog system and bot engine for creating human-like conversation chat bots. It exposes an expressive script for crafting dialogue and features text-expansion using WordNet and information retrieval using a fact system built on a [Level](https://github.com/Level/level) interface.`
9
10	`Note: This version (v1.x) is designed to work with and tested against the latest Node 6.x and above.`
11
12	`## Why SuperScript?`
13
14	`SuperScript's power comes in its topics and conversations, which mimic typical human conversations. If you're looking to create complex conversations with branching dialogue, or recreate the natural flow of talking about different topics, SuperScript is for you!`
15
16	`## What comes in the box`
17
18	`* Dialog engine.`
19	`* Multi-user platform for easy integration with group chat systems like Slack.`
20	`* Message pipeline with NLP tech such as POS tagging, sentence analysis and question tagging.`
21	`* Extensible plugin architecture to call your own APIs or do your own NLP if you want to!`
22	`* A built in graph database using LevelDB. Each user has their own sub-level, allowing you to define complex relationships between entities.`
23	`* [WordNet](http://wordnet.princeton.edu/), a database for word and concept expansion.`
24
25	`## Install`
26
27	`npm install superscript`
28
29	`## Getting Started`
30
31	`### bot-init`
32
33	If you've installed superscript globally (`npm install -g superscript`), a good way to get your new bot up and running is by running the `bot-init` script:
34
35	`bot-init myBotName --clients telnet,slack`
36
37	This will create a bot in a new 'myBotName' folder in your current directory. You can specify the clients you want with the `--clients` flag.
38
39	`Then all you need to do is run:`
40
41	```
42	`cd myBotName`
43	`npm install`
44	`parse`
45	`npm run build`
46	`npm run start-[clientName]`
47	```
48
49	This will start the server. You then need to connect to a client to be able to talk to your bot! If you're using the telnet client, you'll need to open up a new Terminal tab, and run `telnet localhost 2000`.
50
51	Note: The `parse` step is a bin script that will compile your SuperScript script. By default, it will look at the `chat` folder in your current directory.
52
53	`### Clone a template`
54
55	Alternatively, check out the [`hello-superscript`](https://github.com/silentrob/hello-superscript) repo for a clean starting point to building your own bot. There's no guarantee at present that this is using the latest version of SuperScript.
56
57	`### Using Heroku's one-click deploy`
58
59	`Thanks to @bmann we now have a one-click deploy to Heroku! More info can be found over at [superscript-heroku](https://github.com/bmann/superscript-heroku).`
60
61	`#### Express Client`
62
63	`[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/bmann/superscript-heroku/tree/master)`
64
65	`#### Slack Client`
66
67	`The slack-client branch creates a superscript powered bot that sits in your Slack. You'll need to create a bot and give it a name in the [Slack apps directory](http://my.slack.com/apps/A0F7YS25R-bots) in order to get a token that lets your bot connect to your Slack.`
68
69	`[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/bmann/superscript-heroku/tree/slack-client)`
70
71	`Creating the bot in the Slack directory means you'll see the bot appear in your Slack as offline. When your server from above is running correctly, the status of the bot will go green, and you can say "Hi" to it and it will respond.`
72
73	`## Upgrading to v1.x`
74
75	`Information on upgrading to v1.x can be found [on the wiki](https://github.com/superscriptjs/superscript/wiki/Upgrading-to-v1).`
76
77	`## Documentation`
78
79	`Visit [superscriptjs.com](http://superscriptjs.com) for all the details on how to get started playing with SuperScript. Or [read the wiki](https://github.com/superscriptjs/superscript/wiki)`
80
81	`### Example Script - Script Authoring`
82
83	`+ hello human`
84	`- Hello Bot`
85
86	`+` matches all input types
87
88	`-` Is the reply sent back to the user.
89
90
91	`### Optional and Alternates - Script Authoring`
92
93	`+ [hey] hello (nice\|mean) human`
94	`- Hello Bot`
95
96	`[]` are for optional words, they may or may not appear in the input match
97
98	`()` are alternate words. One MUST appear.
99
100	`### Capturing results - Script Authoring (wildcards)`
101
102	`+ * should ~2 work 1`
103	`- I have no idea.`
104
105	`*` Matches ZERO or more words or tokens
106
107	`*~n` Matches ZERO to N words or tokens
108
109	`*n` Matches exactly N number of words or tokens
110
111
112	`## And More`
113
114	`The above is just a tiny fraction of what the system is capable of doing. Please see the [full documentation](http://superscriptjs.com) to learn more.`
115
116
117	`### Additional Resources`
118
119	`* [Sublime Text Syntax Highlighting](https://github.com/mariusursache/superscript-sublimetext)`
120	`* [Atom Syntax Highlighting](https://github.com/DBozhinovski/language-superscript)`
121
122	`### Further Reading`
123
124	`* [Introducing SuperScript](https://medium.com/@rob_ellis/superscript-ce40e9720bef) on Medium`
125	`* [Creating a Chatbot](https://medium.com/@rob_ellis/creating-a-chat-bot-42861e6a2acd) on Medium`
126	`* [Custom Slack chatbot tutorial](https://medium.com/@rob_ellis/slack-superscript-rise-of-the-bots-bba8506a043c) on Medium`
127	`* [SuperScript the big update](https://medium.com/@rob_ellis/superscript-the-big-update-3fa8099ab89a) on Medium`
128	`* [Full Documentation](https://github.com/superscriptjs/superscript/wiki)`
129	`* Follow [@rob_ellis](https://twitter.com/rob_ellis)`
130
131	`### Further Watching`
132
133	`* [Talking to Machines EmpireJS](https://www.youtube.com/watch?v=uKqO6HCKSBg)`
134
135	`## Thanks`
136
137	`SuperScript is based off of a fork of RiveScript with idiom brought in from ChatScript. Without the work of Noah Petherbridge and Bruce Wilcox, this project would not be possible.`
138
139	`## License`
140
141	`[The MIT License (MIT)](LICENSE.md)`
142
143	`Copyright © 2014-2017 Rob Ellis`