Feedback Result Persistence#

Feedback evaluation results in TruLens flow through three layers: the schema (in-memory Pydantic models), the ORM (SQLAlchemy mappings), and the database (trulens_feedbacks table). The dashboard reads back this data via get_records_and_feedback and renders per-call metadata through a dedicated detail view.

Schema: FeedbackResult and FeedbackCall#

The two core serializable types live in schema/feedback.py:

• FeedbackResult — top-level result for one Feedback instance against one record. Key fields:

  • feedback_result_id — content-addressed ID derived via obj_id_of_obj on a model_dump() 1
  • record_id, feedback_definition_id — foreign keys to records and feedback definitions
  • status — FeedbackResultStatus enum: NONE, RUNNING, DONE, FAILED, SKIPPED
  • calls — list of FeedbackCall objects (one per input combination)
  • result — final aggregated float; error — traceback string on failure; multi_result — JSON-encoded dict for multi-valued feedbacks

• FeedbackCall — records a single invocation of the feedback function with args (selector-extracted inputs), ret (float or list), and meta (arbitrary dict for extra data such as reasoning).

A single feedback evaluation can produce multiple FeedbackCall records when selectors match more than one value (controlled by FeedbackCombinations: ZIP or PRODUCT). The agg function then reduces these to the scalar result.

Database Table: trulens_feedbacks#

The ORM mapping is in database/orm.py. The table name is trulens_feedbacks (prefix + feedbacks). Columns:

The ORM.FeedbackResult.parse() classmethod does the serialization: all FeedbackCall objects are packed together into calls_json via json_str_of_obj(dict(calls=obj.calls)) 2. All JSON columns use SQLAlchemy Text (not native JSON) for cross-database compatibility 3.

Write Path: run_and_log#

Feedback.run_and_log() is the main entry point for executing and persisting a feedback result:

1. A placeholder FeedbackResult with status=RUNNING is immediately written via db.insert_feedback() 4.
2. Feedback.run() executes the implementation, builds FeedbackCall objects for each input combination, aggregates them with self.agg, and returns a FeedbackResult with status=DONE (or FAILED).
3. The final result is upserted via db.insert_feedback(feedback_result) 5.

SQLAlchemyDB.insert_feedback() uses session.merge() for thread-safe upsert semantics. A Snowflake-specific workaround inserts -1 for nullable floats first, then updates to NULL, because the Snowflake connector cannot bind None to numeric parameters in the same statement 6.

For deferred mode, Feedback.evaluate_deferred() queries rows with status in [NONE, FAILED, RUNNING] and dispatches them to a thread pool. RUNNING rows are only retried after TruSession.RETRY_RUNNING_SECONDS has elapsed 7.

The DBConnector.add_feedback() method 8 is the public API used externally (e.g., for logging human feedback). It accepts a FeedbackResult, a Future[FeedbackResult], or raw kwargs.

Dashboard: Retrieval and Record Limits#

The Records page (pages/Records.py) fetches data through get_records_and_feedback() in dashboard_utils.py, which is decorated with @st.cache_data (15-minute TTL). This in turn calls SQLAlchemyDB.get_records_and_feedback(), which joins trulens_records, trulens_feedbacks, and trulens_apps, ordering by timestamp descending.

Record limit: The UI defaults to RECORDS_LIMIT = 1000 9, stored in Streamlit session state under the key ST_RECORDS_LIMIT = "records_limit" 10. When the result set hits the limit, a banner prompts the user with a "Show all" button that sets the limit to None 11. Feedback score columns are identified by feedback_col_names returned alongside the DataFrame.

OTel vs. legacy: If OTel tracing is enabled, get_records_and_feedback delegates to _get_records_and_feedback_otel(), which reconstructs records from the trulens_events table using RECORD_ROOT, EVAL, and EVAL_ROOT span types 12.

get_feedback_defs() is called separately to populate feedback_directions (the higher_is_better per-feedback flag), which drives color-coding in the grid.

Dashboard: Detailed Feedback View#

When a user selects a record in the grid, _render_trace() renders a detail panel. The "Feedback Results" section uses two helpers from records_utils.py:

1. _render_feedback_pills() — renders a pill/selectbox with score and icon for each feedback column that has a non-null result. Icons come from CATEGORY.of_score() based on direction.

2. _render_feedback_call() — reads {feedback_col}_calls from the row (the deserialized calls_json), then calls display_feedback_call() which:

   • Separates EVAL_ROOT and EVAL spans (for OTel) from legacy {args, ret, meta} dicts 13
   • For OTel: filters to the most recent eval_root_id to avoid duplicate evaluations 14
   • Builds a DataFrame with args, score (from ret), and flattened meta columns 15
   • For groundedness feedbacks: expands the reasons/explanation field into per-statement rows via expand_groundedness_df()
   • Applies row-level color highlighting via highlight()

The meta dict on each FeedbackCall 16 is the vehicle for surfacing per-call context — such as reasoning text from LLM-graded feedback — directly in the UI. It is stored inside calls_json in the database and expanded into DataFrame columns at display time 17.