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"/"trig"/"rdfxml")
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.

RDF 1.2 and quoted triples

The same --quoted-triple-syntax vocabulary and defaults as the CLI, in both directions:

# Reading: what Turtle/TriG `<< s p o >>` means. "rdf-star" (default) = a quoted
# triple, as before; "rdf12" = RDF 1.2 (`<<( s p o )>>` triple terms, `<< … >>`
# reifiers, `{| … |}` annotations). N-Triples/N-Quads/RDF-XML ignore it.
g = rete.open(rete.build(ttl_text, "ttl", quoted_triple_syntax="rdf12"))
rete.Builder().add_file("data.trig", quoted_triple_syntax="rdf12")

# Writing: to_nquads spells a quoted triple as the RDF 1.2 triple term
# `<<( s p o )>>` by default, which pyoxigraph / Oxigraph 0.5 and Jena 5 read;
# "rdf-star" writes rete's stored `<<s p o>>`. RDF 1.2 has no subject-position
# triple term, so such a statement raises ValueError under "rdf12".
g.to_nquads("out.nq")                                    # rdf12
g.to_nquads("out.nq", quoted_triple_syntax="rdf-star")

# The card says whether a file holds any, from its header (so old files answer):
g.card()["signals"]["quoted_triples"]
# {"present": True, "export_surfaces": ["rdf12", "rdf-star"], "export_default": "rdf12"}

The Pyodide wheel has no RDF 1.2 Turtle/TriG reader and refuses quoted_triple_syntax="rdf12" for those formats by name.

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.