Release v0.3.10 — Analytics Integration: NetworkX/igraph Export & Parse Cache

[DecisionNerd]

Release v0.3.10 — Research-driven Ergonomics

GraphForge v0.3.10 is the research-driven ergonomics release. Four use-case research docs validated the v0.3.9 baseline (#449–#452), surfacing 4 bugs and 5 API gaps. v0.3.10 fixes those bugs, ships quality-of-life API improvements, and polishes the documentation across the use-case guides.

Theme: Validate → Fix → Ship → Document — in that order.

---

Implementation Order

Phase	PR	Closes	Description	Status
1	#494	#481	Fix ORDER BY on aliased RETURN DISTINCT property	✅ Merged
2	#495	#482	Fix variable reuse across WITH boundary (KeyError → UndefinedVariable)	✅ Merged
3	#496	#474	Fix EXISTS {} inner anonymous node with property predicate (ValidationError)	✅ Merged
4	#497	#468	Parse shortestPath/allShortestPaths; raise NotImplementedError with BFS hint	✅ Merged
5	#498	#477	Fix network-analysis.md: wrong SNAP labels, obsolete export patterns, shortestPath note	✅ Merged
6	#499	#469	Schema introspection: labels(), relationship_types(), node_count(), relationship_count()	✅ Merged
7	#500	#470	JSON export/import: to_json(), from_json(), Hypothesis roundtrip test	✅ Merged
8	#501	#471	merge_node() safe upsert with label validation, on_create/on_match semantics	✅ Merged
9	#502	#472	add_graph_documents() LangChain-compatible batch ingestion	✅ Merged
10	#504	#464	Parse/plan LRU cache (cache_size, clear_cache, cache_info)	✅ Merged
11	—	#457, #456, #455, #454, #453, #473, #503	Documentation batch	🔄 In progress
12	—	#448	Release cut: version bump, CHANGELOG, tag, publish	⏳ Pending

Rule: One PR at a time — merge before starting next.

---

Code PRs — Merged ✅

PR	Closes	Description
#494	#481	Planner: ORDER BY scope allows original projected vars under RETURN DISTINCT
#495	#482	Planner/executor: WITH boundary scope reset; KeyError replaced with UndefinedVariable
#496	#474	Planner: EXISTS {} anonymous inner node gets synthetic variable; Pydantic ValidationError fixed
#497	#468	Parser: shortestPath()/allShortestPaths() grammar + transformer; planner raises NotImplementedError with workaround message
#498	#477	Docs: network-analysis.md SNAP labels fixed, to_networkx()/to_igraph() used, shortestPath annotated
#499	#469	API: labels(), relationship_types(), node_count(label), relationship_count(type) — 4 introspection methods
#500	#470	API: to_json(path, metadata, indent), GraphForge.from_json(path), Hypothesis roundtrip property test
#501	#471	API: merge_node(labels, match_on, on_create, on_match) with regex label validation, index-safe on_match
#502	#472	API: add_graph_documents() duck-typed LangChain ingestion, idempotent edges, rel type pre-check
#504	#464	API: GraphForge(cache_size=N) LRU plan cache; clear_cache(); cache_info(); thread-safe

---

Release Blockers

• Phase 1–4: Planner, executor, and parser bugs fixed (fix: ORDER BY on aliased RETURN DISTINCT property no longer raises #494–fix: shortestPath() / allShortestPaths() parse and raise NotImplementedError #497)
• Phase 5: network-analysis.md doc fixes (docs: fix network-analysis.md labels, API methods, and shortestPath note #498)
• Phase 6: Schema introspection API (feat: schema introspection API — labels(), relationship_types(), node_count(), relationship_count() #499)
• Phase 7: JSON export/import API (feat: JSON export/import API — to_json() and from_json() #500)
• Phase 8: merge_node() safe upsert (feat: merge_node() safe upsert API #501)
• Phase 9: add_graph_documents() (feat: add_graph_documents() LangChain-compatible ingestion #502 / feat: add_graph_documents() — LangChain-compatible batch ingestion API #472)
• Phase 10: Parse/plan LRU cache (feat: parse/plan LRU cache for repeated queries #504 / feat: parse/plan LRU cache for repeated queries (stretch) #464)
• Phase 11: Documentation batch (docs: resolve shortestPath() availability contradiction across use-case docs #453–docs: add optional dependency extras to installation guide #457, docs: warn about CREATE vs MERGE idempotency in KG construction guide #473, docs: update use-case research docs to use v0.3.10 ergonomic API #503)
• No TCK regressions from v0.3.9 baseline (3,850+ scenarios)
• All unit + integration tests green
• CI green on Python 3.10–3.14 × all platforms
• Version bumped to 0.3.10 in pyproject.toml
• CHANGELOG.md [Unreleased] promoted to [0.3.10]
• Tracking issue closed

---

Documentation Acceptance Criteria

docs/getting-started/installation.md (#457)

• Add optional dependency extras: graphforge[networkx], graphforge[igraph], graphforge[all]
• Document what each extra installs

examples/05_migration_from_networkx.py (#456)

• Replace manual export code with to_networkx() API
• Verify all examples run without error

docs/use-cases/network-analysis.md (#455)

• Use to_networkx() / to_igraph() throughout
• Consistent NotImplementedError message for shortestPath()

docs/guide/analytics-integration.md (#454)

• New guide: pandas, NetworkX, igraph integration
• Cover to_dicts(), to_dataframe(), to_networkx(), to_igraph()

shortestPath contradiction across use-case docs (#453)

• All use-case docs agree: shortestPath() raises NotImplementedError with BFS workaround

docs/use-cases/knowledge-graph-construction.md (#473)

• Add CREATE vs MERGE idempotency warning
• Reference add_graph_documents() for LangChain workflows

docs/research/ — all four research docs (#503)

• All code examples runnable against v0.3.10
• No examples use manual workarounds superseded by the v0.3.10 API
• Resolved friction points annotated with the API method and PR that fixed them
• shortestPath() status consistent across all four docs

---

Post-v0.3.10 Policy

API surface rule: Any new GraphForge public method added in v0.3.10 must have 90%+ branch coverage and at least one property-based or Hypothesis test where the invariant is non-trivial (e.g., round-trips, idempotency).

LangChain compatibility rule: add_graph_documents() must remain duck-typed — no langchain-community import in production code. All LangChain types are accepted by structural compatibility only.

[DecisionNerd]

Phase 1 complete — PR #494 open

Fixes #481: RETURN DISTINCT a.year AS year ORDER BY a.year now works correctly.

Root cause: projected_prop_paths excluded aliased PropertyAccess items (elif not item.alias guard in planner.py:513). One-line fix: remove the guard so aliased properties are tracked for ORDER BY validation.

4 new tests (2 unit, 2 integration) + full pre-push green.

[DecisionNerd]

Phase 2 complete — PR #495 open

Fixes #482: variable reuse across WITH boundary (KeyError: 'a') is resolved.

Root cause: two optimizer bugs — redundant traversal elimination and filter pushdown both failed to treat Aggregate as a scope boundary. The second MATCH's ScanNodes was incorrectly eliminated as a duplicate of the pre-aggregate one.

4 new tests (2 unit optimizer, 2 integration including full Jaccard query). Pre-push green.

[DecisionNerd]

Phase 3 complete — PR #496 open

Fixes #474: EXISTS {} inner anonymous node with property map no longer raises Pydantic ValidationError.

Root cause: one-line bug — _plan_match used node_pattern.variable (can be None) instead of the already-resolved var_name when calling _properties_to_predicate.

4 integration tests covering all acceptance criteria. Pre-push green.