{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# The AIML Chatbot kernel\n",
    "\n",
    "The _AIML Chatbot kernel_ wraps the [pyAIML](https://github.com/creatorrr/pyAIML) Python library to create a conversational bot within a notebook. The bot behaviour is defined by loading [AIML](https://en.wikipedia.org/wiki/AIML) categories. A \"category\" in AIML is akin to a rule, and defines a _pattern_-_template_ pair\n",
    "\n",
    "Input cells are messages for the bot, which get interpreted and the bot output is the result of the cell execution. Additionally, a few magics for both control (cells starting with  apercent sign) are available; these are not passed to the bot as user messages, but executed to change the bot behaviour in some way."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## First steps\n",
    "\n",
    "On an empty bot there is nothing to do (the bot does not produce any output, since it does not have rules to work with). So when creating an (empty) AIML notebook, any input cell will just return the general help message"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"help\">AIML Chatbot<br/><br/>You can start by loading a database of rules:<br/><br/>%learn alice | standard | &lt;dbdirectory&gt; | &lt;xml-file&gt;<br/><br/>For &quot;alice&quot; &amp; &quot;standard&quot; databases, the rules will<br/>automatically be activated. For a custom database,<br/>you will need to launch the &quot;load &lt;name&gt;&quot; command<br/>defined in it.<br/><br/>Once loaded, you can start chatting with the bot. <br/><br/>New databases can be added by additional &quot;%learn&quot; commands.<br/><br/>Use &quot;%lsmagic&quot; to see all the available magics.<br/></div></div>"
      ],
      "text/plain": [
       "AIML Chatbot\n",
       "\n",
       "You can start by loading a database of rules:\n",
       "\n",
       "%learn alice | standard | <dbdirectory> | <xml-file>\n",
       "\n",
       "For \"alice\" & \"standard\" databases, the rules will\n",
       "automatically be activated. For a custom database,\n",
       "you will need to launch the \"load <name>\" command\n",
       "defined in it.\n",
       "\n",
       "Once loaded, you can start chatting with the bot. \n",
       "\n",
       "New databases can be added by additional \"%learn\" commands.\n",
       "\n",
       "Use \"%lsmagic\" to see all the available magics.\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "Hello"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Getting help\n",
    "\n",
    "This same help message can also be obtained at any time by using the `%help` magic command\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"help\">AIML Chatbot<br/><br/>You can start by loading a database of rules:<br/><br/>%learn alice | standard | &lt;dbdirectory&gt; | &lt;xml-file&gt;<br/><br/>For &quot;alice&quot; &amp; &quot;standard&quot; databases, the rules will<br/>automatically be activated. For a custom database,<br/>you will need to launch the &quot;load &lt;name&gt;&quot; command<br/>defined in it.<br/><br/>Once loaded, you can start chatting with the bot. <br/><br/>New databases can be added by additional &quot;%learn&quot; commands.<br/><br/>Use &quot;%lsmagic&quot; to see all the available magics.<br/></div></div>"
      ],
      "text/plain": [
       "AIML Chatbot\n",
       "\n",
       "You can start by loading a database of rules:\n",
       "\n",
       "%learn alice | standard | <dbdirectory> | <xml-file>\n",
       "\n",
       "For \"alice\" & \"standard\" databases, the rules will\n",
       "automatically be activated. For a custom database,\n",
       "you will need to launch the \"load <name>\" command\n",
       "defined in it.\n",
       "\n",
       "Once loaded, you can start chatting with the bot. \n",
       "\n",
       "New databases can be added by additional \"%learn\" commands.\n",
       "\n",
       "Use \"%lsmagic\" to see all the available magics.\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%help"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And the `%lsmagics` command lists all available magics with their meaning"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false,
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"help\">Available magics:<br/>%aiml  %forget  %help  %learn  %load  %lsmagics  %save  %setp  %show bot  %show session  %show size<br/><br/>%aiml  : add additional AIML rules<br/>%forget  : reset the bot<br/>%help  : show general help<br/>%learn alice | standard | &lt;dbdirectory&gt; | &lt;xml-file&gt; : learn an AIML db<br/>%load &lt;name&gt; : load bot state from a file<br/>%lsmagics  : list all magics<br/>%save &lt;name&gt; : save bot state to a file<br/>%setp [bot] &lt;name&gt; &lt;value&gt; : set a predicate, or a bot predicate<br/>%show bot  : show the defined bot predicates<br/>%show session  : show the predicates defined in the session<br/>%show size  : show the number of categories loaded in the bot</div></div>"
      ],
      "text/plain": [
       "Available magics:\n",
       "%aiml  %forget  %help  %learn  %load  %lsmagics  %save  %setp  %show bot  %show session  %show size\n",
       "\n",
       "%aiml  : add additional AIML rules\n",
       "%forget  : reset the bot\n",
       "%help  : show general help\n",
       "%learn alice | standard | <dbdirectory> | <xml-file> : learn an AIML db\n",
       "%load <name> : load bot state from a file\n",
       "%lsmagics  : list all magics\n",
       "%save <name> : save bot state to a file\n",
       "%setp [bot] <name> <value> : set a predicate, or a bot predicate\n",
       "%show bot  : show the defined bot predicates\n",
       "%show session  : show the predicates defined in the session\n",
       "%show size  : show the number of categories loaded in the bot"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%lsmagics"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Learning\n",
    "\n",
    "The most important of these magics is `%learn`, which loads an AIML database into the bot.\n",
    "\n",
    "There are three versions for that:\n",
    "1. Learning a predefined database: use `%learn alice` or `%learn standard`. AIML categories defined in the DB will be automatically loaded.\n",
    "2. Learning a custom database: use `%learn <directory>` where _directory_ is a directory containing a set of AIML files to learn, plus an `startup.xml` file referencing them. A `load <name>` command is needed afterwards to load the learned rules into the bot\n",
    "3. Learning a single AIML file: use `%learn <file.xml>` or `%learn <file.aiml>`\n",
    "\n",
    "See [02-chatbot-alice.ipynb](02-chatbot-alice.ipynb) for an example of the first type.\n",
    "\n",
    "An additional way of creating rules is by writing them directly in notebook cells, using the `%aiml` magic. Such rules are immediately added to the bot when the cell is executed. You can:\n",
    "* Start from scratch (inserting rules to an empty bot). See [03-chatbot-inline.ipynb](03-chatbot-new.ipynb) for an example\n",
    "* Add rules to a bot already filled with categories. See [04-chatbot-alice-augment.ipynb](04-chatbot-alice-augment.ipynb) for an example"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div style=\"border-top: 1px gray solid; font-family: Cursive, sans-serif;\">Version: 1.0 (2016-07-19)<br/>\n",
    "Author: Paulo Villegas</div>"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "AIML Chatbot",
   "language": "",
   "name": "aimlbot"
  },
  "language_info": {
   "mimetype": "text/xml",
   "name": "Chatbot"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}