Merge pull request #566 from decypher-ai/rebased_develop-factcheck

Autoalign factcheck examples

Author: drazvan

examples/configs/autoalign/autoalign_factcheck_config/config.yml

@@ -1,12 +1,19 @@
 models:
   - type: main
     engine: openai
-    model: gpt-3.5-turbo
+    model: gpt-3.5-turbo-instruct
 rails:
-  config:
-    autoalign:
-      parameters:
-        fact_check_endpoint: "https://<AUTOALIGN_ENDPOINT>/factcheck"
-  output:
-    flows:
-      - autoalign factcheck output
+    config:
+        autoalign:
+            parameters:
+                fact_check_endpoint: "https://<AUTOALIGN_ENDPOINT>/factcheck"
+            output:
+                guardrails_config:
+                  {
+                      "factcheck": {
+                          "verify_response": false
+                      },
+                  }
+    output:
+        flows:
+            - autoalign factcheck output

examples/configs/autoalign/autoalign_factcheck_config/rails/factcheck.co

@@ -0,0 +1,10 @@
+define user ask about pluto
+  "What is pluto?"
+  "How many moons does pluto have?"
+  "Is pluto a planet?"
+
+define flow answer pluto question
+  user ask about pluto
+  # For pluto questions, we activate the fact checking.
+  $check_facts = True
+  bot provide pluto answer

examples/configs/autoalign/autoalign_factcheck_config/rails/general.co

@@ -0,0 +1,62 @@
+define user express greeting
+  "hi"
+  "hello"
+  "hey"
+
+define user ask name
+  "What is your name?"
+
+define user ask capabilities
+  "What can you do?"
+  "help"
+
+define bot inform capabilities
+  "I am an example bot that illustrates the fact checking and hallucination detection capabilities. Ask me about the documents in my knowledge base to test my fact checking abilities, or about other topics to test my hallucination detection."
+
+define flow capabilities
+    user ask capabilities
+    bot inform capabilities
+
+define user ask knowledge base
+    "What is in your knowledge base?"
+    "What do you know?"
+    "What can I ask you about?"
+
+define bot inform knowledge base
+    "You can ask me about anything! My knowledge base includes information about the pluto for which I have documents in knowledge base, which I can use for fact checking."
+
+define flow knowledge base
+    user ask knowledge base
+    bot inform knowledge base
+
+define user request repeat
+  "Please repeat that"
+  "repeat"
+  "What was that?"
+
+define flow
+  user express greeting
+  bot express greeting
+
+define bot offer additional help
+  "If you have any more questions or if there's anything else I can help you with, please don't hesitate to ask."
+
+define user ask general question
+  "What stocks should I buy?"
+  "Can you recommend the best stocks to buy?"
+  "Can you recommend a place to eat?"
+  "Do you know any restaurants?"
+  "Can you tell me your name?"
+  "What's your name?"
+  "Can you paint?"
+  "Can you tell me a joke?"
+  "What is the biggest city in the world"
+  "Can you write an email?"
+  "I need you to write an email for me."
+  "Who is the president?"
+  "What party will win the elections?"
+  "Who should I vote with?"
+
+define flow
+  user ask general question
+  bot provide response

nemoguardrails/library/autoalign/README.md

@@ -316,7 +316,7 @@ define bot refuse to respond
 The actions `autoalign_input_api` and `autoalign_output_api` takes in two arguments `show_autoalign_message` and
 `show_toxic_phrases`. Both the arguments expect boolean value being passed to them. The default value of
 `show_autoalign_message` is `True` and for `show_toxic_phrases` is False. The `show_autoalign_message` controls whether
-we will any output from autoalign or not. The response from AutoAlign would be presented as a subtext, when
+we will show any output from autoalign or not. The response from AutoAlign would be presented as a subtext, when
 `show_autoalign_message` is kept `True`. Details regarding the second argument can be found in `text_toxicity_extraction`
 section.
 
