opencog_tutorials/GHOST/ghost-tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# GHOST (General Holistic Organism Scripting Tool)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Goals and Vision"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The design intention of Ghost (the “General Holistic Organism Scripting Tool”) is to allow human authors to script behaviors for artificial characters.   Significant flexibility is desired, e.g. to support\n",
    "* Purely textual chatbots, animated characters, or physical robots\n",
    "* Characters controlled precisely by human-authored rules; or characters with a great deal of autonomy, where human-authored rules serve mainly to tweak parameters and indicate propensities\n",
    "\n",
    "Ghost is envisioned as having both a textual and a graphical user interface.   The textual interface is aimed to have roughly the same level of complexity as ChatScript (on which it is heavily based), meaning that it should be usable by non-programmers who are able to deal with a fairly intricate formal syntax. \n",
    "\n",
    "The GUI is not yet designed at time of writing, but is intended to make Ghost authoring feasible for a broader class of content authors, and to make it easier and more rapid for everyone.   Some brief notes  regarding the envisioned GUI are given at the end of this document."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# High Level Design"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ghost is implemented as a DSL (Domain-Specific Language) within the Scheme shell associated with the OpenCog engine.    Ghost syntax closely resembles (and in most respects is identical to) ChatScript; but the Ghost interpreter is written in Scheme and runs in the OpenCog Scheme shell.   Ghost rules are interpreted into Atoms living in OpenCog’s Atomspace semantic knowledge store, and are executed within OpenCog using the OpenCog Pattern Matcher and Action Selector and associated mechanisms.\n",
    "\n",
    "A Ghost rule has two required parts, a pattern and an action; and an optional third part, a goal or set of goals.   The general semantic is: When the pattern is observed, if the goal is being pursued by the agent, then consider taking the action. If no goal is specified, a generic goal such as “interact with others” is implicitly assumed. A Ghost “script” consists of a set of rules, which may be grouped into files called “topics.”   A topic may have some annotations associated with it, which apply to all the rules in the topic (unless overridden by annotations specific to certain rules.)\n",
    "\n",
    "Both patterns and actions may optionally reference Scheme functions.  (Support for functions written in other languages may be added in a later version.)   An envisioned usage pattern is: Writing Ghost rules and, in coordination with the Ghost rule authoring process, adding new Scheme functions to help the rules do their things.\n",
    "\n",
    "An example simple Ghost rule is:\n",
    "```\n",
    "#goal: (novelty=1)\n",
    "s: ( Hi there ^no_people_around ) Who said that? ^look_around\n",
    "```\n",
    "This rule is somewhat trivial as it lacks variables.   But it shows the basic format; here we have:\n",
    " * Pattern = someone says “Hi there” to the agent, and there are no people around (i.e. the Scheme function no_people_around outputs True)\n",
    " * Action = the agent says “Who said that?” and then invokes the Scheme function look_around\n",
    " * Goal = novelty … so the agent should use this rule when the “novelty” goal is important to it\n",
    " \n",
    "Behind the scenes, the Ghost interpreter uses OpenCog’s Pattern Matcher to match the patterns of its rules to content in OpenCog’s Atomspace knowledge store.  The specifics of this matching are simple now, but are highly customizable and can be made more sophisticated in future versions.\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Installation\n",
    "**Opencog**\n",
    "\n",
    "Ghost is a module inside [Opencog](https://github.com/opencog/opencog). So install Opencog first.\n",
    "\n",
    "**Relex**\n",
    "\n",
    "[RelEx](https://github.com/opencog/relex) is a dependency parser for the English language. It extracts dependency relations from Link Grammar, and adds some shallow semantic analysis. The primary use of RelEx is as a language input front-end to the OpenCog artificial general intelligence system. Ghost uses relex."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Hello in Ghost\n",
    "Open guile shell and import the necessary modules:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "(use-modules (opencog)\n",
    "             (opencog nlp)\n",
    "             (opencog nlp relex2logic)\n",
    "             (opencog openpsi)\n",
    "             (opencog ghost)\n",
    "             (opencog ghost procedures))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next start the [relex](https://github.com/opencog/relex) server:\n",
    "\n",
    "**Without Docker:**\n",
    "```\n",
    "$ cd /path/to/relex/project/directory/\n",
    "$ ./opencog-server.sh\n",
    "```\n",
    "\n",
    "**With Docker:**   \n",
    "When using docker, inside the started guile shell set the host for the container running relex. This way\n",
    "the relex server will be looked for at the specified IP address instead of the default 127.0.0.1."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "172.21.0.2"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(set-relex-server-host)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Parse your rules using `ghost-parse` for single rule or `ghost-parse-file` for files containing rules:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: (hello) hello there! ^keep\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Test the parsed rules using `test-ghost`.\n",
    "When the input doesn't match any pattern:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "()"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(test-ghost \"hi\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the input matches the pattern of the previously parsed rule:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "((WordNode \"hello\")\n",
       " (WordNode \"there\")\n",
       " (WordNode \"!\")\n",
       ")"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(test-ghost \"hello\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The result sentence is returned as a list of WordNodes containing the words. To extract the sentence do the following."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(hello there !)"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"hello\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Design Overview\n",
    "\n",
    "* A GHOST rule is essentially an OpenPsi rule (aka psi-rule), which is an ImplicationLink that can be expressed as\n",
    "```\n",
    "context AND action -> goal\n",
    "```\n",
    "\n",
    "* That is if a pattern or context is matched action is then executed and the goal is said to be achieved.\n",
    "\n",
    "* A goal also has an ugre to express the level of need to achieve that goal.\n",
    "\n",
    "* Ghost rules are organized into topics. Before parsing any rules a topic can be set and all subsequent rules created will belong to that topic until another topic is set or the end of the file is reached. If no topic is set a default topic is used.\n",
    "\n",
    "* When a GHOST rule is being created, it will firstly be passed to a parser for syntax checking and preliminary interpretation. Any rules that is not syntactically correct or with unsupported features will be rejected at this stage.\n",
    "\n",
    "* The parser will then pass the intermediate interpretations (aka terms) to a translator that converts them into OpenCog atoms to be stored in the AtomSpace.\n",
    "\n",
    "* Ghost action selector is responsible for selecting a rule that is applicable to a given context. When a textual input is received, rules that satisfy the given context will first be selected as candidates. A full context evaluation will then be done for each of the candidates. Action selector will pick one of them based on their satisfiability and their truth value. Satisfiability of rules are compared based on the following criteria:\n",
    "   \n",
    "   * Wether a pattern is matched or not\n",
    "   * The strength of the rule's goal\n",
    "   * The urge of the goal\n",
    "   * Importance of the rule (rules just selected are considered less important)\n",
    "   * Whether a rule is in the current topic (priority is given)\n",
    "\n",
    "For example consider two rules with the same pattern but different goal strength:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"#goal: (goal1=0.5) u: (hi) hi there ^keep\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"#goal: (goal1=0.7) u: (hi) hello there ^keep\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "((WordNode \"hello\")\n",
       " (WordNode \"there\")\n",
       ")"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(test-ghost \"hi\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The action selector picks the rule with the higher goal strength.\n",
    "\n",
    "* Once a rule is selected it will not be considered again for subsequent inputs unless it is specified otherwise via\n",
    "`^keep` function or `keep` topic feature."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Syntax\n",
    "\n",
    "The syntax of GHOST rules is modeled heavily on [ChatScript](https://github.com/bwilcox-1234/ChatScript/blob/master/WIKI/ChatScript-Basic-User-Manual.md#rules). However, GHOST uses several ChatScript features for different purposes than they are normally used in ChatScript; and also contains some additional features."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Topic\n",
    "Rules are bundled into topics. All rules after a topic definition will belong to that rule. The topic declares its name, its keywords, and then its rules. It ends with the end of the file or a new topic declaration.\n",
    "\n",
    "```\n",
    "topic: ~NAME features [list of keywords]\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"topic: ~GREETING [hi hello]\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now all rules created will be under GREETING topic. If `keep` topic feature is used all rules in the topic can be considered repeatedly by the action selector."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Label\n",
    "A rule can optionally be given a label by which it can be referred by other rules or from the guile shell:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: lbl (ghost) Ghost is a behavior scripting tool ^keep\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(ImplicationLink (stv 0.9 0.9)\n",
       "   (AndLink\n",
       "      (TrueLink\n",
       "         (ExecutionOutputLink\n",
       "            (GroundedSchemaNode \"scm: ghost-execute-action\")\n",
       "            (ListLink\n",
       "               (WordNode \"Ghost\")\n",
       "               (WordNode \"is\")\n",
       "               (WordNode \"a\")\n",
       "               (WordNode \"behavior\")\n",
       "               (WordNode \"scripting\")\n",
       "               (WordNode \"tool\")\n",
       "            )\n",
       "         )\n",
       "         (PutLink\n",
       "            (StateLink\n",
       "               (AnchorNode \"GHOST Last Executed\")\n",
       "               (VariableNode \"$x\")\n",
       "            )\n",
       "            (ConceptNode \"lbl\")\n",
       "         )\n",
       "         (ExecutionOutputLink\n",
       "            (GroundedSchemaNode \"scm: ghost-record-executed-rule\")\n",
       "            (ListLink\n",
       "               (ConceptNode \"lbl\")\n",
       "            )\n",
       "         )\n",
       "         (PutLink\n",
       "            (StateLink\n",
       "               (AnchorNode \"GHOST Current Topic\")\n",
       "               (VariableNode \"$x\")\n",
       "            )\n",
       "            (ConceptNode \"GHOST GREETING\")\n",
       "         )\n",
       "      )\n",
       "      (SatisfactionLink\n",
       "         (VariableList\n",
       "            (TypedVariableLink\n",
       "               (GlobNode \"wildcard-$119530376034-jHRxwrgZhjlsoORho57az14a\")\n",
       "               (TypeSetLink\n",
       "                  (TypeNode \"WordNode\")\n",
       "                  (IntervalLink\n",
       "                     (NumberNode \"0.000000\")\n",
       "                     (NumberNode \"-1.000000\")\n",
       "                  )\n",
       "               )\n",
       "            )\n",
       "            (TypedVariableLink\n",
       "               (GlobNode \"wildcard-$119530445859-mYPvzgLfwErKgBzG3DRGyrOm\")\n",
       "               (TypeSetLink\n",
       "                  (TypeNode \"WordNode\")\n",
       "                  (IntervalLink\n",
       "                     (NumberNode \"0.000000\")\n",
       "                     (NumberNode \"-1.000000\")\n",
       "                  )\n",
       "               )\n",
       "            )\n",
       "            (TypedVariableLink\n",
       "               (VariableNode \"ghost-$119530538816-f9r2Yscqv65yB4QLDqx7IPXt\")\n",
       "               (TypeNode \"WordNode\")\n",
       "            )\n",
       "            (TypedVariableLink\n",
       "               (VariableNode \"ghost-$119530560821-ETJT131zBHgiqtyS7dU3S0dE\")\n",
       "               (TypeNode \"WordInstanceNode\")\n",
       "            )\n",
       "            (TypedVariableLink\n",
       "               (GlobNode \"wildcard-$119530627160-fH6qqVSSsTivmj2xhfA9dJZ7\")\n",
       "               (TypeSetLink\n",
       "                  (TypeNode \"WordNode\")\n",
       "                  (IntervalLink\n",
       "                     (NumberNode \"0.000000\")\n",
       "                     (NumberNode \"-1.000000\")\n",
       "                  )\n",
       "               )\n",
       "            )\n",
       "            (TypedVariableLink\n",
       "               (GlobNode \"wildcard-$119530648086-V3XF5DZEptavdPD1DDECeZXf\")\n",
       "               (TypeSetLink\n",
       "                  (TypeNode \"WordNode\")\n",
       "                  (IntervalLink\n",
       "                     (NumberNode \"0.000000\")\n",
       "                     (NumberNode \"-1.000000\")\n",
       "                  )\n",
       "               )\n",
       "            )\n",
       "            (TypedVariableLink\n",
       "               (VariableNode \"$S\")\n",
       "               (TypeNode \"SentenceNode\")\n",
       "            )\n",
       "            (TypedVariableLink\n",
       "               (VariableNode \"$P\")\n",
       "               (TypeNode \"ParseNode\")\n",
       "            )\n",
       "         )\n",
       "         (AndLink\n",
       "            (ReferenceLink\n",
       "               (VariableNode \"ghost-$119530560821-ETJT131zBHgiqtyS7dU3S0dE\")\n",
       "               (VariableNode \"ghost-$119530538816-f9r2Yscqv65yB4QLDqx7IPXt\")\n",
       "            )\n",
       "            (ParseLink\n",
       "               (VariableNode \"$P\")\n",
       "               (VariableNode \"$S\")\n",
       "            )\n",
       "            (EvaluationLink\n",
       "               (GroundedPredicateNode \"scm: ghost-lemma?\")\n",
       "               (ListLink\n",
       "                  (VariableNode \"ghost-$119530538816-f9r2Yscqv65yB4QLDqx7IPXt\")\n",
       "                  (WordNode \"ghost\")\n",
       "               )\n",
       "            )\n",
       "            (WordInstanceLink\n",
       "               (VariableNode \"ghost-$119530560821-ETJT131zBHgiqtyS7dU3S0dE\")\n",
       "               (VariableNode \"$P\")\n",
       "            )\n",
       "            (EvaluationLink\n",
       "               (PredicateNode \"GHOST Lemma Sequence\")\n",
       "               (ListLink\n",
       "                  (VariableNode \"$S\")\n",
       "                  (ListLink\n",
       "                     (GlobNode \"wildcard-$119530445859-mYPvzgLfwErKgBzG3DRGyrOm\")\n",
       "                     (WordNode \"ghost\")\n",
       "                     (GlobNode \"wildcard-$119530648086-V3XF5DZEptavdPD1DDECeZXf\")\n",
       "                  )\n",
       "               )\n",
       "            )\n",
       "            (EvaluationLink\n",
       "               (PredicateNode \"GHOST Word Sequence\")\n",
       "               (ListLink\n",
       "                  (VariableNode \"$S\")\n",
       "                  (ListLink\n",
       "                     (GlobNode \"wildcard-$119530376034-jHRxwrgZhjlsoORho57az14a\")\n",
       "                     (VariableNode \"ghost-$119530538816-f9r2Yscqv65yB4QLDqx7IPXt\")\n",
       "                     (GlobNode \"wildcard-$119530627160-fH6qqVSSsTivmj2xhfA9dJZ7\")\n",
       "                  )\n",
       "               )\n",
       "            )\n",
       "            (StateLink\n",
       "               (AnchorNode \"GHOST Currently Processing\")\n",
       "               (VariableNode \"$S\")\n",
       "            )\n",
       "         )\n",
       "      )\n",
       "   )\n",
       "   (ConceptNode \"GHOST Default Goal\")\n",
       ")\n"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(ghost-get-rule \"lbl\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Goal\n",
    "In a ghost rule the satisfiability of a context followed by execution of the action implies achievement of the given goal. Goal has value (0-1) which indicates the strength of the implication link in the rule. The higher the goal value the more likely that the execution of the action achieves that goal given that the context is satisfied.\n",
    "\n",
    "```\n",
    "context AND action ==> goal\n",
    "```\n",
    "\n",
    "There are two ways of creating goals,\n",
    "\n",
    "**1. Top level goal(s)**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"goal: (please_user=0.8)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this case, all the rules created after it will be having the same goal and the same weight, until another top level goal or the end of file is reached. For example the following rule uses the above top level goal."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: lbl1 (hello) Hello sweet wonderful human\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`ghost-rule-tv` returns the truth value of the implication link as `stv mean confidence`. The mean value is the strength of the goal."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(stv 0.800000 0.900000)"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(ghost-rule-tv \"lbl1\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "It is also possible to create a list of rules that are ordered."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"ordered-goal: (please_user=0.8)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The rules being created under ordered-goals will have a different weight, based on the order of creation. The relationship between the order and the weight forms a geometric sequence with a factor of 0.5.\n",
    "\n",
    "For example, if there are five rules under the above please_user=0.8 goal, the first rule will have a weight of 0.4, the second one will have 0.2, the third one will have 0.1, and so on. The sum of the weights will get closer to the weight of the top level goal (0.8) if more rules are created under it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**2. Rule level goal(s)**\n",
    "In this case, the goals will only be linked to the rule created immediately after it. Top level goals will also be linked to the rule if there are any. A top level goal will be overwritten by a rule level goal if the same goal is defined. Any number of rule level goals can be specified inside the goal declaration parenthesis."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"#goal: (novelty=0.67 please_user=0.4) u: (what be you name) I forgot\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I forgot)"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"what is your name\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Urge\n",
    "A goal can have an urge to express the level of urgency to achive that goal. Tweaking the urge value of a goal affects the chances of corresponding rules to be selected by the action selector. If the urge of a goal is increased corresponding rules will be more likely to be selected. \n",
    "\n",
    "The urge of a goal is 1 (maximum) by default. The default urge can be changed, and it should be done before creating the goal, for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"urge: (tease_user=1 creativity=0.5)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The urge value of the goal can be changed via OpenPsi function `psi-increase-urge GOAL VALUE` and `psi-decrease-urge GOAL VALUE`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Lemma\n",
    "Lemma is a base word that represents all forms of a word that have the same meaning. In English, for example, ***run, runs, ran*** and ***running*** are forms of the same word. **run** is the lemma. In chatscript parlance this is the canonical form. \n",
    "\n",
    "Ghost assists you in generalizing your patterns. It simultaneously matches both the original word and a canonical form of it if your pattern word is in the canonical form. And it checks both lowercase and uppercase forms of your words. For nouns, the canonical form is the singular. So if your pattern is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: (dog) I have a cat ^keep\") "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "this will respond equally to I like dogs and I have a dog."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I have a cat)"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"I like dogs\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I have a cat)"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"I have a dog\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Whereas the pattern\n",
    "\n",
    "```\n",
    "u: (dogs) I have a cat\n",
    "```\n",
    "will only respond to ***I like dogs*** but not to ***I have a dog***."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For verbs, the canonical form is the infinitive tense. If your pattern is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: (what be *1) I don't know ^keep\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will respond equally to ***What is it?*** and ***What are you?*** and ***What am I?.***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I don't know)"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"What is it?\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I don't know)"
      ]
     },
     "execution_count": 25,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"What are you\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I don't know)"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"What am I\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I don't know)"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"What am I and what are you\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* Possessive suffixes ' and 's transform to the word 's.\n",
    "* Adjectives and adverbs revert to their base form.\n",
    "* Determiners a an the some these those that become a.\n",
    "* Text numbers like two thousand and twenty one transcribe into digit format.\n",
    "* Floating point numbers migrate to integers if they match value exactly, while currency values become floating       point.\n",
    "* Personal pronouns like me my myself mine move to the subject form I, while whom, whomever whoever whose shift to   who and anyone somebody anybody become someone and whatever becomes what, whenever becomes when, whichever         becomes which."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Phrase\n",
    "When you want Ghost to treat multiple-word phrases as a single entity put the words inside double quotes. You should always put multiple-word proper names in double quotes, particularly ones with embedded punctuation. You want Ghost to know that the entire phrase is considered a single entity. So\n",
    "\n",
    "```\n",
    "u: ( \"Dr. Watson\" )\n",
    "u: ( \"The Beatles\" )\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: ( \\\" dr. watson \\\" ) How may I help You?\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(How may I help You ?)"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"dr. watson\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Choice\n",
    "You can match alternate words in the same position by placing those choices in brackets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"?: (you [swim ride fish ]) I do ^keep\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I do)"
      ]
     },
     "execution_count": 31,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"do you swim?\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I do)"
      ]
     },
     "execution_count": 32,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"do you fish?\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that elements of a choice can be sequences of words either as double-quoted phrases or as paren sequences"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"?: (you [eat ingest \\\"binge and purge\\\" (feed my face ) ] meat) I love meat\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I love meat)"
      ]
     },
     "execution_count": 34,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"do you feed my face meat\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Concept\n",
    "Choices are handy for synonyms, but you have to repeat them over and over in different rules. At such point being able to declare a list of choices in one place and use them everywhere else becomes convenient. This is the concept set. It is hugely important in writing patterns that match meaning.\n",
    "\n",
    "Unlike choices, a concept cannot use paren notation to hold a sequence of words, though it can use quoted expressions.\n",
    "\n",
    "A concept is a top-level declaration consisting of a name starting with ~ and consisting of only alpha-numeric characters and underscores. A concept has a list of words it defines. You can use the set name in any pattern or topic keyword list in place of a word."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 35,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"concept: ~eat [eat ingest \\\"binge and purge\\\"]\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once a concept is defined you can use it in your patterns."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 36,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"s: (I ~eat meat) Do you really? I am a vegan.\") "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Do you really ? I am a vegan .)"
      ]
     },
     "execution_count": 37,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"I ingest meat\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "See [this](https://github.com/bwilcox-1234/ChatScript/blob/master/WIKI/ChatScript-Basic-User-Manual.md#concepts) for more info."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Optional\n",
    "Sometimes you can expect a word might or might not be supplied. Your pattern can reflect this, swallowed it when present. `{}` is just like choice `[]`, except the match is optional. It is allowed to fail."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: (define {word concept} hate) Sorry. I don't know it. ^keep \")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Sorry . I don't know it .)"
      ]
     },
     "execution_count": 39,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"define word hate\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Sorry . I don't know it .)"
      ]
     },
     "execution_count": 40,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"define concept hate\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can also use quoted pharases and parenthesis notation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: ( define { \\\"the word\\\" (the meaning of) } love ) Sorry. I don’t know it. ^keep\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Sorry . I don’t know it .)"
      ]
     },
     "execution_count": 42,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"define the word love\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Sorry . I don’t know it .)"
      ]
     },
     "execution_count": 43,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"define the meaning of love\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Indefinite Wildcard\n",
    "The wildcard * means 0 or more words in sequence. It can be used to widen a pattern:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: (when * you * home) I go home tomorrow ^keep\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This pattern responds to ***When will you go home*** and ***When Roger is with you, will there be anyone at home?***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I go home tomorrow)"
      ]
     },
     "execution_count": 45,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"When will you go home\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I go home tomorrow)"
      ]
     },
     "execution_count": 46,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"When Roger is with you, will there be anyone at home?\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I go home tomorrow)"
      ]
     },
     "execution_count": 47,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"When you home?\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Precise Wildcard\n",
    "As you may notice, indefinite wildcards can allow all sorts of mischief to creep into a match. An overprotective way to manage this is using wildcards that tell you exactly how many words can be swallowed up. The * followed by a number names how many words it absorbs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: (when *1 you *1 to school) I went to school yesterday ^keep\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This matches ***When did you go school*** but won’t accept wide variances like ***When Roger is with you*** nor will it accept ***when you went school*** which hasn’t room for the first ****1***."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I went to school yesterday)"
      ]
     },
     "execution_count": 49,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"When did you go to school?\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "()"
      ]
     },
     "execution_count": 50,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"When you go to school\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Range-restricted Wildcard\n",
    "\n",
    "The usual way to manage the excesses of the previous wildcards is to use a range restricted wildcard. This is an * followed by a ~ and a number, like *~3. It means from 0 up through that number, or approximately that number.\n",
    "\n",
    "A common choice is *~2. This leaves room for some filler words (like a determiner and an adjective or perhaps some kind of adverb), without requiring them or letting the sentence stray.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: (you *~2 go *~2 gym) I often go to that gym. ^keep\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This responds equally to ***You can go to gym*** and ***you should not go to your gym***."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I often go to that gym .)"
      ]
     },
     "execution_count": 52,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"You can go to gym\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I often go to that gym .)"
      ]
     },
     "execution_count": 53,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"You should not go to gym\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Match Variable\n",
    "When you use wildcards and sets in a pattern, you can ask the system to memorize briefly the word it matches. Just place an underscore in front of what you want memorized.\n",
    "\n",
    "The purpose of memorizing is to be able to use the value on output. The results of memorization are stored on match variables named _0, _1, etc, depending upon how many underscores you use in the pattern."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"concept: ~meat [ham chicken beef]\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: ( do you eat _~meat ) No, I hate _0. ^keep\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(No , I hate ham .)"
      ]
     },
     "execution_count": 56,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"do you eat ham\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the input is do you eat ham the output would be No, I hate ham. Of course, the value of _0 is only guaranteed for the execution of this rule. Match variables may be clobbered when you execute another rule. Or they may last for a while.\n",
    "\n",
    "At most it will last for the duration of the current volley (several sentences maybe) after which it should be presumed trashed. Whenever you start a volley, you should presume match variables all hold unknown junk."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: ( do you eat _[ ham eggs bacon] ) I eat '_0.\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 58,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I eat eggs .)"
      ]
     },
     "execution_count": 58,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"do you eat eggs\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the system memorizes your underscore match, it stores both the original word, its canonical form, and the position of the text. On output, by default you get the canonical form. If you want the original form, you must precede your reference with an apostrophe. In the above rule, for example, if `'_0` were changed to `_0` the output would be `I eat egg`; the canonical form of `eggs` would be used. \n",
    "\n",
    "For more than one `_` use `_0` and `_1` and so on."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 59,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: ( do you like _* or _* ) I don’t like '_0 so I guess that means I prefer '_1.\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 60,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I don’t like tea so I guess that means I prefer coffee .)"
      ]
     },
     "execution_count": 60,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"do you like tea or coffee\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you memorize an optional area, `{test me}`, then you get either the word that matched or the match variable is set to null if it fails to match. A null variable prints nothing on output.\n",
    "\n",
    "If you use match variables, they are allocated in the order of the pattern. E.g.,\n",
    "```\n",
    "s: ( _~fruit [_~animal _bear] _~like )\n",
    "```\n",
    "In the above, _0 is a fruit and _2 is a like, and the _~animal or _bear is _1.\n",
    "\n",
    "If you had NOT put _in front of bear, you are at risk that the ~like match may be _1 or _2, depending on what happened inside `[]`. That's your headache if you use nested memorization.\n",
    "\n",
    "See [here](https://github.com/bwilcox-1234/ChatScript/blob/master/WIKI/ChatScript-Basic-User-Manual.md#_-match-variables) for more."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## User Variable\n",
    "\n",
    "If you need memory that lasts beyond the current input, one source of this is user variables. A variable is named with a starting dollar sign or two and then an alphabetic letter and then the rest must be alpha, digit, underscore, or hyphen. You initialize it using a C-style assignment in the output.\n",
    "\n",
    "The = assignment operator MUST be separated from the variable and the value by at least one space, otherwise the system has no way to tell you don't want it to simply output some bizarre word.\n",
    "\n",
    "Unlike match variables, user variables hold a single value only.\n",
    "\n",
    "See [here](https://github.com/bwilcox-1234/ChatScript/blob/master/WIKI/ChatScript-Basic-User-Manual.md#user_variables) for more."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 61,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: ( I eat _*1 ) $food = '_0 I eat oysters.\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 62,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I eat oysters .)"
      ]
     },
     "execution_count": 62,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"I eat bread\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Once user variables are set you can later use them in the output. Note that `$food` is also inside the pattern which checks if `$food` is set first. Otherwise the rule won't trigger."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 63,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: (what do I eat $food) You eat $food ^keep\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 64,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(You eat bread)"
      ]
     },
     "execution_count": 64,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"what do I eat\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Sentence Boundary\n",
    "Sometimes, to get a proper meaning in the pattern, you need to actually know where an input begins or ends. For example:\n",
    "\n",
    "```\n",
    "u: (what is an elephant) An elephant is a pachyderm. \n",
    "```\n",
    "\n",
    "matches ***Tell me what is an elephant*** and ***what is an elephant*** and ***what is an elephant doing in the room***. \n",
    "\n",
    "That last one is inappropriately matched.\n",
    "\n",
    "The > matches the end of the sentence. This makes it possible to correctly manage the above sentences as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 65,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: (what is an elephant > ) An elephant is a pachyderm. ^keep \")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 66,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(An elephant is a pachyderm .)"
      ]
     },
     "execution_count": 66,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"Tell me what is an elephant\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 67,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I don't know)"
      ]
     },
     "execution_count": 67,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"what is an elephant doing in the room\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The < doesn’t really match the start of the sentence so much as it sets the current position of matching to the start of the sentence. Thus"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 68,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: ( roses < I like ) I like roses too. ^keep\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "matches ***I like roses*** because it finds roses anywhere in the sentence, then the < resets the match position to the sentence start, and then it finds ***I like*** at the beginning. Of course this will not match ***You know I like roses*** because I is not at the start of the sentence."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 69,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I like roses too .)"
      ]
     },
     "execution_count": 69,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"I like roses\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 70,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "()"
      ]
     },
     "execution_count": 70,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"You know I like roses\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Negation\n",
    "\n",
    "The absence of words is represented using ! and means it must not be found anywhere after the current match location. When placed at the start of the pattern, it means not anywhere in the sentence at all."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 71,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: ( ![ not never rarely ] I * eat meat ) You eat meat. ^keep\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 72,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "()"
      ]
     },
     "execution_count": 72,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"I never eat meat\" ))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 73,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(You eat meat .)"
      ]
     },
     "execution_count": 73,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"I eat meat\" ))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Unordered Matching\n",
    "\n",
    "Often times you are interested in matching several keywords, but you explicitly want any order of them. For example the sentence ***I love birds*** is a lot like ***Birds are what I love*** but subject and object move around. One somewhat tedious way to match in any order is:\n",
    "```\n",
    "u: ( I < * love < * birds ) I love birds too.\n",
    "```\n",
    "\n",
    "This works by going back to the beginning of the sentence and allowing any number of words to match a wildcard until the next keyword is found. It’s ugly. The cleaner way is to use the unordered markers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 74,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: ( << I birds love >> ) I love birds too. ^keep\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 75,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I love birds too .)"
      ]
     },
     "execution_count": 75,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"I love birds\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 76,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I love birds too .)"
      ]
     },
     "execution_count": 76,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"Birds are what I love\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Since the words can be matched in any order, this resets the scanning mechanism back the original starting condition, which is always < * meaning you can match the next the next item anywhere in the sentence.\n",
    "\n",
    "Position is freely reset to the start following the << >> sequence so if you had the pattern:\n",
    "\n",
    "```\n",
    "u: ( I * like << really >> photos)\n",
    "```\n",
    "and input ***photos I really like*** then it would match because it found ***I * like*** then found anywhere ***really*** and then reset the position freely back to start and found ***photos*** somewhere in the sentence."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Rejoinder\n",
    "\n",
    "Rejoinders are attempts to predict a user’s immediate response to something the chatbot says. They cannot be triggered except on input immediately after the rule they follow has issued output. Rejoinder hierarchy can be set using letters `a-q`\n",
    "\n",
    "```\n",
    "u: (you have a cake) yes do you want some?\n",
    "    a: (yes) here you go\"\n",
    "    a: (no) your loss\n",
    "\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Randomized Output\n",
    "\n",
    "You can select among a range of choices by using output choices. Each choice is encased in [ ], and a contiguous set of them form a zone that the system will pick randomly among. Whenever bracketed items are discontiguous, you get a new random zone.\n",
    "\n",
    "```\n",
    "?: (hey) [hello.][hi][hey] Are you going to [dance][swim][eat] anytime soon?\n",
    "```\n",
    "\n",
    "The above has two random zones, separated by fixed text. So it might output\n",
    "hello. Are you going to dance anytime soon?\n",
    "\n",
    "or\n",
    "\n",
    "hey Are you going to eat anytime soon?."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 77,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: (hey) [hello.][hi][hey] Are you going to [dance][swim][eat] anytime soon? ^keep\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 78,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(hello . Are you going to eat anytime soon ?)"
      ]
     },
     "execution_count": 78,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"hey?\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 79,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(hey Are you going to dance anytime soon ?)"
      ]
     },
     "execution_count": 79,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"hey?\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 80,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(hey Are you going to swim anytime soon ?)"
      ]
     },
     "execution_count": 80,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"hey?\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 81,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(hey Are you going to eat anytime soon ?)"
      ]
     },
     "execution_count": 81,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"hey?\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Function\n",
    "Ghost supports scheme functions inside context and action parts. By making use of functions, Ghost is used beyond coding simple verbal chat rules. \n",
    "\n",
    "* A function is first defined in the public interface via `define-public`\n",
    "* A function can then be used inside context and/or action part by putting `^` followed by the name of the function.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Functions Inside Action part\n",
    "Functions inside Action part can be used in two ways:\n",
    " * To output text via return values\n",
    " * To take non-verbal actions\n",
    "\n",
    "For example consider the following scheme function that returns a list of `Word` nodes wrapped in a `Listlink`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 82,
   "metadata": {},
   "outputs": [],
   "source": [
    "(define-public (findkiller)\n",
    "  ; ... the process of finding the killer ...\n",
    "  ; The answer should be a list of nodes wrapped in a ListLink\n",
    "  (List (Word \"Bob\") (Word \"and\") (Word \"Alice\")))\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the function is used in the action part of a rule the returned list of words are substituted in the output."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 83,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: ( who killed _* ) I think ^findkiller killed '_0\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If the input is ***who killed the dinosaurs***, the above rule will be triggered, `findkiller` will be called, and finally the output will be ***I think Bob and Alice killed the dinosaurs***."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 84,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I think Bob and Alice killed the dinosaurs)"
      ]
     },
     "execution_count": 84,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"Who killed the dinosaurs\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For non-verbal actions the function can make the robot take a certain action (For example smile):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 88,
   "metadata": {},
   "outputs": [],
   "source": [
    "(define-public (smile)\n",
    "               (display \"I am smiling\")\n",
    "               (List (Word \"\")))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this instance the function displays a text but in a real application the function can be made to control motors responsible for smiling."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 93,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: (give me a smile) ^smile\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 92,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "()"
      ]
     },
     "execution_count": 92,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"give me a smile\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "When the above rule triggers the text ***I am smiling*** is displayed in console (not shown here). Note that the function has to return empty word still."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Functions Inside Context Part\n",
    "When inside context part the scheme function has to return either `stv 1 1` or `stv 0 1` representing `true` or `false` respectively. A rule will only trigger if the received input matches the text part of the context and all functions inside the context part return `stv 1 1` aka `true`.\n",
    "\n",
    "Consider the following scheme function that returns `true` or `false` randomly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 94,
   "metadata": {},
   "outputs": [],
   "source": [
    "(define-public (random-stv)\n",
    "               (if (= (random 2) 1)\n",
    "                   (stv 1 1)\n",
    "                   (stv 0 1)\n",
    "                )\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 103,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: (check output ^random-stv) There is output ^keep\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above rule triggers when `random-stv` returns only `stv 1 1`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 104,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(There is output)"
      ]
     },
     "execution_count": 104,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"check output\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 105,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(There is output)"
      ]
     },
     "execution_count": 105,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"check output\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 107,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "()"
      ]
     },
     "execution_count": 107,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"check output\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 108,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "()"
      ]
     },
     "execution_count": 108,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"check output\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 109,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(There is output)"
      ]
     },
     "execution_count": 109,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"check output\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A function can also take arguments. The argument supplied to the scheme function is in the form of a `Word` node. For example consider the following function which checks wether the robot is happy or not based on a given threshold. The happiness level is represented as a random number that is compared against the treshold to determine if the robot is happy enough."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 111,
   "metadata": {},
   "outputs": [],
   "source": [
    "(define-public (is-happy argWord)\n",
    "               (define thresh (string->number (cog-name argWord)))\n",
    "               (if (>= (/ (random 10) 10) thresh)\n",
    "                   (stv 1 1)\n",
    "                   (stv 0 1)\n",
    "                )\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 126,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: (are you happy ^is-happy(0.7) ) Yes I am happy ^keep\" )"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above rule outputs ***Yes I am happy*** 30% of the time."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 128,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "()"
      ]
     },
     "execution_count": 128,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"are you happy\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 129,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(Yes I am happy)"
      ]
     },
     "execution_count": 129,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"are you happy\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 130,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "()"
      ]
     },
     "execution_count": 130,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"are you happy\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 131,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "()"
      ]
     },
     "execution_count": 131,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"are you happy\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Special Functions\n",
    "* `^keep` function inside the action part makes a single rule to be considered by the action selector repeatedly.\n",
    "* `^reuse`, to reuse the action of another rule, e.g.\n",
    "  * `^reuse(some_label)` will reuse the action of another rule with a label named \"some_label\". It's                      recommended to use a unique label for each of the rules in the rulebase, topic.label is not supported.\n",
    "  * Once triggered, the rule being reused will also be considered as triggered, so it will not be triggered            again unless you `^keep` it.\n",
    "  * Note, currently reusing a rule with local variables in the action of the rule is not supported, but user            variables are fine."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 134,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: WHAT (what are you) I am a bot. ^keep\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 135,
   "metadata": {},
   "outputs": [],
   "source": [
    "(ghost-parse \"u: (tell me about yourself) ^reuse(WHAT) ^keep\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 138,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I am a bot .)"
      ]
     },
     "execution_count": 138,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"what are you\"))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 139,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(I am a bot .  )"
      ]
     },
     "execution_count": 139,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "(map cog-name (test-ghost \"tell me about yourself\"))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, the second rule uses the action part of the first rule via `reuse`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Notes Toward a Future Ghost GUI\n",
    "\n",
    "It is desired that Ghost should have a GUI as well as a textual syntax.   Among other feature, the GUI should\n",
    "\n",
    "* Allow graphical, point-and-click based creation of Ghost rules.  A rule created graphically can be optionally       viewed and edited in textual form.\n",
    "* Allow visualization of the results of enaction of one or more Ghost rules, in a visualizer customized for the       type of character being scripted.  For instance, if Ghost is being used to script a Hanson robot, then the GUI     may allow visualization fo the outcome of a Ghost rule or rule-set on a 3D avatar emulating the robot.\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Guile",
   "language": "scheme",
   "name": "guile-kernel"
  },
  "language_info": {
   "codemirror_mode": "scheme",
   "file_extension": ".scm",
   "mimetype": "application/x-scheme",
   "name": "guile",
   "pygments_lexer": "scheme",
   "version": "2.0.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}