Developer Builds FSM-Based Framework to Make LLM Chatbots Follow Scripts Reliably and Cheaply

The author, working on a business chatbot, found that large language models struggle to reliably follow long, detailed scripts because their wide context window causes them to lose structure over long instructions, and that existing agent-based solutions to break tasks into steps multiply the number of model calls and thus the cost of each dialogue. To solve this cheaply, the author built an open-source library where a finite state machine (FSM) governs the overall conversation graph and controls which stage instructions are passed to the LLM at any given moment, so the model only ever sees the instructions relevant to the current stage rather than the entire script. The architecture consists of three modules: an FSM module that tracks the dialogue graph and user state, a vars_memory module that stores dialogue variables with change history, and a conversation_core module that orchestrates calls to the LLM. On each turn the model must respond with a fixed four-field contract — a message to the user, a transition signal, structured stage results, and a stage summary — and if it violates this contract (invalid JSON, nonexistent transition signals, missing results) the system automatically sends a corrective follow-up request. Conversational continuity across stage transitions is maintained using OpenAI's Responses API previous_response_id chaining, which also reduces cost via cheaper cache-read pricing. The overall dialogue script is described in a YAML file, with detailed stage instructions kept in separate files, allowing the underlying engine to be reused across different chatbot domains without modification. To manage the complexity of hand-editing YAML, the author built a script that converts the YAML into a draw.io diagram for easier human review, plus a log viewer tool to inspect test conversations in a chat-like format with expandable system logs, including real-time updates when debugging locally. As a demonstration, the repository includes an example 'analyst bot' that helps solo developers scope out project requirements, which the author reports required only about 1.03 LLM calls per user message while still reliably following the script and collecting structured information, though the demo bot's prompt engineering was left unpolished.