TongGraph

TongGraph is a lightweight embedded graph compute database for Python applications that need local GraphRAG retrieval, AI memory, agent context graphs, and probabilistic graph reasoning. TongGraph is for applications that want fast local graph structure, persistence, traversal, algorithms, and inference without running a separate database service.

Feature Highlights

• Property graph model with labels, typed edges, scalar properties, and external IDs.
• Rust core exposed through a compact Python SDK.
• Local SQLite persistence with reopen, indexes, snapshots, and compute segment compaction.
• Traversal and analytics APIs for neighbors, k-hop retrieval, BFS, shortest path, connected components, PageRank, random walks, subgraphs, and batch jobs.
• Structured path-query DSL plus a provider-neutral natural-language compiler hook.
• Named full-text indexes for node and edge properties with Unicode word search, trigram substring search, filters, and snapshot reads.
• Named vector indexes for caller-provided node and edge embeddings with cosine, dot-product, and Euclidean exact search.
• Embedded Cypher compatibility subset for local MATCH, CREATE, MERGE, SET, REMOVE, DELETE, DETACH DELETE, RETURN, parameters, and staged transactions.
• Probabilistic graph layer with variables, CPDs, factor tables, evidence, active-subgraph belief propagation, posteriors, and traces.
• Reproducible Python benchmark scripts for graph algorithms and belief propagation.

Getting Started

Install tonggraph with uv (recommended):

uv add tonggraph

or pip:

pip install tonggraph

For local development, run:

git clone https://github.com/bigai-nlco/TongGraph.git
cd TongGraph
uv sync --dev
uv run python scripts/build_python_extension.py

Verify the package:

uv run python -c "from tonggraph import Graph; print(Graph().node_count())"

Create a small graph:

from tonggraph import Graph

graph = Graph()
alice = graph.add_node(
    "alice",
    labels=["Person"],
    properties={"name": "Alice", "active": True},
)
bob = graph.add_node("bob", labels=["Person"], properties={"name": "Bob"})
graph.add_edge(alice, bob, "KNOWS", properties={"weight": 0.8})

print(graph.neighbors(alice))
print(graph.k_hop(alice, 1))

Use local persistence by passing a SQLite path:

graph = Graph("memory.db")
graph.add_node("session:1", labels=["Session"])
graph.compact()

reopened = Graph("memory.db")
print(reopened.node_count())

Run the Python tests and benchmark scripts:

uv run python scripts/build_python_extension.py
uv run pytest
uv run python tests/benchmark/gbench.py --nodes 100 --degree 3 --repeat 3 --output /tmp/gbench.json
uv run python scripts/benchmark_algorithms.py --nodes 1000 --degree 4 --repeat 2
uv run python scripts/benchmark_belief_propagation.py --nodes 1000 --degree 4 --repeat 2

For local development, uv run pytest rebuilds the in-place PyO3 extension when the checked-out Rust or Python sources are newer than the local extension artifact. Release validation should still run the build command explicitly before pytest.

Documentation

• Quickstarts
• Core concepts
• Examples

Development

Before setting up the repository, install:

• Python 3.10 or newer
• uv for the Python environment and Python dependencies
• A stable Rust toolchain, including rustc and cargo, preferably installed with rustup
• A C/C++ build toolchain and the SQLite development library

On Ubuntu or Debian, install the native build dependencies with:

sudo apt update
sudo apt install -y build-essential libsqlite3-dev

On macOS, install the Xcode command-line tools. SQLite is normally provided by the operating system:

xcode-select --install

On Windows, install Rust with the MSVC toolchain, the Visual Studio C++ Build Tools, and SQLite development libraries that are visible to the linker. Alternatively, use WSL and follow the Ubuntu instructions above.

For Linux, macOS, or WSL, install Rust through rustup with:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Verify the required tools before continuing:

python --version
uv --version
rustc --version
cargo --version

uv manages the Python virtual environment and Python packages. It does not install the Rust toolchain, compiler toolchain, or SQLite development library.

Install development dependencies and build the local extension in place:

uv sync --dev
uv run python scripts/build_python_extension.py

Run the test and documentation checks:

uv run pytest
uv run mkdocs build --strict