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'

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

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

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

  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, and the top-level examples/*.py demos.
      # 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).
      - name: Run mypy
        run: uv run mypy src benchmarks examples/*.py

      - name: Run ty
        run: uv run ty check src benchmarks examples/*.py

  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@v7
        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@v7
        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 }}-

      - name: Run quick example validation
        run: |
          uv run pytest \
            tests/examples/test_entity_resolution.py \
            tests/examples/test_full_stack_apps.py \
            tests/examples/test_google_cloud_financial_advisor.py \
            tests/examples/test_google_cloud_integration.py \
            tests/examples/test_google_adk_demo.py \
            tests/examples/test_microsoft_agent_example.py \
            tests/examples/test_crewai_example.py \
            tests/examples/test_llamaindex_example.py \
            tests/examples/test_aws_financial_advisor.py \
            tests/examples/test_domain_schemas.py \
            tests/examples/test_no_llm_example.py \
            tests/examples/test_enrichment_example.py \
            tests/examples/test_no_phantom_methods.py \
            -v \
            --tb=short \
            --timeout=60

  # 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: "20"

      - 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@v7
        with:
          name: dist
          path: dist/