graphforge 0.3.9__tar.gz → 0.4.0__tar.gz

{graphforge-0.3.9 → 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.9 → graphforge-0.4.0}/.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.4.0}/.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.4.0}/.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.4.0}/CHANGELOG.md

@@ -7,6 +7,34 @@ 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
+- **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.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.9 → 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
+.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
 
@@ -178,3 +181,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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphforge
-Version: 0.3.9
+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
@@ -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>
@@ -104,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.
 
@@ -176,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:
@@ -326,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:
 
 ```
 ┌─────────────────────────────────────────────────┐
@@ -336,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.
 
 ---
 
@@ -369,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.9 → 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.