Building state machine library with help from AI tools

Just out of boredom, while waiting for my follow-up interview sessions, I built a state-machine library, powered by genruler. I built one in the past, to be exact, during my first job after graduation. This implementation is loosely based on the design my supervisor drafted back then. The project also aimed to showcase how the rule DSL can be utilized.

According to the helpful summary returned by a Google search on finite state machine (emphasis mine)

A “finite state machine” means a computational model where a system can only be in a limited number of distinct states at any given time, and transitions between these states are triggered by specific inputs, essentially allowing it to process information based on a set of defined conditions with no possibility of having an infinite number of states; “finite” here refers to the limited set of possible states the system can exist in.

The library receives a dictionary that represents the schema of the finite state machine. For example, we want to build an order tracking system

Finite state machine diagram generated by Graphviz

And the schema would look something like this (in truncated YAML form for clarity)

machine:
  initial_state: pending_payment

states:
  pending_payment:
    name: pending payment
    transitions:
      order_authorization:
        name: order is authorized
        destination: authorized
        rule: (condition.equal (basic.field "is_authorized") (boolean.tautology))

  authorized:
    name: authorized
    action: authorize_order
    transitions:
      order_partially_paid:
        name: order is partially paid
        destination: partially_paid
        rule: (boolean.tautology)
      order_fully_paid:
        name: order is fully paid
        destination: paid
        rule: (boolean.tautology)

    ...

Therefore, to set everything up, we call

import genstates
import yaml
import order_processor

with open("states.yaml") as schema:
  machine = genstates.Machine(yaml.safe_load(schema), order_processor)

So in this fictional example, we will receive some payload whenever there is a change in the order. For example, when the seller acknowledges the order, we get

{
  "is_authorized": true,
  ...
}

We can then check through the library

state = machine.initial # assume the order is created

transition = machine.get_transition(state, "order_authorization")

assert transition.check_condition(payload)

The check also runs an additional validation check if defined in the schema. This is helpful if you intend to return an error message to the caller.

try:
  assert transition.check_condition(payload)
except ValidationFailedError as e:
  logger.exception(e)

Sometimes, we know that every time the payload arrives, it should trigger a transition, but we don’t always know which one. Therefore, we just pass it into Machine.progress

try:
  state = machine.progress(state, payload)
except ValidationFailedError as e:
  logger.exception(e)

Once knowing what state the order should progress, we can start writing code to work on the logic

# fetch the order from database
order = Order.get(id=payload["order_id"])
current_state = machine.states[order.state]

# fetch next state
try:
    new_state = machine.progress(current_state, payload)
except ValidationFailedError as e:
    # validation failed, do something
    logger.exception(e)
    return
except MissingTransitionError as e:
    # can't find a valid transition from given payload
    logger.exception(e)
    return
except DuplicateTransitionError as e:
    # found more than one transition from given payload
    logger.exception(e)
    return

# do processing (example)
log = Log.create(order=order, **payload)
log.save()

order.state = new_state.key
order.save()

Ideally, I can also extract the processing logic away, which is the reason I imported order_processor in the beginning. In the authorization state definition, we also defined an action

authorized:
    name: authorized
    action: authorize_order
    ...

So in the module order_processor, we define a new function called authorized_order

def authorize_order(payload):
    # do the processing here instead
    pass

Such that the following is possible, where state management code is separated from the rest of processing logic

# fetch the order from database
order = Order.get(id=payload["order_id"])
current_state = machine.states[order.state]

# fetch next state
new_state = machine.progress(current_state, payload)


# do processing (example)
new_state.do_action(payload)

However, I am still working on it now, and should make it in the next release. Meanwhile, it is also capable of doing something similar to map and reduce if every state has action defined. Feel free to check the project for development progress. And both genruler and genstates are now up on PyPI, yay!

Now, how about the AI thing?

I downloaded Codeium Windsurf after the library is somewhat usable. I eventually used it to strip hy dependency off from genruler, and added documentation and README to the project. For genstates, I used cascade to generate documentation, README, as well as tests. Overall, it feels like I have a mid to senior programmer around to help me out with tasks I would assign to my interns or even juniors.

Most of the core logic still comes from my end, as intelligent as the language model is at the moment, they still make mistakes here and there and hence, require supervision. I also experimented with qwen2.5-coder:7b model, and it works rather well, albeit rather slowly due to my crappy workstation. I find the price Codeium asks for is fair, if I am to build my own product and managed to make money out of it.

While the generation parts works fine, but writing actual code is not as great. I am not sure if Pylance is working properly there, considered it is proprietary, or whether it is due to the completion magic windsurf does, my editor is no longer able to do auto-import of libraries when I write code. For example, when I auto-completes reduce() function in my code, in vscode it would automagically insert from functools import reduce into my code. However, this is not the case in windsurf, which makes it a little bit irritating. However, considering this is new, the coding experience should be fixed over time.

On the other hand, I am still in search of a lighter editor, and zed does catch my attention. However, since my Surface Book 2 died recently, I am only left with a Samsung Galaxy Tab S7FE when I am away from my home office. Hence, vscode with a web frontend (and it is surprisingly usable) connected to my workstation is still my main editor (it even works with the neovim extension).

Generative AI powered by LLM is rapidly changing our lives, there’s no point in resisting it. However, IMHO, we should also have some self-restrain to not use it for everything. It really should be used as a complement to innovative or creative work, not a replacement to innovation and creativity.

We should also know what it is outputting, instead of blindly accept what it does. For example, in genruler, I made it improve my original README with more extensive examples. Instead of accepting it as-is, I made it to generate tests for all the examples it generates in the README, so the example code passes and works as I intended.

Overall, yea, I do think these Generative AI enhanced editors do worth the money they ask for. In the end, these are tools, they are meant to offer assistance to work, not replacing the person hitting the keyboard.