Knowledge

---

Introduction — Triggers — Replies — Conversations — Topics — Plugins and Functions — Knowledge — Under the Hood

---

Knowledge

This introduces a new element called facts. Facts are triples aiming to provide common knowledge to your bot. They can be also used in generating part of a reply, by replacing a word in the reply.

Facts are used throughout SuperScript, in the script parser (ss-parse) and inside custom functions.

When passed into the parser, we allow terms to be expanded to be more expressive. For example:

+ I like ~sport
- Really? Wow, I like ~sport, too!

In the above example ~sport is expanded in both the gambit and reply, and resolved to a sport defined either in Wordnet or the facts DB. (For more technical details see sfacts).

To use this part of the system, you first need to pass in some options to the superscript engine, specifically factSystem object literal with importData which is an array of files, and a clean boolean to tell superscript to reload the data on reload. We store the underlining fact data in MongoDB.

const superscript = require('superscript');
const options = {
  factSystem: {
    importData: [...],
    clean: true,
  },
  importFile: './data.json',
};

superscript.setup(options, (err, bot) => {
  botHandle(null, bot);
});

Data Format

The fact system takes data in 2 formats, either as a table or concept hierarchy.

Concepts

Concepts are defined like this: concept <name> (list_of_words_or_other_concepts)

The file we store them in should end in .top ie: sports.top

concept: ~sport (~aerial_sports ~combat_sports ~equestrian_sports ~gymnastics ~minor_outdoor_activities
~mountain_sports ~precision_sports ~skate_sports ~sports_ball ~sports_raquet ~track_field_sport 
~water_sports ~winter_sports ~wnsport  sport team )

All concept must start with a ~.

We would then further define the linked concepts elsewhere in the file ie:

concept: ~combat_sports (aikido boxing capoeira fencing judo jujitsu jujutsu
 karate kendo kung_fu martial_art~1 shinjutsu sumo wrestling )

So when we use ~sport in our script, we know the term could be one of aerial_sport, combat_sports, equestirian_sports etc.

Also, ~sport does not match sport directly since it uses a isA relationship, so that term is also included in the top list.

Tables

Table files should end in .tbl ie: opposites.tbl

Tables have 2 sections, the header definition, and DATA here is an example of opposites.tbl:

table: ~opposites (^arg1 ^arg2)
^createfact(^arg1 opposite ^arg2)
^createfact(^arg2 opposite ^arg1)
DATA:
taller shorter
longer shorter
smile frown
tall short
save spend
artifact natural_object

We first give the table a name and list say how many arguments we expect table: ~opposites (^arg1 ^arg2) Then we define how the fact should be created ^createfact(^arg1 opposite ^arg2) and ^createfact(^arg2 opposite ^arg1)

createfact takes three arguments, but we only define 2, the subject and object. The verb is hard coded to opposite. We define two facts because we want to be able to key off the subject or object in either order.

The data section below is a space delimited list with _ for spaces.

We provide one other varient to this syntax where the data can also contain an array of terms.

table: ~colorof (^color ^object)
^createfact(^object color ^color)

 DATA:
 green [grass leaf plant emerald ~plants turtle parsley topaz]
 blue [sky water bluebell blue_screen_of_death blue_jeans jeans blueberry 
ocean sea lake ink blue_jay  eye]

Here we create a fact for each item in the list.

User knowledge

From within SuperScript, you can save data directly to the fact system by using a plugin function save, createFact or createUserFact.

Save / Get

Save is a key/value semantic sugar on top of SVO using the user_id as the 'verb'. ^save("key","value")

Get will fetch the item for the user ^get("key")

createUserFact / queryUserFact

If you want to use the entire triple, you can call ^createUserFact("subject","verb","object"). And to fetch data use ^queryUserFact("subject", "verb") This method will actually search "subject" / "verb" and fall back to "obect" / "verb" if that fails.

---

Continue to Under the Hood