renamed ChatAtomicFlow + readme + demo

.gitignore

@@ -1 +1,443 @@
-__pycache__/
+# Created by https://www.toptal.com/developers/gitignore/api/python,java,c++,pycharm,visualstudiocode,macos,linux,windows
+# Edit at https://www.toptal.com/developers/gitignore?templates=python,java,c++,pycharm,visualstudiocode,macos,linux,windows
+
+### C++ ###
+# Prerequisites
+*.d
+
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+
+# Fortran module files
+*.mod
+*.smod
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+*.app
+
+### Java ###
+# Compiled class file
+*.class
+
+# Log file
+*.log
+
+# BlueJ files
+*.ctxt
+
+# Mobile Tools for Java (J2ME)
+.mtj.tmp/
+
+# Package Files #
+*.jar
+*.war
+*.nar
+*.ear
+*.zip
+*.tar.gz
+*.rar
+
+# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
+hs_err_pid*
+replay_pid*
+
+### Linux ###
+*~
+
+# temporary files which can be created if a process still has a handle open of a deleted file
+.fuse_hidden*
+
+# KDE directory preferences
+.directory
+
+# Linux trash folder which might appear on any partition or disk
+.Trash-*
+
+# .nfs files are created when an open file is removed but is still being accessed
+.nfs*
+
+### macOS ###
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two \r
+Icon
+
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### PyCharm ###
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
+# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
+
+# User-specific stuff
+.idea/**/workspace.xml
+.idea/**/tasks.xml
+.idea/**/usage.statistics.xml
+.idea/**/dictionaries
+.idea/**/shelf
+
+# AWS User-specific
+.idea/**/aws.xml
+
+# Generated files
+.idea/**/contentModel.xml
+
+# Sensitive or high-churn files
+.idea/**/dataSources/
+.idea/**/dataSources.ids
+.idea/**/dataSources.local.xml
+.idea/**/sqlDataSources.xml
+.idea/**/dynamic.xml
+.idea/**/uiDesigner.xml
+.idea/**/dbnavigator.xml
+
+# Gradle
+.idea/**/gradle.xml
+.idea/**/libraries
+
+# Gradle and Maven with auto-import
+# When using Gradle or Maven with auto-import, you should exclude module files,
+# since they will be recreated, and may cause churn.  Uncomment if using
+# auto-import.
+# .idea/artifacts
+# .idea/compiler.xml
+# .idea/jarRepositories.xml
+# .idea/modules.xml
+# .idea/*.iml
+# .idea/modules
+# *.iml
+# *.ipr
+
+# CMake
+cmake-build-*/
+
+# Mongo Explorer plugin
+.idea/**/mongoSettings.xml
+
+# File-based project format
+*.iws
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Cursive Clojure plugin
+.idea/replstate.xml
+
+# SonarLint plugin
+.idea/sonarlint/
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml
+crashlytics.properties
+crashlytics-build.properties
+fabric.properties
+
+# Editor-based Rest Client
+.idea/httpRequests
+
+# Android studio 3.1+ serialized cache file
+.idea/caches/build_file_checksums.ser
+
+### PyCharm Patch ###
+# Comment Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-215987721
+
+# *.iml
+# modules.xml
+# .idea/misc.xml
+# *.ipr
+
+# Sonarlint plugin
+# https://plugins.jetbrains.com/plugin/7973-sonarlint
+.idea/**/sonarlint/
+
+# SonarQube Plugin
+# https://plugins.jetbrains.com/plugin/7238-sonarqube-community-plugin
+.idea/**/sonarIssues.xml
+
+# Markdown Navigator plugin
+# https://plugins.jetbrains.com/plugin/7896-markdown-navigator-enhanced
+.idea/**/markdown-navigator.xml
+.idea/**/markdown-navigator-enh.xml
+.idea/**/markdown-navigator/
+
+# Cache file creation bug
+# See https://youtrack.jetbrains.com/issue/JBR-2257
+.idea/$CACHE_FILE$
+
+# CodeStream plugin
+# https://plugins.jetbrains.com/plugin/12206-codestream
+.idea/codestream.xml
+
+# Azure Toolkit for IntelliJ plugin
+# https://plugins.jetbrains.com/plugin/8053-azure-toolkit-for-intellij
+.idea/**/azureSettings.xml
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+### VisualStudioCode ###
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+### VisualStudioCode Patch ###
+# Ignore all local history of files
+.history
+.ionide
+
+### Windows ###
+# Windows thumbnail cache files
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+
+# Dump file
+*.stackdump
+
+# Folder config file
+[Dd]esktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Windows Installer files
+*.cab
+*.msi
+*.msix
+*.msm
+*.msp
+
+# Windows shortcuts
+*.lnk
+
+# End of https://www.toptal.com/developers/gitignore/api/python,java,c++,pycharm,visualstudiocode,macos,linux,windows
+
+.*
+flow_modules/

