Home

Example status — excerpt: the opening schema demonstrates the public model surface; continue to Getting Started for the tested artifact lifecycle.

relflow builds PyTorch/Lightning models for records that are not naturally flat. An order can contain line items, a customer can have several histories, and a session can contain events. You describe those fields and relationships as a schema; relflow uses the schema as both the input contract and the model blueprint.

import relflow as rf

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

model

Model780.5K params · 3.0 MB

▶nodes ModuleDict780.5K

▶order/customer_tier NodeModule52.9K

▶embedder Embedder1.3K

vocab OnlineVocabularyModel

▶embeddings ModuleDict1.3K

state Embedding 5, 64320

dtype float32
device cpu

content Embedding 16, 641.0K

dtype float32
device cpu

▶counters ModuleDict0

state Counter

content Counter

▶decoder Decoder51.5K

▶pool LearnedQueryCrossAttention50.2K

▶blocks ModuleList50.0K

▶0 CrossAttentionBlock50.0K

attention_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

ffn_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

▶attention RotaryMultiheadAttention16.6K

q_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

k_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

v_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

out_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

rotary RotaryEmbedding

▶ffn Sequential33.1K

0 Linear in_features=64, out_features=256, bias=True16.6K

in_features 64
out_features 256
bias True

tensor

dtype float32
device cpu

1 GELU approximate='none'

approximate 'none'

2 Dropout p=0.0, inplace=False

p 0.0
inplace False

3 Linear in_features=256, out_features=64, bias=True16.4K

in_features 256
out_features 64
bias True

tensor

dtype float32
device cpu

4 Dropout p=0.0, inplace=False

p 0.0
inplace False

norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

▶linears ModuleDict1.4K

state Linear in_features=64, out_features=5, bias=True325

in_features 64
out_features 5
bias True

tensor

dtype float32
device cpu

content Linear in_features=64, out_features=16, bias=True1.0K

in_features 64
out_features 16
bias True

tensor

dtype float32
device cpu

▶order/line_items/sku NodeModule317.0K

▶embedder Embedder131.4K

vocab OnlineVocabularyModel

▶embeddings ModuleDict131.4K

state Embedding 5, 64320

dtype float32
device cpu

content Embedding 2048, 64131.1K

dtype float32
device cpu

▶counters ModuleDict0

state Counter

content Counter

▶decoder Decoder185.6K

▶pool LearnedQueryCrossAttention52.2K

▶blocks ModuleList50.0K

▶0 CrossAttentionBlock50.0K

attention_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

ffn_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

▶attention RotaryMultiheadAttention16.6K

q_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

k_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

v_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

out_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

rotary RotaryEmbedding

▶ffn Sequential33.1K

0 Linear in_features=64, out_features=256, bias=True16.6K

in_features 64
out_features 256
bias True

tensor

dtype float32
device cpu

1 GELU approximate='none'

approximate 'none'

2 Dropout p=0.0, inplace=False

p 0.0
inplace False

3 Linear in_features=256, out_features=64, bias=True16.4K

in_features 256
out_features 64
bias True

tensor

dtype float32
device cpu

4 Dropout p=0.0, inplace=False

p 0.0
inplace False

norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

▶linears ModuleDict133.4K

state Linear in_features=64, out_features=5, bias=True325

in_features 64
out_features 5
bias True

tensor

dtype float32
device cpu

content Linear in_features=64, out_features=2048, bias=True133.1K

in_features 64
out_features 2048
bias True

tensor

dtype float32
device cpu

▶order/line_items/quantity NodeModule54.6K

▶embedder Embedder2.0K

embeddings Embedding 5, 64320

dtype float32
device cpu

counter Counter

linear Linear in_features=26, out_features=64, bias=True1.7K

in_features 26
out_features 64
bias True

tensor

dtype float32
device cpu

normalizer GlobalOnlineNormalizer

▶decoder Decoder52.6K

▶pool LearnedQueryCrossAttention52.2K

▶blocks ModuleList50.0K

▶0 CrossAttentionBlock50.0K

attention_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

ffn_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

▶attention RotaryMultiheadAttention16.6K

q_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

k_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

v_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

out_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

rotary RotaryEmbedding

▶ffn Sequential33.1K

0 Linear in_features=64, out_features=256, bias=True16.6K

in_features 64
out_features 256
bias True

tensor

dtype float32
device cpu

1 GELU approximate='none'

approximate 'none'

2 Dropout p=0.0, inplace=False

p 0.0
inplace False

3 Linear in_features=256, out_features=64, bias=True16.4K

in_features 256
out_features 64
bias True

tensor

dtype float32
device cpu

4 Dropout p=0.0, inplace=False

p 0.0
inplace False

norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

classification Linear in_features=64, out_features=5, bias=True325

in_features 64
out_features 5
bias True

tensor

dtype float32
device cpu

regression Linear in_features=64, out_features=1, bias=True65

in_features 64
out_features 1
bias True

tensor

dtype float32
device cpu

▶order/line_items/price NodeModule54.6K

