Refactor context to (eventually) support runtime plugins (#127)

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 [email protected]
 
 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/api_docs/docs/api_reference/context.md

@@ -3,7 +3,6 @@
       show_root_heading: true
       show_root_full_path: false
       members:
-        - __init__
         - collect_events
         - from_dict
         - get_result

docs/src/content/docs/llamaagents/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>

docs/src/content/docs/llamaagents/workflows/managing_events.md

@@ -117,12 +117,11 @@ async for event in handler.stream_events():
 result = await handler
 ```
 
-There is also the possibility of streaming internal events (such as changes occurring while the step is running, modifications of the workflow state or variations in the size of the internal queues). In order to do so, you need to pass `expose_internal = True` to `stream_events`.
+There is also the possibility of streaming internal events (such as changes occurring while the step is running and modifications of the workflow state). In order to do so, you need to pass `expose_internal = True` to `stream_events`.
 
-All the internal events are instances of `InternalDispatchEvent`, but they can be divided into two sub-classes:
+All the internal events are instances of `InternalDispatchEvent`. The primary internal event is:
 
-- `StepStateChanged`: exposes internal changes in the state of the event, including whether the step is running or in progress, what worker it is running on and what events it takes as input and output, as well as changes in the workflow state.
-- `EventsQueueChanged`: reports the state of the internal queues.
+- `StepStateChanged`: exposes internal changes in the state of the event, including whether the step is PREPARING (queued), RUNNING, or NOT_RUNNING, what worker it is running on and what events it takes as input and output.
 
 Here is how you can stream these internal events:
 
@@ -138,9 +137,6 @@ async for event in handler.stream_events(expose_internal=True):
         print("Input event for current step:", event.input_event_name)
         print("Workflow state at current step:", event.context_state or "No state reported")
         print("Output event of current step:", event.output_event_name or "No output event yet")
-    elif isinstance(event, EventsQueueChanged):
-        print("Queue name:", event.name)
-        print("Queue size:", event.size)
     # other event streaming logic here
 
 result = await handler