OpenAIChatAtomicFlow.py → ChatAtomicFlow.py

@@ -17,7 +17,78 @@ from flows.backends.llm_lite import LiteLLMBackend
 log = logging.get_logger(__name__)
 
 
-class OpenAIChatAtomicFlow(AtomicFlow):
+class ChatAtomicFlow(AtomicFlow):
+    """ This class implements a ChatAtomicFlow. It is a flow that uses a LLM via an API to generate textuals responses to textual inputs.
+    It employs litellm as a backend to query the LLM via an API. See litellm's supported models and APIs here: https://docs.litellm.ai/docs/providers
+    
+    *Configuration Parameters*:
+    
+    - `name` (str): The name of the flow. This name is used to identify the flow in the logs. Default: "ChatAtomicFlow"
+    - `description` (str): A description of the flow. This description is used to generate the help message of the flow. 
+    Default: "Flow which uses as tool an LLM though an API"
+    - `enable_cache` (bool): Whether to enable cache for this flow. Default: True
+    - `n_api_retries` (int): The number of times to retry the API call in case of failure. Default: 6
+    - `wait_time_between_retries` (int): The number of seconds to wait between each API call when the call fails. Default: 20
+    - `system_name` (str): The name of the system (roles of LLM). Default: "system"
+    - `user_name` (str): The name of the user (roles of LLM). Default: "user"
+    - `assistant_name` (str): The name of the assistant (roles of LLM). Default: "assistant"
+    - `backend` Dict[str,Any]: The backend of the flow. Used to call models via an API.
+    See litellm's supported models and APIs here: https://docs.litellm.ai/docs/providers.
+    The default parameters of the backend are all defined at flows.backends.llm_lite.LiteLLMBackend
+    (also see the defaul parameters of litellm's completion parameters: https://docs.litellm.ai/docs/completion/input#input-params-1).
+    Except for the following parameters who are overwritten by the ChatAtomicFlow in ChatAtomicFlow.yaml:
+        - `model_name` (Union[Dict[str,str],str]): The name of the model to use. 
+        When using multiple API providers, the model_name can be a dictionary of the form 
+        {"provider_name": "model_name"}. E.g. {"openai": "gpt-3.5-turbo", "azure": "azure/gpt-3.5-turbo"}
+        Default: "gpt-3.5-turbo" (the name needs to follow the name of the model in litellm  https://docs.litellm.ai/docs/providers).
+        - `n` (int) : The number of answers to generate. Default: 1
+        - `max_tokens` (int): The maximum number of tokens to generate. Default: 2000
+        - `temperature` float: The temperature of the generation. Default: 0.3
+        - `top_p` float: An alternative to sampling with temperature. It instructs the model to consider the results of
+        the tokens with top_p probability. Default: 0.2
+        - `frequency_penalty` (number): It is used to penalize new tokens based on their frequency in the text so far. Default: 0.0
+        - `presence_penalty` (number): It is used to penalize new tokens based on their existence in the text so far. Default: 0.0
+        - `stream` (bool): Whether to stream the response or not. Default: True
+    - `system_message_prompt_template` (Dict[str,Any]): The template of the system message. It is used to generate the system message. 
+    By default its of type flows.prompt_template.JinjaPrompt.
+    None of the parameters of the prompt are defined by default and therefore need to be defined if one wants to use the system prompt. 
+    Default parameters are defined in flows.prompt_template.jinja2_prompts.JinjaPrompt.
+    - `init_human_message_prompt_template` (Dict[str,Any]): The prompt template of the human/user message used to initialize the conversation
+    (first time in). It is used to generate the human message. It's passed as the user message to the LLM.
+    By default its of type flows.prompt_template.JinjaPrompt. None of the parameters of the prompt are defined by default and therefore need to be defined if one
+    wants to use the init_human_message_prompt_template. Default parameters are defined in flows.prompt_template.jinja2_prompts.JinjaPrompt.
+    - `human_message_prompt_template` (Dict[str,Any]): The prompt template of the human/user message (message used everytime the except the first time in).
+    It's passed as the user message to the LLM. By default its of type flows.prompt_template.JinjaPrompt and has the following parameters:
+        - `template` (str): The template of the human message. Default: see ChatAtomicFlow.yaml for the default value.
+        - `input_variables` (List[str]): The input variables of the human message prompt template. Default: ["query"]
+    - `previous_messages` (Dict[str,Any]): Defines which previous messages to include in the input of the LLM. Note that if `first_k`and `last_k` are both none,
+    all the messages of the flows's history are added to the input of the LLM. Default:
+        - `first_k` (int): If defined, adds the first_k earliest messages of the flow's chat history to the input of the LLM. Default: None
+        - `last_k` (int): If defined, adds the last_k latest messages of the flow's chat history to the input of the LLM. Default: None
+        
+    
+    *Input Interface Initialized (Expected input the first time in flow)*:
+    
+    - `query` (str): The query given to the flow. (e.g. {"query":"What's the capital of Switzerland?"})
+    
+    *Input Interface (Expected input the after the first time in flow)*:
+        
+    - `query` (str): The query given to the flow. (e.g. {"query": "Are you sure of your answer?"})
+        
+    *Output Interface*:
+    
+    - `api_output` (str): The output of the API call. It is the response of the LLM to the input. (e.g. {"api_output": "The Capital of Switzerland is Bern"})
+        
+    :param system_message_prompt_template: The template of the system message. It is used to generate the system message.
+    :type system_message_prompt_template: JinjaPrompt
+    :param human_message_prompt_template: The template of the human message. It is used to generate the human message.
+    :type human_message_prompt_template: JinjaPrompt
+    :param init_human_message_prompt_template: The template of the human message that is used to initialize the conversation (first time in). It is used to generate the human message.
+    :type init_human_message_prompt_template: Optional[JinjaPrompt]
+    :param backend: The backend of the flow. It is a LLM that is queried via an API. See litellm's supported models and APIs here: https://docs.litellm.ai/docs/providers
+    :type backend: LiteLLMBackend
+    :param \**kwargs: Additional arguments to pass to the flow. See :class:`flows.base_flows.AtomicFlow` for more details.
+    """
     REQUIRED_KEYS_CONFIG = ["backend"]
 
     SUPPORTS_CACHING: bool = True
