Model Templates

rf.Model.from_yaml(path) builds a fresh model from a YAML architecture template. Use a template to keep the schema and its options in a reviewable configuration file, while the application supplies data and training behavior.

Define A Template

For example, payment-model.yaml defines the same payment task as Your First Model:

preset: xs
fields:
  amount:
    type: number
  merchant:
    type: category
  disputed:
    type: boolean
    mask: true

Load the file from Python:

from pathlib import Path

import relflow as rf

model = rf.Model.from_yaml(Path("payment-model.yaml"))

Each fields mapping assigns names to its children, just as Python keyword arguments do. Every child has an explicit lowercase type. Field options use the same names as their Python counterparts. Here, mask: true excludes the dispute label from input and makes it the supervised target. The root remains anonymous at rf.Address(); the target has address rf.Address("disputed").

Defaults And Overrides

The optional preset selects xs, sm, md, lg, or xl, with the same defaults as the size factories. The preset entry is file-only and accepts these five bundled names. Without a preset, supply the required d_model, n_layers, and n_heads as top-level options in the file or the Python call. For example, an explicit configuration can replace the preset entry with:

d_model: 128
n_layers: 2
n_heads: 4

Python keyword arguments override the file’s root settings:

model = rf.Model.from_yaml(
    "payment-model.yaml",
    n_layers=3,
)

The precedence is Python overrides, then explicit file options, then preset defaults. A root override applies only to the root; it does not rewrite options on child branches or leaves. Define children in the file’s fields mapping; the loader does not accept Python field overrides.

Each supplied option replaces that whole option. For example, reduction: {type: attention, n_outputs: 1} creates an attention reduction with one output and its ordinary remaining defaults. It does not recursively merge with the preset reduction. Likewise, a Python reduction=rf.Mean() replaces the reduction declared in the file.

Omitting an option allows defaults to apply. An explicit null is preserved: attention: null disables encoder attention, while reduction: null retains routed child slots. These retain the same meaning as Python None; see Branch.

Structured Options

A repeated history uses type: branch and its own child mapping. For example, add this entry under the template’s fields:

recent_transactions:
  type: branch
  length: 32
  overflow: tail
  fields:
    days_ago:
      type: number
    amount:
      type: number
    merchant:
      type: category

This reads the same structure as Add Transaction History. overflow: tail assumes records are ordered oldest to newest; the template does not sort them or join database tables.

Nested option mappings use existing configuration fields. For example, an explicit masking policy can be written as:

mask:
  rate: 0.15
  reconstruct: true

A mask may also be a list of policy mappings. Boolean and floating-point masking shorthands retain their Python meanings. See Masking And Objectives for the policies and their interactions.

Declare an Enum vocabulary with a YAML sequence:

type: enum
values: [debit_card, credit_card, bank_transfer]

The same uniqueness and scalar-type validation applies as for Enum. YAML uses PyYAML’s scalar conventions: quote strings such as "NO", "on", or "2026-09-22" when they should remain labels rather than booleans or dates. YAML aliases may reuse field definitions. Undeclared options and duplicate mapping keys are rejected, including attempts to override a key introduced by YAML merge syntax (<<).

Custom type names resolve against the live tensorfield registry. Import the application’s extension module before loading a template that uses it; the file does not import Python code. Declared extension options use the same validation as built-in fields. See Custom Tensorfields.

Architecture And Training State

A template creates a new architecture with fresh model state. It does not restore trained parameters, category vocabularies, or quantile normalization state. Use checkpoint loading to resume a trained model.

Once the application supplies a data module named data, configure optimization on model.fit(...), for example model.fit(data, batch_size=128, learning_rate=1e-4, weight_decay=0.01, max_epochs=30). Training options and schedulers belong to that call, not the YAML architecture. Data sources, preprocessors, and the training loop also remain application code; see Data Modules and Preprocessing.