▶embedder Embedder2.0K

embeddings Embedding 5, 64320

dtype float32
device cpu

counter Counter

linear Linear in_features=26, out_features=64, bias=True1.7K

in_features 26
out_features 64
bias True

tensor

dtype float32
device cpu

normalizer GlobalOnlineNormalizer

▶decoder Decoder52.6K

▶pool LearnedQueryCrossAttention52.2K

▶blocks ModuleList50.0K

▶0 CrossAttentionBlock50.0K

attention_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

ffn_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

▶attention RotaryMultiheadAttention16.6K

q_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

k_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

v_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

out_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

rotary RotaryEmbedding

▶ffn Sequential33.1K

0 Linear in_features=64, out_features=256, bias=True16.6K

in_features 64
out_features 256
bias True

tensor

dtype float32
device cpu

1 GELU approximate='none'

approximate 'none'

2 Dropout p=0.0, inplace=False

p 0.0
inplace False

3 Linear in_features=256, out_features=64, bias=True16.4K

in_features 256
out_features 64
bias True

tensor

dtype float32
device cpu

4 Dropout p=0.0, inplace=False

p 0.0
inplace False

norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

classification Linear in_features=64, out_features=5, bias=True325

in_features 64
out_features 5
bias True

tensor

dtype float32
device cpu

regression Linear in_features=64, out_features=1, bias=True65

in_features 64
out_features 1
bias True

tensor

dtype float32
device cpu

▶order/returned NodeModule51.1K

▶embedder Embedder448

vocab OnlineVocabularyModel

▶embeddings ModuleDict448

state Embedding 5, 64320

dtype float32
device cpu

content Embedding 2, 64128

dtype float32
device cpu

▶counters ModuleDict0

state Counter

content Counter

▶decoder Decoder50.6K

▶pool LearnedQueryCrossAttention50.2K

▶blocks ModuleList50.0K

▶0 CrossAttentionBlock50.0K

attention_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

ffn_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

▶attention RotaryMultiheadAttention16.6K

q_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

k_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

v_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

out_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

rotary RotaryEmbedding

▶ffn Sequential33.1K

0 Linear in_features=64, out_features=256, bias=True16.6K

in_features 64
out_features 256
bias True

tensor

dtype float32
device cpu

1 GELU approximate='none'

approximate 'none'

2 Dropout p=0.0, inplace=False

p 0.0
inplace False

3 Linear in_features=256, out_features=64, bias=True16.4K

in_features 256
out_features 64
bias True

tensor

dtype float32
device cpu

4 Dropout p=0.0, inplace=False

p 0.0
inplace False

norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

▶linears ModuleDict455

state Linear in_features=64, out_features=5, bias=True325

in_features 64
out_features 5
bias True

tensor

dtype float32
device cpu

content Linear in_features=64, out_features=2, bias=True130

in_features 64
out_features 2
bias True

tensor

dtype float32
device cpu

▶order NodeModule150.1K

▶encoder BranchEncoder150.1K

▶encoder ModuleList100.0K

▶0 RotaryTransformerEncoderLayer50.0K

attention_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

ffn_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

▶attention RotaryMultiheadAttention16.6K

q_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

k_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

v_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

out_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

rotary RotaryEmbedding

▶ffn Sequential33.1K

0 Linear in_features=64, out_features=256, bias=True16.6K

in_features 64
out_features 256
bias True

tensor

dtype float32
device cpu

1 GELU approximate='none'

approximate 'none'

2 Dropout p=0.0, inplace=False

p 0.0
inplace False

3 Linear in_features=256, out_features=64, bias=True16.4K

in_features 256
out_features 64
bias True

tensor

dtype float32
device cpu

4 Dropout p=0.0, inplace=False

p 0.0
inplace False

▶1 RotaryTransformerEncoderLayer50.0K

attention_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

ffn_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

▶attention RotaryMultiheadAttention16.6K

q_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

k_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

v_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

out_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

rotary RotaryEmbedding

▶ffn Sequential33.1K

0 Linear in_features=64, out_features=256, bias=True16.6K

in_features 64
out_features 256
bias True

tensor

dtype float32
device cpu

1 GELU approximate='none'

approximate 'none'

2 Dropout p=0.0, inplace=False

p 0.0
inplace False

3 Linear in_features=256, out_features=64, bias=True16.4K

in_features 256
out_features 64
bias True

tensor

dtype float32
device cpu

4 Dropout p=0.0, inplace=False

p 0.0
inplace False

▶pool LearnedQueryCrossAttention50.2K

▶blocks ModuleList50.0K

▶0 CrossAttentionBlock50.0K

attention_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

ffn_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

▶attention RotaryMultiheadAttention16.6K

q_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

k_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

v_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

out_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

rotary RotaryEmbedding

▶ffn Sequential33.1K

0 Linear in_features=64, out_features=256, bias=True16.6K

in_features 64
out_features 256
bias True

tensor

dtype float32
device cpu

1 GELU approximate='none'

approximate 'none'

2 Dropout p=0.0, inplace=False

