Predictive context

Looking for usage documentation? Check out Relational predictions.

`PredictiveContext`

A database and training task shared by fitted predictors. Build the split source from a spec’s database and SQL task.

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

Load a database and training task from YAML.

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

Fit a registered model and return its independent fitted state.

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`. `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

Build the shared DFS feature cache on CPU; return cache_dir. Featurizes exactly what 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 on the GPU. The artifacts are shared by all DFS models.

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`.

Returns

Type	Description
`str \| Path`	—

`PredictiveContext.compute_test_labels`

View source

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.

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

Yield each test timestamp and its labeled entity IDs.

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`.

Yields

Type	Description
`tuple[pd.Timestamp, list[Any]]`	`(timestamp, entity_ids)` pairs, ready for one `PredictiveQuery` each.

Reference

tabpfn

tabpfn-client

tabpfn-extensions

tabpfn-rel

REST API

`PredictiveContext`

`PredictiveContext.from_yaml`

`PredictiveContext.fit`

`PredictiveContext.precompute_cache`

`PredictiveContext.compute_test_labels`

`PredictiveContext.group_test_entities`

​PredictiveContext

​PredictiveContext.from_yaml

​PredictiveContext.fit

​PredictiveContext.precompute_cache

​PredictiveContext.compute_test_labels

​PredictiveContext.group_test_entities

`PredictiveContext`

`PredictiveContext.from_yaml`

`PredictiveContext.fit`

`PredictiveContext.precompute_cache`

`PredictiveContext.compute_test_labels`

`PredictiveContext.group_test_entities`