Package com.tnsai.planning

Class UtilityAIPlanner

java.lang.Object
com.tnsai.planning.UtilityAIPlanner
All Implemented Interfaces:
Planner
public class UtilityAIPlanner extends Object implements Planner
Utility AI planner that selects actions based on cost/value trade-offs.

Unlike BackwardChainingPlanner which plans toward goals, UtilityAIPlanner greedily selects the action with highest utility at each step. This is ideal for:

  • Exploratory behaviors (chatbots)
  • Dynamic environments
  • Cost optimization
  • Reactive agents

Algorithm

 for each applicable action:
     score = 0
     for each consideration:
         score += consideration.evaluate(action, state) * consideration.weight()
     if score > bestScore:
         bestAction = action
 return bestAction

Usage


 UtilityAIPlanner planner = UtilityAIPlanner.builder()
     .consideration(Consideration.cost())
     .consideration(Consideration.value())
     .consideration(Consideration.preconditionSatisfied())
     .build();

 // Or with defaults
 UtilityAIPlanner planner = new UtilityAIPlanner(MyRole.class);
Author:
TnsAI Team
See Also:

  • Constructor Details

    • UtilityAIPlanner

      public UtilityAIPlanner(Class<?> roleClass)
      Creates a planner from a role class.

      Extracts actions with nested @Utility configuration from @Action.

      Parameters:
      roleClass - class with @Action methods (optionally with utility = @Utility(...))

    • UtilityAIPlanner

      public UtilityAIPlanner(Class<?> roleClass, List<Consideration> considerations)
      Creates a planner from a role class with custom considerations.
      Parameters:
      roleClass - class with @Action methods
      considerations - list of considerations

    • UtilityAIPlanner

      public UtilityAIPlanner(List<PlanningGoal> goals, List<PlanningAction> actions, List<Consideration> considerations)
      Creates a planner with explicit goals, actions, and considerations.
      Parameters:
      goals - planning goals
      actions - available actions
      considerations - utility considerations

  • Method Details

    • builder

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

    • plan

      public List<PlanningAction> plan(Map<String,Object> state)
      Description copied from interface: Planner
      Creates a plan to achieve unsatisfied goals.
      Specified by:
      plan in interface Planner
      Parameters:
      state - current state (belief map)
      Returns:
      ordered list of actions to execute; empty only when every registered goal is already satisfied

    • plan

      public List<PlanningAction> plan(Map<String,Object> state, boolean useChaining)
      Description copied from interface: Planner
      Creates a plan with optional chaining.
      Specified by:
      plan in interface Planner
      Parameters:
      state - current state
      useChaining - true to use backward chaining for multi-step plans
      Returns:
      ordered list of actions

    • selectBestAction

      public Optional<PlanningAction> selectBestAction(Map<String,Object> state)
      Selects the action with highest utility score.
      Parameters:
      state - current world state
      Returns:
      best action, or empty if no applicable action

    • getActionsByUtility

      public List<PlanningAction> getActionsByUtility(Map<String,Object> state)
      Gets all actions sorted by utility (highest first).
      Parameters:
      state - current world state
      Returns:
      sorted list of applicable actions

    • calculateUtility

      public float calculateUtility(PlanningAction action, Map<String,Object> state)
      Calculates total utility score for an action.
      Parameters:
      action - action to evaluate
      state - current state
      Returns:
      utility score

    • getGoals

      public List<PlanningGoal> getGoals()
      Description copied from interface: Planner
      Returns all registered goals.
      Specified by:
      getGoals in interface Planner
      Returns:
      list of goals

    • getActions

      public List<PlanningAction> getActions()
      Description copied from interface: Planner
      Returns all registered actions.
      Specified by:
      getActions in interface Planner
      Returns:
      list of actions

    • findUnsatisfiedGoals

      public List<PlanningGoal> findUnsatisfiedGoals(Map<String,Object> state)
      Description copied from interface: Planner
      Finds goals that are not currently satisfied.
      Specified by:
      findUnsatisfiedGoals in interface Planner
      Parameters:
      state - current state
      Returns:
      unsatisfied goals, ordered by priority (highest first)

    • findSatisfiedGoals

      public List<PlanningGoal> findSatisfiedGoals(Map<String,Object> state)
      Description copied from interface: Planner
      Finds goals that are currently satisfied.
      Specified by:
      findSatisfiedGoals in interface Planner
      Parameters:
      state - current state
      Returns:
      satisfied goals

    • isGoalSatisfied

      public boolean isGoalSatisfied(String goalName, Map<String,Object> state)
      Description copied from interface: Planner
      Checks if a specific goal is satisfied.
      Specified by:
      isGoalSatisfied in interface Planner
      Parameters:
      goalName - goal name
      state - current state
      Returns:
      true if goal condition is satisfied

    • isGoalSatisfied

      public boolean isGoalSatisfied(PlanningGoal goal, Map<String,Object> state)
      Description copied from interface: Planner
      Checks if a goal is satisfied.
      Specified by:
      isGoalSatisfied in interface Planner
      Parameters:
      goal - goal to check
      state - current state
      Returns:
      true if goal condition is satisfied

    • findActionsForGoal

      public List<PlanningAction> findActionsForGoal(PlanningGoal goal, Map<String,Object> state)
      Description copied from interface: Planner
      Finds actions that can help achieve a goal.
      Specified by:
      findActionsForGoal in interface Planner
      Parameters:
      goal - target goal
      state - current state
      Returns:
      applicable actions for the goal

    • findApplicableActions

      public List<PlanningAction> findApplicableActions(Map<String,Object> state)
      Description copied from interface: Planner
      Finds actions whose preconditions are satisfied.
      Specified by:
      findApplicableActions in interface Planner
      Parameters:
      state - current state
      Returns:
      applicable actions

    • applyEffects

      public Map<String,Object> applyEffects(PlanningAction action, Map<String,Object> state)
      Description copied from interface: Planner
      Simulates applying an action's effects to a state.
      Specified by:
      applyEffects in interface Planner
      Parameters:
      action - action to apply
      state - state to modify (returns new state)
      Returns:
      new state after applying effects