graphforge 0.3.9__tar.gz → 0.3.10__tar.gz

{graphforge-0.3.9 → graphforge-0.3.10}/.github/workflows/docs.yml

@@ -6,12 +6,15 @@ on:
     paths:
       - 'docs/**'
       - 'mkdocs.yml'
+      - 'src/graphforge/**'
+      - 'pyproject.toml'
       - '.github/workflows/docs.yml'
   pull_request:
     branches: [main]
     paths:
       - 'docs/**'
       - 'mkdocs.yml'
+      - 'src/graphforge/**'
   workflow_dispatch:
 
 permissions:
@@ -19,7 +22,6 @@ permissions:
   pages: write
   id-token: write
 
-# Allow only one concurrent deployment
 concurrency:
   group: pages
   cancel-in-progress: false
@@ -28,30 +30,30 @@ jobs:
   build:
     name: Build Documentation
     runs-on: ubuntu-latest
-
     steps:
-      - name: Checkout code
+      - name: Checkout
         uses: actions/checkout@v6
         with:
-          fetch-depth: 0  # Fetch all history for git info
+          fetch-depth: 0
 
       - name: Install uv
         uses: astral-sh/setup-uv@v8.1.0
+        with:
+          enable-cache: true
 
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
           python-version: '3.12'
 
-      - name: Install documentation dependencies
-        run: |
-          uv pip install --system -e ".[docs]"
+      - name: Install docs dependencies
+        run: uv sync --group docs
 
       - name: Build documentation
-        run: mkdocs build --strict
+        run: uv run mkdocs build --strict
 
       - name: Upload Pages artifact
-        if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
+        if: github.event_name != 'pull_request'
         uses: actions/upload-pages-artifact@v5
         with:
           path: site/
@@ -59,7 +61,7 @@ jobs:
   deploy:
     name: Deploy to GitHub Pages
     needs: build
-    if: (github.event_name == 'push' || github.event_name == 'workflow_dispatch') && github.ref == 'refs/heads/main'
+    if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
 
     environment:

{graphforge-0.3.9 → graphforge-0.3.10}/.github/workflows/test.yml

@@ -266,7 +266,7 @@ jobs:
 
       - name: Report TCK performance metrics
         if: always()
-        run: uv run python3 scripts/tck_perf_report.py test-results-tck.xml --threshold 5
+        run: uv run python3 scripts/tck_perf_report.py test-results-tck.xml --threshold 2
 
       - name: Upload TCK results to Codecov
         uses: codecov/codecov-action@v6

{graphforge-0.3.9 → graphforge-0.3.10}/.gitignore

@@ -173,6 +173,10 @@ profile_*
 *.log
 .temp/
 tmp/
+
+# macOS Finder "keep both" duplicates (e.g. "file 2.py", "file 2.md", "file 3")
+* [0-9]
+* [0-9].*
 # MkDocs build output
 site/
 tck_*.txt

