Experimental LLM support (gunthercox#2407)

* Add experimental LLM support via Ollama

* Add documentation

* Better support streaming response

* Use streaming response in example

* Update documentation and examples

* Note design considerations

* Update diagram

* Update intersphinx links

* Add designated classes for LLM clients

Author: gunthercox

chatterbot/__init__.py

@@ -4,7 +4,7 @@
 from .chatterbot import ChatBot
 
 
-__version__ = '1.2.6'
+__version__ = '1.2.7'
 
 __all__ = (
     'ChatBot',

chatterbot/chatterbot.py

@@ -40,11 +40,21 @@ class ChatBot(object):
 
     :param logger: A ``Logger`` object.
     :type logger: logging.Logger
+
+    :param model: A definition used to load a large language model.
+                  Defaults to ``None``.
+                  (Added in version 1.2.7)
+    :type model: dict
+
+    :param stream: Return output as a streaming responses when a ``model`` is defined.
+                   (Added in version 1.2.7)
     """
 
-    def __init__(self, name, **kwargs):
+    def __init__(self, name, stream=False, **kwargs):
         self.name = name
 
+        self.stream = stream
+
         self.logger = kwargs.get('logger', logging.getLogger(__name__))
 
         storage_adapter = kwargs.get('storage_adapter', 'chatterbot.storage.SQLStorageAdapter')
@@ -112,6 +122,11 @@ def __init__(self, name, **kwargs):
         # NOTE: 'xx' is the language code for a multi-language model
         self.nlp = spacy.blank(self.tagger.language.ISO_639_1)
 
+        self.model = None
+        if model := kwargs.get('model'):
+            import_path = model.pop('client')
+            self.model = utils.initialize_class(import_path, self, **model)
+
         # Allow the bot to save input it receives so that it can learn
         self.read_only = kwargs.get('read_only', False)
 
@@ -185,6 +200,10 @@ def get_response(self, statement=None, **kwargs) -> Statement:
             additional_response_selection_parameters
         )
 
+        # If streaming is enabled return the response immediately
+        if self.stream:
+            return response
+
         # Update any response data that needs to be changed
         if persist_values_to_response:
             for response_key in persist_values_to_response:
@@ -219,6 +238,12 @@ def generate_response(self, input_statement, additional_response_selection_param
         result = None
         max_confidence = -1
 
+        # If a model is provided, use it to process the input statement
+        # instead of the logic adapters
+        if self.model:
+            model_response = self.model.process(input_statement)
+            return model_response
+
         for adapter in self.logic_adapters:
             if adapter.can_process(input_statement):
 

chatterbot/llm.py

@@ -0,0 +1,145 @@
+"""
+Large Language Model (LLM) clients.
+
+    .. note::
+        As a part of the development process when choosing models it is
+        important to research and understand the models you are using.
+
+        A good example of why this is important can be found in the
+        description of the Phi-3 model from Microsoft which discusses
+        responsible AI considerations such as the limitations of the
+        model, and appropriate use cases.
+        https://huggingface.co/microsoft/Phi-3-mini-4k-instruct-gguf#responsible-ai-considerations
+"""
+
+
+class ModelClient:
+    """
+    A base class to define the interface for language model clients.
+    """
+
+    def __init__(self, chatbot, model: str, **kwargs):
+        self.chatbot = chatbot
+        self.model = model
+
+
+class Ollama(ModelClient):
+    """
+    This client class allows the use of Ollama models for chatbot responses.
+
+    .. warning::
+        This is a new and experimental class. It may not work as expected
+        and its functionality may change in future releases.
+
+    .. note::
+        Added in version 1.2.7
+    """
+
+    def __init__(self, chatbot, model: str, **kwargs):
+        """
+        keyword arguments:
+            host: The host URL for the Ollama server.
+                Default is 'http://localhost:11434'.
+        """
+        super().__init__(chatbot, model)
+        from ollama import Client, AsyncClient
+
+        self.host = kwargs.get('host', 'http://localhost:11434')
+
+        # TODO: Look into supporting the async client
+        self.async_mode = False
+
+        # https://github.com/ollama/ollama-python
+        if self.async_mode:
+            self.client = AsyncClient(
+                host=self.host,
+            )
+        else:
+            self.client = Client(
+                host=self.host,
+            )
+
+    def process(self, statement):
+
+        system_message = {
+            'role': 'system',
+            'content': 'Please keep responses short and concise.'
+        }
+        message = {
+            'role': 'user',
+            'content': statement.text
+        }
+
+        if self.chatbot.stream:
+            for part in self.client.chat(
+                model=self.model,
+                messages=[system_message, message],
+                stream=True
+            ):
+                yield part['message']['content']
+        else:
+            response = self.client.chat(
+                model=self.model,
+                messages=[system_message, message]
+            )
+
+            return response.message.content
+
+
+class OpenAI(ModelClient):
+    """
+    This client class allows the use of the OpenAI API to generate chatbot responses.
+
+    .. warning::
+        This is a new and experimental class. It may not work as expected
+        and its functionality may change in future releases.
+
+    .. note::
+        Added in version 1.2.7
+    """
+
+    def __init__(self, chatbot, model, **kwargs):
+        super().__init__(chatbot, model, **kwargs)
+        from openai import OpenAI as OpenAIClient
+        from openai import AsyncOpenAI as AsyncOpenAIClient
+
+        self.host = kwargs.get('host', None)
+
+        # TODO: Look into supporting the async client
+        self.async_mode = False
+
+        # https://github.com/openai/openai-python
+        if self.async_mode:
+            self.client = AsyncOpenAIClient(
+                base_url=self.host,
+            )
+        else:
+            self.client = OpenAIClient(
+                base_url=self.host,
+            )
+
+    def process(self, statement):
+
+        system_message = {
+            'role': 'developer',
+            'content': 'Please keep responses short and concise.'
+        }
+        message = {
+            'role': 'user',
+            'content': statement.text
+        }
+
+        if self.chatbot.stream:
+            for part in self.client.chat.completions.create(
+                model=self.model,
+                messages=[system_message, message],
+                stream=True
+            ):
+                yield part
+        else:
+            response = self.client.chat.completions.create(
+                model=self.model,
+                messages=[system_message, message]
+            )
+
+            return response.output_text

chatterbot/logic/__init__.py

@@ -5,6 +5,7 @@
 from chatterbot.logic.time_adapter import TimeLogicAdapter
 from chatterbot.logic.unit_conversion import UnitConversion
 
+
 __all__ = (
     'LogicAdapter',
     'BestMatch',

chatterbot/utils.py

@@ -1,11 +1,12 @@
 """
 ChatterBot utility functions
 """
+from typing import Union
 import importlib
 import time
 
 
-def import_module(dotted_path):
+def import_module(dotted_path: str):
     """
     Imports the specified module based on the
     dot notated import path for the module.
@@ -17,7 +18,7 @@ def import_module(dotted_path):
     return getattr(module, module_parts[-1])
 
 
-def initialize_class(data, *args, **kwargs):
+def initialize_class(data: Union[dict, str], *args, **kwargs):
     """
     :param data: A string or dictionary containing a import_path attribute.
     """

docs/_static/dialog-processing-flow-llm.svg

@@ -1,3 +1,20 @@
+table {
+    width: 100%;
+}
+
+th.head p {
+    text-align: center;
+}
+
+.table-justified td {
+    width: 50%;
+}
+
+.caption-text {
+    padding-top: 3px;
+    padding-bottom: 3px;
+}
+
 .wy-side-nav-search {
     background-color: #300a24;
 }

docs/_static/dialog-processing-flow.svg

@@ -220,5 +220,6 @@
 
 # Configuration for intersphinx
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3', None)
+    'python': ('https://docs.python.org/3', None),
+    'mathparse': ('https://mathparse.chatterbot.us/', None),
 }

docs/_static/style.css

@@ -13,6 +13,10 @@ Glossary
    logic adapter
       An adapter class that allows a ChatBot instance to select a response to 
 
+   RAG
+      Retrieval-Augmented Generation. A method of by which a large language model
+      can retrieve information from a database or other source of information.
+
    storage adapter
       A class that allows a chat bot to store information somewhere, such as a database.
 
@@ -22,6 +26,15 @@ Glossary
       and hypothesis testing, checking occurrences or validating linguistic
       rules within a specific language territory [2]_.
 
+   large language models
+      A type of artificial intelligence model that can generate generate
+      human-like text, often trained on a significantly large corpus of
+      text data.
+
+   MCP
+      Model Context Protocol. A protocol for providing context data to a large
+      language model to enable or improve its ability to perform various tasks.
+
    preprocessors
       A member of a list of functions that can be used to modify text
       input that the chat bot receives before the text is passed to