@@ -449,33 +449,34 @@ For text toxicity detection, the matching score has to be following format:
 Can extract toxic phrases by changing the colang file a bit:
 
 ```colang
-define flow call autoalign input
+define subflow autoalign check input
   $input_result = execute autoalign_input_api(show_autoalign_message=True, show_toxic_phrases=True)
-
   if $input_result["guardrails_triggered"]
     $autoalign_input_response = $input_result['combined_response']
     bot refuse to respond
     stop
+  else if $input_result["pii_fast"] and $input_result["pii_fast"]["guarded"]:
+    $user_message = $input_result["pii_fast"]["response"]
 
-define flow call autoalign output
+define subflow autoalign check output
   $output_result = execute autoalign_output_api(show_autoalign_message=True, show_toxic_phrases=True)
-
   if $output_result["guardrails_triggered"]
     bot refuse to respond
     stop
   else
     $pii_message_output = $output_result["pii_fast"]["response"]
     if $output_result["pii_fast"]["guarded"]
-      bot respond pii output
-      stop
-
-
-define bot respond pii output
-  "$pii_message_output"
+      $bot_message = $pii_message_output
 
+define subflow autoalign factcheck output
+  if $check_facts == True
+    $check_facts = False
+    $threshold = 0.5
+    $output_result = execute autoalign_factcheck_output_api(factcheck_threshold=$threshold, show_autoalign_message=True)
+    bot provide response
 
 define bot refuse to respond
-  "I'm sorry I can't respond."
+  "I'm sorry, I can't respond to that."
 ```
 
 
@@ -561,6 +562,12 @@ To use AutoAlign's factcheck module, you have to modify the `config.yml` in the
 rails:
   config:
     autoalign:
+      guardrails_config:
+        {
+          "factcheck":{
+            "verify_response": false
+          }
+        }
       parameters:
         fact_check_endpoint: "https://<AUTOALIGN_ENDPOINT>/factcheck"
   output:
@@ -571,28 +578,55 @@ rails:
 Specify the factcheck endpoint the parameters section of autoalign's config.
 Then, you have to call the corresponding subflows for factcheck guardrails.
 
+In the guardrails config for factcheck you can toggle "verify_response" flag
+which will enable(true) / disable (false) additional processing of LLM Response.
+This processing ensures that only relevant LLM responses undergo fact-checking
+and responses like greetings ('Hi', 'Hello' etc.) do not go through fact-checking
+process.
+
+Note that the verify_response is set to False by default as it requires additional
+computation, and we encourage users to determine which LLM responses should go through
+AutoAlign fact checking whenever possible.
+
+
 Following is the format of the colang file, which is present in the library:
 ```colang
-define flow autoalign factcheck input
-  execute autoalign_retrieve_relevant_chunks_input
-  $input_result = execute autoalign_factcheck_input_api
-
-define flow autoalign factcheck output
-  execute retrieve_relevant_chunks
-  $output_result = execute autoalign_factcheck_output_api
-  if $input_result < 0.5
-    bot inform autoalign factcheck input violation
-  if $output_result < 0.5
-    bot inform autoalign factcheck output violation
-    stop
+define subflow autoalign factcheck output
+  if $check_facts == True
+    $check_facts = False
+    $threshold = 0.5
+    $output_result = execute autoalign_factcheck_output_api(factcheck_threshold=$threshold)
+```
+
+The `threshold` can be changed depending upon the use-case, the `output_result`
+variable stores the factcheck score which can be used for further processing.
+The `show_autoalign_message` controls whether we will show any output from autoalign
+or not. The response from AutoAlign would be presented as a subtext, when
+`show_autoalign_message` is kept `True`.
 
-define bot inform autoalign factcheck input violation
-  "Factcheck input violation has been detected by AutoAlign."
+To use this flow you need to have colang file of the following format:
 
-define bot inform autoalign factcheck output violation
-  "$bot_message Factcheck output violation has been detected by AutoAlign."
+```colang
+define user ask about pluto
+  "What is pluto?"
+  "How many moons does pluto have?"
+  "Is pluto a planet?"
+
+define flow answer report question
+  user ask about pluto
+  # For pluto questions, we activate the fact checking.
+  $check_facts = True
+  bot provide report answer
 ```
 
+The above example is of a flow related to a case where the
+knowledge base is about pluto. You need to define the flow
+for use case by following the above example, this ensures that
+the fact-check takes place only for particular topics and not
+for ideal chit-chat.
+
+
+
 The output of the factcheck endpoint provides you with a factcheck score against which we can add a threshold which determines whether the given output is factually correct or not.
 
 The supporting documents or the evidence has to be placed within a `kb` folder within `config` folder.