@@ -46,11 +117,19 @@ class OpenAIChatAtomicFlow(AtomicFlow):
         ], f"Flow name '{self.flow_config['name']}' cannot be 'system', 'user' or 'assistant'"
 
     def set_up_flow_state(self):
+        """ This method sets up the state of the flow and clears the previous messages."""
         super().set_up_flow_state()
         self.flow_state["previous_messages"] = []
 
     @classmethod
     def _set_up_prompts(cls, config):
+        """ This method sets up the prompts of the flow. It instantiates the prompt templates.
+        
+        :param config: The configuration of the flow.
+        :type config: Dict[str, Any]
+        :return: The instantiated prompts of the flow.
+        :rtype: Dict[str, Any]
+        """
         kwargs = {}
         
         kwargs["system_message_prompt_template"] = \
@@ -64,6 +143,13 @@ class OpenAIChatAtomicFlow(AtomicFlow):
     
     @classmethod
     def _set_up_backend(cls, config):
+        """ This method sets up the backend of the flow. It instantiates the backend.
+        
+        :param config: The configuration of the flow.
+        :type config: Dict[str, Any]
+        :return: The instantiated backend of the flow.
+        :rtype: Dict[str, Any]
+        """
         kwargs = {}
 
         kwargs["backend"] = \
@@ -73,6 +159,13 @@ class OpenAIChatAtomicFlow(AtomicFlow):
 
     @classmethod
     def instantiate_from_config(cls, config):
