Implementation:Truera Trulens Records Utils

Knowledge Sources	Truera_Trulens TruLens Docs
Domains	Dashboard, Visualization
Last Updated	2026-02-14 08:00 GMT

Overview

Utility module for rendering feedback records in the TruLens dashboard, providing cell highlighting, feedback pill rendering, and feedback call detail display.

Description

The records_utils module contains functions responsible for the visual presentation of feedback data in the TruLens Streamlit dashboard. It bridges raw database records and the Streamlit UI with functions for:

Cell Highlighting:

df_cell_highlight(score, feedback_name, feedback_directions, n_cells) -- Returns a list of CSS background-color styles for DataFrame cells based on the feedback score and direction. Scores are mapped to CATEGORY thresholds (pass/warning/fail). Distance-based feedback and None scores receive the UNKNOWN category color.

Span Type Processing (OTel support):

_identify_span_types(call) -- Separates a list of call dictionaries into EVAL_ROOT spans and EVAL spans. Legacy (pre-OTel) spans are identified by the presence of args, ret, and meta keys and classified as EVAL spans.
_filter_eval_calls_by_root(eval_root_calls, eval_calls) -- Filters EVAL spans to only those belonging to the most recent EVAL_ROOT spans (based on deduplication by timestamp). This handles re-evaluation scenarios where feedback is computed multiple times.
_filter_duplicate_span_calls(df) -- Groups EVAL_ROOT spans by (args_span_id, args_span_attribute) and retains only the most recent entry per group based on timestamp. Falls back to returning all spans if grouping columns are absent.
_process_eval_calls_for_display(eval_calls) -- Converts EVAL call dictionaries into a display-ready DataFrame with formatted args, a score column (defaulting to -1 for None returns), and flattened meta fields.

Feedback Display:

display_feedback_call(record_id, call, feedback_name, feedback_directions) -- The main display function for feedback call details. It separates span types, filters by most recent EVAL_ROOT, processes calls into a styled DataFrame, and handles special groundedness feedback expansion. Numeric columns are formatted to 2 decimal places.
_render_feedback_pills(feedback_col_names, feedback_directions, selected_row) -- Renders clickable feedback pills using st.pills (Streamlit 1.40.0+) or falls back to st.selectbox. Each pill shows the category icon, feedback name, and score (e.g., "✓ relevance 0.85"). Returns the selected feedback column name.
_render_feedback_call(feedback_col, selected_row, feedback_directions) -- Handles the MULTI_CALL_NAME_DELIMITER parsing and invokes display_feedback_call with the appropriate feedback calls data from the selected row.

Usage

These functions are used by the Streamlit page renderer (trulens.dashboard.streamlit) and the records detail pages. Use df_cell_highlight when applying conditional formatting to feedback DataFrames. Use _render_feedback_pills and _render_feedback_call for interactive feedback exploration in record detail views.

Code Reference

Source Location

Repository: Truera_Trulens
File: src/dashboard/trulens/dashboard/utils/records_utils.py
Lines: 1-346

Signature

def df_cell_highlight(
    score: float,
    feedback_name: str,
    feedback_directions: Dict[str, bool],
    n_cells: int = 1,
) -> List[str]: ...


def display_feedback_call(
    record_id: str,
    call: List[Dict[str, Any]],
    feedback_name: str,
    feedback_directions: Dict[str, bool],
): ...


def _identify_span_types(
    call: List[Dict[str, Any]],
) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]: ...


def _filter_eval_calls_by_root(
    eval_root_calls: List[Dict[str, Any]],
    eval_calls: List[Dict[str, Any]],
) -> List[Dict[str, Any]]: ...


def _filter_duplicate_span_calls(df: pd.DataFrame) -> pd.DataFrame: ...


def _process_eval_calls_for_display(
    eval_calls: List[Dict[str, Any]],
) -> pd.DataFrame: ...


def _render_feedback_pills(
    feedback_col_names: Sequence[str],
    feedback_directions: Dict[str, bool],
    selected_row: Optional[pd.Series] = None,
): ...


def _render_feedback_call(
    feedback_col: str,
    selected_row: pd.Series,
    feedback_directions: Dict[str, bool],
): ...

Import

from trulens.dashboard.utils.records_utils import df_cell_highlight
from trulens.dashboard.utils.records_utils import display_feedback_call
from trulens.dashboard.utils.records_utils import _render_feedback_pills
from trulens.dashboard.utils.records_utils import _render_feedback_call

I/O Contract

Inputs

df_cell_highlight:

Name	Type	Required	Description
score	float	yes	The feedback score value (typically 0.0 to 1.0).
feedback_name	str	yes	The name of the feedback function (e.g., "relevance", "groundedness").
feedback_directions	Dict[str, bool]	yes	Maps feedback names to direction. `True` means higher is better.
n_cells	int	no	Number of cells to apply the style to (default 1).

display_feedback_call:

Name	Type	Required	Description
record_id	str	yes	The ID of the record being displayed.
call	List[Dict[str, Any]]	yes	List of feedback call dictionaries containing span/call data.
feedback_name	str	yes	The feedback function name.
feedback_directions	Dict[str, bool]	yes	Maps feedback names to direction.

_render_feedback_pills:

Name	Type	Required	Description
feedback_col_names	Sequence[str]	yes	Names of the feedback function columns.
feedback_directions	Dict[str, bool]	yes	Maps feedback names to direction.
selected_row	Optional[pd.Series]	no	The selected record row. If provided, pills show scores and icons.

Outputs

Name	Type	Description
df_cell_highlight return	List[str]	List of CSS style strings (e.g., `"background-color: #abcdef"`).
display_feedback_call return	None	Renders a styled DataFrame directly to Streamlit.
_render_feedback_pills return	Optional[str]	The name of the selected feedback column, or `None` if no selection.
_render_feedback_call return	None	Renders feedback call details directly to Streamlit.

Usage Examples

from trulens.dashboard.utils.records_utils import df_cell_highlight

# Apply conditional cell highlighting to a pandas DataFrame
feedback_directions = {"relevance": True, "toxicity": False}
styles = df_cell_highlight(
    score=0.85,
    feedback_name="relevance",
    feedback_directions=feedback_directions,
    n_cells=3,
)
# Returns: ["background-color: #<pass_color>"] * 3

from trulens.dashboard.utils.records_utils import _render_feedback_pills
from trulens.dashboard.utils.records_utils import _render_feedback_call

# Render feedback pills in a Streamlit page
feedback_col_names = ["relevance", "groundedness", "answer_relevance"]
feedback_directions = {"relevance": True, "groundedness": True, "answer_relevance": True}

selected_ff = _render_feedback_pills(
    feedback_col_names=feedback_col_names,
    feedback_directions=feedback_directions,
    selected_row=selected_record_row,
)

if selected_ff:
    _render_feedback_call(
        selected_ff,
        selected_record_row,
        feedback_directions=feedback_directions,
    )

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment