Class ContextManager

java.lang.Object
uno.anahata.ai.context.ContextManager
public class ContextManager extends Object
Manages the conversation context (history) for a Chat session.

This class is responsible for:

  • Maintaining the list of ChatMessage objects.
  • Tracking the total token count of the conversation.
  • Managing context listeners for history changes.
  • Delegating specialized tasks to SessionManager (persistence), ResourceTracker (stateful files), and ContextPruner (pruning).

  • Constructor Details

    • ContextManager

      public ContextManager(Chat chat)
      Constructs a new ContextManager for the given Chat instance.
      Parameters:
      chat - The Chat instance to manage context for.

  • Method Details

    • getCallingInstance

      public static ContextManager getCallingInstance()
      Gets the ContextManager for the currently executing tool.

      This method uses a ThreadLocal to retrieve the active instance, allowing tools to interact with the context without needing an explicit reference.

      Returns:
      The active ContextManager.
      Throws:
      IllegalStateException - if not called from a tool execution thread.

    • addListener

      public void addListener(ContextListener listener)
      Adds a listener to be notified of changes to the conversation history.
      Parameters:
      listener - The listener to add.

    • removeListener

      public void removeListener(ContextListener listener)
      Removes a previously added context listener.
      Parameters:
      listener - The listener to remove.

    • add

      public void add(ChatMessage message)
      Adds a new message to the conversation context.

      This method performs several side effects:

      • Calculates and sets the elapsed time since the last message.
      • Handles stateful resource replacement via ResourceTracker.
      • Updates the total token count if usage metadata is present.
      • Triggers ephemeral tool call pruning if the message is from the user.
      • Notifies listeners of the history change.

      Parameters:
      message - The message to add.

    • getTotalTokenCount

      public int getTotalTokenCount()
      Gets the total token count of the conversation.
      Returns:
      The total token count.

    • clear

      public void clear()
      Clears all messages from the context and resets the token count.

    • getContext

      public List<ChatMessage> getContext()
      Returns a copy of the current conversation history.
      Returns:
      A list of ChatMessage objects.

    • setContext

      public void setContext(List<ChatMessage> newContext)
      Replaces the entire conversation history with a new list of messages.

      This is typically used when restoring a session. It recalculates elapsed times for all messages and updates the token count from the most recent usage metadata.

      Parameters:
      newContext - The new list of messages.

    • pruneMessages

      public void pruneMessages(List<Long> sequentialIds, String reason)
      Prunes a set of messages from the context by their sequential IDs.
      Parameters:
      sequentialIds - The list of sequential IDs to prune.
      reason - The reason for pruning.

    • pruneParts

      public void pruneParts(long messageSequentialId, List<Number> partIndices, String reason)
      Prunes specific parts from a message.
      Parameters:
      messageSequentialId - The sequential ID of the message.
      partIndices - The indices of the parts to prune.
      reason - The reason for pruning.

    • prunePartsByReference

      public void prunePartsByReference(List<com.google.genai.types.Part> partsToPrune, String reason)
      Prunes specific parts from the context by their object references.
      Parameters:
      partsToPrune - The list of Part objects to prune.
      reason - The reason for pruning.

    • pruneToolCall

      public void pruneToolCall(String toolCallId, String reason)
      Prunes a specific tool call and its associated response from the context.
      Parameters:
      toolCallId - The unique ID of the tool call.
      reason - The reason for pruning.

    • notifyHistoryChange

      public void notifyHistoryChange()
      Notifies listeners of a change in the conversation history and triggers an automatic backup.

    • getChatMessageForPart

      public Optional<ChatMessage> getChatMessageForPart(com.google.genai.types.Part part)
      Finds the ChatMessage that contains a specific Part instance.
      Parameters:
      part - The Part to find.
      Returns:
      An Optional containing the ChatMessage if found, otherwise empty.