# RelFM

relationalai.semantics.reasoners.predictive.estimators.relational.relfm

```python
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`](/api/python/v1.35/semantics/reasoners/predictive/estimators/relational/relfm/relfm_class/index.md#method-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`](/api/python/v1.35/semantics/reasoners/predictive/index.md)):

```python
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`()

```python
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`](/api/python/v1.35/semantics/frontend/base/relationship_class/index.md) 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`()

```python
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:**

- `ValueError` - If no dataset has been prepared yet (i.e. [`RelFM.predictions`](/api/python/v1.35/semantics/reasoners/predictive/estimators/relational/relfm/relfm_class/index.md#method-predictions) or
  [`RelFM.score`](/api/python/v1.35/semantics/reasoners/predictive/estimators/relational/relfm/relfm_class/index.md#method-score) has not been called).

**Examples:**

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

### .`save_dataset_diagram`()

```python
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:**

- `ValueError` - If no dataset has been prepared yet (i.e. [`RelFM.predictions`](/api/python/v1.35/semantics/reasoners/predictive/estimators/relational/relfm/relfm_class/index.md#method-predictions) or
  [`RelFM.score`](/api/python/v1.35/semantics/reasoners/predictive/estimators/relational/relfm/relfm_class/index.md#method-score) has not been called).

**Examples:**

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

### .`score`()

```python
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`](/api/python/v1.35/semantics/reasoners/predictive/estimators/relational/relfm/relfm_class/index.md#method-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`](/api/python/v1.35/semantics/reasoners/predictive/estimators/relational/relfm/relfm_class/index.md#method-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

```d2 inline layout=dagre theme=0 darkTheme=false pad=8 title="Inheritance hierarchy"
direction: down
"relationalai.semantics.reasoners.predictive.estimators.relational.relfm.RelFM": {
  label: "RelFM"
  link: "/api/python/v1.35/semantics/reasoners/predictive/estimators/relational/relfm/relfm_class"
}
"relationalai.semantics.reasoners.predictive.estimators.relational.base.PredictiveEstimator": {
  label: "PredictiveEstimator"
}
"abc.ABC": {
  label: "abc.ABC"
}
"relationalai.semantics.reasoners.predictive.estimators.relational.base.PredictiveEstimator" -> "relationalai.semantics.reasoners.predictive.estimators.relational.relfm.RelFM"
"abc.ABC" -> "relationalai.semantics.reasoners.predictive.estimators.relational.base.PredictiveEstimator"
```