From a5486b66f25cfdfca3ed016cce4c1850e6f1cf07 Mon Sep 17 00:00:00 2001 From: Gunther Cox Date: Fri, 13 May 2016 19:54:58 -0400 Subject: [PATCH] Updated examples and documentation. This adds a tutorial on how to use the MongoDB adapter. This also adds information about training a chat bot. --- .travis.yml | 1 - chatterbot/adapters/logic/no_logic.py | 21 ++++++ docs/adapters/index.rst | 9 +++ docs/adapters/input.rst | 1 + docs/adapters/logic.rst | 1 + docs/adapters/output.rst | 1 + docs/adapters/storage.rst | 32 +++++++-- docs/conf.py | 17 ++++- docs/corpus.rst | 14 ---- docs/examples.rst | 18 +++++ docs/index.rst | 10 ++- docs/training.rst | 95 +++++++++++++++++++++++++++ examples/terminal_example.py | 16 ++--- examples/terminal_example2.py | 1 + examples/terminal_mongo_example.py | 14 +--- 15 files changed, 201 insertions(+), 50 deletions(-) create mode 100644 chatterbot/adapters/logic/no_logic.py delete mode 100644 docs/corpus.rst create mode 100644 docs/training.rst diff --git a/.travis.yml b/.travis.yml index 3fcee963f..fb8872cb3 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,7 +3,6 @@ language: python python: - '3.4' - - '3.3' - '2.7' install: diff --git a/chatterbot/adapters/logic/no_logic.py b/chatterbot/adapters/logic/no_logic.py new file mode 100644 index 000000000..616a9b8b3 --- /dev/null +++ b/chatterbot/adapters/logic/no_logic.py @@ -0,0 +1,21 @@ +from chatterbot.adapters.logic import LogicAdapter +from chatterbot.conversation import Statement + + +class NoLogic(LogicAdapter): + + def can_process(self, statement): + """ + Determines if this adapter can respond to the input. + """ + return True + + def process(self, statement): + import random + + # Get all statements that are in response to the closest match + response_list = self.context.storage.filter( + in_response_to__contains=statement.text + ) + + return 1, random.choice(response_list) diff --git a/docs/adapters/index.rst b/docs/adapters/index.rst index 8e68d5132..8f9ddbdea 100644 --- a/docs/adapters/index.rst +++ b/docs/adapters/index.rst @@ -1,3 +1,4 @@ +======== Adapters ======== @@ -41,4 +42,12 @@ Each adapter can be set by passing in the dot-notated import path to the constru ], ) +Third Party Adapters +-------------------- + +`chatterbot-voice`_ - A text to speech (tts) and speech recognition adapter designed to use with ChatterBot. +`chatterbot-weather`_ A ChatterBot logic adapter that returns information about the current weather. + .. _MongoDB: https://docs.mongodb.com/ +.. _chatterbot-voice: https://github.com/gunthercox/chatterbot-voice +.. _chatterbot-weather: https://github.com/gunthercox/chatterbot-weather diff --git a/docs/adapters/input.rst b/docs/adapters/input.rst index f34f00f44..8953929ca 100644 --- a/docs/adapters/input.rst +++ b/docs/adapters/input.rst @@ -1,3 +1,4 @@ +============== Input Adapters ============== diff --git a/docs/adapters/logic.rst b/docs/adapters/logic.rst index 0d468e2fe..5b28bcbc9 100644 --- a/docs/adapters/logic.rst +++ b/docs/adapters/logic.rst @@ -1,3 +1,4 @@ +============== Logic Adapters ============== diff --git a/docs/adapters/output.rst b/docs/adapters/output.rst index ad9cce699..b9f24bdf2 100644 --- a/docs/adapters/output.rst +++ b/docs/adapters/output.rst @@ -1,3 +1,4 @@ +=============== Output Adapters =============== diff --git a/docs/adapters/storage.rst b/docs/adapters/storage.rst index 7ba056269..4e4f2a1b7 100644 --- a/docs/adapters/storage.rst +++ b/docs/adapters/storage.rst @@ -1,3 +1,4 @@ +================ Storage Adapters ================ @@ -14,14 +15,14 @@ The storage adapter that your bot uses can be specified by setting the `storage_ ) Read Only Mode --------------- +============== If you instantiate your chatterbot with the parameter `read_only=True` then the database will not be altered when input is given to the chatterbot. The `read_only` parameter is set to false by default. Json Database Adapter ---------------------- +===================== .. autofunction:: chatterbot.adapters.storage.JsonDatabaseAdapter @@ -32,18 +33,35 @@ passed to the ChatterBot constructor. This storage adapter uses a local file database so this parameter is needed to specify the location of the file. Mongo Database Adapter ----------------------- +====================== .. autofunction:: chatterbot.adapters.storage.MongoDatabaseAdapter "chatterbot.adapters.storage.MongoDatabaseAdapter" -The MongoDB Database adapter requires an additional parameter (`database`) to -be passed to the ChatterBot constructor. This value will be the name of the -database you choose to connect to. +database +-------- + +The MongoDB Database adapter requires an additional parameter, `database`, +to be passed to the ChatterBot constructor. This value will be the name +of the database you choose to connect to. + +.. code-block:: python + + database='chatterbot-database' + +database_uri +------------ + +If you need to connect to a remote instance of MongoDB, you +can set the `database_uri` parameter to the uri of your database. + +.. code-block:: python + + database_uri='mongodb://example.com:8100/' Creating a new storage adapter ------------------------------- +============================== It is fairly easy to write your own storage adapter to connect to just about any database or storage endpoint. To get started, you will need to create a diff --git a/docs/conf.py b/docs/conf.py index 7adbe7d3d..dbaf1bd7a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -9,6 +9,17 @@ import sys import os +# Get the project root dir, which is the parent dir of this +cwd = os.getcwd() +project_root = os.path.dirname(cwd) + +# Insert the project root dir as the first element in the PYTHONPATH. +# This lets us ensure that the source package is imported, and that its +# version is used. +sys.path.insert(0, project_root) + +import chatterbot + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -55,9 +66,9 @@ # built documents. # # The short X.Y version. -version = u'0.4' +version = chatterbot.__version__ # The full version, including alpha/beta/rc tags. -release = u'0.4.0' +release = chatterbot.__version__ # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -109,7 +120,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'alabaster' +#html_theme = 'alabaster' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/corpus.rst b/docs/corpus.rst deleted file mode 100644 index 8d50a9000..000000000 --- a/docs/corpus.rst +++ /dev/null @@ -1,14 +0,0 @@ -Training Corpus -=============== - -This is a :term:`corpus` of data that is included in the chatterbot module. - -.. glossary:: - - corpus - In linguistics, a corpus (plural corpora) or text corpus is a large - and structured set of texts. They are used to do statistical analysis - and hypothesis testing, checking occurrences or validating linguistic - rules within a specific language territory [1]_. - -.. [1] https://en.wikipedia.org/wiki/Text_corpus diff --git a/docs/examples.rst b/docs/examples.rst index e0a836aba..91a53583e 100644 --- a/docs/examples.rst +++ b/docs/examples.rst @@ -22,3 +22,21 @@ output adapters have been specified. .. literalinclude:: ../examples/terminal_example2.py :language: python + +Using MongoDB +------------- + +Before you can use ChatterBot's built in adapter for MongoDB, +you will need to `install MongoDB`_. Make sure MongoDB is +running in your environment before you execute your program. +To tell ChatterBot to use this adapter, you will need to set +the `storage_adapter` parameter. + +.. code-block:: python + + storage_adapter="chatterbot.adapters.storage.MongoDatabaseAdapter" + +.. literalinclude:: ../examples/terminal_mongo_example.py + :language: python + +.. _install MongoDB: https://docs.mongodb.com/manual/installation/ diff --git a/docs/index.rst b/docs/index.rst index 7f09fa34a..a8dea56c0 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -10,10 +10,10 @@ Contents: tutorial examples - chatterbot + training adapters/index + chatterbot conversations - corpus utils About ChatterBot @@ -30,6 +30,11 @@ Simple Example .. literalinclude:: ../examples/basic_example.py :language: python +Report an Issue +=============== + +Please direct all bug reports and feature requests to the project's issue +tracker on `GitHub`_. Indices and tables ================== @@ -38,3 +43,4 @@ Indices and tables * :ref:`modindex` * :ref:`search` +.. _GitHub: https://github.com/gunthercox/ChatterBot diff --git a/docs/training.rst b/docs/training.rst new file mode 100644 index 000000000..894fff2ef --- /dev/null +++ b/docs/training.rst @@ -0,0 +1,95 @@ +======== +Training +======== + +ChatterBot has tools that simplify the process of training a bot instance. +These tools range from simple utility methods that update relations of known +statements, to a corpus of pre-loaded training data that you can use. + +Training via list data +====================== + +For the training, process, you will need to pass in a list of statements where the order of each statement is based on it's placement in a given conversation. + +For example, if you were to run bot of the following training calls, then the resulting chatterbot would respond to both statements of "Hi there!" and "Greetings!" by saying "Hello". + +.. code-block:: python + + chatterbot = ChatBot("Training Example") + + chatterbot.train([ + "Hi there!", + "Hello", + ]) + + chatterbot.train([ + "Greetings!", + "Hello", + ]) + +You can also provide longer lists of training conversations. +This will establish each item in the list as a possible response to it's predecessor in the list. + +.. code-block:: python + + chatterbot.train([ + "How are you?", + "I am good.", + "That is good to hear.", + "Thank you", + "You are welcome.", + ]) + +Training with corpus data +========================= + +ChatterBot comes with a corpus data and utility module that makes it easy to +quickly train your bot to communicate. To do so, simply specify the corpus +data modules you want to use. + +.. code-block:: python + + chatterbot.train( + "chatterbot.corpus.english" + ) + +Specifying corpus scope +----------------------- + +It is also possible to import individual subsets of ChatterBot's at once. +For example, if you only wish to train based on the english greetings and +conversations corpora then you would simply specify them. + +.. code-block:: python + + chatterbot.train( + "chatterbot.corpus.english.greetings", + "chatterbot.corpus.english.conversations" + ) + +The ChatterBot Corpus +===================== + +This is a :term:`corpus` of data that is included in the chatterbot module. + +Corpus language availability +---------------------------- + +Corpus data is user contributed, but it is also not difficult to create one if you are familiar with the language. +This is because each corpus is just a sample of various input statements and their responses for the bot to train itself with. + +To explore what languages and sets of corpora are available, check out the `chatterbot/corpus/data`_ directory in the repository. + +If you are interested in contributing a new language corpus, or adding a module to an existing language, please create a pull request. Contributions are welcomed! + +.. glossary:: + + corpus + In linguistics, a corpus (plural corpora) or text corpus is a large + and structured set of texts. They are used to do statistical analysis + and hypothesis testing, checking occurrences or validating linguistic + rules within a specific language territory [1]_. + +.. [1] https://en.wikipedia.org/wiki/Text_corpus + +.. _chatterbot/corpus/data: https://github.com/gunthercox/ChatterBot/tree/master/chatterbot/corpus diff --git a/examples/terminal_example.py b/examples/terminal_example.py index 3972be59d..79fcf3431 100644 --- a/examples/terminal_example.py +++ b/examples/terminal_example.py @@ -1,10 +1,5 @@ from chatterbot import ChatBot -''' -In this example we use a while loop combined with a try-except statement. -This allows us to have a conversation with the chat bot until we press -ctrl-c or ctrl-d on the keyboard. -''' # Create a new instance of a ChatBot bot = ChatBot("Terminal", @@ -19,16 +14,15 @@ database="../database.db" ) -# Text to prompt the user with initially -user_input = "Type something to begin..." - -print(user_input) +print("Type something to begin...") +# The following loop will execute each time the user enters input while True: try: - # We pass None to this method because it expects a response. - # The TerminalAdapter will handle reading from the user's terminal. + # We pass None to this method because the parameter + # is not used by the TerminalAdapter bot_input = bot.get_response(None) + # Press ctrl-c or ctrl-d on the keyboard to exit except (KeyboardInterrupt, EOFError, SystemExit): break diff --git a/examples/terminal_example2.py b/examples/terminal_example2.py index 0a21306e9..8613439c5 100644 --- a/examples/terminal_example2.py +++ b/examples/terminal_example2.py @@ -18,5 +18,6 @@ bot_input = bot.get_response(None) print(bot_input) + # Press ctrl-c or ctrl-d on the keyboard to exit except (KeyboardInterrupt, EOFError, SystemExit): break diff --git a/examples/terminal_mongo_example.py b/examples/terminal_mongo_example.py index 5be9bac89..6ba5577b6 100644 --- a/examples/terminal_mongo_example.py +++ b/examples/terminal_mongo_example.py @@ -1,7 +1,7 @@ from chatterbot import ChatBot -# Create a new instance of a ChatBot +# Create a new ChatBot instance bot = ChatBot("Terminal", storage_adapter="chatterbot.adapters.storage.MongoDatabaseAdapter", logic_adapters=[ @@ -14,20 +14,10 @@ print("Type something to begin...") -''' -In this example we use a while loop combined with a try-except statement. -This allows us to have a conversation with the chat bot until we press -ctrl-c or ctrl-d on the keyboard. -''' - while True: try: - ''' - The get_response method also uses the io adapter to determine how - the bot's output should be returned. In the case of the TerminalAdapter, - the output is printed to the user's terminal. - ''' bot_input = bot.get_response(None) + # Press ctrl-c or ctrl-d on the keyboard to exit except (KeyboardInterrupt, EOFError, SystemExit): break