add public async methods for Get Explanations API (#118)

* add public async methods for Get Explanations API

* prepare for release

Author: LukeMainwaring

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.31] - 2025-09-18
+
+### Added
+
+- Add `get_explanation_async()` API for TLM and TrustworthyRAG
+
 ## [1.1.30] - 2025-09-09
 
 ### Added
@@ -60,8 +66,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Updated `TLMOptions` to support `disable_trustworthiness` parameter
-    - Skips trustworthiness scoring when `disable_trustworthiness` is True, assuming either custom evaluation criteria (TLM) or RAG Evals (TrustworthyRAG) are provided
-
+  - Skips trustworthiness scoring when `disable_trustworthiness` is True, assuming either custom evaluation criteria (TLM) or RAG Evals (TrustworthyRAG) are provided
 
 ## [1.1.22] - 2025-07-29
 
@@ -87,55 +92,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add `get_model_name()` method to `TrustworthyRAG`, `TLMChatCompletion`
 
-
 ## [1.1.18] - 2025-07-25
 
 ### Fixed
 
 - Properly pass quality preset in `TLMChatCompletion`
 
-
 ## [1.1.17] - 2025-07-18
 
 ### Changed
 
 - Enabled `TLMChatCompletion.score()`to evaluate structured outputs in `ChatCompletion` objects
 
-
 ## [1.1.16] - 2025-07-15
 
 ### Changed
 
 - Add internal setting to bypass model validation check (for custom/VPC models)
 
-
 ## [1.1.15] - 2025-07-14
 
 ### Changed
 
 - Enabled `TLMChatCompletion.score()`to evaluate tool calls in `ChatCompletion` objects
 
-
 ## [1.1.14] - 2025-07-08
 
 ### Added
 
 - New TLMOption `num_self_reflections`
 - Support for `best` and `high` preset in `TrustworthyRAG`
 
-### Changed 
+### Changed
 
 - Deprecate `use_self_reflection`
 - Documentation updates for new default configurations
 
-
 ## [1.1.13] - 2025-06-26
 
 ### Added
 
 - Added `form_response_string_chat_completions_api` in `chat.py`
 
-
 ## [1.1.12] - 2025-06-23
 
 ### Fixed
@@ -153,7 +151,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Bug fix in `chat.py` for empty tool list still using tools prompt
 - Bug fix in `chat.py` for handling empty strings args
 
-
 ## [1.1.10] - 2025-06-20
 
 ### Added
@@ -346,8 +343,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Release of the Cleanlab TLM Python client.
 
-
-[Unreleased]: https://github.com/cleanlab/cleanlab-tlm/compare/v1.1.30...HEAD
+[Unreleased]: https://github.com/cleanlab/cleanlab-tlm/compare/v1.1.31...HEAD
+[1.1.31]: https://github.com/cleanlab/cleanlab-tlm/compare/v1.1.30...v1.1.31
 [1.1.30]: https://github.com/cleanlab/cleanlab-tlm/compare/v1.1.29...v1.1.30
 [1.1.29]: https://github.com/cleanlab/cleanlab-tlm/compare/v1.1.28...v1.1.29
 [1.1.28]: https://github.com/cleanlab/cleanlab-tlm/compare/v1.1.27...v1.1.28

src/cleanlab_tlm/__about__.py

@@ -1,2 +1,2 @@
 # SPDX-License-Identifier: MIT
-__version__ = "1.1.30"
+__version__ = "1.1.31"

src/cleanlab_tlm/tlm.py

@@ -588,6 +588,59 @@ def get_explanation(
             )
         )
 
+    async def get_explanation_async(
+        self,
+        *,
+        prompt: Union[str, Sequence[str]],
+        response: Optional[Union[str, Sequence[str]]] = None,
+        tlm_result: Union[TLMResponse, TLMScore, Sequence[TLMResponse], Sequence[TLMScore]],
+    ) -> Union[str, list[str]]:
+        """Asynchronously gets explanations for a given prompt-response pair with a given score.
+
+        This method provides detailed explanations from TLM about why a particular response
+        received its trustworthiness score.
+
+        The `tlm_result` object will be mutated to include the explanation in its log.
+
+        Args:
+            prompt (str | Sequence[str]): The original prompt(s) that were used to generate
+                the response(s) or that were evaluated for trustworthiness scoring.
+            response (str | Sequence[str], optional): The response(s) that were evaluated.
+                Required when `tlm_result` contains a `TLMScore` object, as the response text is
+                not included there. Should not be provided when `tlm_result` contains a `TLMResponse`
+                object, as the response text is already included there.
+            tlm_result (TLMResponse | TLMScore | Sequence[TLMResponse] | Sequence[TLMScore]):
+                The result object(s) from a previous TLM call (either `prompt()` or
+                `get_trustworthiness_score()`).
+
+        Returns:
+            str | list[str]: Explanation(s) for why TLM assigned the given trustworthiness
+                score(s) to the response(s).
+                If a single prompt/result pair was provided, returns a single explanation string.
+                If a list of prompt/results was provided, returns a list of explanation strings matching the input order.
+        """
+        formatted_tlm_result = tlm_explanation_format_tlm_result(tlm_result, response)
+
+        async with aiohttp.ClientSession() as session:
+            if isinstance(prompt, str) and isinstance(tlm_result, dict) and isinstance(formatted_tlm_result, dict):
+                return await self._get_explanation_async(
+                    prompt,
+                    tlm_result,
+                    formatted_tlm_result,
+                    session,
+                    timeout=self._timeout,
+                )
+
+            assert isinstance(prompt, Sequence)
+            assert isinstance(tlm_result, Sequence)
+            assert isinstance(formatted_tlm_result, Sequence)
+
+            return await self._batch_get_explanation(
+                prompts=prompt,
+                tlm_results=tlm_result,
+                formatted_tlm_results=formatted_tlm_result,
+            )
+
     async def _batch_get_explanation(
         self,
         prompts: Sequence[str],

src/cleanlab_tlm/utils/rag.py

@@ -426,6 +426,85 @@ def get_explanation(
             )
         )
 
