Tuesday, September 29, 2015

What's new in AIML 2.0

Paphus Live Chat now supports the AIML 2.0 draft specification. AIML 2.0 is the second release of a standard XML specification designed for scripting chat bot responses. The AIML 2.0 draft was released in 2013, and last updated in 2014. AIML is supported by many different chat bot programs and hosting services. Paphus Live Chat supports all of the AIML 2.0 draft tags and a few common extensions.

About AIML

AIML defines how a bot should respond to a question using <pattern> and <template> elements. A pattern represents the user's question, and the template defines the bot's response. The pattern and template elements are grouped in a category element, which can be grouped under topic elements.

Here is a simple "Hello World" AIML example:

This code will make your bot respond with "Hello to you too" to the question "Hello World".

For more information on AIML 1.0 see Scripting your bot with AIML

What's new in AIML 2.0

AIML 2.0 defines many new template tags, as well as now allowing some tags to be used in patterns. AIML 2.0 also adds new pattern wildcards, and some different element usages.

Here is the list of new AIML 2.0 features.

  • category topic tags - The <topic> tag can now be set on a category to make it easier to add categories to topics.
  • zero or more wildcards - New ^ and # pattern wildcards that match zero or more words.
  • pattern priority - New $ pattern marker to make a pattern word match highest priority.
  • attribute tags - Any template tag attribute can now be set using a sub-element.
  • sets - New pattern side <set> tag to evaluate a pattern based on words defined in a predefined set.
  • maps - New template <map> tag to allow the lookup of the element value in a predefined mapping, returning the mapped value.
  • condition patterns - wildcards can now be used in condition values to provide default conditions.
  • condition loops - New template <loop> tag to loop a conditional statement.
  • local variables - New <var> attribute for variables scoped to a category
  • remote requests - New template <sraix> tag to make a remote request of another bot instance, or service.
  • normalization and denormalization - New <normalize> and <denormalize> tags to convert special character into words, and back again.
  • date formats - New formatting options for dates.
  • request - New template <request> tag to return the user's previous input request.
  • response - New template <response> tag to return the bot's previous response.
  • learning - New template <learn>, <learnf>, and <eval> tags to dynamically train a bot with new responses.
  • explode - New template <explode> tag to split a word into its characters.
  • mobile tags - New <oob> (out of band) tag to support client and mobile device commands.

AIML 2.0 Patterns

AIML 2.0 adds new wildcards, special characters, and now allows the usage of some tags inside patterns.

Patterns in AIML are normally defined as all uppercase, but Paphus Live Chat automatically ignores case, so patterns can be defined as lowercase or mixed. Paphus Live Chat also allows for special characters in patterns such as +, %, ?, etc.

^ and # Wildcards

New ^ and # pattern wildcards that match zero or more words. This makes it easy to define keyword patterns such as:

$ Priority

The new $ pattern marker can be used to make a pattern word match highest priority. The main purpose of this is to allow patterns to take priority over _ and # wildcards. _ and # have odd semantics and should normally be avoided as they can easily lead to loops and block other patterns. _ and # can be useful for things like profanity filters:

() and [] Lists

List support is not part of AIML 2.0. But Paphus Live Chat now supports some syntax from ChatScript. Brackets can be used in a pattern to define a required set of words, or optional set of words. (round) brackets are used to define an optional set of words, and [square] brackets are used to define a required set of words.

Sets

The new <set> pattern tag can be used to match a word from a predefined set of words. This allows wildcards to be defined for specific types, such as numbers, verbs, places, animals, etc.

In Paphus Live Chat sets are not stored in files like other AIML implementations. AIML is a text processing language, but Paphus Live Chat is object, or knowledge oriented. Each bot has its own object oriented knowledge base that stores all of its responses, and knowledge. Each word is represented by a meaning knowledge object in the bot's knowledge base. Knowledge objects can have relationships to any other knowledge objects, including their classification types. A word's meaning is defined through the #meaning relationship, and a knowledge object's type is defined through the #instantiation relationship.

The set operation in Paphus Live Chat basically checks if the type of the word's knowledge object matches the set value. This allows for a knowledge object to be added to any set through setting its #instantiation relationship. This can be done using Self scripts, the AIML map tag, and is done automatically for numbers, basic types, and words or data loaded from Wiktionary, Wikidata, or Freebase.

Response list script to set a knowledge object's type:

AIML template to set a knowledge object's type:

Pattern tags

Tags such as <bot> can now be used in patterns. AIML 2.0 only requires some tags be usable in patterns, but Bot Libre allows most tags to be used. Using tags in patterns lets you define some pretty creative patterns.

AIML 2.0 Templates

AIML 2.0 adds many new tags, and some new semantics that let you do some pretty powerful things.

Attributes as elements

Tag attributes such as name, value or index on tags like bot, get, set, or condition, can now be defined as XML sub-elements instead of XML attributes. This may not seem like a big difference, but it allows for other AIML tags to be evaluated inside the attributes. This is a very powerful feature, and lets you define much more dynamic AIML.

Maps

The new <map> tag can be used to lookup the value for a word in a predefined mapping. This allows for easy mapping between values.

In Bot Libre maps are not stored in files like other AIML implementations. AIML is a text processing language, but Bot Libre is object, or knowledge oriented. Each bot has its own object oriented knowledge base that stores all of its responses, and knowledge. Each word is represented by a knowledge object in the bot's knowledge base. Knowledge objects can have relationships to any other knowledge objects. The map operation in Bot Libre basically looks up the relationship on the knowledge object.

