relflow

Build and adapt foundation models for your own structured data.

Relflow is an open source model factory for typed, nested data. Describe your records and prediction targets, and it generates a custom neural architecture, trains the model, and serves predictions and learned representations.

Suppose your dataset contains purchases with line items, accounts with transaction histories, and several types of values inside each record. relflow lets you keep those relationships in the model instead of hand-designing a fixed set of aggregate features. Describe the records and the fields to predict; the schema defines the architecture. One declaration gives you field encodings, attention over related records, prediction heads, and training objectives, with growing vocabularies and reusable embeddings built in.

How it works

1. Fields represent values. Tensorfields such as Number, Category, and Text convert typed inputs into embeddings. Learned state, including numeric normalization and categorical vocabularies, stays with the model. relflow supports nearly dozen different data types, and you can build and register your own.
2. Branches build context. Branches describe arbitrarily nested records and variable-length collections. Attention combines their fields and repeated records; nested branches pass learned context toward the root.
3. Targets read that context. Each target has a decoder and a loss suited to its datatype. Decoders read context along their schema paths, so targets can live at the root or inside repeated records.

Train from data wherever it lives: stream files from disk or cloud storage, read database queries, or connect custom record generators. Use Polars when data is already in memory. PyTorch Lightning runs training. Your application prepares the observations; relflow builds their encoders, decoders, and objectives. Built-in and custom field types use the same extension protocol, so new representations and objectives plug into the model factory.

Measured results

1.18 million predictions per second on one NVIDIA A10G. In a synthetic Arrow IPC serving benchmark, a tiny, attention-free XS model processed 50.3 million rows with zero failed requests, including client encoding, HTTPS, and response decoding. The setup and three measured passes are below.

The evidence catalog adds 79 controlled learning experiments with code, comparisons, seeds, and recorded results. Examples from the recorded 0.4.2 snapshot; each version's documentation uses the evidence assets frozen for that release:

Experiment	relflow result	Control
Match IDs absent from training	0.9991 AUC with Hash	0.5000 with unknown Category labels
Recall a value by an unfamiliar ID	0.100 normalized RMSE, median of three seeds	1.401 after corrupting the lookup IDs
Distinguish nulls from zero	100% accuracy with value states preserved	50% after filling nulls with zero

These are controlled synthetic tasks. Each page includes its protocol, comparisons, limitations, and complete run report.

Recorded 2026-10-06: one NVIDIA A10G replica with 2 CPUs and 8 GiB host memory; an untrained, 3,142-parameter xs model with attention disabled and mean pooling. Each input contains four numeric/Boolean records generated from seeded Gaussian numbers and random Booleans. This measures serving throughput, not prediction quality or the default attention model.

The client sent 131,072 rows per request with four concurrent requests, Zstandard Arrow IPC, and gzip responses. Each pass completed 128 requests (16,777,216 rows). Input generation was outside the timer; Arrow validation, encoding on every request, HTTPS, and response decoding were inside it.

Pass	Rows/second	p95 request latency	Failed requests
1	1,179,732	923.3 ms	0
2	1,234,752	611.9 ms	0
3	1,122,590	749.2 ms	0

The headline is the median of these three passes.

Install

Requires Python 3.12 or newer:

uv add relflow

With pip, use python -m pip install relflow. Optional extras include relflow[text] for Hugging Face text encoders and relflow[serving] for HTTP serving.

Define a model

Suppose you have historical payment records and want to decide which new payments deserve review just after booking. Each row contains amount, merchant, and whether a dispute was reported in the following 30 days. Declare the two inputs and that observed outcome:

import relflow as rf

model = rf.Model.xs(
    amount=rf.Number,
    merchant=rf.Category,
    disputed=rf.Boolean(mask=True),
)

Keyword names match the keys in your records: amount=rf.Number reads the amount column. Use a bare class for default options, or call it to configure the field. mask=True makes disputed a supervised target: its label trains the decoder but is never included in the inputs. Mark additional fields to train multiple targets in the same model.

xs supplies architecture defaults for the root, child branches, and field decoders. The preset ladder runs from rf.Model.xs(...) through .sm(...), .md(...), .lg(...), and .xl(...); each creates a fresh, untrained model from your declared schema. Override options such as d_model, n_layers, or n_heads when needed. Use fields={...} for generated schemas or field names that collide with configuration options.

Train and predict

Stream your application's Parquet datasets from disk or cloud storage, with one payment per row. Training and validation contain amount, merchant, and the known disputed label; request rows contain the inputs and a payment_id for joining results.

data = rf.ArrowDataModule(
    train="payments/train/*.parquet",
    validate="payments/validation/*.parquet",
)
model.fit(data, batch_size=128, learning_rate=1e-4, max_epochs=30)

requests = rf.ArrowDataModule(
    predict="payments/requests/*.parquet",
    retain=("payment_id",),
)
model.predict(
    datamodule=requests,
    batch_size=256,
    callbacks=[rf.Writer("payment-predictions")],
    return_predictions=False,
)

model.save("payment.rf")
restored = rf.Model.load("payment.rf")

Datasets are scanned in Arrow batches with a bounded training shuffle buffer; the full inputs need not fit in memory. Writer streams output to payment-predictions/rank-*.parquet, and return_predictions=False avoids collecting the complete result in memory. File paths, globs, rf.source(...), and restartable batch factories are also supported. Cloud paths such as s3://your-data-bucket/payments/train/*.parquet use the same interface. SQL queries and custom record generators connect through relflow's data modules.

