ChatterBot 1.2.2__py3-none-any.whl → 1.2.4__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.2'
+__version__ = '1.2.4'
 
 __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

@@ -11,11 +11,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 +60,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,8 +111,6 @@ 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)
 

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
 
@@ -100,12 +100,7 @@ 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'])
@@ -157,12 +152,7 @@ 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'])

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/specific_response.py

@@ -1,4 +1,8 @@
 from chatterbot.logic import LogicAdapter
+from chatterbot.conversation import Statement
+from chatterbot import languages
+from chatterbot.utils import get_model_for_language
+import spacy
 
 
 class SpecificResponseAdapter(LogicAdapter):
@@ -8,30 +12,65 @@ class SpecificResponseAdapter(LogicAdapter):
     :kwargs:
         * *input_text* (``str``) --
           The input text that triggers this logic adapter.
-        * *output_text* (``str``) --
+        * *output_text* (``str`` or ``function``) --
           The output text returned by this logic adapter.
+          If a function is provided, it should return a string.
     """
 
     def __init__(self, chatbot, **kwargs):
         super().__init__(chatbot, **kwargs)
-        from chatterbot.conversation import Statement
 
         self.input_text = kwargs.get('input_text')
 
-        output_text = kwargs.get('output_text')
-        self.response_statement = Statement(text=output_text)
+        self.matcher = None
+
+        if MatcherClass := kwargs.get('matcher'):
+            language = kwargs.get('language', languages.ENG)
+
+            self.nlp = self._initialize_nlp(language)
+
+            self.matcher = MatcherClass(self.nlp.vocab)
+
+            self.matcher.add('SpecificResponse', [self.input_text])
+
+        self._output_text = kwargs.get('output_text')
+
+    def _initialize_nlp(self, language):
+        model = get_model_for_language(language)
+
+        return spacy.load(model)
 
     def can_process(self, statement):
-        if statement.text == self.input_text:
+        if self.matcher:
+            doc = self.nlp(statement.text)
+            matches = self.matcher(doc)
+
+            if matches:
+                return True
+        elif statement.text == self.input_text:
             return True
 
         return False
 
     def process(self, statement, additional_response_selection_parameters=None):
 
-        if statement.text == self.input_text:
-            self.response_statement.confidence = 1
+        if callable(self._output_text):
+            response_statement = Statement(text=self._output_text())
+        else:
+            response_statement = Statement(text=self._output_text)
+
+        if self.matcher:
+            doc = self.nlp(statement.text)
+            matches = self.matcher(doc)
+
+            if matches:
+                response_statement.confidence = 1
+            else:
+                response_statement.confidence = 0
+
+        elif statement.text == self.input_text:
+            response_statement.confidence = 1
         else:
-            self.response_statement.confidence = 0
+            response_statement.confidence = 0
 
-        return self.response_statement
+        return response_statement

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/logic/unit_conversion.py

@@ -158,7 +158,8 @@ class UnitConversion(LogicAdapter):
                     response = func(p)
                     if response.confidence == 1.0:
                         break
-        except Exception:
+        except Exception as e:
+            self.chatbot.logger.warning('Error during UnitConversion: {}'.format(str(e)))
             response.confidence = 0.0
-        finally:
-            return response
+
+        return response

chatterbot/storage/__init__.py

@@ -2,6 +2,7 @@ from chatterbot.storage.storage_adapter import StorageAdapter
 from chatterbot.storage.django_storage import DjangoStorageAdapter
 from chatterbot.storage.mongodb import MongoDatabaseAdapter
 from chatterbot.storage.sql_storage import SQLStorageAdapter
+from chatterbot.storage.redis import RedisVectorStorageAdapter
 
 
 __all__ = (
@@ -9,4 +10,5 @@ __all__ = (
     'DjangoStorageAdapter',
     'MongoDatabaseAdapter',
     'SQLStorageAdapter',
+    'RedisVectorStorageAdapter',
 )

chatterbot/storage/redis.py

@@ -0,0 +1,390 @@
+from datetime import datetime
+from chatterbot.storage import StorageAdapter
+from chatterbot.conversation import Statement as StatementObject
+
+
+# TODO: This list may not be exhaustive.
+# Is there a full list of characters reserved by redis?
+REDIS_ESCAPE_CHARACTERS = {
+    '\\': '\\\\',
+    ':': '\\:',
+    '|': '\\|',
+    '%': '\\%',
+    '!': '\\!',
+    '-': '\\-',
+}
+
+REDIS_TRANSLATION_TABLE = str.maketrans(REDIS_ESCAPE_CHARACTERS)
+
+def _escape_redis_special_characters(text):
+    """
+    Escape special characters in a string that are used in redis queries.
+    """
+    return text.translate(REDIS_TRANSLATION_TABLE)
+
+
+class RedisVectorStorageAdapter(StorageAdapter):
+    """
+    .. warning:: BETA feature (Released March, 2025): this storage adapter is new
+        and experimental. Its functionality and default parameters might change
+        in the future and its behavior has not yet been finalized.
+
+    The RedisVectorStorageAdapter allows ChatterBot to store conversation
+    data in a redis instance.
+
+    All parameters are optional, by default a redis instance on localhost is assumed.
+
+    :keyword database_uri: eg: redis://localhost:6379/0',
+        The database_uri can be specified to choose a redis instance.
+    :type database_uri: str
+    """
+
+    class RedisMetaDataType:
+        """
+        Subclass for redis config metadata type enumerator.
+        """
+        TAG = 'tag'
+        TEXT = 'text'
+        NUMERIC = 'numeric'
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        from chatterbot.vectorstores import RedisVectorStore
+        from langchain_redis import RedisConfig  # RedisVectorStore
+        from langchain_huggingface import HuggingFaceEmbeddings
+
+        self.database_uri = kwargs.get('database_uri', 'redis://localhost:6379/0')
+
+        config = RedisConfig(
+            index_name='chatterbot',
+            redis_url=self.database_uri,
+            content_field='in_response_to',
+            metadata_schema=[
+                {
+                    'name': 'conversation',
+                    'type': self.RedisMetaDataType.TAG,
+                },
+                {
+                    'name': 'text',
+                    'type': self.RedisMetaDataType.TEXT,
+                },
+                {
+                    'name': 'created_at',
+                    'type': self.RedisMetaDataType.NUMERIC,
+                },
+                {
+                    'name': 'persona',
+                    'type': self.RedisMetaDataType.TEXT,
+                },
+                {
+                    'name': 'tags',
+                    'type': self.RedisMetaDataType.TAG,
+                    # 'separator': '|'
+                },
+            ],
+        )
+
+        # TODO should this call from_existing_index if connecting to
+        # a redis instance that already contains data?
+
+        self.logger.info('Loading HuggingFace embeddings')
+
+        # TODO: Research different embeddings
+        # https://python.langchain.com/docs/integrations/vectorstores/mongodb_atlas/#initialization
+
+        embeddings = HuggingFaceEmbeddings(
+            model_name='sentence-transformers/all-mpnet-base-v2'
+        )
+
+        self.logger.info('Creating Redis Vector Store')
+
+        self.vector_store = RedisVectorStore(embeddings, config=config)
+
+    def get_statement_model(self):
+        """
+        Return the statement model.
+        """
+        from langchain_core.documents import Document
+
+        return Document
+
+    def model_to_object(self, document):
+
+        in_response_to = document.page_content
+
+        # If the value is an empty string, set it to None
+        # to match the expected type (the vector store does
+        # not use null values)
+        if in_response_to == '':
+            in_response_to = None
+
+        values = {
+            'in_response_to': in_response_to,
+        }
+
+        if document.id:
+            values['id'] = document.id
+
+        values.update(document.metadata)
+
+        tags = values['tags']
+        values['tags'] = list(set(tags.split('|') if tags else []))
+
+        return StatementObject(**values)
+
+    def count(self):
+        """
+        Return the number of entries in the database.
+        """
+
+        '''
+        TODO
+        faiss_vector_store = FAISS(
+            embedding_function=embedding_function,
+            index=IndexFlatL2(embedding_size),
+            docstore=InMemoryDocstore(),
+            index_to_docstore_id={}
+        )
+        doc_count = faiss_vector_store.index.ntotal
+        '''
+
+        client = self.vector_store.index.client
+        return client.dbsize()
+
+    def remove(self, statement):
+        """
+        Removes the statement that matches the input text.
+        Removes any responses from statements where the response text matches
+        the input text.
+        """
+        self.vector_store.delete(ids=[statement.id.split(':')[1]])
+
+    def filter(self, page_size=4, **kwargs):
+        """
+        Returns a list of objects from the database.
+        The kwargs parameter can contain any number
+        of attributes. Only objects which contain all
+        listed attributes and in which all values match
+        for all listed attributes will be returned.
+
+        kwargs:
+            - conversation
+            - persona
+            - tags
+            - in_response_to
+            - text
+            - exclude_text
+            - exclude_text_words
+            - persona_not_startswith
+            - search_in_response_to_contains
+            - order_by
+        """
+        from redisvl.query.filter import Tag, Text
+
+        # https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/query_syntax/
+        filter_condition = None
+
+        if 'in_response_to' in kwargs:
+            filter_condition = Text('in_response_to') == kwargs['in_response_to']
+
+        if 'conversation' in kwargs:
+            query = Tag('conversation') == kwargs['conversation']
+            if filter_condition:
+                filter_condition &= query
+            else:
+                filter_condition = query
+
+        if 'persona' in kwargs:
+            query = Tag('persona') == kwargs['persona']
+            if filter_condition:
+                filter_condition &= query
+            else:
+                filter_condition = query
+
+        if 'tags' in kwargs:
+            query = Tag('tags') == kwargs['tags']
+            if filter_condition:
+                filter_condition &= query
+            else:
+                filter_condition = query
+
+        if 'exclude_text' in kwargs:
+            query = Text('text') != '|'.join([
+                f'%%{text}%%' for text in kwargs['exclude_text']
+            ])
+            if filter_condition:
+                filter_condition &= query
+            else:
+                filter_condition = query
+
+        if 'exclude_text_words' in kwargs:
+            _query = '|'.join([
+                f'%%{text}%%' for text in kwargs['exclude_text_words']
+            ])
+            query = Text('text') % f'-({ _query })'
+            if filter_condition:
+                filter_condition &= query
+            else:
+                filter_condition = query
+
+        if 'persona_not_startswith' in kwargs:
+            _query = _escape_redis_special_characters(kwargs['persona_not_startswith'])
+            query = Text('persona') % f'-(%%{_query}%%)'
+            if filter_condition:
+                filter_condition &= query
+            else:
+                filter_condition = query
+
+        if 'text' in kwargs:
+            _query = _escape_redis_special_characters(kwargs['text'])
+            query = Text('text') % '|'.join([f'%%{_q}%%' for _q in _query.split()])
+            if filter_condition:
+                filter_condition &= query
+            else:
+                filter_condition = query
+
+        ordering = kwargs.get('order_by', None)
+
+        if ordering:
+            ordering = ','.join(ordering)
+
+        if 'search_in_response_to_contains' in kwargs:
+            _search_text = kwargs.get('search_in_response_to_contains', '')
+
+            # TODO similarity_search_with_score
+            documents = self.vector_store.similarity_search(
+                _search_text,
+                k=page_size,  # The number of results to return
+                return_all=True,  # Include the full document with IDs
+                filter=filter_condition,
+                sort_by=ordering
+            )
+        else:
+            documents = self.vector_store.query_search(
+                k=page_size,
+                filter=filter_condition,
+                sort_by=ordering
+            )
+
+        return [self.model_to_object(document) for document in documents]
+
+    def create(
+        self,
+        text,
+        in_response_to=None,
+        tags=None,
+        **kwargs
+    ):
+        """
+        Creates a new statement matching the keyword arguments specified.
+        Returns the created statement.
+        """
+        # from langchain_community.vectorstores.redis.constants import REDIS_TAG_SEPARATOR
+
+        _default_date = datetime.now()
+
+        metadata = {
+            'text': text,
+            'category': kwargs.get('category', ''),
+            # NOTE: `created_at` must have a valid numeric value or results will
+            # not be returned for similarity_search for some reason
+            'created_at': kwargs.get('created_at') or int(_default_date.strftime('%y%m%d')),
+            'tags': '|'.join(tags) if tags else '',
+            'conversation': kwargs.get('conversation', ''),
+            'persona': kwargs.get('persona', ''),
+        }
+
+        ids = self.vector_store.add_texts([in_response_to or ''], [metadata])
+
+        metadata['created_at'] = _default_date
+        metadata['tags'] = tags or []
+        metadata.pop('text')
+        statement = StatementObject(
+            id=ids[0],
+            text=text,
+            **metadata
+        )
+        return statement
+
+    def create_many(self, statements):
+        """
+        Creates multiple statement entries.
+        """
+        Document = self.get_statement_model()
+        documents = [
+            Document(
+                page_content=statement.in_response_to or '',
+                metadata={
+                    'text': statement.text,
+                    'conversation': statement.conversation or '',
+                    'created_at': int(statement.created_at.strftime('%y%m%d')),
+                    'persona': statement.persona or '',
+                    'tags': '|'.join(statement.tags) if statement.tags else '',
+                }
+            ) for statement in statements
+        ]
+
+        self.logger.info('Adding documents to the vector store')
+
+        self.vector_store.add_documents(documents)
+
+    def update(self, statement):
+        """
+        Modifies an entry in the database.
+        Creates an entry if one does not exist.
+        """
+        metadata = {
+            'text': statement.text,
+            'conversation': statement.conversation or '',
+            'created_at': int(statement.created_at.strftime('%y%m%d')),
+            'persona': statement.persona or '',
+            'tags': '|'.join(statement.tags) if statement.tags else '',
+        }
+
+        Document = self.get_statement_model()
+        document = Document(
+            page_content=statement.in_response_to or '',
+            metadata=metadata,
+        )
+
+        if statement.id:
+            self.vector_store.add_texts(
+                [document.page_content], [metadata], keys=[statement.id.split(':')[1]]
+            )
+        else:
+            self.vector_store.add_documents([document])
+
+    def get_random(self):
+        """
+        Returns a random statement from the database.
+        """
+        client = self.vector_store.index.client
+
+        random_key = client.randomkey()
+
+        if random_key:
+            random_id = random_key.decode().split(':')[1]
+
+            documents = self.vector_store.get_by_ids([random_id])
+
+            if documents:
+                return self.model_to_object(documents[0])
+        
+        raise self.EmptyDatabaseException()
+
+    def drop(self):
+        """
+        Remove all existing documents from the database.
+        """
+        index_name = self.vector_store.config.index_name
+        client = self.vector_store.index.client
+
+        for key in client.scan_iter(f'{index_name}:*'):
+            # self.vector_store.index.drop_keys(key)
+            client.delete(key)
+
+        # Commenting this out for now because there is no step
+        # to recreate the index after it is dropped (really what
+        # we want is to delete all the keys in the index, but
+        # keep the index itself)
+        # self.vector_store.index.delete(drop=True)