ChatterBot 1.2.3__py3-none-any.whl → 1.2.5__py3-none-any.whl

chatterbot/__init__.py

@@ -4,7 +4,7 @@ ChatterBot is a machine learning, conversational dialog engine.
 from .chatterbot import ChatBot
 
 
-__version__ = '1.2.3'
+__version__ = '1.2.5'
 
 __all__ = (
     'ChatBot',

chatterbot/__main__.py

@@ -1,7 +1,16 @@
+"""
+Example usage for ChatterBot command line arguments:
+
+python -m chatterbot --help
+"""
+
 import sys
 
 
 def get_chatterbot_version():
+    """
+    Return the version of the current package.
+    """
     from chatterbot import __version__
 
     return __version__
@@ -10,3 +19,9 @@ def get_chatterbot_version():
 if __name__ == '__main__':
     if '--version' in sys.argv:
         print(get_chatterbot_version())
+    elif '--help' in sys.argv:
+        print('usage: chatterbot [--version, --help]')
+        print('  --version: Print the version of ChatterBot')
+        print('  --help: Print this help message')
+        print()
+        print('Documentation at https://docs.chatterbot.us')

chatterbot/chatterbot.py

@@ -3,6 +3,7 @@ from chatterbot.storage import StorageAdapter
 from chatterbot.logic import LogicAdapter
 from chatterbot.search import TextSearch, IndexedTextSearch
 from chatterbot.tagging import PosLemmaTagger
+from chatterbot.conversation import Statement
 from chatterbot import languages
 from chatterbot import utils
 import spacy
@@ -11,11 +12,41 @@ import spacy
 class ChatBot(object):
     """
     A conversational dialog chat bot.
+
+    :param name: A name is the only required parameter for the ChatBot class.
+    :type name: str
+
+    :keyword storage_adapter: The dot-notated import path to a storage adapter class.
+                              Defaults to ``"chatterbot.storage.SQLStorageAdapter"``.
+    :type storage_adapter: str
+
+    :param logic_adapters: A list of dot-notated import paths to each logic adapter the bot uses.
+                           Defaults to ``["chatterbot.logic.BestMatch"]``.
+    :type logic_adapters: list
+
+    :param tagger: The tagger to use for the chat bot.
+                   Defaults to :class:`~chatterbot.tagging.PosLemmaTagger`
+    :type tagger: object
+
+    :param tagger_language: The language to use for the tagger.
+                            Defaults to :class:`~chatterbot.languages.ENG`.
+    :type tagger_language: object
+
+    :param preprocessors: A list of preprocessor functions to use for the chat bot.
+    :type preprocessors: list
+
+    :param read_only: If True, the chat bot will not save any input it receives, defaults to False.
+    :type read_only: bool
+
+    :param logger: A ``Logger`` object.
+    :type logger: logging.Logger
     """
 
     def __init__(self, name, **kwargs):
         self.name = name
 
+        self.logger = kwargs.get('logger', logging.getLogger(__name__))
+
         storage_adapter = kwargs.get('storage_adapter', 'chatterbot.storage.SQLStorageAdapter')
 
         logic_adapters = kwargs.get('logic_adapters', [
@@ -30,11 +61,29 @@ class ChatBot(object):
 
         self.storage = utils.initialize_class(storage_adapter, **kwargs)
 
-        Tagger = kwargs.get('tagger', PosLemmaTagger)
+        tagger_language = kwargs.get('tagger_language', languages.ENG)
 
-        self.tagger = Tagger(language=kwargs.get(
-            'tagger_language', languages.ENG
-        ))
+        try:
+            Tagger = kwargs.get('tagger', PosLemmaTagger)
+
+            self.tagger = Tagger(language=tagger_language)
+        except IOError as io_error:
+            # Return a more helpful error message if possible
+            if "Can't find model" in str(io_error):
+                model_name = utils.get_model_for_language(tagger_language)
+                if hasattr(tagger_language, 'ENGLISH_NAME'):
+                    language_name = tagger_language.ENGLISH_NAME
+                else:
+                    language_name = tagger_language
+                raise self.ChatBotException(
+                    'Setup error:\n'
+                    f'The Spacy model for "{language_name}" language is missing.\n'
+                    'Please install the model using the command:\n\n'
+                    f'python -m spacy download {model_name}\n\n'
+                    'See https://spacy.io/usage/models for more information about available models.'
+                ) from io_error
+            else:
+                raise io_error
 
         primary_search_algorithm = IndexedTextSearch(self, **kwargs)
         text_search_algorithm = TextSearch(self, **kwargs)
@@ -63,18 +112,15 @@ class ChatBot(object):
         # NOTE: 'xx' is the language code for a multi-language model
         self.nlp = spacy.blank(self.tagger.language.ISO_639_1)
 
-        self.logger = kwargs.get('logger', logging.getLogger(__name__))
-
         # Allow the bot to save input it receives so that it can learn
         self.read_only = kwargs.get('read_only', False)
 
-    def get_response(self, statement=None, **kwargs):
+    def get_response(self, statement=None, **kwargs) -> Statement:
         """
         Return the bot's response based on the input.
 
         :param statement: An statement object or string.
         :returns: A response to the input.
-        :rtype: Statement
 
         :param additional_response_selection_parameters: Parameters to pass to the
             chat bot's logic adapters to control response selection.
@@ -268,7 +314,7 @@ class ChatBot(object):
         # Save the response statement
         return self.storage.create(**statement.serialize())
 
-    def get_latest_response(self, conversation):
+    def get_latest_response(self, conversation: str):
         """
         Returns the latest response in a conversation if it exists.
         Returns None if a matching conversation cannot be found.

chatterbot/comparisons.py

@@ -2,7 +2,7 @@
 This module contains various text-comparison algorithms
 designed to compare one statement to another.
 """
-from chatterbot import constants
+from chatterbot.utils import get_model_for_language
 from difflib import SequenceMatcher
 import spacy
 
@@ -19,19 +19,17 @@ class Comparator:
     def __call__(self, statement_a, statement_b):
         return self.compare(statement_a, statement_b)
 
-    def compare_text(self, text_a, text_b):
+    def compare_text(self, text_a: str, text_b: str) -> float:
         """
         Implemented in subclasses: compare text_a to text_b.
 
         :return: The percent of similarity between the statements based on the implemented algorithm.
-        :rtype: float
         """
         return 0
 
-    def compare(self, statement_a, statement_b):
+    def compare(self, statement_a, statement_b) -> float:
         """
         :return: The percent of similarity between the statements based on the implemented algorithm.
-        :rtype: float
         """
         return self.compare_text(statement_a.text, statement_b.text)
 
@@ -46,12 +44,11 @@ class LevenshteinDistance(Comparator):
     based on the Levenshtein distance algorithm.
     """
 
-    def compare_text(self, text_a, text_b):
+    def compare_text(self, text_a: str, text_b: str) -> float:
         """
         Compare the two pieces of text.
 
         :return: The percent of similarity between the text of the statements.
-        :rtype: float
         """
 
         # Return 0 if either statement has a None text value
@@ -100,22 +97,16 @@ class SpacySimilarity(Comparator):
     def __init__(self, language):
         super().__init__(language)
 
-        try:
-            model = constants.DEFAULT_LANGUAGE_TO_SPACY_MODEL_MAP[self.language]
-        except KeyError as e:
-            raise KeyError(
-                f'Spacy model is not available for language {self.language}'
-            ) from e
+        model = get_model_for_language(language)
 
         # Disable the Named Entity Recognition (NER) component because it is not necessary
         self.nlp = spacy.load(model, exclude=['ner'])
 
-    def compare_text(self, text_a, text_b):
+    def compare_text(self, text_a: str, text_b: str) -> float:
         """
         Compare the similarity of two strings.
 
         :return: The percent of similarity between the closest synset distance.
-        :rtype: float
         """
 
         # Return 0 if either statement has a None text value
@@ -157,17 +148,12 @@ class JaccardSimilarity(Comparator):
     def __init__(self, language):
         super().__init__(language)
 
-        try:
-            model = constants.DEFAULT_LANGUAGE_TO_SPACY_MODEL_MAP[self.language]
-        except KeyError as e:
-            raise KeyError(
-                f'Spacy model is not available for language {self.language}'
-            ) from e
+        model = get_model_for_language(language)
 
         # Disable the Named Entity Recognition (NER) component because it is not necessary
         self.nlp = spacy.load(model, exclude=['ner'])
 
-    def compare_text(self, text_a, text_b):
+    def compare_text(self, text_a: str, text_b: str) -> float:
         """
         Return the calculated similarity of two
         statements based on the Jaccard index.

chatterbot/conversation.py

@@ -40,10 +40,9 @@ class StatementMixin(object):
         """
         self.tags.extend(tags)
 
-    def serialize(self):
+    def serialize(self) -> dict:
         """
         :returns: A dictionary representation of the statement object.
-        :rtype: dict
         """
         data = {}
 

chatterbot/ext/django_chatterbot/abstract_models.py

@@ -32,7 +32,8 @@ class AbstractBaseTag(models.Model):
 
     name = models.SlugField(
         max_length=constants.TAG_NAME_MAX_LENGTH,
-        unique=True
+        unique=True,
+        help_text='The unique name of the tag.'
     )
 
     class Meta:
@@ -49,16 +50,19 @@ class AbstractBaseStatement(models.Model, StatementMixin):
     """
 
     text = models.CharField(
-        max_length=constants.STATEMENT_TEXT_MAX_LENGTH
+        max_length=constants.STATEMENT_TEXT_MAX_LENGTH,
+        help_text='The text of the statement.'
     )
 
     search_text = models.CharField(
         max_length=constants.STATEMENT_TEXT_MAX_LENGTH,
-        blank=True
+        blank=True,
+        help_text='A modified version of the statement text optimized for searching.'
     )
 
     conversation = models.CharField(
-        max_length=constants.CONVERSATION_LABEL_MAX_LENGTH
+        max_length=constants.CONVERSATION_LABEL_MAX_LENGTH,
+        help_text='A label used to link this statement to a conversation.'
     )
 
     created_at = models.DateTimeField(
@@ -68,21 +72,25 @@ class AbstractBaseStatement(models.Model, StatementMixin):
 
     in_response_to = models.CharField(
         max_length=constants.STATEMENT_TEXT_MAX_LENGTH,
-        null=True
+        null=True,
+        help_text='The text of the statement that this statement is in response to.'
     )
 
     search_in_response_to = models.CharField(
         max_length=constants.STATEMENT_TEXT_MAX_LENGTH,
-        blank=True
+        blank=True,
+        help_text='A modified version of the in_response_to text optimized for searching.'
     )
 
     persona = models.CharField(
-        max_length=constants.PERSONA_MAX_LENGTH
+        max_length=constants.PERSONA_MAX_LENGTH,
+        help_text='A label used to link this statement to a persona.'
     )
 
     tags = models.ManyToManyField(
         TAG_MODEL,
-        related_name='statements'
+        related_name='statements',
+        help_text='The tags that are associated with this statement.'
     )
 
     # This is the confidence with which the chat bot believes

chatterbot/ext/django_chatterbot/apps.py

@@ -6,3 +6,10 @@ class DjangoChatterBotConfig(AppConfig):
     name = 'chatterbot.ext.django_chatterbot'
     label = 'django_chatterbot'
     verbose_name = 'Django ChatterBot'
+
+    def ready(self):
+        from chatterbot.ext.django_chatterbot import settings as defaults
+        from django.conf import settings
+
+        settings.CHATTERBOT = getattr(settings, 'CHATTERBOT', {})
+        settings.CHATTERBOT.update(defaults.CHATTERBOT_DEFAULTS)

chatterbot/ext/django_chatterbot/migrations/0020_alter_statement_conversation_and_more.py

@@ -0,0 +1,53 @@
+# Generated by Django 4.1 on 2025-03-29 23:27
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('django_chatterbot', '0019_alter_statement_id_alter_tag_id_and_more'),
+    ]
+
+    operations = [
+        migrations.AlterField(
+            model_name='statement',
+            name='conversation',
+            field=models.CharField(help_text='A label used to link this statement to a conversation.', max_length=32),
+        ),
+        migrations.AlterField(
+            model_name='statement',
+            name='in_response_to',
+            field=models.CharField(help_text='The text of the statement that this statement is in response to.', max_length=255, null=True),
+        ),
+        migrations.AlterField(
+            model_name='statement',
+            name='persona',
+            field=models.CharField(help_text='A label used to link this statement to a persona.', max_length=50),
+        ),
+        migrations.AlterField(
+            model_name='statement',
+            name='search_in_response_to',
+            field=models.CharField(blank=True, help_text='A modified version of the in_response_to text optimized for searching.', max_length=255),
+        ),
+        migrations.AlterField(
+            model_name='statement',
+            name='search_text',
+            field=models.CharField(blank=True, help_text='A modified version of the statement text optimized for searching.', max_length=255),
+        ),
+        migrations.AlterField(
+            model_name='statement',
+            name='tags',
+            field=models.ManyToManyField(help_text='The tags that are associated with this statement.', related_name='statements', to='django_chatterbot.tag'),
+        ),
+        migrations.AlterField(
+            model_name='statement',
+            name='text',
+            field=models.CharField(help_text='The text of the statement.', max_length=255),
+        ),
+        migrations.AlterField(
+            model_name='tag',
+            name='name',
+            field=models.SlugField(help_text='The unique name of the tag.', unique=True),
+        ),
+    ]

chatterbot/ext/django_chatterbot/settings.py

@@ -5,7 +5,7 @@ from django.conf import settings
 from chatterbot import constants
 
 
-CHATTERBOT_SETTINGS = getattr(settings, 'CHATTERBOT', {})
+CHATTERBOT = getattr(settings, 'CHATTERBOT', {})
 
 CHATTERBOT_DEFAULTS = {
     'name': 'ChatterBot',
@@ -13,5 +13,4 @@ CHATTERBOT_DEFAULTS = {
     'django_app_name': constants.DEFAULT_DJANGO_APP_NAME
 }
 
-CHATTERBOT = CHATTERBOT_DEFAULTS.copy()
-CHATTERBOT.update(CHATTERBOT_SETTINGS)
+CHATTERBOT.update(CHATTERBOT_DEFAULTS)

chatterbot/ext/sqlalchemy_app/models.py

@@ -1,7 +1,7 @@
 from sqlalchemy import Table, Column, Integer, String, DateTime, ForeignKey
-from sqlalchemy.orm import relationship
+from sqlalchemy.orm import relationship, declarative_base
 from sqlalchemy.sql import func
-from sqlalchemy.ext.declarative import declared_attr, declarative_base
+from sqlalchemy.ext.declarative import declared_attr
 
 from chatterbot.conversation import StatementMixin
 from chatterbot import constants

chatterbot/logic/logic_adapter.py

@@ -4,6 +4,7 @@ from chatterbot.adapters import Adapter
 from chatterbot.storage import StorageAdapter
 from chatterbot.search import IndexedTextSearch
 from chatterbot.conversation import Statement
+from chatterbot import utils
 
 
 class LogicAdapter(Adapter):
@@ -28,7 +29,7 @@ class LogicAdapter(Adapter):
     :type response_selection_method: collections.abc.Callable
 
     :param default_response:
-          The default response returned by this logic adaper
+          The default response returned by this logic adapter
           if there is no other possible response to return.
     :type default_response: str or list or tuple
     """
@@ -50,6 +51,14 @@ class LogicAdapter(Adapter):
             'maximum_similarity_threshold', 0.95
         )
 
+        if response_selection_method := kwargs.get('response_selection_method'):
+            if isinstance(response_selection_method, str):
+                # If an import path is provided, import the method
+                response_selection_method = utils.import_module(
+                    response_selection_method
+                )
+                kwargs['response_selection_method'] = response_selection_method
+
         # By default, select the first available response
         self.select_response = kwargs.get(
             'response_selection_method',
@@ -68,18 +77,16 @@ class LogicAdapter(Adapter):
             Statement(text=default) for default in default_responses
         ]
 
-    def can_process(self, statement):
+    def can_process(self, statement) -> bool:
         """
         A preliminary check that is called to determine if a
         logic adapter can process a given statement. By default,
         this method returns true but it can be overridden in
         child classes as needed.
-
-        :rtype: bool
         """
         return True
 
-    def process(self, statement, additional_response_selection_parameters=None):
+    def process(self, statement, additional_response_selection_parameters=None) -> Statement:
         """
         Override this method and implement your logic for selecting a response to an input statement.
 
@@ -97,12 +104,10 @@ class LogicAdapter(Adapter):
         :param additional_response_selection_parameters: Parameters to be used when
             filtering results to choose a response from.
         :type additional_response_selection_parameters: dict
-
-        :rtype: Statement
         """
         raise self.AdapterMethodNotImplementedError()
 
-    def get_default_response(self, input_statement):
+    def get_default_response(self, input_statement: Statement) -> Statement:
         """
         This method is called when a logic adapter is unable to generate any
         other meaningful response.
@@ -125,7 +130,7 @@ class LogicAdapter(Adapter):
         return response
 
     @property
-    def class_name(self):
+    def class_name(self) -> str:
         """
         Return the name of the current logic adapter class.
         This is typically used for logging and debugging.

chatterbot/logic/specific_response.py

@@ -1,6 +1,7 @@
 from chatterbot.logic import LogicAdapter
 from chatterbot.conversation import Statement
-from chatterbot import constants, languages
+from chatterbot import languages
+from chatterbot.utils import get_model_for_language
 import spacy
 
 
@@ -35,12 +36,7 @@ class SpecificResponseAdapter(LogicAdapter):
         self._output_text = kwargs.get('output_text')
 
     def _initialize_nlp(self, language):
-        try:
-            model = constants.DEFAULT_LANGUAGE_TO_SPACY_MODEL_MAP[language]
-        except KeyError as e:
-            raise KeyError(
-                f'Spacy model is not available for language {language}'
-            ) from e
+        model = get_model_for_language(language)
 
         return spacy.load(model)
 

chatterbot/logic/time_adapter.py

@@ -1,7 +1,8 @@
 from datetime import datetime
-from chatterbot import constants, languages
+from chatterbot import languages
 from chatterbot.logic import LogicAdapter
 from chatterbot.conversation import Statement
+from chatterbot.utils import get_model_for_language
 import spacy
 
 
@@ -36,12 +37,7 @@ class TimeLogicAdapter(LogicAdapter):
 
         language = kwargs.get('language', languages.ENG)
 
-        try:
-            model = constants.DEFAULT_LANGUAGE_TO_SPACY_MODEL_MAP[language]
-        except KeyError as e:
-            raise KeyError(
-                f'Spacy model is not available for language {language}'
-            ) from e
+        model = get_model_for_language(language)
 
         self.nlp = spacy.load(model)
 

chatterbot/preprocessors.py

@@ -1,12 +1,13 @@
 """
 Statement pre-processors.
 """
+from chatterbot.conversation import Statement
 from unicodedata import normalize
 from re import sub as re_sub
 from html import unescape
 
 
-def clean_whitespace(statement):
+def clean_whitespace(statement: Statement) -> Statement:
     """
     Remove any consecutive whitespace characters from the statement text.
     """
@@ -24,7 +25,7 @@ def clean_whitespace(statement):
     return statement
 
 
-def unescape_html(statement):
+def unescape_html(statement: Statement) -> Statement:
     """
     Convert escaped html characters into unescaped html characters.
     For example: "&lt;b&gt;" becomes "<b>".
@@ -34,7 +35,7 @@ def unescape_html(statement):
     return statement
 
 
-def convert_to_ascii(statement):
+def convert_to_ascii(statement: Statement) -> Statement:
     """
     Converts unicode characters to ASCII character equivalents.
     For example: "på fédéral" becomes "pa federal".

chatterbot/response_selection.py

@@ -2,10 +2,11 @@
 Response selection methods determines which response should be used in
 the event that multiple responses are generated within a logic adapter.
 """
+from chatterbot.conversation import Statement
 import logging
 
 
-def get_most_frequent_response(input_statement, response_list, storage=None):
+def get_most_frequent_response(input_statement, response_list, storage=None) -> Statement:
     """
     :param input_statement: A statement, that closely matches an input to the chat bot.
     :type input_statement: Statement
@@ -18,7 +19,6 @@ def get_most_frequent_response(input_statement, response_list, storage=None):
     :type storage: StorageAdapter
 
     :return: The response statement with the greatest number of occurrences.
-    :rtype: Statement
     """
     matching_response = None
     occurrence_count = -1
@@ -41,7 +41,7 @@ def get_most_frequent_response(input_statement, response_list, storage=None):
     return matching_response
 
 
-def get_first_response(input_statement, response_list, storage=None):
+def get_first_response(input_statement, response_list, storage=None) -> Statement:
     """
     :param input_statement: A statement, that closely matches an input to the chat bot.
     :type input_statement: Statement
@@ -54,7 +54,6 @@ def get_first_response(input_statement, response_list, storage=None):
     :type storage: StorageAdapter
 
     :return: Return the first statement in the response list.
-    :rtype: Statement
     """
     logger = logging.getLogger(__name__)
     logger.info('Selecting first response from list of {} options.'.format(
@@ -63,7 +62,7 @@ def get_first_response(input_statement, response_list, storage=None):
     return response_list[0]
 
 
-def get_random_response(input_statement, response_list, storage=None):
+def get_random_response(input_statement, response_list, storage=None) -> Statement:
     """
     :param input_statement: A statement, that closely matches an input to the chat bot.
     :type input_statement: Statement
@@ -76,7 +75,6 @@ def get_random_response(input_statement, response_list, storage=None):
     :type storage: StorageAdapter
 
     :return: Choose a random response from the selection.
-    :rtype: Statement
     """
     from random import choice
     logger = logging.getLogger(__name__)

chatterbot/search.py

@@ -149,58 +149,3 @@ class TextSearch:
                 ))
 
                 yield statement
-
-
-class VectorSearch:
-    """
-    .. note:: BETA feature: this search method is new and experimental.
-
-    Search for similar text based on a :term:`vector database`.
-    """
-
-    name = 'vector_search'
-
-    def __init__(self, chatbot, **kwargs):
-        from chatterbot.storage import RedisVectorStorageAdapter
-
-        # Good documentation:
-        # https://python.langchain.com/docs/integrations/vectorstores/redis/
-        #
-        # https://hub.docker.com/r/redis/redis-stack
-
-        # Mondodb:
-        # > Vector Search is only supported on Atlas Clusters
-        # https://www.mongodb.com/community/forums/t/can-a-local-mongodb-instance-be-used-when-working-with-langchain-mongodbatlasvectorsearch/265356
-
-        # FAISS:
-        # https://python.langchain.com/docs/integrations/vectorstores/faiss/
-
-        print("Starting Redis Vector Store")
-
-        # TODO: look into:
-        # https://python.langchain.com/api_reference/redis/chat_message_history/langchain_redis.chat_message_history.RedisChatMessageHistory.html
-
-        # The VectorSearch class is only compatible with the RedisVectorStorageAdapter
-        if not isinstance(chatbot.storage, RedisVectorStorageAdapter):
-            raise Exception(
-                'The VectorSearch search method requires the RedisVectorStorageAdapter storage adapter.'
-            )
-
-    def search(self, input_statement, **additional_parameters):
-        print("Querying Vector Store")
-
-        # Similarity search with score and filter
-        # NOTE: It looks like `return_all` is needed to return the full document
-        # specifically what we need here is the ID
-        scored_results = self.storage.vector_store.similarity_search_with_score(
-            input_statement.text, k=2, return_all=True
-        )
-        # sort_by="score", filter={"category": "likes"})
-
-        print("Similarity Search with Score Results:\n")
-        for doc, score in scored_results:
-            print(f"Content: {doc.page_content[:150]}...")
-            print(f"ID: {doc.id}")
-            print(f"Metadata: {doc.metadata}")
-            print(f"Score: {score}")
-            print()