ci-python.yml

name: Python CI

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'tests/**'
      - 'benchmarks/**'
      - 'examples/**'
      - 'docs/**'
      - 'scripts/**'
      - 'pyproject.toml'
      - 'uv.lock'
      - 'Makefile'
      - 'docker-compose.test.yml'
      - 'codecov.yml'
      - '.github/workflows/ci-python.yml'
  pull_request:
    branches: [main]
    paths:
      - 'src/**'
      - 'tests/**'
      - 'benchmarks/**'
      - 'examples/**'
      - 'docs/**'
      - 'scripts/**'
      - 'pyproject.toml'
      - 'uv.lock'
      - 'Makefile'
      - 'docker-compose.test.yml'
      - 'codecov.yml'
      - '.github/workflows/ci-python.yml'

# Least privilege by default; widen per job if one ever needs to write.
permissions:
  contents: read

# A new push to a PR branch supersedes the run in flight. Worth having on a
# workflow that spins up a Neo4j service in four separate jobs.
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Set up Python
        run: uv python install 3.12

      - name: Install dependencies
        run: uv sync --group dev

      # `examples` is in scope (xc-F04): 155 tracked example .py files used to be
      # neither linted nor formatted. One narrow carve-out, mirrored in the
      # Makefile's RUFF_EXTEND_IGNORES:
      # TODO(#144): the AWS FSA Lambda shim imports `src.main`, which ruff's
      # isort sorts into the first-party block. Drop the ignore once that file
      # carries an `# isort: skip` or the backend becomes a real package.
      - name: Run ruff check
        run: |
          uv run ruff check src tests examples \
            --extend-per-file-ignores 'examples/financial-services-advisor/aws-financial-services-advisor/backend/handler.py:I001'

      - name: Run ruff format check
        run: uv run ruff format --check src tests examples

  type-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Set up Python
        run: uv python install 3.12

      # All extras so integrations/ is actually analyzed against real framework
      # types, not stubbed out. Without them the checkers only shallowly analyze
      # integrations/ and would miss real errors. See the type-safety tracking
      # issue #144.
      - name: Install dependencies
        run: uv sync --all-extras --group dev

      # Checked surface: src, benchmarks, the top-level examples/*.py demos and
      # every examples/<dir>/main.py entrypoint. Both checkers are blocking and
      # the surface is kept at zero errors. mypy is the source of truth; ty is
      # the second, independent checker (its complementary rules must also pass).
      # Kept in step with `make typecheck` / `make ty`.
      - name: Run mypy
        # mypy refuses more than one `main.py` per invocation ("Duplicate module
        # named main") and the example directories are hyphenated, so they
        # cannot be packages — one invocation per file.
        run: |
          uv run mypy src benchmarks examples/*.py
          for f in examples/*/main.py; do
            echo "mypy $f"
            uv run mypy "$f"
          done

      - name: Run ty
        # ty takes them all at once. examples/buffered-writes/main.py is excluded
        # because ty rejects its `write_mode: str` parameter against
        # Literal["sync", "buffered"].
        # TODO: narrow that annotation and drop the filter (it passes mypy).
        run: |
          files=$(ls examples/*/main.py | grep -v '^examples/buffered-writes/main.py$')
          # shellcheck disable=SC2086
          uv run ty check src benchmarks examples/*.py $files

  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13"]
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Set up Python ${{ matrix.python-version }}
        run: uv python install ${{ matrix.python-version }}

      # The `strands` extra is needed for the Strands integration's unit tests:
      # tests/unit/integrations/test_strands_*.py all begin with
      # `pytest.importorskip("strands")`, so without it they silently skip and
      # this job reports green on code it never ran. Kept to that one extra --
      # the rest of the suite is designed to run on the dev group alone.
      - name: Install dependencies
        run: uv sync --group dev --extra strands

      - name: Run unit tests
        run: uv run pytest tests/unit -v --cov=neo4j_agent_memory --cov-report=xml --cov-report=term-missing

      - name: Upload unit test coverage artifact
        uses: actions/upload-artifact@v4
        if: matrix.python-version == '3.12'
        with:
          name: coverage-unit
          path: .coverage
          include-hidden-files: true

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v4
        if: matrix.python-version == '3.12'
        with:
          files: ./coverage.xml
          flags: unit
          fail_ci_if_error: false

  integration-test:
    runs-on: ubuntu-latest
    # Use GitHub Actions services for Neo4j - more reliable than testcontainers in CI
    services:
      neo4j:
        image: neo4j:5.26-community
        ports:
          - 7687:7687
          - 7474:7474
        env:
          NEO4J_AUTH: neo4j/test-password
          NEO4J_PLUGINS: '["apoc"]'
          NEO4J_dbms_security_procedures_unrestricted: apoc.*
          NEO4J_dbms_security_procedures_allowlist: apoc.*
        options: >-
          --health-cmd "cypher-shell -u neo4j -p test-password 'RETURN 1'"
          --health-interval 10s
          --health-timeout 10s
          --health-retries 20
          --health-start-period 30s
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Set up Python
        run: uv python install 3.12

      - name: Install dependencies
        run: uv sync --group dev --all-extras

      - name: Wait for Neo4j to be ready
        run: |
          echo "Waiting for Neo4j to be ready..."
          for i in {1..60}; do
            if curl -s http://localhost:7474 > /dev/null 2>&1; then
              echo "Neo4j HTTP interface is ready"
              # Also check bolt connection
              if uv run python -c "from neo4j import GraphDatabase; d = GraphDatabase.driver('bolt://localhost:7687', auth=('neo4j', 'test-password')); d.verify_connectivity(); d.close(); print('Bolt ready')" 2>/dev/null; then
                echo "Neo4j is fully ready!"
                break
              fi
            fi
            echo "Attempt $i: Waiting for Neo4j..."
            sleep 2
          done

      # Cache the whole Hugging Face cache dir so tests don't re-download any
      # model on every run (a cold download can exceed the no-llm test's
      # subprocess timeout). Repeated in each job that pulls a model.
      - name: Cache Hugging Face models
        uses: actions/cache@v4
        with:
          path: ~/.cache/huggingface
          # Rotating key: restore-keys restores the newest prior cache (so nothing
          # re-downloads on a normal run), then the run re-saves under a fresh
          # per-commit key so any newly-used model is folded in automatically —
          # no manual version bump for contributors to remember.
          key: hf-cache-${{ runner.os }}-${{ github.sha }}
          restore-keys: |
            hf-cache-${{ runner.os }}-

      - name: Run integration tests with coverage
        # NAMS integration tests have a dedicated workflow
        # (.github/workflows/nams-integration.yml) so we exclude them here.
        run: |
          uv run pytest tests/integration -v \
            --ignore=tests/integration/nams \
            --tb=short \
            --timeout=300 \
            -x \
            --cov=neo4j_agent_memory \
            --cov-report=xml:coverage-integration.xml \
            --cov-report=term-missing
        env:
          NEO4J_URI: bolt://localhost:7687
          NEO4J_USERNAME: neo4j
          NEO4J_PASSWORD: test-password

      - name: Upload integration coverage artifact
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage-integration
          path: .coverage
          include-hidden-files: true

      - name: Upload integration coverage to Codecov
        uses: codecov/codecov-action@v4
        if: always()
        with:
          files: ./coverage-integration.xml
          flags: integration
          fail_ci_if_error: false

  integration-test-matrix:
    runs-on: ubuntu-latest
    needs: integration-test
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12", "3.13"]
      fail-fast: false
    services:
      neo4j:
        image: neo4j:5.26-community
        ports:
          - 7687:7687
          - 7474:7474
        env:
          NEO4J_AUTH: neo4j/test-password
          NEO4J_PLUGINS: '["apoc"]'
          NEO4J_dbms_security_procedures_unrestricted: apoc.*
          NEO4J_dbms_security_procedures_allowlist: apoc.*
        options: >-
          --health-cmd "cypher-shell -u neo4j -p test-password 'RETURN 1'"
          --health-interval 10s
          --health-timeout 10s
          --health-retries 20
          --health-start-period 30s
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Set up Python ${{ matrix.python-version }}
        run: uv python install ${{ matrix.python-version }}

      - name: Install all dependencies
        run: uv sync --group dev --all-extras

      - name: Wait for Neo4j
        run: |
          for i in {1..60}; do
            if curl -s http://localhost:7474 > /dev/null 2>&1; then
              sleep 5  # Extra wait for full initialization
              break
            fi
            sleep 2
          done

      - name: Cache Hugging Face models
        uses: actions/cache@v4
        with:
          path: ~/.cache/huggingface
          # Rotating key: restore-keys restores the newest prior cache (so nothing
          # re-downloads on a normal run), then the run re-saves under a fresh
          # per-commit key so any newly-used model is folded in automatically —
          # no manual version bump for contributors to remember.
          key: hf-cache-${{ runner.os }}-${{ github.sha }}
          restore-keys: |
            hf-cache-${{ runner.os }}-

      - name: Run integration tests
        # NAMS integration tests run in their own workflow
        # (.github/workflows/nams-integration.yml).
        run: |
          uv run pytest tests/integration \
            --ignore=tests/integration/nams \
            -v \
            --tb=short \
            --timeout=600 \
            --durations=20
        env:
          NEO4J_URI: bolt://localhost:7687
          NEO4J_USERNAME: neo4j
          NEO4J_PASSWORD: test-password

  # Alternative job using testcontainers (useful for debugging or different environments)
  integration-test-testcontainers:
    runs-on: ubuntu-latest
    if: github.event_name == 'workflow_dispatch' || contains(github.event.head_commit.message, '[testcontainers]')
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Set up Python
        run: uv python install 3.12

      - name: Install dependencies
        run: uv sync --group dev --all-extras

      - name: Cache Hugging Face models
        uses: actions/cache@v4
        with:
          path: ~/.cache/huggingface
          # Rotating key: restore-keys restores the newest prior cache (so nothing
          # re-downloads on a normal run), then the run re-saves under a fresh
          # per-commit key so any newly-used model is folded in automatically —
          # no manual version bump for contributors to remember.
          key: hf-cache-${{ runner.os }}-${{ github.sha }}
          restore-keys: |
            hf-cache-${{ runner.os }}-

      - name: Run integration tests with testcontainers
        run: |
          uv run pytest tests/integration \
            --ignore=tests/integration/nams \
            -v \
            --tb=short \
            --timeout=600
        # No NEO4J_URI set - will use testcontainers

  # Example smoke tests - validates that all examples work with current package
  example-tests:
    runs-on: ubuntu-latest
    needs: test # Run after unit tests pass
    services:
      neo4j:
        image: neo4j:5.26-community
        ports:
          - 7687:7687
          - 7474:7474
        env:
          NEO4J_AUTH: neo4j/test-password
          NEO4J_PLUGINS: '["apoc"]'
          NEO4J_dbms_security_procedures_unrestricted: apoc.*
          NEO4J_dbms_security_procedures_allowlist: apoc.*
        options: >-
          --health-cmd "cypher-shell -u neo4j -p test-password 'RETURN 1'"
          --health-interval 10s
          --health-timeout 10s
          --health-retries 20
          --health-start-period 30s
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Set up Python
        run: uv python install 3.12

      - name: Install all dependencies
        run: uv sync --group dev --all-extras

      - name: Wait for Neo4j
        run: |
          echo "Waiting for Neo4j to be ready..."
          for i in {1..60}; do
            if curl -s http://localhost:7474 > /dev/null 2>&1; then
              if uv run python -c "from neo4j import GraphDatabase; d = GraphDatabase.driver('bolt://localhost:7687', auth=('neo4j', 'test-password')); d.verify_connectivity(); d.close()" 2>/dev/null; then
                echo "Neo4j is ready!"
                break
              fi
            fi
            echo "Attempt $i: Waiting for Neo4j..."
            sleep 2
          done

      - name: Cache Hugging Face models
        uses: actions/cache@v4
        with:
          path: ~/.cache/huggingface
          # Rotating key: restore-keys restores the newest prior cache (so nothing
          # re-downloads on a normal run), then the run re-saves under a fresh
          # per-commit key so any newly-used model is folded in automatically —
          # no manual version bump for contributors to remember.
          key: hf-cache-${{ runner.os }}-${{ github.sha }}
          restore-keys: |
            hf-cache-${{ runner.os }}-

      - name: Run example smoke tests
        run: |
          uv run pytest tests/examples \
            -v \
            --tb=short \
            --timeout=120
        env:
          NEO4J_URI: bolt://localhost:7687
          NEO4J_USERNAME: neo4j
          NEO4J_PASSWORD: test-password

  # Quick example validation (no Neo4j required) - runs in parallel with other tests
  example-tests-quick:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Set up Python
        run: uv python install 3.12

      - name: Install dependencies
        run: uv sync --group dev --all-extras

      - name: Cache Hugging Face models
        uses: actions/cache@v4
        with:
          path: ~/.cache/huggingface
          # Rotating key: restore-keys restores the newest prior cache (so nothing
          # re-downloads on a normal run), then the run re-saves under a fresh
          # per-commit key so any newly-used model is folded in automatically —
          # no manual version bump for contributors to remember.
          key: hf-cache-${{ runner.os }}-${{ github.sha }}
          restore-keys: |
            hf-cache-${{ runner.os }}-

      # One marker-driven definition of the quick suite (xc-F01), shared with
      # `make test-examples-quick` and documented in examples/README.md. The
      # hand-maintained file list this replaced had drifted out of step with
      # tests/examples/ five times; tests/examples/test_examples_registry.py now
      # fails if a test module has no quick-selectable test, so a new example
      # cannot silently skip this job.
      - name: Run quick example validation
        run: |
          uv run pytest tests/examples \
            -m "not requires_neo4j and not slow" \
            -v \
            --tb=short \
            --timeout=60

      # The lennys backend has its own pyproject and test suite; the offline
      # subset needs no Neo4j and no keys.
      - name: Run lennys-memory backend tests (offline subset)
        working-directory: examples/lennys-memory/backend
        run: |
          uv sync
          uv run pytest tests -m "not integration" -q --timeout=120

      # Same shape for the GCP financial-services backend.
      - name: Run google-cloud-financial-advisor backend tests
        working-directory: examples/financial-services-advisor/google-cloud-financial-advisor/backend
        run: |
          uv sync
          uv run ruff check src tests
          uv run pytest -q --timeout=120

      # Examples must use the public API: `client.query.cypher` for reads,
      # `client.graph.execute_write` for writes. `client._client` and the
      # internal Cypher-constant module are reach-throughs that break on any
      # refactor. Prose mentions (inside ``backticks``) are allowed, and the
      # examples' own test suites are exempt.
      # TODO: examples/lennys-memory/backend/tests/test_integration.py:240 still
      # reaches through; drop the /tests/ exemption once it is fixed.
      - name: Guard against private-API reach-through in examples
        run: |
          hits=$(grep -rn --include='*.py' \
            -e '\._client\.execute_' \
            -e 'from neo4j_agent_memory\.graph\.queries' \
            examples/ | grep -v '/tests/' | grep -v '``' || true)
          if [ -n "$hits" ]; then
            echo "$hits"
            echo "::error::examples must use client.query / client.graph, not private internals"
            exit 1
          fi

  # GitHub's workflow-level `paths:` filter is all-or-nothing, so this job
  # narrows it per-job: the frontend matrix below is skipped on a Python-only
  # pull request. On pushes to main it always runs. Plain git, no third-party
  # action.
  changed-paths:
    name: Detect changed paths
    runs-on: ubuntu-latest
    outputs:
      frontend: ${{ steps.detect.outputs.frontend }}
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Detect example frontend / infrastructure changes
        id: detect
        env:
          BASE_REF: ${{ github.base_ref }}
        run: |
          if [ "${{ github.event_name }}" != "pull_request" ]; then
            echo "frontend=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          git fetch --no-tags origin "$BASE_REF"
          if git diff --name-only "origin/$BASE_REF...HEAD" \
               | grep -Eq '^examples/.*/(frontend|infrastructure)/'; then
            echo "frontend=true" >> "$GITHUB_OUTPUT"
          else
            echo "frontend=false" >> "$GITHUB_OUTPUT"
          fi

  # Install and build every example frontend plus the CDK app (xc-F08). None of
  # these was ever installed, linted or built by CI, so a frontend that no
  # longer compiles used to ship silently behind 38 `exists()` assertions.
  #
  # The TypeScript flagship (typescript/examples/nextjs-memory-chat) is built by
  # the `type-check-examples` job in ci-typescript.yml instead — its sources live
  # under typescript/**, which this workflow deliberately does not watch.
  frontend-build:
    name: Build example frontend (${{ matrix.name }})
    runs-on: ubuntu-latest
    needs: changed-paths
    if: needs.changed-paths.outputs.frontend == 'true'
    strategy:
      fail-fast: false
      matrix:
        include:
          - name: full-stack-chat-agent
            dir: examples/full-stack-chat-agent/frontend
          - name: lennys-memory
            dir: examples/lennys-memory/frontend
          - name: aws-financial-services-advisor
            dir: examples/financial-services-advisor/aws-financial-services-advisor/frontend
          - name: google-cloud-financial-advisor
            dir: examples/financial-services-advisor/google-cloud-financial-advisor/frontend
          - name: microsoft-agent-retail-assistant
            dir: examples/microsoft_agent_retail_assistant/frontend
          - name: aws-fsa-infrastructure
            dir: examples/financial-services-advisor/aws-financial-services-advisor/infrastructure
            build: synth
    steps:
      - uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '22'

      # `npm ci` needs a tracked lockfile. Not every example has one (the
      # microsoft frontend does not), so fall back to `npm install` rather than
      # failing the matrix entry.
      - name: Install dependencies
        working-directory: ${{ matrix.dir }}
        run: |
          if [ -f package-lock.json ]; then
            npm ci
          else
            echo "::notice::no package-lock.json in ${{ matrix.dir }} — using npm install"
            npm install
          fi

      - name: Type-check
        working-directory: ${{ matrix.dir }}
        run: |
          npm run type-check --if-present
          npm run typecheck --if-present

      - name: Lint
        working-directory: ${{ matrix.dir }}
        run: npm run lint --if-present

      - name: Test
        working-directory: ${{ matrix.dir }}
        run: npm test --if-present

      - name: Build
        working-directory: ${{ matrix.dir }}
        run: npm run ${{ matrix.build || 'build' }}

  # Documentation tests - validates code snippets and internal links
  docs-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Set up Python
        run: uv python install 3.12

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Install Python dependencies
        run: uv sync --group dev

      - name: Install docs dependencies
        run: cd docs && npm install

      - name: Run documentation syntax validation
        run: |
          uv run pytest tests/docs/test_code_snippets.py \
            -v \
            --tb=short \
            --timeout=60

      - name: Run documentation link validation
        run: |
          uv run pytest tests/docs/test_links.py \
            -v \
            --tb=short \
            --timeout=60

      - name: Run documentation build tests
        run: |
          uv run pytest tests/docs/test_build_pipeline.py \
            -v \
            --tb=short \
            --timeout=180

  # Merge coverage from unit and integration tests, check threshold
  coverage-report:
    runs-on: ubuntu-latest
    needs: [test, integration-test]
    if: always()
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Set up Python
        run: uv python install 3.12

      - name: Install dependencies
        run: uv sync --group dev

      - name: Download unit coverage
        uses: actions/download-artifact@v4
        with:
          name: coverage-unit
          path: coverage-unit/
        continue-on-error: true

      - name: Download integration coverage
        uses: actions/download-artifact@v4
        with:
          name: coverage-integration
          path: coverage-integration/
        continue-on-error: true

      - name: Merge coverage reports
        run: |
          # Combine coverage data from both test jobs
          uv run coverage combine coverage-unit/.coverage coverage-integration/.coverage || true
          uv run coverage xml -o coverage-merged.xml
          uv run coverage report --show-missing
        continue-on-error: true

      - name: Upload merged coverage to Codecov
        uses: codecov/codecov-action@v4
        with:
          files: ./coverage-merged.xml
          flags: merged
          fail_ci_if_error: false

      - name: Check coverage threshold
        run: |
          uv run coverage report --fail-under=55 || echo "::warning::Coverage below 55% threshold"
        continue-on-error: true

  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        uses: astral-sh/setup-uv@v4

      - name: Set up Python
        run: uv python install 3.12

      - name: Build package
        run: uv build

      - name: Check package
        run: |
          uv run pip install dist/*.whl
          uv run python -c "import neo4j_agent_memory; print(neo4j_agent_memory.__version__)"

      - name: Upload artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/