Branch

A Branch combines repeated objects into a local context. Its child fields stay aligned within each object, letting the model compare objects before passing their evidence to the parent.

orders:
  - age_days: 3
    channel: web
    line_items:
      - sku: mug
        quantity: 2
        unit_price: 12.50
      - sku: plate
        quantity: 1
        unit_price: 18.00
churned: false

import relflow as rf

model = rf.Model(
    name="customer", d_model=128, n_layers=3, n_heads=8,
    orders=rf.Branch(
        length=64,
        overflow="tail",
        embed=True,
        age_days=rf.Number,
        channel=rf.Category(size=16),
        line_items=rf.Branch(
            length=16,
            sku=rf.Category(size=8192),
            quantity=rf.Number,
            unit_price=rf.Number,
        ),
    ),
    churned=rf.Boolean(mask=True),
)

Figure 1: Line-item fields combine within each order; order context contributes to the customer prediction.

Binding and shape

The parent keyword supplies the collection name. With query=None, orders reads the same-named child collection, and its leaves read keys within each order. Use a query for a different structural path and a preprocessor for sorting, filtering, or derived values.

A child branch requires a list of objects, including when length=1. Only the generated model root reads one object directly. Each branch adds a shape axis. length caps retained items, shorter collections are padded, and overflow chooses which excess items survive. Padding does not contribute to attention or reduction.

Definitions are reusable: binding clones them without changing the original. Use fields={"length": rf.Number} for generated schemas or child names that collide with configuration. Use Set for membership alone and Vector for one numeric vector.

Options

Option	Default	Meaning
fields	None	Named child mapping, combinable with keyword children; names must be unique.
query	None	Optional node-relative structural path.
length	1	Positive maximum retained items per parent coordinate.
overflow	"head"	Keep first items ("head"), keep last items ("tail"), or raise ("error"). Order comes from the processed source.
attention	"mha"	Encoder mode; see below.
n_layers	1	Positive sequence-encoder depth.
n_heads	4	Positive, even encoder head count and fallback for Attention reduction. Active attention requires heads to divide d_model with at least two dimensions per head.
reduction	rf.Attention()	What encoded memory reaches the parent.
dropout	None	Optional encoder dropout in [0, 1) and reduction fallback.
mask	False	Masking policy applied atomically to active descendants.
embed	False	Export this branch’s contextual embedding.
description	None	Human-readable notes.

Branch settings are local. Model settings configure the generated singleton root; they do not replace every child branch’s defaults.

Attention and reduction

An attention-enabled branch first mixes direct sibling leaves at each aligned record coordinate, when there is more than one. Its n_layers sequence stack then mixes child slots across the branch. Finally, reduction chooses the representations routed to its parent.

Encoder mode	Key/value heads
"mha"	One per query head.
"gqa"	One per pair of query heads.
"mqa"	One shared by every query head.
None	No coordinate or sequence attention; reduction still runs.

Sharing key/value heads changes model capacity as well as cost.

Reduction	Parent receives	Tradeoff
rf.Attention(n_outputs=1)	A fixed number of learned summaries.	Bounded memory; outputs do not guarantee item identity.
rf.Mean()	One average of present encoded vectors.	Cheap; count, order, and individual values are not directly preserved.
None	Every encoded child slot with its presence state.	Keeps token correspondence available; increases parent sequence cost.

Attention has n_outputs=1, n_layers=1, n_heads=None, dropout=None, and position=True. Counts are positive. Omitted heads and dropout inherit from the branch; explicit values override them. position controls rotary position in the reducer only. Mean has no tuning options. These configurations are frozen and share settings, not learned weights, when reused.

attention=None and reduction=None skip different operations. Use both for pure pass-through. Turning off reducer position alone does not remove position information from earlier encoder attention.

Choose reduction from the evidence the parent needs. A mean is not a raw-field sum, and more learned summaries do not perform a join. Capacity must survive later reductions too. model.schema.branch_outputs reports each branch’s static routed width.

The nested cardinality proof tests whether session summaries preserve enough information for their parent. The Mean control isolates what is lost when identical repeated values become one normalized summary.

Masks and output

A branch mask makes one decision per retained branch coordinate and applies it to the whole descendant subtree. A reconstructing policy creates leaf objectives; the branch has no typed decoder of its own. Structural skipping omits selected inputs from tensorization and attention.

embed=True exports branch context at its address. See Embeddings for output roles and Model tree for the route through nested contexts.