Model Tree

A schema describes what belongs together. Leaves represent typed values; branches combine related values into context; the root represents one observation. The same tree defines where reconstruction targets and exported embeddings live.

Follow One Observation

An order can contain several line items. This is one illustrative record:

customer_tier: gold
line_items:
  - sku: A12
    quantity: 2
    price: 19.99
  - sku: B07
    quantity: 1
    price: 45.50
returned: false

The parent supplies each child’s name:

import relflow as rf

model = rf.Model(
    name="order",
    d_model=64,
    n_layers=2,
    n_heads=4,
    customer_tier=rf.Category(size=16),
    line_items=rf.Branch(
        length=32,
        sku=rf.Category(size=8192),
        quantity=rf.Number,
        price=rf.Number,
    ),
    returned=rf.Boolean(mask=True),
)

Figure 1: Line-item context reaches the order context. The return target supplies no encoder input.

Fields at the same line-item position belong to the same item. The branch contextualizes those inputs and reduces the item collection before routing it to the order. The root combines that representation with customer tier. mask=True keeps the return answer out of the encoder and creates its reconstruction objective.

A decoder pools representations along its ancestor path. Learned decoder queries can also be conditioned on visible sibling representations when their coordinates align. It is therefore misleading to treat every decoder as reading only the root, or to treat a tree edge as a database join. Explicit joins and derived values belong in preprocessing.

Names And Addresses

Model(name="order") names the generated root, whose default name is record. The root is always a singleton; repeated data belongs in a child branch. A child branch reads a list even when length=1; a bare child mapping is not a branch collection. Branch and leaf definitions have no name or positional arguments.

amount=rf.Number uses the field’s defaults. Use rf.Number(...) to configure it. Reusing a definition creates independent named nodes and learned modules; it does not share model weights.

Use a fields mapping when generating children or when a child name collides with a configuration option:

measurements = rf.Branch(
    length=8,
    fields={"length": rf.Number, "description": rf.Category(size=16)},
)

An address identifies a schema location, such as order/line_items/price. Addresses appear in prediction fields, metric names, and mutation predicates. They describe the model’s structure even when an explicit query reads a differently named source path. Names and nesting match input data by default; see Binding Data for other source layouts.

Configure The Context

d_model, n_layers, and n_heads are required when building a Model from fields. d_model is the shared embedding width. The model’s encoder settings configure the root; child branches have their own settings.

Setting	Controls
attention	The branch encoder: "mha", "gqa", "mqa", or None.
n_layers, n_heads, dropout	That branch’s encoder.
reduction	What the branch passes to its parent. Defaults to rf.Attention().
length	Maximum retained records in a child branch.
overflow	Keep the first records ("head", default), last records ("tail"), or raise ("error").
mask	Which inputs to hide or reconstruct.
embed=True	Export the representation at that address.

Encoder and reduction settings are separate. attention=None disables encoder attention but leaves the selected reduction in place. An attention reduction owns its n_outputs, n_layers, optional n_heads/dropout, and position; omitted reduction heads/dropout inherit the branch values. rf.Mean() averages present inputs. reduction=None preserves routed child slots instead of summarizing them. See Branch for the complete reduction contract.

Short collections are padded. Padding and structurally skipped inputs do not contribute to attention or mean pooling. An explicit null remains a modeled value state and is different from padding.

Only declared options are accepted. Use description for notes. A leaf’s active=False excludes it from execution while retaining it in the schema; change an existing model through mutation methods. For learning and output roles, continue to Masking and Embeddings.