feat(demo): add clickable source references with PDF page navigation

- Extract page references from retrieved content metadata in RAGService
- Add Reference record to store page, type, and preview text
- Update ChatMessage to include list of references
- MessageBubble displays clickable "Sources: p.1 p.2..." links
- Clicking a page link navigates PDF viewer to that page
- Hover tooltips show content type and preview
- Add CSS styles for reference pill-shaped badges

Author: bsbodden

demos/rag-multimodal/src/main/java/com/redis/vl/demo/rag/model/ChatMessage.java

@@ -1,9 +1,10 @@
 package com.redis.vl.demo.rag.model;
 
 import java.time.Instant;
+import java.util.List;
 
 /**
- * Represents a chat message with cost tracking.
+ * Represents a chat message with cost tracking and source references.
  *
  * @param id Unique message identifier
  * @param role Message role (USER or ASSISTANT)
@@ -13,6 +14,7 @@
  * @param costUsd Cost in USD for this message (for AI responses)
  * @param model LLM model used (for AI responses)
  * @param fromCache Whether the response came from cache
+ * @param references Source references from retrieved content
  */
 public record ChatMessage(
     String id,
@@ -22,7 +24,8 @@ public record ChatMessage(
     int tokenCount,
     double costUsd,
     String model,
-    boolean fromCache) {
+    boolean fromCache,
+    List<Reference> references) {
 
   public enum Role {
     USER,
@@ -37,7 +40,7 @@ public enum Role {
    */
   public static ChatMessage user(String content) {
     return new ChatMessage(
-        generateId(), Role.USER, content, Instant.now(), 0, 0.0, null, false);
+        generateId(), Role.USER, content, Instant.now(), 0, 0.0, null, false, List.of());
   }
 
   /**
@@ -53,7 +56,24 @@ public static ChatMessage user(String content) {
   public static ChatMessage assistant(
       String content, int tokenCount, double costUsd, String model, boolean fromCache) {
     return new ChatMessage(
-        generateId(), Role.ASSISTANT, content, Instant.now(), tokenCount, costUsd, model, fromCache);
+        generateId(), Role.ASSISTANT, content, Instant.now(), tokenCount, costUsd, model, fromCache, List.of());
+  }
+
+  /**
+   * Creates an assistant message with references.
+   *
+   * @param content Message content
+   * @param tokenCount Token count
+   * @param costUsd Cost in USD
+   * @param model Model name
+   * @param fromCache Whether from cache
+   * @param references Source references
+   * @return Assistant chat message with references
+   */
+  public static ChatMessage assistant(
+      String content, int tokenCount, double costUsd, String model, boolean fromCache, List<Reference> references) {
+    return new ChatMessage(
+        generateId(), Role.ASSISTANT, content, Instant.now(), tokenCount, costUsd, model, fromCache, references);
   }
 
   private static String generateId() {

demos/rag-multimodal/src/main/java/com/redis/vl/demo/rag/model/Reference.java

@@ -0,0 +1,28 @@
+package com.redis.vl.demo.rag.model;
+
+/**
+ * A reference to a source location in the PDF document.
+ *
+ * @param page Page number (1-indexed)
+ * @param type Content type (TEXT or IMAGE)
+ * @param preview Short preview of the content
+ */
+public record Reference(int page, String type, String preview) {
+
+  /**
+   * Creates a reference with a truncated preview.
+   *
+   * @param page Page number
+   * @param type Content type
+   * @param content Full content text
+   * @param maxLength Maximum preview length
+   * @return Reference with truncated preview
+   */
+  public static Reference of(int page, String type, String content, int maxLength) {
+    String preview = content;
+    if (preview != null && preview.length() > maxLength) {
+      preview = preview.substring(0, maxLength) + "...";
+    }
+    return new Reference(page, type, preview);
+  }
+}

demos/rag-multimodal/src/main/java/com/redis/vl/demo/rag/service/RAGService.java

@@ -3,6 +3,7 @@
 import com.redis.vl.demo.rag.model.CacheType;
 import com.redis.vl.demo.rag.model.ChatMessage;
 import com.redis.vl.demo.rag.model.LLMConfig;
+import com.redis.vl.demo.rag.model.Reference;
 import com.redis.vl.extensions.cache.CacheHit;
 import com.redis.vl.extensions.cache.LangCacheSemanticCache;
 import com.redis.vl.extensions.cache.SemanticCache;
@@ -145,13 +146,22 @@ public ChatMessage query(String userQuery, CacheType cacheType) {
       System.out.println("  [" + i + "] " + preview);
     }
 
-    // 2. Separate text and image content
+    // 2. Separate text and image content + extract references
     List<Content> textContent = new ArrayList<>();
     List<Content> imageContent = new ArrayList<>();
+    List<Reference> references = new ArrayList<>();
 
     for (Content content : retrievedContent) {
       if (content.textSegment() != null && content.textSegment().metadata() != null) {
-        String type = content.textSegment().metadata().getString("type");
+        var metadata = content.textSegment().metadata();
+        String type = metadata.getString("type");
+
+        // Extract reference info
+        Integer page = metadata.getInteger("page");
+        if (page != null) {
+          references.add(Reference.of(page, type != null ? type : "TEXT", content.textSegment().text(), 80));
+        }
+
         if ("IMAGE".equals(type)) {
           imageContent.add(content);
         } else {
@@ -162,6 +172,16 @@ public ChatMessage query(String userQuery, CacheType cacheType) {
       }
     }
 
+    // Deduplicate references by page (keep first occurrence of each page)
+    List<Reference> uniqueRefs = new ArrayList<>();
+    java.util.Set<Integer> seenPages = new java.util.HashSet<>();
+    for (Reference ref : references) {
+      if (seenPages.add(ref.page())) {
+        uniqueRefs.add(ref);
+      }
+    }
+    references = uniqueRefs;
+
     // 3. Build multimodal prompt with context and images
     String contextText = buildContext(textContent);
     List<dev.langchain4j.data.message.ChatMessage> messages = new ArrayList<>();
@@ -241,7 +261,7 @@ public ChatMessage query(String userQuery, CacheType cacheType) {
     int tokenCount = costTracker.countTokens(responseText);
     double cost = costTracker.calculateCost(config.provider(), config.model(), tokenCount);
 
-    return ChatMessage.assistant(responseText, tokenCount, cost, config.model(), false);
+    return ChatMessage.assistant(responseText, tokenCount, cost, config.model(), false, references);
   }
 
   /**

demos/rag-multimodal/src/main/java/com/redis/vl/demo/rag/ui/ChatController.java

@@ -67,7 +67,8 @@ protected void updateItem(ChatMessage item, boolean empty) {
                 if (empty || item == null) {
                   setGraphic(null);
                 } else {
-                  setGraphic(new MessageBubble(item));
+                  // Pass page navigator to enable click-to-page references
+                  setGraphic(new MessageBubble(item, pdfViewer::goToPage));
                 }
               }
             });
@@ -323,7 +324,8 @@ private void addSystemMessage(String content) {
             0,
             0.0,
             "System",
-            false);
+            false,
+            java.util.List.of());
     messages.add(systemMessage);
     scrollToBottom();
   }

demos/rag-multimodal/src/main/java/com/redis/vl/demo/rag/ui/MessageBubble.java

@@ -1,10 +1,15 @@
 package com.redis.vl.demo.rag.ui;
 
 import com.redis.vl.demo.rag.model.ChatMessage;
+import com.redis.vl.demo.rag.model.Reference;
 import com.redis.vl.demo.rag.service.JTokKitCostTracker;
+import java.util.function.Consumer;
 import javafx.geometry.Insets;
 import javafx.geometry.Pos;
+import javafx.scene.control.Hyperlink;
 import javafx.scene.control.Label;
+import javafx.scene.control.Tooltip;
+import javafx.scene.layout.FlowPane;
 import javafx.scene.layout.HBox;
 import javafx.scene.layout.VBox;
 import javafx.scene.text.Text;
@@ -18,6 +23,7 @@
 public class MessageBubble extends HBox {
 
   private final ChatMessage message;
+  private final Consumer<Integer> pageNavigator;
 
   /**
    * Creates a new message bubble.
@@ -26,7 +32,19 @@ public class MessageBubble extends HBox {
    */
   @SuppressWarnings("this-escape")
   public MessageBubble(ChatMessage message) {
+    this(message, null);
+  }
+
+  /**
+   * Creates a new message bubble with page navigation support.
+   *
+   * @param message Chat message to display
+   * @param pageNavigator Callback for navigating to a page (receives 0-based page number)
+   */
+  @SuppressWarnings("this-escape")
+  public MessageBubble(ChatMessage message, Consumer<Integer> pageNavigator) {
     this.message = message;
+    this.pageNavigator = pageNavigator;
     build();
   }
 
@@ -57,7 +75,7 @@ private void build() {
               message.model());
 
       if (message.fromCache()) {
-        costText += " • ⚡ From Cache";
+        costText += " • From Cache";
         costLabel.getStyleClass().add("cached");
       }
 
@@ -66,6 +84,41 @@ private void build() {
       contentBox.getChildren().add(costLabel);
     }
 
+    // Add references section if available
+    if (message.references() != null && !message.references().isEmpty()) {
+      FlowPane refsPane = new FlowPane();
+      refsPane.setHgap(5);
+      refsPane.setVgap(3);
+      refsPane.getStyleClass().add("references-pane");
+
+      Label refsLabel = new Label("Sources:");
+      refsLabel.getStyleClass().add("refs-label");
+      refsPane.getChildren().add(refsLabel);
+
+      for (Reference ref : message.references()) {
+        Hyperlink pageLink = new Hyperlink("p." + ref.page());
+        pageLink.getStyleClass().add("page-link");
+
+        // Set tooltip with preview
+        String tooltipText = ref.type() + ": " + ref.preview();
+        Tooltip tooltip = new Tooltip(tooltipText);
+        tooltip.setWrapText(true);
+        tooltip.setMaxWidth(300);
+        pageLink.setTooltip(tooltip);
+
+        // Navigate to page on click (convert 1-indexed to 0-indexed)
+        if (pageNavigator != null) {
+          pageLink.setOnAction(e -> pageNavigator.accept(ref.page() - 1));
+        } else {
+          pageLink.setDisable(true);
+        }
+
+        refsPane.getChildren().add(pageLink);
+      }
+
+      contentBox.getChildren().add(refsPane);
+    }
+
     // Style the bubble based on role
     contentBox.getStyleClass().add("message-bubble");
     if (message.role() == ChatMessage.Role.USER) {

demos/rag-multimodal/src/main/resources/styles/app.css

@@ -370,3 +370,41 @@
     -fx-background-color: #E7F3FF;
     -fx-text-fill: #1877F2;
 }
+
+/* References Section in Message Bubbles */
+.references-pane {
+    -fx-padding: 8px 0 0 0;
+    -fx-border-color: #E4E6EB;
+    -fx-border-width: 1px 0 0 0;
+    -fx-border-insets: 8px 0 0 0;
+}
+
+.refs-label {
+    -fx-font-size: 11px;
+    -fx-text-fill: #65676B;
+    -fx-font-weight: 600;
+    -fx-padding: 2px 4px;
+}
+
+.page-link {
+    -fx-font-size: 11px;
+    -fx-text-fill: #1877F2;
+    -fx-padding: 2px 6px;
+    -fx-background-color: #E7F3FF;
+    -fx-background-radius: 10px;
+    -fx-border-color: transparent;
+}
+
+.page-link:hover {
+    -fx-background-color: #CCE4FF;
+    -fx-underline: true;
+}
+
+.page-link:pressed {
+    -fx-background-color: #B3D7FF;
+}
+
+.page-link:disabled {
+    -fx-text-fill: #BCC0C4;
+    -fx-background-color: #F0F2F5;
+}