Text

Use Text to encode strings with a frozen Hugging Face model. relflow learns how to combine those representations with the other fields. It does not fine-tune the external encoder or generate text.

subject: Delayed transfer
messages:
  - body: The international transfer has not arrived.
    author_role: customer
  - body: The payment is awaiting review.
    author_role: agent
escalated: true

import relflow as rf

model = rf.Model(
    name="ticket", d_model=128, n_layers=3, n_heads=8,
    subject=rf.Text(max_length=64),
    messages=rf.Branch(
        length=32,
        body=rf.Text(max_length=256, encoder_pooling="mean"),
        author_role=rf.Category(size=4),
    ),
    escalated=rf.Boolean(mask=True),
)

Install the optional encoder dependency before constructing the model:

uv add "relflow[text]"

Input and options

The Arrow leaf must contain strings. An empty string is valued; a null has a separate state. Tokenization pads and truncates at max_length.

Option	Default	Meaning
model	"google/bert_uncased_L-2_H-128_A-2"	Hugging Face identifier or local model path.
max_length	128	Positive tokenization length limit.
tokenizer_batch_size	4096	Maximum strings materialized per tokenizer call.
encoder_batch_size	32	Maximum flattened text values per frozen-encoder call.
encoder_pooling	"cls"	"cls", "mean", or "pooler"; the last requires pooler_output.
objective	"l2"	Embedding reconstruction loss: "l1" or "l2".
jitter	rf.Jitter()	Training noise on the pooled frozen embedding before learned projection.

cls and mean require last_hidden_state. Text fields using the same model reuse its frozen encoder within the process. Right-padded values are grouped by length and cropped per encoder batch; left-padded values retain their full width. max_length still controls truncation and tensor storage.

Learning and output

A reconstructing mask trains the decoder against the pristine frozen embedding, using state loss and the configured content objective on valued targets. Jitter affects only visible continuous inputs, not strings, token IDs, or target embeddings. Both settings of jitter.normalize act at the same pooled-embedding boundary.

Text has no decoded public state/content payload. embed=True exports a contextual relflow embedding, distinct from the frozen encoder output; see shared leaf options. Use Vector when the source already supplies an embedding.

External model assets

The first use of a remote model identifier may download tokenizer and encoder assets. relflow checkpoints save the request and learned relflow weights, but do not bundle those external assets. Every loading or serving process must be able to resolve the same identifier or local path. For reproducible deployment, prepare a pinned encoder directory and ship it with the artifact.