p 0.0
inplace False

3 Linear in_features=256, out_features=64, bias=True16.4K

in_features 256
out_features 64
bias True

tensor

dtype float32
device cpu

4 Dropout p=0.0, inplace=False

p 0.0
inplace False

norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

▶order/line_items NodeModule100.2K

▶encoder BranchEncoder100.2K

▶encoder ModuleList50.0K

▶0 RotaryTransformerEncoderLayer50.0K

attention_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

ffn_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

▶attention RotaryMultiheadAttention16.6K

q_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

k_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

v_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

out_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

rotary RotaryEmbedding

▶ffn Sequential33.1K

0 Linear in_features=64, out_features=256, bias=True16.6K

in_features 64
out_features 256
bias True

tensor

dtype float32
device cpu

1 GELU approximate='none'

approximate 'none'

2 Dropout p=0.0, inplace=False

p 0.0
inplace False

3 Linear in_features=256, out_features=64, bias=True16.4K

in_features 256
out_features 64
bias True

tensor

dtype float32
device cpu

4 Dropout p=0.0, inplace=False

p 0.0
inplace False

▶pool LearnedQueryCrossAttention50.2K

▶blocks ModuleList50.0K

▶0 CrossAttentionBlock50.0K

attention_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

ffn_norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

▶attention RotaryMultiheadAttention16.6K

q_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

k_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

v_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

out_proj Linear in_features=64, out_features=64, bias=True4.2K

in_features 64
out_features 64
bias True

tensor

dtype float32
device cpu

rotary RotaryEmbedding

▶ffn Sequential33.1K

0 Linear in_features=64, out_features=256, bias=True16.6K

in_features 64
out_features 256
bias True

tensor

dtype float32
device cpu

1 GELU approximate='none'

approximate 'none'

2 Dropout p=0.0, inplace=False

p 0.0
inplace False

3 Linear in_features=256, out_features=64, bias=True16.4K

in_features 256
out_features 64
bias True

tensor

dtype float32
device cpu

4 Dropout p=0.0, inplace=False

p 0.0
inplace False

norm LayerNorm (64,) eps=1e-05, elementwise_affine=True, bias=True128

eps 1e-05
elementwise_affine True
bias True

tensor

dtype float32
device cpu

Module typesWeightActivationNormalizationRegularizationTrainableFrozen / no params

This model reads an order as a structured object. The line items interact in their own repeated context before that context is pooled into the order. The returned value is hidden and learned as a supervised target. The root address is order, so its target prediction is written at order/returned.

Why Preserve The Record Shape?

Flattening nested records into one feature row can be the right choice. It can also discard ordering and local relationships, force every history into the same window, and move important modeling decisions into a separate feature pipeline.

relflow is useful when those relationships are part of the signal:

• orders with line items;
• accounts with transactions and statements;
• users with sessions and events;
• devices with repeated measurements;
• mixed-type records where each history needs its own length and overflow rule.

Use a simpler tabular model when flattening loses no meaningful context. Read Motivation for the longer design argument and the boundaries of the approach.

What The Schema Controls

• Leaf types such as Number, Category, Set, Hash, DateParts, Text, and Vector own value encoding, loss, metrics, and prediction output.
• Branch nodes preserve repeated contexts and pool them into their parent.
• target=True, masking, and pruning decide which values are hidden and learned from context.
• embed=True selects root, branch, or leaf representations to export during prediction.
• Field names and optional queries bind raw record values to stable schema addresses.

Lightning owns the training, validation, test, and prediction loops. RelFlow owns the schema-derived model, typed tensors, losses, and output contract.

Choose Your Route

If you want to…	Start with…
Install the package and produce a first prediction	Getting Started
See how one raw record becomes tensors, losses, and output	Data Flow
Understand branches, leaves, contexts, and addresses	Model Tree
Bind ordinary or mismatched input records	Binding Data
Choose the representation for a field	Built-In Data Types
Train and evaluate a model	Training With Lightning
Interpret metrics and select a model	Evaluation And Metrics
Save, restore, or resume an artifact	Model Lifecycle
Run large offline prediction jobs	Batch Inference
Operate an online endpoint	Online Serving
Look up a familiar API quickly	AI / Expert Quickstart

Supported Workflows

The public workflow covers schema construction, in-memory and streaming data modules, Lightning training, interactive prediction, Parquet batch output, postprocessing, and optional FastAPI-backed serving. Schema mutation, dynamic masking, field importance, and field stacking are available as more advanced workflows.

Scale depends on the schema, branch lengths, vocabulary sizes, hardware, precision, data pipeline, and batch size. Each page labels its examples as runnable, excerpt, or sketch; none is a portable throughput benchmark for a production workload.

First Learning Path

Getting Started → Data Flow → Model Tree → Data Types → Binding Data → Learning Modes & Embeddings → Data Modules → Training With Lightning → Evaluation And Metrics → Model Lifecycle → Prediction Output → choose Batch Inference or Online Serving.

Community

Join the relflow Discord for questions, design discussion, and release notes.