+    async def get_explanation_async(
+        self,
+        *,
+        response: Optional[Union[str, Sequence[str]]] = None,
+        query: Union[str, Sequence[str]],
+        context: Union[str, Sequence[str]],
+        tlm_result: Union[
+            TrustworthyRAGResponse,
+            Sequence[TrustworthyRAGResponse],
+            TrustworthyRAGScore,
+            Sequence[TrustworthyRAGScore],
+        ],
+        prompt: Optional[Union[str, Sequence[str]]] = None,
+        form_prompt: Optional[Callable[[str, str], str]] = None,
+    ) -> Union[str, list[str]]:
+        """Asynchronously gets explanations for a response with a given trustworthiness score.
+
+        This method provides detailed explanations from TrustworthyRAG about why a particular response
+        received its trustworthiness score.
+
+        The `tlm_result` object will be mutated to include the explanation in its log,
+        adding an "explanation" key to the log dictionary.
+
+        Args:
+            response (str | Sequence[str], optional): The response(s) that were evaluated.
+                Required when `tlm_result` contains a `TrustworthyRAGScore` object, as the response text is
+                not included there. Should not be provided when `tlm_result` contains a `TrustworthyRAGResponse`
+                object, as the response text is already included there.
+            query (str | Sequence[str]): The user query (or list of multiple queries) that was used to generate the response.
+            context (str | Sequence[str]): The context (or list of multiple contexts) that was retrieved from the RAG Knowledge Base and used to generate the response.
+            tlm_result (TrustworthyRAGResponse | Sequence[TrustworthyRAGResponse] | TrustworthyRAGScore | Sequence[TrustworthyRAGScore]): The result object(s) from a previous TrustworthyRAG call (either `generate()` or `score()`).
+            prompt (str | Sequence[str], optional): Optional prompt (or list of multiple prompts) representing the actual inputs (combining query, context, and system instructions into one string) to the LLM that generated the response.
+            form_prompt (Callable[[str, str], str], optional): Optional function to format the prompt based on query and context. Cannot be provided together with prompt, provide one or the other.
+                    This function should take query and context as parameters and return a formatted prompt string.
+                    If not provided, a default prompt formatter will be used.
+                    To include a system prompt or any other special instructions for your LLM,
+                    incorporate them directly in your custom `form_prompt()` function definition.
+
+        Returns:
+            str | list[str]: Explanation(s) for why TrustworthyRAG assigned the given trustworthiness score to the response(s).
+                If a single prompt/result pair was provided, returns a single explanation string.
+                If a list of prompt/results was provided, returns a list of explanation strings matching the input order.
+
+        """
+        if prompt is None and form_prompt is None:
+            form_prompt = TrustworthyRAG._default_prompt_formatter
+
+        formatted_prompt = validate_rag_inputs(
+            query=query,
+            context=context,
+            response=response,
+            prompt=prompt,
+            form_prompt=form_prompt,
+            evals=self._evals,
+            is_generate=response is None,
+        )
+
+        formatted_tlm_result = tlm_explanation_format_trustworthy_rag_result(tlm_result, response)
+
+        if isinstance(formatted_prompt, str) and isinstance(formatted_tlm_result, dict):
+            assert isinstance(tlm_result, dict)
+
+            return await self._get_explanation_async(
+                prompt=formatted_prompt,
+                tlm_result=tlm_result,
+                formatted_tlm_result=formatted_tlm_result,
+                timeout=self._timeout,
+            )
+
+        assert isinstance(formatted_prompt, Sequence)
+        assert isinstance(tlm_result, Sequence)
+        assert isinstance(formatted_tlm_result, Sequence)
+
+        return await self._batch_get_explanation(
+            prompts=formatted_prompt,
+            tlm_results=tlm_result,
+            formatted_tlm_results=formatted_tlm_result,
+        )
+
     async def _batch_get_explanation(
         self,
         prompts: Sequence[str],