Metadata-Version: 2.0
Name: django-bot
Version: 0.2.1
Summary: A lightweight django framework for bots
Home-page: https://github.com/shaileshahuja/django-bot
Author: shaileshahuja
Author-email: shailesh.ahuja03@gmail.com
License: GNU General Public License v3.0
Platform: UNKNOWN
Classifier: Environment :: Other Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 1.8
Classifier: Framework :: Django :: 1.9
Classifier: Framework :: Django :: 1.10
Classifier: Framework :: Django :: 1.11
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Communications
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Requires-Dist: celery (>=4.0)
Requires-Dist: slackclient (==1.0.5)
Requires-Dist: Django (>=1.8)
Requires-Dist: apiai (==1.2.3)

django-bot
==========
A django library that makes it easier to develop bots with a common interface for messaging platforms (eg. Slack, FB messenger) and natural langauge parsers (eg. api.ai).

|build-status| |pypi-version|

.. |build-status| image:: https://travis-ci.org/shaileshahuja/django-bot.svg?branch=develop
    :target: https://travis-ci.org/shaileshahuja/django-bot
.. |pypi-version| image:: https://badge.fury.io/py/django-bot.svg
    :target: https://pypi.python.org/pypi/django-bot

Overview
========
BETA version: Currently django-bot only supports Slack and api.ai. Future plans include supporting more messaging platforms (Facebook Messenger, Telegram, Kik, Google assistant, Cortana, Skype, Alexa), and more natural langauge parsers (AWS Lex, wit.ai).

This library helps to maintain authenticated users and groups in the database and allows you to respond to any messages as well as initiate conversations with any of those.

Requirements and Installation
*****************************

django-bot for Python works with Python 2.7, 3.4, 3.5, 3.6 and django >= 1.8, and requires ``PyPI`` to install dependencies. The message parsing and delivery is done in the background with the help of celery. It also requires slackclient and apiai python libraries for communication with the external services. 

.. code-block:: bash

    pip install django-bot

Of course, if you prefer doing things the hard way, by pulling down the source code directly into your project:

.. code-block:: bash

    git clone https://github.com/shaileshahuja/django-bot.git

Getting started
===============

User model
**********

First, we need to define the model and attributes of every user communicating with the bot.

``models.py``

.. code-block:: python

   from converse.models import AbstractUser

   class MyUser(AbstractUser):
       credits = models.FloatField(default=0.0)

This user model is automatically created for each authenticated user. For example, if a slack team is authenticated, ``MyUser`` object will be created for each user in the team. Make sure to define defaults for all fields.

Default properties available
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``org``: The organization this user belongs to.

``messenger``: Returns an implementation of ``converse.messengers.MessengerBase`` object. This messenger object can be used to send messages to the user. It exposes a consistent interface for different platforms.

``email``: The email address of the user, if available

``name``: The name of the user, if available

Organization model
******************

You must also define a model that will be instantiated for each organization that authenticates your bot. Again, remember to define defaults for any custom fields.

``models.py``

.. code-block:: python

   from converse.models import AbstractOrganization

   class Organization(AbstractOrganization):
       pass

Default properties available
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``users``: A queryset of user objects that belong to this organization

``messenger``: Returns an implementation of ``converse.messengers.MessengerBase`` object. This messenger object can be used to send messages to a group common to all members of the organization. In Slack, this will send a message to #general.

``name``: The name of the organization, if available

Actions
*******

Then, we need to define actions that can be triggered when the user sends a message. The parser will detect the intent of the user, extract parameters and the pass action be to taken back to the calling program.

``actions.py``

.. code-block:: python

   @Executor(action="account.balance")
   class CreditsQuery(ActionBase):
       @property
       def execute(self):
           self.user.messenger.send("Please wait while we retrieve your details...")
           # this method is called in the background, so it is safe to make time consuming API requests
           self.user.messenger.send_text("You have ${:.2f} left in your account".format(self.user.credits),
                                         quick_replies=[QuickReply("buy credits"), QuickReply("redeem gift")]

We also need to tell django where the action classes / methods are written.

``settings.py``

.. code-block:: python

   ACTION_MODULES = ['<list of modules where actions can be found>'] # ['x.actions']

Integrating with Slack
**********************
Create a Slack app via the developer portal, and add the following credentials to your django application.

``settings.py``

.. code-block:: python

   SLACK_CLIENT_ID = '<your slack client id>'
   SLACK_CLIENT_SECRET = '<your slack client secret>'
   SLACK_VERIFICATION_TOKEN = '<your slack verification token>'

Next, add this to your django URLs.

``urls.py``

.. code-block:: python

   urlpatterns = [
       ...,
       url(r'^converse/', include('converse.urls', namespace='converse'))
   ]

Next, start your server (behind https, try ngrok if in development environment), and add these URLs to your Slack app.

OAuth & Permissions -> Redirect URLs: <https base url>/converse/slack/oauth

Event Subscriptions -> Request URL: <https base url>/converse/slack/webhook

Interactive Messages -> Request URL: <https base url>/converse/slack/action

Integrating with api.ai
***********************

``settings.py``

.. code-block:: python

   # right now this is the only supported NLP framework for chatbots
   TEXT_PARSER = 'converse.parsers.APIAIParser'
   API_AI_CLIENT_TOKEN = '<your api.ai client token>'

To match the actions in api.ai to the actions you write, make sure the name in ``@Executor(action="<name>")`` is the same as the one the 'actions' field in your intent. You can access the slot filling params using ``self.params`` and the conversation context using ``self.contexts``.

Sending messages as the bot
***************************

``converse.messengers.MessengerBase``: This class provides the API for all messenger classes

``converse.messengers.SlackMessenger``: Implements this API, and so will all future implementations of other messengers.

Methods:
^^^^^^^^
``send``: To send a plaintext message.

``send_text``: To send a message with quick replies.

``send_image``: To send an image with quick replies.

Quick replies are instant prompts for the user to click and respond. In Slack, they are sent as actions.

Example:

.. code-block:: python

   user.messenger.send_text("Are you sure?", quick_replies=[QuickReply("yes"), QuickReply(text="Cancel", value="No")])

Clicking on 'yes' will send a request back to your server with query ``QuickReply.value``.

Implementing your own parser
****************************
Parsers are responsible for understanding the intent of the user from the text query, which receives the text to be parsed and the session id. The session id can be used to respond to queries with context.
``converse.parsers.APIAIParser`` is one such parser that connects to api.ai. You may implement your own by extending ``converse.parsers.ParserBase`` and implementing the ``parse`` method. This method receives the text query and the session id and should return a ``ParserResponse`` object.


