Package com.tnsai.server.rag

Class RagService

java.lang.Object
com.tnsai.server.rag.RagService
public final class RagService extends Object
Orchestrates the RAG pipeline for a single session.

Holds an InMemoryKnowledgeBase, manages directory indexing via FileIndexer, and provides BM25 + TF-IDF hybrid search and context-prompt building.

Thread-safe: may be called from multiple virtual threads concurrently. Indexing is serialised via a lock; reads (search) are concurrent.

  • Field Details

    • CHAT_SOURCE

      public static final String CHAT_SOURCE
      Canonical chat source name for a session corpus.

      Agents that may be grounded on one declare it as their MEMORY chat knowledge, and the binding attachChatTo(com.tnsai.agents.Agent) supplies must carry exactly this name — that pair is what stops chat grounding on a source nobody declared.

      Since:
      0.16.0
      See Also:

    • CHAT_TOP_K

      public static final int CHAT_TOP_K
      How many results the session corpus gives chat. The agent's MEMORY chat knowledge must search with the same topK, or it refuses the binding.
      Since:
      0.18.0
      See Also:

  • Constructor Details

    • RagService

      public RagService()

  • Method Details

    • indexDirectory

      public void indexDirectory(Path path, Consumer<FileIndexer.IndexProgress> progressCallback) throws IOException
      Indexes all supported files under the given directory.
      Parameters:
      path - directory to index
      progressCallback - receives progress updates (may be null)
      Throws:
      IOException - if the directory cannot be walked

    • search

      public List<com.tnsai.knowledge.SearchResult> search(String query, int topK)
      Searches the knowledge base.
      Parameters:
      query - search query (natural language)
      topK - maximum number of results
      Returns:
      list of search results, ordered by relevance

    • getStatus

      public IndexStatus getStatus()
      Returns a snapshot of the current index status.

    • clear

      public void clear()
      Clears the knowledge base and resets all counters.

    • buildContextPrompt

      public String buildContextPrompt(String query, int topK)
      Searches the knowledge base and formats the results as a context block suitable for prepending to a user message before LLM invocation.

      Retrieved content and provenance are escaped and enclosed in the canonical untrusted-context fence shared with native agent RAG.

      Parameters:
      query - the user's message / query
      topK - maximum number of context chunks to include
      Returns:
      the augmented prompt, or the original query if no context is found

    • attachChatTo

      public void attachChatTo(com.tnsai.agents.Agent agent)
      Attaches this session corpus to an agent as a canonical live chat binding. Built-in development chat then grounds on the original user message instead of a rewritten prompt.

      The binding holds the corpus rather than copying it, so documents indexed later in the session are visible without rebinding. The agent must have declared CHAT_SOURCE as its MEMORY chat knowledge, searched with CHAT_TOP_K, or it refuses the binding.

      Callers rebind per message; each attach releases the previous binding and never the corpus, which this service owns.

      Parameters:
      agent - conversation agent

    • addDocument

      public String addDocument(String content, Map<String,Object> metadata)
      Adds a document to the knowledge base.
      Parameters:
      content - the document text content
      metadata - optional metadata (may be null)
      Returns:
      the generated document ID

    • removeDocument

      public boolean removeDocument(String documentId)
      Removes a document from the knowledge base.
      Parameters:
      documentId - the document ID
      Returns:
      true if the document was found and removed

    • listDocuments

      public List<RagService.DocumentInfo> listDocuments()
      Lists all documents in the knowledge base with basic metadata.
      Returns:
      list of document info records

    • getDocument

      public Optional<com.tnsai.knowledge.Document> getDocument(String documentId)
      Gets a specific document by ID.
      Parameters:
      documentId - the document ID
      Returns:
      the document, or empty if not found