Adrian/viz (#163)

* cp

* wip

* wip

* wip

* working again

* test gha

* fix precommits

* Add llama-index-utils-workflow release

* woops

* clean up pyproject

* Update docs

* ugly toml sort fix

* oops

Author: adrianlyjak

.github/workflows/lint.yml

@@ -18,5 +18,5 @@ jobs:
       - name: Run linter
         shell: bash
         run: |
-          uv sync --all-extras
+          uv sync --all-extras --all-packages
           uv run -- pre-commit run -a

.github/workflows/publish_release.yml

@@ -19,7 +19,8 @@ on:
         type: string
   push:
     tags:
-      - "v*"
+      - "v*"                       # core package tags
+      - "*@v*"                    # package-scoped tags like package@v1.2.3
 
 jobs:
   build-n-publish:
@@ -28,6 +29,15 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+    strategy:
+      fail-fast: false
+      matrix:
+        package: [llama-index-workflows, llama-index-utils-workflow]
+        include:
+          - package: llama-index-workflows
+            is_core: true
+          - package: llama-index-utils-workflow
+            is_core: false
 
     steps:
       - uses: actions/checkout@v4
@@ -37,42 +47,76 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v6
 
-      - name: Validate version
-        if: startsWith(github.ref, 'refs/tags/')
+      - name: Parse tag
+        id: tag
+        run: |
+          REF_NAME="${GITHUB_REF_NAME}"
+          if [[ "${REF_NAME}" == v* ]]; then
+            PKG="llama-index-workflows"
+            VERSION="${REF_NAME#v}"
+          else
+            # strip optional leading '@'
+            REF_TRIMMED="${REF_NAME#@}"
+            PKG_PART="${REF_TRIMMED%@v*}"
+            PKG="${PKG_PART}"
+            VERSION_PART="${REF_TRIMMED#*@v}"
+            VERSION="${VERSION_PART}"
+          fi
+          echo "package=${PKG}" >> $GITHUB_OUTPUT
+          echo "version=${VERSION}" >> $GITHUB_OUTPUT
+
+      - name: Compute directory flag
+        id: dir
+        run: |
+          if [ "${{ matrix.is_core }}" = "true" ]; then
+            echo "dir_flag=" >> $GITHUB_OUTPUT
+          else
+            echo "dir_flag=--directory packages/${{ matrix.package }}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Guard non-target matrix entry
+        if: steps.tag.outputs.package != matrix.package
+        run: echo "Skipping matrix package ${{ matrix.package }} for tag ${{ steps.tag.outputs.package }}" && exit 0
+
+      - name: Validate version (core only)
+        if: startsWith(github.ref, 'refs/tags/') && matrix.is_core == true
         run: uv run python scripts/validate_version.py
 
       - name: Set version output
         id: version
         run: |
-          VERSION=$(uv run python -c "from importlib.metadata import version; print(version('llama-index-workflows'))")
+          VERSION=$(uv run ${{ steps.dir.outputs.dir_flag }} python -c "from importlib.metadata import version; print(version('${{ matrix.package }}'))")
           echo "Version: $VERSION"
           echo "version=$VERSION" >> $GITHUB_OUTPUT
 
       - name: Build and publish
         env:
           UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
         run: |
-          uv build
-          uv publish
+          uv build ${{ steps.dir.outputs.dir_flag }}
+          uv publish ${{ steps.dir.outputs.dir_flag }}
 
-      - name: Generate OpenAPI spec
+      - name: Generate OpenAPI spec (core only)
+        if: matrix.is_core == true
         run: |
           uv sync --all-extras
           uv run hatch run server:openapi
 
-      - name: Create GitHub Release
+      - name: Create GitHub Release (core only)
+        if: matrix.is_core == true
         uses: ncipollo/release-action@v1
         with:
           artifacts: "dist/*,openapi.json"
           generateReleaseNotes: true
 
-      - name: Detect change type for tags
+      - name: Detect change type for tags (core only)
         id: detect_change
-        if: startsWith(github.ref, 'refs/tags/')
+        if: startsWith(github.ref, 'refs/tags/') && matrix.is_core == true
         run: uv run python scripts/detect_change_type.py
 
       - name: Set SDK trigger parameters
         id: sdk_params
+        if: matrix.is_core == true
         run: |
           if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
             echo "change_type=${{ github.event.inputs.server_change_type }}" >> $GITHUB_OUTPUT
@@ -84,14 +128,15 @@ jobs:
 
       - name: Generate GitHub App Token
         id: app-token
+        if: matrix.is_core == true
         uses: actions/create-github-app-token@v1
         with:
           app-id: ${{ secrets.CI_BOT_APP_ID }}
           private-key: ${{ secrets.CI_BOT_PRIVATE_KEY }}
           owner: run-llama
 
       - name: Trigger SDK Update
-        if: steps.sdk_params.outputs.change_type != 'none' && steps.sdk_params.outputs.change_type != ''
+        if: matrix.is_core == true && steps.sdk_params.outputs.change_type != 'none' && steps.sdk_params.outputs.change_type != ''
         uses: peter-evans/repository-dispatch@v3
         with:
           token: ${{ steps.app-token.outputs.token }}

.github/workflows/test.yml

@@ -17,6 +17,14 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        package: [llama-index-workflows, llama-index-utils-workflow]
+        include:
+          - package: llama-index-workflows
+            is_root: true
+            coverage_report: true
+          - package: llama-index-utils-workflow
+            is_root: false
+            coverage_report: false
     steps:
       - uses: actions/checkout@v4
         with:
@@ -28,16 +36,22 @@ jobs:
           python-version: ${{ matrix.python-version }}
           enable-cache: true
 
-      - name: Run tests
-        if: matrix.python-version != env.COV_PYTHON_VERSION
-        run: uv run --all-extras pytest
+      - name: Compute directory flag
+        run: |
+          if [ "${{ matrix.is_root }}" = "true" ]; then
+            echo "DIR_FLAG=" >> $GITHUB_ENV
+          else
+            echo "DIR_FLAG=--directory packages/${{ matrix.package }}" >> $GITHUB_ENV
+          fi
+
+      - name: Sync dev dependencies for selected package
+        run: uv sync --all-extras $DIR_FLAG --group dev
 
       - name: Run tests with coverage
-        if: matrix.python-version == env.COV_PYTHON_VERSION
-        run: uv run --all-extras -- pytest --cov --cov-report=xml
+        run: uv run --all-extras $DIR_FLAG -- pytest --cov --cov-report=xml
 
       - name: Report Coveralls
-        if: matrix.python-version == env.COV_PYTHON_VERSION
+        if: matrix.coverage_report == true && matrix.python-version == env.COV_PYTHON_VERSION
         uses: coverallsapp/github-action@v2
         env:
           COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}

