Package com.tnsai.planning

Interface PlannerHandle

public interface PlannerHandle
SPI handle for planning system integration.

This interface defines the planning contract that Agent uses. The concrete implementation lives in tnsai-intelligence and is discovered via SpiLoader.

Supports two planning paradigms:

  • Goal-oriented planning: backward chaining from goals to actions
  • Utility-based planning: greedy action selection by cost/value

Usage Example


 Agent agent = AgentBuilder.create()
     .role(new SurvivalRole())
     .build();

 // Generate plan for all unsatisfied goals
 List<PlanStep> plan = agent.plan();

 // Generate plan for specific goal
 List<PlanStep> plan = agent.planForGoal("survive");

 // Execute the plan
 PlanResult result = agent.executePlan(plan);

  • Method Details

    • plan

      List<PlannerHandle.PlanStep> plan(Map<String,Object> state)
      Generates a plan to satisfy all unsatisfied goals.
      Parameters:
      state - current agent state (beliefs) extracted from @State fields
      Returns:
      ordered list of plan steps, empty if all goals satisfied

    • planForGoal

      List<PlannerHandle.PlanStep> planForGoal(String goalName, Map<String,Object> state)
      Generates a plan to satisfy a specific goal.
      Parameters:
      goalName - the goal to plan for
      state - current agent state
      Returns:
      ordered list of plan steps, empty if goal already satisfied
      Throws:
      IllegalArgumentException - if goalName is not a registered goal

    • execute

      PlannerHandle.PlanResult execute(List<PlannerHandle.PlanStep> steps, Object roleInstance)
      Executes a plan on a role instance.
      Parameters:
      steps - the plan steps to execute
      roleInstance - the role instance containing @ActionSpec methods
      Returns:
      result containing success status, step results, and final state
      Throws:
      SecurityException - with UNAUTHORIZED, before any step runs, if a step's action declares an execution policy or @Security: plan steps do not pass the access gate, so such an action has to be dispatched through ActionExecutor

    • isGoalSatisfied

      boolean isGoalSatisfied(String goalName, Map<String,Object> state)
      Checks if a goal is satisfied in the given state.
      Parameters:
      goalName - the goal to check
      state - current agent state
      Returns:
      true if the goal condition is met

    • getUnsatisfiedGoals

      List<String> getUnsatisfiedGoals(Map<String,Object> state)
      Returns names of all unsatisfied goals in the given state.
      Parameters:
      state - current agent state
      Returns:
      list of unsatisfied goal names, sorted by priority

    • getRegisteredGoals

      List<String> getRegisteredGoals()
      Returns all registered goal names.
      Returns:
      unmodifiable list of goal names