Package com.tnsai.fsm

Class StateMachine

java.lang.Object
com.tnsai.fsm.StateMachine
public class StateMachine extends Object
A Finite State Machine implementation for bounded agent autonomy.

Provides deterministic state transitions with guard conditions, entry/exit actions, and transition actions. Suitable for production AI agent workflows where predictable behavior is required.

Thread safety: This class is not thread-safe. All calls to start(), fire(Event), and reset() must be externally synchronized if accessed from multiple threads.

Usage


 // Define states
 State idle = State.initial("IDLE");
 State processing = State.of("PROCESSING");
 State review = State.of("REVIEW");
 State approved = State.terminal("APPROVED");
 State rejected = State.terminal("REJECTED");

 // Build state machine
 StateMachine sm = StateMachine.builder("ReviewWorkflow")
     .states(idle, processing, review, approved, rejected)
     .transition(Transition.from(idle).to(processing).on("START"))
     .transition(Transition.from(processing).to(review).on("SUBMIT"))
     .transition(Transition.from(review).to(approved)
         .on("REVIEW_COMPLETE")
         .when(Guard.greaterThan("confidence", 0.9)))
     .transition(Transition.from(review).to(rejected)
         .on("REVIEW_COMPLETE")
         .when(Guard.lessThan("confidence", 0.5)))
     .maxTransitions(100)
     .build();

 // Execute
 sm.start();
 sm.fire(Event.of("START"));
 sm.fire(Event.of("SUBMIT"));
 sm.getContext().set("confidence", 0.95);
 sm.fire(Event.of("REVIEW_COMPLETE"));

 // Check result
 if (sm.isInTerminalState()) {
     System.out.println("Final state: " + sm.getCurrentState().getName());
 }

  • Method Details

    • builder

      public static StateMachine.Builder builder(String name)
      Creates a builder with the given name.
      Parameters:
      name - the state machine name
      Returns:
      new builder

    • start

      public StateMachine start()
      Starts the state machine.
      Returns:
      this state machine
      Throws:
      StateMachineException - if already started or no initial state

    • start

      public StateMachine start(StateMachineContext context)
      Starts the state machine with the given context.
      Parameters:
      context - the context
      Returns:
      this state machine
      Throws:
      StateMachineException - if already started or no initial state

    • fire

      public boolean fire(Event event)
      Fires an event to trigger transitions.
      Parameters:
      event - the event
      Returns:
      true if a transition occurred
      Throws:
      StateMachineException - if not running or max transitions exceeded

    • getCurrentState

      public State getCurrentState()
      Gets the current state.
      Returns:
      current state

    • getContext

      public StateMachineContext getContext()
      Gets the context.
      Returns:
      context

    • getStatus

      public StateMachine.Status getStatus()
      Gets the status.
      Returns:
      status

    • isRunning

      public boolean isRunning()
      Returns whether the state machine is running.
      Returns:
      true if running

    • isInTerminalState

      public boolean isInTerminalState()
      Returns whether the state machine is in a terminal state.
      Returns:
      true if completed

    • getName

      public String getName()
      Gets the state machine name.
      Returns:
      name

    • getTransitionCount

      public int getTransitionCount()
      Gets the transition count.
      Returns:
      number of transitions executed

    • getStates

      public Map<String,State> getStates()
      Gets all states.
      Returns:
      unmodifiable map of states

    • getTransitions

      public List<Transition> getTransitions()
      Gets all transitions.
      Returns:
      unmodifiable list of transitions

    • getAvailableEvents

      public List<String> getAvailableEvents()
      Gets available events from current state.
      Returns:
      list of available event names

    • reset

      public void reset()
      Resets the state machine.

    • addListener

      public void addListener(StateMachineListener listener)
      Adds a listener.
      Parameters:
      listener - the listener

    • removeListener

      public void removeListener(StateMachineListener listener)
      Removes a listener.
      Parameters:
      listener - the listener

    • toString

      public String toString()
      Overrides:
      toString in class Object