Package com.tnsai.annotations

Annotation Interface State

@Documented @Retention(RUNTIME) @Target(FIELD) public @interface State
Marks a field as agent state for planning.

State fields represent the agent's current knowledge about itself and the world. They are used by the

invalid reference 
com.tnsai.planning.Planner
to:
  • Check goal satisfaction conditions
  • Evaluate action preconditions
  • Apply action postconditions (effects)

Usage


 @PromptTemplates("prompts/life-cell.prompt.template")
 @RoleSpec(
     name = "LifeCell",
     goals = {
         @Goal(name = "survive", condition = "state == ALIVE")
     }
 )
 public class LifeCellRole extends Role {

     @State(description = "Current cell state", template = "cell_state")
     private CellState state = CellState.DEAD;

     @State(description = "Number of live neighbors (0-8)", template = "neighbor_count")
     private int neighborCount = 0;

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

Planning Integration

State fields are automatically extracted and used by the planner:

  1. Planner collects state field values as a Map
  2. Goal conditions are evaluated against the state
  3. Action preconditions are checked against the state
  4. Action postconditions modify the state
Author:
TnsAI Team
See Also:
  • Goal
  • invalid reference 
    Action#precondition()
  • invalid reference 
    Action#postcondition()
  • invalid reference 
    com.tnsai.planning.Planner

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    String
    description
    Description of what this state represents.
    String[]
    invariants
    Invariants that must always hold for this state.
    String
    name
    Custom name for the state field.
    String
    template
    Template key for custom prompt rendering.

  • Element Details

    • name

      String name
      Custom name for the state field.

      If empty, the field name is used.

      Returns:
      state name
      Default:
      ""

    • description

      String description
      Description of what this state represents.

      Used in documentation and system prompts.

      Returns:
      state description
      Default:
      ""

    • template

      String template
      Template key for custom prompt rendering.

      References a key in the prompt template file specified by PromptTemplates on the Role class.

      The template value supports ${value}, ${name}, and ${description} placeholders.

      If empty, the default format is used.

      Example: template = "neighbor_count" resolves to "You have ${value} live neighbors" from the template file.

      Returns:
      template key, or empty for default format
      See Also:
      Default:
      ""

    • invariants

      String[] invariants
      Invariants that must always hold for this state.

      Used for validation and contract checking.

      Example: invariants = {"value >= 0", "value <= 8"}

      Returns:
      array of invariant expressions
      Default:
      {}