Skip to content
RelationalAI Docs

RelFM

relationalai.semantics.reasoners.predictive
RelFM(
    *,
    database: Optional[str] = None,
    schema: Optional[str] = None,
    graph: Optional[Graph] = None,
    property_transformer: Optional[PropertyTransformer] = None,
    context: Optional[b.Relationship | b.Fragment | b.Chain] = None,
    validation: Optional[b.Relationship | b.Fragment | b.Chain] = None,
    source_concept: Optional[b.Concept] = None,
    task_type: Optional[str] = None,
    eval_metric: Optional[str] = None,
    use_current_time: bool = True,
    has_time_column: Optional[bool] = None,
    test_batch_size: Optional[int] = None,
    stream_logs: bool = True,
    dataset_alias: Optional[str] = None,
    parallel_reasoners_init: bool = True,
    n_estimators: int = 8,
    random_state: Optional[int] = 42,
    dfs_max_depth: int = 2,
    sample_size: Optional[int] = None,
    sampling_strategy: str = "stratified",
    device: Literal["cpu", "cuda"] = "cpu",
    clamp_min: Optional[int] = 0,
    clamp_max: Optional[int] = 100,
    regression_output: Literal["point", "distribution"] = "point",
    quantile_levels: Optional[List[float]] = None,
    norm_methods: Optional[Union[str, List[str]]] = None
)

Predict in-context with RelFM — a foundation model that requires no training.

Unlike GNN, RelFM has a single workflow: construct it with context (used directly as labeled in-context examples) and call RelFM.predictions — there is no fit(), load(), or register_model().

Parameters

  • database

    (str, default: None) - Snowflake database to save predictions in.

  • schema

    (str, default: None) - Snowflake schema to save predictions in.

  • graph

    (Graph, default: None) - The knowledge graph with edges defined. Used to pull in features from related tables via multi-hop DFS (see dfs_max_depth).

  • property_transformer

    (PropertyTransformer, default: None) - Column-level semantic type annotations. If omitted, all column types are auto-inferred.

  • context

    (Relationship or Fragment, default: None) - Labeled split used directly as in-context examples (RelFM has no training step, so this plays the role of GNN’s train split at inference time).

  • validation

    (Relationship or Fragment, default: None) - Optional validation split.

  • source_concept

    (Concept, default: None) - Source concept (inferred from context if omitted).

  • task_type

    (str, default: None) - One of "binary_classification", "multiclass_classification", or "regression". Link prediction and multilabel classification are not supported by RelFM.

  • eval_metric

    (str, default: None) - Evaluation metric compatible with the chosen task_type.

  • use_current_time

    (bool, default: True) - Use the current timestamp as the prediction time. Default is True.

  • has_time_column

    (bool, default: None) - Set to True when the task relationships use the at keyword for temporal ordering.

  • test_batch_size

    (int, default: None) - Batch size used during inference. Default is 256.

  • stream_logs

    (bool, default: True) - Stream logs to stdout. Default is True.

  • dataset_alias

    (str, default: None) - User chosen alias for the dataset.

  • parallel_reasoners_init

    (bool, default: True) - Initialize the Predictive and Logic reasoners in parallel. Default is True.

  • n_estimators

    (int, default: 8) - Ensemble size. More = better quality, slower inference. Default is 8.

  • random_state

    (int, default: 42) - Seed for ensemble generation and context sampling. Default is 42.

  • dfs_max_depth

    (int, default: 2) - How many hops across related tables to pull features from before running RelFM (1-3). Default is 2.

  • sample_size

    (int, default: None) - Max context rows sampled from context before feature generation. Default (None) uses all rows.

  • sampling_strategy

    (str, default: “stratified”) - How to draw the context sample: "stratified" (default), "most_recent", "mixed", "random", or "balanced".

  • device

    (str, default: “cpu”) - Inference device, "cpu" (default) or "cuda".

  • clamp_min

    (int, default: 0) - Min percentile clamp for regression predictions. Default is 0.

  • clamp_max

    (int, default: 100) - Max percentile clamp for regression predictions. Default is 100.

  • regression_output

    (str, default: “point”) - "point" (default) or "distribution".

  • quantile_levels

    (list of float, default: None) - Quantile levels output when regression_output="distribution".

  • norm_methods

    (str or list of str, default: None) - Feature normalization method(s).

