KAI Flow: a visual platform for building AI-powered assistants

Using a simple drag-and-drop interface, you can design workflows that answer questions, search the web, process documents, and automate tasks. All workflows are created and managed on a visual canvas, allowing you to see how each component works together. You can test your assistants in real time, adjust their behavior, and deploy them with confidence.

🎬 Showcase

---

📚 Table of Contents

• ⚡ Quick Start with Docker
• 💻 Local Development (Python venv / Conda)
• 🧭 VS Code Debugging
• 🧱 Project Structure
• ✨ App Overview
• 📊 Repository Stats
• 🙌 Contributing
• 🆘 Troubleshooting
• 🤝 Code of Conduct
• 📝 License

⚡ Quick Start with Docker 🐳

Step 1 — Configure Environment Variables

Rename `.env.example` to `.env` in the project root directory and update the values as needed.

Step 2 — Start the Backend & Frontend

docker compose up -d

Once running, open:

• Frontend: http://localhost:23058
• Backend (Swagger): http://localhost:23056/docs

💻 Local Development (Python venv / Conda)

Prerequisites

• Python 3.11
• Node.js ≥ 18.15

Step 1 — Configure Environment Variables

Rename `.env.example` to `.env` in the project root directory and update the values as needed.

Step 2 - Edit Constant in .env file

Replace host.docker.internal with 127.0.0.1 in the DATABASE_URL variable in the .env file.

Step 3 — Set Up a Python Environment

Option A — venv (recommended)

python -m venv .venv

# Windows (Command Prompt)
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install --upgrade pip
pip install -r backend/requirements.txt

Option B — Conda

conda create -n kai-flow python=3.11 -y
conda activate kai-flow
pip install -r backend/requirements.txt

---

Step 4 — Start PostgreSQL

docker run --name kai ^
  -e POSTGRES_DB=kai ^
  -e POSTGRES_USER=kai ^
  -e POSTGRES_PASSWORD=kai ^
  -p 5432:5432 ^
  -d postgres:15

Step 5 — Initialize the Database Schema

Ensure your PostgreSQL container is running, then:

python backend/migrations/database_setup.py

Step 6 — Run the Backend

python backend/main.py

Step 7 — Run the Frontend open another terminal

cd client
npm install
npm run dev
# Open the printed Vite URL (e.g. http://localhost:5173)

---

SSL Certificates (Optional)

To run the backend with HTTPS locally, generate self-signed certificates:

cd backend/cert

# Windows (PowerShell)
$env:OPENSSL_CONF="C:\Program Files\Git\usr\ssl\openssl.cnf"; openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/C=TR/ST=Istanbul/L=Istanbul/O=KAI/OU=Dev/CN=localhost"

# macOS / Linux
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj "/C=TR/ST=Istanbul/L=Istanbul/O=KAI/OU=Dev/CN=localhost"

---

Widget (Embeddable)

A standalone chat widget for embedding KAI‑Flow agents into other sites.

cd widget
npm install
npm run dev

🧭 VS Code Debugging (.vscode/launch.json)

Create the folder: .vscode/ at the repository root and add launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Backend Main",
      "type": "python",
      "request": "launch",
      "program": "${workspaceFolder}/backend/main.py",
      "console": "integratedTerminal",
      "env": { "DOTENV_PATH": "${workspaceFolder}/.env" }
    }
  ]
}

🧱 Project Structure

