Sayflow

Inspiration

Workflows are locked away in Python scripts, YAML files, and drag-and-drop builders — and the people who actually know the workflow often cannot read them. What if the program was the description? Sayflow is a plain-English programming language for agent workflows, so non-programmers can write near-English lines and understand exactly what will happen.

What it does

Sayflow is a complete language: a lexer, a recursive-descent parser, and a tree-walking interpreter in a single dependency-free Python file. It compiles plain English into an executable workflow and runs it with a visible, numbered step trace, so you can follow, trust, and audit every step. For example:

for each file in "sample/inbox":
  if filename contains "invoice":
    move file to "sample/sorted/invoices"

It includes three real examples — file triage, a reminder digest, and CSV cleanup that trims, normalises, and dedupes rows. Workflows are sandboxed to the workspace, and errors are friendly, for example: "Line 4: I don't know the word 'frobnicate'...". The language covers named values, file read/write/append/move/copy/delete, folder and line loops, nested if/otherwise with word conditions, text transforms, CSV field picking, and dedup.

How we built it

Sayflow is a single Python 3 standard-library file. The lexer is quote-aware, the parser handles recursive blocks, and the interpreter walks the tree. One transform-binding bug — "capitalised of" initially title-cased a whole sentence — was caught by the self-test and now binds tightly. Running python3 sayflow.py --selftest runs the 3 examples in a sandbox, with 8/8 checks passing.

Challenges we ran into

Making an English-like grammar unambiguous, and handling loops that move files while listing them — solved by snapshotting the listing before the loop runs. The step trace also had to stay readable while remaining complete enough to audit.

Accomplishments that we're proud of

A non-programmer can read a Sayflow program aloud and predict what it will do. It performs real file operations and dedup, with no mocks, and it has zero dependencies.

What we learned

Language design is UX design: every grammar choice is a choice about what a reader will understand.

What's next

An ask human-approval gate written in English, read-aloud traces, and send/fetch steps.

Try it

Repository: https://github.com/CloudCorpRecords/sayflow

Run: python3 sayflow.py examples/reminder-digest.say

Test: python3 sayflow.py --selftest

Build Disclosure

Build Disclosure: AI-built. Built by AI agents (Tree / Muse fleet) directed by Rene Turcios during the hackathon period; Rene set the direction and reviewed; agents designed, coded, and tested.

Built With

• python