feat (graphdb) Neo4j backend — E2E green ✅

[hourdays]

TL;DR

Adds Neo4j (Bolt / Cypher) as a fully-functional graph DB engine alongside Lakebase. Opt-in via Settings → Triple Store → Global → Neo4j (Bolt). Lakebase remains the default; existing deployments are unaffected.

End-to-end demo on fevm-mjolnir using a real PFAS research-paper ontology:

AI-generated classes from the paper	32
AI-generated relations	13
Entities mapped via Auto-Map	25 / 25
Relations mapped via Auto-Map	12 / 12
Triples written to Neo4j over Bolt	303 in 5.3 s
OWL 2 RL T-Box inference	99 inferred in 0.102 s
SHACL Data Quality (Graph mode against Neo4j)	92.3 % Consistency pass on 13 auto-generated rules
Aura cleanup after capture	0 nodes — paper stays in fevm-mjolnir only

📚 Deck + screenshots (committed in this PR)

Full deck (21 slides) and screenshots live under docs/v0.6-neo4j-demo/:

• 📄 OntoBricks-PR47-Neo4j.pdf — 4.9 MB, 21 slides
• 🌐 deck.html — same content, single-file HTML
• 🖼️ screenshots/ — 13 source PNGs

Key proof screenshots

Settings → Triple Store → Global · engine switched to Neo4j

Build success · 3-card arch: Triple Store → Bolt (UNWIND·MERGE) → Graph DB (Neo4j) · 303 triples

Cockpit · same 3-card arch · Digital Twin Active

Neo4j Browser · 303 nodes under :WaterTreatment_V1 label

Inference · T-Box OWL 2 RL: 99 inferred in 0.102 s

GraphQL Playground · real query against the Neo4j-backed graph

SHACL Data Quality · Graph mode against Neo4j · 92.3 % Consistency pass · 1 rule with 12 violations

What this PR ships

When a user picks Neo4j in Settings → Triple store → Global and configures URI/database/auth in Settings → Triple store → Neo4j, the entire OntoBricks stack works against the Neo4j backend:

• Build writes triples via Bolt with UNWIND + MERGE over a :store-labelled nodes
• Knowledge Graph view, Inference, Graph Chat, GraphQL all query Neo4j via Cypher (16 named-query methods implemented)
• Reasoning (SWRL/OWL) wired to SWRLFlatCypherTranslator — currently scaffolded (returns None + warns), full translation in a follow-up PR. T-Box OWL 2 RL still runs via RDFLib upstream of the store, which produced 99 inferred triples on the demo.
• Settings UI exposes a dedicated Neo4j sub-page with URI/database/auth/credentials form
• Build page + Cockpit both show a 3-card architecture diagram: Triple Store → Bolt (UNWIND·MERGE) → Graph DB (Neo4j), mirroring the Lakeflow Sync card on Lakebase

Lakebase remains the default; existing Lakebase deployments are unaffected.

Architecture decisions

• Single-label-per-store schema (post-bug-fix). Triples are persisted as (:sanitised_table_name) {subject, predicate, object} nodes. The original idea of a :Triple:<store> compound label was abandoned because Neo4j 5+ rejects compound labels in CREATE CONSTRAINT.
• No raw Cypher entry point. execute_query raises NotImplementedError. All writes go through the ontology-validated build pipeline — preserves the C2 safeguard ("l'entrée se fait par l'ontologie", Benoit 20/05).
• No UC Volume sync. Neo4j Aura is remote-only; sync_to_remote / sync_from_remote / local_path are no-ops.
• engine_config keys: uri, database, auth_method (basic / databricks_secret), credentials, encrypted.
• Flat triple model in v1 (supports_graph_model=False). The native property-graph mode (Neo4jGraphStore, supports_graph_model=True) is the natural v2 backend — typed-node graph model is deferred. This is why the Neo4j Browser shows 303 nodes and 0 relationships — by design, not a bug.

Behind the scenes — what the GraphQL resolver emits

For { pfascompounds { id label } } the resolver calls two named methods on Neo4jStore, each emitting a parameterised Cypher statement (no string interpolation):

-- 1. List subjects of type Pfascompound
MATCH (t:`WaterTreatment_V1`)
WHERE t.predicate = $rdf_type
  AND t.object    = $type_uri
RETURN DISTINCT t.subject AS subject
ORDER BY subject SKIP $offset LIMIT $limit

