README.md

---
title: Agentic Workflow Node Lab
emoji: 🤖
colorFrom: indigo
colorTo: yellow
sdk: docker
app_port: 7860
pinned: false
---

# Agentic Workflow Lab

A deliberately small educational workflow simulator. Build a graph with **Input**, **AI Worker**, **Decision Rules**, **Human Review**, **Simulated Tool**, and **Output** nodes, then send one item through it at a time. Actions and integrations are simulations only.

## Local setup (Conda + VS Code)

1. Install [Miniconda](https://docs.conda.io/projects/miniconda/en/latest/) and Node.js 20+.
2. In this folder, create the environment:

   ```bash
   conda env create -f environment.yml
   conda activate workflow-lab
   cp .env.example .env
   ```

3. Put your server-side API key in `.env`. The browser never receives it.
4. In VS Code, run **Tasks: Run Task → Start app**, or use two terminals:

   ```bash
   uvicorn backend.main:app --reload --port 8000
   cd frontend && npm install && npm run dev
   ```

Open <http://localhost:5173>. The frontend proxies `/api` calls to FastAPI.

## LLM settings

The backend uses the OpenAI Python SDK and supports OpenAI-compatible endpoints:

```dotenv
OPENAI_API_KEY=...
OPENAI_MODEL=gpt-4.1-mini
# OPENAI_BASE_URL=https://your-compatible-endpoint/v1
```

Without a key, the app runs in deterministic demo mode so the workflow UI can still be taught and tested.

## How execution works

- Exactly one item enters through an Input node.
- Solid workflow connections determine what runs next.
- Purple dashed tool connections grant an AI Worker access to a Simulated Tool; they do not advance the workflow.
- AI Workers see each attached tool's name, description, expected input, and prior results. They decide at runtime whether to call a tool, may call up to five tools, and then produce their final work.
- Simulated Tools return prompt-generated information or simulated actions. They never invoke a real integration.
- Decision Rules return the ID of one connected target using route labels and explicit plain-English rules.
- Human Review is a dedicated node that pauses on the server; the learner replies in English, then execution resumes.
- Output ends the run and displays the accumulated result and event trace.
- Safety limits of 50 workflow steps and five tool calls per worker prevent accidental loops.

### The two connection types

```text
Input ──flow──> AI Worker ──flow──> Decision Rules ──flow──> Output
                    │
                    └──tool access (dashed)──> Simulated Tool
```

Select a workflow connection to give it a route label such as `High risk` or `Standard response`. Decision Rules uses these labels when applying its English rules.

Workflow JSON can be downloaded and loaded in the browser. The JSON stores the canvas, connections, node settings, and input text—never API keys.

## Hugging Face Spaces deployment

Create a new **Docker Space**, upload this repository, and add `OPENAI_API_KEY` as a Space **Secret**. Optionally add `OPENAI_MODEL` and `OPENAI_BASE_URL` as variables/secrets. The included `Dockerfile` builds React and serves it from FastAPI on port 7860.

For Git-based deployment:

```bash
git remote add space https://huggingface.co/spaces/YOUR_NAME/YOUR_SPACE
git push space main
```

Do not commit `.env`; it is ignored.

## Project map

```text
backend/                 FastAPI API, execution engine, prompt templates
frontend/                React + React Flow visual editor
.vscode/tasks.json       one-click local development task
environment.yml          Conda environment
Dockerfile               Hugging Face Spaces build
```