add validator and fix readme

Author: aaravnavani

README.md

@@ -1,110 +1,54 @@
 # Overview
 
-| Developed by | Guardrails AI |
+| Developed by | Jonathan Bennion |
 | --- | --- |
-| Date of development | Feb 15, 2024 |
+| Date of development | Mar 29, 2024 |
 | Validator type | Format |
-| Blog |  |
 | License | Apache 2 |
 | Input/Output | Output |
 
-## Description
-
-### Intended Use
-This validator is a template for creating other validators, but for demonstrative purposes it ensures that a generated output is the literal `pass`.
+# Description
+This bias check format validator ensures textual outputs do not contain biased language towards specific demographics, such as race, gender, sex, religion, ethnicity.   
+    
+## Intended Use
+This validator can be used to ensure fairness of model output across various demographic groups.
 
-### Requirements
+## Requirements
 
 * Dependencies:
-	- guardrails-ai>=0.4.0
+    - guardrails-ai>=0.4.0
+    - dbias>=0.1.0  
+        
+* Dev Dependencies:
+    - pytest
+    - pyright
+    - ruff
 
 * Foundation model access keys:
-	- OPENAI_API_KEY
+    - Dependent on the use case (rephrase if unclear)   
+
 
-## Installation
+# Installation
 
 ```bash
-$ guardrails hub install hub://guardrails/validator_template
+$ guardrails hub install hub://guardrails/bias_check
 ```
 
-## Usage Examples
+# Usage Examples
 
-### Validating string output via Python
+## Validating string output via Python
 
 In this example, we apply the validator to a string output generated by an LLM.
 
 ```python
 # Import Guard and Validator
-from guardrails.hub import ValidatorTemplate
+from guardrails.hub import BiasCheck
 from guardrails import Guard
 
 # Setup Guard
-guard = Guard().use(
-    ValidatorTemplate
+guard = Guard.use(
+    BiasCheck()
 )
 
-guard.validate("pass")  # Validator passes
-guard.validate("fail")  # Validator fails
-```
-
-### Validating JSON output via Python
-
-In this example, we apply the validator to a string field of a JSON output generated by an LLM.
-
-```python
-# Import Guard and Validator
-from pydantic import BaseModel, Field
-from guardrails.hub import ValidatorTemplate
-from guardrails import Guard
-
-# Initialize Validator
-val = ValidatorTemplate()
-
-# Create Pydantic BaseModel
-class Process(BaseModel):
-		process_name: str
-		status: str = Field(validators=[val])
-
-# Create a Guard to check for valid Pydantic output
-guard = Guard.from_pydantic(output_class=Process)
-
-# Run LLM output generating JSON through guard
-guard.parse("""
-{
-	"process_name": "templating",
-	"status": "pass"
-}
-""")
-```
-
-# API Reference
-
-**`__init__(self, on_fail="noop")`**
-<ul>
-Initializes a new instance of the ValidatorTemplate class.
-
-**Parameters**
-- **`arg_1`** *(str)*: A placeholder argument to demonstrate how to use init arguments.
-- **`arg_2`** *(str)*: Another placeholder argument to demonstrate how to use init arguments.
-- **`on_fail`** *(str, Callable)*: The policy to enact when a validator fails.  If `str`, must be one of `reask`, `fix`, `filter`, `refrain`, `noop`, `exception` or `fix_reask`. Otherwise, must be a function that is called when the validator fails.
-</ul>
-<br/>
-
-**`validate(self, value, metadata) -> ValidationResult`**
-<ul>
-Validates the given `value` using the rules defined in this validator, relying on the `metadata` provided to customize the validation process. This method is automatically invoked by `guard.parse(...)`, ensuring the validation logic is applied to the input data.
-
-Note:
-
-1. This method should not be called directly by the user. Instead, invoke `guard.parse(...)` where this method will be called internally for each associated Validator.
-2. When invoking `guard.parse(...)`, ensure to pass the appropriate `metadata` dictionary that includes keys and values required by this validator. If `guard` is associated with multiple validators, combine all necessary metadata into a single dictionary.
-
-**Parameters**
-- **`value`** *(Any)*: The input value to validate.
-- **`metadata`** *(dict)*: A dictionary containing metadata required for validation. Keys and values must match the expectations of this validator.
-    
-    
-    | Key | Type | Description | Default |
-    | --- | --- | --- | --- |
-    | `key1` | String | Description of key1's role. | N/A |
-</ul>
+guard.validate("The movie was great!") # Validator passes
+guard.validate("Why do men always think the movie was great?")  # Validator fails

