Implementation:Truera Trulens Appui Widgets

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

Overview

An ipywidgets-based interactive UI module for viewing and inspecting TruLens app records directly within Jupyter notebooks.

Description

The appui module provides a set of classes built on top of ipywidgets and traitlets that allow users to interactively explore TruLens-instrumented applications and their recorded data from within a Jupyter notebook environment. The module defines four primary classes:

Selector -- Wraps a TruLens Lens path expression (e.g. Select.RecordCalls.retrieve.rets) into an editable text widget with a delete button. It validates the path expression in real time and highlights invalid paths with a red border. Selectors are used both for inspecting parts of the live application object (app selectors) and for inspecting parts of recorded data (record selectors).

SelectorValue -- Pairs a Selector with an object to evaluate the selector path against. When the selector path or the target object changes (observed via traitlets), it resolves the path, traverses the object structure, and renders the results as an HTML listing inside an ipywidgets.HTML widget. It handles mappings, sequences, and primitive types with truncated output capped at VALUE_MAX_CHARS (1024 characters).

RecordWidget -- Represents a single record (one human input and its corresponding computer output) displayed as a vertical box. It manages a collection of SelectorValue instances for all active record selectors, allowing users to drill into different parts of the recorded call data via record.layout_calls_as_app().

AppUI -- The top-level interactive interface that composes all the other widgets. It provides text inputs and buttons for submitting new queries to the app (+ Record), adding app-level selectors (+ Select.App), and adding record-level selectors (+ Select.Record). It supports both synchronous and asynchronous app invocations. Each new record is displayed vertically in the top area, while app-level selector results are shown in a side panel.

Usage

Use the AppUI class when you want to interactively run queries against a TruLens-instrumented app and inspect internal state, call details, and intermediate results without leaving a Jupyter notebook. This is particularly useful during development and debugging of LLM applications, where you need quick feedback on what data is flowing through your instrumented components.

Code Reference

Source Location

Repository: Truera_Trulens
File: src/dashboard/trulens/dashboard/appui.py
Lines: 1-434

Signature

class Selector(HasTraits):
    select = Unicode()
    jpath = traitlets.Any()

    def __init__(
        self, select: Union[serial_utils.Lens, str], make_on_delete: Callable
    ): ...


class SelectorValue(HasTraits):
    selector = traitlets.Any()
    obj = traitlets.Any()

    def __init__(
        self,
        selector: Selector,
        stdout_display: widgets.Output,
        instrument: core_instruments.Instrument,
    ): ...

    def update(self): ...


class RecordWidget:
    def __init__(
        self,
        record_selections,
        instrument: core_instruments.Instrument,
        record=None,
        human_or_input=None,
        stdout_display: widgets.Output = None,
    ): ...

    def update_selections(self): ...
    def remove_selector(self, selector: Selector): ...
    def set_human(self, human: str): ...
    def set_comp(self, comp: str): ...


class AppUI(traitlets.HasTraits):
    def __init__(
        self,
        app: core_app.App,
        use_async: bool = False,
        app_selectors: Optional[List[Union[str, serial_utils.Lens]]] = None,
        record_selectors: Optional[List[Union[str, serial_utils.Lens]]] = None,
    ): ...

    def add_record(self, w): ...
    def add_app_selection(self, w): ...
    def add_record_selection(self, w): ...

Import

from trulens.dashboard.appui import AppUI
from trulens.dashboard.appui import Selector
from trulens.dashboard.appui import SelectorValue
from trulens.dashboard.appui import RecordWidget

I/O Contract

Inputs

AppUI constructor:

Name	Type	Required	Description
app	core_app.App	yes	A TruLens-instrumented application instance to interact with.
use_async	bool	no	Whether to invoke the app's `main_acall` asynchronously (default `False`).
app_selectors	Optional[List[Union[str, serial_utils.Lens]]]	no	Initial list of selector paths to inspect the live app object.
record_selectors	Optional[List[Union[str, serial_utils.Lens]]]	no	Initial list of selector paths to inspect each recorded call.

Selector constructor:

Name	Type	Required	Description
select	Union[serial_utils.Lens, str]	yes	A Lens path expression or its string representation.
make_on_delete	Callable	yes	Factory function that receives the Selector and returns a callback for the delete button.

SelectorValue constructor:

Name	Type	Required	Description
selector	Selector	yes	The Selector instance whose path is used to extract values.
stdout_display	widgets.Output	yes	An Output widget for capturing print/log output during evaluation.
instrument	core_instruments.Instrument	yes	The instrument instance used for JSON serialization of internal objects.

Outputs

Name	Type	Description
AppUI.widget	widgets.VBox	The top-level composite ipywidget to display in a Jupyter cell.
Selector.w	widgets.HBox	The delete button and text input for a single selector.
SelectorValue.w	widgets.VBox	The selector widget plus its rendered HTML listing.
RecordWidget.d	widgets.VBox	The full record display including human input, computer output, and selector values.

Usage Examples

from trulens.dashboard.appui import AppUI
from trulens.core.schema.select import Select

# Assume `tru_app` is a TruLens-instrumented app (e.g., TruChain, TruLlama, etc.)
ui = AppUI(
    app=tru_app,
    use_async=False,
    app_selectors=[
        Select.App.app_name,
        Select.App.app_version,
    ],
    record_selectors=[
        Select.RecordCalls.retrieve.rets,
        Select.RecordCalls.generate.args.prompt,
    ],
)

# Display the interactive UI in a Jupyter notebook cell
display(ui.widget)

# Programmatically add a new record
ui.main_input.value = "What is the capital of France?"
ui.add_record(None)

# Programmatically add a new app selector
ui.app_selector.value = "app.model_id"
ui.add_app_selection(None)

Related Pages

Page Connections

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

Principle

Implementation

Heuristic

Environment