graphrag-queries

name	graphrag-queries
description	Use when answering natural-language questions over the protocol graph in graph-protokoll: the offline intent-router (pipeline/graphrag.py), the Neo4j Text2Cypher path (pipeline/neo4j_graphrag.py), the NEO4J_SCHEMA / few-shot examples, multi-hop traversals, or query-with-provenance work. Trigger on GraphRAG/Cypher/Text2Cypher/"ask the graph" tasks.

GraphRAG queries (multi-hop questions with audio provenance)

Protocol questions are multi-hop and structured ("which Beschluss from which Abstimmung under which TOP — and where in the audio?"), which is why this uses a graph, not flat vector RAG. There are two implementations sharing one mental model.

Two paths

File	Path	What
pipeline/graphrag.py	Demopfad	GraphRAG.ask(frage) — deterministic intent router over the in-memory graph (GraphIndex: out/inc/by_type/provenance). Each answer ends with ↳ Audiobeleg [mm:ss]. No LLM, no Neo4j.
pipeline/neo4j_graphrag.py	Produktivpfad	Official neo4j-graphrag Text2Cypher: NL question → schema-guided Cypher → Neo4j → LLM answer. LLM via OpenAILLM base_url → local Ollama/vLLM (on-prem, no cloud).

# demo router (stdlib): run_demo.py asks the scenario questions
python3 run_demo.py --scenario gemeinderat
# production (needs Neo4j loaded + a local LLM):
python3 -m pipeline.neo4j_graphrag "Welche Aussagen sind falsch — mit Quelle?"

When editing

• Keep NEO4J_SCHEMA truthful. It lists the node labels + relationships Text2Cypher is allowed to use. Whenever build_graph adds/renames a label or edge, update this schema (and the demo router's traversals) to match — a drifted schema produces wrong Cypher.
• Fact-check answers must cite. The few-shot EXAMPLES are written so verdict queries always return verdict and q.label/q.url. Preserve that when adding examples; the fact-check sourcing invariant extends to query answers.
• Provenance in answers. In the demo router, surface provenance(nid) (BELEGT_DURCH → Transkriptsegment, sorted by start_sec) via _cite. Don't return claims without their beleg.
• The router matches German keywords (faktencheck, beschlussfähig, befangen, aufgabe, abstimmung, …). Extend the keyword map and add a matching by_type/traversal method when adding a query type; keep the fallback hint listing the supported questions.
• On-prem: never point the LLM at a cloud endpoint by default — llm_base_url targets a local OpenAI-compatible server.

Verify

python3 run_demo.py (both scenarios print Q&A with belege). For Text2Cypher, a live Neo4j (docker compose -f docker-compose.neo4j.yml up -d, then --load) and a local LLM are needed.