Package com.tnsai.rag.files

Class AgentRecordFormat

java.lang.Object
com.tnsai.rag.files.AgentRecordFormat
public final class AgentRecordFormat extends Object
The format of the lines in an agent's .history and .log files: the MDC keys, the logback patterns that write them and the file extensions. RecordParser reads the same grammar back.

TnsAI writes no such file itself. A host that keeps per-agent files writes them with these patterns through its own logback appenders, puts the episode state under EPISODE_STATE_MDC_KEY and the conversation the line belongs to under CONVERSATION_MDC_KEY. A line written while no conversation is in the MDC carries "-" in that field, so every line has the field.

The conversation field stands before the writer's name, so a line still ends with "] <agent> <message>":

 2026-10-21 18:00:00 [running] [conv-1] Alice has started episode 1.
 2026-10-21 18:00:00 INFO  [running] [-] Alice chat started

A message of several lines is written with two spaces before each line after its first, so no line of a message reads as a record of its own: RecordParser parses a line only from its start. A line a message forges, such as a record of another conversation, therefore continues the record it was written in. Lines written before this indent, and the stack trace logback appends after a message, are not indented.

Only a line feed ends a line. Any other line terminator in a message, such as a lone carriage return or U+2028, is written as it is and read back as part of the line it is in.

Since:
0.18.6

  • Field Details

    • EPISODE_STATE_MDC_KEY

      public static final String EPISODE_STATE_MDC_KEY
      The MDC key the episode state is written from.
      See Also:

    • CONVERSATION_MDC_KEY

      public static final String CONVERSATION_MDC_KEY
      The MDC key the conversation id is written from; the value is opaque to TnsAI.
      See Also:

    • NO_CONVERSATION

      public static final String NO_CONVERSATION
      What the conversation field holds on a line written outside any conversation.
      See Also:

    • HISTORY_EXTENSION

      public static final String HISTORY_EXTENSION
      The extension of an agent's history file.
      See Also:

    • LOG_EXTENSION

      public static final String LOG_EXTENSION
      The extension of an agent's log file.
      See Also:

    • LOG_PATTERN

      public static final String LOG_PATTERN
      The logback pattern of a log file: time, level, episode state, conversation, the logger's last name segment, then the message, its lines after the first indented by two spaces.
      See Also:

    • HISTORY_PATTERN_TEMPLATE

      public static final String HISTORY_PATTERN_TEMPLATE
      The logback pattern of a history file as a String.format(java.lang.String, java.lang.Object...) template, with %s standing for the agent's name: time, episode state, conversation, the agent's name, then the message, its lines after the first indented by two spaces. It carries no level and no logger name. Use historyPattern(String) to fill it, which escapes the name.
      See Also:

  • Method Details

    • historyPattern

      public static String historyPattern(String agentName)
      The history pattern with the agent's name written into it as literal text, its \ % ( ) escaped so logback does not read them as pattern syntax.
      Parameters:
      agentName - the agent whose history the pattern writes
      Returns:
      the logback pattern
      Throws:
      NullPointerException - if agentName is null