https://github.com/computemachines/flowno
Python DSL for writing dataflow programs.
https://github.com/computemachines/flowno
Last synced: about 2 months ago
JSON representation
Python DSL for writing dataflow programs.
- Host: GitHub
- URL: https://github.com/computemachines/flowno
- Owner: computemachines
- License: mit
- Created: 2025-02-23T20:16:46.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-02-04T03:28:18.000Z (4 months ago)
- Last Synced: 2026-02-04T14:54:04.444Z (4 months ago)
- Language: Python
- Homepage: https://flowno.net
- Size: 2.36 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Flowno
Flowno is a Python DSL for building concurrent, cyclic, and streaming
[dataflow](https://en.wikipedia.org/wiki/Dataflow_programming) programs - ideal
for designing modular LLM agents. Inspired by no-code flowchart tools like
[ComfyUI](https://github.com/comfyanonymous/ComfyUI), Flowno lets you describe
workflows in code while handling complex dependency resolution (including cycles
and streaming) behind the scenes.
Basically it is yet another attempt at implementing "workflow" style programming.
## Key Features
- **Node-Based Design**
Define processing steps as nodes with a simple decorator. Nodes can be
stateless or stateful - consume, yield or transform streams - single or
multiple outputs.
- **Cycles & Streaming**
Unlike many workflow/flowchart/visual dataflow tools, Flowno supports cyclic
graphs and streaming edges. Use default values to bootstrap cycles.
- **Concurrent By Default**
The Flowno runtime schedules nodes to run as soon as their inputs are ready.
Flowno provides a set of basic non-blocking concurrency primitives.
- **~~Type-Checked & Autocompleted~~**
TODO
~~Flowno works well with type checkers and IDEs to catch incompatible~~
~~connections between nodes.~~
## Quickstart
Set up a virtual environment and install Flowno:
```bash
python -m venv .venv # Requires Python 3.10+
source .venv/bin/activate # On Windows use: .venv\Scripts\activate
pip install flowno
```
Create a minimal flow (`hello.py`):
```python
from flowno import node, FlowHDL
@node
async def Add(x, y):
return x + y
@node
async def Print(value):
print(f"Value: {value}")
with FlowHDL() as f:
f.sum = Add(1, 2)
f.print = Print(f.sum)
f.run_until_complete()
```
```bash
(.venv) $ python hello.py
Value: 3
```
## How It Works
Flowno has three key components that work together to create dataflow programs:
### 1. Node Creation
The `@node` decorator transforms `async` functions (or classes) into a
constructor for a new subclass of `DraftNode`. The transformed function
takes takes connections to other nodes or constant values as arguments and
returns a `DraftNode` instance.
```python
@node
async def Add(x, y):
return x + y
draft_node_1 = Add(1, 2) # Creates a node that will add 1 and 2
draft_node_2 = Add(draft_node_1, 3) # Connects to the output of draft_node_1 to first input of draft_node_2
```
### 2. Flow Description
The `FlowHDL` context manager provides a declarative way to define node
connections. Inside this context, nodes are assigned as attributes and can reference
other nodes' outputs:
```python
with FlowHDL() as f:
f.node_a = Add(1, 2) # No references
f.node_b = Add(f.node_a, 1) # Backward reference
f.node_c = Add(f.node_d, 1) # Forward reference
f.node_d = Add(f.node_c, 1) # Backward reference creating a cycle
```
The context uses Python's `__getattr__` method to return placeholder objects when
accessing undefined attributes like `f.node_d`. These forward references are a core
feature of Flowno - they're not errors. However, each forward-referenced node must
eventually be defined in the flow (as shown in the last line for `f.node_d`). During
`__exit__`, the placeholders are resolved into proper node connections, and all
`DraftNode` instances are finalized into full `Node` objects.
This mechanism allows you to define nodes in any order, which simplifies the
construction of cyclic graphs.
### 3. Execution
When you call `f.run_until_complete()`, Flowno executes your flow:
1. Identifies nodes ready to run (those with all inputs available)
2. Executes ready nodes concurrently
3. Propagates outputs to dependent nodes
4. For cyclic flows, uses default values to bootstrap the cycle
The runtime is asynchronous - nodes only wait for their direct dependencies and
run concurrently with other nodes. Execution continues until all nodes complete
or, for cyclic flows, until an uncaught exception occurs.
## Features TODO
- **Conditional Nodes**
Currently all nodes are executed unconditionally. The only way to skip a node is to add an immediate return statement to bypass the node's logic. I plan to add a way to conditionally execute nodes based on the output of other nodes.
## Non-Goals
- **Visual Editor**
Flowno is a DSL for defining dataflows in code. It does not include a visual
editor for creating flows. I have a crude prototype of a visual editor, but I
just don't see the value in dragging and dropping nodes. A visual editor can't
be used by a LLM agent, for example.
- **Backpropagation**
Flowno is not a machine learning framework. I considered adding some sort of
automatic differentiation, but I could never do it as well as PyTorch, and
cycles would be difficult.
## About The Naming Conventions
> A Foolish Consistency is the Hobgoblin of Little Minds
>
> -- Style Guide for Python Code (PEP-8)
My naming conventions deviate from standard Python style. I capitalize node names
(like `Add` instead of `add`) because they are factory functions that behave like
classes - when you call a decorated node function, it returns a `DraftNode`
instance.
The `FlowHDL` context with its `f.node_name = Node()` syntax is an abuse of
Python's `__getattr__` method. However, this approach gets you:
- LSP type checking support
- Slightly better IDE autocomplete functionality
- Forward references for natural cycle definitions
## License
Flowno is released under the MIT License.