feat(demo): add semantic router with response classifier and UX improvements

Adds semantic router integration and several UX improvements to the RAG demo:

- SemanticRouterPanel: New panel for configuring semantic routing with YAML/JSON
  config loading, enable toggle, sample routes, and testing functionality
- Response classifier: Filters out source references when LLM response indicates
  no relevant information found in context (uses SemanticRouter with permissive
  threshold for semantic matching)
- Settings panel improvements: Document section moved to top for easier PDF
  upload access, panel now opens by default on startup
- VerticalTabPane: Fixed collapsed state initialization so selectTab() properly
  expands the panel
- Updated tests to accommodate RAGService constructor changes

Author: bsbodden

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

@@ -7,6 +7,7 @@
 import com.redis.vl.extensions.cache.CacheHit;
 import com.redis.vl.extensions.cache.LangCacheSemanticCache;
 import com.redis.vl.extensions.cache.SemanticCache;
+import com.redis.vl.extensions.router.SemanticRouter;
 import com.redis.vl.langchain4j.RedisVLContentRetriever;
 import com.redis.vl.langchain4j.RedisVLDocumentStore;
 import dev.langchain4j.data.image.Image;
@@ -48,6 +49,7 @@ public class RAGService {
   private final LLMConfig config;
   private final SemanticCache localCache;
   private final LangCacheSemanticCache langCache;
+  private final SemanticRouter responseClassifier;
 
   private static final String SYSTEM_PROMPT =
       """
@@ -68,6 +70,7 @@ public class RAGService {
    * @param config LLM configuration
    * @param localCache Local Redis-based semantic cache
    * @param langCache LangCache cloud service for semantic caching (can be null)
+   * @param responseClassifier Semantic router for classifying responses (can be null)
    */
   public RAGService(
       RedisVLContentRetriever contentRetriever,
@@ -76,14 +79,16 @@ public RAGService(
       CostTracker costTracker,
       LLMConfig config,
       SemanticCache localCache,
-      LangCacheSemanticCache langCache) {
+      LangCacheSemanticCache langCache,
+      SemanticRouter responseClassifier) {
     this.contentRetriever = contentRetriever;
     this.documentStore = documentStore;
     this.chatModel = chatModel;
     this.costTracker = costTracker;
     this.config = config;
     this.localCache = localCache;
     this.langCache = langCache;
+    this.responseClassifier = responseClassifier;
   }
 
   /**
@@ -237,7 +242,21 @@ public ChatMessage query(String userQuery, CacheType cacheType) {
     Response<AiMessage> response = chatModel.generate(messages);
     String responseText = response.content().text();
 
-    // 4. Store in cache based on cache type
+    // 5. Clear references if response indicates no relevant information
+    if (responseClassifier != null) {
+      System.out.println("→ Classifying response: " + responseText.substring(0, Math.min(100, responseText.length())) + "...");
+      var routeMatch = responseClassifier.route(responseText);
+      System.out.println("→ Route match result: " + (routeMatch != null ? "name=" + routeMatch.getName() + ", distance=" + routeMatch.getDistance() : "null"));
+      if (routeMatch != null && routeMatch.getName() != null) {
+        references = List.of();
+        System.out.println("→ Response classified as '" + routeMatch.getName()
+            + "' (distance: " + routeMatch.getDistance() + "), clearing references");
+      }
+    } else {
+      System.out.println("→ Response classifier is NULL - not classifying response");
+    }
+
+    // 6. Store in cache based on cache type
     if (cacheType == CacheType.LOCAL && localCache != null) {
       System.out.println("→ Storing to Local Cache: " + userQuery);
       localCache.store(userQuery, responseText);
@@ -275,4 +294,5 @@ private String buildContext(List<Content> content) {
         .map(c -> c.textSegment().text())
         .collect(Collectors.joining("\n\n"));
   }
+
 }

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

@@ -4,6 +4,8 @@
 import com.redis.vl.demo.rag.model.LLMConfig;
 import com.redis.vl.extensions.cache.LangCacheSemanticCache;
 import com.redis.vl.extensions.cache.SemanticCache;
+import com.redis.vl.extensions.router.Route;
+import com.redis.vl.extensions.router.SemanticRouter;
 import com.redis.vl.index.SearchIndex;
 import com.redis.vl.langchain4j.RedisVLContentRetriever;
 import com.redis.vl.langchain4j.RedisVLDocumentStore;
@@ -157,7 +159,10 @@ public RAGService createRAGService(LLMConfig config) {
     // Create chat model based on provider
     ChatLanguageModel chatModel = createChatModel(config);
 
-    return new RAGService(retriever, documentStore, chatModel, costTracker, config, localCache, langCache);
+    // Create response classifier to detect "no relevant info" responses
+    SemanticRouter responseClassifier = createResponseClassifier();
+
+    return new RAGService(retriever, documentStore, chatModel, costTracker, config, localCache, langCache, responseClassifier);
   }
 
   /**
@@ -233,6 +238,80 @@ public CostTracker getCostTracker() {
     return costTracker;
   }
 
+  /**
+   * Creates a SemanticRouter with the given routes.
+   *
+   * @param routes List of routes to configure
+   * @return SemanticRouter instance
+   * @throws IllegalStateException if services not initialized
+   */
+  public SemanticRouter createSemanticRouter(List<Route> routes) {
+    return createSemanticRouter("rag_demo_router", routes);
+  }
+
+  /**
+   * Creates a SemanticRouter with a custom name and routes.
+   *
+   * @param name Name for the router index
+   * @param routes List of routes to configure
+   * @return SemanticRouter instance
+   * @throws IllegalStateException if services not initialized
+   */
+  public SemanticRouter createSemanticRouter(String name, List<Route> routes) {
+    if (jedis == null || embeddingModel == null) {
+      throw new IllegalStateException("Services not initialized. Call initialize() first.");
+    }
+
+    LangChain4JVectorizer vectorizer = new LangChain4JVectorizer(
+        "all-minilm-l6-v2", embeddingModel, VECTOR_DIM);
+
+    return SemanticRouter.builder()
+        .name(name)
+        .routes(routes)
+        .vectorizer(vectorizer)
+        .jedis(jedis)
+        .overwrite(true)  // Recreate index when routes change
+        .build();
+  }
+
+  /**
+   * Creates a response classifier router for detecting "no relevant information" responses.
+   * This router matches LLM responses that indicate the context didn't contain
+   * relevant information to answer the user's question.
+   *
+   * @return SemanticRouter configured for response classification
+   * @throws IllegalStateException if services not initialized
+   */
+  public SemanticRouter createResponseClassifier() {
+    // Reference phrases that indicate "no relevant information found"
+    // These should match typical LLM responses when context doesn't have the answer
+    List<String> noInfoReferences = List.of(
+        "The context provided does not contain information",
+        "The provided context does not contain information about this topic",
+        "I cannot find relevant information in the given context",
+        "The context doesn't mention anything about this",
+        "Based on the provided context, I don't have information on this",
+        "This topic is not covered in the available context",
+        "I don't have enough information in the context to answer",
+        "The documents provided do not address this question",
+        "There is no relevant information available to answer this",
+        "I cannot determine this from the given context",
+        "The context does not include details about this subject",
+        "does not contain information about",
+        "I'm unable to find information about this in the context"
+    );
+
+    Route noInfoRoute = Route.builder()
+        .name("no-relevant-info")
+        .references(noInfoReferences)
+        .distanceThreshold(1.5)  // Very permissive - cosine distance range is 0-2
+        .build();
+
+    SemanticRouter classifier = createSemanticRouter("response_classifier", List.of(noInfoRoute));
+    System.out.println("Response classifier initialized with " + noInfoReferences.size() + " reference phrases, threshold: 1.5");
+    return classifier;
+  }
+
   /**
    * Closes all resources.
    */

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

@@ -7,7 +7,11 @@
 import com.redis.vl.demo.rag.model.LogEntry.Category;
 import com.redis.vl.demo.rag.service.EventLogger;
 import com.redis.vl.demo.rag.service.RAGService;
+import com.redis.vl.extensions.router.Route;
+import com.redis.vl.extensions.router.RouteMatch;
+import com.redis.vl.extensions.router.SemanticRouter;
 import java.io.File;
+import java.util.List;
 import java.util.concurrent.ExecutorService;
 import java.util.concurrent.Executors;
 import javafx.application.Platform;
@@ -27,7 +31,8 @@
 public class ChatController extends BorderPane {
 
   private static final int SETTINGS_TAB = 0;
-  private static final int LOG_TAB = 1;
+  private static final int ROUTER_TAB = 1;
+  private static final int LOG_TAB = 2;
 
   private final ObservableList<ChatMessage> messages = FXCollections.observableArrayList();
   private final ListView<ChatMessage> messageListView;
@@ -37,12 +42,14 @@ public class ChatController extends BorderPane {
   private final VerticalTabPane tabPane;
   private final SettingsPanel settingsPanel;
   private final LogPanel logPanel;
+  private final SemanticRouterPanel routerPanel;
   private final EventLogger eventLogger;
   private File currentPdfFile;
 
   private RAGService ragService;
   private com.redis.vl.demo.rag.service.ServiceFactory serviceFactory;
   private com.redis.vl.demo.rag.service.PDFIngestionService pdfIngestionService;
+  private SemanticRouter semanticRouter;
   private final ExecutorService executor = Executors.newSingleThreadExecutor();
   private final AppConfig config = AppConfig.getInstance();
 
@@ -65,10 +72,19 @@ public ChatController() {
     logPanel = new LogPanel();
     logPanel.setEventLogger(eventLogger);
 
+    // Semantic router panel content
+    routerPanel = new SemanticRouterPanel();
+    routerPanel.setOnEnabledChange(this::onRouterEnabledChange);
+
     // Vertical tab pane (right side)
+    // Icons: Settings=gear, Router=fork, Log=scroll/document
     tabPane = new VerticalTabPane();
-    tabPane.addTab("⚙", "Settings", settingsPanel);
-    tabPane.addTab("📋", "Event Log", logPanel);
+    tabPane.addTab("\u2699", "Settings", settingsPanel);           // Tab 0 - Settings (top) - gear
+    tabPane.addTab("\u2443", "Semantic Router", routerPanel);      // Tab 1 - Router (top) - fork symbol
+    tabPane.addTab("\u2261", "Event Log", logPanel, true);         // Tab 2 - Log (bottom) - identical sign (≡)
+
+    // Start with settings panel open (for PDF upload)
+    tabPane.selectTab(SETTINGS_TAB);
 
     // Update log badge when count changes
     logPanel.setCountListener(count -> {
@@ -169,6 +185,31 @@ private void sendMessage() {
     executor.submit(
         () -> {
           try {
+            // Check semantic router BEFORE RAG if enabled
+            if (routerPanel.isRouterEnabled() && semanticRouter != null) {
+              RouteMatch match = semanticRouter.route(userInput);
+              if (match.getName() != null) {
+                // Query blocked by semantic router
+                String routeName = match.getName();
+                double distance = match.getDistance() != null ? match.getDistance() : 0.0;
+                Platform.runLater(() -> {
+                  long elapsed = System.currentTimeMillis() - startTime;
+                  String blockMessage = String.format(
+                      "This query was blocked by the semantic router.\n\n" +
+                      "Matched route: %s\nDistance: %.4f\n\n" +
+                      "The query appears to be off-topic or outside the scope of the document.",
+                      routeName, distance);
+                  addSystemMessage(blockMessage);
+                  eventLogger.warn(Category.RETRIEVAL, "Query BLOCKED by router: " + routeName + " (distance: " + String.format("%.4f", distance) + ")");
+                  setInputEnabled(true);
+                  settingsPanel.setStatus("Ready");
+                  inputField.requestFocus();
+                });
+                return; // Don't proceed to RAG
+              }
+              eventLogger.debug(Category.RETRIEVAL, "Router check passed - no route match");
+            }
+
             ChatMessage response = ragService.query(userInput, cacheType);
             long elapsed = System.currentTimeMillis() - startTime;
 
@@ -355,6 +396,70 @@ public PDFViewerPanel getPdfViewer() {
     return pdfViewer;
   }
 
+  /**
+   * Gets the semantic router panel for external configuration.
+   *
+   * @return SemanticRouterPanel instance
+   */
+  public SemanticRouterPanel getRouterPanel() {
+    return routerPanel;
+  }
+
+  /**
+   * Handles router enabled/disabled toggle changes.
+   *
+   * @param enabled Whether routing is now enabled
+   */
+  private void onRouterEnabledChange(boolean enabled) {
+    if (enabled) {
+      // Initialize the semantic router with sample routes
+      if (semanticRouter == null && serviceFactory != null) {
+        eventLogger.info(Category.RETRIEVAL, "Initializing semantic router...");
+        routerPanel.setStatus("Initializing router...");
+
+        executor.submit(() -> {
+          try {
+            // Convert sample routes to Route objects
+            List<Route> routes = routerPanel.getSampleRoutes().stream()
+                .map(sample -> Route.builder()
+                    .name(sample.name())
+                    .references(sample.references())
+                    .distanceThreshold(sample.threshold())
+                    .build())
+                .toList();
+
+            semanticRouter = serviceFactory.createSemanticRouter(routes);
+            routerPanel.setRouter(semanticRouter);
+
+            Platform.runLater(() -> {
+              eventLogger.info(Category.RETRIEVAL, "Semantic router initialized with " + routes.size() + " routes");
+              routerPanel.setStatus("Router ready - " + routes.size() + " routes");
+              addSystemMessage("Semantic router enabled with " + routes.size() + " routes:\n• " +
+                  String.join("\n• ", routes.stream().map(Route::getName).toList()));
+            });
+          } catch (Exception e) {
+            Platform.runLater(() -> {
+              eventLogger.error(Category.RETRIEVAL, "Router initialization failed: " + e.getMessage());
+              routerPanel.setStatus("Router initialization failed");
+              routerPanel.setRouterEnabled(false);  // Disable toggle on failure
+              addSystemMessage("Failed to initialize semantic router: " + e.getMessage());
+            });
+          }
+        });
+      } else if (semanticRouter != null) {
+        eventLogger.info(Category.RETRIEVAL, "Semantic router enabled");
+        addSystemMessage("Semantic router enabled. Off-topic queries will be blocked.");
+      } else {
+        eventLogger.warn(Category.RETRIEVAL, "Cannot enable router - services not initialized");
+        routerPanel.setStatus("Connect to Redis first");
+        routerPanel.setRouterEnabled(false);
+      }
+    } else {
+      eventLogger.info(Category.RETRIEVAL, "Semantic router disabled");
+      addSystemMessage("Semantic router disabled. All queries will be processed.");
+    }
+  }
+
   /**
    * Truncates a string to the specified length.
    *