KAI-Flow/
├─ backend/                 # FastAPI Backend (Python 3.11)
│  ├─ app/
│  │  ├─ api/               # REST API endpoints
│  │  ├─ auth/              # Authentication logic
│  │  ├─ core/              # Core utilities (config, engine, etc.)
│  │  ├─ middleware/         # Custom middleware
│  │  ├─ models/            # SQLAlchemy database models
│  │  ├─ nodes/             # Workflow node definitions
│  │  │  ├─ agents/         # AI Agent nodes
│  │  │  ├─ llms/           # LLM provider nodes
│  │  │  ├─ tools/          # Tool nodes (web search, code, etc.)
│  │  │  ├─ memory/         # Memory / context nodes
│  │  │  ├─ embeddings/     # Embedding nodes
│  │  │  ├─ vector_stores/  # Vector store nodes
│  │  │  ├─ splitters/      # Text splitter nodes
│  │  │  ├─ triggers/       # Workflow trigger nodes
│  │  │  └─ document_loaders/
│  │  ├─ schemas/           # Pydantic schemas
│  │  ├─ services/          # Business logic services
│  │  └─ routes/            # Route definitions
│  ├─ migrations/           # Database setup scripts
│  ├─ main.py               # Application entry point
│  └─ requirements.txt      # Python dependencies
├─ client/                  # React 19 Frontend
│  ├─ app/
│  │  ├─ components/        # React components
│  │  │  ├─ canvas/         # Workflow canvas
│  │  │  ├─ nodes/          # Node UI components
│  │  │  └─ modals/         # Configuration modals
│  │  ├─ routes/            # Page routes
│  │  ├─ services/          # API service layer
│  │  ├─ stores/            # Zustand state stores
│  │  └─ lib/               # Utilities
│  ├─ package.json
│  └─ vite.config.ts
├─ widget/                  # Embeddable Chat Widget
│  ├─ src/                  # Widget source
│  ├─ widget.js             # Pre-built widget bundle
│  └─ package.json
├─ docs/                    # Documentation (MkDocs)
├─ .env.example             # Environment variable template
├─ docker-compose.yml       # Docker Compose configuration
├─ Dockerfile               # Backend Docker image
└─ README.md

✨ App Overview (What you can build)

• Visual Workflow Builder: Drag-and-drop interface powered by XYFlow 12 for creating AI agents and chains.
• Modern Tech Stack: React 19.1, React Router 7, Vite 6.3, Tailwind 4.1, DaisyUI 5 (Frontend) + FastAPI 0.116, LangChain 0.3, LangGraph 0.6 (Backend).
• AI/ML Framework: Integrated LangChain, LangGraph, and LangSmith for building and debugging complex agent flows.
• Vector Database: PostgreSQL with pgvector for embedding storage and semantic search.
• Node Types: LLMs, Agents, Tools (Web Search, Code Execution), Memory, Embeddings, Vector Stores, Document Loaders, Text Splitters, Triggers.
• Embeddable Widget: Export your agents as an embeddable widget (@kaiflow/widget on npm).
• Secure: JWT-based authentication with Keycloak integration support.
• Scheduling: Built-in cron-based workflow scheduling with APScheduler.

📊 Repository Stats (⭐ Stars & ⬇️ Downloads)

⭐ Star History

⬇️ Downloads

Metric	Badge
All releases (total)
Latest release
Stars (live)
Forks (live)

🙌 Contributing

We welcome PRs! Please:

1. Open an issue describing the change or bug.
2. Fork the repo and create a feature branch.
3. Add or adjust tests where applicable.
4. Open a PR with a clear description and screenshots/GIFs.

👥 Contributors

⭐ Stargazers & 🍴 Forkers

⭐ Stargazers · 🍴 Forkers

🆘 Troubleshooting

Port 5432 already in use

• Stop any existing Postgres: docker ps, then docker stop <container>
• Or change the host port mapping: -p 5433:5432

Cannot connect to Postgres

• Verify env values in the root .env file
• Ensure container is healthy: docker logs kai

Migrations didn’t run / tables missing

• Re-run from backend directory: python -m migrations.database_setup
• Ensure CREATE_DATABASE=true in the root .env file

Frontend cannot reach backend

• Check client/.env → VITE_API_BASE_URL=http://localhost:8000
• CORS: ensure backend CORS is configured for your dev origin

VS Code doesn’t load env

• Using our snippet? Make sure your app reads DOTENV_PATH
• Alternative: VS Code "envFile": "${workspaceFolder}/.env"

🤝 Code of Conduct

Please follow our Contributor Covenant Code of Conduct to keep the community welcoming.

📝 License

Source code is available under the Apache License 2.0 — see LICENSE for details.