> ## Documentation Index
> Fetch the complete documentation index at: https://docs.priorlabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> TabPFN-3 and later versions support up to 1,000,000 rows, subject to feature count and checkpoint/API limits.
> For large datasets, use per-estimator subsampling, e.g. inference_config={"SUBSAMPLE_SAMPLES": 100_000}, in TabPFNClassifier or TabPFNRegressor from tabpfn or tabpfn_client.
> Pass raw pandas DataFrames to fit and predict. Categorical strings/categories, raw text, and missing feature values are handled automatically; no manual integer/one-hot encoding, imputation, scaling, or outlier removal is needed.

# Predictive context

> Predictive context for TabPFN-Rel.

> [!NOTE]
>
> Looking for usage documentation? Check out [Relational predictions](https://docs.priorlabs.ai/capabilities/relational.md).

## `PredictiveContext`

[ View source ](https://github.com/PriorLabs/relarena/blob/4b74c718ba6ff9c67cf63b4beac6dadaffdd09d8/packages/relarena-core/src/relarena_core/userdb/query.py#L40)

A database and training task shared by fitted predictors.

Build the split source from a spec's database and SQL task.

```python theme={null}
PredictiveContext(
    spec: PredictiveQuerySpec,
    *,
    data_version: str | None = None,
)
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `spec` | `PredictiveQuerySpec` | Required | The database and task; the task's split cutoffs define the splits. |
| `data_version` | `str \| None` | `None` | Label for this copy of the data, recorded in run identities. |

**Raises**

`ValueError`

If the validation window ends after the last row at or
before `test_timestamp`.

***

## `PredictiveContext.from_yaml`

[ View source ](https://github.com/PriorLabs/relarena/blob/4b74c718ba6ff9c67cf63b4beac6dadaffdd09d8/packages/relarena-core/src/relarena_core/userdb/query.py#L95)

Load a database and training task from YAML.

```python theme={null}
PredictiveContext.from_yaml(
    path: str | Path,
    *,
    data_dir: str | Path | None = None,
    data_version: str | None = None,
) -> PredictiveContext
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `path` | `str \| Path` | Required | Task YAML; see `PredictiveQuerySpec.from_yaml`. |
| `data_dir` | `str \| Path \| None` | `None` | Base directory for the tables' data files. |
| `data_version` | `str \| None` | `None` | Label for this copy of the data, recorded in run identities. |

**Returns**

| Type | Description |
| - | - |
| `PredictiveContext` | — |

***

## `PredictiveContext.fit`

[ View source ](https://github.com/PriorLabs/relarena/blob/4b74c718ba6ff9c67cf63b4beac6dadaffdd09d8/packages/relarena-core/src/relarena_core/userdb/query.py#L113)

Fit a registered model and return its independent fitted state.

```python theme={null}
PredictiveContext.fit(
    model: str,
    *,
    n_trials: int = 10,
    seed: int = 0,
    cache_dir: str | Path | None = None,
) -> FittedPredictor
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `model` | `str` | Required | Registered model name, e.g. `"constant-global"` or `"tabpfn-rel-client-latest"`. |
| `n_trials` | `int` | `10` | Tuning trials on the inner split (train→val, database censored at `val_timestamp`); the best config is then refit on the outer split. A sampled space draws this many configs besides the default; a fixed grid is capped at this length. `0` fits the default config. |
| `seed` | `int` | `0` | Random seed for tuning and fitting. |
| `cache_dir` | `str \| Path \| None` | `None` | Local directory caching DFS features across tuning, the final fit and [`predict`](https://docs.priorlabs.ai/api-reference/python/relarena-core/fitted-predictor#fittedpredictor-predict). `None` uses `RELARENA_CACHE_DIR`, or no persistent cache when it is unset. |

**Returns**

| Type | Description |
| - | - |
| `FittedPredictor` | The fitted predictor, with tuning results in `trials`. |

***

## `PredictiveContext.precompute_cache`

[ View source ](https://github.com/PriorLabs/relarena/blob/4b74c718ba6ff9c67cf63b4beac6dadaffdd09d8/packages/relarena-core/src/relarena_core/userdb/query.py#L202)

Build the shared DFS feature cache on CPU; return `cache_dir`.

Featurizes exactly what [`fit`](https://docs.priorlabs.ai/api-reference/python/relarena-core/context#predictivecontext-fit) reads (the inner split for tuning, the outer
refit split), so a later `fit(model, cache_dir=...)` reads the DFS instead of
recomputing it. For a large custom database, run this on a big CPU node, then
[`fit`](https://docs.priorlabs.ai/api-reference/python/relarena-core/context#predictivecontext-fit) on the GPU. The artifacts are shared by all DFS models.

```python theme={null}
PredictiveContext.precompute_cache(
    cache_dir: str | Path,
) -> str | Path
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `cache_dir` | `str \| Path` | Required | Local directory to fill; pass the same one to [`fit`](https://docs.priorlabs.ai/api-reference/python/relarena-core/context#predictivecontext-fit). |

**Returns**

| Type | Description |
| - | - |
| `str \| Path` | — |

***

## `PredictiveContext.compute_test_labels`

[ View source ](https://github.com/PriorLabs/relarena/blob/4b74c718ba6ff9c67cf63b4beac6dadaffdd09d8/packages/relarena-core/src/relarena_core/userdb/query.py#L220)

Compute labels for the historical test windows from the full database.

Only complete test windows are returned. Rows for entities missing from the
frozen database are dropped with a warning.

```python theme={null}
PredictiveContext.compute_test_labels(
    *,
    data_end_timestamp: str | pd.Timestamp | None = None,
) -> pd.DataFrame
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `data_end_timestamp` | `str \| pd.Timestamp \| None` | `None` | Last date with complete data. `None` uses the latest timestamp in any table. |

**Returns**

| Type | Description |
| - | - |
| `pd.DataFrame` | The test rows: time, entity (original ids) and target columns. |

**Raises**

`ValueError`

If the first test window is not fully covered by the data.

***

## `PredictiveContext.group_test_entities`

[ View source ](https://github.com/PriorLabs/relarena/blob/4b74c718ba6ff9c67cf63b4beac6dadaffdd09d8/packages/relarena-core/src/relarena_core/userdb/query.py#L286)

Yield each test timestamp and its labeled entity IDs.

```python theme={null}
PredictiveContext.group_test_entities(
    labels: pd.DataFrame,
) -> Iterator[tuple[pd.Timestamp, list[Any]]]
```

**Parameters**

| Parameter | Type | Default | Description |
| - | - | - | - |
| `labels` | `pd.DataFrame` | Required | Test rows from [`compute_test_labels`](https://docs.priorlabs.ai/api-reference/python/relarena-core/context#predictivecontext-compute-test-labels). |

**Yields**

| Type | Description |
| - | - |
| `tuple[pd.Timestamp, list[Any]]` | `(timestamp, entity_ids)` pairs, ready for one [`PredictiveQuery`](https://docs.priorlabs.ai/api-reference/python/relarena-core/query#predictivequery) each. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.