Examples

Assuming the setup from the module-level Quick Start (relationalai.semantics.reasoners.predictive):

relfm = RelFM(
    graph=gnn_graph,
    property_transformer=property_transformer,
    source_concept=Students,
    context=Train,
    validation=Validation,
    task_type="binary_classification",
    eval_metric="roc_auc",
)
Students.predictions = relfm.predictions(domain=Test)

Methods

.predictions()

RelFM.predictions(domain: b.Relationship | b.Fragment | b.Chain) -> b.Relationship

Generate predictions on a test domain.

Materializes the context/validation splits together with the test table, submits a prediction job, and returns a Relationship that can be assigned to a concept field for downstream querying.

The prediction attributes available on the returned relationship depend on the task type:

  • Classification: .probs, .predicted_labels — same shape as GNN’s classification output.
  • Regression: .predicted_value (or, when regression_output="distribution", one column per configured quantile_levels).

Parameters:

  • domain

    (Relationship or Fragment or Chain) - The test split relationship (e.g. the Test relationship defined during data modeling).

Returns:

  • Relationship - A prediction relationship to be assigned to the source concept (e.g. User.predictions = relfm.predictions(domain=Test)).

Raises:

  • TypeError - If domain is not a Relationship, Fragment, or Chain.
  • ValueError - If the test domain schema does not match the context schema.
  • NotImplementedError - If deployments are enabled in the model configuration. Predictive reasoning is not yet supported in deployments.

.display_dataset_diagram()

RelFM.display_dataset_diagram(show_dtypes: bool = False) -> None

Display the dataset schema inline in a Jupyter notebook.

Renders a diagram of the tables, columns, and foreign-key relationships of the prepared dataset as an SVG in the current notebook cell. Requires the Graphviz dot command-line tool to be installed (brew install graphviz or apt install graphviz).

Parameters:

  • show_dtypes

    (bool, default: False) - Include column data types in the diagram. Default is False.

Raises:

Examples:

relfm.predictions(domain=Test)
relfm.display_dataset_diagram(show_dtypes=True)

.save_dataset_diagram()

RelFM.save_dataset_diagram(path: str, show_dtypes: bool = False) -> None

Save the dataset schema diagram to a file.

Writes a diagram of the tables, columns, and foreign-key relationships of the prepared dataset to path. The output format is inferred from the file extension (e.g. svg, png, pdf). Requires the Graphviz dot command-line tool to be installed (brew install graphviz or apt install graphviz).

Parameters:

  • path

    (str) - Destination file path, e.g. "schema.svg" or "schema.png".

  • show_dtypes

    (bool, default: False) - Include column data types in the diagram. Default is False.

Raises:

Examples:

relfm.predictions(domain=Test)
relfm.save_dataset_diagram("schema.svg")

.score()

RelFM.score(domain: Optional[b.Relationship | b.Fragment | b.Chain] = None) -> dict

Score RelFM against a labeled domain and return evaluation metrics.

Unlike RelFM.predictions, score() needs true labels to compare against — pass a labeled split with the same shape as context (source concept plus label column), or omit domain to score against the validation split already configured on this instance.

Runs the same DFS + ICL pipeline as RelFM.predictions, but against this split, then computes every metric available for the task type — not just the configured eval_metric — since RelFM has no training loop to justify tracking only one.

Parameters:

  • domain

    (Relationship, Fragment, or Chain, default: None) - A labeled split to score against. Defaults to the validation split passed to the constructor.

Returns:

  • dict - {"metric_name": str, "metrics": dict[str, float]} — the configured eval_metric’s name (also a key in metrics), plus every metric available for this task type.

Raises:

  • ValueError - If no domain is available (neither passed nor configured via validation= at construction), or if domain is not a Relationship, Fragment, or Chain.
  • NotImplementedError - If deployments are enabled in the model configuration.

Inheritance Hierarchy

RelFMPredictiveEstimatorabc.ABC