Welcome to pyaiml21 documentation!
========================================

pyaiml21 is a Python 3 package used to create and run a chatbot written in the AIML.


Quick start
-----------

In this tutorial, you will learn how to create a run a simple AIML chatbot
using pyaiml21 interpreters. To learn about AIML and how it works, please refer
to the `official AIML 2.1 specification <http://www.aiml.foundation/doc.html>`_.

Installation
^^^^^^^^^^^^

First, install the pyaim21 package.

.. code-block:: bash

    $ pip install -U pyaiml21


Creating Interpreter
^^^^^^^^^^^^^^^^^^^^

The easiest way to start the interpreter is via using a command line script.
`pyaiml21` comes with a simple script to run your chatbots, if you unpacked
the contents of your bot into `alice/` folder (so that the structure
is `alice/aiml/..`, `alice/aimlif/..`, `alice/sets/..` ..), then running
the following will start your bot:

.. code-block:: bash

    $ aiml --bot alice

It is still possible to start your bot directly from python, e.g.

    >>> from pyaiml21 import Bot
    >>> my_bot = Bot()
    >>> my_bot.learn_aiml("path to .aiml file")
    >>> # more loading stuff, see `pyaiml21.utils` for helpers
    >>> my_bot.respond("Hello", "USER_1")
    Hi! How are you doing?

For backwards compatibility, the option to use `Kernel` object is available:

    >>> from pyaiml21 import Kernel
    >>> kernel = Kernel()


Loading the Knowledge into the Interpreter
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The AIML specification states, that the bot's knowledge should be stored in the *.aiml*
files, and it can be loaded by the interpreter. However, the *pyaiml21* does not include
any *.aiml* files - therefore you can not directly run the chatbot, you will have to download
them yourself, for example the standard AIML set from
`ALICE github repo <https://github.com/drwallace/aiml-en-us-foundation-alice>`_:

.. code-block:: bash

    $ git clone https://github.com/drwallace/aiml-en-us-foundation-alice.git aiml-files
    $ aiml --bot aiml-files/program-ab

Now, the interpreter has parsed and stored the bot's knowledge and it is ready to
start chat session.


Running the Chat Conversation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

After the bot is loaded, you can use :py:meth:`Bot.respond` method to chat with the bot:

    >>> my_bot.response("Hello", "my_user_id")
    "Hi."

Alternatively, you can use ``input`` and while loop to run the conversation and accept the user
queries from the command prompt / standard input:

    >>> query = ""
    >>> while query != "QUIT":
    ...     print(my_bot.response(query, "my_user_id"))
    ...     query = input("> ")


Data Storage
^^^^^^^^^^^^

In the basic settings of the ``Bot`` object, the chatbot stores
it's information in the main memory and it is impossible to change this.
However, the ``pyaiml21`` package allows you to store the data into (possibly)
shared database, via classes :py:class:`pyaiml21.graphmaster.SqLiteGraphMaster`
or :py:class:`pyaiml21.graphmaster.MongoGraphMaster`.


Extending the Interpreter with new Tags
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It is possible to define custom tags for the interpreter, see
extensions.


.. toctree::
    :hidden:

    Home page <self>
    Extensions <extensions>
    API reference <_autosummary/pyaiml21>
