Package com.tnsai.intelligence.rag

Class ReasoningRAGStrategy

java.lang.Object
com.tnsai.intelligence.rag.ReasoningRAGStrategy
All Implemented Interfaces:
RAGStrategy
public final class ReasoningRAGStrategy extends Object implements RAGStrategy
Descends a document tree with a model choosing the branch, without scoring.

Every other strategy here assumes similarity approximates relevance. That assumption fails on long structured corpora — regulation, specification, contract — where the passage that answers a question shares no vocabulary with it. This one starts at the root and asks a TreeNavigator which child is worth opening, reading titles and summaries rather than content, until it reaches something it considers the answer.

It is the opposite walk from HierarchicalRAGStrategy, which takes similarity hits and expands upward through deterministic parent edges. Both read the same HierarchyIndex; only the direction and the selector differ.

What this strategy keeps for itself

A traversal costs one model call per level, and the model is third-party code. So the runtime, not the provider, owns every bound:

  • maxNodesVisited caps total descent across all roots.
  • maxDepth caps any single path.
  • A returned id that was not offered ends that path — a provider cannot navigate to a node the index does not have, and cannot revisit one either, since HierarchyIndex gives every node a single parent.

None of these are errors. Each ends the descent at the last valid node and returns what was collected, recording why in HierarchyMetadata.STOP_REASON. A partial answer from a real subtree beats failing a request over one bad step, and the stop reason makes "the model wandered" visible rather than something to infer from thin results.

Scores

There is no score model here — nothing is ranked, a node is either where the descent landed or it is not. Landed nodes therefore carry 1.0, and RAGContext.minScore() consequently admits every result. RAGContext.metadataFilters() and RAGContext.maxResults() are applied normally: a strategy that quietly ignored declared filters is exactly the defect TAN-5625 fixed, and this one does not reintroduce it.

Since:
0.14.0

  • Field Details

    • DEFAULT_MAX_NODES_VISITED

      public static final int DEFAULT_MAX_NODES_VISITED
      Default ceiling on nodes opened per retrieval, across all roots.
      See Also:

    • DEFAULT_MAX_DEPTH

      public static final int DEFAULT_MAX_DEPTH
      Default ceiling on the depth of any single descent.
      See Also:

    • SELECTED_SCORE

      public static final double SELECTED_SCORE
      Score carried by every node the descent lands on.
      See Also:

    • NODE_TITLE_METADATA

      public static final String NODE_TITLE_METADATA
      Metadata key holding a node's heading, shown to the navigator.
      See Also:

    • NODE_SUMMARY_METADATA

      public static final String NODE_SUMMARY_METADATA
      Metadata key holding a node's summary, shown to the navigator.

      Absent summaries do not fail the traversal — they leave the navigator choosing between titles alone. Producing them is indexing work and belongs to the ingestion pipeline (TAN-5612), not to retrieval.

      See Also:

  • Constructor Details

    • ReasoningRAGStrategy

      public ReasoningRAGStrategy(HierarchyIndex index, TreeNavigator navigator, String model, Set<String> allowedSources, int maxNodesVisited, int maxDepth)
      Creates a vectorless reasoning strategy.
      Parameters:
      index - tree of documents and parent relationships
      navigator - provider that chooses branches
      model - exact model identifier the navigator serves
      allowedSources - selected source groups; empty allows all
      maxNodesVisited - ceiling on nodes opened per retrieval
      maxDepth - ceiling on the depth of any single descent

    • ReasoningRAGStrategy

      public ReasoningRAGStrategy(HierarchyIndex index, TreeNavigator navigator, String model)
      Creates a strategy with the default bounds.
      Parameters:
      index - tree of documents and parent relationships
      navigator - provider that chooses branches
      model - exact model identifier the navigator serves

  • Method Details

    • name

      public String name()
      Description copied from interface: RAGStrategy
      Returns the unique name of this strategy (e.g., "vector", "keyword", "hybrid").

      Names are compared case-insensitively using Locale.ROOT.

      Specified by:
      name in interface RAGStrategy
      Returns:
      the strategy name, never null

    • retrieve

      public List<RetrievedDocument> retrieve(String query, RAGContext context)
      Description copied from interface: RAGStrategy
      Retrieves documents relevant to the given query.

      Every returned document must exactly match all metadata filters in the context. Implementations apply that constraint before limiting the result to RAGContext.maxResults().

      Specified by:
      retrieve in interface RAGStrategy
      Parameters:
      query - the search query (never null)
      context - retrieval parameters (max results, min score, exact metadata filters)
      Returns:
      an unmodifiable list of retrieved documents, sorted by descending relevance