Kuzu in Python: Build a No-Server GraphRAG Retriever

GraphRag does not always need a server. Kuzu lets you build a local graph retriever that stays simple enough to prototype. You'll learn how the pieces fit into a workflow that builds a local entity [music] graph and retrieves linked contexts. I'm Professor Pi teaching AI engineering and LLM [music] systems with simple Python. GraphRag is about feeding an LLM the right supporting facts. The hard part [music] is finding which documents and passages actually back an answer. People reach for a graph when plain vector search misses entity structure or cross-document links. Kuzu is a lightweight [music] graph engine you can run locally so you can iterate quickly without spinning [music] up a remote service. At a high level, you want two things. First, a way to record documents, entities, and mentions. Second, a retriever that [music] walks those links and returns the most relevant supporting text. Imagine [music] asking why a company acquired a startup and getting a paragraph that cites a specific press release >> [music] >> and an analyst note. That is the outcome this approach targets. We will build a [music] tiny, self-contained example. It will create an in-memory Kuzu graph, >> [music] >> add two documents and entity mentions, attach a small chunk of supporting text, >> [music] >> and then run a ranked retrieval that favors documents linked by strong mentions. You will see how the graph owns scoring, how chunks map to documents, and how a simple retriever returns ready-to-use evidence. Quick note, this code is designed to teach the core idea clearly. Library versions and local setups can vary so check the official docs if your setup behaves differently. Let's start by creating the in-memory database and inserting a seed document. This snippet establishes an in-memory Kuzu connection and seeds the first document node. Engineers often ask whether they can iterate on a graph rack [music] schema before requesting infrastructure. So, Kuzu database colon plus a direct connection answers that question decisively. We immediately define the lean [music] doc table and call con.execute to insert a seed row, giving every later retrieval [music] step a reliable anchor. The follow-up count query shows how to verify the graph without extra tooling, which keeps experiments reproducible. [music] Seeing documents ready equals one confirms the embedded database is primed for the next expansion. [music] Now, we need entities and mention edges so the graph can express relationships between text [music] and concepts. This example expands the schema with entity awareness and weighted mention edges using Kuzu. The main question here is how [music] to represent entity-linked evidence without juggling multiple insert statements. So, the chained con.execute call adds the entity table, the mentions relationship, and two [music] canonical nodes in a single batch. The U and unwind clause then fans out local tuples directly inside [music] Cypher, stamping weight values onto each relationship so you can compare entity strength later. The resulting count shows both edges landed, keeping the knowledge graph consistent with the text source. The mentions linked equals two output proves the graph now tracks entity links for the seeded document. With a basic graph in place, we want to see ranking and add a second document to compare signals. This code adds a second document, records a fresh mention, and ranks results for Ent Kuzo directly in Kuzo. Engineers typically debate whether to aggregate mention weights in the database or in Python. So, the sum m.weight and order by score d e s c pieces demonstrate [music] that Kuzo can own the scoring logic. We also introduce the chunk [music] node table and has chunk relationship here. So, later chunks can snap into place without refactoring [music] earlier steps. Pulling ranking.getnext yields the leading doc score pair without extra conversions, [music] keeping the control flow tight. The entity leader.doc1 score equals 0.90 print confirms document one still carries the strongest signal for that entity. Next, we attach a concrete [music] chunk of text and ask the graph to find the best supporting [music] neighbor for the second document. This snippet attaches the first [music] chunk node and uses Kuzo to surface the best supporting document for doc two via shared entities. The decision point is whether [music] to materialize helper snippets outside the database. So, the unwind block [music] creates the chunk and has chunk edge in one Cypher round trip and keeps everything [music] co-located with the mentions. The multi-hop query walks [music] doc two, entity, doc one, chunk, summing m.weight, so you only elevate [music] neighbors that truly reinforce the focus document. Because the predicate excludes the focus [music] node, the result zeros in on external justification you can feed to a language model. >> [music] >> The context doc equals doc one, chunk chunk 1A, overlap 0.90. [music] Output shows exactly which chunk should accompany the answer. Finally, wrap the graph calls in a small retriever helper that returns ranked documents with their chunk text so a prompt can be composed immediately. This example wraps the graph calls in a tiny retriever that returns entity scored documents and their chunk text directly from Kuzu. The main concern at this point is whether to lift edge [music] weights into Python or let Cypher package them. So the helper [music] executes a single ranked query and hands back ready to use tuples. Optional match gathers any [music] chunk strings tied to each document. Meaning downstream prompts [music] can include evidence without another database call. Adjusting top K spans or contracts how many documents you surface before vector re-ranking or evaluation. [music] The printed retrieval doc equals doc-1 line proves the helper [music] yields a document identifier, chunk snippet, and score that can feed your rag chain. Mapping this toy to a real project is straightforward. Replace the seed rows with your documents and entities. Incrementally load chunks as you ingest new text. Swap the simple score for a domain adjusted [music] weighting if needed. Use this pattern when provenance and entity links matter and you want [music] to iterate locally before committing to a remote graph service. Keep in mind, an in-memory [music] graph is perfect for prototyping but you'll need a persistent, scalable store [music] for real workloads. Next step, scale the pipeline by adding vector re-ranking after the graph stage [music] and measure recall and latency on a bigger corpus. Tune how many neighbors you surface and see how that affects final answer quality. If practical AI engineering helps you, subscribe and watch the AI engineering videos.