test.yml

name: Test Suite

on:
  pull_request:

  push:
    branches:
      - main

  schedule:
    - cron: "0 2 * * *" # 2 AM UTC nightly

  workflow_dispatch:

env:
  PYTHON_VERSION: "3.11"
  UV_VERSION: "0.12.3"

jobs:
  service-tests:
    name: Service Tests
    runs-on: ubuntu-latest
    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Run service tests
        uses: ./.github/actions/run-service-tests
        with:
          python-version: ${{ env.PYTHON_VERSION }}
          uv-version: ${{ env.UV_VERSION }}
        env:
          HF_HOME: ${{ github.workspace }}/hf_cache
          HF_TOKEN: ${{ secrets.HF_TOKEN }}
          GOOGLE_CREDENTIALS: ${{ secrets.GOOGLE_CREDENTIALS }}
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          GCP_LOCATION: ${{ secrets.GCP_LOCATION }}
          GCP_PROJECT_ID: ${{ secrets.GCP_PROJECT_ID }}
          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
          COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}
          MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
          VOYAGE_API_KEY: ${{ secrets.VOYAGE_API_KEY }}
          # The live Azure OpenAI tests gate themselves on AZURE_OPENAI_ENDPOINT,
          # AZURE_OPENAI_API_KEY and OPENAI_API_VERSION: if any of the three is empty
          # or unset they skip, so an absent secret disables them and re-adding it
          # re-enables them with no code change. These lines stay wired up for that
          # reason. (test_non_supported_dtypes is deliberately left ungated -- it
          # validates dtype before any client is built and needs no network.)
          AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
          AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
          AZURE_OPENAI_DEPLOYMENT_NAME: ${{ secrets.AZURE_OPENAI_DEPLOYMENT_NAME }}
          OPENAI_API_VERSION: ${{ secrets.OPENAI_API_VERSION }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          LANGCACHE_WITH_ATTRIBUTES_API_KEY: ${{ secrets.LANGCACHE_WITH_ATTRIBUTES_API_KEY }}
          LANGCACHE_WITH_ATTRIBUTES_CACHE_ID: ${{ secrets.LANGCACHE_WITH_ATTRIBUTES_CACHE_ID }}
          LANGCACHE_WITH_ATTRIBUTES_URL: ${{ secrets.LANGCACHE_WITH_ATTRIBUTES_URL }}
          LANGCACHE_NO_ATTRIBUTES_API_KEY: ${{ secrets.LANGCACHE_NO_ATTRIBUTES_API_KEY }}
          LANGCACHE_NO_ATTRIBUTES_CACHE_ID: ${{ secrets.LANGCACHE_NO_ATTRIBUTES_CACHE_ID }}
          LANGCACHE_NO_ATTRIBUTES_URL: ${{ secrets.LANGCACHE_NO_ATTRIBUTES_URL }}

  test:
    name: Python ${{ matrix.python-version }} - redis-py ${{ matrix.redis-py-version }} [${{ matrix.redis-image }}]
    runs-on: ubuntu-latest
    needs: service-tests
    env:
      HF_HOME: ${{ github.workspace }}/hf_cache
      REDIS_IMAGE: ${{ matrix.redis-image }}
      REDIS_PY_VERSION: ${{ matrix.redis-py-version }}
      # Required: without it `uv run` re-syncs the venv to uv.lock and reverts
      # the redis-py pin set below.
      UV_NO_SYNC: "1"
    strategy:
      fail-fast: false
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
        redis-py-version: ["6.x", "7.x"]
        redis-image: ["redis:8.2", "redis:8.4", "redis:latest"]
    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Cache HuggingFace Models
        uses: actions/cache@v4
        with:
          path: hf_cache
          key: ${{ runner.os }}-hf-cache

      - name: Install Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: Install uv
        uses: astral-sh/setup-uv@v10.0.0
        with:
          version: ${{ env.UV_VERSION }}
          enable-cache: true
          python-version: ${{ matrix.python-version }}   # sets UV_PYTHON
          cache-dependency-glob: |
            pyproject.toml
            uv.lock

      - name: Install dependencies
        run: |
          set -euo pipefail

          uv sync --all-extras --frozen

          # Must cover every redis-py-version matrix value; unhandled values fail.
          case "$REDIS_PY_VERSION" in
            "6.x") spec="redis>=6,<7" ;;
            "7.x") spec="redis>=7,<8" ;;
            *)
              echo "::error title=Unhandled redis-py-version::Matrix value '${REDIS_PY_VERSION}' has no install rule -- add a case branch in .github/workflows/test.yml."
              exit 1
              ;;
          esac

          uv pip install "$spec"
          uv run python -c 'import redis; print("redis-py:", redis.__version__)'

      - name: Run tests
        run: |
          make test

  notebooks:
    name: Notebook Validation
    runs-on: ubuntu-latest
    needs: service-tests
    # Needs API-key secrets, unavailable to fork PRs. Keep in sync with
    # service-tests.
    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
    env:
      HF_HOME: ${{ github.workspace }}/hf_cache
    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Cache HuggingFace Models
        uses: actions/cache@v4
        with:
          path: hf_cache
          key: ${{ runner.os }}-hf-cache

      - name: Install Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Install uv
        uses: astral-sh/setup-uv@v10.0.0
        with:
          version: ${{ env.UV_VERSION }}
          enable-cache: true
          python-version: ${{ env.PYTHON_VERSION }}   # sets UV_PYTHON
          cache-dependency-glob: |
            pyproject.toml
            uv.lock

      - name: Install dependencies
        run: |
          uv sync --all-extras --frozen

      - name: Start Redis
        run: |
          set -euo pipefail
          # Wait for readiness: `make test-notebooks` probes Redis for SVS
          # support and silently skips 09_svs_vamana.ipynb if it can't connect.
          # Probe over the same host-to-published-port path the notebooks use.
          docker run -d --name redis -p 6379:6379 redis:8.4
          probe() {
            uv run --no-sync python -c "import redis; redis.Redis.from_url('redis://localhost:6379').ping()"
          }
          ready=0
          for _ in $(seq 1 30); do
            if probe 2>/dev/null; then
              ready=1
              break
            fi
            sleep 1
          done
          if [ "$ready" -ne 1 ]; then
            # Unsuppressed retry: distinguishes an unreachable server from a
            # broken venv or import.
            echo "Final probe attempt, stderr shown:"
            probe || true
            echo "::error title=Redis not ready::redis:8.4 never accepted a connection on localhost:6379 after 30 attempts"
            docker logs redis || true
            exit 1
          fi
          docker exec redis redis-cli INFO server | grep redis_version

      - name: Run notebooks
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}
          MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
          VOYAGE_API_KEY: ${{ secrets.VOYAGE_API_KEY }}
          # The Azure cells in docs/user_guide/04_vectorizers.ipynb carry an
          # unconditional `# NBVAL_SKIP`, so notebook validation skips them whether or
          # not these secrets are set, and never blocks on getpass for missing
          # credentials. Restoring the secrets is therefore not enough on its own --
          # those markers have to be removed too. These lines stay wired up so that
          # re-enabling needs no workflow change.
          AZURE_OPENAI_API_KEY: ${{ secrets.AZURE_OPENAI_API_KEY }}
          AZURE_OPENAI_ENDPOINT: ${{ secrets.AZURE_OPENAI_ENDPOINT }}
          AZURE_OPENAI_DEPLOYMENT_NAME: ${{ secrets.AZURE_OPENAI_DEPLOYMENT_NAME }}
          OPENAI_API_VERSION: ${{ secrets.OPENAI_API_VERSION }}
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          HF_TOKEN: ${{ secrets.HF_TOKEN }}
        run: |
          make test-notebooks

  docs:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v6

      - name: Install Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ env.PYTHON_VERSION }}

      - name: Install uv
        uses: astral-sh/setup-uv@v10.0.0
        with:
          version: ${{ env.UV_VERSION }}
          enable-cache: true
          python-version: ${{ env.PYTHON_VERSION }}   # sets UV_PYTHON
          cache-dependency-glob: |
            pyproject.toml
            uv.lock
  
      - name: Install dependencies
        run: |
          uv sync --group docs --frozen

      - name: Build docs
        run: |
          make docs-build