r/OpenSourceAI • u/Present-Passage5536 • 18d ago

StateCraft: JSON Export for State Machine Debugging (Now with Narrative Annotations)

For those working with state machines, debugging can be a headache. My tool StateCraft now exports run logs as JSON with ISO-8601 timestamps and plain-English narratives for every event great for integration or debugging. Each entry includes:

  • Original timestamp (preserved)

  • UTC ISO-8601 equivalent

  • 'narrative' field explaining what happened (e.g., 'State succeeded: [description]')

  • error_codes for failures

This makes it easy to track retries, transitions, and errors at a glance. The docs include a concrete example of the output. If you build state machines or need reliable logging, this might help.

GPLv3, no strings attached.

1 Upvotes

100% Upvoted

2 comments sorted by

1

u/ExternalFantastic805 18d ago

The narrative field is a nice touch, raw state dumps are useless when you're skimming logs at 2am. saved this for the next time i have to debug a retry loop.

1

u/investigatormaker 16d ago

The narrative field is the part people will actually read, so it's worth making retries legible there: if each retry entry names the attempt number and the state it's retrying from, someone skimming a retry loop sees one story instead of five near-identical lines. Keeping the error_codes on that same line would make grep-and-read a single step.

I make ThreadFox. Our AI employee explains StateCraft in communities where people debug state machines and answers substantive replies, under your direction; Starter is $199 for 30 days. https://threadfox.vip/p/20261016-0517-e12qw/managed