docs/src/content/docs/workflows/drawing.md

@@ -23,8 +23,9 @@ draw_all_possible_flows(JokeFlow, filename="joke_flow_all.html")
 
 # Draw an execution
 w = JokeFlow()
-await w.run(topic="Pirates")
-draw_most_recent_execution(w, filename="joke_flow_recent.html")
+handler = w.run(topic="Pirates")
+await handler
+draw_most_recent_execution(handler, filename="joke_flow_recent.html")
 ```
 
 <div id="working-with-global-context-state"></div>

packages/llama-index-utils-workflow/.gitignore

@@ -0,0 +1 @@
+test*.html

packages/llama-index-utils-workflow/README.md

@@ -0,0 +1,30 @@
+# LlamaIndex Utils: Workflow
+
+Utilities for LlamaIndex workflows, including visualization tools.
+
+```bash
+pip install llama-index-utils-workflow
+```
+
+## Features
+
+- **Workflow visualization** with `draw_all_possible_flows()`
+- **Latest execution visualization** with `draw_most_recent_execution()`
+- **Label truncation support** for better readability with long event names
+
+## Usage
+
+```python
+from llama_index.utils.workflow import draw_all_possible_flows
+
+# Basic workflow visualization
+draw_all_possible_flows(my_workflow, "workflow.html")
+
+# With label truncation for long event names (v0.4.0+)
+draw_all_possible_flows(my_workflow, "workflow.html", max_label_length=15)
+
+# Latest execution visualization
+handler = my_workflow.run()
+await handler
+draw_most_recent_execution(handler, "workflow.html")
+```

packages/llama-index-utils-workflow/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = ["pytest>=8.4.2", "pytest-asyncio>=1.0.0", "pytest-cov>=6.1.1"]
+
+[project]
+name = "llama-index-utils-workflow"
+version = "0.4.1"
+description = "llama-index utils for workflows"
+readme = "README.md"
+authors = [{name = "Adrian Lyjak", email = "adrianlyjak@gmail.com"}]
+requires-python = ">=3.9"
+dependencies = [
+  "llama-index-core>=0.14,<0.15.0",
+  "llama-index-workflows>=2.8.3,<3.0.0",
+  "pyvis>=0.3.2"
+]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/llama_index"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/llama_index"]