rete-graph — Python client for .rete files

Query local and remote .rete graph files with SPARQL from Python. A .rete file is a single, immutable, range-queryable RDF graph file (rete): drop it on any HTTP host that supports Range requests and query it in place — the client fetches only the byte ranges a query touches, never the whole file.

These are native bindings (PyO3) to the same Rust engine that powers the rete CLI and the browser playground.

Install

uv pip install rete-graph        # or: pip install rete-graph

Wheels cover Linux (x86_64/aarch64), macOS, Windows — and, from 0.2.0, browser Python: in JupyterLite or marimo's WASM playground, %pip install rete-graph resolves a Pyodide (PyEmscripten) wheel and remote graphs are queried over sync-XHR range requests, no server anywhere.

A runnable tour with captured outputs lives in examples/tutorial.ipynb, and examples/agents/ turns a graph into agent tools for LangChain and Pydantic AI.

Use

import rete_graph as rete

# Remote: lazy HTTP range reads — a selective query over a multi-GB file
# fetches KBs. Any S3/R2/CDN/GitHub URL with Range + CORS works.
g = rete.open("https://data.graphplaza.com/boe/boe.rete")

rows = g.query("""
    SELECT ?s ?label WHERE {
        ?s <http://www.w3.org/2000/01/rdf-schema#label> ?label
    } LIMIT 10
""")
for row in rows:
    print(row["s"].value, "→", row["label"].to_python())

print(g.stats())   # {'fileLength': ..., 'bytes': ..., 'requests': ...}

query() returns {variable: Term} rows for SELECT, a bool for ASK, and (s, p, o) triples for CONSTRUCT/DESCRIBE. A Term carries .kind / .value / .datatype / .lang, plus .to_python() (int/float/bool for common XSD types) and .n3.

More:

g = rete.open("data/example.rete")            # local file, opened lazily too
g = rete.open(rete.build(nt_text))            # build a graph in memory ("nt"/"nq"/"ttl")
g = rete.open(rete.build(rdflib_graph))       # or straight from an rdflib Graph/Dataset
g = rete.open(url, headers={"Authorization": "Bearer ..."})   # authed hosts

g.examples()                                  # SPARQL examples embedded in the file — run as-is
g.query(q, reason=True)                       # OWL 2 QL entailment (query rewriting)
g.query_df("SELECT ...")                      # pandas DataFrame (pip install rete-graph[pandas])
g.schema()                                    # class/predicate profile
g.prefix_search("Berl")                       # label autocomplete
g.text_search("volcano eruption")             # full-text (files built with --text-index)
g.info(), g.quads, g.content_hash()

SPARQL 1.1 SERVICE federation works out of the box — join a .rete file against any public SPARQL endpoint in one query.

Stream every quad out

iter_quads() is a generator over the whole dataset — default graph first, then each named graph — walked in batches, so peak memory is bounded by one batch no matter how big the file is:

for s, p, o, graph in g.iter_quads():        # N-Triples term tokens; graph is
    ...                                      # None for the default graph

to_nquads() serializes the same walk to a path or any open stream, which is what makes handing a .rete to another RDF toolchain a three-liner:

g.to_nquads("out.nq")                        # or a StringIO / gzip.open(...) / sys.stdout
store = pyoxigraph.Store()
store.bulk_load(path="out.nq", format=pyoxigraph.RdfFormat.N_QUADS)

Measured on figshare.rete (221 MB, 15.9 M quads): to_nquads streams the whole file in 941 MiB peak RSS in 25 s, of which only ~20 MiB is the batch — the rest is the engine's faulted index/dictionary, and it is flat in the quad count. list(g.iter_quads()) on the same file needs many GB, and rete export needs > 1.1 GiB. Pass batch_size= to trade: a small batch makes a peek at a remote graph much cheaper (5 quads for 1.1 MB of range reads at batch_size=1, versus 44 MB at the default 10 000), a large one speeds up a full walk. Scope with graph=: rete.DEFAULT_GRAPH for the unnamed default graph alone, or an IRI for one named graph.

Prepare a .rete step by step

The lazy Builder configures a build — sources, embedded Dataset Card, pyramid, full-text index — then run() / export():

builder = (
    rete.Builder()
    .add_file("people.ttl")                    # or .add(text) / .add(rdflib_graph)
    .card(title="People", license="CC0-1.0", created="2026-07-16")
    .pyramid(algo="louvain")                   # or "types", or .pyramid(False)
    .text_index()
)
builder.run()                                  # bytes; counts in builder.stats
builder.export("people.rete")                  # immutable, host-anywhere file
builder.graph().card()                         # read the embedded card back

See the "Python: build a .rete" tutorial in the docs for the full walkthrough.

Custom storage (fsspec, S3, GCS, …)

Anything that can serve byte ranges can back a graph — pass an object with read_at(offset, length) -> bytes and len():

import fsspec, rete_graph as rete

class FsspecReader:
    def __init__(self, url, **kw):
        self.f = fsspec.open(url, "rb", **kw).open()
        self.size = self.f.size
    def len(self):
        return self.size
    def read_at(self, offset, length):
        self.f.seek(offset)
        return self.f.read(length)

g = rete.open(reader=FsspecReader("s3://my-bucket/data.rete", anon=False))

Building from source

The package is a maturin project; the repo convention is to build in Docker (nothing on the host):

# from the repository root
docker run --rm -v "$PWD":/io ghcr.io/pyo3/maturin build \
    --release -m clients/python/Cargo.toml --out clients/python/dist

uv pip install clients/python/dist/*.whl

Tests: uv pip install pytest && pytest clients/python/tests.

Wheels are abi3 (>= 3.9): one wheel per platform covers every CPython. Releases are published to PyPI by .github/workflows/python-client-publish.yml on a py-v* tag.