+        """ This method instantiates the flow from a configuration file
+        
+        :param config: The configuration of the flow.
+        :type config: Dict[str, Any]
+        :return: The instantiated flow.
+        :rtype: ChatAtomicFlow
+        """
         flow_config = deepcopy(config)
 
         kwargs = {"flow_config": flow_config}
@@ -85,12 +178,22 @@ class OpenAIChatAtomicFlow(AtomicFlow):
         return cls(**kwargs)
 
     def _is_conversation_initialized(self):
+        """ This method checks if the conversation is initialized or not.
+        
+        :return: True if the conversation is initialized, False otherwise.
+        :rtype: bool
+        """
         if len(self.flow_state["previous_messages"]) > 0:
             return True
 
         return False
 
     def get_interface_description(self):
+        """ This method returns the description of the flow's input and output interface.
+        
+        :return: The description of the flow's interface.
+        :rtype: Dict[str, Any]
+        """
         if self._is_conversation_initialized():
 
             return {"input": self.flow_config["input_interface_initialized"],
@@ -101,19 +204,26 @@ class OpenAIChatAtomicFlow(AtomicFlow):
 
     @staticmethod
     def _get_message(prompt_template, input_data: Dict[str, Any]):
+        """ This method generates a message using a prompt template and input data which should contain the input variables of the prompt template.
+        
+        :param prompt_template: The prompt template.
+        :type prompt_template: JinjaPrompt
+        :param input_data: The input data of the prompt template.
+        :type input_data: Dict[str, Any]
+        :return: The generated message.
+        """
         template_kwargs = {}
         for input_variable in prompt_template.input_variables:
             template_kwargs[input_variable] = input_data[input_variable]
         msg_content = prompt_template.format(**template_kwargs)
         return msg_content
 
-    def _get_demonstration_query_message_content(self, sample_data: Dict):
-        input_variables = self.init_human_message_prompt_template.input_variables
-        return self.init_human_message_prompt_template.format(**{k: sample_data[k] for k in input_variables})
-
-
     def _add_demonstrations(self, input_data: Dict[str, Any]):
+        """ This method adds demonstrations to the flow (If any). The demonstrations should be passed from a DemonstrationFlow
         
+        :param input_data: The input data of the flow.
+        :type input_data: Dict[str, Any]
+        """
         for demonstration in input_data.get("demonstrations",[]):
             query = demonstration["query"]
             response = demonstration["response"]
@@ -127,7 +237,13 @@ class OpenAIChatAtomicFlow(AtomicFlow):
     def _state_update_add_chat_message(self,
                                        role: str,
                                        content: str) -> None:
-
+        """ This method adds a message to the flow's state.
+        
+        :param role: The role of the message (e.g. "user", "assistant", "system").
+        :type role: str
+        :param content: The content of the message.
+        :type content: str
+        """
 
         acceptable_roles = [self.flow_config["system_name"],self.flow_config["user_name"],self.flow_config["assistant_name"]]
         if role in acceptable_roles:
@@ -149,6 +265,12 @@ class OpenAIChatAtomicFlow(AtomicFlow):
         self._log_message(chat_message)
 
     def _get_previous_messages(self):
+        """ This method returns the previous messages of the flow. If first_k is set, it returns the first k messages. If last_k is set, it returns the last k messages.
+        If both are set, it returns the first k messages and the last k messages. If none are set, it returns all the messages.
+        
+        :return: The previous messages of the flow.
+        :rtype: List[Dict[str, Any]]
+        """
         all_messages = self.flow_state["previous_messages"]
         first_k = self.flow_config["previous_messages"]["first_k"]
         last_k = self.flow_config["previous_messages"]["last_k"]
@@ -162,7 +284,11 @@ class OpenAIChatAtomicFlow(AtomicFlow):
         return all_messages[-last_k:]
 
     def _call(self):
-         
+        """ This method calls the backend of the flow (so queries the LLM). It calls the backend with the previous messages of the flow.
+        
+        :return: The output of the backend.
+        :rtype: Any
+        """
         messages = self._get_previous_messages()
         _success = False
         attempts = 1
@@ -193,6 +319,11 @@ class OpenAIChatAtomicFlow(AtomicFlow):
         return response
 
     def _initialize_conversation(self, input_data: Dict[str, Any]):
+        """ This method initializes the conversation (occurs the first time in). It adds the system message and potentially the demonstrations (if any).
+        
+        :param input_data: The input data of the flow.
+        :type input_data: Dict[str, Any]
+        """
         # ~~~ Add the system message ~~~
         system_message_content = self._get_message(self.system_message_prompt_template, input_data)
 
@@ -203,6 +334,12 @@ class OpenAIChatAtomicFlow(AtomicFlow):
         self._add_demonstrations(input_data)
 
     def _process_input(self, input_data: Dict[str, Any]):
+        """ This method processes the input of the flow. It adds the human message to the flow's state. If the conversation is not initialized, it also initializes it
+        (adding the system message and potentially the demonstrations).
+        
+        :param input_data: The input data of the flow.
+        :type input_data: Dict[str, Any]
+        """
         if self._is_conversation_initialized():
             # Construct the message using the human message prompt template
             user_message_content = self._get_message(self.human_message_prompt_template, input_data)
@@ -219,8 +356,15 @@ class OpenAIChatAtomicFlow(AtomicFlow):
         self._state_update_add_chat_message(role=self.flow_config["user_name"],
                                             content=user_message_content)
 
-    def run(self,
-            input_data: Dict[str, Any]) -> Dict[str, Any]:
+    def run(self,input_data: Dict[str, Any]):
+        """ This method runs the flow. It processes the input, calls the backend and updates the state of the flow.
+        
+        :param input_data: The input data of the flow.
+        :type input_data: Dict[str, Any]
+        :return: The LLM's api output.
+        :rtype: Dict[str, Any]
+        """
+        
         # ~~~ Process input ~~~
         self._process_input(input_data)
 

OpenAIChatAtomicFlow.yaml → ChatAtomicFlow.yaml

@@ -1,4 +1,6 @@
 # This is an abstract flow, therefore some required fields are not defined (and must be defined by the concrete flow)
+name: ChatAtomicFlow
+description: "Flow which uses as tool an LLM though an API"
 enable_cache: True
 
 n_api_retries: 6
@@ -46,8 +48,5 @@ previous_messages:
   first_k: null  # Note that the first message is the system prompt
   last_k: null
 
-demonstrations: null
-demonstrations_response_template: null
-
 output_interface:
   - "api_output"

README.md

@@ -1,26 +1,156 @@
 ---
 license: mit
 ---
-(TODO)
 
-## Description
+# Table of Contents
 
-< Flow description >
+* [ChatAtomicFlow](#ChatAtomicFlow)
+  * [ChatAtomicFlow](#ChatAtomicFlow.ChatAtomicFlow)
+    * [set\_up\_flow\_state](#ChatAtomicFlow.ChatAtomicFlow.set_up_flow_state)
+    * [instantiate\_from\_config](#ChatAtomicFlow.ChatAtomicFlow.instantiate_from_config)
+    * [get\_interface\_description](#ChatAtomicFlow.ChatAtomicFlow.get_interface_description)
+    * [run](#ChatAtomicFlow.ChatAtomicFlow.run)
 
-## Configuration parameters
+<a id="ChatAtomicFlow"></a>
 
-&lt; Name 1 &gt; (&lt; Type 1 &gt;): &lt; Description 1 &gt;. Required parameter.
+# ChatAtomicFlow
 
-&lt; Name 2 &gt; (&lt; Type 2 &gt;): &lt; Description 2 &gt;. Default value is: &lt; value 2 &gt;
+<a id="ChatAtomicFlow.ChatAtomicFlow"></a>
 
-## Input interface
+## ChatAtomicFlow Objects
 
-&lt; Name 1 &gt; (&lt; Type 1 &gt;): &lt; Description 1 &gt;. 
+```python
+class ChatAtomicFlow(AtomicFlow)
+```
 
-(Note that the interface might depend on the state of the Flow.)
+This class implements a ChatAtomicFlow. It is a flow that uses a LLM via an API to generate textuals responses to textual inputs.
 
-## Output interface
+It employs litellm as a backend to query the LLM via an API. See litellm's supported models and APIs here: https://docs.litellm.ai/docs/providers
 
-&lt; Name 1 &gt; (&lt; Type 1 &gt;): &lt; Description 1 &gt;. 
+*Configuration Parameters*:
+
+- `name` (str): The name of the flow. This name is used to identify the flow in the logs. Default: "ChatAtomicFlow"
+- `description` (str): A description of the flow. This description is used to generate the help message of the flow. 
+Default: "Flow which uses as tool an LLM though an API"
+- `enable_cache` (bool): Whether to enable cache for this flow. Default: True
+- `n_api_retries` (int): The number of times to retry the API call in case of failure. Default: 6
+- `wait_time_between_retries` (int): The number of seconds to wait between each API call when the call fails. Default: 20
+- `system_name` (str): The name of the system (roles of LLM). Default: "system"
+- `user_name` (str): The name of the user (roles of LLM). Default: "user"
+- `assistant_name` (str): The name of the assistant (roles of LLM). Default: "assistant"
+- `backend` Dict[str,Any]: The backend of the flow. Used to call models via an API.
+See litellm's supported models and APIs here: https://docs.litellm.ai/docs/providers.
+The default parameters of the backend are all defined at flows.backends.llm_lite.LiteLLMBackend
+(also see the defaul parameters of litellm's completion parameters: https://docs.litellm.ai/docs/completion/input#input-params-1).
+Except for the following parameters who are overwritten by the ChatAtomicFlow in ChatAtomicFlow.yaml:
+    - `model_name` (Union[Dict[str,str],str]): The name of the model to use. 
+    When using multiple API providers, the model_name can be a dictionary of the form 
+    {"provider_name": "model_name"}. E.g. {"openai": "gpt-3.5-turbo", "azure": "azure/gpt-3.5-turbo"}
+    Default: "gpt-3.5-turbo" (the name needs to follow the name of the model in litellm  https://docs.litellm.ai/docs/providers).
+    - `n` (int) : The number of answers to generate. Default: 1
+    - `max_tokens` (int): The maximum number of tokens to generate. Default: 2000
+    - `temperature` float: The temperature of the generation. Default: 0.3
+    - `top_p` float: An alternative to sampling with temperature. It instructs the model to consider the results of
+    the tokens with top_p probability. Default: 0.2
+    - `frequency_penalty` (number): It is used to penalize new tokens based on their frequency in the text so far. Default: 0.0
+    - `presence_penalty` (number): It is used to penalize new tokens based on their existence in the text so far. Default: 0.0
+    - `stream` (bool): Whether to stream the response or not. Default: True
+- `system_message_prompt_template` (Dict[str,Any]): The template of the system message. It is used to generate the system message. 
+By default its of type flows.prompt_template.JinjaPrompt.
+None of the parameters of the prompt are defined by default and therefore need to be defined if one wants to use the system prompt. 
+Default parameters are defined in flows.prompt_template.jinja2_prompts.JinjaPrompt.
+- `init_human_message_prompt_template` (Dict[str,Any]): The prompt template of the human/user message used to initialize the conversation
+(first time in). It is used to generate the human message. It's passed as the user message to the LLM.
+By default its of type flows.prompt_template.JinjaPrompt. None of the parameters of the prompt are defined by default and therefore need to be defined if one
+wants to use the init_human_message_prompt_template. Default parameters are defined in flows.prompt_template.jinja2_prompts.JinjaPrompt.
+- `human_message_prompt_template` (Dict[str,Any]): The prompt template of the human/user message (message used everytime the except the first time in).
+It's passed as the user message to the LLM. By default its of type flows.prompt_template.JinjaPrompt and has the following parameters:
+    - `template` (str): The template of the human message. Default: see ChatAtomicFlow.yaml for the default value.
+    - `input_variables` (List[str]): The input variables of the human message prompt template. Default: ["query"]
+- `previous_messages` (Dict[str,Any]): Defines which previous messages to include in the input of the LLM. Note that if `first_k`and `last_k` are both none,
+all the messages of the flows's history are added to the input of the LLM. Default:
+    - `first_k` (int): If defined, adds the first_k earliest messages of the flow's chat history to the input of the LLM. Default: None
+    - `last_k` (int): If defined, adds the last_k latest messages of the flow's chat history to the input of the LLM. Default: None
+
+
+*Input Interface Initialized (Expected input the first time in flow)*:
+
+- `query` (str): The query given to the flow. (e.g. {"query":"What's the capital of Switzerland?"})
+
+*Input Interface (Expected input the after the first time in flow)*:
+
+- `query` (str): The query given to the flow. (e.g. {"query": "Are you sure of your answer?"})
+
+*Output Interface*:
+
+- `api_output` (str): The output of the API call. It is the response of the LLM to the input. (e.g. {"api_output": "The Capital of Switzerland is Bern"})
+
+**Arguments**:
+
+- `system_message_prompt_template` (`JinjaPrompt`): The template of the system message. It is used to generate the system message.
+- `human_message_prompt_template` (`JinjaPrompt`): The template of the human message. It is used to generate the human message.
+- `init_human_message_prompt_template` (`Optional[JinjaPrompt]`): The template of the human message that is used to initialize the conversation (first time in). It is used to generate the human message.
+- `backend` (`LiteLLMBackend`): The backend of the flow. It is a LLM that is queried via an API. See litellm's supported models and APIs here: https://docs.litellm.ai/docs/providers
+- `\**kwargs`: Additional arguments to pass to the flow. See :class:`flows.base_flows.AtomicFlow` for more details.
+
+<a id="ChatAtomicFlow.ChatAtomicFlow.set_up_flow_state"></a>
+
+#### set\_up\_flow\_state
+
+```python
+def set_up_flow_state()
+```
+
+This method sets up the state of the flow and clears the previous messages.
+
+<a id="ChatAtomicFlow.ChatAtomicFlow.instantiate_from_config"></a>
+
+#### instantiate\_from\_config
+
+```python
+@classmethod
+def instantiate_from_config(cls, config)
+```
+
+This method instantiates the flow from a configuration file
+
+**Arguments**:
+
+- `config` (`Dict[str, Any]`): The configuration of the flow.
+
+**Returns**:
+
+`ChatAtomicFlow`: The instantiated flow.
+
+<a id="ChatAtomicFlow.ChatAtomicFlow.get_interface_description"></a>
+
+#### get\_interface\_description
+
+```python
+def get_interface_description()
+```
+
+This method returns the description of the flow's input and output interface.
+
+**Returns**:
+
+`Dict[str, Any]`: The description of the flow's interface.
+
+<a id="ChatAtomicFlow.ChatAtomicFlow.run"></a>
+
+#### run
+
+```python
+def run(input_data: Dict[str, Any])
+```
+
+This method runs the flow. It processes the input, calls the backend and updates the state of the flow.
+
+**Arguments**:
+
+- `input_data` (`Dict[str, Any]`): The input data of the flow.
+
+**Returns**:
+
+`Dict[str, Any]`: The LLM's api output.
 
-(Note that the interface might depend on the state of the Flow.)

__init__.py

@@ -1 +1 @@
-from .OpenAIChatAtomicFlow import OpenAIChatAtomicFlow
+from .ChatAtomicFlow import ChatAtomicFlow

simpleQA.yaml → demo.yaml

@@ -8,8 +8,8 @@ output_interface:  # Connector between the Flow's output and the caller
   keys_to_rename:
     api_output: answer  # Rename the api_output to answer
 
-flow:  # Overrides the OpenAIChatAtomicFlow config
-  _target_: aiflows.OpenAIChatFlowModule.OpenAIChatAtomicFlow.instantiate_from_default_config
+flow:  # Overrides the ChatAtomicFlow config
+  _target_: aiflows.ChatFlowModule.ChatAtomicFlow.instantiate_from_default_config
 
   name: "SimpleQA_Flow"
   description: "A flow that answers questions."
@@ -18,34 +18,39 @@ flow:  # Overrides the OpenAIChatAtomicFlow config
   input_interface_non_initialized:
     - "question"
 
-  # ~~~ OpenAI model parameters ~~
-  model: "gpt-3.5-turbo"
-  generation_parameters:
+  # ~~~ backend model parameters ~~
+  backend:
+    _target_: flows.backends.llm_lite.LiteLLMBackend
+    api_infos: ???
+    model_name: 
+      openai: "gpt-3.5-turbo"
+      azure: "azure/gpt-4"
+    
+    # ~~~ generation_parameters ~~
     n: 1
     max_tokens: 3000
     temperature: 0.3
 
-    model_kwargs:
-      top_p: 0.2
-      frequency_penalty: 0
-      presence_penalty: 0
+    top_p: 0.2
+    frequency_penalty: 0
+    presence_penalty: 0
 
   n_api_retries: 6
   wait_time_between_retries: 20
 
   # ~~~ Prompt specification ~~~
   system_message_prompt_template:
-    _target_: langchain.PromptTemplate
+    _target_: flows.prompt_template.JinjaPrompt
     template: |2-
       You are a helpful chatbot that truthfully answers questions.
     input_variables: []
     partial_variables: {}
-    template_format: jinja2
+ 
 
   init_human_message_prompt_template:
-    _target_: langchain.PromptTemplate
+    _target_: flows.prompt_template.JinjaPrompt
     template: |2-
       Answer the following question: {{question}}
     input_variables: ["question"]
     partial_variables: {}
-    template_format: jinja2
+

pip_requirements.py

@@ -1 +0,0 @@
-# ToDo

run.py

@@ -16,7 +16,7 @@ CACHING_PARAMETERS.do_caching = False  # Set to True in order to disable caching
 logging.set_verbosity_debug()
 
 dependencies = [
-    {"url": "aiflows/OpenAIChatFlowModule", "revision": os.getcwd()},
+    {"url": "aiflows/ChatFlowModule", "revision": os.getcwd()},
 ]
 from flows import flow_verse
 flow_verse.sync_dependencies(dependencies)
@@ -35,12 +35,11 @@ if __name__ == "__main__":
     #                           api_version =  os.getenv("AZURE_API_VERSION") )
 
     root_dir = "."
-    cfg_path = os.path.join(root_dir, "SimpleQA.yaml")
+    cfg_path = os.path.join(root_dir, "demo.yaml")
     cfg = read_yaml_file(cfg_path)
 
     cfg["flow"]["backend"]["api_infos"] = api_information
     # ~~~ Instantiate the Flow ~~~
-    # ~~~ Instantiate the Flow ~~~
     flow_with_interfaces = {
         "flow": hydra.utils.instantiate(cfg['flow'], _recursive_=False, _convert_="partial"),
         "input_interface": (