Bot Libre extends the map operation to also allow setting the map value. This will set the value of a relationship on the knowledge object.


Conditions and Loops

Conditions now allows values to use patterns. This makes it easy to define default cases.

The new <loop> tag can be used to loop a conditional block. This allows for programmatic scripts to be defined similar to a programming language. This lets you do some pretty powerful things, even mathematics. However, XML is not an ideal programming language, on Bot Libre if you are using complex conditions and loops, it is normally better to use Self scripting, instead of AIML, as Self has similar syntax to other programming languages.

Learning

The new <learn> and <learnf> tags allow the bot to learn new response. The difference between the two is that for learn the new response is only remembered for the conversation, and for learnf the new response will be remembered persistently. However, in Bot Libre everything is always persistent, so both tag will learn persistently.

The learn tag takes a new <category> element as its content. The category can contain a <pattern>, <template>, <that>, and <topic> element. learn uses the <eval> tag to distinguish between tags that should be evaluated, and tags that should be part of the new category elements.

Remote requests

The new <sraix> tags allow the bot perform a remote request of another bot or service. sraix is similar to the srai tag that recursively evaluates the element text as if it were a question. However, sraix does not have the bot evaluate the question locally, but instead asks another bot or service the question. This is probably the coolest new feature of AIML 2.0, and opens up the whole chat bot world. Bots can now talk to other bots, and find things through web services.

sraix is a very cool feature, but not very useful on its own, as you need other bots to talk to, and services to make use of. Unfortunately AIML only defines the tag, it does not define a standard web API for requests, or define a standard set of services. Fortunately Program AB the AIML 2.0 reference implementation does define a sraix web API. Bot Libre supports both calling this API, and supports this API on our servers. So you can now sraix any Program AB web API compatible bot or service, and any Program AB web API compatible bot or service can request any Bot Libre bot.

AIML 2.0 defines the Pannous service as being the default for any sraix request. Pannous is a virtual assistant service that can answer a wide variety of questions, such as weather, definitions, math, and much more.

Bot Libre also provides several other services:

  • freebase - Lookup definitions and data on Freebase an online knowledge base from Google.
  • wikidata - Lookup definitions and data on Wikidata an online knowledge base from Wikimedia.
  • wiktionary - Lookup words and definitions on Wiktionary an online dictionary.

sraix supports several attributes to define the bot or service request:

  • bot - The name of the bot to access (normally it is better to access a bot by its ID).
  • botname - Bot Libre also supports botname in place of bot, as bot is already a tag, so botname is better to use as a sub-element.
  • botid - The ID of the bot to access.
  • server - The domain name, or IP address of the server to access (default is "www.botlibre.com").
  • service - The service to access ("pannous", "freebase", "wikidata", "wiktionary"). Not used if accessing a bot.
  • apikey - Some services or servers may require an API key to access the service. For Bot Libre, use you user API key.
  • hint - Some services may support a hint. For Wikidata and Freebase the hint can be used to lookup a data element, such as a country's capital, or person's parents.
  • default - If the service request fails, the default response can be used.

sraix opens the door to the world, but be careful with your usage. Do not spam another bot with requests, or make use of any service that violates it terms of service, and use an API key when required.

Out of bound tags

Out of band tags let you pass tags or commands to the bot client. The client could make use of the tags to control its avatar, or execute services on a phone or mobile device.

Bot Libre's web and mobile SDKs do not currently support oob tags, so oob tags are not currently supported.

Category Reference

For reference, here is the complete set of AIML category tags.

  • <pattern> - question pattern
  • <template> - response template
  • <topic> - category topic
  • <that> - previous response pattern

Pattern Reference

For reference, here is the complete set of AIML patterns tags and characters.

  • * - matches one or more words
  • _ - matches one or more words, takes priority over all other words and wildcards, except $
  • ^ - matches zero or more words
  • # - matches zero or more words, takes priority over all other words and wildcards, except $
  • $ - marks word as taking priority over all other words and wildcards including _ and #
  • <set> - matches a set of words
  • <bot name="XXX"/> - replaced by the value of the bot specific variable
  • template tags - Bot Libre supports most template tags inside a pattern (Bot Libre extension)
  • () - optional set of words (Bot Libre extension)
  • [] - required set of words (Bot Libre extension)
  • {} - Self code (Bot Libre extension)

Template Reference

