Package com.tnsai.context

Interface ContextManagerHandle

public interface ContextManagerHandle
SPI handle for context graph management.

This interface defines the context management contract that Agent uses. The concrete implementation (AgentContextManager) lives in tnsai-intelligence and is discovered via SpiLoader.

  • Method Details

    • noOp

      static ContextManagerHandle noOp()
      Returns a no-op implementation that silently ignores all operations. Used as a null-object when context graph is not enabled.
      Returns:
      a no-op ContextManagerHandle (singleton)

    • createSnapshot

      ContextSnapshot createSnapshot(SnapshotTrigger trigger, List<Belief> beliefs, List<Desire> desires, List<Intention> intentions)
      Creates a context snapshot capturing the current agent state.
      Parameters:
      trigger - the reason for the snapshot
      beliefs - current beliefs
      desires - current desires
      intentions - current intentions
      Returns:
      the created snapshot

    • createSnapshot

      ContextSnapshot createSnapshot(SnapshotTrigger trigger)
      Creates a snapshot with just the trigger (for minimal snapshots).
      Parameters:
      trigger - the reason for the snapshot
      Returns:
      the created snapshot

    • executeWithTrace

      <T> T executeWithTrace(String description, Supplier<T> operation, Supplier<List<Belief>> beliefs, Supplier<List<Desire>> desires, Supplier<List<Intention>> intentions)
      Executes an operation with full decision tracing.
      Type Parameters:
      T - return type
      Parameters:
      description - operation description
      operation - the operation to execute
      beliefs - supplier for current beliefs
      desires - supplier for current desires
      intentions - supplier for current intentions
      Returns:
      the operation result

    • executeWithTrace

      <T> T executeWithTrace(String description, Supplier<T> operation)
      Simplified traced execution without BDI suppliers.
      Type Parameters:
      T - return type
      Parameters:
      description - operation description
      operation - the operation to execute
      Returns:
      the operation result

    • createTrace

      DecisionTrace createTrace(DecisionTrace.Builder builder)
      Creates a decision trace manually.
      Parameters:
      builder - preconfigured trace builder
      Returns:
      saved decision trace

    • findTrace

      Optional<DecisionTrace> findTrace(String traceId)

    • getRecentDecisions

      List<DecisionTrace> getRecentDecisions(int limit)

    • getAllDecisions

      List<DecisionTrace> getAllDecisions()

    • findDecisionsByAction

      List<DecisionTrace> findDecisionsByAction(String action)

    • findSuccessfulDecisions

      List<DecisionTrace> findSuccessfulDecisions()

    • findFailedDecisions

      List<DecisionTrace> findFailedDecisions()

    • findDecisionsInCurrentConversation

      List<DecisionTrace> findDecisionsInCurrentConversation()

    • findPrecedents

      List<DecisionTrace> findPrecedents(DecisionTrace referenceTrace, double threshold)

    • explainDecision

      Optional<String> explainDecision(String traceId)

    • summarizeRecentDecisions

      List<String> summarizeRecentDecisions(int limit)

    • findSnapshot

      Optional<ContextSnapshot> findSnapshot(String snapshotId)

    • getRecentSnapshots

      List<ContextSnapshot> getRecentSnapshots(int limit)

    • trackEntity

      void trackEntity(Entity entity)

    • untrackEntity

      void untrackEntity(String entityId)

    • getTrackedEntities

      Collection<Entity> getTrackedEntities()

    • clearTrackedEntities

      void clearTrackedEntities()

    • setVariable

      void setVariable(String key, Object value)

    • getVariable

      Optional<Object> getVariable(String key)

    • getVariable

      <T> Optional<T> getVariable(String key, Class<T> type)

    • removeVariable

      void removeVariable(String key)

    • clearVariables

      void clearVariables()

    • startConversation

      String startConversation()

    • startConversation

      void startConversation(String conversationId)

    • endConversation

      void endConversation()

    • getCurrentConversationId

      Optional<String> getCurrentConversationId()

    • ensureConversation

      default String ensureConversation()
      Starts a conversation if none is active and returns the current ID.

      The default is check-then-act. Implementations that own a lifecycle lock must override this so concurrent callers share one conversation (TAN-3955).

    • getTraceStatistics

      DecisionTraceStore.DecisionTraceStatistics getTraceStatistics()

    • getSnapshotStatistics

      SnapshotStore.SnapshotStoreStatistics getSnapshotStatistics()

    • getDecisionCount

      int getDecisionCount()

    • getSnapshotCount

      int getSnapshotCount()

    • cleanupOldTraces

      int cleanupOldTraces(Instant olderThan)

    • cleanupOldSnapshots

      int cleanupOldSnapshots(Instant olderThan)

    • getAgentId

      String getAgentId()