research: knowledge graph construction ergonomics and pipeline limitations

[DecisionNerd]

Goal

Hands-on validation of the knowledge-graph-construction use case against GraphForge v0.3.9. Build a small KG from mock LLM extraction output (5–10 entity types, 20+ relationships) and document friction points.

Scope

• Run through every code example in docs/use-cases/knowledge-graph-construction.md — produce a pass/fail matrix
• Document pain points in MERGE-based ingest (e.g., dynamic label support, parameterized label syntax)
• Schema validation gaps: no constraint enforcement, no programmatic way to list all labels/relationship types
• Export ergonomics: how painful is it to get a subgraph into pandas or share as JSON?
• Ingestion performance: what happens when batches grow to 1K, 10K entities?
• Recommendations for utility functions or API additions that would reduce friction

Output

docs/research/kg-construction.md — findings document with:

• Code examples of each friction point (runnable against v0.3.9)
• Pass/fail matrix for all documented patterns
• Prioritized list of recommended API additions

Acceptance Criteria

• All code in knowledge-graph-construction.md tested; failures documented
• Friction points supported by concrete code, not just prose
• Recommendations are specific (method signature proposals, not vague suggestions)
• No code changes to the library (findings only)

[DecisionNerd]

Research complete. Findings in docs/research/kg-construction.md (PR #475).

Snippet validation: 9/11 pass. Failures: S8 (shortestPath SyntaxError → #468), S5 validation script bug (doc pattern is correct).

Pipeline test: 31/31 checks pass across 7 stages including all export methods and 10K bulk ingest (296K nodes/sec).

Issues filed from findings:

• fix: shortestPath() causes SyntaxError — parser does not recognise the function #468 shortestPath() SyntaxError at parse time
• feat: schema introspection — labels(), relationship_types(), node_count(), relationship_count() #469 Schema introspection methods (labels(), relationship_types(), etc.)
• feat: to_json() and from_json() — first-class JSON Graph export and import #470 to_json() / from_json()
• feat: merge_node() — safe, ergonomic node upsert with validated label injection #471 merge_node() — safe label injection
• feat: add_graph_documents() — LangChain-compatible batch ingestion API #472 add_graph_documents() — LangChain compatibility
• docs: warn about CREATE vs MERGE idempotency in KG construction guide #473 Docs: CREATE vs MERGE idempotency warning
• fix: EXISTS {} subquery fails in planner when outer variable used in inner MATCH property #474 EXISTS {} subquery planner bug

Ontology research: All three approaches (Pydantic-only, GF ontology-as-graph, hybrid) validated against current main. Hybrid (C) recommended — single source of truth, fail-fast Pydantic validation, runtime schema introspection via GF.