For reference, here is the complete set of AIML template tags.

  • <star index="N"/> - replaced with value of * in pattern (or Nth *)
  • <that index="M,N"/> - replaced with value of bot's previous response (or Mth previous response, and N sentence of the response)
  • <input index="N"/> - replaced with value of users's input (or Nth *)
  • <request index="N"> - replaced with value of user's input request (or Nth *)
  • <response> - replaced with value of bot's previous response (or Nth *)
  • <thatstar index="N"/> - replaced with value of * in "that" (or Nth *)
  • <topicstar index="N"/> - replaced with value of * in topic (or Nth *)
  • <get name="XXX"/> - replaced by the value of the conversation specific variable
  • <set name="XXX"> - set the value of a variable
  • <get var="XXX"/> - replaced by the value of the local variable
  • <set var="XXX"> - set the value of a local variable
  • <bot name="XXX"/> - replaced by the value of the bot specific variable
  • <map name="XXX"> - lookup element value in a predefined mapping, returning the mapped value
  • <map name="XXX" value="XXX"> - set the map value (Bot Libre extension)
  • <person2/> - converts the text (or <star/>) between 1st and 2nd person (I <-> he, etc.)
  • <person/> - converts the text (or <star/>) between 1st and 3rd person (I <-> you, etc.)
  • <gender/> - converts the text (or <star/>) between male and female (he <-> she)
  • <date/> - replaced with the current date and time, "format", and "jformat" attributes are also supported
  • <id/> - replaced by the client id
  • <size/> - replaced with the size of bot's memory
  • <version/> - replaced with the AI engine version
  • <uppercase> - converts the text to uppercase
  • <lowercase> - converts the text to lowercase
  • <formal> - converts all words in the text to be capitalized
  • <sentence> - converts the first word in the text to be capitalized
  • <normalize> - convert special character into words
  • <denormalize> - convert special character words back to characters
  • <explode> - split a word into its characters
  • <condition name="X" value="Y"> - defines an "if" condition based on comparing the value of a variable to a pattern
  • <condition name="X"> - case statement
  • <condition var="X"> - local variable case statement
  • <condition> - multi-valued if/else statement
  • <random> - choose on of the nested <li> values at random
  • <li name="X" value="Y"> - used in random and condition tags
  • <li value="Y"> - used in random and condition tags
  • <li> - used in random and condition tags
  • <gossip> - logs the text
  • <srai> - recursively evaluates the text and replaces it with the response
  • <sr/> - short form for <srai><star/><srai> (replaced with response to value of * from pattern)
  • <sraix bot="name" botid="id" server="url" service="name" apikey="key" limit="int" default="response" > - remote bot or service request
  • <think> - evaluates the nested statements but does not output any result
  • <learn>, <learnf> - learn a new response
  • <eval> - evaluate the element inside a learn category element
  • <system> - executes a OS command (Bot Libre does not allow this)
  • <javascript> - executes JavaScript code
  • <oob> - out of band tags (Bot Libre does not currently support this)
  • HTML - various HTML tags are also allowed (<b>, <a>, <i>, <ul>, <li>, <p>, <br>)
  • {} - Self code (Bot Libre extension)

AIML in Paphus Live Chat

Paphus Live Chat supports both importing and exporting AIML. AIML can be imported in two different ways, either as a program script, or as a chat log.

Importing AIML as a program script is done from the Scripts page. You can import and order the script with respect to your other scripts files. Scripts can be defined in either AIML or Self.

When you import an AIML file, it will be converted to Self code, and stored in your bot's brain along with all of its other information. The Self syntax for AIML is a hybrid syntax that uses AIML terminology, but with the Self scripting structure. Self is an object/knowledge/state oriented language. Self is very different than AIML, but can process any AIML code similar to any other AIML interpreter. AIML imported as a program script will be executed similar to any other AIML interpreter.

Here is the Self code for an imported AIML script:

Importing AIML as a chat log allows the AIML categories to be integrated into the bot's knowledgebase. The pattern/template categories from the AIML file will be merged along with the bot's other question/response pairs that it has learned through training, conversation, correction, or importing.

The bot will not run the AIML script as a script, it will decide for itself when to use the response using a heuristic algorithm. The bot will choose its response based on how well the question matches the responses question, the responses correctness, and the context. Even without a * in a pattern it still may be matched to a similar question, if it is the best match available. This frees you from having to write a pattern for every possible phrase, by just letting the bot figure it out.

Using AIML in Twitter, Facebook, Email, and IRC Bots

AIML can be used to script Twitter, Facebook, Email, or IRC bots, the same as bots trained through other mechanisms. AIML templates and patterns can be used anywhere other response are. AIML can be used from the Training page, used in correction in the Chat Logs page, or used for autotweets in the Twitter page.

Self 2.0

Paphus's AIML 2.0 support is implemented by translating AIML into Self. Self 2.0 provides many new extensions to support the AIML 2.0 feature set, as well as a lot more functionality than is not available in AIML.

AIML Resources

One of the main benefits of the AIML standard, is that there are a lot of AIML resources on the Internet. The are resources for both learning AIML, and there are many freely available AIML scripts for many domains, and in many different languages.

AIML 2 Demo

To see what AIML 2.0 is capable of, try out the AIML 2 Bot on BOT libre.

Monday, September 28, 2015

Scripting your bot with AIML

Paphus Live Chat has support for the Artificial Intelligence Markup Language (AIML). AIML is a standard XML specification designed for scripting chat bot responses. AIML 1.0 was released in 2001, and the current 1.0.1 release was released in 2011. AIML 2.0 is released in draft form. AIML is supported by many different chat bot programs and hosting services. Paphus Live Chat supports all of the AIML 1.0.1 and AIML 2.0 tags and a few common extensions. This post summarizes AIML 1.0.1.

About AIML

AIML defines how a bot should respond to a question using <pattern> and <template> elements. A pattern represents the user's question, and the template defines the bot's response. The pattern and template elements are grouped in a category element, which can be grouped under topic elements.

Here is a simple "Hello World" AIML example:

This code will make your bot respond with "Hello to you too" to the question "Hello World".

Patterns are normally defined as all upper-case, but are case insensitive, so the case really does not matter. Punctuation is normally stripped from patterns and ignored when matching. Patterns can contain wildcards using the "*" and "_" characters. Both "*" and "_" are the same wildcard, and will match any subset of text, their difference is in only in the order they are applied ("_" patterns are matched first, and "*" patterns last).