To collect predictions in memory, call result = model.predict(datamodule=requests, batch_size=256, devices=1). The result is an eager Polars DataFrame with nested predictions, optional representations, and retained inputs columns. Use result.to_dicts() for Python records or result.to_arrow() when integrating with Arrow consumers.

For observations already loaded into memory, pass an eager Polars DataFrame directly:

import polars as pl

requests = pl.read_parquet("payments/requests.parquet")
result = model.predict(requests, batch_size=256, retain=("payment_id",))

When training and validation frames are already in memory, use rf.PolarsDataModule(train=train_frame, validate=validation_frame) with the same model.fit(...) call. model.encode(frame) and model.write(raw_predictions, source=frame) also accept Polars frames for custom inference workflows.

fit configures AdamW, early stopping, and restoration of the best validation checkpoint. Supply hardware, logging, and other Lightning options through fit. Saved models include the schema, weights, and learned field state.

Prediction files contain a predictions.disputed record with state probabilities, content (the probability of True), and an inferred flag. Retained identifiers appear under inputs. Scan completed output lazily with pl.scan_parquet("payment-predictions/rank-*.parquet") and use Polars expressions to select the columns needed downstream.

Add nested context

To use an account's previous transactions alongside the current payment, include a history list of records in each observation and describe it with rf.Branch(...):

history_model = rf.Model.xs(
    amount=rf.Number,
    merchant=rf.Category,
    history=rf.Branch(
        length=32,
        overflow="tail",
        amount=rf.Number,
        merchant=rf.Category,
    ),
    disputed=rf.Boolean(mask=True),
)

history reads the same-named collection, and its fields read each child record's keys. With history ordered oldest to newest, this branch retains the most recent 32 records. length is a cap; shorter histories need no manual padding. Branches can nest further, and mask=True on a child field requests a prediction for each retained record.

Set embed=True on the model, a branch, or a field to export contextual embeddings under a separate representations column. This requests output; it does not add a training objective.

Pretrain, adapt, and reuse

The foundation-model workflow is to pretrain on a broad collection of your structured records using reconstruction objectives, then adapt the learned model to downstream prediction tasks. Fine-tuning updates the learned encoders and task heads. Exporting representations lets separate predictors use that context while the exporting model stays fixed.

A supervised model can also start from fresh initialization. Evaluate reuse on the intended downstream tasks and populations. See Pretraining and fine-tuning and Reusable representations.

Schema mutation can add targets or change the input tree while retaining compatible learned state. New or incompatible components initialize as the schema changes.

Extensible field types

Numbers, categories, booleans, sets, dates, text, vectors, hashes, quantiles, and latent clusters have their own representations and objectives. They use the same extension registry available to your application.

Define a custom tensorfield with rf.Extension: declare its accepted Arrow types and validated Pydantic options, then register its tensorization, embedder, decoder, loss, and output writer by rf.Component role. The shared engine handles nesting, masking, batching, and device transfer. Your datatype owns its semantics without adding special cases to the model or data loader. See Custom tensorfields for the full contract.

Serve the trained model

With relflow[serving] installed, save this module as serve_payments.py beside the payment.rf artifact produced above:

import relflow as rf

app = rf.Deployment(checkpoint="payment.rf").app()

From that directory, start the HTTP server:

uvicorn serve_payments:app --host 127.0.0.1 --port 8000

The application chooses the hosting infrastructure and can attach shared preprocessors and postprocessors. Batch prediction and HTTP serving use the saved schema and learned state. See Serving for requests, validation, and resource controls, and Performance for measuring throughput with the workload, record shape, hardware, and requested outputs stated.

Learn more

• Your first model
• Use cases
• Pretraining and fine-tuning
• Reusable representations
• Model structure and configuration
• Data types
• Arrow data loading
• Streaming batch inference
• Prediction output

Tutorials and guides live in docs/; canonical learning experiments and recorded results live in evidence/. For package development, see CONTRIBUTING.md.

Community · Apache 2.0 license

Continuous Integration

ci.yml is the entry point for PRs to main, merge groups, main pushes, and manual validation. Each run builds one package wheel and source distribution; the full Python/platform test matrix installs that same wheel. Documentation checks and complete Evidence validation run alongside the matrix. Evidence runs the full suite freshly for baseline and candidate, preserving every experiment's original seeds, budgets, and checks. CI / required rejects errors, cancellations, and missing required jobs. Evidence runs across twelve GitHub-hosted CPU shards through the pinned trusted executor, with both roles for each proof on one runner and a separate full-catalog collector. Dependency caches accelerate setup; learning results execute freshly. The candidate commit supplies the suite from this repository. See the hosted guide.

Main pushes compare against the pre-push revision. Successful main CI also publishes coverage. Version releases retain verified evidence reports and publication JSON assets in this repository before publishing the package tag. Hosted documentation reads those versioned assets; ordinary CI creates no publication commits or follow-up PRs. Nightly dependency compatibility and configured accelerator checks remain independent. Local pre-commit continues to run formatting, lint, types, and fast tests. Release publication consumes the shared distributions, verifies existing tag targets and published bytes, and repairs incomplete publication using its original checked build. It never overwrites a different published artifact. The reusable documentation workflow validates and renders the static site using its isolated environment; see the documentation guide for preview and build commands. Read the Docs builds the hosted versions and pull request previews from .readthedocs.yaml, with latest following main and verified release versions activated separately. Public pages and assets use https://www.relflow.ai/en/<version>/; the root redirects to latest. That guide describes hosted settings, Gold, and apex HTTPS forwarding.