Class Kb

java.lang.Object
com.oracle.coherence.rag.api.Kb
@ApplicationScoped @Path("/api/kb") public class Kb extends Object
REST API controller for managing document stores and performing cross-store operations in the Coherence RAG framework.

This class provides HTTP endpoints for:

  • Managing multiple document stores
  • Configuring store settings
  • Performing searches across multiple stores
  • Executing chat operations with context retrieval

The API is designed to work with multiple named stores, each with their own configuration and content. Cross-store operations aggregate results from all configured stores to provide comprehensive search and chat capabilities.

All endpoints support CORS for web application integration and use JSON for request/response payloads where applicable.

Since:
25.09
Author:
Aleks Seovic 2025.07.04

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    Kb.ConfiguredStore
    Record representing a configured store with its name and configuration.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Kb()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    jakarta.ws.rs.core.Response
    chat(Store.ChatRequest req)
    Executes a chat request with context retrieval across all stores.
    jakarta.ws.rs.core.Response
    configureStore(String storeName, StoreConfig config)
    Creates or updates the configuration for a specific store.
    void
    cors()
    Handles CORS preflight requests for the main API endpoint.
    void
    corsChat()
    Handles CORS preflight requests for the chat endpoint.
    void
    corsSearch()
    Handles CORS preflight requests for the search endpoint.
    void
    corsStoreConfig(String name)
    Handles CORS preflight requests for store configuration endpoints.
    jakarta.ws.rs.core.Response
    search(Store.SearchRequest req)
    Performs a search across all configured stores.
    Store
    store(String storeName)
    Returns a specific store instance for sub-resource operations.
    jakarta.ws.rs.core.Response
    storeConfig(String storeName)
    Returns the configuration for a specific store.
    jakarta.ws.rs.core.Response
    storeList()
    Returns a list of all configured stores with their configurations.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Kb

      public Kb()

  • Method Details

    • cors

      @OPTIONS @CrossOrigin public void cors()
      Handles CORS preflight requests for the main API endpoint.

    • corsSearch

      @OPTIONS @CrossOrigin @Path("search") public void corsSearch()
      Handles CORS preflight requests for the search endpoint.

    • corsChat

      @OPTIONS @CrossOrigin @Path("chat") public void corsChat()
      Handles CORS preflight requests for the chat endpoint.

    • corsStoreConfig

      @OPTIONS @CrossOrigin @Path("config/{storeName}") public void corsStoreConfig(@PathParam("storeName") String name)
      Handles CORS preflight requests for store configuration endpoints.
      Parameters:
      name - the store name (unused but required for path matching)

    • store

      @Path("{storeName}") public Store store(@PathParam("storeName") String storeName)
      Returns a specific store instance for sub-resource operations.

      This method provides access to individual store operations by delegating to the Store resource class. The returned Store handles document management, indexing, and search operations for the specified store.

      Parameters:
      storeName - the name of the store to access
      Returns:
      a Store instance for the specified store name
      Throws:
      IllegalArgumentException - if the store name is null or invalid

    • storeList

      @GET @Produces("application/json") public jakarta.ws.rs.core.Response storeList()
      Returns a list of all configured stores with their configurations.

      This endpoint provides an overview of all available stores in the system, including their names and current configurations. The list is sorted alphabetically by store name for consistent ordering.

      Returns:
      a Response containing a list of ConfiguredStore records

    • storeConfig

      @GET @Path("config/{storeName}") @Produces("application/json") public jakarta.ws.rs.core.Response storeConfig(@PathParam("storeName") String storeName)
      Returns the configuration for a specific store.

      This endpoint allows clients to retrieve the current configuration settings for a named store, including embedding model settings, chunk parameters, and indexing configuration.

      Parameters:
      storeName - the name of the store whose configuration to retrieve
      Returns:
      a Response containing the StoreConfig, or 404 if store not found

    • configureStore

      @PUT @Path("config/{storeName}") @Consumes("application/json") public jakarta.ws.rs.core.Response configureStore(@PathParam("storeName") String storeName, StoreConfig config)
      Creates or updates the configuration for a specific store.

      This endpoint allows clients to configure store settings including embedding models, document chunking parameters, and indexing options. If the store doesn't exist, it will be created with the provided configuration.

      Parameters:
      storeName - the name of the store to configure
      config - the new configuration to apply
      Returns:
      a Response with no content indicating successful configuration
      Throws:
      IllegalArgumentException - if the store name or config is invalid

    • search

      @POST @Consumes("application/json") @Produces("application/json") @Path("search") public jakarta.ws.rs.core.Response search(Store.SearchRequest req)
      Performs a search across all configured stores.

      This endpoint executes a search query against all available stores and aggregates the results, providing a unified view of matching document chunks across the entire system. Results are ranked by score and limited to the requested maximum number.

      Parameters:
      req - the search request containing query parameters
      Returns:
      a Response containing SearchResult with aggregated results and timing
      Throws:
      IllegalArgumentException - if the search request is invalid

    • chat

      @POST @Path("chat") @Consumes("application/json") @Produces("text/plain") public jakarta.ws.rs.core.Response chat(Store.ChatRequest req)
      Executes a chat request with context retrieval across all stores.

      This endpoint processes a chat request by first retrieving relevant context from all configured stores, then using a chat model to generate a response. The response is streamed back to the client for real-time interaction.

      Parameters:
      req - the chat request containing the question and parameters
      Returns:
      a Response containing a streaming answer
      Throws:
      IllegalArgumentException - if the chat request is invalid
      RuntimeException - if the chat model is unavailable