feat(query): add runtime parameters support for vector queries

Implements runtime parameter support for VectorQuery and VectorRangeQuery
to enable dynamic query-time tuning without rebuilding indexes. Brings
feature parity with Python redis-vl PR #439.

Runtime Parameters Added:
- efRuntime: HNSW dynamic candidate list size for improved recall
- epsilon: Range search approximation factor for VectorRangeQuery
- searchWindowSize: SVS-VAMANA KNN search window size
- useSearchHistory: SVS-VAMANA search buffer control (OFF/ON/AUTO)
- searchBufferCapacity: SVS-VAMANA compression tuning parameter

Implementation Details:
- Added fields, getters/setters with validation to VectorQuery
- Added fields, getters/setters with validation to VectorRangeQuery
- Updated Builder classes with fluent API methods
- Parameters passed through toParams() map for Redis execution
- All parameters optional (null by default) for backward compatibility

Testing:
- Created RuntimeParametersIntegrationTest with 12 comprehensive tests
- All parameter validation tested (positive, non-negative, enum checks)
- Functional behavior verified with actual Redis indexes
- All 12 integration tests passing

Documentation:
- Javadoc added to all builder methods and setters
- Added FT.AGGREGATE limitation notes to HybridQuery and MultiVectorQuery
- References to Python PR #439 included throughout

Note: Runtime parameters are NOT supported in FT.AGGREGATE queries
(HybridQuery, MultiVectorQuery). Use VectorQuery or VectorRangeQuery
if runtime parameter support is required.

Author: bsbodden

core/src/main/java/com/redis/vl/query/HybridQuery.java

@@ -19,6 +19,11 @@
  * <p>It allows you to perform a hybrid search using both text and vector similarity. It scores
  * documents based on a weighted combination of text and vector similarity.
  *
+ * <p><strong>Note on Runtime Parameters:</strong> HybridQuery uses Redis FT.AGGREGATE for
+ * aggregation-based hybrid search. As of Redis Stack 7.2+, runtime parameters (efRuntime, epsilon,
+ * etc.) are NOT supported in FT.AGGREGATE queries. If you need runtime parameter support, use
+ * {@link VectorQuery} or {@link VectorRangeQuery} instead. See Python PR #439 for details.
+ *
  * <p>Python equivalent:
  *
  * <pre>

core/src/main/java/com/redis/vl/query/MultiVectorQuery.java

@@ -17,6 +17,12 @@
  * <p>Vectors may be of different size and datatype, but must be indexed using the 'cosine'
  * distance_metric.
  *
+ * <p><strong>Note on Runtime Parameters:</strong> MultiVectorQuery uses Redis FT.AGGREGATE for
+ * aggregation-based multi-vector search. As of Redis Stack 7.2+, runtime parameters (efRuntime,
+ * epsilon, etc.) are NOT supported in FT.AGGREGATE queries. If you need runtime parameter support
+ * with single-vector queries, use {@link VectorQuery} or {@link VectorRangeQuery} instead. See
+ * Python PR #439 for details.
+ *
  * <p>Ported from Python: redisvl/query/aggregate.py:257-400 (MultiVectorQuery class)
  *
  * <p>Python equivalent:

core/src/main/java/com/redis/vl/query/VectorQuery.java

