feat(vector-io): Add the Neo4j vector provider (#6274)

## Summary

- Add the `remote::neo4j` VectorIO provider with vector, keyword,
hybrid, and graph-aware retrieval.
- Store chunks with correct upsert semantics, including stale-metadata
replacement and a per-store `chunk_id` uniqueness constraint.
- Add deterministic unit and live Neo4j integration coverage, including
a standard RAG versus GraphRAG comparison.
- Add generated provider documentation, dependencies, and GitHub Actions
coverage with a Neo4j 2025.10 service.

## Validation

- `uv run pytest tests/unit/providers/vector_io/test_neo4j.py -q` -> 8
passed
- `NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j
NEO4J_PASSWORD=ogxpassword uv run pytest
tests/integration/vector_io/test_neo4j_graph_retrieval.py -q` -> 1
passed
- `uv run ruff check ...` -> passed
- Workflow YAML parsing -> passed

The live integration test uses fixed embeddings and deterministic graph
relationships. Standard retrieval returns only the directly matching
chunk; GraphRAG returns the related chunk reached through the graph.

---------

Signed-off-by: Francisco Javier Arceo <farceo@redhat.com>

Author: franciscojavierarceo

.github/workflows/integration-vector-io-tests.yml

@@ -38,7 +38,7 @@ jobs:
     strategy:
       matrix:
         # Use a smaller set of providers on PRs to reduce runner contention
-        vector-io-provider: ${{ github.event_name == 'pull_request' && fromJSON('["inline::faiss", "inline::sqlite-vec", "remote::pgvector"]') || fromJSON('["inline::faiss", "inline::sqlite-vec", "inline::milvus", "remote::chromadb", "remote::pgvector", "remote::weaviate", "remote::qdrant", "remote::elasticsearch", "remote::infinispan"]') }}
+        vector-io-provider: ${{ github.event_name == 'pull_request' && fromJSON('["inline::faiss", "inline::sqlite-vec", "remote::pgvector", "remote::neo4j"]') || fromJSON('["inline::faiss", "inline::sqlite-vec", "inline::milvus", "remote::chromadb", "remote::pgvector", "remote::weaviate", "remote::qdrant", "remote::elasticsearch", "remote::infinispan", "remote::neo4j"]') }}
         python-version: ${{ github.event.schedule == '0 0 * * 1' && fromJSON('["3.12", "3.13"]') || fromJSON('["3.12"]') }}
       fail-fast: false # we want to run all tests regardless of failure
 
@@ -81,6 +81,30 @@ jobs:
             -p 5432:5432 \
             pgvector/pgvector:pg17
 
+      - name: Start Neo4j
+        if: matrix.vector-io-provider == 'remote::neo4j'
+        run: |
+          docker run --rm -d \
+            --name neo4j \
+            -p 7474:7474 -p 7687:7687 \
+            -e NEO4J_AUTH=neo4j/ogxpassword \
+            neo4j:2025.10
+
+      - name: Wait for Neo4j to be ready
+        if: matrix.vector-io-provider == 'remote::neo4j'
+        run: |
+          echo "Waiting for Neo4j to be ready..."
+          for _ in {1..60}; do
+            if docker exec neo4j cypher-shell -u neo4j -p ogxpassword 'RETURN 1 AS ok' >/dev/null 2>&1; then
+              echo "Neo4j is ready!"
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "Neo4j failed to start"
+          docker logs neo4j
+          exit 1
+
       - name: Wait for PGVector to be ready
         if: matrix.vector-io-provider == 'remote::pgvector'
         run: |
@@ -239,6 +263,10 @@ jobs:
           INFINISPAN_URL: ${{ matrix.vector-io-provider == 'remote::infinispan' && 'http://localhost:11222' || '' }}
           INFINISPAN_USERNAME: ${{ matrix.vector-io-provider == 'remote::infinispan' && 'admin' || '' }}
           INFINISPAN_PASSWORD: ${{ matrix.vector-io-provider == 'remote::infinispan' && 'password' || '' }}
+          NEO4J_URI: ${{ matrix.vector-io-provider == 'remote::neo4j' && 'bolt://localhost:7687' || '' }}
+          NEO4J_USER: ${{ matrix.vector-io-provider == 'remote::neo4j' && 'neo4j' || '' }}
+          NEO4J_PASSWORD: ${{ matrix.vector-io-provider == 'remote::neo4j' && 'ogxpassword' || '' }}
+          NEO4J_DATABASE: ${{ matrix.vector-io-provider == 'remote::neo4j' && 'neo4j' || '' }}
         run: |
           uv run --no-sync \
             pytest -sv --stack-config="files=inline::localfs,inference=inline::sentence-transformers?trust_remote_code=true,vector_io=${{ matrix.vector-io-provider }},file_processors=inline::pypdf" \
@@ -275,6 +303,11 @@ jobs:
         run: |
           docker logs infinispan > infinispan.log
 
+      - name: Write Neo4j logs to file
+        if: ${{ always() && matrix.vector-io-provider == 'remote::neo4j' }}
+        run: |
+          docker logs neo4j > neo4j.log
+
       - name: Upload all logs to artifacts
         if: ${{ always() }}
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1

docs/docs/building_applications/rag.mdx

@@ -182,6 +182,99 @@ OGX provides OpenAI-compatible RAG capabilities through:
 - **Files API**: Document upload and processing using OpenAI's file format
 - **Responses API**: Enhanced chat completions with agentic tool calling via file search
 
+## GraphRAG with Neo4j
+
+Standard RAG retrieves chunks that are semantically or lexically similar to a
+query. GraphRAG starts with those same vector or keyword results, then follows
+relationships in a graph to find related chunks that may not contain the query
+terms themselves. This is useful for questions that depend on shared entities,
+references, or multi-hop relationships across documents.
+
+OGX provides GraphRAG through the `remote::neo4j` VectorIO provider. The
+provider performs the initial vector, keyword, or hybrid search in Neo4j, then
+expands the result through connected chunk nodes. In the deterministic example
+below, standard retrieval returns a Python chunk, while GraphRAG can also return
+a machine-learning chunk connected through the `python` entity.
+
+### Configure Neo4j
+
+Start Neo4j locally:
+
+```bash
+docker run -d --name ogx-neo4j \
+  -p 7474:7474 -p 7687:7687 \
+  -e NEO4J_AUTH=neo4j/ogxpassword \
+  neo4j:2025.10
+```
+
+Add a Neo4j provider to your stack configuration and enable graph retrieval:
+
+```yaml
+providers:
+  vector_io:
+    - provider_id: neo4j
+      provider_type: remote::neo4j
+      config:
+        uri: ${env.NEO4J_URI:=bolt://localhost:7687}
+        user: ${env.NEO4J_USER:=neo4j}
+        password: ${env.NEO4J_PASSWORD:=}
+        database: ${env.NEO4J_DATABASE:=neo4j}
+        graph_retrieval_enabled: true
+        graph_expansion_depth: 2
+        graph_max_neighbors: 10
+        graph_expansion_weight: 0.15
+        persistence:
+          backend: kv_default
+          namespace: vector_io::neo4j
+```
+
+For the local container above, set `NEO4J_PASSWORD=ogxpassword` before starting
+OGX. Use a secret manager or an environment-specific secret in production.
+
+The provider supports vector, keyword, and hybrid search. `graph_expansion_depth`
+is limited to three hops, and `graph_relationship_types` can restrict traversal
+to selected relationship types. Neighbors receive a score based on the seed
+chunk score multiplied by `graph_expansion_weight`.
+
+### Index Documents and Add Relationships
+
+Create and populate the vector store using the normal Files and Vector Stores
+APIs. Select Neo4j when creating the store:
+
+```python
+from openai import OpenAI
+
+client = OpenAI(base_url="http://localhost:8321/v1", api_key="none")
+vector_store = client.vector_stores.create(
+    name="knowledge-graph",
+    extra_body={"provider_id": "neo4j"},
+)
+
+# Upload files and attach them to vector_store as shown above.
+```
+
+OGX stores chunks and their embeddings, but it does not infer entities or
+relationships for you. Add graph structure with the Neo4j driver or
+`cypher-shell`. Chunk labels are derived from the vector store identifier; for
+example, a store with the identifier `vs_demo` uses the `OGXChunk_vs_demo` label:
+
+```cypher
+MERGE (python:Entity {name: 'python'})
+MATCH (python_chunk:OGXChunk_vs_demo {chunk_id: 'chunk-python'})
+MATCH (ml_chunk:OGXChunk_vs_demo {chunk_id: 'chunk-ml'})
+MERGE (python_chunk)-[:MENTIONS]->(python)
+MERGE (ml_chunk)-[:MENTIONS]->(python)
+```
+
+Use the same Vector Stores search or Responses `file_search` workflow after
+relationships are present. With `graph_retrieval_enabled: false`, retrieval is
+standard RAG. With it enabled, the Neo4j provider expands the initial results
+through the graph and returns the highest-scoring seed and related chunks.
+
+GraphRAG quality depends on the graph structure: add relationships that encode
+meaningful connections, keep traversal depth and neighbor limits bounded, and
+compare results against standard retrieval before enabling it broadly.
+
 ## Configuring Default Embedding Models
 
 To enable automatic vector store creation without specifying embedding models, configure a default embedding model in your config.yaml like so:

docs/docs/providers/vector_io/remote_neo4j.mdx

@@ -0,0 +1,91 @@
+---
+description: |
+  [Neo4j](https://neo4j.com/) is a remote graph database provider for OGX VectorIO.
+  It supports vector search with Neo4j vector indexes, keyword search with full-text
+  indexes, hybrid search with OGX reranking, and optional graph-aware expansion through
+  relationships between retrieved chunks.
+
+  ## Features
+
+  - Vector search over chunk embeddings
+  - Keyword search over chunk text
+  - Hybrid search using OGX reranking
+  - Optional graph-aware retrieval through related chunks
+  - OpenAI-compatible vector store lifecycle through OGX
+
+  ## Usage
+
+  Run Neo4j locally:
+
+  ```bash
+  docker run -d --name ogx-neo4j -p 7474:7474 -p 7687:7687 \
+    -e NEO4J_AUTH=neo4j/ogxpassword neo4j:2025.10
+  ```
+sidebar_label: Remote - Neo4J
+title: remote::neo4j
+---
+
+# remote::neo4j
+
+## Description
+
+
+[Neo4j](https://neo4j.com/) is a remote graph database provider for OGX VectorIO.
+It supports vector search with Neo4j vector indexes, keyword search with full-text
+indexes, hybrid search with OGX reranking, and optional graph-aware expansion through
+relationships between retrieved chunks.
+
+## Features
+
+- Vector search over chunk embeddings
+- Keyword search over chunk text
+- Hybrid search using OGX reranking
+- Optional graph-aware retrieval through related chunks
+- OpenAI-compatible vector store lifecycle through OGX
+
+## Usage
+
+Run Neo4j locally:
+
+```bash
+docker run -d --name ogx-neo4j -p 7474:7474 -p 7687:7687 \
+  -e NEO4J_AUTH=neo4j/ogxpassword neo4j:2025.10
+```
+
+
+## Configuration
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `uri` | `str` | No | bolt://localhost:7687 | Neo4j Bolt URI. |
+| `user` | `str` | No | neo4j | Neo4j username. |
+| `password` | `SecretStr \| None` | No |  | Neo4j password. |
+| `database` | `str` | No | neo4j | Neo4j database name. |
+| `index_prefix` | `str` | No | ogx | Prefix for Neo4j vector and full-text indexes. |
+| `graph_retrieval_enabled` | `bool` | No | False | Whether to expand initial retrieval results through graph relationships. |
+| `graph_expansion_depth` | `int` | No | 1 | Maximum relationship traversal depth for graph-aware retrieval. |
+| `graph_max_neighbors` | `int` | No | 10 | Maximum graph-expanded neighbor chunks to consider per query. |
+| `graph_expansion_weight` | `float` | No | 0.15 | Score multiplier applied to graph-expanded chunks relative to seed chunk scores. |
+| `graph_relationship_types` | `list[str] \| None` | No |  | Relationship types used for graph expansion. When omitted, all relationships are considered. |
+| `persistence` | `KVStoreReference` | No |  | Config for KV store backend. |
+| `persistence.namespace` | `str` | No |  | Key prefix for KVStore backends |
+| `persistence.backend` | `str` | No |  | Name of backend from storage.backends |
+| `metadata_store` | `SqlStoreReference \| None` | No |  | SQL store reference for tenant-isolated vector store metadata. |
+| `metadata_store.table_name` | `str` | No |  | Name of the table to use for the SqlStore |
+| `metadata_store.backend` | `str` | No |  | Name of backend from storage.backends |
+
+## Sample Configuration
+
+```yaml
+uri: ${env.NEO4J_URI:=bolt://localhost:7687}
+user: ${env.NEO4J_USER:=neo4j}
+password: ${env.NEO4J_PASSWORD:=}
+database: ${env.NEO4J_DATABASE:=neo4j}
+graph_retrieval_enabled: false
+graph_expansion_depth: 1
+graph_max_neighbors: 10
+graph_expansion_weight: 0.15
+persistence:
+  namespace: vector_io::neo4j
+  backend: kv_default
+```