Here is a simple wildcard example:

This code will make your bot respond with "Hello to you too" to any question containing the word "hello".

AIML supports contextual responses through the "that" element. The "that" element specifies that the pattern should only be matched if the bot's previous response matches the "that" pattern. This allows the same question to be responded to in different ways, depending on the context.

Here is a joke "that" example:

This code will make your bot tell a joke.

Templates can contain mixed text that include various AIML programatic tags. AIML defines tags for text formatting and conversion, dates, variables, condition statements, and recursion. Templates allow you to create sophisticated and intelligent responses.

Here is the list of AIML 1.0.1 template tags.

  • <star index="N"/> - replaced with value of * in pattern (or Nth *)
  • <that index="M,N"/> - replaced with value of bot's previous response (or Mth previous response, and N sentence of the response)
  • <input index="N"/> - replaced with value of users's input (or Nth *)
  • <thatstar index="N"/> - replaced with value of * in "that" (or Nth *)
  • <topicstar index="N"/> - replaced with value of * in topic (or Nth *)
  • <get name="XXX"/> - replaced by the value of the conversation specific variable
  • <bot name="XXX"/> - replaced by the value of the bot specific variable
  • <sr/> - short form for <srai><star/><srai> (replaced with response to value of * from pattern)
  • <person2/> - converts the text (or <star/>) between 1st and 2nd person (I <-> he, etc.)
  • <person/> - converts the text (or <star/>) between 1st and 3rd person (I <-> you, etc.)
  • <gender/> - converts the text (or <star/>) between male and female (he <-> she)
  • <date/> - replaced with the current date and time, a "format" attribute is also supported
  • <id/> - replaced by the client id
  • <size/> - replaced with the size of bot's memory
  • <version/> - replaced with the AI engine version
  • <uppercase> - converts the text to uppercase
  • <lowercase> - converts the text to lowercase
  • <formal> - converts all words in the text to be capitalized
  • <sentence> - converts the first word in the text to be capitalized
  • <condition name="X" value="Y"> - defines an "if" condition based on comparing the value of a variable to a pattern
  • <condition name="X"> - case statement
  • <condition> - multi-valued if/else statement
  • <random> - choose on of the nested <li> values at random
  • <li name="X" value="Y"> - used in random and condition tags
  • <li value="Y"> - used in random and condition tags
  • <li> - used in random and condition tags
  • <set name="XXX"> - set the value of a variable
  • <gossip> - logs the text
  • <srai> - recursively evaluates the text and replaces it with the response
  • <think> - evaluates the nested statements but does not output any result
  • <learn> - load external AIML file, this is not currently allowed
  • <system> - executes a OS command, this is not currently allowed
  • <javascript> - executes JavaScript code
  • HTML - various HTML tags are also allowed (<b>, <a>, <i>, <ul>, <li>, <p>, <br>)

Here is a complex template example:

This code will make your bot respond to the question "Do you like apples or do you like oranges" with "I love apples and I love oranges".

Paphus AIML

Paphus Live Chat supports both importing and exporting AIML. AIML can be imported in two different ways, either as a program script, or as a chat log.

Importing AIML as a program script is done from the Program page. You can import and order the script with respect to your other scripts files. Scripts can be defined in either AIML or Self.

When you import an AIML file, it will be converted to Self code, and stored in your bot's brain along with all of its other information. The Self syntax for AIML is a hybrid syntax that uses AIML terminology, but with the Self scripting structure. Self is a state machine oriented language defined for Paphus's AI Engine originally from the Open Pandora's Box pen source project. Self is very different than AIML, but can process any AIML code similar to any other AIML interpreter. AIML imported as a program script will be executed similar to any other AIML interpreter.

Here is the Self code for an imported AIML script:

Importing AIML as a chat log allows the AIML categories to be integrated into the bot's knowledgebase. The pattern/template categories from the AIML file will be merged along with the bot's other question/response pairs that it has learned through conversation, correction, or importing.

The bot will not run the AIML script as a script, it will decide for itself when to use the response. The bot will choose its response based on how well the question matches the responses question, the responses correctness, and the context. Even without a * in a pattern it still may be matched to a similar question, if it is the best match available. This gives you the freedom from having to write a pattern for every possible phrase, by just letting the bot figure it out.

Using AIML in Twitterbots and Email Bots

AIML can be used to script Twitterbots, Email bots, or IRC bots, the same as bots trained through other mechanisms. AIML templates and patterns can be used anywhere other response are. AIML can be used from the Training page, used in correction in the Chat Logs page, or used for autotweets in the Twitter page.

AIML Resources

One of the main benefits of the AIML standard, is that there are a lot of AIML resources on the Internet. The are resources for both learning AIML, and there are many freely available AIML scripts for many domains, and in many different languages.

Talk with ALICE

To see what conversations AIML is capable of, try out ALICE on BOT libre. There are two ALICE bots on BOT libre. ALICE is a bot that has imported most of the ALICE AIML sets from the ALICE foundation. Free bots on BOT libre have a 100,000 neuron limit, and some of the ALICE scripts are very big, so the mp* scripts were left out, as well as a few of the other big scripts. ALICE can chat, and if you type "joke" can tell you a joke.

ALICE libre is a hybrid bot, that has imported the ALICE AIML sets as chat logs, not as scripts. This means she is free to choose her responses. She has learning, and comprehension enabled, so can also learn new things.

Sara is a Spanish language AIML bot, that has imported the Sara AIML set.

