# NeuroFlow

A **local-first, node-based ML orchestrator** with a visual pipeline builder.

![NeuroFlow](https://img.shields.io/badge/version-0.2.0-green)
![Python](https://img.shields.io/badge/python-3.9+-blue)
![License](https://img.shields.io/badge/license-MIT-blue)

## Features

- **Visual Pipeline Builder** - Drag-and-drop nodes to create ML workflows
- **Node-Based Architecture** - Connect data loaders, preprocessors, models, and evaluators
- **Custom Python Nodes** - Inject custom Python code directly into your workflows
- **Code View Toggle** - Switch between visual editor and code representation (Overleaf-style)
- **Built-in Visualizations** - View metrics, charts, and model performance
- **Local-First** - All data stays on your machine
- **Export/Import** - Save and share workflows as JSON
- **One Command** - Install and run with a single command

## Quick Start

### Installation

```bash
# Install from PyPI
pip install neuroflow-ml

# Or install from source
git clone https://github.com/aayushgokhale/neuroflow.git
cd neuroflow/NeuroFlow
pip install -e .
```

### Running NeuroFlow

```bash
# Start NeuroFlow (opens browser automatically)
neuroflow

# Or specify a custom port
neuroflow --port 3000

# Don't open browser automatically
neuroflow --no-browser
```

Visit `http://localhost:8000` to access the visual pipeline builder.

## Usage

### Building a Pipeline

1. **Drag nodes** from the left sidebar onto the canvas
2. **Connect nodes** by dragging from output ports to input ports
3. **Configure nodes** by clicking on them and editing parameters
4. **Run the workflow** by clicking the "Run Workflow" button
5. **View results** in the Results Panel with metrics and charts

### Custom Python Nodes

NeuroFlow supports custom Python nodes for maximum flexibility:

1. Click **"Add Custom Node"** in the left sidebar
2. Write your Python code with access to `input_data`, `pd`, `np`, and `sklearn`
3. Set the `output` variable with your results
4. Connect to other nodes and run

### View Toggle (Overleaf-Style)

Switch between visual and code views using the toggle in the top navigation:
- **Visual**: Drag-and-drop node canvas
- **Code**: VS Code-style syntax-highlighted view of all nodes

### Node Types

| Category | Nodes |
|----------|-------|
| **Data** | CSV Loader, SQL Query, API Fetch |
| **Preprocessing** | Normalize, Encode, Split Data, Handle Missing |
| **Models** | Random Forest, Neural Net, XGBoost, Gradient Boosting |
| **Evaluate** | Accuracy Chart, Loss Curve, Confusion Matrix |
| **Custom** | Custom Python Node |

### Example Workflow

```
CSV Loader -> Split Data -> Random Forest -> Evaluator
```

## Development

### Prerequisites

- Python 3.9+
- Node.js 18+
- pnpm (recommended)

### Setup

```bash
# Clone the repository
git clone https://github.com/aayushgokhale/neuroflow.git
cd neuroflow

# Install backend dependencies
cd NeuroFlow
pip install -e ".[dev]"

# Install frontend dependencies
cd ../Frontend
pnpm install

# Run development servers
# Terminal 1: Backend
cd NeuroFlow && uvicorn app.main:app --reload

# Terminal 2: Frontend
cd Frontend && pnpm dev
```

### Building for Distribution

```bash
cd NeuroFlow
./build.sh
pip install -e .
```

## Project Structure

```
neuroflow/
|-- Frontend/                 # Next.js frontend
|   |-- app/                  # App router pages
|   |-- components/           # React components
|   |   |-- neuroflow/        # NeuroFlow-specific components
|   |-- public/               # Static assets
|-- NeuroFlow/                # Python backend package
|   |-- app/                  # FastAPI application
|   |   |-- cli.py            # CLI entry point
|   |   |-- main.py           # FastAPI app
|   |   |-- engine.py         # Workflow execution engine
|   |   |-- schemas.py        # Pydantic models
|   |   |-- executors/        # Node executors
|   |-- data/                 # Demo datasets
|   |-- static/               # Built frontend (after build)
|   |-- pyproject.toml        # Package configuration
```

## API Reference

### REST Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/health` | Health check |
| `POST` | `/api/workflows/execute/sync` | Execute a workflow synchronously |
| `POST` | `/api/workflows/execute` | Execute a workflow asynchronously |
| `GET` | `/api/workflows/{id}/status` | Get execution status |
| `POST` | `/api/data/upload` | Upload data files |
| `GET` | `/api/models/{id}/download` | Download trained model |

### WebSocket

Connect to `/ws/workflow/{run_id}` for real-time execution progress updates.

## Changelog

### v0.2.0 (2026-03-04)

**New Features**
- Added Overleaf-style view toggle between visual editor and code view
- Added custom Python node support with inline code execution
- Added custom node drawer for creating nodes with configurable inputs/outputs
- Added "Load Custom Nodes Demo" workflow showcasing custom node capabilities
- Added edit/save functionality in code view

**Improvements**
- Improved JSON serialization for pandas/numpy objects in workflow results
- Enhanced storage manager with proper type conversion
- Updated node icons - custom nodes now use Code2 icon
- Better error handling in workflow execution

**Bug Fixes**
- Fixed async executor issues with custom Python nodes
- Fixed pandas Series serialization errors in API responses
- Fixed connection line rendering on canvas zoom

### v0.1.0 (2026-02-15)

**Initial Release**
- Visual drag-and-drop pipeline builder
- Node-based ML workflow architecture
- Built-in node types: Data, Preprocessing, Models, Evaluation
- Local-first execution with FastAPI backend
- Demo workflow with auto-mpg dataset
- Export/import workflows as JSON
- Real-time execution progress via WebSocket

## License

MIT License - see [LICENSE](LICENSE) for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Contact

Created by [Aayush Gokhale](https://github.com/aayushgokhale)
