Spaces:
Running
Running
| 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](https://docs.astral.sh/uv/) installed locally, or [Docker](https://www.docker.com/) 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](https://nicegui.io/) 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](https://vueflow.dev/) 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](https://github.com/kratadata) and [cansik](https://github.com/cansik) while teaching generative-ai in 2025. |