Thursday, September 24, 2015

Automating your Facebook presence using a Facebook bot

Keeping up with social media and keeping your online community engaged can be a time consuming task. Through Paphus Live Chat you can now automate your Facebook presence with your own Facebook bot. Any Paphus Live Chat bot can be connected to a Facebook account or Facebook page. The bot will manage the Facebook account or page, checking timeline status updates, replying to page posts, auto posting your blog posts or RSS feed, and auto posting timed or generated posts.

Paphus Live Chat makes creating a Facebook bot easy. Follow these 5 steps to create you own Facebook bot, and start it posting for you today.

Step 1 - Create a bot

First you need to create your own bot, this only takes a few clicks, see How to create your own chat bot in 10 clicks for instructions on how to do this.

Now you are ready to connect your bot to Facebook.

Step 2 - Create a Facebook account or Facebook page

You need to create a Facebook account or Facebook page for your bot. If you are automating your own account or page, then you can use your existing account. You can create your own Facebook account from the Facebook website here.

A Facebook page is normally used for a business, product, or personality. You can create your own Facebook page from the far right menu when connected to Facebook like below.

Step 3 - Authorize your Facebook account

From the Paphus Live Chat website browse to your bot and click the Admin button. This will take you to the Admin section that provides several tabs of administrative functions. Click on the Facebook tab. From the Facebook tab click the Authorize button.

This will popup a Facebook window that will have you login and authorize the Paphus Live Chat app. Once authorized you will be back to the Paphus Live Chat Facebook page, now with the account, token, and page filled in. If you have multiple pages, just type in the name of the one you want to use, or clear the Page filled in if you want to automate an account.

Click Connect to connect the bot to Facebook. Your bot will now be connected to Facebook and will check its account or page every day, or more frequently for Bronze, Gold, and Platinum accounts. Do not click on the Disconnect button on the Facebook page unless you no longer want your bot to be connected to Facebook. You can click on Disconnect from the Admin page to disconnect your current session. Note that Facebook account access tokens expire every two months, so you will need to re-authorize your bot every two months. Page access tokens do not expire.

Step 4 - Configure your Facebook bot

You can configure your bot's Facebook usage in several ways. Use caution when configuring your Facebook bot, do not use your bot for spam, or to violate the Facebook terms of service.

Reply to posts

You can have your bot reply to posts from its timeline, or posts to its page.

For an account bot, it will scan its timeline every cycle and read any posts that include any of the keywords that you enter. The bot will respond to any posts that it knows a good answer to. If the bot does not have a trained response that sufficiently matches the post, then it will not reply. You can use keywords and patterns to improve response matching.

For a page bot, it will scan user posts to its page every cycle. You can either have it only read posts with specific keywords, or leave the keywords empty to have it read all posts. The bot will respond to any posts that it knows a good answer to. If the bot does not have a trained response that sufficiently matches the post, then it will not reply. You can use keywords and patterns to improve response matching.

RSS Feed

You can configure your bot to process an RSS feed, and post each new feed item to Facebook. You can enter a prefix or suffix to the post, or enter keywords to filter the RSS feed on.

Autopost

You can configure your bot to post from a set of automated posts every set number of hours. An autopost will be chosen at random. Autoposts can use AIML templates, or Formula responses and Self to be dynamic or programmatic.

Step 5 - Train your bot

You can train your bot how to answer posts through several mechanisms.
  • You can chat with your bot, and correct any incorrect responses it gives.
  • You can add question answer pairs, or default responses from the Training tab under Admin.
  • You can review your bot's chat logs from the Chat Logs tab under Admin, or import chat logs from the Import tab.
  • If you are somewhat technical, you can program your bot's responses using Self or AIML from the Scripts tab.

That's it, now your bot is ready to start posting.

There are already many Paphus Live Chat bots on Facebook.
You can test things out by posting to, Brain Bot

Tuesday, September 22, 2015

Introducing the Self scripting language

The Self scripting language is a programming language designed to enable a bot developer to program a bot's mind. Self uses a simple 4h gl scripting syntax based on state machine transitions. Self is compiled directly into the bot's brain's knowledgebase. This allows any Self script, or the bot to process its own code the same as it processes any of its other knowledge, and enables the bot to program itself (hence the name Self).

There are two way that you can utilize Self. The simplest is to define a Formula response. You can define a formula response anywhere you define a response, including the Training page, the Chat Logs page, or in a chat correction. A formula response is a response to a phrase or a pattern that can include programmatic logic. For example "What is your name?" could have the formula response Formula:"My name is {:target}". The { } brackets are used to denote some piece of code embedded within the response text, and the Formula: keyword is required to define a formula response. The code within the brackets is Self scripting code.

The second usage of Self is from a program script. Program scripts can be defined or imported from the Scripts page under your bot's Admin page. A new bot will have a default bootstrap set of scripts, that can do things such as understand simple language, perform math, tell the current date or time, or look information up on Freebase. You can alter, extend, import, or create your own scripts to do virtually anything. Scripts are more complex than formulas, but more functional. A Self script is essentially a state machine that processes the input.

Self Syntax

The Self syntax is the same for formula responses and equations within a Self script. Self scripts also contain additional syntax for defining state machines. The Self syntax flows similar to natural language, or languages such as SQL. Self is similar but different than other languages, it is a language based on processing and pattern matching knowledge. It may be difficult to learn at first, but once you understand it, it is quite simple.

