Overview
Utility module providing display helper functions for rendering feedback results, including icon lookup, feedback result retrieval with timeout, row highlighting, and groundedness explanation expansion.
Description
The Display Utils module (display.py) contains four core functions used across the TruLens dashboard and programmatic API for presenting feedback evaluation results:
get_icon -- Given a FeedbackDefinition and a numeric result score, determines the appropriate status icon (pass, warning, fail, or distance) by delegating to the CATEGORY.of_score classifier. Handles None scores by defaulting to 0 and respects the higher_is_better direction flag as well as special "distance" feedback types.
get_feedback_result -- Retrieves feedback results from a Record object by polling its feedback_and_future_results list for a matching feedback name. It uses a polling loop with a configurable timeout (default 60 seconds), waiting 1 second between attempts. Once the future resolves, it extracts the call-level details (args, return value, and metadata) into a flat DataFrame. Raises TimeoutError if the feedback is not available within the timeout window.
highlight -- A pandas Styler function that applies background-color CSS to DataFrame rows based on a feedback score. It classifies the score using CATEGORY.of_score and applies the corresponding category color. Handles "distance" feedback types and None scores with special category colors.
expand_groundedness_df -- Parses and normalizes groundedness feedback explanations from multiple formats into a standardized DataFrame with columns "Statement", "Supporting Evidence from Source", and "score". It handles:
- New list-of-dict format in the "reasons" column (preferred format).
- List-of-dict format in the "explanation" column.
- JSON string in the "explanation" column that parses to a list of dicts.
- List-of-string format with regex-parsed "Criteria:", "Supporting Evidence:", and "Score:" fields.
- Legacy string-based format with "STATEMENT N:" delimiters.
- Falls back to an empty DataFrame if no parseable data is found.
Usage
Use get_icon when rendering feedback results in tables or summaries to quickly indicate pass/fail/warning status. Use get_feedback_result to programmatically retrieve and inspect feedback call-level details after running an LLM application through TruLens. Use highlight as a pandas Styler function for color-coding feedback DataFrames. Use expand_groundedness_df when displaying detailed groundedness evaluation results to break down per-statement scoring into a readable table.
Code Reference
Source Location
Signature
def get_icon(
fdef: feedback_schema.FeedbackDefinition,
result: float,
) -> str: ...
def get_feedback_result(
tru_record: record_schema.Record,
feedback_name: str,
timeout: int = 60,
) -> pd.DataFrame: ...
def highlight(
row: pd.Series,
selected_feedback: str,
feedback_directions: Dict[str, bool],
default_direction: str,
) -> List[str]: ...
def expand_groundedness_df(
df: pd.DataFrame,
) -> pd.DataFrame: ...
Import
from trulens.dashboard.display import get_icon
from trulens.dashboard.display import get_feedback_result
from trulens.dashboard.display import highlight
from trulens.dashboard.display import expand_groundedness_df
I/O Contract
Inputs
get_icon
| Name |
Type |
Required |
Description
|
| fdef |
feedback_schema.FeedbackDefinition |
yes |
The feedback definition containing the name and higher_is_better direction flag.
|
| result |
float |
yes |
The numeric feedback score. If None, defaults to 0 internally.
|
get_feedback_result
| Name |
Type |
Required |
Description
|
| tru_record |
record_schema.Record |
yes |
The TruLens record containing feedback_and_future_results, a list of (FeedbackDefinition, Future) tuples.
|
| feedback_name |
str |
yes |
The name of the feedback to retrieve results for (must match a feedback definition name).
|
| timeout |
int |
no |
Maximum seconds to wait for the feedback result future to resolve. Defaults to 60.
|
highlight
| Name |
Type |
Required |
Description
|
| row |
pd.Series |
yes |
A single row from a DataFrame to apply styling to. Must contain a "score" field for non-distance feedbacks.
|
| selected_feedback |
str |
yes |
The name of the currently selected feedback metric. If it contains "distance", a special distance color is applied.
|
| feedback_directions |
Dict[str, bool] |
yes |
Mapping of feedback names to their direction (True = higher is better).
|
| default_direction |
str |
yes |
Fallback direction string, either "HIGHER_IS_BETTER" or "LOWER_IS_BETTER".
|
expand_groundedness_df
| Name |
Type |
Required |
Description
|
| df |
pd.DataFrame |
yes |
A DataFrame containing a "reasons" and/or "explanation" column with groundedness evaluation data in one of several supported formats.
|
Outputs
get_icon
| Name |
Type |
Description
|
| icon |
str |
A Unicode icon string representing the feedback category (e.g. pass, warning, fail, distance, or unknown).
|
get_feedback_result
| Name |
Type |
Description
|
| feedback_result |
pd.DataFrame |
DataFrame where each row corresponds to a feedback call, with columns from the call's args, a "score" column from the return value, and additional columns from the call's metadata.
|
highlight
| Name |
Type |
Description
|
| styles |
List[str] |
A list of CSS style strings (one per cell in the row), each setting the background-color to the category's color.
|
expand_groundedness_df
| Name |
Type |
Description
|
| df |
pd.DataFrame |
Normalized DataFrame with columns: "Statement" (the claim being evaluated), "Supporting Evidence from Source" (evidence text), and "score" (numeric groundedness score per statement). Empty if no parseable data is found.
|
Usage Examples
# Example 1: Getting an icon for a feedback result
from trulens.dashboard.display import get_icon
icon = get_icon(fdef=my_feedback_definition, result=0.85)
print(f"Feedback status: {icon}")
# Example 2: Retrieving feedback results from a record with timeout
from trulens.dashboard.display import get_feedback_result
# After running: result, record = tru_app.with_record(my_app, "What is AI?")
feedback_df = get_feedback_result(
tru_record=record,
feedback_name="groundedness",
timeout=120,
)
print(feedback_df)
# Columns include the feedback function's input args, "score", and metadata fields.
# Example 3: Highlighting a DataFrame of feedback results
import pandas as pd
from trulens.dashboard.display import highlight
feedback_df = pd.DataFrame({
"input": ["What is AI?", "Explain ML"],
"score": [0.92, 0.45],
})
styled_df = feedback_df.style.apply(
highlight,
axis=1,
selected_feedback="relevance",
feedback_directions={"relevance": True},
default_direction="HIGHER_IS_BETTER",
)
# The 0.92 row will have a green/pass background, the 0.45 row an orange/warning background.
# Example 4: Expanding groundedness reasons into a readable table
from trulens.dashboard.display import expand_groundedness_df
# Given a feedback result DataFrame with a "reasons" column containing list[dict]:
groundedness_df = expand_groundedness_df(feedback_df)
print(groundedness_df.columns.tolist())
# ['Statement', 'Supporting Evidence from Source', 'score']
for _, row in groundedness_df.iterrows():
print(f"Statement: {row['Statement']}")
print(f"Evidence: {row['Supporting Evidence from Source']}")
print(f"Score: {row['score']}")
print("---")
Related Pages
