Package com.tnsai.integration.activity

Class AgentActivity<P>

java.lang.Object
com.tnsai.integration.activity.AgentActivity<P>
Type Parameters:
P - how the caller identifies a peer, the other agent of a message
public final class AgentActivity<P> extends Object
Thread-safe, bounded record of what one agent has recently done: the messages it sent and received, the outcomes of the actions its LLM called, and the notes it wrote.

The record is held in memory by the agent that owns it, and ActivityBlock renders it for that agent's LLM. It is not a log: nothing is written out.

Two caps bound it: a number of entries, and a number of characters over all entries, counting each entry's text and type. When an entry would take the record over either, the oldest entries are dropped until it fits. The newest entry is always kept, because a third cap, on the characters of one entry's type and text together, cuts a longer one short before it is kept and may not exceed the whole. The type is cut first, then the text to what the type leaves.

Every text and type passes through the redactor before the record cuts it, so the record's own cut cannot leave behind the start of something the redactor would have hidden. A text the caller already cut short before recording it is redacted as it arrives. Line breaks in a text or type are replaced by a space after redaction, so an entry stays one line when it is rendered. Peers are kept as the caller identifies them; ActivityBlock names them through the caller's function, which is responsible for what a name shows.

Since:
0.18.5

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    AgentActivity.Entry<P>
    One entry of the record.
    static enum 
    AgentActivity.Kind
    What an entry of the record describes.

  • Constructor Summary

    Constructors
    Constructor
    Description
    AgentActivity(int maxEntries, int maxChars, int maxEntryChars, UnaryOperator<String> redactor)
    Creates an empty record.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    acted(double tick, String action, boolean failed, String outcome)
    Records an action the agent's LLM called.
    void
    noted(double tick, String note)
    Records a note the agent wrote.
    List<AgentActivity.Entry<P>>
    read()
    Returns a stable snapshot of the record, oldest first.
    void
    received(double tick, P sender, String type, String text, boolean textTruncated)
    Records a message the agent received.
    void
    sent(double tick, List<? extends P> receivers, String type, String text, boolean textTruncated)
    Records a message the agent sent.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • AgentActivity

      public AgentActivity(int maxEntries, int maxChars, int maxEntryChars, UnaryOperator<String> redactor)
      Creates an empty record.
      Parameters:
      maxEntries - the most entries the record holds
      maxChars - the most characters of text and type the record holds over all its entries
      maxEntryChars - the most characters one entry's type and text hold together
      redactor - applied to every text and type before it is kept, outside the record's lock and so possibly from several threads at once; it must be thread-safe, and an exception it throws reaches the caller and nothing is recorded. A null it returns is kept as the empty text, or as no type
      Throws:
      IllegalArgumentException - if a cap is less than one, or maxEntryChars exceeds maxChars
      NullPointerException - if redactor is null
      Since:
      0.18.5

  • Method Details

    • sent

      public void sent(double tick, List<? extends P> receivers, String type, String text, boolean textTruncated)
      Records a message the agent sent.
      Parameters:
      tick - the tick at which it was sent
      receivers - the agents it was sent to; null is none
      type - the message type, or null when it has none
      text - the message text
      textTruncated - whether the caller already cut text short
      Throws:
      NullPointerException - if receivers holds a null
      Since:
      0.18.5

    • received

      public void received(double tick, P sender, String type, String text, boolean textTruncated)
      Records a message the agent received.
      Parameters:
      tick - the tick at which it was received
      sender - the agent that sent it, or null when it is not known
      type - the message type, or null when it has none
      text - the message text
      textTruncated - whether the caller already cut text short
      Since:
      0.18.5

    • acted

      public void acted(double tick, String action, boolean failed, String outcome)
      Records an action the agent's LLM called.
      Parameters:
      tick - the tick at which it ran
      action - the action's name
      failed - whether it failed
      outcome - what it returned, or why it failed
      Since:
      0.18.5

    • noted

      public void noted(double tick, String note)
      Records a note the agent wrote.
      Parameters:
      tick - the tick at which it was written
      note - the note
      Since:
      0.18.5

    • read

      public List<AgentActivity.Entry<P>> read()
      Returns a stable snapshot of the record, oldest first.
      Returns:
      an immutable list that later recording does not change
      Since:
      0.18.5