@@ -43,6 +43,15 @@ public class VectorQuery {
   /** EF runtime parameter for HNSW algorithm */
   private Integer efRuntime;
 
+  /** Search window size for SVS-VAMANA algorithm (Python PR #439) */
+  private Integer searchWindowSize;
+
+  /** Search history usage for SVS-VAMANA algorithm: OFF, ON, AUTO (Python PR #439) */
+  private String useSearchHistory;
+
+  /** Search buffer capacity for SVS-VAMANA algorithm (Python PR #439) */
+  private Integer searchBufferCapacity;
+
   /** Filter query for pre-filtering */
   private Filter filter;
 
@@ -76,6 +85,9 @@ private VectorQuery(
       String hybridField,
       String hybridQuery,
       Integer efRuntime,
+      Integer searchWindowSize,
+      String useSearchHistory,
+      Integer searchBufferCapacity,
       List<String> returnFields,
       boolean normalizeVectorDistance,
       String sortBy,
@@ -92,6 +104,9 @@ private VectorQuery(
     this.hybridField = hybridField;
     this.hybridQuery = hybridQuery;
     this.efRuntime = efRuntime;
+    this.searchWindowSize = searchWindowSize;
+    this.useSearchHistory = useSearchHistory;
+    this.searchBufferCapacity = searchBufferCapacity;
     this.returnFields = returnFields;
     this.normalizeVectorDistance = normalizeVectorDistance;
     this.sortBy = sortBy;
@@ -293,11 +308,25 @@ public Map<String, Object> toParams() {
     byte[] vectorBytes = ArrayUtils.floatArrayToBytes(vector);
     params.put("vec", vectorBytes);
 
-    // Add EF runtime if specified (for HNSW)
+    // Add runtime parameters if specified
+    // EF runtime for HNSW
     if (efRuntime != null) {
       params.put("ef_runtime", efRuntime);
     }
 
+    // SVS-VAMANA runtime parameters (Python PR #439)
+    if (searchWindowSize != null) {
+      params.put("search_window_size", searchWindowSize);
+    }
+
+    if (useSearchHistory != null) {
+      params.put("use_search_history", useSearchHistory);
+    }
+
+    if (searchBufferCapacity != null) {
+      params.put("search_buffer_capacity", searchBufferCapacity);
+    }
+
     return params;
   }
 
@@ -407,11 +436,81 @@ public Integer getEfRuntime() {
    * Set the EF runtime parameter for HNSW
    *
    * @param efRuntime EF runtime value
+   * @throws IllegalArgumentException if efRuntime is not positive
    */
   public void setEfRuntime(int efRuntime) {
+    if (efRuntime <= 0) {
+      throw new IllegalArgumentException("efRuntime must be positive");
+    }
     this.efRuntime = efRuntime;
   }
 
+  /**
+   * Get the search window size for SVS-VAMANA
+   *
+   * @return Search window size value
+   */
+  public Integer getSearchWindowSize() {
+    return searchWindowSize;
+  }
+
+  /**
+   * Set the search window size parameter for SVS-VAMANA
+   *
+   * @param searchWindowSize Search window size value
+   * @throws IllegalArgumentException if searchWindowSize is not positive
+   */
+  public void setSearchWindowSize(int searchWindowSize) {
+    if (searchWindowSize <= 0) {
+      throw new IllegalArgumentException("searchWindowSize must be positive");
+    }
+    this.searchWindowSize = searchWindowSize;
+  }
+
+  /**
+   * Get the use search history parameter for SVS-VAMANA
+   *
+   * @return Use search history value (OFF, ON, or AUTO)
+   */
+  public String getUseSearchHistory() {
+    return useSearchHistory;
+  }
+
+  /**
+   * Set the use search history parameter for SVS-VAMANA
+   *
+   * @param useSearchHistory Use search history value (must be OFF, ON, or AUTO)
+   * @throws IllegalArgumentException if useSearchHistory is not one of the allowed values
+   */
+  public void setUseSearchHistory(String useSearchHistory) {
+    if (useSearchHistory != null && !useSearchHistory.matches("OFF|ON|AUTO")) {
+      throw new IllegalArgumentException("useSearchHistory must be one of: OFF, ON, AUTO");
+    }
+    this.useSearchHistory = useSearchHistory;
+  }
+
+  /**
+   * Get the search buffer capacity for SVS-VAMANA
+   *
+   * @return Search buffer capacity value
+   */
+  public Integer getSearchBufferCapacity() {
+    return searchBufferCapacity;
+  }
+
+  /**
+   * Set the search buffer capacity parameter for SVS-VAMANA
+   *
+   * @param searchBufferCapacity Search buffer capacity value
+   * @throws IllegalArgumentException if searchBufferCapacity is not positive
+   */
+  public void setSearchBufferCapacity(int searchBufferCapacity) {
+    if (searchBufferCapacity <= 0) {
+      throw new IllegalArgumentException("searchBufferCapacity must be positive");
+    }
+    this.searchBufferCapacity = searchBufferCapacity;
+  }
+
   /**
    * Get the fields to return in results
    *
@@ -560,6 +659,9 @@ public Builder() {
     private String hybridField;
     private String hybridQuery;
     private Integer efRuntime;
+    private Integer searchWindowSize;
+    private String useSearchHistory;
+    private Integer searchBufferCapacity;
     private List<String> returnFields;
     private boolean normalizeVectorDistance = false;
     private String sortBy;
@@ -774,8 +876,12 @@ public Builder withHybridSearch(String field, String query) {
      *
      * @param efRuntime EF runtime value
      * @return This builder
+     * @throws IllegalArgumentException if efRuntime is not positive
      */
     public Builder efRuntime(Integer efRuntime) {
+      if (efRuntime != null && efRuntime <= 0) {
+        throw new IllegalArgumentException("efRuntime must be positive");
+      }
       this.efRuntime = efRuntime;
       return this;
     }
@@ -785,12 +891,73 @@ public Builder efRuntime(Integer efRuntime) {
      *
      * @param efRuntime EF runtime value
      * @return This builder
+     * @throws IllegalArgumentException if efRuntime is not positive
      */
     public Builder withEfRuntime(int efRuntime) {
+      if (efRuntime <= 0) {
+        throw new IllegalArgumentException("efRuntime must be positive");
+      }
       this.efRuntime = efRuntime;
       return this;
     }
 
+    /**
+     * Set the search window size parameter for SVS-VAMANA algorithm.
+     *
+     * <p>Controls the KNN search window size. Must be positive.
+     *
+     * <p>Python PR #439: SVS-VAMANA runtime parameter support
+     *
+     * @param searchWindowSize Search window size (must be positive)
+     * @return This builder
+     * @throws IllegalArgumentException if searchWindowSize is not positive
+     */
+    public Builder searchWindowSize(Integer searchWindowSize) {
+      if (searchWindowSize != null && searchWindowSize <= 0) {
+        throw new IllegalArgumentException("searchWindowSize must be positive");
+      }
+      this.searchWindowSize = searchWindowSize;
+      return this;
+    }
+
+    /**
+     * Set the use search history parameter for SVS-VAMANA algorithm.
+     *
+     * <p>Controls search buffer usage. Valid values: "OFF", "ON", "AUTO"
+     *
+     * <p>Python PR #439: SVS-VAMANA runtime parameter support
+     *
+     * @param useSearchHistory Search history mode (OFF, ON, or AUTO)
+     * @return This builder
+     * @throws IllegalArgumentException if useSearchHistory is not one of: OFF, ON, AUTO
+     */
+    public Builder useSearchHistory(String useSearchHistory) {
+      if (useSearchHistory != null && !useSearchHistory.matches("OFF|ON|AUTO")) {
+        throw new IllegalArgumentException("useSearchHistory must be one of: OFF, ON, AUTO");
+      }
+      this.useSearchHistory = useSearchHistory;
+      return this;
+    }
+
+    /**
+     * Set the search buffer capacity parameter for SVS-VAMANA algorithm.
+     *
+     * <p>Controls compression tuning. Must be positive.
+     *
+     * <p>Python PR #439: SVS-VAMANA runtime parameter support
+     *
+     * @param searchBufferCapacity Search buffer capacity (must be positive)
+     * @return This builder
+     * @throws IllegalArgumentException if searchBufferCapacity is not positive
+     */
+    public Builder searchBufferCapacity(Integer searchBufferCapacity) {
+      if (searchBufferCapacity != null && searchBufferCapacity <= 0) {
+        throw new IllegalArgumentException("searchBufferCapacity must be positive");
+      }
+      this.searchBufferCapacity = searchBufferCapacity;
+      return this;
+    }
+
     /**
      * Set the fields to return in results
      *
@@ -995,6 +1162,9 @@ public VectorQuery build() {
           hybridField,
           hybridQuery,
           efRuntime,
+          searchWindowSize,
+          useSearchHistory,
+          searchBufferCapacity,
           returnFields,
           normalizeVectorDistance,
           sortBy,