examples/03-chatbot-inline.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Defining AIML categories inline\n",
    "\n",
    "Instead of loading an external AIML DB, it is also possible to create a bot from scratch by executing notebook cells containing AIML code. This notebook offers a few examples."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Full AIML\n",
    "\n",
    "The most direct procedure is to add a fully-compliant [AIML](http://www.alicebot.org/TR/2001/WD-aiml/) document in a cell, preceded by the `%aiml` magic. This magic must be present alone in the first cell line, save for comment lines, i.e. lines starting with `#` (which are ignored).\n",
    "\n",
    "The XML preamble is optional; if missing it will be added automatically. Encoding is always UTF-8"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"ctrl\">Loaded 3 new patterns</div></div>"
      ],
      "text/plain": [
       "Loaded 3 new patterns\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%aiml\n",
    "# Receiving a greeting and answering back\n",
    "\n",
    "<?xml version=\"1.0\" encoding=\"utf-8\"?>\n",
    "<aiml version=\"1.0\">\n",
    "  \n",
    "  # The \"good NNN\" greeting allows us to infer the time of the day\n",
    "  <category>\n",
    "    <pattern>GOOD *</pattern>\n",
    "    <template>\n",
    "      <think><set name=\"tod\"><star/></set></think>\n",
    "      <srai>HI</srai>\n",
    "    </template>\n",
    "  </category>\n",
    "\n",
    "  # A Hello greeting is less defining\n",
    "  <category>\n",
    "    <pattern>HELLO</pattern>\n",
    "    <template><srai>HI</srai></template>\n",
    "  </category>\n",
    "\n",
    "  # This is the template creating the greeting response\n",
    "  <category>\n",
    "    <pattern>HI</pattern>\n",
    "    <template>\n",
    "      <random>\n",
    "        <li>Hi there</li>\n",
    "        <li>Hello</li>\n",
    "        <li>\n",
    "           <condition name=\"tod\">\n",
    "             <li value=\"morning\">Good morning</li>\n",
    "             <li value=\"afternoon\">Good afternoon</li>\n",
    "             <li value=\"evening\">Good evening</li>\n",
    "             <li value=\"night\">Good night</li>\n",
    "             <li>Hello</li>\n",
    "           </condition>\n",
    "        </li>\n",
    "      </random>\n",
    "    </template>\n",
    "  </category>\n",
    "\n",
    "</aiml>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There can also be comment lines within the AIML document; they are ignored (of course, given that AIML is XML, we can also add comments as XML comments)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Test it"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"bot\">Hi there</div></div>"
      ],
      "text/plain": [
       "Hi there\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "Good morning"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"bot\">Good morning</div></div>"
      ],
      "text/plain": [
       "Good morning\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "Hello"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can inspect the session predicates, to check the \"*tod*\" (time-of-day) predicate that was (supposedly) assigned"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"info\">Session fields:<br/>  tod = morning</div></div>"
      ],
      "text/plain": [
       "Session fields:\n",
       "  tod = morning\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%show session"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Simplified AIML\n",
    "\n",
    "Given that XML is rather verbose, a slightly simplified syntax is also possible by removing the outer wrapper tags: `<aiml>`, `<category>`, `<pattern>`, `<template>`.\n",
    "\n",
    "This mode is automatically triggered if the first non-comment & non-empty line of an `%aiml` cell does not begin with an XML tag (i.e. an angle bracket element). In this mode:\n",
    "  * categories are separated by blank lines (at least one, any amount of them)\n",
    "  * within a category, the first line is always the pattern\n",
    "  * all the remaining lines are joined together to form the template\n",
    "  * except if the second line starts with `<that>`, in which case this line is considered as a pattern-side THAT and the template is formed by all lines starting from the third. There is no need to close the `<that>` element in the second line\n",
    "  * the template must be proper AIML code, with all the necessary AIML tags, closed as necessary\n",
    "  \n",
    "As an example, the following cell contains *exactly* the same AIML code as the one above in the \"full AIML\" format. In fact, if we execute it the answer will be **loaded 0 new patterns**, since those patterns were already defined above and hence they are already in the bot (if we execute a `%forget` cell before, then they will be loaded new).\n",
    "\n",
    "As an additional bonus, automatic normalization (uppercasing and punctuation removal) is done on patterns and on text fragments of `<srai>` elements, so we can use \"normal\" text there.\n",
    "\n",
    "If you want to include the defined categories within a topic, use the topic name as an additional parameter to the header magic, i.e.\n",
    "<pre>\n",
    "  %aiml &lt;topicname&gt;\n",
    "</pre>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"ctrl\">Loaded 0 new patterns</div></div>"
      ],
      "text/plain": [
       "Loaded 0 new patterns\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%aiml\n",
    "\n",
    "  \n",
    "# The \"good NNN\" greeting allows us to infer the time of the day\n",
    "good *\n",
    "<think><set name=\"tod\"><star/></set></think>\n",
    "<srai>HI</srai>\n",
    "\n",
    "# A Hello greeting is less defining\n",
    "hello\n",
    "<srai>hi</srai>\n",
    "\n",
    "# This is the template creating the greeting response\n",
    "hi\n",
    "<random>\n",
    "   <li>Hi there</li>\n",
    "   <li>Hello</li>\n",
    "   <li>\n",
    "      <condition name=\"tod\">\n",
    "        <li value=\"morning\">Good morning</li>\n",
    "        <li value=\"afternoon\">Good afternoon</li>\n",
    "        <li value=\"evening\">Good evening</li>\n",
    "        <li value=\"night\">Good night</li>\n",
    "        <li>Hello</li>\n",
    "      </condition>\n",
    "   </li>\n",
    "</random>\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "### Test again"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"bot\">Good morning</div></div>"
      ],
      "text/plain": [
       "Good morning\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "good morning"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Updating pattern space\n",
    "\n",
    "Every `%aiml` cell executed adds to the existing categories, so that the current state of the brain is the sum of all executed `%aiml` cells (plus the categories added via `%load` or `%learn` magics). \n",
    "\n",
    "So we can now add new categories:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"ctrl\">Loaded 1 new patterns</div></div>"
      ],
      "text/plain": [
       "Loaded 1 new patterns\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%aiml\n",
    "\n",
    "# Note we use the full form, since substitution patterns will have \"what's\" expanded\n",
    "# We refer this to the HI category defined above\n",
    "what is up\n",
    "<srai>hi</srai>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"bot\">Good morning</div></div>"
      ],
      "text/plain": [
       "Good morning\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "what's up?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can modify an existing category. It will say **loaded 0 new patterns** because the pattern already existed, but the result will be modified"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"ctrl\">Loaded 0 new patterns</div></div>"
      ],
      "text/plain": [
       "Loaded 0 new patterns\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%aiml\n",
    "\n",
    "hello\n",
    "How do you do?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"bot\">How do you do?</div></div>"
      ],
      "text/plain": [
       "How do you do?\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "hello"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However we *cannot* delete an existing pattern (the most we can do is assign an empty output to it). Currently the only way to completely remove it is to execute a `%forget` cell and then re-execute all notebook cells defining AIML (`%aiml`, `%load`, `%learm`).\n",
    "\n",
    "## Saving/loading bots\n",
    "\n",
    "### Saving full bot state\n",
    "\n",
    "The `%save` & `%load` commands can be used to save to disk and load from it the full bot state (optionally we can omit saving/loading part of this state)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Saving session predicates... 1 predicates\n",
      "Saving bot predicates... 1 predicates\n",
      "Saving subbers for person2 ... 9 subs\n",
      "Saving subbers for gender ... 8 subs\n",
      "Saving subbers for normal ... 59 subs\n",
      "Saving subbers for person ... 13 subs\n",
      "Saving brain to myexample.brain... done (0.01 seconds)\n",
      "Writing main bot file: myexample.ini\n",
      "Packing into: myexample.bot\n"
     ]
    }
   ],
   "source": [
    "%save myexample.bot"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The saving process by default creates one `*.bot` file. This is a ZIP file with two files inside:\n",
    "* A `.ini` file that contains session predicates, bot predicates and all substitution strings. Plus a pointer to the brain file.\n",
    "* A `.brain` file that contains the bot categories, in a compiled form\n",
    "\n",
    "There is a variant, indicated by the `rawfiles` option, in which those two files are left unpacked.\n",
    "\n",
    "The saved state can be now loaded back by using the `%load` command"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"ctrl\">Resetting bot brain</div></div>"
      ],
      "text/plain": [
       "Resetting bot brain\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%forget"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Opening: myexample.bot\n",
      "Loading session predicates... 1 predicates\n",
      "Loading bot predicates... 1 predicates\n",
      "Loading subs for person2 ... 9 subs\n",
      "Loading subs for gender ... 8 subs\n",
      "Loading subs for normal ... 59 subs\n",
      "Loading subs for person ... 13 subs\n",
      "Loading brain from /tmp/myexample.brain... done (4 categories in 0.00 seconds)\n"
     ]
    }
   ],
   "source": [
    "%load myexample"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`%save` and `%load` accept additional parameters that make them skip saving/loading part of the data: `noses`, `nobot`, `nosub`, `nobrain`. They can be mixed freely "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"info\">Session fields:<br/>  tod = morning</div></div>"
      ],
      "text/plain": [
       "Session fields:\n",
       "  tod = morning\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%show session "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Saving AIML rules\n",
    "\n",
    "A final option for reusing the AIML cells in other notebooks (or other systems) is to use the `%record` magic.\n",
    "This command has three forms:\n",
    "* `%record on` starts saving. All AIML cells executed afterwards will be kept in a special list\n",
    "* `%record save <name>` saves all cells stored so far as an AIML file (the `.aiml` suffix is added automatically)\n",
    "* `%record off` stops saving AIML cells and cleans up all cells stored in memory\n",
    "\n",
    "Note that _only_ the AIML cells since `%record on` was executed will be saved. Rules loaded via `%learn` or `%load` commands will **not** be included."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"ctrl\">Record activated</div></div>"
      ],
      "text/plain": [
       "Record activated\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%record on"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"ctrl\">Loaded 0 new patterns</div></div>"
      ],
      "text/plain": [
       "Loaded 0 new patterns\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%aiml\n",
    "\n",
    "# Note we use the full form, since substitution patterns will have \"what's\" expanded \n",
    "what is up\n",
    "Howdy"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"ctrl\">Loaded 0 new patterns</div></div>"
      ],
      "text/plain": [
       "Loaded 0 new patterns\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%aiml\n",
    "\n",
    "<category>\n",
    "  <pattern>HI</pattern>\n",
    "  <template>Hello</template>\n",
    "</category>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"ctrl\">Record saved to &quot;aimlexample.aiml&quot; (2 cells)</div></div>"
      ],
      "text/plain": [
       "Record saved to \"aimlexample.aiml\" (2 cells)\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%record save aimlexample "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"ctrl\">Record deactivated</div></div>"
      ],
      "text/plain": [
       "Record deactivated\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%record off"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "AIML files saved can be loaded again with the `%learn` magic. They can also be used in any system that understands AIML 1.0"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"ctrl\">Resetting bot brain</div></div>"
      ],
      "text/plain": [
       "Resetting bot brain\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%forget"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"ctrl\">Learning patterns in &quot;aimlexample.aiml&quot;</div></div>"
      ],
      "text/plain": [
       "Learning patterns in \"aimlexample.aiml\"\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Loading aimlexample.aiml... done (0.00 seconds)\n"
     ]
    },
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"ctrl\">Loaded 2 new patterns</div></div>"
      ],
      "text/plain": [
       "Loaded 2 new patterns\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "%learn aimlexample.aiml"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"krn-bot\"><div class=\"bot\">Hello</div></div>"
      ],
      "text/plain": [
       "Hello\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "Hi"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "This definition of AIML categories done inline in notebook cells can also be done _on top of_ a bot loaded via `%learn` or `%load`. See [04-chatbot-alice-augment](04-chatbot-alice-augment.ipynb) for an example."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "AIML Chatbot",
   "language": "",
   "name": "aimlbot"
  },
  "language_info": {
   "mimetype": "text/xml",
   "name": "Chatbot"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}