nemoguardrails/library/autoalign/actions.py

@@ -77,6 +77,8 @@
     "intellectual_property": {"mode": "OFF"},
 }
 
+default_factcheck_config = {"factcheck": {"verify_response": False}}
+
 
 def process_autoalign_output(responses: List[Any], show_toxic_phrases: bool = False):
     """Processes the output provided AutoAlign API"""
@@ -174,16 +176,17 @@ async def autoalign_factcheck_infer(
     request_url: str,
     text: str,
     documents: List[str],
+    guardrails_config: Optional[Dict[Any, Any]] = None,
 ):
     """Checks the facts for the text using the given documents and provides a fact-checking score"""
+    factcheck_config = default_factcheck_config.copy()
     api_key = os.environ.get("AUTOALIGN_API_KEY")
     if api_key is None:
         raise ValueError("AUTOALIGN_API_KEY environment variable not set.")
     headers = {"x-api-key": api_key}
-    request_body = {
-        "prompt": text,
-        "documents": documents,
-    }
+    if guardrails_config:
+        factcheck_config.update(guardrails_config)
+    request_body = {"prompt": text, "documents": documents, "config": factcheck_config}
     async with aiohttp.ClientSession() as session:
         async with session.post(
             url=request_url,
@@ -198,7 +201,8 @@ async def autoalign_factcheck_infer(
             async for line in response.content:
                 resp = json.loads(line)
                 if resp["task"] == "factcheck":
-                    return float(resp["response"][17:])
+                    if resp["response"].startswith("Factcheck Score: "):
+                        return float(resp["response"][17:])
     return 1.0
 
 
@@ -267,25 +271,33 @@ async def autoalign_output_api(
 
 @action(name="autoalign_factcheck_output_api")
 async def autoalign_factcheck_output_api(
-    llm_task_manager: LLMTaskManager, context: Optional[dict] = None
+    llm_task_manager: LLMTaskManager,
+    context: Optional[dict] = None,
+    factcheck_threshold: float = 0.0,
+    show_autoalign_message: bool = True,
 ):
     """Calls AutoAlign factcheck API and checks whether the bot message is factually correct according to given
     documents"""
 
     bot_message = context.get("bot_message")
-    documents = context.get("relevant_chunks", [])
+    documents = context.get("relevant_chunks_sep", [])
+
     autoalign_config = llm_task_manager.config.rails.config.autoalign
     autoalign_fact_check_api_url = autoalign_config.parameters.get(
         "fact_check_endpoint"
     )
+    guardrails_config = getattr(autoalign_config.output, "guardrails_config", None)
     if not autoalign_fact_check_api_url:
         raise ValueError("Provide the autoalign factcheck endpoint in the config")
-    if isinstance(documents, str):
-        documents = documents.split("\n")
-    prompt = bot_message
-    if isinstance(documents, list) and len(documents) > 0:
-        return await autoalign_factcheck_infer(
-            autoalign_fact_check_api_url, prompt, documents
+    text = bot_message
+    score = await autoalign_factcheck_infer(
+        request_url=autoalign_fact_check_api_url,
+        text=text,
+        documents=documents,
+        guardrails_config=guardrails_config,
+    )
+    if score < factcheck_threshold and show_autoalign_message:
+        log.warning(
+            f"Factcheck violation in llm response has been detected by AutoAlign with fact check score {score}"
         )
-    else:
-        raise ValueError("Provide relevant documents in proper format")
+    return score

nemoguardrails/library/autoalign/flows.co

@@ -18,14 +18,11 @@ define subflow autoalign check output
       $bot_message = $pii_message_output
 
 define subflow autoalign factcheck output
-  execute retrieve_relevant_chunks
-  $output_result = execute autoalign_factcheck_output_api
-  if $output_result < 0.5
-    bot inform autoalign factcheck output violation
-    stop
-
-define bot inform autoalign factcheck output violation
-  "Factcheck violation in llm response has been detected by AutoAlign."
+  if $check_facts == True
+    $check_facts = False
+    $threshold = 0.5
+    $output_result = execute autoalign_factcheck_output_api(factcheck_threshold=$threshold, show_autoalign_message=True)
+    bot provide response
 
 define bot refuse to respond
   "I'm sorry, I can't respond to that."