Package com.tnsai.agents.cognitive

Class CognitiveEngine

java.lang.Object
com.tnsai.agents.cognitive.CognitiveEngine
public class CognitiveEngine extends Object
Manages the BDI (Belief-Desire-Intention) cognitive state of an agent.

The CognitiveEngine encapsulates all BDI-related state and operations, providing a clean separation from the main Agent class. It handles:

  • Static beliefs, desires, and intentions (immutable, from configuration)
  • Dynamic beliefs, desires, and intentions (mutable, runtime modifications)
  • Belief revision strategies for handling conflicting beliefs
  • Desire conflict resolution

Thread Safety

This class uses CopyOnWriteArrayList for dynamic collections, making it thread-safe for concurrent read/write operations.

Usage


 CognitiveEngine engine = CognitiveEngine.builder()
     .beliefs(List.of(new Belief("The sky is blue")))
     .desires(List.of(Desire.goal("Help the user")))
     .beliefRevisionStrategy(BeliefRevisionStrategy.RECENCY_BASED)
     .build();

 // Add dynamic belief
 engine.addBelief(new Belief("User prefers concise answers"));

 // Query all beliefs
 List<Belief> all = engine.allBeliefs();
Author:
TnsAI Team
See Also:

  • Method Details

    • builder

      public static CognitiveEngine.Builder builder()
      Creates a new builder for CognitiveEngine.
      Returns:
      a new builder instance

    • staticBeliefs

      public List<Belief> staticBeliefs()
      Returns the static beliefs (from configuration).
      Returns:
      unmodifiable list of static beliefs

    • dynamicBeliefs

      public List<Belief> dynamicBeliefs()
      Returns the dynamic beliefs (added at runtime).
      Returns:
      unmodifiable snapshot of dynamic beliefs

    • allBeliefs

      public List<Belief> allBeliefs()
      Returns all beliefs (static + dynamic).
      Returns:
      combined unmodifiable list

    • addBelief

      public void addBelief(Belief belief)
      Adds a belief dynamically at runtime.

      If a belief revision strategy is configured, it will be used to handle conflicts with existing beliefs.

      Parameters:
      belief - the belief to add
      Throws:
      IllegalArgumentException - if belief is null

    • removeBelief

      public boolean removeBelief(Belief belief)
      Removes a dynamically added belief.
      Parameters:
      belief - the belief to remove
      Returns:
      true if the belief was removed

    • removeBeliefByContent

      public boolean removeBeliefByContent(String content)
      Removes a belief by content.
      Parameters:
      content - the content of the belief to remove
      Returns:
      true if a belief was removed

    • updateBeliefConfidence

      public boolean updateBeliefConfidence(String content, double newConfidence)
      Updates the confidence of a belief with matching content.
      Parameters:
      content - the content to match
      newConfidence - the new confidence level (0.0 to 1.0)
      Returns:
      true if a belief was updated

    • clearExpiredBeliefs

      public int clearExpiredBeliefs()
      Removes all expired beliefs from the dynamic belief list.
      Returns:
      number of beliefs removed

    • clearDynamicBeliefs

      public void clearDynamicBeliefs()
      Clears all dynamic beliefs.

    • setBeliefRevisionStrategy

      public void setBeliefRevisionStrategy(BeliefRevisionStrategy strategy)
      Sets the belief revision strategy.
      Parameters:
      strategy - the strategy to use (null to disable)

    • getBeliefRevisionStrategy

      public BeliefRevisionStrategy getBeliefRevisionStrategy()
      Returns the current belief revision strategy.
      Returns:
      the current strategy, or null if none set

    • staticDesires

      public List<Desire> staticDesires()
      Returns the static desires (from configuration).
      Returns:
      unmodifiable list of static desires

    • dynamicDesires

      public List<Desire> dynamicDesires()
      Returns the dynamic desires (added at runtime).
      Returns:
      unmodifiable snapshot of dynamic desires

    • allDesires

      public List<Desire> allDesires()
      Returns all desires (static + dynamic).
      Returns:
      combined unmodifiable list

    • addDesire

      public void addDesire(Desire desire)
      Adds a desire dynamically at runtime.

      If a conflict resolver is configured and conflicts are detected, the resolver is used to determine which desire(s) to keep.

      Parameters:
      desire - the desire to add
      Throws:
      IllegalArgumentException - if desire is null

    • removeDesire

      public boolean removeDesire(Desire desire)
      Removes a dynamically added desire.
      Parameters:
      desire - the desire to remove
      Returns:
      true if the desire was removed

    • removeDesireByObjective

      public boolean removeDesireByObjective(String objective)
      Removes a desire by objective.
      Parameters:
      objective - the objective to match
      Returns:
      true if a desire was removed

    • findConflictingDesires

      public List<List<Desire>> findConflictingDesires()
      Finds desires that might conflict with each other.
      Returns:
      list of potentially conflicting desire pairs

    • clearDynamicDesires

      public void clearDynamicDesires()
      Clears all dynamic desires.

    • setDesireConflictResolver

      public void setDesireConflictResolver(DesireConflictResolver resolver)
      Sets the desire conflict resolver.
      Parameters:
      resolver - the resolver to use (null to disable)

    • getDesireConflictResolver

      public DesireConflictResolver getDesireConflictResolver()
      Returns the current desire conflict resolver.
      Returns:
      the current resolver, or null if none set

    • staticIntentions

      public List<Intention> staticIntentions()
      Returns the static intentions (from configuration).
      Returns:
      unmodifiable list of static intentions

    • dynamicIntentions

      public List<Intention> dynamicIntentions()
      Returns the dynamic intentions (added at runtime).
      Returns:
      unmodifiable snapshot of dynamic intentions

    • allIntentions

      public List<Intention> allIntentions()
      Returns all intentions (static + dynamic).
      Returns:
      combined unmodifiable list

    • addIntention

      public void addIntention(Intention intention)
      Adds an intention dynamically at runtime.
      Parameters:
      intention - the intention to add
      Throws:
      IllegalArgumentException - if intention is null

    • removeIntention

      public boolean removeIntention(Intention intention)
      Removes a dynamically added intention.
      Parameters:
      intention - the intention to remove
      Returns:
      true if the intention was removed

    • removeIntentionByTask

      public boolean removeIntentionByTask(String taskDescription)
      Removes an intention by task description.
      Parameters:
      taskDescription - the task description to match
      Returns:
      true if an intention was removed

    • completeIntention

      public boolean completeIntention(Intention intention)
      Marks an intention as completed by removing it.
      Parameters:
      intention - the intention that was completed
      Returns:
      true if the intention was removed

    • clearDynamicIntentions

      public void clearDynamicIntentions()
      Clears all dynamic intentions.

    • clearAllDynamic

      public void clearAllDynamic()
      Clears all dynamic BDI components (beliefs, desires, intentions).

    • clearAllDynamicBDI

      public void clearAllDynamicBDI()
      Clears all dynamic BDI components (beliefs, desires, intentions).

      Alias for clearAllDynamic() for API compatibility.

    • snapshot

      public CognitiveEngine.BDISnapshot snapshot()
      Returns a snapshot of the current BDI state for serialization/debugging.
      Returns:
      BDI state snapshot

    • restoreFromSnapshot

      public void restoreFromSnapshot(CognitiveEngine.BDISnapshot snapshot)
      Restores dynamic BDI state from a snapshot.

      This clears current dynamic state and adds all items from the snapshot that are not in the static lists.

      Parameters:
      snapshot - the snapshot to restore from