notebooks/Basics.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# SymbolicAI: Basics"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Get Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import warnings\n",
    "warnings.filterwarnings('ignore')\n",
    "os.chdir('../') # set the working directory to the root of the project\n",
    "import numpy as np\n",
    "from symai import *\n",
    "from symai.components import *\n",
    "from IPython.display import display"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using Symbols"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "Hi there!"
      ],
      "text/plain": [
       "<class 'symai.symbol.Symbol'>(value=Hi there!)"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sym = Symbol('Hi there!')\n",
    "sym"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Adding two symbols together."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "Hi there! How are you?"
      ],
      "text/plain": [
       "<class 'symai.symbol.Symbol'>(value=Hi there! How are you?)"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res = sym + 'how are you?'\n",
    "res"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If one of the objects is a symbol then the other object is converted to a symbol."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A `Symbol` instance takes in any type of object and preserves its original value type until it is evaluated and sent to the neuro-symbolic engine:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "numpy.ndarray"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sym = Symbol(np.array([5, 2, 42, 1]))\n",
    "sym.value_type"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "One can also easily retriev the object by accessing the `value` attribute:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 5,  2, 42,  1])"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sym.value"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can add multiple values together and their operation will be contextualized evaluated. Here we use the shift operator to integrate a new value into the existing symbol:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "['5', '2', '42', '1', '2']"
      ],
      "text/plain": [
       "<class 'symai.symbol.Symbol'>(value=['5', '2', '42', '1', '2'])"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res = sym << 2\n",
    "res"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We could do the same manipulation with the `+` operator, however, the prompts designed for each individual operator may contain different information, therefore, therefore may not evaluated to similar outcomes. In the following example it is clear that the `+` operator is not to shift the value into the array:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "[\"5\", \"2\", \"42\", \"3\"]"
      ],
      "text/plain": [
       "<class 'symai.symbol.Symbol'>(value=[\"5\", \"2\", \"42\", \"3\"])"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "res = sym + 2\n",
    "res"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, if we use the `+` operator to evaluate arithmetic operations, the results are quite different:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "x + 1"
      ],
      "text/plain": [
       "<class 'symai.symbol.Symbol'>(value=x + 1)"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x = Symbol('x')\n",
    "x += 1\n",
    "x"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For simple expressions and operations we can use LLMs to interpret the mathematical expression and evaluate the result:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "x + 1 = 0\n",
       "\n",
       "To solve for x:\n",
       "\n",
       "x + 1 - 1 = 0 - 1\n",
       "\n",
       "x = -1"
      ],
      "text/plain": [
       "<class symai.symbol.Symbol at 0x16f4b4610>(value=x + 1 = 0\n",
       "\n",
       "To solve for x:\n",
       "\n",
       "x + 1 - 1 = 0 - 1\n",
       "\n",
       "x = -1)"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "x = Symbol('x + 1 = 0')\n",
    "x.interpret()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Evaluating Expressions"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Similar to `word2vec` we intend to preform contextualized operations on different symbols. \n",
    "\n",
    "Word2vec is a machine learning algorithm that is used to generate dense vector representations of words. It works by training a shallow neural network to predict a word given its neighbors in a text corpus. The resulting vectors are then used in a wide range of natural language processing applications, such as sentiment analysis, text classification, and clustering.\n",
    "\n",
    "Below we can see an example how one can perform operations on the word embedding vectors (colored boxes)."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"../assets/images/img3.png\" width=\"470px\">"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, we can also perform operations on the natural language space itself. For example, we can add two the word expressions similar to how we added them in the word2vec space:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "Queen"
      ],
      "text/plain": [
       "<class symai.symbol.Symbol at 0x16e47da10>(value=Queen)"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "Symbol('King - Man + Women').interpret()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As we can see, if the `expression` method is empty the default implementation of `Symbol` uses only the `value` stored within the current symbol. \n",
    "\n",
    "Now let's try to evaluate a more complex expression:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"alert alert-success\" role=\"alert\">\n",
       "  x^2 + 2x + 1\n",
       "</div>"
      ],
      "text/plain": [
       "<class 'symai.symbol.Symbol'>(value=x^2 + 2x + 1)"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "expression = Interface('wolframalpha')\n",
    "res = expression('x^2 + 2x + 1')\n",
    "res\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Well, not exactly simplified the way we intended it. \n",
    "\n",
    "This is because using LLMs for expression evaluations is still very limited, therefore, to leverage the full power of symbolic programming we can use the `expression` method to evaluate an expression via `WolframAlpha`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div class=\"alert alert-success\" role=\"alert\">\n",
       "  x = -1\n",
       "</div>"
      ],
      "text/plain": [
       "<class 'symai.symbol.Expression'>(value=x = -1)"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sym = Symbol()\n",
    "expression = Interface('wolframalpha')\n",
    "res = expression('x^2 + 2x + 1')\n",
    "res"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There we go! The `command` method configures the `symbolic` engine to evaluate expressions via `WolframAlpha`. One can see that this evaluates the expression and returns the correct result."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Showing other basic operations"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Sometimes we want to simply concatenate to symbols together without any other neural operation. This is easily done with the `|` operation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "Welcome to our tutorial.Hello world!"
      ],
      "text/plain": [
       "<class symai.symbol.Symbol at 0x16ffcf890>(value=Welcome to our tutorial.Hello world!)"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# define a second string\n",
    "sym = Symbol(\"Welcome to our tutorial.\")\n",
    "test2 = 'Hello world!'\n",
    "# concatenate strings\n",
    "res = sym | test2\n",
    "res"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can of course define full sentences as Symbols and perform several operations on them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "sym = Symbol(\"\"\"Images and videos of domestic cats make up some of the most viewed content on the World Wide Web, particularly image macros in the form of lolcats. ThoughtCatalog has described cats as the \"unofficial mascot of the Internet\".[1]\n",
    "The subject has attracted the attention of various scholars and critics, who have analyzed why this form of low art has reached iconic status. Although it may be considered frivolous, cat-related Internet content contributes to how people interact with media and culture.[2] Some argue that there is a depth and complexity to this seemingly simple content, with a suggestion that the positive psychological effects that pets have on their owners also hold true for cat images viewed online.[3]\n",
    "Research has suggested that viewing online cat media is related to positive emotions, and that it even may work as a form of digital therapy or stress relief for some users. Some elements of research also shows that feelings of guilt when postponing tasks can be reduced by viewing cat content.[4]\n",
    "\"\"\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here we translate the existing Symbol to German:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "Bilder und Videos von Hauskatzen gehören zu den am meisten gesehenen Inhalten im World Wide Web, insbesondere Bildmakros in Form von Lolcats. ThoughtCatalog hat Katzen als das \"inoffizielle Maskottchen des Internets\" beschrieben.[1]\n",
       "Das Thema hat die Aufmerksamkeit verschiedener Gelehrter und Kritiker auf sich gezogen, die analysiert haben, warum diese Form der niedrigen Kunst einen ikonischen Status erreicht hat. Obwohl es als belanglos angesehen werden kann, trägt internetbezogener Katzeninhalt dazu bei, wie Menschen mit Medien und Kultur interagieren.[2] Einige argumentieren, dass es eine Tiefe und Komplexität in diesem scheinbar einfachen Inhalt gibt, mit dem Vorschlag, dass die positiven psychologischen Effekte, die Haustiere auf ihre Besitzer haben, auch für online betrachtete Katzenbilder zutreffen.[3]\n",
       "Die Forschung hat vorgeschlagen, dass das Anschauen von Katzenmedien im Internet mit positiven Emotionen verbunden ist und dass es sogar als eine Form der digitalen Therapie oder Stressentlastung für einige Nutzer dienen kann. Einige Forschungsergebnisse zeigen auch, dass Gefühle der Schuld, wenn Aufgaben aufgeschoben werden, durch das Betrachten von Katzeninhalten reduziert werden können.[4]"
      ],
      "text/plain": [
       "<class symai.symbol.Symbol at 0x10dc856d0>(value=Bilder und Videos von Hauskatzen gehören zu den am meisten gesehenen Inhalten im World Wide Web, insbesondere Bildmakros in Form von Lolcats. ThoughtCatalog hat Katzen als das \"inoffizielle Maskottchen des Internets\" beschrieben.[1]\n",
       "Das Thema hat die Aufmerksamkeit verschiedener Gelehrter und Kritiker auf sich gezogen, die analysiert haben, warum diese Form der niedrigen Kunst einen ikonischen Status erreicht hat. Obwohl es als belanglos angesehen werden kann, trägt internetbezogener Katzeninhalt dazu bei, wie Menschen mit Medien und Kultur interagieren.[2] Einige argumentieren, dass es eine Tiefe und Komplexität in diesem scheinbar einfachen Inhalt gibt, mit dem Vorschlag, dass die positiven psychologischen Effekte, die Haustiere auf ihre Besitzer haben, auch für online betrachtete Katzenbilder zutreffen.[3]\n",
       "Die Forschung hat vorgeschlagen, dass das Anschauen von Katzenmedien im Internet mit positiven Emotionen verbunden ist und dass es sogar als eine Form der digitalen Therapie oder Stressentlastung für einige Nutzer dienen kann. Einige Forschungsergebnisse zeigen auch, dass Gefühle der Schuld, wenn Aufgaben aufgeschoben werden, durch das Betrachten von Katzeninhalten reduziert werden können.[4])"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sym.translate('German')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And now, we try to classify how the mood of the above sentences:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "neutral"
      ],
      "text/plain": [
       "<class symai.symbol.Symbol at 0x16ffc5c50>(value=neutral)"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sym.choice(['angry', 'neutral', 'hate-speech', 'happy', 'unk'], default='unk')"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Documentation Generator Example"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "from examples.docs import Docs, CppDocs\n",
    "docs = Docs()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\"\"\"Decorates a function to be executed with pre_processors, post_processors, and constraints.\n",
      "\n",
      "This decorator is used to apply preprocessing, postprocessing, and constraint validation to the output of a function. It provides a way to hook into the execution of the function, allowing for additional processing or validation steps to be applied before and after the function runs.\n",
      "\n",
      "Args:\n",
      "    default (str, optional): The default value to be returned if the validation of constraints fails. It can also be used to provide a default response if the function cannot be executed. Defaults to None.\n",
      "    constraints (List[Callable], optional): A list of callables that are used to validate the output of the function. An empty list means no constraints will be applied. Defaults to an empty list ( [] ).\n",
      "    pre_processors (List[PreProcessor], optional): A list of preprocessing objects that are applied to the arguments of the function before the function is called. Preprocessors can modify or augment the function arguments. Defaults to an empty list ( [] ).\n",
      "    post_processors (List[PostProcessor], optional): A list of postprocessing objects that are applied to the output of the function after the function has completed execution. Postprocessors can modify or filter the function's output. Defaults to an empty list ( [] ).\n",
      "    **decorator_kwargs: Additional keyword arguments that are passed to the execute_func function.\n",
      "\n",
      "Returns:\n",
      "    Callable: A wrapper function that, when called, executes the wrapped function with preprocessing, postprocessing, and constraint checks applied.\n",
      "\n",
      "Example Usage:\n",
      "    @execute(default='Error', constraints=[check_positive], post_processors=[format_result])\n",
      "    def calculate_area(length, width):\n",
      "        return length * width\n",
      "\n",
      "    class MathOperations:\n",
      "        @execute(pre_processors=[convert_to_int])\n",
      "        def multiply(self, a, b):\n",
      "            return a * b\n",
      "\"\"\"\n"
     ]
    }
   ],
   "source": [
    "doc = docs(\"\"\"def execute(default: str = None,\n",
    "            constraints: List[Callable] = [],\n",
    "            pre_processors: List[PreProcessor] = [],\n",
    "            post_processors: List[PostProcessor] = [],\n",
    "            **decorator_kwargs):\n",
    "    def decorator(func):\n",
    "        @functools.wraps(func)\n",
    "        def wrapper(instance, *args, **kwargs):\n",
    "            return execute_func(instance,\n",
    "                                func=func,\n",
    "                                constraints=constraints,\n",
    "                                default=default,\n",
    "                                pre_processors=pre_processors,\n",
    "                                post_processors=post_processors,\n",
    "                                **decorator_kwargs)\n",
    "        return wrapper\n",
    "    return decorator\n",
    "\"\"\")\n",
    "print(doc)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Markdown"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can actually on the fly also generate markdown documentation for our notebooks. This is done by using the built in `query` method. The `query` method is used to query the `symbolic` engine for information about the current symbol. The `query` method can therefore be used to ask the engine to generate documentation in a specific format."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "```markdown\n",
      "# News Class Documentation\n",
      "\n",
      "The `News` class is a utility that helps developers inject uniform preprocessing, postprocessing, and constraint validation behaviors into their methods. It's implemented as a Python decorator, which can be easily applied to any function.\n",
      "\n",
      "## Overview\n",
      "\n",
      "The `News` class decorator streamlines the process of enhancing functions with additional processing layers. It allows functions to be wrapped such that:\n",
      "\n",
      "- Input arguments can be pre-processed before the function runs.\n",
      "- Output can be post-processed after the function completes.\n",
      "- The output can be validated against constraints to ensure it adheres to certain requirements.\n",
      "\n",
      "By using this decorator, developers can maintain cleaner codebases by separating concerns and avoiding repetitive code.\n",
      "\n",
      "## Features\n",
      "\n",
      "### Pre-Processing\n",
      "\n",
      "Pre-processors are used to transform or prepare the input data before the core logic of the function is executed. They can be used, for example, to validate input types, convert formats, or enrich data.\n",
      "\n",
      "### Post-Processing\n",
      "\n",
      "Post-processors are applied after the function has produced an output. They can be used for formatting the output, performing additional calculations on the results, or logging.\n",
      "\n",
      "### Constraints\n",
      "\n",
      "Constraints serve as checks or validations applied to the function's output. They can raise exceptions or alter the output if it does not meet pre-determined criteria.\n",
      "\n",
      "## Syntax and Arguments\n",
      "\n",
      "When decorating a function with the `News` class, you can provide several optional arguments:\n",
      "\n",
      "- `default`: The default value to return if constraints validation fails, or if the function cannot be executed.\n",
      "- `constraints`: A list of callables that receive the function's output and return a boolean value indicating whether the output meets the constraint.\n",
      "- `pre_processors`: Objects that are called with the function's arguments before the function itself is called.\n",
      "- `post_processors`: Objects that are called with the function's output after it has executed.\n",
      "- `**decorator_kwargs`: Any additional keyword arguments that should be passed to the `execute_func` function.\n",
      "\n",
      "The decorator returns a callable that represents the wrapped function.\n",
      "\n",
      "## Example Usage\n",
      "\n",
      "```python\n",
      "@execute(default='Error', constraints=[check_positive], post_processors=[format_result])\n",
      "def calculate_area(length, width):\n",
      "    return length * width\n",
      "\n",
      "class MathOperations:\n",
      "    @execute(pre_processors=[convert_to_int])\n",
      "    def multiply(self, a, b):\n",
      "        return a * b\n",
      "```\n",
      "\n",
      "In the example above, the `calculate_area` function is decorated to return the string `'Error'` by default if any of the constraints fail. It also applies a post-processor that formats the final result.\n",
      "\n",
      "For the `MathOperations` class, the `multiply` method is decorated with a pre-processor that ensures the inputs are converted to integers before the multiplication occurs.\n",
      "\n",
      "## Conclusion\n",
      "\n",
      "The `News` class decorator offers a versatile and powerful way to enhance functions with additional processing and validation. It promotes cleaner, more modular code and helps ensure that functions operate within defined parameters.\n",
      "```\n"
     ]
    }
   ],
   "source": [
    "res = doc.query(context=\"Write a very detailed Markdown documentation the News class.\")\n",
    "print(res)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "continualrl",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.13"
  },
  "orig_nbformat": 4,
  "vscode": {
   "interpreter": {
    "hash": "7f6e76e437f50039fcb1dabeb26a40fb80edddddd3448a5d408bb52a844f2e97"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}