Package com.tnsai.integration.scop

Class ChatTurn

java.lang.Object
com.tnsai.integration.scop.ChatTurn
public final class ChatTurn extends Object
One chat request for SCOPBridge.sendToLLM(ChatTurn): the conversation to send and everything that shapes it on its way out.

Owners carry the meaning of the turn. A turn with owners refreshes every owner's @State and, with a retrieval context, gives and searches their chat knowledge. A turn without owners is dispatched with no @State and no knowledge. Either way the bridge sends a deep copy of the conversation with any prior bridge-marked state removed. The caller lists the owners; the bridge does not discover them.

The bridge prepares the turn itself, so the conversation is given as stored, with the owners whose state it carries listed, as in ChatTurn.builder(config, conversation).tools(tools).owners(agent, role).build(). A conversation that SCOPBridge.prepareConversationForDispatch(org.json.JSONArray, java.lang.Object...) returned holds its owners' state only until it is sent: in a turn without those owners, that state is removed.

ChatTurn.Builder.build() checks the turn's shape, so a malformed turn fails where it is built rather than when it is sent: no owner is null, a Collection or listed twice by identity, and each binding belongs to one listed owner, and a retrieval context comes with at least one owner. The rules among one owner's bindings, at most one checked against its declarations and no two searching the same source name, run when the turn is sent. The checks that need an owner's declarations, such as a binding that disagrees with its owner's knowledge, run only when a turn with a retrieval context is sent.

A turn is one request: its retrieval context carries that request's deadline, cancellation and turn message, so each send builds its own turn. The turn holds the caller's conversation and tools, not copies; the bridge reads them when the turn is sent and never mutates them.

Since:
0.18.6

  • Method Details

    • builder

      public static ChatTurn.Builder builder(LLMConfiguration config, org.json.JSONArray conversation)
      Starts a turn for conversation under config.
      Parameters:
      config - provider-neutral LLM configuration
      conversation - caller-owned conversation history
      Returns:
      a builder with no tools, owners, bindings, retrieval context or request section
      Throws:
      NullPointerException - if config or conversation is null

    • config

      public LLMConfiguration config()
      Returns:
      the provider-neutral LLM configuration

    • conversation

      public org.json.JSONArray conversation()
      Returns:
      the caller-owned conversation history

    • tools

      public org.json.JSONArray tools()
      Returns:
      the provider-neutral tool declarations, or null for none

    • owners

      public List<Object> owners()
      Returns:
      the owners in the order given, possibly empty

    • bindings

      public List<com.tnsai.rag.ChatKnowledgeBinding> bindings()
      Returns:
      the bindings in the order given, possibly empty

    • context

      public com.tnsai.rag.ChatRetrievalContext context()
      Returns:
      the request-local retrieval context, or null for no retrieval

    • requestSection

      public String requestSection()
      Returns:
      the section for this request alone, or null for none