Composable graph tooling for analysis, construction, and refinement
An embedded, openCypher-compatible graph engine with a Rust core, Arrow results, and Parquet persistence — for research and investigative workflows
GraphForge is an embedded graph engine for nontechnical analysts working with an agent, and for technical users who write their own code. Build a graph, ask a question, and keep what you learn without running a database server. Rust owns the behavior; durable projects use Parquet-backed storage.
Start with ordinary graph construction and querying. Saving analyses, recording challenged hypotheses, independent research, and collaboration are successive, optional journeys. A basic user does not need an ontology, Branch, Version, Proposal, or decision model.
Use GraphForge to inspect a citation network, analyze dependencies, or connect an inquiry to its evidence. For a centrally hosted application with many concurrent users, evaluate an operational database against your workload. Scale guidance explains measured scope and limits.
Choose a learning path:
- Basic: no programming prerequisite. Understand a graph and complete a guided mixed-methods example; an agent or helper handles execution.
- Advanced: basic Python, database, and terminal skills. Write queries and use additional capabilities as needed. GraphForge-specific concepts are explained along the way.
Architecture and implementation contracts are separate specialist references. Neither learning path assumes expert knowledge.
The docs target v0.6.0. Check release availability before using these final-version commands:
python -m pip install graphforge==0.6.0For Node integration:
npm install @curatelabs/graphforge@0.6.0 apache-arrowBefore final publication, select an available candidate or use a source build as described in Installation. Before v1.0.0, there is no backward-compatibility or migration guarantee. The docs maintain one current guide set.
Choose your entry path: Work with an agent, Use a notebook, or Integrate GraphForge.
from graphforge import GraphForge
forge = GraphForge()
survey = forge.add_node("Paper", title="Survey")
methods = forge.add_node("Paper", title="Methods")
forge.add_edge(survey, "CITES", methods)
result = forge.execute("""
MATCH (source:Paper)-[:CITES]->(paper:Paper)
RETURN source.title AS source, paper.title AS title
""")
print(result.to_pylist())
# [{'source': 'Survey', 'title': 'Methods'}]
forge.close()This example runs in memory and loses state when closed. Follow Your first graph for a fuller question, then save and reopen if needed. Durable projects require admitted local storage.
Later, record and revisit an inquiry, or keep research history.
Canonical open-dataset catalogs (graphforge.datasets, SNAP / LDBC /
NetworkRepository convenience loaders) are a backlog extension and are
not part of the core release. Build graphs with the construction APIs or Cypher
today. Choose data for a graph explains
external sources and the supported construction route.
GraphForge exposes one Rust-owned engine through Cypher and analyst-intent APIs:
forge.execute("MATCH ...") → Cypher compiler and execution pipeline
forge.rank(..., by=...) → Rust algorithm dispatch → Arrow Table
forge.cluster(..., by=...) → Rust algorithm dispatch → Arrow Table
forge.similar(..., by=...) → Rust algorithm dispatch → Arrow Table
forge.paths(..., by=...) → Rust algorithm dispatch → Arrow Table
forge.analyze(..., by=...) → Rust algorithm dispatch → Arrow Table
forge.find(...) → Search path → Arrow Table
The Cypher path is four independent Rust layers:
graphforge-cypher → graphforge-ir → graphforge-rel → graphforge-exec
↘ graphforge-storage (Parquet)
Algorithm verbs bypass the Cypher parser and dispatch directly to typed Rust
handlers. Tabular query and analysis results are pyarrow.Table objects in
Python and Arrow IPC bytes in Node. Construction methods can return handles;
metadata and lifecycle methods can return collections, scalars, or no value.
Graph identities are public UUIDs. Python and Node adapt arguments and native
Arrow data; igraph and NetworkX are optional development parity oracles, never
runtime backends or fallbacks.
Graph data persists as Arrow/Parquet; metadata uses JSON.
The agent skills package has a deterministic local NPX pack, offline install, and invocation workflow.
Documentation is an Astro Starlight site under
docs-site/. Markdown sources stay in docs/; the site syncs allowlisted pages
into the Starlight content collection at build time.
# Docs site (local) — see also docs/README.md and docs-site/README.md
pnpm install
pnpm docs:dev # http://localhost:4321/
pnpm docs:build # output: docs-site/dist/
pnpm docs:preview # serve docs-site/dist/
# or: make docs-serve / make docs-build / make docs-clean
# Install with dev dependencies
uv sync --dev
# Run all checks (mirrors CI Lint)
make check
# Targeted Rust gates while iterating
cargo fmt --all -- --check
cargo clippy --workspace -- -D warnings
cargo test --workspaceReleases are cut by pushing a v<version> tag; see RELEASING.md.
| Version | Focus | Status |
|---|---|---|
| v0.6.0 | Basic graph use plus optional inquiry, research, decision, and interchange workflows | Release scope; see live readiness trackers |
| v1.0 | Long-term API stability commitment | Future |
Next steps: install → quick start → docs site. Contributors start at Contributing; operators at Publishing.
See docs/releases/roadmap.md for delivery detail. Release notes are attached to each immutable GitHub Release.
Open source under the Apache License 2.0 (Apache-2.0) © Curate Labs Inc.
You may use, modify, and distribute GraphForge, including for commercial
purposes, subject to the license terms. See LICENSE and
licensing details.
Built on Apache Arrow, DataFusion, Parquet, and the openCypher specification.