validator/main.py

@@ -8,41 +8,57 @@
     register_validator,
 )
 
+import Dbias
+from Dbias import text_debiasing
 
-@register_validator(name="guardrails/validator_template", data_type="string")
-class ValidatorTemplate(Validator):
-    """Validates that {fill in how you validator interacts with the passed value}.
+@register_validator(name="guardrails/bias_check", data_type="string")
+class BiasCheck(Validator):
+    """Validates that the text is free from biases related to age, gender, sex, ethnicity, religion, etc.
 
     **Key Properties**
 
     | Property                      | Description                       |
     | ----------------------------- | --------------------------------- |
-    | Name for `format` attribute   | `guardrails/validator_template`   |
+    | Name for `format` attribute   | `guardrails/bias_check`           |
     | Supported data types          | `string`                          |
-    | Programmatic fix              | {If you support programmatic fixes, explain it here. Otherwise `None`} |
+    | Programmatic fix              | The debiased text if bias is detected |
 
     Args:
-        arg_1 (string): {Description of the argument here}
-        arg_2 (string): {Description of the argument here}
+        debias_strength (float): The strength of the bias to apply, ranging from 0 to 1.
+        on_fail (Callable): The policy to enact when a validator fails. If `str`, must be one of `reask`, `fix`, `filter`, `refrain`, `noop`, `exception` or `fix_reask`. Otherwise, must be a function that is called when the validator fails.
     """  # noqa
 
-    # If you don't have any init args, you can omit the __init__ method.
     def __init__(
         self,
-        arg_1: str,
-        arg_2: str,
+        debias_strength: float = 0.5,
         on_fail: Optional[Callable] = None,
     ):
-        super().__init__(on_fail=on_fail, arg_1=arg_1, arg_2=arg_2)
-        self._arg_1 = arg_1
-        self._arg_2 = arg_2
+        super().__init__(on_fail=on_fail, debias_strength=debias_strength)
+        self.debias_strength = debias_strength
 
     def validate(self, value: Any, metadata: Dict = {}) -> ValidationResult:
-        """Validates that {fill in how you validator interacts with the passed value}."""
-        # Add your custom validator logic here and return a PassResult or FailResult accordingly.
-        if value != "pass": # FIXME
+        """Validates that the text is free from biases related to age, gender, sex, ethnicity, religion, etc."""
+        debiased_value = Dbias.text_debiasing.debias_text(value, strength=self.debias_strength)
+        if value != debiased_value:
             return FailResult(
-                error_message="{A descriptive but concise error message about why validation failed}",
-                fix_value="{The programmtic fix if applicable, otherwise remove this kwarg.}",
+                error_message="The original response contains potential biases that are now addressed.",
+                fix_value=debiased_value,
             )
         return PassResult()
+
+
+# Run tests via `pytest -rP ./bias_check.py`
+class TestBiasCheck:
+    def test_success_case(self):
+        validator = BiasCheck(debias_strength=0.5)
+        input_text = "The sun rises in the morning."
+        result = validator.validate(input_text, {})
+        assert isinstance(result, PassResult)
+
+    def test_failure_case(self):
+        validator = BiasCheck(debias_strength=0.5)
+        input_text = "The sun only rises for Humanists."
+        result = validator.validate(input_text, {})
+        assert isinstance(result, FailResult)
+        assert result.error_message == "The original response contains potential biases that are now addressed."
+        assert result.fix_value == "The sun rises for everyone."