From 8ca1b9ba15f5380d2eb5e88ac2571ea9e89a5474 Mon Sep 17 00:00:00 2001 From: Thuc Pham <51660321+thucpn@users.noreply.github.com> Date: Thu, 18 Sep 2025 10:45:44 +0700 Subject: [PATCH] feat: viz-node (#187) --- .changeset/metal-facts-guess.md | 6 + demo/visualization/README.md | 81 ++++- demo/visualization/index.html | 2 +- demo/visualization/package.json | 4 +- demo/visualization/src/main.ts | 9 - demo/visualization/src/viz-browser.ts | 15 + demo/visualization/src/viz-node.ts | 17 + demo/visualization/src/workflow.ts | 52 ++- packages/graph/biome.json | 7 + packages/graph/package.json | 58 ++++ packages/{viz => graph}/src/graph.ts | 0 packages/graph/src/index.ts | 1 + packages/{viz => graph}/src/parser.ts | 0 .../{viz => graph}/src/tests/graph.test.ts | 0 packages/{viz => graph}/src/types.ts | 0 packages/graph/tsconfig.json | 11 + packages/graph/vitest.config.ts | 9 + packages/viz-node/biome.json | 7 + packages/viz-node/package.json | 63 ++++ packages/viz-node/src/canvas.ts | 22 ++ packages/viz-node/src/drawing.ts | 136 ++++++++ packages/viz-node/src/index.ts | 5 + packages/viz-node/src/tests/canvas.test.ts | 52 +++ packages/viz-node/tsconfig.json | 11 + packages/viz-node/vitest.config.ts | 9 + packages/viz/package.json | 5 +- packages/viz/src/drawing.ts | 2 +- pnpm-lock.yaml | 310 +++++++++++++++++- pnpm-workspace.yaml | 1 + tsconfig.json | 6 + 30 files changed, 840 insertions(+), 61 deletions(-) create mode 100644 .changeset/metal-facts-guess.md delete mode 100644 demo/visualization/src/main.ts create mode 100644 demo/visualization/src/viz-browser.ts create mode 100644 demo/visualization/src/viz-node.ts create mode 100644 packages/graph/biome.json create mode 100644 packages/graph/package.json rename packages/{viz => graph}/src/graph.ts (100%) create mode 100644 packages/graph/src/index.ts rename packages/{viz => graph}/src/parser.ts (100%) rename packages/{viz => graph}/src/tests/graph.test.ts (100%) rename packages/{viz => graph}/src/types.ts (100%) create mode 100644 packages/graph/tsconfig.json create mode 100644 packages/graph/vitest.config.ts create mode 100644 packages/viz-node/biome.json create mode 100644 packages/viz-node/package.json create mode 100644 packages/viz-node/src/canvas.ts create mode 100644 packages/viz-node/src/drawing.ts create mode 100644 packages/viz-node/src/index.ts create mode 100644 packages/viz-node/src/tests/canvas.test.ts create mode 100644 packages/viz-node/tsconfig.json create mode 100644 packages/viz-node/vitest.config.ts diff --git a/.changeset/metal-facts-guess.md b/.changeset/metal-facts-guess.md new file mode 100644 index 0000000..6749e1b --- /dev/null +++ b/.changeset/metal-facts-guess.md @@ -0,0 +1,6 @@ +--- +"@llamaindex/workflow-viz-node": patch +"@llamaindex/workflow-viz": patch +--- + +Generate workflow visualization in Node.js diff --git a/demo/visualization/README.md b/demo/visualization/README.md index d3f1306..2fc9d28 100644 --- a/demo/visualization/README.md +++ b/demo/visualization/README.md @@ -1,13 +1,16 @@ -### Workflow Visualization Demo +# Workflow Visualization Demo -A minimal Vite + TypeScript + React demo that visualizes an example `@llamaindex/workflow-core` graph using `@llamaindex/workflow-viz` and Sigma.js. +This demo showcases two different ways to visualize `@llamaindex/workflow-core` graphs: -### Prerequisites +1. **Browser Visualization**: Interactive web-based graph using Sigma.js +2. **Node.js Image Generation**: Generate static PNG images using node-canvas + +## Prerequisites - **Node.js**: v20 or newer - **npm** (bundled with Node.js) -### Install +## Installation From the repo root: @@ -16,6 +19,12 @@ cd demo/visualization npm install ``` +--- + +## 🌐 Browser Visualization + +Interactive web-based workflow visualization using Sigma.js for real-time graph rendering. + ### Run in development ```bash @@ -38,13 +47,67 @@ npm run preview Open the preview server at [http://localhost:4173](http://localhost:4173) (or the port shown in the terminal). -### What this demo does +### What it does -- Defines a small workflow in `src/workflow.ts` using `createWorkflow` and wraps it with `withDrawing` to add drawing capabilities. -- Use `draw` method of the workflow to render it in a HTML container in `src/main.ts` using force-directed layout. +- Defines a workflow in `src/workflow.ts` using `createWorkflow` and wraps it with `withDrawing` to add drawing capabilities +- Uses the `draw` method to render the workflow in an HTML container using force-directed layout +- Provides interactive graph navigation, zoom, and pan capabilities ### Key files -- `src/workflow.ts`: Example workflow (events, handlers) - adding drawing capabilities -- `src/main.ts`: Renders the workflow in a HTML container using force-directed layout +- `src/workflow.ts`: Example workflow (events, handlers) with drawing capabilities +- `src/viz-browser.ts`: Browser visualization entry point +- `src/style.css`: Styling for the visualization +- `index.html`: HTML container for the visualization - `vite.config.ts`: Vite config with React SWC plugin + +--- + +## 🖼️ Node.js Image Generation + +Generate static PNG images of workflow graphs using node-canvas for documentation, reports, or automated workflows. + +### Generate Graph as PNG image + +```bash +npm run generate +``` + +This will create `workflow.png` in the current directory. + +> **Note:** This uses `node-canvas`, which requires native dependencies. +> +> **On macOS:** +> +> ```bash +> brew install pkg-config cairo pango libpng jpeg giflib librsvg +> ``` +> +> **On Ubuntu/Debian:** +> +> ```bash +> sudo apt-get install build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev +> ``` +> +> **For pnpm v10+:** Run `pnpm approve-builds` or add `enable-pnpm-unsafe-build-scripts=true` to `.npmrc`. + +### What it does + +- Uses the same workflow definition from `src/workflow.ts` +- Wraps the workflow with `withDrawingNode` for Node.js image generation +- Generates a high-quality PNG image with configurable dimensions and layout +- Perfect for automated documentation, CI/CD pipelines, or batch processing + +### Key files + +- `src/workflow.ts`: Shared workflow definition (events, handlers) +- `src/viz-node.ts`: Node.js image generation entry point +- `package.json`: Contains the `generate` script + +--- + +## Shared Components + +Both examples use the same underlying workflow definition: + +- **`src/workflow.ts`**: Contains the example workflow with events and handlers that both browser and Node.js examples can use diff --git a/demo/visualization/index.html b/demo/visualization/index.html index 0ad9f4d..e500a14 100644 --- a/demo/visualization/index.html +++ b/demo/visualization/index.html @@ -9,6 +9,6 @@
- +