Package com.tnsai.rag

package com.tnsai.rag
Canonical RAG configuration and retrieval contracts.

Ownership

  • tnsai-core owns immutable configuration, request/result, lifecycle, and provider contracts.
  • tnsai-intelligence owns source loaders, strategy execution, ranking, reranking, deduplication, and cache implementations.
  • Chat and action entry points own prompt/context rendering. The engine never emits <tnsai-memory> or _rag_context content. Consequently Search.contextWindow() is a rendering budget owned by the caller, not the engine — see the invariant below.

Runtime invariants

  • An engine is created from one owner's canonical KnowledgeSourceConfig set and closed with that owner.
  • Every cache key and backend namespace includes the complete RetrievalScope and the request's metadata filters; query-only or source-only global caches are forbidden. See RetrievalRequest.metadataFilters() for the digest rules a key must follow.
  • The engine neither validates nor applies Search.contextWindow(). It bounds assembled prompt text, and the engine returns RetrievalEvidence rather than prompt text, so there is nothing for it to bound. Ordinary retrieval evidence volume is governed by topK, topN, and minScore. Whichever entry point renders evidence into a prompt applies contextWindow there and reports truncation through its own channel — on the action path, RetrievalSpi.RETRIEVED_CONTEXT_TRUNCATED_KEY. An engine-path caller that never renders evidence into a prompt therefore has no window to enforce.
  • use = DIRECT knowledge is an action and chat-turn policy, not an engine one. Each DIRECT entry is given whole within its maxTokens, or a quarter of the model's input window, and a source over that budget fails rather than being truncated. DIRECT bypasses query ranking but retains source admission, exact metadata filters, configuration/provider checks, and request cancellation.
  • Providers check cooperative cancellation and absolute deadlines between blocking phases and configure backend-native timeouts.
  • Empty evidence is a successful result. Failures are never encoded as empty evidence or swallowed.
  • Evidence retains source, document, score, rank, and strategy provenance through all ranking and formatting phases.