graphforge 0.3.10__tar.gz → 0.4.0__tar.gz

{graphforge-0.3.10 → graphforge-0.4.0}/.github/SECURITY.md

@@ -2,12 +2,14 @@
 
 ## Supported Versions
 
-GraphForge is currently in active development. Security updates are provided for the following versions:
+GraphForge is pre-v1.0. The API is still maturing, and only the **latest release** receives security updates. If you discover a vulnerability, please update to the latest version first.
 
-| Version | Supported          |
-| ------- | ------------------ |
-| 0.1.x   | :white_check_mark: |
-| < 0.1   | :x:                |
+| Version | Supported |
+| ------- | --------- |
+| Latest (0.3.x) | :white_check_mark: |
+| Older releases | :x: |
+
+We will begin supporting multiple versions once a stable v1.0 API is reached.
 
 ## Reporting a Vulnerability
 
@@ -19,11 +21,7 @@ Please do not report security vulnerabilities through public GitHub issues.
 
 ### 2. Report Privately
 
-Send a detailed report to:
-
-**Email:** [Add your security contact email]
-
-Or use GitHub's private vulnerability reporting:
+Use GitHub's private vulnerability reporting:
 
 1. Go to the [Security tab](https://github.com/DecisionNerd/graphforge/security)
 2. Click "Report a vulnerability"
@@ -126,7 +124,7 @@ GraphForge uses SQLite for persistence:
 
 ### 2. Query Execution
 
-- **No query timeout:** Long-running queries can cause DoS (roadmap item)
+- **No query timeout:** Long-running queries can cause DoS
 - **No resource limits:** No built-in limits on memory/CPU usage
 - **No access control:** No user authentication/authorization system
 
@@ -134,18 +132,6 @@ GraphForge uses SQLite for persistence:
 
 - **MessagePack:** Uses msgpack for serialization (ensure trusted data only)
 
-## Security Roadmap
-
-Future security enhancements planned:
-
-- [ ] Query timeout mechanisms
-- [ ] Resource usage limits (memory, CPU)
-- [ ] Query complexity analysis
-- [ ] Access control system
-- [ ] Audit logging
-- [ ] Encrypted database files
-- [ ] Security scanning in CI/CD (Dependabot, CodeQL)
-
 ## Security-Related Configuration
 
 ### Bandit (Security Linting)
@@ -174,19 +160,11 @@ safety check
 - **CVE assignment:** We'll request CVEs for significant vulnerabilities
 - **Security advisories:** Published on GitHub Security Advisories
 
-## Contact
-
-For security-related questions (non-vulnerability):
-
-- **Email:** [Add your contact email]
-- **Discussions:** [GitHub Discussions](https://github.com/DecisionNerd/graphforge/discussions)
-
 ## Attribution
 
 We believe in recognizing security researchers who help improve GraphForge. With your permission, we'll:
 
 - Credit you in security advisories
-- List you in our security hall of fame (coming soon)
 - Mention you in release notes
 
 ## Additional Resources
@@ -197,6 +175,6 @@ We believe in recognizing security researchers who help improve GraphForge. With
 
 ---
 
-**Last Updated:** January 31, 2026
+**Last Updated:** 2026-05-06
 
 Thank you for helping keep GraphForge secure!

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

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-07
+
+### Added
+- **`db.gds` graph algorithm surface** (#484, PRs #514–#516) — 8 compiled algorithms dispatched to igraph (preferred) or NetworkX: `pagerank`, `betweenness_centrality`, `closeness_centrality`, `degree_centrality`, `louvain`, `connected_components`, `clustering_coefficient`, `triangle_count`. Stream mode returns `dict[node_id, scalar]`; write mode persists results via `set_node_properties()`. Optional `node_label`, `rel_type`, `directed` filters.
+- **`db.search` hybrid retrieval surface** (#476, PRs #517 #533–#539) — FTS5 text search (`db.search.text()`), vector cosine similarity (`db.search.vector()`), and RRF-fused hybrid (`db.search()` / `db.search.hybrid()`). All methods return `list[SearchHit]` with `.ref`, `.score`, `.sources`, `.text_score`, `.vector_score`. Multi-space vector storage: `set_node_vector(id, vec, space="model-name")`. Bring-your-own-vectors; `space` can represent text embeddings, geo coordinates, temporal features, or any numeric feature array.
+- **`SearchHit` result type** — frozen dataclass with score provenance; every `.ref.id` is directly addressable in `db.execute()`.
+- **`set_node_properties()` bulk write-back** (#480, PR #515) — batch-update node properties from a `dict[node_id, dict[prop, value]]`.
+- **`directed` and `node_id_property` export parameters** (#478 #479, PR #514) — `to_networkx(directed=True)`, `to_igraph(node_id_property="name")`, etc.
+- **`graphforge.recipes.neighbourhood()`** (#492, PR #518) — n-hop subgraph expansion returning `list[dict]` for LLM context building.
+- **Benchmark suite** (#388, PR #519) — `make benchmark` runs real-dataset benchmarks through M-tier (XS/S/M/L).
+- **Integration tests for three-surface interoperability** (PR #541) — GDS write-back readable via Cypher, search results addressable via `id()`, cross-surface PageRank threshold queries.
+- **Use-case documentation** (PR #542, closes #523 #524 #525 #526) — `db.gds` examples in `network-analysis.md`; `db.search` + `recipes` in `llm-workflows.md`; deduplication pattern in `knowledge-graph-construction.md`; hybrid tool selection in `agent-grounding.md`.
+
 ## [0.3.10] - 2026-05-06
 
 ### Added

{graphforge-0.3.10 → graphforge-0.4.0}/CLAUDE.md

@@ -111,7 +111,17 @@ PYTEST_WORKERS=2 make test
 
 **When to use `pre-push-fast`:** iterating on non-test changes (refactors, docs, config). Always run the full `pre-push` before opening a PR.
 
-## Architecture: 4-Layer System
+## Architecture: Three-Surface API
+
+GraphForge has three independent API surfaces that share a single storage layer. **Each surface has a distinct code path. Not every feature flows through all four Cypher layers.**
+
+```
+db.execute("MATCH ...")    →  Cypher path (4-layer pipeline below)
+db.gds.pagerank(...)       →  Algorithm path (bypasses parser/planner/executor)
+db.search(...)             →  Search path (bypasses parser/planner/executor)
+```
+
+### Cypher Path (db.execute)
 
 ```
 User Code (Python API / Cypher)
@@ -142,12 +152,90 @@ User Code (Python API / Cypher)
 └─────────────────────────────────────────────────┘
 ```
 
+### Algorithm Path (db.gds)
+
+`db.gds.*` methods do **not** follow the 4-layer pattern. They live in `src/graphforge/algorithms/` and bypass the parser, planner, and executor entirely.
+
+```
+_export_for_algorithm(node_label, rel_type, directed)
+    ↓
+_resolve_backend()  →  native (future) → igraph → NetworkX
+    ↓
+backend.compute(G, **kwargs)  →  dict[node_id, scalar]
+    ↓
+set_node_properties({nid: {write_property: val} …})   ← if write_property set
+```
+
+Key files:
+- `src/graphforge/algorithms/gds.py` — `GraphDataScience` accessor class
+- `src/graphforge/algorithms/_dispatch.py` — `_resolve_backend()` + dispatch helpers
+- `src/graphforge/algorithms/centrality.py` — pagerank, betweenness, closeness, degree
+- `src/graphforge/algorithms/community.py` — louvain, connected_components
+- `src/graphforge/algorithms/structural.py` — clustering_coefficient, triangle_count
+
+#### Adding a db.gds Algorithm
+
+1. Implement in `algorithms/<category>.py`
+2. Add dispatch branch in `_dispatch.py` for each supported backend
+3. Expose method on `GraphDataScience` class in `gds.py`
+4. Tests: unit test per backend + integration test via `db.gds.<name>()`
+
+#### Adding a New Backend Tier
+
+1. Add detection logic in `_resolve_backend()`
+2. Implement algorithm dispatch in the new backend branch
+3. Test priority fallback (native → igraph → NX)
+4. API and existing tests do not change
+
+### Search Path (db.search)
+
+`db.search.*` operates on SQLite FTS5 virtual tables and BLOB vector columns — not the graph execution engine. It does not parse Cypher.
+
+Primary entry point: `db.search(query, vector=...)` — hybrid by default.
+Named methods: `db.search.text(query)`, `db.search.vector(vec)`, `db.search.hybrid(query, vec)`.
+All methods return `list[SearchHit]` with `.ref`, `.score`, `.sources`, `.text_score`, `.vector_score`.
+
+**Bring-your-own-vectors contract:** GraphForge stores and queries vectors but does not generate them.
+The `space` parameter identifies what a vector *represents* — vectors are not limited to text embeddings.
+Common uses: text embeddings (`"text-embedding-3-small"`, SBERT), geographic coordinates (`[lat, lon]`),
+temporal features (`[unix_timestamp, ...]`), or any numeric feature array. For each space, cosine
+similarity finds the closest stored vectors to a query vector. Callers are responsible for consistent
+encoding and dimensionality between stored and query vectors. `db.search.text()` works standalone.
+A recipe for embedding + indexing in one call is tracked in issue #540.
+
+Key files:
+- `src/graphforge/search/search.py` — `GraphSearch` class (text, vector, hybrid, index_node, index_all)
+- `src/graphforge/search/types.py` — `SearchHit` frozen dataclass
+- FTS5 virtual tables: `node_fts`, `edge_fts`
+- Vector store: `node_vector`, `edge_vector` (BLOB columns + NumPy, composite PK `(node_id, space)`)
+
+### Recipes Module (graphforge.recipes)
+
+`graphforge.recipes` is a collection of standalone helper functions (not a `db.*` accessor). Each recipe composes Cypher + API calls into a reusable pattern. Import directly from `graphforge.recipes`.
+
+Key files:
+- `src/graphforge/recipes/__init__.py` — All recipe functions
+
+Current recipes:
+- `neighbourhood(db, canonical, hops, *, label, canonical_prop)` — n-hop neighbourhood expansion returning `list[dict]`
+
+### Design Constraint: No Cypher Extensions
+
+**Neither `db.gds` nor `db.search` modifies `cypher.lark`.** If you are adding a feature and find yourself editing the grammar, you are in the wrong surface.
+
+| Feature type | Surface | Touches parser? |
+|---|---|---|
+| New Cypher clause or function | `db.execute` | Yes — all 4 layers |
+| New graph algorithm | `db.gds` | No |
+| New search capability | `db.search` | No |
+
 ### Key Principles
 
 1. **Each layer is independent** - Parser knows nothing about execution
 2. **AST is the contract** - Parser produces AST, planner consumes it
 3. **Operators are composable** - Planner emits list, executor chains them
 4. **Storage is pluggable** - Executor uses Graph interface
+5. **Surfaces are independent** - `db.gds` and `db.search` bypass the Cypher pipeline
 
 ### Adding Cypher Features
 
@@ -364,6 +452,27 @@ def test_create_node():
 
 ## Common Development Tasks
 
+### Adding a db.gds Algorithm
+
+1. Implement in `src/graphforge/algorithms/<category>.py`
+2. Add dispatch in `_dispatch.py` for each backend
+3. Expose method on `GraphDataScience` in `gds.py`
+4. Tests: unit per backend + integration via `db.gds.<name>()`
+
+### Adding a db.search Feature
+
+1. Add schema migration in search layer (FTS or vector table)
+2. Implement in `src/graphforge/search/<feature>.py`
+3. Expose method on `GraphSearch` accessor
+4. Tests: unit + integration; verify `NodeRef` results are addressable in `db.execute()`
+
+### Adding a Recipe
+
+1. Implement in `src/graphforge/recipes/__init__.py`
+2. Compose from `db.execute()`, `db.gds.*`, or `db.search.*` — recipes are convenience wrappers
+3. Tests: unit test in `tests/unit/recipes/`
+4. Recipe should return plain Python types (list, dict), not CypherValues
+
 ### Adding a New Cypher Clause
 
 1. Grammar: Add to `cypher.lark`

{graphforge-0.3.10 → graphforge-0.4.0}/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 docs-serve docs-build docs-clean
+.PHONY: help lint format type-check security test pre-push pre-push-fast clean test-tck docstring-coverage test-network benchmark 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}'
@@ -33,6 +33,9 @@ test-integration:  ## Run integration tests in parallel (excludes snap/network d
 test-network:  ## Run external network/download tests (snap datasets; requires internet)
 	uv run pytest tests/ -m "snap" -v
 
+benchmark:  ## Run db.gds algorithm benchmarks on snap-ego-facebook; updates benchmarks/baseline.md
+	PYTHONPATH=src uv run python benchmarks/algorithms/bench_gds.py
+
 test-perf-xs:  ## Run perf QA for XS/S datasets only (karate + ego-facebook, ~3 MB total)
 	uv run pytest tests/perf/ -m "perf and not perf_large and not perf_slow" -k "xs or s_face" -v -s
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphforge
-Version: 0.3.10
+Version: 0.4.0
 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
@@ -109,9 +109,13 @@ Modern data science and ML workflows increasingly produce graph-shaped data —
 
 † *Traversal queries with LIMIT scale to ~20M edges; full-scan aggregations are practical up to ~1M edges.*
 
-### v0.3.9 — Performance Release
+### v0.4.0 — Three-Surface API
 
-v0.3.9 delivers substantial performance improvements over v0.3.8: LALR(1) linear-time parsing, O(1) property equality index, LIMIT short-circuit for traversal and UNWIND, bulk ingestion API, SQLite PRAGMA tuning, and `elementId()`. TCK compliance is maintained at **3,885/3,885 (100%)**.
+v0.4.0 ships two new API surfaces alongside the existing Cypher executor:
+
+- **`db.gds`** — 8 compiled graph algorithms (PageRank, betweenness, Louvain, triangle count, and more) dispatched to igraph or NetworkX. Results write back to node properties and are immediately queryable via Cypher.
+- **`db.search`** — hybrid retrieval combining FTS5 text search and vector cosine similarity via RRF fusion. Returns `SearchHit` objects with score provenance; every result is addressable in `db.execute()`.
+- **`graphforge.recipes`** — composable helper functions; `neighbourhood()` builds n-hop context for LLM prompts.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full list of changes.
 
@@ -181,6 +185,36 @@ bob = db.create_node(['Person'], name='Bob', age=25)
 db.create_relationship(alice, bob, 'KNOWS', since=2020)
 ```
 
+### Graph algorithms
+
+```python
+# Compute PageRank and write scores back to nodes
+db.gds.pagerank(write_property="rank")
+
+# Query the written scores via Cypher
+top = db.execute("MATCH (n) RETURN n.name, n.rank ORDER BY n.rank DESC LIMIT 5")
+
+# Stream mode — returns dict[node_id, score] without mutating the graph
+bc = db.gds.betweenness_centrality()
+```
+
+### Hybrid search
+
+```python
+db = GraphForge("research.db")
+
+# Index node text for full-text search
+db.search.index_all(node_label="Paper", properties=["title", "abstract"])
+
+# Store a precomputed embedding (bring your own model)
+db.search.set_node_vector(node_id, embedding, space="text-embedding-3-small")
+
+# Hybrid retrieval — text + vector signals fused via RRF
+results = db.search("graph neural networks", vector=query_embedding, top_k=10)
+for hit in results:
+    print(hit.ref.properties["title"].value, hit.score, hit.sources)
+```
+
 ### Access result values
 
 Results contain `CypherValue` objects — use `.value` to get the Python value:
@@ -331,7 +365,15 @@ finally:
 
 ## Architecture
 
-GraphForge is built in four independent layers:
+GraphForge exposes three independent API surfaces over a shared storage layer:
+
+```
+db.execute("MATCH ...")    →  Cypher path   (Parser → Planner → Executor → Storage)
+db.gds.pagerank(...)       →  Algorithm path (export → compiled backend → write-back)
+db.search.fts(...)         →  Search path   (SQLite FTS5 / vector index → NodeRef list)
+```
+
+The Cypher path is four independent layers:
 
 ```
 ┌─────────────────────────────────────────────────┐
@@ -341,11 +383,11 @@ GraphForge is built in four independent layers:
 ├─────────────────────────────────────────────────┤
 │  Executor       executor.py + evaluator.py      │  Plan → Results
 ├─────────────────────────────────────────────────┤
-│  Storage        memory.py + sqlite_backend.py   │  In-memory + SQLite
+│  Storage        memory.py + sqlite_backend.py   │  In-memory + SQLite WAL
 └─────────────────────────────────────────────────┘
 ```
 
-Storage uses **MessagePack** for efficient binary encoding of graph properties. Persistence is a single SQLite file with WAL mode for durability.
+The algorithm and search paths bypass the Cypher executor entirely — `db.gds` and `db.search` are Python-method surfaces, not Cypher extensions. Storage uses **MessagePack** for efficient binary encoding of graph properties.
 
 ---
 
@@ -374,9 +416,8 @@ make coverage
 |---------|-------|--------|
 | v0.3.8 | Full TCK compliance (3,885/3,885) | **Released** |
 | v0.3.9 | Performance: LALR parser, property indexes, bulk ingest, SQLite tuning, LIMIT short-circuit | **Released** |
-| v0.3.10 | Analytics integration: NetworkX/igraph export, parse/plan cache | Planned |
-| v0.4.0 | Native SNA algorithms: PageRank, betweenness, WCC, shortest path via `CALL gf.algo.*` | Planned |
-| v1.0 | Production-ready: thread safety, large graph support | Future |
+| v0.3.10 | Analytics integration: NetworkX/igraph export, parse/plan cache, `add_graph_documents()` | **Released** |
+| v0.4.0 | Three-surface API: `db.gds.*` graph algorithms + `db.search.*` hybrid retrieval | **Released** |
 
 See [CHANGELOG.md](CHANGELOG.md) for full release history.
 

{graphforge-0.3.10 → graphforge-0.4.0}/README.md

@@ -56,9 +56,13 @@ Modern data science and ML workflows increasingly produce graph-shaped data —
 
 † *Traversal queries with LIMIT scale to ~20M edges; full-scan aggregations are practical up to ~1M edges.*
 
-### v0.3.9 — Performance Release
+### v0.4.0 — Three-Surface API
 
-v0.3.9 delivers substantial performance improvements over v0.3.8: LALR(1) linear-time parsing, O(1) property equality index, LIMIT short-circuit for traversal and UNWIND, bulk ingestion API, SQLite PRAGMA tuning, and `elementId()`. TCK compliance is maintained at **3,885/3,885 (100%)**.
+v0.4.0 ships two new API surfaces alongside the existing Cypher executor:
+
+- **`db.gds`** — 8 compiled graph algorithms (PageRank, betweenness, Louvain, triangle count, and more) dispatched to igraph or NetworkX. Results write back to node properties and are immediately queryable via Cypher.
+- **`db.search`** — hybrid retrieval combining FTS5 text search and vector cosine similarity via RRF fusion. Returns `SearchHit` objects with score provenance; every result is addressable in `db.execute()`.
+- **`graphforge.recipes`** — composable helper functions; `neighbourhood()` builds n-hop context for LLM prompts.
 
 See [CHANGELOG.md](CHANGELOG.md) for the full list of changes.
 
@@ -128,6 +132,36 @@ bob = db.create_node(['Person'], name='Bob', age=25)
 db.create_relationship(alice, bob, 'KNOWS', since=2020)
 ```
 
+### Graph algorithms
+
+```python
+# Compute PageRank and write scores back to nodes
+db.gds.pagerank(write_property="rank")
+
+# Query the written scores via Cypher
+top = db.execute("MATCH (n) RETURN n.name, n.rank ORDER BY n.rank DESC LIMIT 5")
+
+# Stream mode — returns dict[node_id, score] without mutating the graph
+bc = db.gds.betweenness_centrality()
+```
+
+### Hybrid search
+
+```python
+db = GraphForge("research.db")
+
+# Index node text for full-text search
+db.search.index_all(node_label="Paper", properties=["title", "abstract"])
+
+# Store a precomputed embedding (bring your own model)
+db.search.set_node_vector(node_id, embedding, space="text-embedding-3-small")
+
+# Hybrid retrieval — text + vector signals fused via RRF
+results = db.search("graph neural networks", vector=query_embedding, top_k=10)
+for hit in results:
+    print(hit.ref.properties["title"].value, hit.score, hit.sources)
+```
+
 ### Access result values
 
 Results contain `CypherValue` objects — use `.value` to get the Python value:
@@ -278,7 +312,15 @@ finally:
 
 ## Architecture
 
-GraphForge is built in four independent layers:
+GraphForge exposes three independent API surfaces over a shared storage layer:
+
+```
+db.execute("MATCH ...")    →  Cypher path   (Parser → Planner → Executor → Storage)
+db.gds.pagerank(...)       →  Algorithm path (export → compiled backend → write-back)
+db.search.fts(...)         →  Search path   (SQLite FTS5 / vector index → NodeRef list)
+```
+
+The Cypher path is four independent layers:
 
 ```
 ┌─────────────────────────────────────────────────┐
@@ -288,11 +330,11 @@ GraphForge is built in four independent layers:
 ├─────────────────────────────────────────────────┤
 │  Executor       executor.py + evaluator.py      │  Plan → Results
 ├─────────────────────────────────────────────────┤
-│  Storage        memory.py + sqlite_backend.py   │  In-memory + SQLite
+│  Storage        memory.py + sqlite_backend.py   │  In-memory + SQLite WAL
 └─────────────────────────────────────────────────┘
 ```
 
-Storage uses **MessagePack** for efficient binary encoding of graph properties. Persistence is a single SQLite file with WAL mode for durability.
+The algorithm and search paths bypass the Cypher executor entirely — `db.gds` and `db.search` are Python-method surfaces, not Cypher extensions. Storage uses **MessagePack** for efficient binary encoding of graph properties.
 
 ---
 
@@ -321,9 +363,8 @@ make coverage
 |---------|-------|--------|
 | v0.3.8 | Full TCK compliance (3,885/3,885) | **Released** |
 | v0.3.9 | Performance: LALR parser, property indexes, bulk ingest, SQLite tuning, LIMIT short-circuit | **Released** |
-| v0.3.10 | Analytics integration: NetworkX/igraph export, parse/plan cache | Planned |
-| v0.4.0 | Native SNA algorithms: PageRank, betweenness, WCC, shortest path via `CALL gf.algo.*` | Planned |
-| v1.0 | Production-ready: thread safety, large graph support | Future |
+| v0.3.10 | Analytics integration: NetworkX/igraph export, parse/plan cache, `add_graph_documents()` | **Released** |
+| v0.4.0 | Three-surface API: `db.gds.*` graph algorithms + `db.search.*` hybrid retrieval | **Released** |
 
 See [CHANGELOG.md](CHANGELOG.md) for full release history.
 

graphforge-0.4.0/benchmarks/algorithms/bench_gds.py

@@ -0,0 +1,91 @@
+"""Algorithm benchmarks: db.gds vs raw igraph/NX on snap-ego-facebook.
+
+Run with:
+    make benchmark
+    PYTHONPATH=src python benchmarks/algorithms/bench_gds.py   # standalone
+
+Results are written to benchmarks/baseline.md when run via make benchmark.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import time
+
+BASELINE_FILE = Path(__file__).parent.parent / "baseline.md"
+
+
+def _timed(fn):
+    start = time.perf_counter()
+    result = fn()
+    return time.perf_counter() - start, result
+
+
+def run(dataset_name: str = "snap-ego-facebook") -> dict:
+    """Run all algorithm benchmarks and return a results dict."""
+    from graphforge import GraphForge
+    from graphforge.datasets.registry import load_dataset
+
+    gf = GraphForge()
+    load_dataset(gf, dataset_name)
+    nodes = gf.execute("MATCH (n) RETURN count(n) AS c")[0]["c"].value
+    edges = gf.execute("MATCH ()-[r]->() RETURN count(r) AS c")[0]["c"].value
+
+    results: dict = {
+        "dataset": dataset_name,
+        "nodes": nodes,
+        "edges": edges,
+        "algorithms": {},
+    }
+
+    benchmarks = [
+        ("pagerank", gf.gds.pagerank),
+        ("degree_centrality", gf.gds.degree_centrality),
+        ("louvain", gf.gds.louvain),
+        ("connected_components", gf.gds.connected_components),
+        ("clustering_coefficient", gf.gds.clustering_coefficient),
+        ("triangle_count", gf.gds.triangle_count),
+        # betweenness and closeness are O(VE) — included but may be slow
+        ("betweenness_centrality", gf.gds.betweenness_centrality),
+        ("closeness_centrality", gf.gds.closeness_centrality),
+    ]
+
+    for name, fn in benchmarks:
+        elapsed, _ = _timed(fn)
+        results["algorithms"][name] = round(elapsed, 4)
+        print(f"  {name:<30} {elapsed:.3f}s", flush=True)
+
+    return results
+
+
+def _write_baseline(results: dict) -> None:
+    lines = [
+        "# GraphForge Algorithm Benchmark Baseline",
+        "",
+        f"Dataset: `{results['dataset']}` — {results['nodes']:,} nodes, {results['edges']:,} edges",
+        "",
+        "| Algorithm | Time (s) |",
+        "|---|---|",
+    ]
+    for algo, t in results["algorithms"].items():
+        lines.append(f"| `{algo}` | {t:.4f} |")
+    lines += [
+        "",
+        "_Generated by `benchmarks/algorithms/bench_gds.py`._",
+        "",
+        "```json",
+        json.dumps(results, indent=2),
+        "```",
+    ]
+    BASELINE_FILE.write_text("\n".join(lines) + "\n")
+    print(f"\nBaseline written to {BASELINE_FILE}", flush=True)
+
+
+if __name__ == "__main__":
+    import sys
+
+    dataset = sys.argv[1] if len(sys.argv) > 1 else "snap-ego-facebook"
+    print(f"Running algorithm benchmarks on {dataset}...", flush=True)
+    results = run(dataset)
+    _write_baseline(results)

graphforge-0.4.0/benchmarks/baseline.md

@@ -0,0 +1,34 @@
+# GraphForge Algorithm Benchmark Baseline
+
+Dataset: `snap-ego-facebook` — 4,039 nodes, 88,234 edges
+
+| Algorithm | Time (s) |
+|---|---|
+| `pagerank` | 0.1209 |
+| `degree_centrality` | 0.0639 |
+| `louvain` | 0.1126 |
+| `connected_components` | 0.0676 |
+| `clustering_coefficient` | 0.0686 |
+| `triangle_count` | 0.0673 |
+| `betweenness_centrality` | 0.1532 |
+| `closeness_centrality` | 0.1015 |
+
+_Generated by `benchmarks/algorithms/bench_gds.py`._
+
+```json
+{
+  "dataset": "snap-ego-facebook",
+  "nodes": 4039,
+  "edges": 88234,
+  "algorithms": {
+    "pagerank": 0.1209,
+    "degree_centrality": 0.0639,
+    "louvain": 0.1126,
+    "connected_components": 0.0676,
+    "clustering_coefficient": 0.0686,
+    "triangle_count": 0.0673,
+    "betweenness_centrality": 0.1532,
+    "closeness_centrality": 0.1015
+  }
+}
+```