knowledge-graph

name

knowledge-graph

description

Use when extracting structure from a meeting or building/exporting the protocol knowledge graph in graph-protokoll: turning Utterances into a Protocol, building the SPARK-format graph, the 5-layer ontology (normativ/zeitlich/prozedural/fallbezug/provenienz), provenance edges, and JSON/CSV/Cypher/Neo4j export. Trigger on pipeline/extract.py, graph_build.py, export.py, neo4j_loader.py, node/relationship/ontology/Cypher work.

Knowledge graph (Protocol → SPARK graph → Neo4j)

The heart of the project: structured public-administration facts as a verifiable graph.

Flow

Utterances ─→ extract.extract_rule_based ─→ Protocol ─→ graph_build.build_graph ─→ {metadata,nodes,relationships}
   (or bundestag_xml.parse_plenarprotokoll)                 ├─ export.write_json / write_csv / write_cypher
                                                            └─ neo4j_loader.load_graph (idempotent MERGE)

• Protocol (extract.py) is the shared model — see .claude/rules/api-conventions.md §2 for its fields. The rule-based extractor uses German-aware regex (_split_sentences keeps "30. Juni" intact; _is_checkable separates facts from promises). The LLM Produktivpfad is specified by EXTRACTION_PROMPT (raises NotImplementedError until wired to a local LLM).
• build_graph emits the SPARK format and tags every node with a schicht (ontology layer). Layers: L1 normativ (Norm, e.g. GemO §37/§18), L2 zeitlich (Sitzung, Fristen), L3 prozedural (Tagesordnungspunkt → Antrag → Abstimmung → Beschluss → Aufgabe), L4 fallbezug (Person, Fraktion, Redebeitrag, Aussage, Frage, AkustischesEreignis), provenienz (Transkriptsegment), plus faktencheck.

Rules when editing

• Don't break the SPARK contract. Reserved keys (id,label,type,subtype / source_id,target_id,relationship_type), stable slug IDs (_slug, person_…, top_…, segment_<idx> pinned to the utterance index). Set schicht on every node.
• Provenance is mandatory. Use the belegt(entity_id, src_list) helper so every entity with quelle_utterances gets a BELEGT_DURCH → Transkriptsegment edge. The audio-second proof is what makes this a justiziables Protokoll, not a summary.
• Add a node label or rel type? Update three places to keep them in sync: build_graph, the Neo4j NEO4J_SCHEMA (in neo4j_graphrag.py), and the web frontend LAYER/legend if a new schicht appears.
• Export & Neo4j: export.py writes JSON/CSV/Cypher in the format the React/3d-force-graph frontend and Neo4j both read. neo4j_loader.build_statements uses parameterized Cypher
  • _SAFE-gated labels and idempotent MERGE — never string-interpolate data.
• Keep metadata.node_count/relationship_count consistent with the actual lists.

Verify

python3 run_demo.py and python3 ingest_bundestag.py (dry-run prints node/rel counts). For a real load: docker compose -f docker-compose.neo4j.yml up -d then python3 ingest_bundestag.py --xml <prot>.xml --load.