Package com.tnsai.rag

Record Class ChatRetrievalContext

java.lang.Object
java.lang.Record
com.tnsai.rag.ChatRetrievalContext
Record Components:
scope - tenant and conversation-session isolation
runId - application run identity, if present
agentName - application agent or role identity, if present
simulationState - application lifecycle state, if present
currentEpisode - current episode identity, if present
sourceRevision - application source revision, if present
cancellationToken - cooperative cancellation signal
deadline - absolute retrieval deadline, if present
metadataFilters - additional document metadata filters
turnMessage - raw message of the turn, if present
conversationId - opaque conversation identity, if present
sourcePaths - run-time location of declared sources, by source name
public record ChatRetrievalContext(RetrievalScope scope, Optional<String> runId, Optional<String> agentName, Optional<String> simulationState, Optional<String> currentEpisode, Optional<String> sourceRevision, CancellationToken cancellationToken, Optional<Instant> deadline, Map<String,String> metadataFilters, Optional<String> turnMessage, Optional<String> conversationId, Map<String,Path> sourcePaths) extends Record
Typed, request-local identity and lifecycle context for chat retrieval.

The canonical chat fields are copied into RetrievalRequest.metadataFilters() so live sources receive the complete invocation context and cache keys isolate runs, episodes, owners, and source revisions. They use a reserved namespace and are not document predicates for materialized sources; ordinary entries in metadataFilters() remain document filters.

turnMessage(), conversationId() and sourcePaths() are copied into the matching RetrievalRequest components, never into its metadata filters. When a turn message is present, chat searches it instead of the message the provider renders. Source paths move the declared sources of the chat's knowledge to their location for this request: a source the map names reads from the map's location, any other from its declared path, resolved against the run's base directory when one is set.

Since:
0.13.0

  • Field Details

  • Constructor Details

  • Method Details

    • builder

      public static ChatRetrievalContext.Builder builder()
      Returns a builder with unscoped, non-cancellable defaults.

    • withIdentityDefaults

      public ChatRetrievalContext withIdentityDefaults(RetrievalScope fallbackScope, String fallbackAgentName)
      Fills missing scope components and agent identity from the active agent entry context without overriding values supplied by the application.
      Parameters:
      fallbackScope - active tenant/session scope
      fallbackAgentName - active agent identity
      Returns:
      context with missing identity defaults filled

    • documentFilters

      public static Map<String,String> documentFilters(Map<String,String> filters)
      Returns only document predicates, excluding reserved chat lifecycle fields that exist for live-source dispatch and cache isolation.
      Parameters:
      filters - complete retrieval metadata filters
      Returns:
      immutable document-filter subset

    • 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.

    • scope

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

    • runId

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

    • agentName

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

    • simulationState

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

    • currentEpisode

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

    • sourceRevision

      public Optional<String> sourceRevision()
      Returns the value of the sourceRevision record component.
      Returns:
      the value of the sourceRevision 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