Package com.tnsai.context.integration

Class AgentContextManager

java.lang.Object
com.tnsai.context.integration.AgentContextManager
All Implemented Interfaces:
com.tnsai.context.ContextManagerHandle
public class AgentContextManager extends Object implements com.tnsai.context.ContextManagerHandle
Manages context graphs for an agent.

AgentContextManager provides the integration layer between TnsAI agents and the Context Graphs feature, enabling:

  • Automatic context snapshotting before/after decisions
  • Decision tracing with full provenance
  • Explaining past decisions
  • Finding precedent decisions

This class is a facade that delegates to three focused sub-managers:

  • SnapshotManager — context snapshot creation, queries, diffs
  • DecisionTracer — decision tracing with BDI mapping, queries
  • ConversationManager — conversation lifecycle, entity tracking, variables

Usage Example


 // Enable context graph on agent
 AgentContextManager contextManager = new AgentContextManager(
     agent.getAgentId(),
     new InMemorySnapshotStore(),
     new InMemoryDecisionTraceStore()
 );

 // Execute with tracing
 String response = contextManager.executeWithTrace(
     "Process discount request",
     () -> agent.chat("Should we approve 20% discount?"),
     agent::getBeliefs,
     agent::getDesires,
     agent::getIntentions
 );

 // Explain recent decisions
 List<DecisionTrace> traces = contextManager.getRecentDecisions(10);
 for (DecisionTrace trace : traces) {
     System.out.println(trace.explainWhy());
 }

  • Constructor Details

    • AgentContextManager

      public AgentContextManager(String agentId, com.tnsai.context.snapshot.SnapshotStore snapshotStore, com.tnsai.context.decision.DecisionTraceStore traceStore)
      Creates an agent context manager.
      Parameters:
      agentId - the agent's ID
      snapshotStore - store for context snapshots
      traceStore - store for decision traces

    • AgentContextManager

      public AgentContextManager(String agentId, com.tnsai.context.snapshot.SnapshotStore snapshotStore, com.tnsai.context.decision.DecisionTraceStore traceStore, BDIContextMapper bdiMapper)
      Creates an agent context manager with custom BDI mapper.
      Parameters:
      agentId - the agent's ID
      snapshotStore - store for context snapshots
      traceStore - store for decision traces
      bdiMapper - custom BDI mapper

  • Method Details

    • createSnapshot

      public com.tnsai.context.snapshot.ContextSnapshot createSnapshot(com.tnsai.context.snapshot.SnapshotTrigger trigger, List<com.tnsai.models.agent.Belief> beliefs, List<com.tnsai.models.agent.Desire> desires, List<com.tnsai.models.agent.Intention> intentions)
      Specified by:
      createSnapshot in interface com.tnsai.context.ContextManagerHandle

    • createSnapshot

      public com.tnsai.context.snapshot.ContextSnapshot createSnapshot(com.tnsai.context.snapshot.SnapshotTrigger trigger)
      Specified by:
      createSnapshot in interface com.tnsai.context.ContextManagerHandle

    • executeWithTrace

      public <T> T executeWithTrace(String description, Supplier<T> operation, Supplier<List<com.tnsai.models.agent.Belief>> beliefs, Supplier<List<com.tnsai.models.agent.Desire>> desires, Supplier<List<com.tnsai.models.agent.Intention>> intentions)
      Specified by:
      executeWithTrace in interface com.tnsai.context.ContextManagerHandle

    • executeWithTrace

      public <T> T executeWithTrace(String description, Supplier<T> operation)
      Specified by:
      executeWithTrace in interface com.tnsai.context.ContextManagerHandle

    • createTrace

      public com.tnsai.context.decision.DecisionTrace createTrace(com.tnsai.context.decision.DecisionTrace.Builder builder)
      Specified by:
      createTrace in interface com.tnsai.context.ContextManagerHandle

    • findTrace

      public Optional<com.tnsai.context.decision.DecisionTrace> findTrace(String traceId)
      Specified by:
      findTrace in interface com.tnsai.context.ContextManagerHandle

    • getRecentDecisions

      public List<com.tnsai.context.decision.DecisionTrace> getRecentDecisions(int limit)
      Specified by:
      getRecentDecisions in interface com.tnsai.context.ContextManagerHandle

    • getAllDecisions

      public List<com.tnsai.context.decision.DecisionTrace> getAllDecisions()
      Specified by:
      getAllDecisions in interface com.tnsai.context.ContextManagerHandle

    • findDecisionsByAction

      public List<com.tnsai.context.decision.DecisionTrace> findDecisionsByAction(String action)
      Specified by:
      findDecisionsByAction in interface com.tnsai.context.ContextManagerHandle

    • findSuccessfulDecisions

      public List<com.tnsai.context.decision.DecisionTrace> findSuccessfulDecisions()
      Specified by:
      findSuccessfulDecisions in interface com.tnsai.context.ContextManagerHandle

    • findFailedDecisions

      public List<com.tnsai.context.decision.DecisionTrace> findFailedDecisions()
      Specified by:
      findFailedDecisions in interface com.tnsai.context.ContextManagerHandle

    • findDecisionsInCurrentConversation

      public List<com.tnsai.context.decision.DecisionTrace> findDecisionsInCurrentConversation()
      Specified by:
      findDecisionsInCurrentConversation in interface com.tnsai.context.ContextManagerHandle

    • findPrecedents

      public List<com.tnsai.context.decision.DecisionTrace> findPrecedents(com.tnsai.context.decision.DecisionTrace referenceTrace, double threshold)
      Specified by:
      findPrecedents in interface com.tnsai.context.ContextManagerHandle

    • explainDecision

      public Optional<String> explainDecision(String traceId)
      Specified by:
      explainDecision in interface com.tnsai.context.ContextManagerHandle

    • summarizeRecentDecisions

      public List<String> summarizeRecentDecisions(int limit)
      Specified by:
      summarizeRecentDecisions in interface com.tnsai.context.ContextManagerHandle

    • findSnapshot

      public Optional<com.tnsai.context.snapshot.ContextSnapshot> findSnapshot(String snapshotId)
      Specified by:
      findSnapshot in interface com.tnsai.context.ContextManagerHandle

    • getRecentSnapshots

      public List<com.tnsai.context.snapshot.ContextSnapshot> getRecentSnapshots(int limit)
      Specified by:
      getRecentSnapshots in interface com.tnsai.context.ContextManagerHandle

    • diffSnapshots

      public Optional<com.tnsai.context.snapshot.SnapshotDiff> diffSnapshots(String beforeId, String afterId)
      Computes diff between two snapshots.
      Parameters:
      beforeId - first snapshot ID
      afterId - second snapshot ID
      Returns:
      Optional containing the diff

    • trackEntity

      public void trackEntity(com.tnsai.context.entity.Entity entity)
      Specified by:
      trackEntity in interface com.tnsai.context.ContextManagerHandle

    • untrackEntity

      public void untrackEntity(String entityId)
      Specified by:
      untrackEntity in interface com.tnsai.context.ContextManagerHandle

    • getTrackedEntities

      public Collection<com.tnsai.context.entity.Entity> getTrackedEntities()
      Specified by:
      getTrackedEntities in interface com.tnsai.context.ContextManagerHandle

    • clearTrackedEntities

      public void clearTrackedEntities()
      Specified by:
      clearTrackedEntities in interface com.tnsai.context.ContextManagerHandle

    • setVariable

      public void setVariable(String key, Object value)
      Specified by:
      setVariable in interface com.tnsai.context.ContextManagerHandle

    • getVariable

      public Optional<Object> getVariable(String key)
      Specified by:
      getVariable in interface com.tnsai.context.ContextManagerHandle

    • getVariable

      public <T> Optional<T> getVariable(String key, Class<T> type)
      Specified by:
      getVariable in interface com.tnsai.context.ContextManagerHandle

    • removeVariable

      public void removeVariable(String key)
      Specified by:
      removeVariable in interface com.tnsai.context.ContextManagerHandle

    • clearVariables

      public void clearVariables()
      Specified by:
      clearVariables in interface com.tnsai.context.ContextManagerHandle

    • startConversation

      public String startConversation()
      Specified by:
      startConversation in interface com.tnsai.context.ContextManagerHandle

    • ensureConversation

      public String ensureConversation()
      Specified by:
      ensureConversation in interface com.tnsai.context.ContextManagerHandle

    • startConversation

      public void startConversation(String conversationId)
      Specified by:
      startConversation in interface com.tnsai.context.ContextManagerHandle

    • endConversation

      public void endConversation()
      Specified by:
      endConversation in interface com.tnsai.context.ContextManagerHandle

    • getCurrentConversationId

      public Optional<String> getCurrentConversationId()
      Specified by:
      getCurrentConversationId in interface com.tnsai.context.ContextManagerHandle

    • getTraceStatistics

      public com.tnsai.context.decision.DecisionTraceStore.DecisionTraceStatistics getTraceStatistics()
      Specified by:
      getTraceStatistics in interface com.tnsai.context.ContextManagerHandle

    • getSnapshotStatistics

      public com.tnsai.context.snapshot.SnapshotStore.SnapshotStoreStatistics getSnapshotStatistics()
      Specified by:
      getSnapshotStatistics in interface com.tnsai.context.ContextManagerHandle

    • getDecisionCount

      public int getDecisionCount()
      Specified by:
      getDecisionCount in interface com.tnsai.context.ContextManagerHandle

    • getSnapshotCount

      public int getSnapshotCount()
      Specified by:
      getSnapshotCount in interface com.tnsai.context.ContextManagerHandle

    • cleanupOldTraces

      public int cleanupOldTraces(Instant olderThan)
      Specified by:
      cleanupOldTraces in interface com.tnsai.context.ContextManagerHandle

    • cleanupOldSnapshots

      public int cleanupOldSnapshots(Instant olderThan)
      Specified by:
      cleanupOldSnapshots in interface com.tnsai.context.ContextManagerHandle

    • getAgentId

      public String getAgentId()
      Specified by:
      getAgentId in interface com.tnsai.context.ContextManagerHandle

    • getBdiMapper

      public BDIContextMapper getBdiMapper()
      Gets the BDI mapper.
      Returns:
      BDI context mapper

    • getSnapshotStore

      public com.tnsai.context.snapshot.SnapshotStore getSnapshotStore()
      Gets the snapshot store.
      Returns:
      snapshot store

    • getTraceStore

      public com.tnsai.context.decision.DecisionTraceStore getTraceStore()
      Gets the trace store.
      Returns:
      decision trace store