Minimal Workflow Engine

A lightweight, async-first workflow orchestration engine with a premium "Command Center" frontend. Designed for building, running, and visualizing agentic workflows with ease.

Features • Installation • Usage • Frontend • Architecture

---

⚡ Features

Core Engine

• Graph-Based Execution: Define workflows as directed graphs with Nodes (steps) and Edges (logic).
• Cyclic Graphs: Native support for loops (e.g., "Review -> Fix -> Review" cycles).
• Conditional Branching: Dynamic path selection based on state.
• Async Native: Fully asynchronous execution core supporting async def nodes.
• State Management: Shared dictionary-based state passed between all nodes.

Advanced Capabilities

• WebSocket Streaming: Real-time event streaming for live visualization of step execution.
• Persistence: SQLite-backed storage for run history and state recovery.
• Tool Registry: Simple decorator-based system for registering agent tools.
• REST API: Full FastAPI suite for creating runs and querying logic.

---

🚀 Installation

1. Clone & Setup

git clone https://github.com/yourusername/minimal-workflow-engine.git
cd minimal-workflow-engine

2. Install Dependencies

pip install -r requirements.txt

3. Run the Server

python3 -m uvicorn app.main:app --reload --port 8000

The application will start at http://localhost:8000

---

🎮 Frontend "Command Center"

Access the MonitorOS-style dashboard at http://localhost:8000.

Key UI Features:

1. Source Code Input: Edit the python code you want the agent to review.
2. Neural Topology: A real-time visualizer showing the active node in the workflow graph.
3. System Terminal: Live log stream of the execution process via WebSockets.
4. Updated Code: The final output generated by the agent.

How to Use:

1. Open the dashboard.
2. Modify the code in the left "Source Code" panel.
3. Click INITIALIZE AGENT.
4. Watch the graph light up and logs stream as the "Code Review Agent" analyzes your code.
5. See the improvements in the right "Updated Code" panel.

---

🛠 Usage (API)

You can also interact with the engine purely via curl or HTTP clients.

Trigger a Run

curl -X POST "http://127.0.0.1:8000/graph/run" \
  -H "Content-Type: application/json" \
  -d '{
    "graph_id": "code-review-v1", 
    "initial_state": {
        "code": "def hello(): print("world")"
    }
}'

Retrieve State

GET /graph/state/{run_id}

---

🏗 Architecture

The project follows a clean, modular structure:

app/
├── main.py              # Application Entry & Endpoints
├── engine.py            # Core Graph Execution Logic
├── db.py                # Database Persistence Layer
├── registry.py          # Tool/Function Registry
├── workflows/           # Workflow Definitions
│   └── code_review.py   # Sample "Code Review" Graph
└── static/              # Frontend Assets
    ├── index.html       # Command Center Layout
    ├── style.css        # Premium Glassmorphism Styles
    └── script.js        # WebSocket & UI Logic

---

🧩 Default Workflow: Code Review Agent

The engine comes pre-loaded with a Code Review Workflow:

1. Extract: Parses the input Python code.
2. Analyze: Checks complexity and style.
3. Issues?: Decides if the code needs improvement (Branching).
4. Improve: Modifies the code (adding types, docstrings) if needed.
5. Loop: Re-analyzes the new code until it passes checks.

---

Built with 🖤 by @ssanidhya0407