test-python-examples.yml

name: Test Python Examples

# The matrix runs when code changes: the same surface the upstream pull-request branch ships (src, tests, examples, scripts, pyproject.toml, setup.py).
# Documentation, READMEs and agent files do not start it; see "Documentation Development" for what to run by hand, and the release workflow runs everything.
on:
  # Run on push to bindings/python/ directory, on main only: the upstream-main
  # mirror branch that sync-upstream.sh pushes is upstream's tree without our
  # fixes, and running our checks on it only produces red runs nobody acts on.
  push:
    branches:
      - main
    paths:
      - 'bindings/python/src/**'
      - 'bindings/python/tests/**'
      - 'bindings/python/deprecation/**'
      - 'bindings/python/examples/**'
      - 'bindings/python/scripts/**'
      - 'bindings/python/pyproject.toml'
      - 'bindings/python/setup.py'
      - '.github/workflows/test-python-examples.yml'

  # Run on pull request affecting bindings/python/
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
    paths:
      - 'bindings/python/src/**'
      - 'bindings/python/tests/**'
      - 'bindings/python/deprecation/**'
      - 'bindings/python/examples/**'
      - 'bindings/python/scripts/**'
      - 'bindings/python/pyproject.toml'
      - 'bindings/python/setup.py'
      - '.github/workflows/test-python-examples.yml'

  # Allow being called by other workflows (e.g., release workflow)
  workflow_call:
    inputs:
      examples:
        description: "Glob pattern(s) for examples to run (space-separated, relative to bindings/python/examples)."
        required: false
        type: string
        default: "0[1-9]_*.py 1[0-9]_*.py 2[0-9]_*.py"
      build-version:
        description: "Override package version (PEP 440) for build.sh"
        required: false
        type: string
      engine-from-source:
        description: "Build the engine jars from this commit's source (the package module) instead of downloading the jars of the arcadedata/arcadedb image that pom.xml names. Off for a caller that does not set it, so the release workflow keeps its jars."
        required: false
        type: boolean
        default: false

  # Allow manual trigger
  workflow_dispatch:
    inputs:
      examples:
        description: "Glob pattern(s) for examples to run (space-separated, relative to bindings/python/examples)."
        required: false
        default: "0[1-9]_*.py 1[0-9]_*.py 2[0-9]_*.py"
      engine-from-source:
        description: "Build the engine jars from this commit's source (the package module). Turn off to download the jars of the arcadedata/arcadedb image that pom.xml names (upstream's moving snapshot between releases) instead."
        required: false
        type: boolean
        default: true

# SUPERSEDE, do not race.
#
# A force-push to a PR branch left the OLD run going alongside the new one: on
# #6889 both 118b347ce and 75293c7a2 ran at once, and the stale one reported a
# failure that the newer commit had already fixed. Anyone reading the PR sees a
# red check against work that is done.
#
# cancel-in-progress is scoped to pull_request ONLY. On a push to a long-lived
# branch a superseded run is often the one you still want -- it is the record
# for that commit -- so those are left to finish.
concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

# A draft pull request skips every job below; marking it ready for review starts the run
# (`ready_for_review` in the trigger types). Pushes to main, manual dispatch and the release workflow's
# call are never drafts, so they always run.
env:
  EXAMPLES: ${{ inputs.examples || '0[1-9]_*.py 1[0-9]_*.py 2[0-9]_*.py' }}

# Note: Example 21 runs in CI at reduced scale; its arguments and 15-minute
# limit are set in the per-example case in the "Run all examples" step below.

permissions:
  contents: read

