Package com.tnsai.intelligence.rag.hierarchy

Class HierarchyIndex

java.lang.Object
com.tnsai.intelligence.rag.hierarchy.HierarchyIndex
public final class HierarchyIndex extends Object
Immutable hierarchy document index.

The identity snapshot is computed once, on first use, and cached. Callers that select a hierarchical strategy must force the full structural check with validate() before retrieval enters its failure-policy boundary: a malformed hierarchy is a configuration fault, not a transport failure, so it must not be routed through @Search.onFailure.

Since:
0.13.0

  • Constructor Details

    • HierarchyIndex

      public HierarchyIndex(List<RetrievedDocument> documents)
      Creates an index over hierarchy documents.
      Parameters:
      documents - documents with canonical hierarchy metadata

  • Method Details

    • documents

      public List<RetrievedDocument> documents()
      Returns the source documents in declaration order.
      Returns:
      immutable document list

    • size

      public int size()
      Returns the validated index size.
      Returns:
      number of unique hierarchy documents

    • validate

      public void validate()
      Checks every structural invariant this index can decide from its own documents: canonical identity, duplicate hierarchy and entry IDs, blank parents, unresolvable parent references, and parent cycles.

      Whether a hierarchy is well-formed is fixed by the Role's knowledge sources and the installed SourceLoaders, never by request data, so this runs at strategy-selection time — above the @Search.onFailure guard, the same rule rerankerModel, queryExpansionModel and GraphStoreProvider resolution follow. Routing a malformed hierarchy through the guard would let CONTINUE emit a silently ungrounded action that reports success and USE_CACHE answer it from a stale entry, for what is a deployment fault. Failures raised while traversing a valid hierarchy stay runtime concerns and still reach the guard.

      Throws:
      HierarchyException - when any structural invariant is violated

    • find

      public Optional<RetrievedDocument> find(String id)
      Resolves a document by hierarchy ID.
      Parameters:
      id - hierarchy identifier
      Returns:
      matching document, if present

    • identifier

      public String identifier(RetrievedDocument document)
      Resolves the canonical hierarchy ID for a document.
      Parameters:
      document - indexed document or child hit
      Returns:
      canonical hierarchy ID
      Throws:
      HierarchyException - when neither hierarchyId nor entryId is valid

    • parentId

      public Optional<String> parentId(String id)
      Returns the immediate parent ID for an indexed document.
      Parameters:
      id - hierarchy document ID
      Returns:
      parent ID, or empty for a root/flat document

    • sourceGroup

      public String sourceGroup(RetrievedDocument document)
      Resolves the canonical source group used for source fencing.
      Parameters:
      document - hierarchy document
      Returns:
      hierarchySource metadata, or the document source as fallback