|
24 | 24 | class BadResponseThresholds(BaseModel):
|
25 | 25 | """Config for determining if a response is bad.
|
26 | 26 | Each key is an evaluation metric and the value is a threshold such that if the score is below the threshold, the response is bad.
|
| 27 | + |
| 28 | + Default Thresholds: |
| 29 | + - trustworthiness: 0.5 |
| 30 | + - response_helpfulness: 0.5 |
| 31 | + - Any custom eval: 0.5 (if not explicitly specified in bad_response_thresholds) |
27 | 32 | """
|
28 | 33 |
|
29 | 34 | trustworthiness: float = Field(
|
@@ -83,15 +88,41 @@ def __init__(
|
83 | 88 | trustworthy_rag_config: Optional[dict[str, Any]] = None,
|
84 | 89 | bad_response_thresholds: Optional[dict[str, float]] = None,
|
85 | 90 | ):
|
86 |
| - """Evaluates the quality of responses generated in RAG applications and remediates them if needed. |
| 91 | + """Real-time detection and remediation of bad responses in RAG applications, powered by Cleanlab's TrustworthyRAG and Codex. |
87 | 92 |
|
88 |
| - This object combines Cleanlab's various Evals with thresholding to detect bad responses and remediates them with Codex. |
| 93 | + This object combines Cleanlab's TrustworthyRAG evaluation scores with configurable thresholds to detect potentially bad responses |
| 94 | + in your RAG application. When a bad response is detected, it automatically attempts to remediate by retrieving an expert-provided |
| 95 | + answer from your Codex project. |
| 96 | +
|
| 97 | + For most use cases, we recommend using the `validate()` method which provides a complete validation workflow including |
| 98 | + both detection and Codex remediation. The `detect()` method is available separately for testing and threshold tuning purposes |
| 99 | + without triggering a Codex lookup. |
| 100 | +
|
| 101 | + By default, this uses the same default configurations as [`TrustworthyRAG`](/tlm/api/python/utils.rag/#class-trustworthyrag), except: |
| 102 | + - Explanations are returned in logs for better debugging |
| 103 | + - Only the `response_helpfulness` eval is run |
89 | 104 |
|
90 | 105 | Args:
|
91 |
| - codex_access_key (str): The [access key](/codex/web_tutorials/create_project/#access-keys) for a Codex project. |
92 |
| - tlm_api_key (Optional[str]): The API key for [TrustworthyRAG](/tlm/api/python/utils.rag/#class-trustworthyrag). |
93 |
| - trustworthy_rag_config (Optional[dict[str, Any]]): Optional initialization arguments for [TrustworthyRAG](/tlm/api/python/utils.rag/#class-trustworthyrag), which is used to detect response issues. |
94 |
| - bad_response_thresholds (Optional[dict[str, float]]): Detection score thresholds used to flag whether or not a response is considered bad. Each key in this dict corresponds to an Eval from TrustworthyRAG, and the value indicates a threshold below which scores from this Eval are considered detected issues. A response is flagged as bad if any issues are detected for it. |
| 106 | + codex_access_key (str): The [access key](/codex/web_tutorials/create_project/#access-keys) for a Codex project. Used to retrieve expert-provided answers |
| 107 | + when bad responses are detected. |
| 108 | +
|
| 109 | + tlm_api_key (str, optional): API key for accessing [TrustworthyRAG](/tlm/api/python/utils.rag/#class-trustworthyrag). If not provided, this must be specified |
| 110 | + in trustworthy_rag_config. |
| 111 | +
|
| 112 | + trustworthy_rag_config (dict[str, Any], optional): Optional initialization arguments for [TrustworthyRAG](/tlm/api/python/utils.rag/#class-trustworthyrag), |
| 113 | + which is used to detect response issues. If not provided, default configuration will be used. |
| 114 | +
|
| 115 | + bad_response_thresholds (dict[str, float], optional): Detection score thresholds used to flag whether |
| 116 | + a response is considered bad. Each key corresponds to an Eval from TrustworthyRAG, and the value |
| 117 | + indicates a threshold (between 0 and 1) below which scores are considered detected issues. A response |
| 118 | + is flagged as bad if any issues are detected. If not provided, default thresholds will be used. See |
| 119 | + [`BadResponseThresholds`](/codex/api/python/validator/#class-badresponsethresholds) for more details. |
| 120 | + |
| 121 | + Raises: |
| 122 | + ValueError: If both tlm_api_key and api_key in trustworthy_rag_config are provided. |
| 123 | + ValueError: If bad_response_thresholds contains thresholds for non-existent evaluation metrics. |
| 124 | + TypeError: If any threshold value is not a number. |
| 125 | + ValueError: If any threshold value is not between 0 and 1. |
95 | 126 | """
|
96 | 127 | trustworthy_rag_config = trustworthy_rag_config or get_default_trustworthyrag_config()
|
97 | 128 | if tlm_api_key is not None and "api_key" in trustworthy_rag_config:
|
@@ -171,7 +202,12 @@ def detect(
|
171 | 202 | prompt: Optional[str] = None,
|
172 | 203 | form_prompt: Optional[Callable[[str, str], str]] = None,
|
173 | 204 | ) -> tuple[ThresholdedTrustworthyRAGScore, bool]:
|
174 |
| - """Evaluate the response quality using TrustworthyRAG and determine if it is a bad response via thresholding. |
| 205 | + """Score response quality using TrustworthyRAG and flag bad responses based on configured thresholds. |
| 206 | + |
| 207 | + Note: |
| 208 | + This method is primarily intended for testing and threshold tuning purposes. For production use cases, |
| 209 | + we recommend using the `validate()` method which provides a complete validation workflow including |
| 210 | + Codex remediation. |
175 | 211 |
|
176 | 212 | Args:
|
177 | 213 | query (str): The user query that was used to generate the response.
|
@@ -201,7 +237,7 @@ def detect(
|
201 | 237 | is_bad_response = any(score_dict["is_bad"] for score_dict in thresholded_scores.values())
|
202 | 238 | return thresholded_scores, is_bad_response
|
203 | 239 |
|
204 |
| - def remediate(self, query: str) -> str | None: |
| 240 | + def _remediate(self, query: str) -> str | None: |
205 | 241 | """Request a SME-provided answer for this query, if one is available in Codex.
|
206 | 242 |
|
207 | 243 | Args:
|
|
0 commit comments