modusflow 1.0.0
A self-hostable, zero-cost, local-first automation platform for creating and running visual workflows
License: MIT
Requires Python: >=3.8
Keywords: workflow, automation, dag, visual, local-first

# ModusFlow

A self-hostable, zero-cost, local-first automation platform for creating and running visual workflows.

## Features

- 🎨 **Visual Workflow Editor**: Drag-and-drop interface using React Flow
- 🤖 **AI-Assisted Generation**: Generate workflows from plain English prompts
- ⚡ **Async DAG Engine**: Parallel execution where possible
- 💾 **Local-First**: SQLite for history, JSON/YAML for workflows (Git-friendly)
- 🖥️ **CLI Tool**: Headless execution and validation
- 🔧 **Node Types**: Python scripts, HTTP requests, AI models, Shell commands, Delays
- 📊 **Live Logging**: Real-time execution logs per node
- 💰 **Cost Estimation**: Token and cost tracking for AI nodes
- 🔄 **Error Handling**: Retries, on_fail paths, custom error handling

## Quick Start

### Prerequisites

- Python 3.8+
- Node.js 16+
- (Optional) API keys for AI providers (Anthropic, OpenAI, or OpenRouter)

### Backend Setup

```bash
cd backend
pip install -r requirements.txt

# Copy .env.example to .env and add your API keys
cp .env.example .env

# Start the backend
uvicorn app.main:app --reload --port 8000
```

### Frontend Setup

```bash
cd frontend
npm install
npm run dev
```

Visit `http://localhost:5173` to access the visual editor.

### CLI Installation

```bash
cd cli
pip install -e .
```

### CLI Usage

```bash
# Run a workflow
modusflow run data/workflows/example_web_scraper.json

# Generate a workflow from a prompt
modusflow generate "scrape a website and summarize with AI" -o my_workflow.json

# Validate a workflow
modusflow validate data/workflows/example_web_scraper.json
```

## Architecture

- **Backend**: FastAPI + Python async execution engine
- **Frontend**: React + TypeScript + React Flow + Monaco Editor
- **Storage**: 
  - SQLite database for execution history (`data/modusflow.db`)
  - JSON/YAML files for workflows (`data/workflows/*.json`)
- **AI**: Free-tier LLMs via Anthropic (Claude Haiku), OpenAI (GPT-3.5), or OpenRouter

## Node Types

### Python Node
Execute Python code. Output should be JSON-printable or plain text.
```python
import json
result = {"message": "Hello, World!"}
print(json.dumps(result))
```

### HTTP Node
Make HTTP requests (GET, POST, PUT, DELETE, PATCH).
```json
{
  "url": "https://api.example.com/data",
  "method": "GET",
  "headers": {"Authorization": "Bearer token"}
}
```

### AI Node
Call AI models (Claude, GPT, etc.).
```json
{
  "provider": "anthropic",
  "model": "claude-3-haiku-20240307",
  "prompt": "Summarize: ${previous_node}",
  "system_prompt": "You are a helpful assistant."
}
```

### Shell Node
Execute shell commands.
```json
{
  "command": "ls -la | head -10"
}
```

### Delay Node
Wait for a specified duration.
```json
{
  "seconds": 2.5
}
```

## Using Node Outputs

Reference outputs from previous nodes using `${node_id}` syntax:

```json
{
  "prompt": "Summarize this: ${fetch_node}"
}
```

## Error Handling

- **Retries**: Set `retries` and `retry_delay` on any node
- **On-Fail Path**: Set `on_fail` to a node ID that executes on failure
- **Status Tracking**: Each node tracks success/failure status

## Docker Deployment

```bash
# Build and run with Docker Compose
docker-compose up --build

# Or build manually
docker build -t modusflow .
docker run -p 8000:8000 -v $(pwd)/data:/app/data modusflow
```

## Development

### Project Structure

```
ModusFlow1/
├── backend/           # FastAPI backend
│   ├── app/
│   │   ├── main.py   # FastAPI app
│   │   ├── executor.py  # DAG execution engine
│   │   ├── ai_client.py  # AI provider clients
│   │   ├── routes/      # API routes
│   │   └── models.py    # Pydantic models
│   └── requirements.txt
├── frontend/         # React frontend
│   ├── src/
│   │   ├── components/  # React components
│   │   ├── store/       # Zustand state
│   │   └── types.ts     # TypeScript types
│   └── package.json
├── cli/              # CLI tool
│   └── modusflow/
│       └── cli.py
└── data/             # Data directory
    ├── workflows/    # Workflow JSON files
    └── modusflow.db  # SQLite database
```

## License

MIT