Package com.tnsai.models.agent

Class Belief

java.lang.Object
com.tnsai.models.agent.Belief
public final class Belief extends Object
Represents a single belief that an agent holds about the world.

In the BDI (Belief-Desire-Intention) architecture, beliefs represent the agent's knowledge about its environment. Beliefs are included in the agent's system prompt to provide context for decision-making.

Enhanced Belief Properties (v2.0)

  • content - The belief statement
  • confidence - How certain the agent is (0.0-1.0)
  • source - Where the belief came from (sensor, LLM, user, static)
  • timestamp - When the belief was created
  • validUntil - TTL expiration (null = never expires)

BDI Architecture Context

  • Beliefs (this class) - What the agent knows about the world
  • Desire - What the agent wants to achieve
  • Intention - What the agent is committed to doing

Usage Examples


 // Simple belief (backward compatible)
 Belief simple = new Belief("Today is December 31, 2025");

 // Belief with confidence and source
 Belief weather = new Belief(
     "Current temperature is 18°C",
     0.95,
     "weather-api"
 );

 // Belief with TTL (expires in 5 minutes)
 Belief cacheable = Belief.withTTL(
     "API rate limit is at 80%",
     0.99,
     "rate-limiter",
     Duration.ofMinutes(5)
 );

 // Check if belief is still valid
 if (cacheable.isValid()) {
     // Use the belief
 }

Confidence Levels

  • 1.0 - Absolute certainty (static facts)
  • 0.9+ - High confidence (verified data)
  • 0.7-0.9 - Medium confidence (inferred)
  • < 0.7 - Low confidence (uncertain)

Common Sources

  • "static" - Hardcoded facts
  • "user" - User-provided information
  • "llm" - LLM-inferred knowledge
  • "sensor" - External API or sensor data
  • "memory" - Retrieved from memory store

This class is immutable and thread-safe.

Author:
TnsAI Team
See Also:

  • Field Details

    • DEFAULT_CONFIDENCE

      public static final double DEFAULT_CONFIDENCE
      Default confidence level for beliefs without explicit confidence.
      See Also:

    • DEFAULT_SOURCE

      public static final String DEFAULT_SOURCE
      Default source for beliefs without explicit source.
      See Also:

    • SOURCE_USER

      public static final String SOURCE_USER
      Source constant for user-provided beliefs.
      See Also:

    • SOURCE_LLM

      public static final String SOURCE_LLM
      Source constant for LLM-inferred beliefs.
      See Also:

    • SOURCE_SENSOR

      public static final String SOURCE_SENSOR
      Source constant for sensor/API data.
      See Also:

    • SOURCE_MEMORY

      public static final String SOURCE_MEMORY
      Source constant for memory-retrieved beliefs.
      See Also:

  • Constructor Details

    • Belief

      public Belief(String content)
      Creates a belief with only content (backward compatible).

      Uses default confidence (1.0) and source ("static").

      Parameters:
      content - the belief statement
      Throws:
      IllegalArgumentException - if content is null or blank

    • Belief

      public Belief(String content, double confidence, String source)
      Creates a belief with content, confidence, and source.
      Parameters:
      content - the belief statement
      confidence - confidence level (0.0-1.0)
      source - where the belief came from
      Throws:
      IllegalArgumentException - if content is null/blank or confidence is out of range

    • Belief

      public Belief(String content, double confidence, String source, Instant validUntil)
      Creates a fully specified belief.
      Parameters:
      content - the belief statement
      confidence - confidence level (0.0-1.0)
      source - where the belief came from
      validUntil - when the belief expires (null = never)
      Throws:
      IllegalArgumentException - if content is null/blank or confidence is out of range

  • Method Details

    • withTTL

      public static Belief withTTL(String content, double confidence, String source, Duration ttl)
      Creates a belief with a TTL (time-to-live).
      Parameters:
      content - the belief statement
      confidence - confidence level (0.0-1.0)
      source - where the belief came from
      ttl - how long the belief is valid
      Returns:
      a new Belief that expires after the TTL

    • fromUser

      public static Belief fromUser(String content, double confidence)
      Creates a belief from user input.
      Parameters:
      content - the belief statement
      confidence - confidence level (0.0-1.0)
      Returns:
      a new Belief with source "user"

    • fromLLM

      public static Belief fromLLM(String content, double confidence)
      Creates a belief from LLM inference.
      Parameters:
      content - the belief statement
      confidence - confidence level (0.0-1.0)
      Returns:
      a new Belief with source "llm"

    • fromSensor

      public static Belief fromSensor(String content, double confidence, Duration ttl)
      Creates a belief from sensor/API data.
      Parameters:
      content - the belief statement
      confidence - confidence level (0.0-1.0)
      ttl - how long the belief is valid
      Returns:
      a new Belief with source "sensor" and TTL

    • fromMemory

      public static Belief fromMemory(String content, double confidence)
      Creates a belief from memory retrieval.
      Parameters:
      content - the belief statement
      confidence - confidence level (0.0-1.0)
      Returns:
      a new Belief with source "memory"

    • isExpired

      public boolean isExpired()
      Checks if this belief has expired.
      Returns:
      true if the belief has a validUntil and it has passed

    • isValid

      public boolean isValid()
      Checks if this belief is still valid (not expired).
      Returns:
      true if the belief has no TTL or hasn't expired yet

    • hasTTL

      public boolean hasTTL()
      Checks if this belief has a TTL set.
      Returns:
      true if validUntil is not null

    • getAge

      public Duration getAge()
      Returns the age of this belief.
      Returns:
      duration since creation

    • getRemainingTime

      public Duration getRemainingTime()
      Returns the remaining time before expiration.
      Returns:
      remaining duration, or null if no TTL

    • withConfidence

      public Belief withConfidence(double newConfidence)
      Creates a new belief with updated confidence.
      Parameters:
      newConfidence - the new confidence level
      Returns:
      a new Belief with the same content but different confidence

    • withSource

      public Belief withSource(String newSource)
      Creates a new belief with updated source.
      Parameters:
      newSource - the new source
      Returns:
      a new Belief with the same content but different source

    • extendTTL

      public Belief extendTTL(Duration extension)
      Creates a new belief with extended TTL.
      Parameters:
      extension - how much to extend the TTL
      Returns:
      a new Belief with extended validUntil

    • isHighConfidence

      public boolean isHighConfidence()
      Checks if this belief is high confidence (>= 0.9).
      Returns:
      true if confidence is 0.9 or higher

    • isLowConfidence

      public boolean isLowConfidence()
      Checks if this belief is low confidence (invalid input: '<' 0.7).
      Returns:
      true if confidence is below 0.7

    • mightConflictWith

      public boolean mightConflictWith(Belief other)
      Checks if this belief conflicts with another (same topic, different content). This is a simple string-based check; semantic conflict detection requires embedding comparison.
      Parameters:
      other - the other belief to compare
      Returns:
      true if the beliefs might conflict