04 · Relate

Stage 04 connects documents and chunks into a navigable graph. After Walk, Parse, and Chunk produce the document and chunk inventory, Relate links those objects together — recovering the structure that file-level parsers usually discard.

At a glance

Relate is a built-in stage with no swappable component slot. It reads the directory graph, document lineage, and chunk neighbor links already in the SpaceContext, then writes Relation edges back into that same context.

What Relate produces

This stage produces a set of Relation edges. A Relation is a typed, directed edge. It can connect a document to a document, a chunk to a chunk, or a chunk to a document.

Every edge is appended to a single space-level relation list (ctx.space.relations), reachable on the loaded space as space.relations. Each Relation carries an explicit src and dst document id, plus a type and a score, so consumers can index it by either endpoint.

{ "src": "doc_0007", "dst": "doc_0041", "type": "references", "score": 1.0 }

{ "src": "doc_0019", "dst": "doc_0041", "type": "duplicate-of", "score": 1.0 }

Like every stage, Relate obeys the contract run(ctx: SpaceContext) -> SpaceContext and returns the same mutated context. See the pipeline overview for how stages are sequenced and how to insert, replace, or drop one.

The Relation model

A Relation has four fields. src, dst, and type are required; score defaults to 1.0.

Field	Type	Required	Meaning
src	string	yes	Source id — the id of the document or chunk the edge points from.
dst	string	yes	Target id — the id of the document or chunk the edge points to.
type	RelationType	yes	The kind of edge (see below).
score	float	no (default 1.0)	Confidence/similarity, used by threshold-based types (references, duplicate-of). Structural edges leave it at 1.0.

Every edge is explicit

A Relation always carries an explicit src and dst. The same model is used wherever an edge is stored — at the space level in ctx.relations, on a chunk’s relations list, or on a document’s references / referenced_by list — so the source and target are always identifiable without relying on which object holds the edge.

score is meaningful for inferred edges — references resolved by similarity, or duplicate-of detected by near-match. It stays at its default 1.0 for structural edges like sibling and parent, which are facts about the directory rather than guesses.

The five relation types

RelationType is a string enum with exactly five members. New members may be added in future versions; consumers must ignore unknown values rather than fail.

Type	Value	Connects	Derived from
sibling	sibling	document ↔ document	Same folder / same logical group.
parent	parent	document → document	Folder lineage / containment.
references	references	doc/chunk → doc/chunk	Outgoing citation, link, or mention.
continues	continues	chunk → chunk	Next unit in a split sequence.
duplicate-of	duplicate-of	doc/chunk → doc/chunk	Near or exact duplicate content.

sibling

Two documents that live in the same folder — or otherwise belong to the same logical group — are siblings.

This lets an agent answer “what sits next to this?” When a query matches the onboarding doc, the rest of the onboarding folder is one hop away, not scattered across an undifferentiated vector index.

sibling is purely structural. It falls out of the directory graph built in Walk, so it is high-precision and cheap.

parent

parent captures folder lineage and containment — the ancestry that runs root → leaf. A document under policies/data/retention.pdf has policies/data and policies in its lineage.

These edges make that hierarchy traversable as graph edges, not just as a lineage array on the Document. That is how an agent can scope reasoning to “only contracts under /2024/acme.”

Like sibling, parent is derived directly from the walked tree and is therefore reliable.

continues

When a single logical unit is split, continues records the next unit in the sequence. A unit splits when a long section spreads across chunks, or when content spills from one file into the next.

continues complements the chunk-level neighbors links from Chunk. neighbors are the immediate previous/next chunk ids; continues is the typed edge that lets retrieval follow a run of content forward as a first-class relation.

The payoff: an agent can expand a retrieved fragment into the full passage instead of answering from an orphaned slice.

references

references is an outgoing citation, link, or mention — “this invoice references that PO,” or “this guide links to the GDPR policy.” It connects documents across folders, and it is the edge most likely to be inferred rather than read off the tree.

Resolution may draw on explicit links, filename mentions, and (where enabled) embedding similarity. That is why references edges often carry a score below 1.0.

A references edge is appended to space.relations with the citing document as src and the cited document as dst; the reverse direction is recovered by querying the same list for edges whose dst is the target.

duplicate-of

duplicate-of flags near or exact duplicate content — two versions of the same contract, a file copied between folders, or an export that overlaps an original.

It is almost always an inferred, scored edge. Expect a score close to 1.0 for high-confidence duplicates.

This lets a research archive dedupe versions, and lets retrieval avoid returning five copies of the same passage.

Reliability model

Not every relation is derived the same way. Some edges are structural facts from the directory and chunk graph. Others are inferred and should be consumed with their confidence score.

Category	Relation types	How to treat them
Structural	sibling, parent, continues	High precision. Derived from folder structure and chunk order.
Inferred	references, duplicate-of	Use score to threshold. Tune thresholds to your application.

The split matters for consumers:

• Structural edges (sibling, parent, continues) are facts about the walked tree and chunk sequence.
• Inferred edges (references, duplicate-of) may come from explicit links, filename mentions, or similarity. Treat a scored edge as evidence, not absolute fact.

Start conservative

For inferred edges, indx favours high precision over recall. A wrong references edge is worse than a missing one because it can mislead an agent. When you consume the graph, treat score as a confidence dial you can threshold on.

How it fits the pipeline

Relate runs after Chunk and before Enrich:

01 Walk → 02 Parse → 03 Chunk → 04 Relate → 05 Enrich → 06 Embed+Pack

• It depends on the directory graph from Walk (for sibling / parent) and on chunk lineage and neighbor links from Chunk (for continues).
• It runs before Enrich, so the LLM in stage 05 can take the resolved graph into account when producing type, topics, and summaries.
• It is CPU-bound and largely single-pass; it does not call any model by itself.

Because Relate is a built-in stage with no component slot, you tune it through configuration rather than by swapping a backend. For bespoke linking logic, add your own pass with a custom stage — for example, a domain-specific reference resolver inserted after Relate.

See also

• Core objects — how Relation fits alongside Document and Chunk.
• Data models reference — the full Relation and RelationType definitions.
• 05 · Enrich — the next stage, which builds on the relation graph.