Package com.tnsai.planning

Class PlanExecutor

java.lang.Object
com.tnsai.planning.PlanExecutor
public class PlanExecutor extends Object
Executes plans generated by a Planner on a role instance.

PlanExecutor provides the main thinking loop for planning agents:

  1. Extract current state from @State fields
  2. Generate a plan using the planner
  3. Execute each action in the plan
  4. Update state after each action

Usage


 @RoleSpec(
     name = "LifeCell",
     goals = {
         @Goal(name = "survive", condition = "state == ALIVE")
     }
 )
 public class LifeCellRole extends Role {
     @State private CellState state = CellState.DEAD;
     @State private int neighborCount = 3;

     @ActionSpec(
         precondition = "state == DEAD && neighborCount == 3",
         postcondition = "state = ALIVE",
         fulfills = {"survive"}
     )
     public void reproduce() {
         this.state = CellState.ALIVE;
     }
 }

 // Usage
 LifeCellRole role = new LifeCellRole();
 PlanExecutor executor = new PlanExecutor(role);
 List<String> executed = executor.think();
 // Returns: ["reproduce"]

The plan-to-execute contract

This class and PlannerHandleAdapter — the path an agent runs through core's PlannerHandle SPI — share one invariant: a step that declares a precondition is measured against the real @State rather than the planner's simulation, and a step whose precondition has stopped holding is never executed. Everything else about the two differs, because their APIs have different shapes, and the package documentation lists those differences. This surface extracts beliefs afresh before each step with a precondition, skips or throws instead of reporting a row, abandons the rest of the plan when it refuses a step, and checks after the last step that the plan established the goals it set out to establish.

Author:
TnsAI Team
See Also:

  • Constructor Details

    • PlanExecutor

      public PlanExecutor(Object roleInstance)
      Creates an executor for a role instance.

      Uses BackwardChainingPlanner by default.

      Parameters:
      roleInstance - role object instance

    • PlanExecutor

      public PlanExecutor(Object roleInstance, Planner planner)
      Creates an executor with a custom planner.
      Parameters:
      roleInstance - role object instance
      planner - planner implementation

  • Method Details

    • think

      public List<String> think()
      Executes one thinking cycle.

      This is the main entry point for planning agents:

      1. Extract current state
      2. Generate plan for unsatisfied goals
      3. Execute actions in order
      4. Return executed action names
      Returns:
      list of executed action names; empty when every goal is already satisfied. A planned step whose precondition stopped holding is left out, and logged, when the planner declares goals and none of them is left unsatisfied by then.
      Throws:
      PlanningFailureException - if an unsatisfied goal has no plan; if a planned step's precondition no longer holds when execution reaches it while a goal is still unsatisfied, or while the planner declares no goals at all; or if a goal the plan set out to establish — unsatisfied when the plan was produced and satisfied by the plan's declared effects — is unsatisfied once the plan has executed. Steps executed before a refusal keep their effects
      com.tnsai.security.SecurityException - with UNAUTHORIZED, before any step runs, if a planned action declares an execution policy or @Security; see refuseProtectedSteps(java.lang.Object, java.util.List<com.tnsai.planning.PlanningAction>)

    • think

      public List<String> think(boolean useChaining)
      Executes one thinking cycle with optional chaining.
      Parameters:
      useChaining - true to use backward chaining for multi-step plans
      Returns:
      list of executed action names; empty when every goal is already satisfied. A planned step whose precondition stopped holding is left out, and logged, when the planner declares goals and none of them is left unsatisfied by then.
      Throws:
      PlanningFailureException - if an unsatisfied goal has no plan; if a planned step's precondition no longer holds when execution reaches it while a goal is still unsatisfied, or while the planner declares no goals at all; or if a goal the plan set out to establish — unsatisfied when the plan was produced and satisfied by the plan's declared effects — is unsatisfied once the plan has executed. Steps executed before a refusal keep their effects
      com.tnsai.security.SecurityException - with UNAUTHORIZED, before any step runs, if a planned action declares an execution policy or @Security; see refuseProtectedSteps(java.lang.Object, java.util.List<com.tnsai.planning.PlanningAction>)

    • extractBeliefs

      public Map<String,Object> extractBeliefs()
      Extracts current state from @State annotated fields.
      Returns:
      current belief map

    • executeAction

      public void executeAction(PlanningAction action)
      Executes a single action on the role instance.
      Parameters:
      action - action to execute
      Throws:
      com.tnsai.security.SecurityException - with UNAUTHORIZED if the action declares an execution policy or @Security

    • refuseProtectedSteps

      public static void refuseProtectedSteps(Object roleInstance, List<PlanningAction> actions)
      Refuses planned actions that declare an execution policy or @Security.

      A plan step invokes the action method directly, not through ActionExecutor, so neither the access gate nor @Security checks nor approval run for it. An action that declares either has to be dispatched through ActionExecutor. Callers check the whole plan before its first step runs, so a refused plan leaves no side effects.

      Parameters:
      roleInstance - the role instance the actions run on
      actions - the planned actions
      Throws:
      com.tnsai.security.SecurityException - with UNAUTHORIZED for the first action that declares access restrictions
      Since:
      0.17.0

    • getUnsatisfiedGoals

      public List<String> getUnsatisfiedGoals()
      Gets the list of unsatisfied goals.
      Returns:
      unsatisfied goal names

    • getSatisfiedGoals

      public List<String> getSatisfiedGoals()
      Gets the list of satisfied goals.
      Returns:
      satisfied goal names

    • isGoalSatisfied

      public boolean isGoalSatisfied(String goalName)
      Checks if a specific goal is satisfied.
      Parameters:
      goalName - goal name
      Returns:
      true if goal is satisfied

    • getPlan

      public List<String> getPlan()
      Gets the current plan without executing it.
      Returns:
      planned action names; empty when every goal is already satisfied
      Throws:
      PlanningFailureException - if an unsatisfied goal has no plan

    • getPlanner

      public Planner getPlanner()
      Gets the underlying planner.
      Returns:
      planner instance

    • getRoleInstance

      public Object getRoleInstance()
      Gets the role instance.
      Returns:
      role instance