(WIP) Optional explain payload for GraphRAG.search

[zeljkoagic]

Description

What

Adds optional explainability to GraphRAG.search(): structured provenance with numbered sources, graph paths, and a minimal trace (retriever name + generated Cypher for Text2Cypher).

• New module: generation/explain.py, incl. models, builders, Neo4j path serialization, text2cypher_explain_result_formatter / vector_cypher_explain_result_formatter
• GraphRAG.search(..., explain=ExplainConfig()) numbers context [1], [2], optional inline citations, attaches result.explain
• Runnable demo: examples/question_answering/graphrag_with_explain.py (Text2Cypher + VectorCypher, table/JSON output)

Why

Graph RAG answers are hard to trust without provenance. This PoC shows what was retrieved, which graph paths supported it, and how it was fetched — without re-querying after generation.

How

1. Retriever result_formatter puts GraphContext(paths=…) on each item’s metadata["graph"] (plus result-level metadata["cypher"] for Text2Cypher).
2. When explain is set, GraphRAG forces return_context=True, numbers items for the LLM, and projects the same RetrieverResult into ExplainResult via build_explain_result().
3. GraphContext is paths-only, no flat seed/related-node fields, no dict round-trip in the library.
4. Demo-specific movies/vector helpers live in the example script, not the library.

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update
• Project configuration change

Complexity

Complexity: Medium

How Has This Been Tested?

• Unit tests
• E2E tests
• Manual tests

Example CLI included in PR for manual testing.

Checklist

The following requirements should have been met (depending on the changes in the branch):

• Documentation has been updated
• Unit tests have been updated
• E2E tests have been updated
• Examples have been updated
• New files have copyright header
• CLA (https://neo4j.com/developer/cla/) has been signed
• CHANGELOG.md updated if appropriate