README.md

metadata

title: VELAI
emoji: 🫧
colorFrom: blue
colorTo: indigo
pinned: false
sdk: docker
app_file: main.py

VELAI

VELAI is a node-based playground for generative AI content creation. It was built as a hands-on teaching tool so groups can explore prompts, remix results, and see how GenAI pipelines fit together—all inside a visual canvas. Learners can create interactive moodboards that evolve over time by chaining and rewiring past generations, something that is difficult to achieve with chat-only or form-based tools.

What VELAI can do

• Bring many people into the same workshop and let each participant experiment with prompts and images at their own pace.
• Build visual flows that convert text to images and transform images into new formats (for example, meshes) without needing code.
• Iterate quickly by duplicating nodes, swapping connections, and progressively refining visuals.
• Import or export graph JSON files to share lesson setups, then resume right where the class left off.

Who this is for

VELAI is designed for educators, facilitators, and creators who want a lightweight way to demonstrate GenAI concepts. Developers can extend it with new services or node types, while non-developers get an approachable, visual interface that works in a browser.

Quickstart for everyone

Prerequisites

• Python 3.12+ and uv installed locally, or Docker if you prefer containers.
• API access for any external models you plan to call from custom services.

Run locally with uv

• Clone the repository and navigate to its root.
• Install dependencies uv sync and start the app: uv run python main.py.
• Open the browser at http://127.0.0.1:7860. If a password is configured, enter it to access the canvas.

Run with Docker

• Build the image: docker build -t velai ..
• Start a container: docker run -p 7860:7860 -e VELAI_APP_PASSWORD=yourpassword -e VELAI_STORAGE_SECRET=changeme -e VELAI_ADMIN_PASSWORD=youradminpassword -e FAL_KEY=falapikey -v $(pwd)/.storage:/app/.storage velai.
• Visit http://127.0.0.1:7860 to begin exploring.

First session walkthrough

• Start from the provided starter graph: a text prompt node feeds a text-to-image generator. Enter a prompt and run the node to produce the first image.
• Duplicate nodes to branch ideas—one prompt can feed several generators with slight tweaks. Connect outputs to new nodes to compare styles side by side.
• Reuse results as inputs. For example, send an image into a downstream node (such as an image-to-mesh converter) to experiment with 3D-friendly assets.
• Save progress through the Project menu by exporting the graph JSON, or import a JSON file to restore a previous lesson setup.
• Rename nodes by clicking on the titles to keep track of used models.
• Press "F" on keyboard to re-frame all nodes on canvas.

Configuration

VELAI uses environment variables for configuration.

Variable	Default	Notes
VELAI_HOST	127.0.0.1	Bind address for the server
VELAI_PORT	7860	Port for the web app
VELAI_STORAGE_PATH	.storage	Base folder for persisted data
VELAI_STORAGE_SECRET	(none)	Required for shared deployments, keep it private
VELAI_APP_PASSWORD	(empty)	Optional UI password gate
VELAI_LOG_LEVEL	INFO	Example: DEBUG

When running in Docker, mount a volume to /app/.storage (or your custom storage path) to keep session data between container restarts.

Deployment notes

Docker is the simplest way to host VELAI for a classroom or team. Use a reverse proxy or load balancer to add TLS, and set VELAI_APP_PASSWORD plus a strong VELAI_STORAGE_SECRET to protect interactive sessions. For multi-tenant workshops, consider running one container per cohort and persisting each cohort’s .storage volume separately.

How VELAI works (developer view)

VELAI uses NiceGUI for the web interface and a lightweight dataflow engine for the node graph. Each browser session owns a GraphSession that wires together three pieces:

• A registry that knows which node types exist and how to instantiate them.
• A data graph that stores nodes, ports, and connections along with their on-canvas positions.
• A renderer/runtime pair that keeps Vue Flow UI elements in sync with backend state and executes node logic when a user triggers a run.

The starter session registers text, image, text-to-image, and image-to-mesh nodes. It also saves the graph to a simple file-based blob storage so users can refresh the page without losing work.

Extending VELAI with new nodes or services

The platform is designed to be pluggable without deep framework knowledge:

• Define the node’s input/output schemas and create a corresponding Python class that performs the work (for example, calling a new model endpoint). Keep the logic focused on translating inputs to outputs rather than UI concerns.
• Register the node type inside GraphSession.create_default so it appears in the Add Node menu. Provide a renderer so the node shows the right controls and status in the canvas.
• If the node interacts with external systems, place those integrations in the services package to keep model calls and storage helpers reusable across nodes.
• Use the existing nodes as templates. They demonstrate how to expose actions (execute, duplicate), how to persist node state, and how to mark outputs as dirty when inputs change.

With these conventions, teams can introduce new GenAI backends or post-processing steps—such as upscalers, safety filters, or format converters—while keeping the visual editing experience consistent for learners.

Project structure at a glance

• main: Bootstraps the NiceGUI app, configures storage, and serves the FastAPI app.
• velai.dataflow: Core data model for nodes, ports, connections, and Vue Flow serialization.
• velai.ui: Vue Flow based canvas component.
• velai.session: Manages the graph session lifecycle, including node registration, persistence, and event handling.
• velai.runtime: Coordinates graph execution for multiple nodes.
• velai.nodes: Content generation nodes (text, image, mesh, ...).
• velai.services: Integrations and reusable helpers for tasks like image generation, progress tracking, and asset handling.
• velai.storage: Basic document and blob storage implementation.
• velai.static: Frontend assets such as styles and images used by the UI.

Support and feedback

Issues and improvements are welcome. If you encounter problems while running a workshop or adding a node, open an issue with details about the flow, the model you were using, and any console logs that appeared. This helps us keep VELAI a smooth teaching companion for GenAI.

About

Initiated by kratadata and cansik while teaching generative-ai in 2025.