{graphforge-0.3.9 → graphforge-0.3.10}/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.10] - 2026-05-06
+
+### Added
+- **Schema introspection API** (#469, #499) — `labels()`, `relationship_types()`, `node_count(label=None)`, `relationship_count(type=None)` on `GraphForge`; efficient set-union over storage backend
+- **JSON export/import** (#470, #500) — `gf.to_json(path, metadata, indent)` serialises the full graph to a portable JSON file; `GraphForge.from_json(path)` reconstructs it; Hypothesis roundtrip property test
+- **`merge_node()` safe upsert** (#471, #501) — `merge_node(labels, match_on, on_create, on_match)` with regex label validation, index-safe on_match updates, and create/match semantics matching MERGE clause behaviour
+- **`add_graph_documents()` LangChain-compatible ingestion** (#472, #502) — duck-typed batch ingestion accepting any object with `.nodes`/`.relationships` attributes; idempotent edges; rel type pre-check; no `langchain-community` import required
+- **Parse/plan LRU cache** (#464, #504) — `GraphForge(cache_size=N)` caches parsed+planned query pipelines; `clear_cache()` and `cache_info()` for introspection; thread-safe; default size 128
+
+### Fixed
+- **ORDER BY on aliased RETURN DISTINCT property no longer raises UndefinedVariable** (#481, #494) — planner now records `(variable, property)` paths for aliased `PropertyAccess` return items, so `RETURN DISTINCT a.year AS year ORDER BY a.year` resolves correctly
+- **Variable reuse across WITH boundary no longer raises KeyError** (#482, #495) — optimizer's redundant-traversal-elimination pass now treats `Aggregate` as a scope boundary (same as `With`/`Union`/`Subquery`), preventing fresh post-WITH variable bindings from being silently dropped
+- **EXISTS {} subquery crash on anonymous inner node with outer-scope property** (#474, #496) — `_plan_match` now passes `var_name` (always set, from pattern variable or generated) instead of `node_pattern.variable` (can be None) to `_properties_to_predicate`
+- **`shortestPath()` / `allShortestPaths()` parse correctly and raise NotImplementedError** (#468, #497) — previously caused unhelpful `SyntaxError: Unexpected token`; now parsed into `ShortestPathExpression` AST nodes; planner raises `NotImplementedError` with BFS workaround: `MATCH path = (a)-[*1..N]-(b) RETURN length(path) ORDER BY length(path) LIMIT 1`
+
 ## [0.3.9] - 2026-05-04
 
 ### Added

{graphforge-0.3.9 → graphforge-0.3.10}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: help lint format type-check security test pre-push pre-push-fast clean test-tck docstring-coverage test-network test-perf test-perf-xs test-perf-slow test-perf-large coverage coverage-quick coverage-report coverage-diff coverage-strict check-coverage check-patch-coverage test-durations test-analytics
+.PHONY: help lint format type-check security test pre-push pre-push-fast clean test-tck docstring-coverage test-network test-perf test-perf-xs test-perf-slow test-perf-large coverage coverage-quick coverage-report coverage-diff coverage-strict check-coverage check-patch-coverage test-durations test-analytics docs-serve docs-build docs-clean
 
 help:  ## Show this help message
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
@@ -178,3 +178,12 @@ clean:  ## Clean up cache files
 	find . -type f -name "*.pyc" -delete 2>/dev/null || true
 	rm -f test-results*.xml coverage.xml 2>/dev/null || true
 	rm -rf htmlcov/ 2>/dev/null || true
+
+docs-serve:  ## Serve docs locally with live reload (http://127.0.0.1:8000)
+	uv run --group docs mkdocs serve
+
+docs-build:  ## Build docs site to site/ (strict mode)
+	uv run --group docs mkdocs build --strict
+
+docs-clean:  ## Remove built docs
+	rm -rf site/

{graphforge-0.3.9 → graphforge-0.3.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphforge
-Version: 0.3.9
+Version: 0.3.10
 Summary: Composable graph tooling for analysis, construction, and refinement
 Project-URL: Homepage, https://github.com/DecisionNerd/graphforge
 Project-URL: Repository, https://github.com/DecisionNerd/graphforge
@@ -29,6 +29,10 @@ Requires-Dist: msgpack>=1.0
 Requires-Dist: pydantic>=2.6
 Requires-Dist: python-dateutil>=2.8.2
 Requires-Dist: pyyaml>=6.0.3
+Provides-Extra: analytics
+Requires-Dist: networkx>=3.0; extra == 'analytics'
+Requires-Dist: pandas>=2.0; extra == 'analytics'
+Requires-Dist: python-igraph>=0.11; extra == 'analytics'
 Provides-Extra: dev
 Requires-Dist: hypothesis>=6.0; extra == 'dev'
 Requires-Dist: pytest-bdd>=7.0; extra == 'dev'
@@ -39,11 +43,12 @@ Requires-Dist: pytest-timeout>=2.0; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.0; extra == 'dev'
 Requires-Dist: pytest>=9.0.3; extra == 'dev'
 Requires-Dist: ruff==0.15.12; extra == 'dev'
-Provides-Extra: docs
-Requires-Dist: mkdocs-autorefs>=1.0.0; extra == 'docs'
-Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
-Requires-Dist: mkdocs>=1.6.0; extra == 'docs'
-Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
+Provides-Extra: igraph
+Requires-Dist: python-igraph>=0.11; extra == 'igraph'
+Provides-Extra: networkx
+Requires-Dist: networkx>=3.0; extra == 'networkx'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
 Description-Content-Type: text/markdown
 
 <h1 align="center">GraphForge</h1>

{graphforge-0.3.9 → graphforge-0.3.10}/docs/getting-started/installation.md

@@ -18,14 +18,35 @@ uv add graphforge
 
 ```python
 import graphforge
-print(graphforge.__version__)   # 0.3.9
+print(graphforge.__version__)   # 0.3.10
 ```
 
 ## Optional dependencies
 
+GraphForge ships optional extras for analytics workflows.  Install only what
+you need:
+
 ```bash
+# pandas DataFrame export — db.to_dataframe()
+pip install "graphforge[pandas]"
+
+# NetworkX export — db.to_networkx()
+pip install "graphforge[networkx]"
+
+# igraph export — db.to_igraph()
+pip install "graphforge[igraph]"
+
+# All analytics extras at once (pandas + networkx + igraph)
+pip install "graphforge[analytics]"
+
 # Zstandard compression for LDBC .tar.zst datasets
-pip install zstandard
+pip install "graphforge[zstandard]"
+```
+
+With uv:
+
+```bash
+uv add "graphforge[analytics]"
 ```
 
 ## Install from source

graphforge-0.3.10/docs/guide/analytics-integration.md

@@ -0,0 +1,234 @@
+# Analytics Integration
+
+GraphForge ships four export methods that bridge the gap between its Cypher query engine
+and the Python analytics stack.  All four unwrap `CypherValue` objects automatically —
+you get plain Python types, not wrappers.
+
+| Method | Returns | Requires |
+|--------|---------|----------|
+| `db.to_dicts(query)` | `list[dict[str, Any]]` | nothing |
+| `db.to_dataframe(query)` | `pandas.DataFrame` | `pip install "graphforge[pandas]"` |
+| `db.to_networkx(...)` | `networkx.DiGraph` | `pip install "graphforge[networkx]"` |
+| `db.to_igraph(...)` | `igraph.Graph` | `pip install "graphforge[igraph]"` |
+
+---
+
+## `to_dicts()` — plain Python dicts
+
+The simplest export.  Runs a Cypher query and returns a list of dicts with all
+`CypherValue` wrappers unwrapped to their Python equivalents.
+
+```python
+from graphforge import GraphForge
+
+db = GraphForge()
+db.execute("CREATE (:Person {name: 'Alice', age: 30})-[:KNOWS]->(:Person {name: 'Bob', age: 25})")
+
+rows = db.to_dicts("MATCH (n:Person) RETURN n.name AS name, n.age AS age ORDER BY name")
+# [{'name': 'Alice', 'age': 30}, {'name': 'Bob', 'age': 25}]
+```
+
+`to_dicts()` is the preferred pattern for agent loops and LLM workflows — it saves
+boilerplate `.value` accesses with zero overhead vs `execute()`.
+
+Optional parameters dict:
+
+```python
+rows = db.to_dicts(
+    "MATCH (n:Person) WHERE n.age > $min_age RETURN n.name AS name",
+    {"min_age": 28},
+)
+```
+
+---
+
+## `to_dataframe()` — pandas DataFrame
+
+Runs a query and returns a `pandas.DataFrame`.  Column names come from `RETURN`
+aliases; types follow standard pandas inference.
+
+```python
+import matplotlib.pyplot as plt
+
+db = GraphForge("facebook.db")
+
+df = db.to_dataframe("""
+    MATCH (n:Node)
+    WHERE n.degree IS NOT NULL
+    RETURN n.degree AS degree
+    ORDER BY degree
+""")
+
+df["degree"].value_counts().sort_index().plot(
+    kind="bar", logy=True,
+    title="Degree Distribution",
+    xlabel="Degree", ylabel="Nodes",
+    figsize=(12, 4),
+)
+plt.tight_layout()
+plt.savefig("degree_distribution.png", dpi=150)
+```
+
+### Aggregate statistics
+
+```python
+stats = db.to_dataframe("""
+    MATCH (n:Node)
+    WHERE n.degree IS NOT NULL
+    RETURN
+        count(n)        AS total_nodes,
+        avg(n.degree)   AS avg_degree,
+        max(n.degree)   AS max_degree,
+        stDev(n.degree) AS std_degree
+""")
+print(stats.to_string(index=False))
+```
+
+---
+
+## `to_networkx()` — NetworkX DiGraph
+
+Exports the full graph (or a filtered subset) as a `networkx.DiGraph`.  Node
+attributes include all properties plus `_labels` (list of label strings).  Edge
+attributes include all properties plus `_type` (relationship type string).
+
+```python
+import networkx as nx
+
+G = db.to_networkx()
+print(f"Nodes: {G.number_of_nodes()}, Edges: {G.number_of_edges()}")
+```
+
+### Filter by label and relationship type
+
+```python
+# Export only Person nodes and KNOWS edges
+G_social = db.to_networkx(node_label="Person", rel_type="KNOWS")
+```
+
+### Run NetworkX algorithms
+
+```python
+# Degree centrality
+centrality = nx.degree_centrality(G_social)
+
+# PageRank
+pr = nx.pagerank(G_social)
+
+# Clustering coefficient (undirected)
+cc = nx.average_clustering(G_social.to_undirected())
+print(f"Avg clustering: {cc:.4f}")
+```
+
+### Write algorithm results back to GraphForge
+
+NetworkX node IDs are GraphForge internal integers.  Use an UNWIND loop to
+write results back:
+
+```python
+import json
+
+pr_list = [{"node_id": nid, "pagerank": score} for nid, score in pr.items()]
+
+db.execute(
+    "UNWIND $rows AS row "
+    "MATCH (n) WHERE id(n) = row.node_id "
+    "SET n.pagerank = row.pagerank",
+    {"rows": pr_list},
+)
+```
+
+> **Performance note:** Per-node UNWIND write-back is slow above ~5 K nodes
+> because each iteration parses and executes one `SET`.  For large graphs,
+> compute metrics in NetworkX/igraph and store aggregated summaries rather than
+> per-node scores.
+
+---
+
+## `to_igraph()` — igraph Graph
+
+igraph is significantly faster than NetworkX for most graph algorithms:
+betweenness ~130× faster, Louvain ~12×, transitivity ~170×.  Prefer igraph for
+performance-sensitive analysis.
+
+```python
+import igraph as ig
+
+G = db.to_igraph()
+print(f"Nodes: {G.vcount()}, Edges: {G.ecount()}")
+```
+
+### Filter by label and relationship type
+
+```python
+G_social = db.to_igraph(node_label="Person", rel_type="KNOWS")
+```
+
+### Community detection (Louvain)
+
+```python
+G_undirected = G_social.as_undirected()
+communities = G_undirected.community_multilevel()
+print(f"Found {len(communities)} communities")
+print(f"Modularity: {communities.modularity:.4f}")
+```
+
+### Betweenness centrality
+
+```python
+betweenness = G_social.betweenness(directed=False)
+top5 = sorted(zip(betweenness, range(G_social.vcount())), reverse=True)[:5]
+for score, vid in top5:
+    print(f"  vertex {vid}  betweenness={score:.1f}")
+```
+
+---
+
+## Choosing Between Methods
+
+| Scenario | Method |
+|----------|--------|
+| Agent loop / LLM context building | `to_dicts()` |
+| Tabular analysis, plotting | `to_dataframe()` |
+| PageRank, shortest-path algorithms | `to_networkx()` |
+| Betweenness, Louvain, large graphs | `to_igraph()` |
+| Full graph → files / downstream systems | `to_json()` |
+
+---
+
+## JSON Export and Import
+
+`to_json()` / `from_json()` serialise the full graph to the JSON Graph Format
+for sharing, archiving, or loading into other tools.
+
+```python
+# Export
+db.to_json("graph.json", metadata={"source": "pipeline-v2", "date": "2026-05-05"})
+
+# Import into a fresh instance
+from graphforge import GraphForge
+db2 = GraphForge.from_json("graph.json")
+print(db2.node_count(), db2.relationship_count())
+```
+
+---
+
+## Schema Introspection
+
+```python
+print(db.labels())              # ['Organisation', 'Person', 'Technology']
+print(db.relationship_types())  # ['DEPENDS_ON', 'KNOWS', 'RUNS_ON']
+print(db.node_count())          # 42
+print(db.node_count("Person"))  # 15
+print(db.relationship_count())  # 67
+```
+
+---
+
+## Next Steps
+
+- [Network Analysis use case](../use-cases/network-analysis.md) — worked examples
+  on the SNAP ego-Facebook dataset
+- [Knowledge Graph Construction](../use-cases/knowledge-graph-construction.md) —
+  LangChain integration and MERGE patterns
+- [API Reference](../reference/api.md) — full method signatures