run_tutorials.yml

name: Run Tutorials

on:
  workflow_dispatch: # Activate this workflow manually
  schedule:
    - cron: "0 0 * * *"
  pull_request:
    paths:
      - "tutorials/*.ipynb"

jobs:
  generate-matrix:
    runs-on: ubuntu-slim
    outputs:
      matrix: ${{ steps.matrix.outputs.matrix }}
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
        with:
          python-version: "3.11"

      - id: generator
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          # Get tutorial notebooks
          VERSION=$(gh api /repos/deepset-ai/haystack/releases | \
            jq -r '[.[].tag_name | select(test("^v2.[0-9]+.[0-9]+$"))] | first')
          NOTEBOOKS=$(python ./scripts/generate_matrix.py --haystack-version "$VERSION" --include-main)
          echo "matrix={\"include\":$NOTEBOOKS}" >> "$GITHUB_OUTPUT"

      - name: Get changed files
        if: github.event_name == 'pull_request'
        id: files
        uses: tj-actions/changed-files@24d32ffd492484c1d75e0c0b894501ddb9d30d62 # v47.0.0
        with:
          matrix: true
          files: tutorials/*.ipynb

      - name: Filter to changed notebooks (pull request only)
        id: matrix
        shell: python
        env:
          EVENT_NAME: ${{ github.event_name }}
          MATRIX: ${{ steps.generator.outputs.matrix }}
          CHANGED_FILES: ${{ steps.files.outputs.all_changed_files }}
        run: |
          import os
          import json

          matrix = json.loads(os.environ["MATRIX"])

          if os.environ["EVENT_NAME"] == "pull_request":
            changed_files = json.loads(os.environ["CHANGED_FILES"])
            new_matrix = {"include": []}
            for item in matrix["include"]:
              notebook = item["notebook"]
              if f"tutorials/{notebook}.ipynb" in changed_files:
                new_matrix["include"].append(item)
            matrix = new_matrix

          with open(os.environ["GITHUB_OUTPUT"], "a") as f:
            print(f"matrix={json.dumps(matrix)}", file=f)

  run-tutorials:
    needs: generate-matrix
    runs-on: ubuntu-latest

    strategy:
      fail-fast: false
      matrix: ${{ fromJSON(needs.generate-matrix.outputs.matrix) }}

    env:
      HAYSTACK_TELEMETRY_ENABLED: "False"
      HF_API_TOKEN: ${{ secrets.HF_API_KEY }}
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      SERPERDEV_API_KEY: ${{ secrets.SERPERDEV_API_KEY }}
      NOTION_API_KEY: ${{ secrets.NOTION_API_KEY }}
      MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}

    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

      - name: Setup Python and uv
        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
        with:
          python-version: "${{ matrix.python_version }}"

      - name: Install common dependencies
        run: |
          uv venv
          if [ "${{ matrix.haystack_version }}" = "main" ]; then
            uv pip install "haystack-ai @ git+https://github.com/deepset-ai/haystack.git@main"
          else
            VERSION="${{ matrix.haystack_version }}"
            uv pip install "haystack-ai==${VERSION#v}"
          fi
          uv pip install --exclude-newer P3D nbconvert ipython  # P3D = 3-day cutoff; haystack-ai above is exempt

      - name: Install tutorial dependencies
        if: toJSON(matrix.dependencies) != '[]'
        env:
          UV_EXCLUDE_NEWER: P3D  # reject packages uploaded within the last 3 days (supply chain protection)
        run: |
          uv pip install "${{ join(matrix.dependencies, '" "')}}"

      - name: Convert notebook to Python
        run: |
          . .venv/bin/activate
          jupyter nbconvert --to python --RegexRemovePreprocessor.patterns '%%bash' ./tutorials/${{ matrix.notebook }}.ipynb

      - name: Run the converted notebook
        run: |
          . .venv/bin/activate
          NOTEBOOK="./tutorials/${{ matrix.notebook }}.py"
          if [ "${{ matrix.notebook }}" = "47_Human_in_the_Loop_Agent" ]; then
            # We add a prompt to confirm any user inputs in the HiTL notebook
            yes y | python "$NOTEBOOK"
          elif [ "${{ matrix.notebook }}" = "48_Conversational_RAG" ]; then
            yes Q | python "$NOTEBOOK"
          else
            python "$NOTEBOOK"
          fi

      - name: Notify Slack on nightly failure
        if: failure() && github.event_name != 'pull_request'
        uses: deepset-ai/notify-slack-action@a65def0c8bf91d6520286ab34280151c76a5a008 # v1.1.0
        with:
          slack-webhook-url: ${{ secrets.SLACK_WEBHOOK_URL_NOTIFICATIONS }}