-- 2. Pull rdfs:labels for the matched subjects
MATCH (t:`WaterTreatment_V1`)
WHERE t.predicate = $rdfs_label
  AND t.subject IN $subjects
RETURN t.subject AS subject, t.object AS label

The only way Neo4j gets touched is through these 16 named methods — execute_query raises NotImplementedError. C2 is enforced in code, not just in docs. Zero injection surface (all values bound).

Bugs found and fixed in the same PR

• 🔧 triplestore_page_context tautology — _raw if _raw == "lakebase" else "lakebase" silently coerced every non-Lakebase engine to lakebase, hard-stuck the Graph DB (...) label on Lakebase. Replaced with a direct pass-through.
• 🔧 Multi-label CREATE CONSTRAINT — Neo4j 5+ rejects compound :Triple:<store> labels. Switched to single backtick-quoted label.
• 🔧 Driver missing in deployed App — app.yaml.template's uv run lacked --extra neo4j. Added.
• 🔧 Build page + Cockpit Graph DB card was hidden on Neo4j because the entire Lakebase-details container wrapped both the Sync and Graph DB cards. Restructured to keep the Graph DB card visible regardless of engine, swap Lakebase Sync ↔ Neo4j Bolt writer card based on the active engine.

Open questions for @benoitcayladbx

1. execute_query → NotImplementedError. Aligned with the "l'entrée se fait par l'ontologie" rule from 20/05?
2. Flat-triple model (single label per store) for v1; typed-node graph model deferred. OK?

Test plan — all green ✅

• python3 -m py_compile on every changed .py — OK
• node --check on settings.js / query-sync.js / domain-validation.js — OK
• make bundle-validate on dev-lakebase target — clean
• make deploy to fevm-mjolnir — exit 0, apps RUNNING
• Live E2E against Aura — tests/integration/neo4j_e2e_smoke.py — 9 / 9 assertions pass
• UI: dropdown + section + auth toggle + save — verified via Chrome MCP
• Persistence verified via API: GET /settings/graph-engine returns neo4j, config has uri/db/auth/password
• Neo4j Browser shows 13 nodes with full W3C URI subjects/predicates/objects
• Build pipeline through the OntoBricks UI (Domain → Build) — Sync Result panel: 303 total triples · 5.3 s
• Inference UI — T-Box OWL 2 RL = 99 inferred, SWRL skipped (scaffold no-op as designed)
• SHACL Data Quality in Graph mode against Neo4j — 13 auto-generated Consistency rules, 92.3 % pass
• GraphQL Playground — real query (pfascompounds + facilities + treatmentprocesses) returns the expected entities from Neo4j

Smoke-test artefact (committed): tests/integration/neo4j_e2e_smoke.py — runnable by any contributor with neo4j>=5.0 and the Aura creds file.

cc @benoitcayladbx — branch is ready-for-review on the code AND on visible proof.

Effort estimate

For benchmarking future v0.x backend slots. Honest, triangulated from commit timestamps + session memory — not stopwatch.

• ~20 – 25 effective hours of focused dev/design from me (Hugues), across 4 calendar weeks (2026-05-13 → 2026-06-12). Counts only hands-on time, not deploy waits, async Slack threads, or context-switch dead time.
• Phase split (effective hours):
  • Pre-impl (v0.4 study + v0.6 design proposal + 2026-05-20 sync with Benoit + post-sync writeup): ~4 – 6 h
  • Backend (Neo4jStore.py ~580 LoC + factory dispatch + reasoning scaffold + smoke test): ~8 – 11 h
  • Frontend (settings UI, JS wiring, engine-aware Build / Cockpit labels, 3-card arch + Bolt writer card): ~4 – 6 h
  • Bug-hunt (label schema, --extra neo4j, triplestore_page_context tautology + 4 JS reconciliation fixes): ~2 – 3 h
  • Demo + deck (21-slide HTML/PDF, screenshots, SHACL run, GraphQL → Cypher behind-the-scenes slide): ~3 – 4 h
• Compared to a green-field build (driver eval + GraphQL schema mapping + R2RML→Cypher patterns + smoke test infra + deck from scratch) this would probably be 80 – 120 hours. The ratio comes from (a) the existing GraphDBBackend abstraction already in develop, and (b) heavy use of the Databricks-native agent loop for context-switching, deploy-waiting, and live UI verification.