Skip to content

Overview

Embedded sparse graph compute

TongGraph is a Python-facing embedded graph compute database backed by a Rust core. It stores property graphs locally, keeps traversal data in compute-native adjacency layouts, and adds optional finite-discrete probabilistic inference for active graph neighborhoods.

Use it when you want graph retrieval, graph algorithms, and lightweight belief updates in-process rather than behind a separate graph database service.

Quickstart API Reference

Rust core Python API CSR/CSC adjacency Cypher compatible Belief propagation

Goal

TongGraph starts from a compute-native graph kernel and layers database-like features on top. The goal is to make sparse graph storage, neighborhood retrieval, graph algorithms, and probabilistic updates practical inside local applications, research tools, and agent systems.

Highlighted Features

  • Property graph model

    Add nodes and directed typed edges with scalar properties, labels, and external IDs.

  • Compute-first layout

    Traversal reads from compacted outgoing and incoming adjacency segments with a mutable delta overlay for recent writes.

  • Local persistence

    SQLite stores metadata, properties, operation logs, variables, factors, evidence, traces, and segment manifests.

  • Graph algorithms

    Use Python methods for BFS, weighted shortest path, connected components, PageRank, random walks, subgraphs, and batch compute jobs.

  • Structured query layer

    Match connected path patterns with labels, edge types, property filters, return projection, and row limits.

  • Cypher compatibility subset

    Run embedded Graph.cypher() queries for supported MATCH, CREATE, MERGE, RETURN, parameters, result records, and staged local transactions.

  • Sparse probability transfer

    Propagate weighted scores over graph neighborhoods with damping and radius-limited active neighborhoods.

  • Finite belief propagation

    Build binary or categorical variables, CPDs, factor tables, evidence, and residual asynchronous sum-product inference.

Quick Start

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={"probability": 0.8})

assert graph.neighbors(alice) == [bob]
assert graph.query(
    {
        "match": [
            {"node": "a", "external_id": "alice"},
            {"edge": "rel", "type": "KNOWS"},
            {"node": "b", "labels": ["Person"]},
        ],
        "return": ["a", "b"],
    }
) == [{"a": alice, "b": bob}]
assert graph.propagate({alice: 1.0}, 1)[bob] == 0.8

Design Philosophy

TongGraph keeps three ideas separate:

  1. Graph properties are data. A property like probability=0.8 can be used by traversal or propagation, but it is not automatically a probabilistic variable.
  2. Probabilistic semantics are explicit. Variables, states, factors, CPDs, evidence, posteriors, and traces live in a separate model layer.
  3. Storage serves compute. SQLite is a reliable local source of truth, while adjacency traversal and inference run in Rust-owned compute structures.

Where To Go Next