ChatterBot’s statement objects represent either an input statement that the chat bot has received from a user, or an output statement that the chat bot has returned based on some input.

class chatterbot.conversation.Statement(text, **kwargs)[source]

A statement represents a single spoken entity, sentence or phrase that someone can say.

confidence = None

ChatterBot’s logic adapters assign a confidence score to the statement before it is returned. The confidence score indicates the degree of certainty with which the chat bot believes this is the correct response to the given input.

add_extra_data(key, value)[source]

This method allows additional data to be stored on the statement object.

Typically this data is something that pertains just to this statement. For example, a value stored here might be the tagged parts of speech for each word in the statement text.

  • key = ‘pos_tags’
  • value = [(‘Now’, ‘RB’), (‘for’, ‘IN’), (‘something’, ‘NN’), (‘different’, ‘JJ’)]
  • key (str) – The key to use in the dictionary of extra data.
  • value – The value to set for the specified key.

Add the response to the list of statements that this statement is in response to. If the response is already in the list, increment the occurrence count of that response.

Parameters:response (Response) – The response to add.

Find the number of times that the statement has been used as a response to the current statement.

Parameters:statement (Statement) – The statement object to get the count for.
Returns:Return the number of times the statement has been used as a response.
Return type:int

Removes a response from the statement’s response list based on the value of the response text.

Parameters:response_text (str) – The text of the response to be removed.

This property is to allow ChatterBot Statement objects to be swappable with Django Statement models.


Save the statement in the database.

Returns:A dictionary representation of the statement object.
Return type:dict


ChatterBot’s response objects represent the relationship between two statements. A response indicates that one statements was issued in response to another statement.

class chatterbot.conversation.Response(text, **kwargs)[source]

A response represents an entity which response to a statement.

Statement-response relationship

ChatterBot stores knowledge of conversations as statements. Each statement can have any number possible responses.

ChatterBot statement-response relationship

Each Statement object has an in_response_to reference which links the statement to a number of other statements that it has been learned to be in response to. The in_response_to attribute is essentially a reference to all parent statements of the current statement.

ChatterBot statement relationship

The Response object’s occurrence attribute indicates the number of times that the statement has been given as a response. This makes it possible for the chat bot to determine if a particular response is more commonly used than another.

Statement comparison

ChatterBot uses Statement objects to hold information about things that can be said. An important part of how a chat bot selects a response is based on it’s ability to compare two statements to each other. There is a number of ways to do this, and ChatterBot comes with a handful of method built in for you to use.

This module contains various text-comparison algorithms designed to compare one statement to another.

chatterbot.comparisons.jaccard_similarity(statement, other_statement, threshold=0.5)[source]

Calculates the similarity of two statements based on the Jaccard index.

The Jaccard index is composed of a numerator and denominator. In the numerator, we count the number of items that are shared between the sets. In the denominator, we count the total number of items across both sets. Let’s say we define sentences to be equivalent if 50% or more of their tokens are equivalent. Here are two sample sentences:

The young cat is hungry. The cat is very hungry.

When we parse these sentences to remove stopwords, we end up with the following two sets:

{young, cat, hungry} {cat, very, hungry}

In our example above, our intersection is {cat, hungry}, which has count of two. The union of the sets is {young, cat, very, hungry}, which has a count of four. Therefore, our Jaccard similarity index is two divided by four, or 50%. Given our threshold above, we would consider this to be a match.

chatterbot.comparisons.levenshtein_distance(statement, other_statement)[source]

Compare two statements based on the Levenshtein distance of each statement’s text.

For example, there is a 65% similarity between the statements “where is the post office?” and “looking for the post office” based on the Levenshtein distance algorithm.

Returns:The percent of similarity between the text of the statements.
Return type:float
chatterbot.comparisons.sentiment_comparison(statement, other_statement)[source]

Calculate the similarity of two statements based on the closeness of the sentiment value calculated for each statement.

Returns:The percent of similarity between the sentiment value.
Return type:float
chatterbot.comparisons.synset_distance(statement, other_statement)[source]

Calculate the similarity of two statements. This is based on the total maximum synset similarity between each word in each sentence.

This algorithm uses the wordnet functionality of NLTK to determine the similarity of two statements based on the path similarity between each token of each statement. This is essentially an evaluation of the closeness of synonyms.

Returns:The percent of similarity between the closest synset distance.
Return type:float

Use your own comparison function

You can create your own comparison function and use it as long as the function takes two statements as parameters and returns a numeric value between 0 and 1. A 0 should represent the lowest possible similarity and a 1 should represent the highest possible similarity.

def comparison_function(statement, other_statement):

    # Your comparison logic

    # Return your calculated value here
    return 0.0

Setting the comparison method

To set the statement comparison method for your chat bot, you will need to pass the statement_comparison_function parameter to your chat bot when you initialize it. An example of this is shown bellow.

from chatterbot import ChatBot
from chatterbot.comparisons import levenshtein_distance

chatbot = ChatBot(
    # ...