ChatterBot Training Process

ChatterBot includes tools that help simplify the process of training a chat bot instance. ChatterBot’s training process involves loading example dialog into the chat bot’s database. This either creates or builds upon the graph data structure that represents the sets of known statements and responses. When a chat bot trainer is provided with a data set, it creates the necessary entries in the chat bot’s knowledge graph so that the statement inputs and responses are correctly represented.

Several training classes come built-in with ChatterBot. These utilities range from allowing you to update the chat bot’s database knowledge graph based on a list of statements representing a conversation, to tools that allow you to train your bot based on a corpus of pre-loaded training data.

You can also create your own training class. This is recommended if you wish to train your bot with data you have stored in a format that is not already supported by one of the pre-built classes listed below.

Setting the training class

ChatterBot comes with training classes built in, or you can create your own if needed. To use a training class you must import it and pass it to the set_trainer() method before calling train().

import logging
import os
import sys
from .conversation import Statement, Response
from . import utils

class Trainer(object):
    Base class for all other trainer classes.

    def __init__(self, storage, **kwargs):
        self.chatbot = kwargs.get('chatbot') = storage
        self.logger = logging.getLogger(__name__)
        self.show_training_progress = kwargs.get('show_training_progress', True)

    def get_preprocessed_statement(self, input_statement):
        Preprocess the input statement.

        # The chatbot is optional to prevent backwards-incompatible changes
        if not self.chatbot:
            return input_statement

        for preprocessor in self.chatbot.preprocessors:
            input_statement = preprocessor(self, input_statement)

        return input_statement

    def train(self, *args, **kwargs):
        This method must be overridden by a child class.
        raise self.TrainerInitializationException()

    def get_or_create(self, statement_text):
        Return a statement if it exists.
        Create and return the statement if it does not exist.
        temp_statement = self.get_preprocessed_statement(

        statement =

        if not statement:
            statement = Statement(temp_statement.text)

        return statement

    class TrainerInitializationException(Exception):
        Exception raised when a base class has not overridden
        the required methods on the Trainer base class.

        def __init__(self, value=None):
            default = (
                'A training class must be specified before calling train(). ' +
            self.value = value or default

        def __str__(self):
            return repr(self.value)

    def _generate_export_data(self):
        result = []
        for statement in
            for response in statement.in_response_to:
                result.append([response.text, statement.text])

        return result

    def export_for_training(self, file_path='./export.json'):
        Create a file from the database that can be used to
        train other chat bots.
        import json
        export = {'conversations': self._generate_export_data()}
        with open(file_path, 'w+') as jsonfile:
            json.dump(export, jsonfile, ensure_ascii=False)

Training classes

Training via list data

import logging
import os
import sys
from .conversation import Statement, Response
from . import utils

class ListTrainer(Trainer):
    Allows a chat bot to be trained using a list of strings
    where the list represents a conversation.

    def train(self, conversation):
        Train the chat bot based on the provided list of
        statements that represents a single conversation.
        previous_statement_text = None

        for conversation_count, text in enumerate(conversation):
            if self.show_training_progress:
                    'List Trainer',
                    conversation_count + 1, len(conversation)

            statement = self.get_or_create(text)

            if previous_statement_text:

            previous_statement_text = statement.text

Allows a chat bot to be trained using a list of strings where the list represents a conversation.

For the training process, you will need to pass in a list of statements where the order of each statement is based on its 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”.

from chatterbot.trainers import ListTrainer

chatterbot = ChatBot("Training Example")

    "Hi there!",


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.

    "How are you?",
    "I am good.",
    "That is good to hear.",
    "Thank you",
    "You are welcome.",

Training with corpus data

import logging
import os
import sys
from .conversation import Statement, Response
from . import utils

class ChatterBotCorpusTrainer(Trainer):
    Allows the chat bot to be trained using data from the
    ChatterBot dialog corpus.

    def __init__(self, storage, **kwargs):
        super(ChatterBotCorpusTrainer, self).__init__(storage, **kwargs)
        from .corpus import Corpus

        self.corpus = Corpus()

    def train(self, *corpus_paths):

        # Allow a list of corpora to be passed instead of arguments
        if len(corpus_paths) == 1:
            if isinstance(corpus_paths[0], list):
                corpus_paths = corpus_paths[0]

        # Train the chat bot with each statement and response pair
        for corpus_path in corpus_paths:

            corpora = self.corpus.load_corpus(corpus_path)

            corpus_files = self.corpus.list_corpus_files(corpus_path)
            for corpus_count, corpus in enumerate(corpora):
                for conversation_count, conversation in enumerate(corpus):

                    if self.show_training_progress:
                            str(os.path.basename(corpus_files[corpus_count])) + ' Training',
                            conversation_count + 1,

                    previous_statement_text = None

                    for text in conversation:
                        statement = self.get_or_create(text)

                        if previous_statement_text:

                        previous_statement_text = statement.text

Allows the chat bot to be trained using data from the ChatterBot dialog corpus.

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.

from chatterbot.trainers import ChatterBotCorpusTrainer

chatterbot = ChatBot("Training Example")


Specifying corpus scope

It is also possible to import individual subsets of ChatterBot’s corpus at once. For example, if you only wish to train based on the english greetings and conversations corpora then you would simply specify them.


You can also specify file paths to corpus files or directories of corpus files when calling the trainmethod.


Training with the Twitter API

import logging
import os
import sys
from .conversation import Statement, Response
from . import utils

class TwitterTrainer(Trainer):
    Allows the chat bot to be trained using data
    gathered from Twitter.

    :param random_seed_word: The seed word to be used to get random tweets from the Twitter API.
                             This parameter is optional. By default it is the word 'random'.
    :param twitter_lang: Language for results as ISO 639-1 code.
                         This parameter is optional. Default is None (all languages).

    def __init__(self, storage, **kwargs):
        super(TwitterTrainer, self).__init__(storage, **kwargs)
        from twitter import Api as TwitterApi

        # The word to be used as the first search term when searching for tweets
        self.random_seed_word = kwargs.get('random_seed_word', 'random')
        self.lang = kwargs.get('twitter_lang')

        self.api = TwitterApi(

    def random_word(self, base_word, lang=None):
        Generate a random word using the Twitter API.

        Search twitter for recent tweets containing the term 'random'.
        Then randomly select one word from those tweets and do another
        search with that word. Return a randomly selected word from the
        new set of results.
        import random
        random_tweets = self.api.GetSearch(term=base_word, count=5, lang=lang)
        random_words = self.get_words_from_tweets(random_tweets)
        random_word = random.choice(list(random_words))
        tweets = self.api.GetSearch(term=random_word, count=5, lang=lang)
        words = self.get_words_from_tweets(tweets)
        word = random.choice(list(words))
        return word

    def get_words_from_tweets(self, tweets):
        Given a list of tweets, return the set of
        words from the tweets.
        words = set()

        for tweet in tweets:
            tweet_words = tweet.text.split()

            for word in tweet_words:
                # If the word contains only letters with a length from 4 to 9
                if word.isalpha() and len(word) > 3 and len(word) <= 9:

        return words

    def get_statements(self):
        Returns list of random statements from the API.
        from twitter import TwitterError
        statements = []

        # Generate a random word
        random_word = self.random_word(self.random_seed_word, self.lang)'Requesting 50 random tweets containing the word {}'.format(random_word))
        tweets = self.api.GetSearch(term=random_word, count=50, lang=self.lang)
        for tweet in tweets:
            statement = Statement(tweet.text)

            if tweet.in_reply_to_status_id:
                    status = self.api.GetStatus(tweet.in_reply_to_status_id)
                except TwitterError as error:
                    self.logger.warning(str(error))'Adding {} tweets with responses'.format(len(statements)))

        return statements

    def train(self):
        for _ in range(0, 10):
            statements = self.get_statements()
            for statement in statements:

Allows the chat bot to be trained using data gathered from Twitter.

Parameters:random_seed_word – The seed word to be used to get random tweets from the Twitter API. This parameter is optional. By default it is the word ‘random’.twitter_lang – Language for results as ISO 639-1 code. This parameter is optional. Default is None (all languages).

Create an new app using your twitter account. Once created, it will provide you with the following credentials that are required to work with the Twitter API.

twitter_consumer_keyConsumer key of twitter app.
twitter_consumer_secretConsumer secret of twitter app.
twitter_access_token_keyAccess token key of twitter app.
twitter_access_token_secretAccess token secret of twitter app.

Twitter training example

# -*- coding: utf-8 -*-
from chatterbot import ChatBot
from settings import TWITTER
import logging

This example demonstrates how you can train your chat bot
using data from Twitter.

To use this example, create a new file called
In define the following:

    "CONSUMER_KEY": "my-twitter-consumer-key",
    "CONSUMER_SECRET": "my-twitter-consumer-secret",
    "ACCESS_TOKEN": "my-access-token",
    "ACCESS_TOKEN_SECRET": "my-access-token-secret"

# Comment out the following line to disable verbose logging

chatbot = ChatBot(

chatbot.train()'Trained database generated successfully!')

Training with the Ubuntu dialog corpus

Warning:The Ubuntu dialog corpus is a massive data set. Developers will currently experience significantly decreased performance in the form of delayed training and response times from the chat bot when using this corpus.

import logging
import os
import sys
from .conversation import Statement, Response
from . import utils

class UbuntuCorpusTrainer(Trainer):
    Allow chatbots to be trained with the data from
    the Ubuntu Dialog Corpus.

    def __init__(self, storage, **kwargs):
        super(UbuntuCorpusTrainer, self).__init__(storage, **kwargs)

        self.data_download_url = kwargs.get(

        self.data_directory = kwargs.get(

        self.extracted_data_directory = os.path.join(
            self.data_directory, 'ubuntu_dialogs'

        # Create the data directory if it does not already exist
        if not os.path.exists(self.data_directory):

    def is_downloaded(self, file_path):
        Check if the data file is already downloaded.
        if os.path.exists(file_path):
  'File is already downloaded')
            return True

        return False

    def is_extracted(self, file_path):
        Check if the data file is already extracted.

        if os.path.isdir(file_path):
  'File is already extracted')
            return True
        return False

    def download(self, url, show_status=True):
        Download a file from the given url.
        Show a progress indicator for the download status.
        Based on:
        import requests

        file_name = url.split('/')[-1]
        file_path = os.path.join(self.data_directory, file_name)

        # Do not download the data if it already exists
        if self.is_downloaded(file_path):
            return file_path

        with open(file_path, 'wb') as open_file:
            print('Downloading %s' % url)
            response = requests.get(url, stream=True)
            total_length = response.headers.get('content-length')

            if total_length is None:
                # No content length header
                download = 0
                total_length = int(total_length)
                for data in response.iter_content(chunk_size=4096):
                    download += len(data)
                    if show_status:
                        done = int(50 * download / total_length)
                        sys.stdout.write('\r[%s%s]' % ('=' * done, ' ' * (50 - done)))

            # Add a new line after the download bar

        print('Download location: %s' % file_path)
        return file_path

    def extract(self, file_path):
        Extract a tar file at the specified file path.
        import tarfile

        print('Extracting {}'.format(file_path))

        if not os.path.exists(self.extracted_data_directory):

        def track_progress(members):
            for member in members:
                # This will be the current file being extracted
                yield member

        with as tar:
            tar.extractall(path=self.extracted_data_directory, members=track_progress(tar))'File extracted to {}'.format(self.extracted_data_directory))

        return True

    def train(self):
        import glob
        import csv

        # Download and extract the Ubuntu dialog corpus if needed
        corpus_download_path =

        # Extract if the directory doesn not already exists
        if not self.is_extracted(self.extracted_data_directory):

        extracted_corpus_path = os.path.join(
            '**', '**', '*.tsv'

        file_kwargs = {}

        if sys.version_info[0] > 2:
            # Specify the encoding in Python versions 3 and up
            file_kwargs['encoding'] = 'utf-8'
            # WARNING: This might fail to read a unicode corpus file in Python 2.x

        for file in glob.iglob(extracted_corpus_path):
  'Training from: {}'.format(file))

            with open(file, 'r', **file_kwargs) as tsv:
                reader = csv.reader(tsv, delimiter='\t')

                previous_statement_text = None

                for row in reader:
                    if len(row) > 0:
                        text = row[3]
                        statement = self.get_or_create(text)
                        print(text, len(row))

                        statement.add_extra_data('datetime', row[0])
                        statement.add_extra_data('speaker', row[1])

                        if row[2].strip():
                            statement.add_extra_data('addressing_speaker', row[2])

                        if previous_statement_text:

                        previous_statement_text = statement.text

Allow chatbots to be trained with the data from the Ubuntu Dialog Corpus.

This training class makes it possible to train your chat bot using the Ubuntu dialog corpus. Because of the file size of the Ubuntu dialog corpus, the download and training process may take a considerable amount of time.

This training class will handle the process of downloading the compressed corpus file and extracting it. If the file has already been downloaded, it will not be downloaded again. If the file is already extracted, it will not be extracted again.

Creating a new training class

You can create a new trainer to train your chat bot from your own data files. You may choose to do this if you want to train your chat bot from a data source in a format that is not directly supported by ChatterBot.

Your custom trainer should inherit chatterbot.trainers.Trainer class. Your trainer will need to have a method named train, that can take any parameters you choose.

Take a look at the existing trainer classes on GitHub for examples.

Leave a Comment

Your email address will not be published.