jobs:
  # First job: Download ArcadeDB JARs (platform-agnostic)
  download-jars:
    name: Download ArcadeDB JARs
    runs-on: ubuntu-24.04
    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
    timeout-minutes: 90
    outputs:
      engine-from-source: ${{ steps.mode.outputs.engine-from-source }}
    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1

      # WHICH ENGINE THE TESTS RUN ON. A push, a pull request and a manual dispatch test the engine built from this
      # commit's source: the jars of upstream's moving snapshot image can carry fixes this repository's source does
      # not have yet (five strict-xfail tripwires fired on 2026-10-04 for that reason, #143), so a green run would say
      # nothing about the code in the checkout. A dispatch can turn it off (engine-from-source: false) to test the
      # snapshot image. A workflow_call that does not set the input (the release workflow) keeps the image's jars.
      # `inputs.*` is empty on push and pull_request, a boolean on the other two.
      - name: Choose where the engine jars come from
        id: mode
        shell: bash
        env:
          ENGINE_FROM_SOURCE_INPUT: ${{ inputs.engine-from-source }}
        run: |
          echo "engine-from-source=${ENGINE_FROM_SOURCE_INPUT:-true}" >> "$GITHUB_OUTPUT"

      # The jars depend only on the engine source tree, so they are cached under a hash of it: a bindings-only change
      # restores them in seconds, and the Maven build runs only when an engine module, a pom or the
      # Maven wrapper changes (an upstream sync, for example). Raise the `v1` to rebuild after a change to the build
      # steps below.
      - name: Restore the engine jars of this source tree
        id: engine-cache
        if: steps.mode.outputs.engine-from-source == 'true'
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: bindings/python/src/arcadedb_embedded/jars
          key: engine-jars-v1-${{ hashFiles('pom.xml', 'mvnw', '.mvn/**', '**/pom.xml', '**/src/main/**', '!bindings/**', '!benchmarks/**', '!e2e*/**', '!load-tests/**', '!docs/**') }}

      - name: Set up JDK 21 (engine from source)
        if: steps.mode.outputs.engine-from-source == 'true' && steps.engine-cache.outputs.cache-hit != 'true'
        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
        with:
          distribution: temurin
          java-version: "21"
          cache: maven

      - name: Build the engine jars from source
        if: steps.mode.outputs.engine-from-source == 'true' && steps.engine-cache.outputs.cache-hit != 'true'
        shell: bash
        run: |
          ./mvnw -B -q -DskipTests -pl package -am package
          # The FULL distribution. The base, headless, and minimal variants are
          # written beside it as arcadedb-<version>-<variant>.dir, and "-" sorts
          # before ".", so `ls | head -1` picked base, which has no plugins (no
          # Gremlin, Bolt, wire protocols, GraphQL, metrics, or tracing).
          LIB=$(ls -d package/target/arcadedb-*.dir/arcadedb-*/lib | grep -vE -- '-(base|headless|minimal)\.dir/' || true)
          if [ "$(printf '%s\n' "$LIB" | grep -c .)" != 1 ] || [ ! -d "$LIB" ]; then
            echo "::error::expected one full-distribution lib under package/target, got: $LIB"; exit 1
          fi
          if ! ls "$LIB"/arcadedb-gremlin-*.jar > /dev/null 2>&1; then
            echo "::error::$LIB has no Gremlin plugin jar, so it is not the full distribution"; exit 1
          fi
          mkdir -p bindings/python/src/arcadedb_embedded/jars
          cp "$LIB"/*.jar bindings/python/src/arcadedb_embedded/jars/
          ENGINE=$(ls bindings/python/src/arcadedb_embedded/jars/arcadedb-engine-*.jar | head -1)
          echo "Built from $(git rev-parse HEAD): $(ls -1 bindings/python/src/arcadedb_embedded/jars/*.jar | wc -l) JARs"
          unzip -p "$ENGINE" META-INF/MANIFEST.MF | tr -d '\r' | grep -i -E "build|version" || true

      - name: Download JARs from ArcadeDB Docker image
        if: steps.mode.outputs.engine-from-source != 'true'
        shell: bash
        run: |
          cd bindings/python

          # Detect ArcadeDB version from pom.xml (Docker format: X.Y.Z-SNAPSHOT)
          ARCADEDB_TAG=$(python3 scripts/extract_version.py --format=docker)
          echo "📌 ArcadeDB version: $ARCADEDB_TAG"

          # Download JARs from official Docker image
          echo "📦 Downloading JARs from arcadedata/arcadedb:$ARCADEDB_TAG..."

          # Create output directory
          mkdir -p src/arcadedb_embedded/jars

          # Create a temporary container and copy JARs from it
          CONTAINER_ID=$(docker create arcadedata/arcadedb:$ARCADEDB_TAG)
          docker cp $CONTAINER_ID:/home/arcadedb/lib/. src/arcadedb_embedded/jars/
          docker rm $CONTAINER_ID

          echo "✅ Downloaded $(ls -1 src/arcadedb_embedded/jars/*.jar | wc -l) JARs"

      # Unfiltered on purpose: build-native.sh applies scripts/jar_exclusions.txt
      # to whatever lands in the jars directory, so the list lives in one place.
      - name: Upload JARs as artifact
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: arcadedb-jars-examples
          path: bindings/python/src/arcadedb_embedded/jars/*.jar
          retention-days: 1

  # Second job: Test examples on each platform
  test-examples:
    name: Test Python Examples (${{ matrix.platform }}, Python ${{ matrix.python-version }})
    runs-on: ${{ matrix.runs-on }}
    timeout-minutes: 120
    needs: download-jars
    # An experimental leg (Python 3.15) is reported but never fails the job, so Examples Test Summary stays green.
    continue-on-error: ${{ matrix.experimental == true }}
    env:
      BUILD_VERSION: ${{ inputs.build-version }}
      # Pin the Hugging Face cache inside the workspace so it is cacheable with
      # one path on every platform (the default differs per OS). The examples
      # embed with sentence-transformers, and this matrix is 17 jobs, so
      # uncached that is 17 independent model downloads per release and 17
      # chances for a transient hub outage to fail a release. It has happened.
      HF_HOME: ${{ github.workspace }}/.hf-cache
      # The examples run in a throwaway uv project (EXAMPLE_PROJECT, written by "Install example
      # dependencies") that lists the example packages, plus the built wheel passed with `--with`.
      # Torch comes from the PyTorch CPU index, which avoids the CUDA build on Linux and Windows.
      # That index is declared `explicit = true` and only torch is pinned to it, so uv asks it
      # about torch alone and every other package comes from PyPI. Do not set UV_INDEX here: with
      # a global extra index uv needs `unsafe-best-match` and asks PyTorch about every package, so a
      # PyTorch outage (503 on /whl/cpu/rich/) fails jobs that do not need torch.
      # UV_PYTHON_DOWNLOADS=never keeps uv on the interpreter setup-python installed.
      # UV_HTTP_RETRIES is raised from its default of 3 to ride out a brief index or CDN outage.
      UV_HTTP_RETRIES: 6
      UV_PYTHON_DOWNLOADS: never
    strategy:
      fail-fast: false
      matrix:
        python-version:
          - '3.11'
          - '3.12'
          - '3.13'
          - '3.14'
        # Temporarily limit to four platforms (skip macOS x86_64, Windows ARM64)
        # platform: ['linux/amd64', 'linux/arm64', 'darwin/amd64', 'darwin/arm64', 'windows/amd64', 'windows/arm64']
        platform: ['linux/amd64', 'linux/arm64', 'darwin/arm64', 'windows/amd64']
        include:
          - platform: linux/amd64
            runs-on: ubuntu-24.04
          - platform: linux/arm64
            runs-on: ubuntu-24.04-arm
          - platform: darwin/arm64
            runs-on: macos-15
          - platform: windows/amd64
            runs-on: windows-2025
          # - platform: darwin/amd64
          #   runs-on: macos-15-intel
          # - platform: windows/arm64
          #   runs-on: windows-11-arm
          # macOS x86_64 and Windows ARM64 temporarily disabled
          # Python 3.15 is informational: one linux/amd64 leg that may fail without failing the
          # job or the summary (continue-on-error below). It uploads no wheel, so the release
          # workflow never collects or publishes a 3.15 wheel. Drop `experimental` when 3.15 is supported.
          - python-version: '3.15'
            platform: linux/amd64
            runs-on: ubuntu-24.04
            experimental: true

    steps:
      - name: Checkout code
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

      - name: Download JARs artifact
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: arcadedb-jars-examples
          path: bindings/python/src/arcadedb_embedded/jars

      - name: Set up Java (for native builds on macOS/Windows)
        if: matrix.platform != 'linux/amd64' && matrix.platform != 'linux/arm64'
        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
        with:
          distribution: 'corretto'
          java-version: '25'

      - name: Set up Docker Buildx (Linux only)
        if: matrix.platform == 'linux/amd64' || matrix.platform == 'linux/arm64'
        uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: ${{ matrix.python-version }}

      - name: Setup UV package manager
        shell: bash
        run: |
          # Retry transient network failures (a connection reset failed a whole examples job on #8897); the
          # script is downloaded first so a retried transfer is never piped half-written into sh.
          installer="$(mktemp)"
          curl -LsSf --retry 5 --retry-all-errors --retry-delay 5 -o "$installer" https://astral.sh/uv/0.12.0/install.sh
          sh "$installer"
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          export PATH="$HOME/.local/bin:$PATH"
          uv --version

      # Windows currently enabled, no symlink needed
      # - name: Create python3 symlink (Windows only)
      #   if: matrix.platform == 'windows/amd64' || matrix.platform == 'windows/arm64'
      #   shell: bash
      #   run: |
      #     PYTHON_DIR=$(dirname "$(which python)")
      #     ln -s "$PYTHON_DIR/python.exe" "$PYTHON_DIR/python3.exe" || true
      #     python3 --version

      - name: Build arcadedb-embedded (${{ matrix.platform }})
        shell: bash
        env:
          ENGINE_FROM_SOURCE: ${{ needs.download-jars.outputs.engine-from-source }}
        run: |
          cd bindings/python
          echo "🔨 Building arcadedb-embedded for ${{ matrix.platform }} with Python ${{ matrix.python-version }}..."
          # scripts/build-native.sh (macOS and Windows) runs `python -m build` with the first python on PATH that
          # has the build module. `uv run --with` puts a throwaway environment holding the build tools first on
          # PATH for this one command, so nothing is installed into the runner's interpreter. Linux builds in Docker.
          BUILD_RUN=(uv run --no-project --python "${{ matrix.python-version }}" --with build --with wheel --with setuptools bash)
          # ENGINE FROM SOURCE: hand the jars built from this commit to build.sh on
          # every platform. Without JAR_LIB_DIR the Linux (Docker) build pulls the
          # snapshot image's jars itself, so the option silently did nothing there
          # while the native builds used the artifact (2026-10-04, run 37193748490).
          if [ "${ENGINE_FROM_SOURCE}" = "true" ]; then
            "${BUILD_RUN[@]}" ./scripts/build.sh ${{ matrix.platform }} ${{ matrix.python-version }} src/arcadedb_embedded/jars
          else
            "${BUILD_RUN[@]}" ./scripts/build.sh ${{ matrix.platform }} ${{ matrix.python-version }}
          fi

      # Note: Java is NOT required - arcadedb-embedded has bundled JRE!

      - name: Install ArcadeDB Python bindings
        shell: bash
        run: |
          # Not installed into the runner's interpreter: the later steps pass this wheel to `uv run --with`.
          wheels=("$GITHUB_WORKSPACE"/bindings/python/dist/*embed*.whl)
          if [ "${#wheels[@]}" -ne 1 ] || [ ! -f "${wheels[0]}" ]; then
            echo "expected exactly one wheel in bindings/python/dist, found: ${wheels[*]}"
            exit 1
          fi
          {
            echo "ARCADEDB_WHEEL=${wheels[0]}"
            echo "EXAMPLE_PROJECT=$RUNNER_TEMP/example-project"
          } >> "$GITHUB_ENV"

      # REMOVE WHEN: jpype1 publishes cp315 wheels (JPype > 1.7.1)
      # JPype has no cp315 wheel yet, so the Python 3.15 leg compiles it from a pinned commit of JPype master
      # (it supports 3.15: jpype-project/jpype#1493, #1498, #1501). That build needs a JDK (jni.h, javac) and
      # Apache Ant, only to build JPype itself. The tests still run on the wheel's bundled JRE.
      - name: Set up JDK and Ant to build JPype (Python 3.15)
        if: matrix.python-version == '3.15'
        uses: actions/setup-java@b843ebf9b913146b38da2eaa7aeddf76074ae1ad # v6.1.0
        with:
          distribution: temurin
          java-version: '17'

      - name: Check Ant for the JPype build (Python 3.15)
        if: matrix.python-version == '3.15'
        shell: bash
        run: |
          command -v ant > /dev/null || { sudo apt-get update -qq && sudo apt-get install -y --no-install-recommends ant; }
          ant -version
          test -f "$JAVA_HOME/include/jni.h"

      - name: Install example dependencies
        shell: bash
        run: |
          # Packages needed by the examples, listed once here for every later step.
          # PyTorch is required by sentence-transformers, even on macOS (its CPU build supports MPS acceleration).
          # tqdm, py7zr and lxml are for the dataset downloads; pandas, polars and pyarrow for
          # 27_dataframe_arrow_ingest.py.
          # numpy is not capped: the old macOS `numpy<2.0` was for Intel Macs, where PyTorch stops at 2.2
          # (built against NumPy 1.x). That leg (darwin/amd64) is disabled; re-enabling it needs the cap
          # back for that platform only. On Apple Silicon a cap breaks pyarrow (it needs NumPy 2 on 3.14).
          # They go into a minimal uv project so that `[tool.uv.sources]` can pin torch alone to the
          # PyTorch CPU index (`explicit = true`); `uv run --no-project` reads no sources, and a
          # requirements file cannot mark an index explicit. The project has no build system, so
          # nothing of it is installed except its dependencies.
          mkdir -p "$EXAMPLE_PROJECT"
          cat > "$EXAMPLE_PROJECT/pyproject.toml" <<'TOML'
          [project]
          name = "arcadedb-examples-env"
          version = "0"
          requires-python = ">=3.11"
          dependencies = [
            "torch", "numpy", "requests", "sentence-transformers", "tqdm", "py7zr", "lxml",
            "pandas", "polars", "pyarrow",
            # REMOVE WHEN: jpype1 publishes cp315 wheels (JPype > 1.7.1)
            "jpype1 @ git+https://github.com/jpype-project/jpype@ed2cc2095c4b45dd3bfcb4fe1af28369c131e166 ; python_version >= '3.15'",
          ]

          [tool.uv.sources]
          torch = { index = "pytorch-cpu" }

          [[tool.uv.index]]
          name = "pytorch-cpu"
          url = "https://download.pytorch.org/whl/cpu"
          explicit = true
          TOML
          # Build the environment now, so a dependency that cannot be resolved or installed fails here.
          EXAMPLES_PYTHON=(uv run --project "$EXAMPLE_PROJECT" --python "${{ matrix.python-version }}" --with "$ARCADEDB_WHEEL" python)
          "${EXAMPLES_PYTHON[@]}" -c "import sys; print(sys.version)"

      # Restored before the dataset step, which is what triggers the model
      # download. Keyed on the model name so bumping the model invalidates it.
      - name: Cache Hugging Face model
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: ${{ github.workspace }}/.hf-cache
          key: hf-all-MiniLM-L6-v2-${{ runner.os }}-${{ runner.arch }}
          restore-keys: |
            hf-all-MiniLM-L6-v2-${{ runner.os }}-

      # Pre-warm with bounded retries, separately from the dataset step, so a
      # transient hub failure is retried here rather than surfacing mid-example
      # as an OSError that reads like a bindings bug. Retrying is appropriate
      # for this step specifically: it exercises third-party I/O, not our code.
      # Deliberately NOT fail-fast: if the hub is truly down the dataset step
      # below still runs and fails with its own message, so this cannot turn a
      # real breakage into a silent skip.
      - name: Pre-warm embedding model
        shell: bash
        continue-on-error: true
        run: |
          EXAMPLES_PYTHON=(uv run --project "$EXAMPLE_PROJECT" --python "${{ matrix.python-version }}" --with "$ARCADEDB_WHEEL" python)
          for attempt in 1 2 3; do
            if "${EXAMPLES_PYTHON[@]}" -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('all-MiniLM-L6-v2'); print('model ready')"; then
              echo "✅ model cached on attempt $attempt"
              exit 0
            fi
            echo "⚠️  model fetch failed (attempt $attempt/3)"
            [ "$attempt" -lt 3 ] && sleep $((attempt * 20))
          done
          echo "::warning::could not pre-warm the embedding model after 3 attempts; the dataset step will retry"

      - name: Download datasets
        shell: bash
        run: |
          EXAMPLES_PYTHON=(uv run --project "$EXAMPLE_PROJECT" --python "${{ matrix.python-version }}" --with "$ARCADEDB_WHEEL" python)
          cd bindings/python/examples

          # Determine which examples are selected
          examples=$(ls $EXAMPLES 2>/dev/null || true)

          # EXIT 75 MEANS "THE DATASET HOST IS DOWN", NOT "THE BINDINGS BROKE".
          #
          # On 2026-08-29 the TLS certificate for files.grouplens.org expired and
          # every job here went red on BOTH this fork and upstream's main -- 11
          # and 12 jobs, every OS, Python 3.10 through 3.14 -- at this step,
          # before a single example ran. Re-running does not help: a re-run
          # happens now, and the certificate is still expired.
          #
          # The cost is not the lost coverage, it is that upstream's main showed
          # a failing run titled with a Python bindings PR. A third party letting
          # a certificate lapse must not be indistinguishable from a regression
          # we introduced.
          #
          # So: skip the examples that need the dataset, keep running the rest,
          # and say plainly why. Any other non-zero exit is still a hard failure.
          SKIPPED_DATASETS=""
          fetch() {  # fetch <label> <download_data.py args...>
            local label="$1"; shift
            # rc MUST be captured in the else branch. After `if cmd; then ...; fi`
            # with no else, the IF STATEMENT returns 0, so a `$?` read after `fi`
            # is the if's status and not the command's -- which silently turned
            # every failure into "exited 0" and would have made this skip
            # everything, including real ones.
            local rc=0
            if "${EXAMPLES_PYTHON[@]}" download_data.py "$@"; then
              return 0
            else
              rc=$?
            fi
            if [ "$rc" -eq 75 ]; then
              echo "::warning title=Dataset unavailable::$label host unreachable; skipping examples that need it"
              SKIPPED_DATASETS="$SKIPPED_DATASETS $label"
              return 0
            fi
            echo "::error title=Dataset download failed::$label exited $rc"
            return "$rc"
          }

          if echo "$examples" | grep -qE '(^|[[:space:]])(04_csv_import_documents|05_csv_import_graph|06_vector_search_recommendations)\.py([[:space:]]|$)'; then
            echo "📥 Downloading MovieLens Small dataset..."
            fetch movielens-small movielens-small
          fi

          if echo "$examples" | grep -qE '(^|[[:space:]])(07_stackoverflow_tables_oltp|08_stackoverflow_tables_olap|09_stackoverflow_graph_oltp|10_stackoverflow_graph_olap|13_stackoverflow_hybrid_queries)\.py([[:space:]]|$)'; then
            echo "📥 Downloading Stack Overflow Tiny dataset (no vectors)..."
            fetch stackoverflow-tiny-novec stackoverflow-tiny --no-vectors
          fi

          if echo "$examples" | grep -qE '(^|[[:space:]])(11_vector_index_build|12_vector_search)\.py([[:space:]]|$)'; then
            echo "📥 Downloading Stack Overflow Tiny dataset (with vectors)..."
            fetch stackoverflow-tiny stackoverflow-tiny
          fi

          # HAND THE SKIP LIST TO THE NEXT STEP.
          #
          # Each step is its own shell, so SKIPPED_DATASETS dies here. Without
          # this the download skips politely and the example loop then runs
          # 04_csv_import_documents.py --dataset movielens-small against data
          # that was never fetched -- the job still fails, just later and with a
          # worse error. Caught in review on #6889.
          echo "SKIPPED_DATASETS=$(echo $SKIPPED_DATASETS | xargs)" >> "$GITHUB_ENV"
          if [ -n "$(echo $SKIPPED_DATASETS | xargs)" ]; then
            echo "::notice title=Datasets unavailable::skipping examples that need:$SKIPPED_DATASETS"
          fi

      - name: Install timeout command (macOS only)
        if: matrix.platform == 'darwin/amd64' || matrix.platform == 'darwin/arm64'
        shell: bash
        run: |
          # macOS doesn't have timeout command by default, use coreutils
          brew install coreutils

      - name: Set UTF-8 encoding (Windows only)
        if: matrix.platform == 'windows/amd64' || matrix.platform == 'windows/arm64'
        shell: bash
        run: |
          echo "PYTHONIOENCODING=utf-8" >> $GITHUB_ENV
          echo "PYTHONUTF8=1" >> $GITHUB_ENV

      - name: Run all examples
        id: run_examples
        shell: bash
        run: |
          cd bindings/python/examples

          # Same environment as the steps above; uv builds it once and reuses it for every example.
          EXAMPLES_PYTHON=(uv run --project "$EXAMPLE_PROJECT" --python "${{ matrix.python-version }}" --with "$ARCADEDB_WHEEL" python)

          echo "🚀 Running Python Examples..."
          echo ""

          # Initialize counters
          total=0
          passed=0
          failed=0
          skipped=0

          # Create results file
          results_file="example-results.txt"
          > $results_file

          # Select example files by pattern(s) in EXAMPLES (space-separated globs)
          examples=$(ls $EXAMPLES 2>/dev/null | sort)

          if [ -z "$examples" ]; then
            echo "❌ No example files found!"
            exit 1
          fi

          # Detect timeout command (macOS uses gtimeout, Linux uses timeout)
          if command -v gtimeout &> /dev/null; then
            TIMEOUT_CMD="gtimeout"
          else
            TIMEOUT_CMD="timeout"
          fi

          # WHICH EXAMPLES NEED WHICH DATASET. Same grouping the download step
          # uses to decide what to fetch, kept in the same file so the two
          # cannot drift into disagreeing about what a dataset is for.
          needs_dataset() {  # <example.py> -> prints the label, or nothing
            case "$1" in
              04_csv_import_documents.py|05_csv_import_graph.py|06_vector_search_recommendations.py)
                echo "movielens-small" ;;
              07_stackoverflow_tables_oltp.py|08_stackoverflow_tables_olap.py|09_stackoverflow_graph_oltp.py|10_stackoverflow_graph_olap.py|13_stackoverflow_hybrid_queries.py)
                echo "stackoverflow-tiny-novec" ;;
              11_vector_index_build.py|12_vector_search.py)
                echo "stackoverflow-tiny" ;;
            esac
          }

          # Run each example
          for example in $examples; do
            total=$((total + 1))

            # Skip, do not fail, when the dataset host was unreachable. Counted
            # as skipped and named, so a reader can tell "not run" from "passed".
            need=$(needs_dataset "$(basename "$example")")
            if [ -n "$need" ] && echo " ${SKIPPED_DATASETS:-} " | grep -q " $need "; then
              echo "SKIP $example - dataset '$need' unavailable (third-party host)"
              skipped=$((skipped + 1))
              continue
            fi

            # Set example-specific parameters and timeout
            case "$example" in
              "21_graph_analytical_view_sql.py")
                example_args="--base-cities 1200 --stale-growth-cities 300 --sync-growth-cities 200 --regions 12 --batch-size 300 --sample-limit 5"
                example_name="$example (reduced scale for CI)"
                timeout_duration=900  # 15 minutes
                example_jvm_args=""
                ;;
              "22_numpy_bulk_io.py")
                example_args="--rows 50000 --points 100000 --vectors 5000"
                example_name="$example (reduced scale for CI)"
                timeout_duration=600  # 10 minutes
                example_jvm_args=""
                ;;
              "04_csv_import_documents.py")
                example_args="--dataset movielens-small --export"
                example_name="$example (movielens-small dataset with export)"
                timeout_duration=900  # 15 minutes
                example_jvm_args="-Xmx8g -Xms8g"
                ;;
              "05_csv_import_graph.py")
                example_args="--dataset movielens-small --method sql --import-jsonl ./exports/movielens_small_db.jsonl.tgz --export"
                example_name="$example (movielens-small dataset, embedded sql method, import/export)"
                timeout_duration=900  # 15 minutes
                example_jvm_args=""
                ;;
              "06_vector_search_recommendations.py")
                example_args="--import-jsonl ./exports/movielens_graph_small_db.jsonl.tgz"
                example_name="$example (vector search, import from JSONL)"
                timeout_duration=900  # 15 minutes
                example_jvm_args=""
                ;;
              "07_stackoverflow_tables_oltp.py")
                example_args="--dataset stackoverflow-tiny --db arcadedb_sql --threads 1 --transactions 1000 --batch-size 500 --mem-limit 2g --run-label ci07"
                example_name="$example (stackoverflow-tiny, arcadedb_sql, minimal oltp)"
                timeout_duration=900
                example_jvm_args=""
                ;;
              "08_stackoverflow_tables_olap.py")
                example_args="--dataset stackoverflow-tiny --db arcadedb_sql --threads 1 --batch-size 500 --query-runs 1 --query-order fixed --mem-limit 2g --run-label ci08"
                example_name="$example (stackoverflow-tiny, arcadedb_sql, minimal olap)"
                timeout_duration=900
                example_jvm_args=""
                ;;
              "09_stackoverflow_graph_oltp.py")
                example_args="--dataset stackoverflow-tiny --db arcadedb_cypher --threads 1 --transactions 1000 --batch-size 500 --mem-limit 2g --run-label ci09"
                example_name="$example (stackoverflow-tiny graph oltp, arcadedb cypher, minimal)"
                timeout_duration=900
                example_jvm_args=""
                ;;
              "10_stackoverflow_graph_olap.py")
                example_args="--dataset stackoverflow-tiny --db arcadedb_cypher --threads 1 --batch-size 500 --query-runs 1 --query-order fixed --mem-limit 2g --run-label ci10"
                example_name="$example (stackoverflow-tiny graph olap, arcadedb cypher, minimal)"
                timeout_duration=900
                example_jvm_args=""
                ;;
              "11_vector_index_build.py")
                example_args="--backend arcadedb_sql --dataset stackoverflow-tiny --threads 1 --mem-limit 2g --batch-size 500 --beam-width 100 --quantization NONE --run-label ci11_arcadedb_sql"
                example_name="$example (vector build, arcadedb_sql backend, minimal)"
                timeout_duration=1200
                example_jvm_args=""
                ;;
              "12_vector_search.py")
                db_path=$(find ./my_test_databases -maxdepth 1 -type d -name 'backend=arcadedb_sql_dataset=stackoverflow-tiny_*run=ci11_arcadedb_sql' | head -n 1)
                if [ -z "$db_path" ]; then
                  echo "❌ Missing build output for 12_vector_search.py. Ensure 11_vector_index_build.py ran first." | tee -a $results_file
                  failed=$((failed + 1))
                  echo ""
                  continue
                fi
                example_args="--backend arcadedb_sql --dataset stackoverflow-tiny --db-path $db_path --ef-search-values 100 --k 10 --query-limit 100 --query-runs 1 --query-order fixed --threads 1 --mem-limit 2g --run-label ci12_arcadedb_sql"
                example_name="$example (vector search, arcadedb_sql backend, minimal)"
                timeout_duration=1200
                example_jvm_args=""
                ;;
              "13_stackoverflow_hybrid_queries.py")
                example_args="--dataset stackoverflow-tiny --batch-size 500 --encode-batch-size 64 --top-k 5 --candidate-limit 100 --min-reputation 100 --infer-sample-limit 5000 --run-label ci13"
                example_name="$example (hybrid pipeline, tiny + minimal limits)"
                timeout_duration=1800
                example_jvm_args=""
                ;;
              "14_lifecycle_timing.py")
                example_args="--runs 1 --table-records 2000 --graph-vertices 500 --vector-records 500 --vector-dimensions 32 --query-runs 10 --jvm-heap 4g"
                example_name="$example (lifecycle benchmark, minimal)"
                timeout_duration=900
                example_jvm_args=""
                ;;
              "15_import_database_vs_transactional_table_ingest.py")
                example_args="--rows-per-table 2000 --tables 2 --columns 6 --string-size 32 --batch-size 500 --async-parallel 1 --parallel 1 --heap-size 4g --work-dir ./my_test_databases/import_vs_txn_dummy_ci"
                example_name="$example (table ingest benchmark, minimal)"
                timeout_duration=1200
                example_jvm_args=""
                ;;
              "16_import_database_vs_transactional_graph_ingest.py")
                example_args="--vertices 2000 --edges 4000 --vertex-int-props 3 --vertex-str-props 2 --edge-int-props 1 --edge-str-props 1 --string-size 32 --batch-size 500 --async-parallel 1 --parallel 1 --heap-size 4g --work-dir ./my_test_databases/import_vs_txn_graph_ci"
                example_name="$example (graph ingest benchmark, minimal)"
                timeout_duration=1200
                example_jvm_args=""
                ;;
              "17_timeseries_end_to_end.py")
                example_args="--hours 2 --interval-minutes 10"
                example_name="$example (time-series end-to-end, minimal)"
                timeout_duration=900
                example_jvm_args=""
                ;;
              "18_geo_predicates_wkt.py")
                example_args=""
                example_name="$example (geo predicates with WKT points and polygons)"
                timeout_duration=900
                example_jvm_args=""
                ;;
              "19_hash_index_exact_match.py")
                example_args=""
                example_name="$example (hash index exact-match workflow)"
                timeout_duration=900
                example_jvm_args=""
                ;;
              "20_graph_algorithms_route_planning.py")
                example_args=""
                example_name="$example (graph algorithms route planning workflow)"
                timeout_duration=900
                example_jvm_args=""
                ;;
              *)
                example_args=""
                example_name="$example"
                timeout_duration=900  # 15 minutes default
                example_jvm_args=""
                ;;
            esac

            log_file="${example%.py}.log"

            echo "----------------------------------------"
            echo "📝 Running: $example_name"
            echo "----------------------------------------"

            # Run the example with appropriate parameters
            if [ -n "$example_jvm_args" ]; then
              if ARCADEDB_JVM_ARGS="$example_jvm_args" JAVA_TOOL_OPTIONS="" _JAVA_OPTIONS="" $TIMEOUT_CMD $timeout_duration "${EXAMPLES_PYTHON[@]}" "$example" $example_args > "$log_file" 2>&1; then
                exit_code=0
              else
                exit_code=$?
              fi
            else
              if ARCADEDB_JVM_ARGS="" JAVA_TOOL_OPTIONS="" _JAVA_OPTIONS="" $TIMEOUT_CMD $timeout_duration "${EXAMPLES_PYTHON[@]}" "$example" $example_args > "$log_file" 2>&1; then
                exit_code=0
              else
                exit_code=$?
              fi
            fi
            # ANSWERS, NOT ONLY A CLEAN EXIT (humemai/arcadedb-embedded-python#12). Example 10 once returned 0 rows for
            # 5 of its 10 queries on every platform and passed. After a clean run, the
            # same arguments on the pure-Python reference backend must give the same
            # row count and hash for every query.
            if [ $exit_code -eq 0 ] && [ "$example" = "10_stackoverflow_graph_olap.py" ]; then
              ref_args="${example_args/--db arcadedb_cypher/--db python_memory}"
              ref_args="${ref_args/--run-label ci10/--run-label ci10ref}"
              ref_log="${example%.py}-reference.log"
              if ! $TIMEOUT_CMD $timeout_duration "${EXAMPLES_PYTHON[@]}" "$example" $ref_args > "$ref_log" 2>&1; then
                echo "❌ reference run (python_memory) of $example failed; last 20 lines:"
                tail -n 20 "$ref_log"
                exit_code=1
              elif ! "${EXAMPLES_PYTHON[@]}" scripts/compare_query_hashes.py "$log_file" "$ref_log"; then
                echo "❌ $example: answers differ from the python_memory reference (above)"
                exit_code=1
              fi
            fi
            if [ $exit_code -eq 0 ]; then
              echo "✅ PASSED: $example_name" | tee -a $results_file
              passed=$((passed + 1))
            else
              if [ $exit_code -eq 124 ]; then
                echo "⏱️  TIMEOUT: $example_name (exceeded $((timeout_duration/60)) minutes)" | tee -a $results_file
                failed=$((failed + 1))
              else
                echo "❌ FAILED: $example_name (exit code: $exit_code)" | tee -a $results_file
                failed=$((failed + 1))
              fi
              # Show last 20 lines of error log
              echo "Last 20 lines of output:"
              tail -n 20 "$log_file"
            fi
            echo ""
          done

          # Print summary
          echo "========================================"
          echo "📊 EXAMPLE TEST SUMMARY"
          echo "========================================"
          echo "Total:   $total"
          echo "Passed:  $passed ✅"
          echo "Failed:  $failed ❌"
          echo "Skipped: $skipped ⏭️"
          echo "========================================"
          echo ""

          echo "Examples pattern(s): $EXAMPLES"

          # Output to GitHub Actions
          echo "total=$total" >> $GITHUB_OUTPUT
          echo "passed=$passed" >> $GITHUB_OUTPUT
          echo "failed=$failed" >> $GITHUB_OUTPUT
          echo "skipped=$skipped" >> $GITHUB_OUTPUT

          # Show detailed results
          echo "Detailed Results:"
          cat $results_file

          # Save list of examples for summary (before the failure exit, so
          # the summary is populated even when some examples fail)
          echo "$examples" > examples-ran.txt

          # Exit with error if any failed
          if [ $failed -gt 0 ]; then
            echo "❌ Some examples failed!"
            exit 1
          else
            echo "✅ All examples passed!"
          fi

      - name: Generate test summary
        if: always()
        shell: bash
        run: |
          cd bindings/python/examples

          echo "## 🎮 Python Examples Test Results (${{ matrix.platform }})" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          total="${{ steps.run_examples.outputs.total || '0' }}"
          passed="${{ steps.run_examples.outputs.passed || '0' }}"
          failed="${{ steps.run_examples.outputs.failed || '0' }}"

          if [ "${{ steps.run_examples.outcome }}" = "success" ]; then
            echo "✅ **Status**: ALL EXAMPLES PASSED ($passed/$total)" >> $GITHUB_STEP_SUMMARY
          else
            echo "❌ **Status**: SOME EXAMPLES FAILED ($passed/$total passed)" >> $GITHUB_STEP_SUMMARY
          fi

          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "| Metric | Count |" >> $GITHUB_STEP_SUMMARY
          echo "|--------|------:|" >> $GITHUB_STEP_SUMMARY
          echo "| 📝 Total | $total |" >> $GITHUB_STEP_SUMMARY
          echo "| ✅ Passed | $passed |" >> $GITHUB_STEP_SUMMARY
          echo "| ❌ Failed | $failed |" >> $GITHUB_STEP_SUMMARY
          echo "| ⏭️ Skipped | ${{ steps.run_examples.outputs.skipped || '0' }} |" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          # Add detailed results if available
          if [ -f example-results.txt ]; then
            echo "### Detailed Results" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
            cat example-results.txt >> $GITHUB_STEP_SUMMARY
            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
          fi

          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### Examples Tested" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "**Pattern(s)**: $EXAMPLES" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          if [ -f examples-ran.txt ]; then
            while IFS= read -r example; do
              [ -n "$example" ] && echo "- **$example**" >> $GITHUB_STEP_SUMMARY
            done < examples-ran.txt
          fi
          echo "" >> $GITHUB_STEP_SUMMARY

      - name: Upload example logs
        if: always()
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: example-logs-${{ matrix.platform == 'linux/amd64' && 'linux-amd64' || matrix.platform == 'linux/arm64' && 'linux-arm64' || matrix.platform == 'darwin/amd64' && 'darwin-amd64' || matrix.platform == 'darwin/arm64' && 'darwin-arm64' || matrix.platform == 'windows/amd64' && 'windows-amd64' || 'windows-arm64' }}-py${{ matrix.python-version }}
          path: |
            bindings/python/examples/*.log
            bindings/python/examples/example-results.txt
          retention-days: 7

      - name: Upload example databases
        if: failure()
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: example-databases-${{ matrix.platform == 'linux/amd64' && 'linux-amd64' || matrix.platform == 'linux/arm64' && 'linux-arm64' || matrix.platform == 'darwin/amd64' && 'darwin-amd64' || matrix.platform == 'darwin/arm64' && 'darwin-arm64' || matrix.platform == 'windows/amd64' && 'windows-amd64' || 'windows-arm64' }}-py${{ matrix.python-version }}
          path: bindings/python/examples/my_test_databases/
          retention-days: 3

  # Summary job that checks all platforms
  test-examples-summary:
    name: Examples Test Summary
    needs: test-examples
    runs-on: ubuntu-24.04
    timeout-minutes: 5
    # Skipped with the matrix on a draft pull request; a skipped check is not a failed one.
    if: always() && (github.event_name != 'pull_request' || github.event.pull_request.draft == false)
    steps:
      - name: Check test results
        shell: bash
        run: |
          echo "## 🎯 Overall Examples Test Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY

          if [ "${{ needs.test-examples.result }}" = "success" ]; then
            echo "✅ **All platforms passed example testing!**" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "All examples ran successfully across all enabled platforms." >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "**Platforms tested**: linux/amd64, linux/arm64, darwin/arm64, windows/amd64" >> $GITHUB_STEP_SUMMARY
            echo "" >> "$GITHUB_STEP_SUMMARY"
            echo "Python 3.15 runs as an informational linux/amd64 leg: its result is shown on the run but does not decide this summary." >> "$GITHUB_STEP_SUMMARY"
          else
            echo "❌ **Some platforms failed example testing**" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "Please check the individual platform jobs for details." >> $GITHUB_STEP_SUMMARY
            exit 1
          fi