State Machine

A state is a distinct, well-defined condition or status in which a system or workflow can exist at a given time. In a finite state machine, the number of states is limited and predetermined.

• Examples: Idle, Processing, Success, Error, AwaitingApproval.
• Each state encapsulates the system's behavior and available transitions.
• The initial state is the entry point when the machine starts.
• Final states (or terminal states) are those from which no further transitions occur, often representing workflow completion or termination.

A transition is a directed change from one state to another, triggered by an event or condition. It defines the possible pathways through the state machine.

• Represented as an arrow: State A --[Event/Condition]--> State B.
• Deterministic: For a given state and input, the next state is predictable.
• Transitions are the core logic that dictates workflow progression.
• A self-transition occurs when an event causes a state to transition back to itself, often used to trigger side effects without changing the primary status.

An event is an external or internal signal that triggers a state transition. It is the input to the state machine.

• Examples: A user action (button_clicked), a completed API call (api_response_received), a timer expiration (timeout), or a message from another system.
• Events are evaluated by the state machine's logic to determine if a valid transition exists from the current state.
• Unhandled events for a given state are typically ignored or cause an error, depending on implementation.

An action is a side effect or operation executed in response to a transition or upon entering/exiting a state. Actions are where the state machine interacts with the external world.

• Entry Action: Executed upon entering a state (e.g., logging, initializing a resource).
• Exit Action: Executed upon leaving a state (e.g., cleaning up resources).
• Transition Action: Executed during the transition itself.
• In AI orchestration, actions frequently involve tool calls, such as invoking an API, querying a database, or generating content with an LLM.

A guard condition is a boolean expression that must evaluate to true for a transition to be taken. It adds conditional logic to transitions.

• Syntax: State --[Event] [Guard]--> NextState.
• Example: A transition from AwaitingApproval to Processing might have a guard [is_approved == true].
• If an event occurs but the guard is false, the transition is not taken, and the state machine remains in its current state.
• Guards enable complex, data-dependent workflow logic within a deterministic framework.

Extended state refers to additional variables or context (beyond the discrete state) that the machine uses to make decisions. It is typically stored in a data structure like a context object.

• Purpose: Allows a finite number of states to represent a vast number of behavioral scenarios.
• Guards and actions read from and write to the extended state.
• Example: A UserOnboarding state machine might have a discrete state ProfileCreation, with extended state variables for user_name, email_verified, and profile_completion_percentage.
• This concept is central to practical implementations like UML statecharts or Harel statecharts.