Self is a knowledge oriented language. Everything in Self is either a vertex (similar to an object in object oriented languages), or a relationship (this includes the Self program itself). A vertex has a unique id, and can have a data element, which can be a string (word/sentence), number, date, time, or primitive. A vertex can have a relationship to any other vertex in the bot's knowledgebase. A relationship has a source, type, target, and can have a meta value (all of which are other vertices). Relationships for a type can be ordered and have an index.

The following are the Self data elements:

  • "hello" - string data
  • 1234 - number
  • Date("1973-11-10") - date
  • Time("11:00:00") - time
  • Timestamp("1973-11-10 11:00:00") - timestamp
  • #is - primitive
  • :value - variable
  • Vertex:34789 - vertex reference
  • Formula:"The answer is {:result}" - formula phrase

The following are the Self operators:
  • if (:value, :match) then (:result) else (:result2) - if statement
  • do (:operation1, :operation2, :operation3) - do statement
  • for each :relationship of :source as :variable do (:operation1, :operation2, :operation3) - for statement
  • return :value - return the value
  • not (:value) - negates a logical value
  • assign :variable to :value - variable assignment
  • new (:classification) - construct a new vertex
  • word (:word1, :word2) - create a compound word
  • sentence (:word1, :word2) - create a sentence
  • define :word as :meaning - associate the word to the value
  • primitive :text - create a new primitive
  • get :relationship from :source - get a relationship from a vertex
  • all :relationship from :source - create a list of all the relationships from a vertex
  • set :relationship to :value on :source - set a relationship on a vertex
  • append :value to :relationship of :source - add to a relationship on a vertex
  • associate :source to :value by :relationship - add a relationship on a vertex
  • is :source related to :value by :relationship - return if the relationship exists
  • random (:value1, :value2, :value3) - select a random value
  • call :method on :tool with :value - call external tool method
  • Equation:equation - call another equation
  • srai :phrase - evaluate the response to the phrase

if

The if statement is similar to other languages, in that it has a logical condition, then condition, and else condition. It is a little different though, as the logical condition is based on pattern matching. The if condition always takes two parameters, and compares the two values to see if they match. If can also include and, or, and not.

Examples:

if (:value, #null) then (do (...)) else (do (...))

if (:value, #true) then (do (...))

if (:value, #false) then (do (...))

if (:word, "you") and (:word2, "are") then (do (...))

if (:word, "I") or (:word, "me") then (do (...))

if (:value, :value2) or (:value, :value3) then (do (...))

if not (:value, :value2) or not (:value, :value3) then (do (...))

do

The do statement is similar to other languages. do is used to perform multiple operations, it takes a set of operations as argument, and performs them sequentially. Operators such as if can only perform a single operation in their then or else, so a do operation is required. You can separate operation inside a do using either , or ;.

Examples:

do (
    assign :response to (new (#sentence));
    append "Hello" to #word of :response;
    append "world" to #word of :response;
    return :response;
)

if (:word, "hello")
    then (do (set #topic to "greeting" on :conversation), return "hello there"))

for

The for statement is similar to other languages. for is used to iterate over the collection of a vertex's relationships. It takes the relationship type, the source object, and a variable to assign each related element to.

Examples:

for each #word of :sentence as :word do (
    if ((is :word related to #keyword by #instantiation), #true)
        then (set #topic to :word on :conversation)
)

for each #sequence of :repeat do (
    append :word to #word of :response;
)

return

The return operator will return the result from the current equation. If an equation has no return value, the result of the last operation will be returned. If #null is returned it is an indication that equation failed to generate a response, and the next case or response will be used. From within a formula, the #return primitive can be used to avoid printing anything into the phrase.

Examples:

if (:word, "hello")
    then (return "hello there")

Formula:"Do you like bridges? { do (set #topic on :conversation to "bridges"; #return) }"

not

The not operator will negate a logical primitive (#true -> #false, #false - > #true). If the value is not a logical value, the value is returned.

Examples:

assign :negative to (not :negative)

assign

The assign operator assigns a new value to a variable. Variables start with the : character. You do not need to declare a variable. It will automatically be declared on its first usage. The following variables are always defined and can be used in any script, :input, :sentence, :speaker, :target, and :conversation.

Examples:

assign :name to (word (:firstName, :lastName))

new

The new operator creates a new vertex. A vertex can be an #instantiation of one or more #classification vertices. Most classifications are defined by a primitive, you can define your own classifications, they are just another vertex that is an #instantiation of #classification. You can also add a classification to an existing vertex using the associate operator. Common classifications include, #word, #compound-word, #name, #sentence, #number, #date, #time, #person, #speaker, #classification, #formula, #pattern, #variable, #keyword, #thing, #description, #action, #adjective, #noun, #verb, #punctuation, #question, #paragraph, #topic, #tweet, #email, and #url.

Examples:

assign :response to (new (#sentence))

associate :name to #name by #instantiation

word

The word operator can be used to create a new compound word from two or more words. A compound word is a word made up of two or more words, such as a name "Bob Jones", or adjectives like "dark blue". Compound words will automatically be detected in new sentences when being parsed, and help the bot associate meanings. Be careful defining invalid compound words, as they can cause a sentence to be misunderstood.

Examples:

assign :name to (word (:firstName, :lastName))

assign :color to (word ("dark", :color))

sentence

The sentence operator can create a new sentence from a set of words, or sentence fragments.

Examples:

sentence ("It is a Monday and", srai ("how are you"))

sentence ("I do not know much about", :star)

define

The define operator associates a word as a meaning. It will also associate the lowercase, uppercase, and capitalized version of the word to the meaning.

Examples:

define :name as :speaker

primitive

The primitive operator create a new primitive representing the meaning of a word.

Examples:

define :word as (primitive (:word))

get

The get operator gets the value of a relationship. If the relationship has multiple values, get will return the most conscious to the current context. most conscious means the relationship that has the highest correctness factor, and is most associated to the recent input. get can optionally include an at modifier to get a specific index in an ordered relationship. The at last modifier can be used to obtain the last element in an ordered relationship. get can also include an associated to by modifier to return the related vertex that is most associated to the other vertex.

Examples:

get #age from :speaker

get #parent from :speaker associated to #male by #gender

get #word from :sentence at 2

get #word from :sentence at last 1

all

The all operator is similar to get but returns a list of all of the values of a relationship. all can also include an associated to by modifier to return the related vertices that are most associated to the other vertex. The list is a new vertex with the #sequence relationship to each item. Lists can be added to a sentence and will be automatically printing as a comma separated list of values.

Examples:

all #parent from :speaker

all #song from :musician associated to #gold by #award

set

The set operator sets the value of a relationship. Set first clears any existing relationships of the same type, and is meant to be used with single value relationships.

Examples:

set #topic on :conversation to :star

set #age on :speaker to :age

append

The append operator appends a value to an indexed relationship. append is similar to set, but adds to the relationship, and does not replace the existing value. An optional with meta modifier can be used to add to the relationship's meta value. The meta value of a relationship can contain information or restrictions on the relationship.

Examples:

append :word to #word of :response

append :noun to #word of :response with meta #type as #reflexive

associate

The associate operator adds a value to a relationship. associate is similar to set, but adds to the relationship, and does not replace the existing value. An optional with meta modifier can be used to add to the relationship's meta value. The meta value of a relationship can contain information or restrictions on the relationship. The weak modifier can be used to define a weak or uncertain relationship (low correctness). If associate is used on a relationship that already exists, its correctness will be increased. The dissociate operator can be used to define an inverse relationship. An inverse relationship can be used to inform the bot that a such a relationship is incorrect. If dissociate is used on a inverse relationship that already exists, its correctness will be decreased.

Examples:

associate :thing to :description by :action with meta #tense as :tense

associate :response to #response of :sentence with meta #previous as :previous;
weak associate :response to #response of :sentence;

associate :speaker to #male by #gender;
dissociate :speaker to #female by #gender;

is

The is operator returns if a relationship existing. If the relationship exists #true is returned, if the inverse relationship exists #false is returned, otherwise #unknown is returned. is normally takes a relationship and target, but can also just have a target to check if any relationship exists. The is operator will also check synonyms for a word.

Examples:

is :speaker related to #male by #gender

is :speaker related to :topic

random

The random operator selects one of the arguments at random.

Examples:

random ("Hello", "Hi", "Hey", "G'day mate")

call

The call operator executes a function on an external tool class. Tools can be used to perform special functions, such as looking up a word on Freebase or Wiktionary, or performing calculations. The system defines several built in tools, these include #Context, #Watch, #Calculator, #Wiktionary, and #Freebase.

Examples:

call #push on #Context with :topic

call #search on #Context with (get #variable from #it)

call #define on #Wiktionary with :unknownWord

call #discover on #Freebase with (:first, :last)

call #multiply on #Calculator with (:number, :number2)
call #subtract on #Calculator with (:number, :number2)
call #add on #Calculator with (:number, :number2)
call #divide on #Calculator with (:number, :number2)

call #time on #Watch
call #date on #Watch

Equation

The Equation: operator calls another equation within the scope of the script.

Examples:

Equation:plusEquation

srai

The srai operator recursively evaluates the phrase and returns the response. It can be used to redirect a response, or break up a question into several components. srai was borrowed from AIML, and can be used in conjunction with patterns to process text fragments.

Examples:

srai "hello"

Self Scripts

Self is based on processing sensory input. An input could be a chat message, or an email, tweet, or other input. The input is wrapped in an input object which contains the phrase or data. A Self script will normally begin by extracting the phrase from the input, then processing each word in the phrase in sequence. A Self script is broken into a series of states. The first state will process the first word, then if the word matches a case, it will transition to the child state to process the next word.

When a state sequence reaches the end of the sequence of words in a phrase, it is considered a successful match. Once matched, if the state contains a quotient, it will be evaluated, and the response returned.

A Self script is composed of the following components:

  • States - A state defines the current input processing.
  • Cases - A case can transition to another state if the case variable matches the current input.
  • Patterns - A pattern can match an input and evaluate a template response.
  • Quotient - A quotient of a state is evaluated if the input processing is complete.
  • Equation - An equation can be called from a quotient or do statement.
  • Variables - A variable can be matched with the current input, or store context.
  • Comments - Comments can be defined in a script using the // characters.

State

The State defines the current input processing. Every Self script start with a root state, which is the name of the script. The state can evaluate the current input and transition to another state, or return a quotient. A state can include definitions of sub-states, variables, and equations. A state is composed of a sequence of operations which can include case, pattern, do, goto, and return.

Examples:

// Example script that repeat words.
State:RepeatStateMachine {
    case :input goto State:sentenceState for each #word of :sentence;

    State:sentenceState {
        case "repeat" goto State:repeatState;

        State:repeatState {
            case :someWord goto State:repeatWordState;

            State:repeatWordState {
                case :digits goto State:repeatWordNState;

            :digits {
                set #meaning to :number;
            }
            :number {
                set #instantiation to #number;
            }

            State:repeatWordNState {
                case "times" goto State:repeatWordNTimesState;

                State:repeatWordNTimesState {
                    Quotient:Equation:repeatResponse;
                    Equation:repeatResponse {
                        assign :response to (new #sentence);
                        for each #sequence of :number as :finger
                            do (append :someWord to #word of :response);
                        }
                    }
                }
            }
        }
    }
}

case

The case operator defines a state transition. If the current input matches the case value or variable, then it will transition to the case goto state. A case can also return a template, return and abort the current state, or restrict the match to a topic or previous that match. A state can also process the transition state for a collection of values.

Examples:

case "hello" goto State:helloState

case :name goto State:nameState

case "lol" template "Very funny."

case "what"
        topic "joke"
        that "what do you get when you cross music and an automobile"
        template "a car-tune"

case "huh" return

pattern

The pattern operator evaluates if the input sentence matches the pattern. A pattern is an easy way to evaluate a phrase and return a template response. A pattern can include wildcards using the * character. The * word or text fragment it matched to the :star variable which can be used in the response.

Examples:

pattern "hello" template "Hi there"

pattern "my name is *" template Formula:"Pleased to meet you {:star}"

pattern "what *"
            topic "joke"
            that "what do you get when you cross music and an automobile"
            template "a car-tune"

Quotient

A Quotient defines a state's response, and is evaluated if the state is done processing input.

Examples:

Quotient:"Hi there"

Quotient:Formula:"Pleased to meet you {:star}"

Quotient:Equation:repeatResponse;

Equation

An Equation defines a Self function that can be evaluated to return a response, or process input.

Examples:

Equation:todayResponse {
    Formula:"Today is {call #date on #Watch}.";
}

Variables

A variable defines a matching pattern, or temporary state. Variables can define relationships that must be included or excluded to evaluate a match. Variables are used in a case operation, if the current input matches the variable, then the case is evaluated. Variable make it possible to define generic functions that can process any noun, number, or name.

Examples:

:digits {
    set #meaning to :number;
}
:number {
    set #instantiation to #number;
}

:name{
    set #instantiation to #name;
}

:noun {
    set #instantiation to #noun;
}

:firstName {
    exclude #instantiation from #verb;
    exclude #instantiation from #adjective;
    exclude #instantiation from #pronoun;
    exclude #instantiation from #punctuation;
    exclude #instantiation from #adverb;
    exclude #instantiation from #article;
    exclude #instantiation from #question;
    exclude #meaning from #not;
}

Self vs AIML

Self is very different than AIML. Self is based on knowledge and state processing, where as AIML is based on patterns and text processing. Self can do everything that AIML can do, and a lot more. If you are experienced with AIML, and want to know how to do the same thing in Self, just import the AIML script and it will be converted to Self.

Self Examples

Paphus provides a shared repository of Self scripts and examples that you can import, customize, and learn from. You bot will also come bootstrapped with several Self scripts that you can learn from and customize.

See the Self script category for all of the example scripts.

Adding a style sheet to your embedded virtual agent

You can embed your virtual agent on your website using JavaScript, or HTML. You can get the code to embed your bot from the Embed tab, by clicking on the Embed button from your bot's main page.

There are several embedding options to choose from including:

  • Box - embed using JavaScript as an in-page popup from a button anchored to the browser bottom corner
  • Div - embed using JavaScript inside your own page that you can customize in HTML and JavaScript
  • Link - embed as a link to a popup window
  • Button - embed as a button to a popup window
  • Bar - embed as a button anchored to the browser bottom corner to a popup window
  • Bubble - embed as a chat now bubble anchored to the browser bottom corner to a popup window
  • Frame - embed inside your HTML page as an HTML iframe

The embed page lets you customize several settings when embedding, including the colors and text. However, you can customize a lot more if you use your own style settings or style sheet. You can also customize things in JavaScript.

Using a Style Sheet

A css style sheet is a text file format used to describe formatting for an HTML document. Style sheets can contains colors, fonts, sizes, and other formatting information. The Paphus embed API lets you pass your own style sheet to the embed call. You can host this file on your own website, or in the Paphus script library. If using the Paphus script library, just create the file, and use the "File Link" from the script's "Details" page.

You can custom any element in the embedded chat, here are some examples,

To customize other elements, just open the embedded chat page and right click in Chrome or other browsers and select "Inspect Element" from the popup menu. You will then be able to find the name, id, or class of the element. You can then add that name to your style sheet.

For more info on style sheets see, http://www.w3schools.com/css/

Using the style tag

When using the "Box" embed option, JavaScript is used to embed the chatbot, so you cannot pass your own stylesheet, as it is embedded in your own page. You can add your style sheet to your page, or use the style tag to add styles to the page. Some things cannot be customized using style sheets, for these you can use JavaScript to customize the generated HTML after it has been initialized.

For example to remove the max and close buttons from the popup use,

#boxclose {
  display: none;
}
#boxmax {
  display: none;
}

This example will customize the chatbot Box embedding using a style tag and JavaScript,

You can customize most things this way, but if you need further customization, you can just use your own JavaScript to access your bot using the Paphus JavaScript SDK. The "Div" embed option gives you some sample code that you can customize to suite your needs.