updated README

README.md

@@ -1,34 +1,27 @@
----
-license: apache-2.0
-language:
-- en
-pipeline_tag: text-generation
-library_name: transformers
----
-# Granite Guardian 3.1 5B
+# Granite Guardian 3.2 5B
 
 ## Model Summary
 
-**Granite Guardian 3.1 5B** is a thinned down version of Granite Guardian 3.1 8B designed to detect risks in prompts and responses.
+**Granite Guardian 3.2 5B** is a thinned down version of Granite Guardian 3.1 8B designed to detect risks in prompts and responses.
 It can help with risk detection along many key dimensions catalogued in the [IBM AI Risk Atlas](https://www.ibm.com/docs/en/watsonx/saas?topic=ai-risk-atlas).
 
-To generate this model, the Granite Guardian 3.1 8B is iteratively pruned and healed on the same unique data comprising human annotations and synthetic data informed by internal red-teaming used for its training. About 30% of the original parameters were removed allowing for faster inference and lower resource requirements while still providing competitive performance. 
+To generate this model, the Granite Guardian is iteratively pruned and healed on the same unique data comprising human annotations and synthetic data informed by internal red-teaming used for its training. About 30% of the original parameters were removed allowing for faster inference and lower resource requirements while still providing competitive performance. 
 It outperforms other open-source models in the same space on standard benchmarks.
 The thinning procedure based on iterative pruning and healing is described in more details in its own section below.
 
 - **Developers:** IBM Research
 - **GitHub Repository:** [ibm-granite/granite-guardian](https://github.com/ibm-granite/granite-guardian)
-- **Cookbook:** [Granite Guardian Recipes](https://github.com/ibm-granite/granite-guardian/tree/main/cookbooks/granite-guardian-3.1)
+- **Cookbook:** [Granite Guardian Recipes](https://github.com/ibm-granite/granite-guardian/tree/main/cookbooks/granite-guardian-3.2)
 - **Website**: [Granite Guardian Docs](https://www.ibm.com/granite/docs/models/guardian/)
 - **Paper:** [Granite Guardian](https://arxiv.org/abs/2412.07724)
-- **Release Date**: January 22, 2025
+- **Release Date**: February 26, 2024
 - **License:** [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)
 
 ## Usage
 ### Intended Use
 
 Granite Guardian is useful for risk detection use-cases which are applicable across a wide-range of enterprise applications -  
-- Detecting harm-related risks within prompt text or model response (as guardrails). These present two fundamentally different use cases as the former assesses user supplied text while the latter evaluates model generated text.
+- Detecting harm-related risks within prompt text, model responses, or conversations (as guardrails). These present fundamentally different use cases as the first assesses user supplied text, the second evaluates model generated text, and the third evaluates the last turn of a conversation.
 - RAG (retrieval-augmented generation) use-case where the guardian model assesses three key issues: context relevance (whether the retrieved context is relevant to the query), groundedness (whether the response is accurate and faithful to the provided context), and answer relevance (whether the response directly addresses the user's query).
 - Function calling risk detection within agentic workflows, where Granite Guardian evaluates intermediate steps for syntactic and semantic hallucinations. This includes assessing the validity of function calls and detecting fabricated information, particularly during query translation.
  
@@ -43,6 +36,8 @@ The model is specifically designed to detect various risks in user and assistant
   - **Profanity**: use of offensive language or insults.
   - **Sexual Content**: explicit or suggestive material of a sexual nature.
   - **Unethical Behavior**: actions that violate moral or legal standards.
+  - **Harm Engagement**: an engagement or endorsement with any requests that are harmful or unethical
+  - **Evasiveness**: avoiding to engage without providing sufficient reason.
 
 The model also finds a novel use in assessing hallucination risks within a RAG pipeline. These include
 - **Context Relevance**: retrieved context is not pertinent to answering the user's question or addressing their needs.
@@ -55,9 +50,8 @@ The model is also equipped to detect risks in agentic workflows, such as
 ### Using Granite Guardian
 
 [Granite Guardian Cookbooks](https://github.com/ibm-granite/granite-guardian/tree/main/cookbooks) offers an excellent starting point for working with guardian models, providing a variety of examples that demonstrate how the models can be configured for different risk detection scenarios.
-- [Quick Start Guide](https://github.com/ibm-granite/granite-guardian/tree/main/cookbooks/granite-guardian-3.1/quick_start_vllm.ipynb) provides steps to start using Granite Guardian for detecting risks in prompts (user message), responses (assistant message), RAG use cases, or agentic workflows.
-- [Detailed Guide](https://github.com/ibm-granite/granite-guardian/tree/main/cookbooks/granite-guardian-3.1/detailed_guide_vllm.ipynb) explores different risk dimensions in depth and shows how to assess custom risk definitions with Granite Guardian.
-- [Usage Governance Workflow](https://github.com/ibm-granite/granite-guardian/tree/main/cookbooks/granite-guardian-3.1/usage_governance_workflow_vllm.ipynb) outlines steps for users investigating AI risks within a use-case, incentivizing them to explore risks from the IBM AI Risk Atlas using Granite Guardian.
+- [Quick Start Guide](https://github.com/ibm-granite/granite-guardian/tree/main/cookbooks/granite-guardian-3.2/quick_start_vllm.ipynb) provides steps to start using Granite Guardian for detecting risks in prompts (user message), responses (assistant message), RAG use cases, or agentic workflows.
+- [Detailed Guide](https://github.com/ibm-granite/granite-guardian/tree/main/cookbooks/granite-guardian-3.2/detailed_guide_vllm.ipynb) explores different risk dimensions in depth and shows how to assess custom risk definitions with Granite Guardian. For finer-grained control over token-level risk probabilities and thresholding, please also consult this cookbook.
 ### Quickstart Example
 
 The following code describes how to use Granite Guardian to obtain probability scores for a given user and assistant message and a pre-defined guardian configuration. 
@@ -71,20 +65,13 @@ from transformers import AutoTokenizer, AutoModelForCausalLM
 
 safe_token = "No"
 unsafe_token = "Yes"
-nlogprobs = 20
 
 def parse_output(output, input_len):
-    label, prob_of_risk = None, None
-
-    if nlogprobs > 0:
-
-        list_index_logprobs_i = [torch.topk(token_i, k=nlogprobs, largest=True, sorted=True)
-                                 for token_i in list(output.scores)[:-1]]
-        if list_index_logprobs_i is not None:
-            prob = get_probabilities(list_index_logprobs_i)
-            prob_of_risk = prob[1]
-
-    res = tokenizer.decode(output.sequences[:,input_len:][0],skip_special_tokens=True).strip()
+    label = None
+    
+    full_res = tokenizer.decode(output.sequences[:,input_len+1:][0],skip_special_tokens=True).strip()
+    confidence_level = full_res.removeprefix('<confidence>').removesuffix('</confidence>').strip()
+    res = tokenizer.decode(output.sequences[:,input_len:input_len+1][0],skip_special_tokens=True).strip()
     if unsafe_token.lower() == res.lower():
         label = unsafe_token
     elif safe_token.lower() == res.lower():
@@ -92,26 +79,9 @@ def parse_output(output, input_len):
     else:
         label = "Failed"
 
-    return label, prob_of_risk.item()
-
-def get_probabilities(logprobs):
-    safe_token_prob = 1e-50
-    unsafe_token_prob = 1e-50
-    for gen_token_i in logprobs:
-        for logprob, index in zip(gen_token_i.values.tolist()[0], gen_token_i.indices.tolist()[0]):
-            decoded_token = tokenizer.convert_ids_to_tokens(index)
-            if decoded_token.strip().lower() == safe_token.lower():
-                safe_token_prob += math.exp(logprob)
-            if decoded_token.strip().lower() == unsafe_token.lower():
-                unsafe_token_prob += math.exp(logprob)
-
-    probabilities = torch.softmax(
-        torch.tensor([math.log(safe_token_prob), math.log(unsafe_token_prob)]), dim=0
-    )
-
-    return probabilities
+    return label, confidence_level
 
-model_path = "ibm-granite/granite-guardian-3.1-5b"
+model_path = "ibm-granitegranite-guardian-3.2-5b"
 
 model = AutoModelForCausalLM.from_pretrained(
     model_path,
@@ -155,10 +125,10 @@ with torch.no_grad():
         output_scores=True,
     )
 
-label, prob_of_risk = parse_output(output, input_len)
+label, confidence = parse_output(output, input_len)
 
 print(f"# risk detected? : {label}") # Yes
-print(f"# probability of risk: {prob_of_risk:.3f}") # 0.994
+print(f"# confidence detected? : {confidence}") # High
 
 # Usage 2: Example for Hallucination risks in RAG (risk_name=groundedness passed through guardian_config)
 
@@ -184,9 +154,10 @@ with torch.no_grad():
         output_scores=True,
     )
 
-label, prob_of_risk = parse_output(output, input_len)
+label, confidence = parse_output(output, input_len)
+
 print(f"# risk detected? : {label}") # Yes
-print(f"# probability of risk: {prob_of_risk:.3f}") # 0.999
+print(f"# confidence detected? : {confidence}") # High
 ```
 
 ### Prompt Template
@@ -213,7 +184,7 @@ Is the user message harmful based on the risk definition? Your answer must be ei
 ### Scope of Use
 
 - Granite Guardian models must <ins>only</ins> be used strictly for the prescribed scoring mode, which generates yes/no outputs based on the specified template. Any deviation from this intended use may lead to unexpected, potentially unsafe, or harmful outputs. The model may also be prone to such behaviour via adversarial attacks. 
-- The model is targeted for risk definitions of general harm, social bias, profanity, violence, sexual content, unethical behavior, jailbreaking, or groundedness/relevance for retrieval-augmented generation, and function calling hallucinations for agentic workflows.
+- The model is targeted for risk definitions of general harm, social bias, profanity, violence, sexual content, unethical behavior, harm engagement, evasiveness, jailbreaking, groundedness/relevance for retrieval-augmented generation, and function calling hallucinations for agentic workflows. It is also applicable for use with custom risk definitions, but these require testing.
 It is also applicable for use with custom risk definitions, but these require testing.
 - The model is only trained and tested on English data.
 - Given their parameter size, the main Granite Guardian models are intended for use cases that require moderate cost, latency, and throughput such as model risk assessment, model observability and monitoring, and spot-checking inputs and outputs.
@@ -224,63 +195,17 @@ Granite Guardian is trained on a combination of human annotated and synthetic da
 Samples from [hh-rlhf](https://huggingface.co/datasets/Anthropic/hh-rlhf) dataset were used to obtain responses from Granite and Mixtral models.
 These prompt-response pairs were annotated for different risk dimensions by a group of people at DataForce.
 DataForce prioritizes the well-being of its data contributors by ensuring they are paid fairly and receive livable wages for all projects.
-Additional synthetic data was used to supplement the training set to improve performance for hallucination and jailbreak related risks.
-
-### Annotator Demographics
-
-| Year of Birth      | Age               | Gender | Education Level                                 | Ethnicity                     | Region          |
-|--------------------|-------------------|--------|-------------------------------------------------|-------------------------------|-----------------|
-| Prefer not to say  | Prefer not to say | Male   | Bachelor                                        | African American              | Florida         |
-| 1989               | 35                | Male   | Bachelor                                        | White                         | Nevada          |
-| Prefer not to say  | Prefer not to say | Female | Associate's Degree in Medical Assistant         | African American              | Pennsylvania    |
-| 1992               | 32                | Male   | Bachelor                                        | African American              | Florida         |
-| 1978               | 46                | Male   | Bachelor                                        | White                         | Colorado        |
-| 1999               | 25                | Male   | High School Diploma                             | Latin American or Hispanic    | Florida         |
-| Prefer not to say  | Prefer not to say | Male   | Bachelor                                        | White                         | Texas           |
-| 1988               | 36                | Female | Bachelor                                        | White                         | Florida         |
-| 1985               | 39                | Female | Bachelor                                        | Native American               | Colorado / Utah |
-| Prefer not to say  | Prefer not to say | Female | Bachelor                                        | White                         | Arkansas        |
-| Prefer not to say  | Prefer not to say | Female | Master of Science                               | White                         | Texas           |
-| 2000               | 24                | Female | Bachelor of Business Entrepreneurship           | White                         | Florida         |
-| 1987               | 37                | Male   | Associate of Arts and Sciences - AAS            | White                         | Florida         |
-| 1995               | 29                | Female | Master of Epidemiology                          | African American              | Louisiana       |
-| 1993               | 31                | Female | Master of Public Health                         | Latin American or Hispanic    | Texas           |
-| 1969               | 55                | Female | Bachelor                                        | Latin American or Hispanic    | Florida         |
-| 1993               | 31                | Female | Bachelor of Business Administration             | White                         | Florida         |
-| 1985               | 39                | Female | Master of Music                                 | White                         | California      |
-
-## Granite Guardian Thinning
-
-Granite Guardian 3.1 8B is a fine-tuned Granite 3.1 8B Instruct model designed to detect risks for prompts and responses. Granite Guardian 8B is released simultaneously w/ a smaller 2B version for users and developers that face low-resource scenarios. The need for small and efficient risk detectors is inherently important to make risk assessment ubiquitous when using Large Language Models (LLMs). 
-
-Both Granite Guardian 3.1 8B and 2B are trained using the exact same data and training process. Model thinning attempts at compressing Granite Guardian 3.1 8B directly and retain much of its performance. Recent research in LLMs compression tries to reduce a model size as a post-training step, with no- to minimal retraining of the original model. Researchers have devised iterative strategies to decrease a model size while retaining performance [How to Prune and Distall LLama-3.1 8B...](https://developer.nvidia.com/blog/how-to-prune-and-distill-llama-3-1-8b-to-an-nvidia-llama-3-1-minitron-4b-model). Inspired by this approach and by recent papers covering the redundancy of layers in LLMs (see [The Unreasonable Ineffectiveness of the Deeper Layers](https://arxiv.org/abs/2403.17887)), a simple strategy was adopted to thin Granite Guardian 3.1 8B to remove about 30% of its parameters while retaining close performance to the 8B model. This thinning reduces memory usage for inference and training and improves inference time as well. Note that no quantization is applied to the model, only the removal of redundant parameters.  
-
-### Iterative Pruning and Healing 
-
-An aggressive pruning of entire layers is employed to reduce the model size. After each pruning, a healing step is applied to remedy some of the performance drops. This iterative process prunes and heals the model in turn. Granite Guardian 3.1 8B is composed of 40 layers and this process removes 12 layers in 2 iterations to reach the goal of 30% parameters removal.
-
-Why an iterative process? In early experiments in compressing Granite Guardian 3.0 8B (previously released), it was noticed that cutting 12 layers at once followed by healing gave worse performance (0.8670 AUC) than cutting 10, healing, cutting 2, and healing again (0.8835 AUC) on the Harm Benchmarks. This behavior was observed consistently for multiple thinning configurations. Each healing step exposes the model to more training data, which allows the model in its new configuration to find a potentially better set of parameters.
-
-### Layer Selection 
-
-For pruning, layers are selected based on the cosine similarity between their input and output vectors. The layers are ranked by maximum cosine similarity values, and the top K layers located between 10th to 30th layers are selected for removal. This strategy was inspired from [The Unreasonable Ineffectiveness of the Deeper Layers](https://arxiv.org/abs/2403.17887). Layers that are candidate for pruning must provide only small changes to the hidden vectors and must be located away from the beginning of the network (feature extraction part of the network) and from the end of the network (decision making part of the network). 
-
-### Model Thinning 
-
-The original model is pruned iteratively by first eliminating 10 layers from the original model, healing it by training on 80% of the original training data, and then removing 2 more layers followed by another healing. 12 layers are pruned in all. Pruning is done each time by ordering the layers by decreasing cosine similarity scores and pruning the layers with higher similarity first in a greedy manner. After 2 iterations, the model reaches 30% parameter reduction with a small loss of performance compared to the Granite Guardian 3.1 8B.  
-
-This iterative process is a simple and viable strategy to get further pruning (and compression ratios) while being able to keep performances close to the 8B model on all the reported Benchmarks.
-For instance, on RAG Hallucination Benchmarks Granite Guardian 5B gives an average AUC of 0.84 (0.86 for 8B) while for the Harm Benchmarks, it gives an aggregated F1 score of 0.795 (0.8 for 8B). 
+Additional synthetic data was used to supplement the training set to improve performance for conversational, hallucination and jailbreak related risks.
 
 ## Evaluations
 
 ### Harm Benchmarks
-Following the general harm definition, Granite-Guardian-3.1-5B is evaluated across the standard benchmarks of [Aeigis AI Content Safety Dataset](https://huggingface.co/datasets/nvidia/Aegis-AI-Content-Safety-Dataset-1.0), [ToxicChat](https://huggingface.co/datasets/lmsys/toxic-chat), [HarmBench](https://github.com/centerforaisafety/HarmBench/tree/main), [SimpleSafetyTests](https://huggingface.co/datasets/Bertievidgen/SimpleSafetyTests), [BeaverTails](https://huggingface.co/datasets/PKU-Alignment/BeaverTails), [OpenAI Moderation data](https://github.com/openai/moderation-api-release/tree/main), [SafeRLHF](https://huggingface.co/datasets/PKU-Alignment/PKU-SafeRLHF) and [xstest-response](https://huggingface.co/datasets/allenai/xstest-response). 
+Following the general harm definition, Granite-Guardian-3.2-5B is evaluated across the standard benchmarks of [Aeigis AI Content Safety Dataset](https://huggingface.co/datasets/nvidia/Aegis-AI-Content-Safety-Dataset-1.0), [ToxicChat](https://huggingface.co/datasets/lmsys/toxic-chat), [HarmBench](https://github.com/centerforaisafety/HarmBench/tree/main), [SimpleSafetyTests](https://huggingface.co/datasets/Bertievidgen/SimpleSafetyTests), [BeaverTails](https://huggingface.co/datasets/PKU-Alignment/BeaverTails), [OpenAI Moderation data](https://github.com/openai/moderation-api-release/tree/main), [SafeRLHF](https://huggingface.co/datasets/PKU-Alignment/PKU-SafeRLHF) and [xstest-response](https://huggingface.co/datasets/allenai/xstest-response). 
 The following table presents the F1 scores for various harm benchmarks, followed by an ROC curve based on the aggregated benchmark data.
 
-| Metric | AegisSafetyTest | BeaverTails | OAI moderation | SafeRLHF(test) | SimpleSafetyTest | HarmBench | ToxicChat | xstest_RH | xstest_RR | xstest_RR(h) | Aggregate F1 |
-|--------|-----------------|-------------|----------------|----------------|------------------|-----------|-----------|-----------|-----------|--------------|--------------|
-| **F1** | 0.89            | 0.83        | 0.74           | 0.79           | 0.99             | 0.80      | 0.73      | 0.90      | 0.44      | 0.84         | 0.795        |
+| Metric | AegisSafetyTest | BeaverTails | OAI moderation | SafeRLHF(test) | SimpleSafetyTest | HarmBench | ToxicChat  | xstest_RH | xstest_RR | xstest_RR(h) | Aggregate F1 |
+|--------|-----------------|-------------|----------------|----------------|------------------|-----------|------------|-----------|-----------|--------------|--------------|
+| **F1** | 0.88            | 0.81        | 0.73           | 0.80           | 1.00             | 0.80     | 0.73       | 0.90       | 0.43      | 0.82         | 0.784        |
 
 
 ![roc.png](roc.png)
@@ -290,16 +215,29 @@ For risks in RAG use cases, the model is evaluated on [TRUE](https://github.com/
 
 | Metric  | mnbm | begin | qags_xsum | qags_cnndm | summeval | dialfact | paws | q2   | frank | Average |
 |---------|------|-------|-----------|------------|----------|----------|------|------|-------|---------|
-| **AUC** | 0.71 | 0.77  | 0.80      | 0.87       | 0.84     | 0.92     | 0.86 | 0.87 | 0.89  | 0.84    |
+| **AUC** | 0.70 | 0.79  | 0.81      | 0.87       | 0.83     | 0.93     | 0.86 | 0.87 | 0.88  | 0.84    |
 
 
 ### Function Calling Hallucination Benchmarks 
 The model performance is evaluated on the DeepSeek generated samples from [APIGen](https://huggingface.co/datasets/Salesforce/xlam-function-calling-60k) dataset, the [ToolAce](https://huggingface.co/datasets/Team-ACE/ToolACE) dataset, and different splits of the [BFCL v2](https://gorilla.cs.berkeley.edu/blogs/12_bfcl_v2_live.html) datasets. For DeepSeek and ToolAce dataset, synthetic errors are generated from `mistralai/Mixtral-8x22B-v0.1` teacher model. For the others, the errors are generated from existing function calling models on corresponding categories of the BFCL v2 dataset.
 
-| Metric  | multiple | simple | parallel | parallel_multiple | javascript | java  | deepseek | toolace|
-|---------|----------|--------|----------|-------------------|------------|-------|----------|--------|
-| **AUC** | 0.78     | 0.75   | 0.78     | 0.68              | 0.75       | 0.90  | 0.90     | 0.76   |
+| Metric  | multiple | simple | parallel | parallel_multiple | javascript | java | deepseek | toolace | Average |
+|---------|----------|-------|-----------|-------------------|------------|------|----------|---------|---------|
+| **AUC** | 0.74     | 0.75  | 0.78      | 0.66              | 0.73       | 0.86 | 0.92     | 0.78    | 0.79    |
+
+
 
+### Multi-turn conversational risk
+The model performance is evaluated on sample conversations taken from the [DICES](https://arxiv.org/abs/2306.11247) dataset and Anthropic's hh-rlhf dataset. Ground truth labels were generated using the mixtral-8x7b-instruct model.
+
+| Metric  |    harm_engagement_response | harm_engagement_prompt | evasiveness_response | evasiveness_prompt |
+|---------|-----------------------------|------------------------|----------------------|--------------------|
+| **AUC** |           0.97              |         0.92           |        0.97          |       0.91         |
+
+| **AUC**             | **Prompt** | **Response** |
+|-----------------|--------|----------|
+| harm_engagement | 0.92   | 0.97     |
+| evasiveness     | 0.91   | 0.97     |
 
 ### Citation
 ```
@@ -312,4 +250,4 @@ The model performance is evaluated on the DeepSeek generated samples from [APIGe
       primaryClass={cs.CL},
       url={https://arxiv.org/abs/2412.07724}, 
 }
-```
+```