Package com.tnsai.rag

Record Class RetrievalRequest

java.lang.Object
java.lang.Record
com.tnsai.rag.RetrievalRequest
Record Components:
query - normalized retrieval query
config - canonical retrieval configuration
scope - tenant/session isolation scope
cancellationToken - cooperative cancellation signal
deadline - absolute deadline, if one is configured
metadataFilters - immutable metadata filters; keys and values are non-blank, and an absent filter is an absent entry rather than an empty value
turnMessage - the raw message of the turn this request serves, if the caller has it; carried for retrievers that read it, never as a metadata filter
conversationId - opaque identity of the conversation this request serves, if the caller has one; carried for retrievers that scope by it, never as a metadata filter
sourcePaths - immutable run-time location of a declared source, by source name; names are non-blank, and an absent location is an absent entry
public record RetrievalRequest(String query, RetrievalConfig config, RetrievalScope scope, CancellationToken cancellationToken, Optional<Instant> deadline, Map<String,String> metadataFilters, Optional<String> turnMessage, Optional<String> conversationId, Map<String,Path> sourcePaths) extends Record
Entry-point-neutral request passed to a RetrievalEngine.

The engine owns its complete source set. The request selects and configures those sources through the canonical RetrievalConfig, while carrying per-invocation identity, cancellation, deadline, and metadata filters.

The engine reads config for retrieval behaviour only. It does not apply Search.contextWindow(), which bounds assembled prompt text rather than evidence — rendering is the caller's responsibility, so the window is enforced wherever evidence becomes a prompt.

Cache keys

A retrieval cache key must cover the full scope(), the full metadataFilters(), turnMessage(), conversationId() and sourcePaths() in addition to the query and configuration. Two properties of this record constrain how:

  • Filter keys and values are arbitrary non-blank text and may contain any separator a naive encoding would use, so {"a": "b|c"} and {"a|b": "c"} both flatten to a|b|c. A key must therefore length-prefix each part rather than join on a delimiter.
  • metadataFilters and sourcePaths are unordered immutable maps whose iteration order is unspecified and varies between JVM runs, so entries must be sorted before they are digested. Digesting in iteration order yields a different key for identical filters on the next run, silently defeating the cache.
Since:
0.13.0

  • Constructor Details

  • Method Details

    • builder

      public static RetrievalRequest.Builder builder(String query, RetrievalConfig config)
      Creates a request builder.
      Parameters:
      query - retrieval query
      config - canonical retrieval configuration
      Returns:
      new builder

    • throwIfAborted

      public void throwIfAborted(Clock clock)
      Throws when cooperative cancellation or the absolute deadline says this request must stop.

      Engines call this at their deadline-enforcement boundary. Backends that own that boundary also call it before, between, and after blocking phases with the same clock, and configure backend-native I/O timeouts; an absolute deadline cannot interrupt an arbitrary blocking call by itself.

      Parameters:
      clock - time source used to evaluate the deadline

    • throwIfAborted

      public void throwIfAborted()
      Evaluates cancellation and deadline against the UTC system clock.

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • query

      public String query()
      Returns the value of the query record component.
      Returns:
      the value of the query record component

    • config

      public RetrievalConfig config()
      Returns the value of the config record component.
      Returns:
      the value of the config record component

    • scope

      public RetrievalScope scope()
      Returns the value of the scope record component.
      Returns:
      the value of the scope record component

    • cancellationToken

      public CancellationToken cancellationToken()
      Returns the value of the cancellationToken record component.
      Returns:
      the value of the cancellationToken record component

    • deadline

      public Optional<Instant> deadline()
      Returns the value of the deadline record component.
      Returns:
      the value of the deadline record component

    • metadataFilters

      public Map<String,String> metadataFilters()
      Returns the value of the metadataFilters record component.
      Returns:
      the value of the metadataFilters record component

    • turnMessage

      public Optional<String> turnMessage()
      Returns the value of the turnMessage record component.
      Returns:
      the value of the turnMessage record component

    • conversationId

      public Optional<String> conversationId()
      Returns the value of the conversationId record component.
      Returns:
      the value of the conversationId record component

    • sourcePaths

      public Map<String,Path> sourcePaths()
      Returns the value of the sourcePaths record component.
      Returns:
      the value of the sourcePaths record component