Separate shared runtime and benchmark responsibilities

README.md

@@ -159,7 +159,7 @@ import pandas as pd
 
 import relarena.models  # registers the built-in models
 from relarena.evaluation import compute_leaderboard
-from relarena.registry import registry
+from relarena.core.registry import registry
 from relarena.results import summary_to_dataframe
 from relarena.runner import run_experiment
 from relarena.tasks import list_entity_tasks
@@ -246,7 +246,7 @@ preprocessing and GPU-bound training have different hardware requirements. RelAr
 permits methods to compute preprocessing artifacts once and cache them on disk before a run.
 
 Caching is not required. RelArena provides an **optional, experimental** helper API in
-[`relarena.cache`](packages/relarena/src/relarena/cache.py) for local paths, miss policies, private scratch
+[`relarena.core.cache`](packages/relarena/src/relarena/cache.py) for local paths, miss policies, private scratch
 computation, and atomic publication. A method may ignore this API and implement caching
 independently. The helper does not bring cache warming into a timed RelArena experiment;
 preprocessing scripts still run separately, so their runtime is not currently included in the

docs/adding-a-model.md

@@ -33,9 +33,9 @@ One folder may register **several** models: `dummy` → `constant-global` +
 import numpy as np
 from relbench.base import Database, EntityTask, Table
 
-from relarena.model import RelArenaModel
-from relarena.registry import register_model
-from relarena.search_space import SearchSpace
+from relarena.core.model import RelArenaModel
+from relarena.core.registry import register_model
+from relarena.core.search_space import SearchSpace
 
 MYMODEL_SPACE = SearchSpace(space=_config_space(), default_overrides={})
 
@@ -142,8 +142,8 @@ import numpy as np
 from relbench.base import EntityTask
 
 from relarena.dataset import InnerSplit, OuterSplit
-from relarena.registry import register_system
-from relarena.system import RelArenaSystem
+from relarena.core.registry import register_system
+from relarena.core.system import RelArenaSystem
 
 
 @register_system
@@ -378,7 +378,7 @@ training settings that do not affect it. Content fingerprints and explicit
 preprocessing versions can be used to invalidate artifacts when their inputs or
 meaning change.
 
-See [`relarena.cache`](../src/relarena/cache.py) for the API and its design
+See [`relarena.core.cache`](../src/relarena/cache.py) for the API and its design
 notes, and [`tests/fixtures/cached_model.py`](../tests/fixtures/cached_model.py)
 for a compact end-to-end example.
 

docs/models/kurversc.md

@@ -8,15 +8,15 @@ feature program and a CatBoost learner. It does not require or use a GPU.
 Sync RelArena's CPU dependency group and the KurveRSC extra:
 
 ```bash
-uv sync --group cpu --extra kurversc
+uv sync --all-packages --group cpu --extra kurversc
 ```
 
 ## Running KurveRSC
 
 Run one task through the ordinary RelArena CLI:
 
 ```bash
-OMP_NUM_THREADS=1 uv run --group cpu --extra kurversc relarena \
+OMP_NUM_THREADS=1 uv run --all-packages --group cpu --extra kurversc relarena \
     --model kurversc \
     --datasets rel-stack \
     --tasks user-badge \
@@ -27,7 +27,7 @@ Run all 21 RelBench v1 entity classification and regression tasks by omitting `-
 `--tasks`:
 
 ```bash
-OMP_NUM_THREADS=1 uv run --group cpu --extra kurversc relarena \
+OMP_NUM_THREADS=1 uv run --all-packages --group cpu --extra kurversc relarena \
     --model kurversc \
     --output kurversc_all_tasks.csv
 ```
@@ -52,7 +52,7 @@ The submitted configuration:
 The bounded search explores GraphReduce feature-family combinations, graph depth, and automatic
 annotation. It prunes candidates that exceed the width guard or cannot produce features for the
 task schema. The fixed values live in
-[`src/relarena/models/kurversc/model.py`](../../src/relarena/models/kurversc/model.py), so the
+[`packages/relarena/src/relarena/models/kurversc/model.py`](../../packages/relarena/src/relarena/models/kurversc/model.py), so the
 registered system name denotes one reproducible procedure without hidden configuration fields.
 Use KurveRSC's public API for ablations or alternative frame budgets.
 

docs/predictive-task.md

@@ -27,19 +27,26 @@ supervised prediction task. Two task types are supported today:
 
 A task is two YAML files: a **task file** (the label SQL, split timestamps, and what
 to predict) and a **database file** (the schema and paths to CSV or Parquet tables)
-that the task references—so one database file can back many tasks. Load and run it:
+that the task references—so one database file can back many tasks. For the hosted
+TabPFN-Rel example, install its extra and configure tabpfn-client authentication:
+
+```bash
+pip install "relarena[tabpfn-rel-api]"
+```
+
+Load and run the task:
 
 ```python
 from relarena.userdb import PredictiveQuery, PredictiveQuerySpec
 
 spec = PredictiveQuerySpec.from_yaml("task.yaml", data_dir="data/")
-preds = PredictiveQuery(spec).fit(model="tabpfn-rel-client").predict()
+preds = PredictiveQuery(spec).fit(model="tabpfn-rel-client", n_trials=0).predict()
 ```
 
 `from_yaml` reads the task file, resolves its `database:` reference (a path relative
-to the task file), and loads the database. `fit` builds the dataset, then tunes and
-fits the model on history; `predict` scores the label-less rows at the end of the
-data.
+to the task file), and loads the database. `fit` builds the dataset and fits the
+default configuration when `n_trials=0`; a positive budget enables temporal tuning.
+`predict` scores the label-less rows at the end of the data.
 
 ## Build the task in four steps
 
@@ -72,8 +79,8 @@ data.
    different `val_timestamp` and `test_timestamp` values over the same tables.
 
 The two files' shapes are defined by
-[`database.schema.json`](../src/relarena/userdb/database.schema.json) and
-[`task.schema.json`](../src/relarena/userdb/task.schema.json) — JSON Schemas with a
+[`database.schema.json`](../packages/relarena-core/src/relarena.core/userdb/database.schema.json) and
+[`task.schema.json`](../packages/relarena-core/src/relarena.core/userdb/task.schema.json) — JSON Schemas with a
 description on every field, validated on load, so a malformed file fails fast with a
 pointer to the offending field rather than an opaque error later.
 
@@ -259,7 +266,7 @@ maximum depth up to which fastdfs joins.
 the final fit, and prediction. The first RPI run fills the local store and later
 runs over the same inputs read it back. Nothing is uploaded. Omit `cache_dir` to
 fall back to `RELARENA_CACHE_DIR`, or to compute without persistent caching when
-neither is set. The underlying `relarena.cache` API is optional and experimental;
+neither is set. The underlying `relarena.core.cache` API is optional and experimental;
 models may implement caching independently.
 
 ```python
@@ -318,7 +325,7 @@ for this task as posed" rather than a verdict either way.
 
 ### Worked examples
 
-- **RelBench v1 (21 tasks)** in `src/relarena/userdb/relbench_v1/`
+- **RelBench v1 (21 tasks)** in `packages/relarena/src/relarena/userdb/relbench_v1/`
   - one folder per dataset (a shared `db.yaml` + one file per task), reproducing
   RelBench's splits byte-for-byte. `materialize_relbench("rel-f1", "data/rel-f1")`
   writes the full tables to parquet; `relbench_v1_spec(dataset, task)` loads the

docs/temporal-validation.md

@@ -81,9 +81,14 @@ database as available to every anchor. Doing so cannot reveal test labels or
 post-boundary data, and it does not recreate the alternative evaluation regime
 that advances the database to each test entity's timestamp.
 
-The implementation lives in [`dataset.py`](../src/relarena/dataset.py). The
-orchestration is in [`runner.py`](../src/relarena/runner.py) and
-[`tuner.py`](../src/relarena/tuner.py).
+Shared split construction lives in core's
+[`dataset.py`](../packages/relarena-core/src/relarena.core/dataset.py), with named
+benchmark loading in RelArena's
+[`dataset.py`](../packages/relarena/src/relarena/dataset.py). Tuning lives in core's
+[`tuner.py`](../packages/relarena-core/src/relarena.core/tuner.py); benchmark
+orchestration and final test scoring live in
+[`runner.py`](../packages/relarena/src/relarena/runner.py) and
+[`refit.py`](../packages/relarena/src/relarena/refit.py).
 
 ## Final-fit regimes
 

examples/README.md

@@ -1,7 +1,7 @@
 # RelArena examples
 
-Two runnable examples, answering two different questions. Both are run from the
-repository root.
+Run these examples from the RelArena repository root. A standalone generated-data
+example is in [`packages/tabpfn-rel`](../packages/tabpfn-rel/examples/tiny_database.py).
 
 | Example | Question it answers | Needs |
 |---|---|---|
@@ -28,13 +28,13 @@ Three files belong to this example:
 
 ```bash
 uvx kaggle datasets download -d olistbr/brazilian-ecommerce -p data/olist --unzip
-uv sync --extra tabpfn-rel-api
-uv run python -c "from tabpfn_client import init; init()"
+uv sync --all-packages --extra tabpfn-rel-api
+uv run --all-packages python -c "from tabpfn_client import init; init()"
 OMP_NUM_THREADS=1 uv run --no-sync python examples/olist_seller_churn.py
 ```
 
 That default runs through the hosted TabPFN API, so it needs no GPU. To run the
-model locally instead (needs `uv sync --extra rdblearn`, GPU recommended):
+model locally instead (needs `uv sync --all-packages --extra tabpfn-rel-local`, GPU recommended):
 
 ```bash
 OMP_NUM_THREADS=1 uv run --no-sync python examples/olist_seller_churn.py --backend local
@@ -53,18 +53,18 @@ split timestamps, and avoid leakage — see
 Fits one RelBench task (rel-f1 / driver-dnf) twice, once with no cache and once
 against a store warmed up front, and checks the predictions are identical — the
 cache only changes speed, never results. On that task it turns a roughly 409s
-fit-and-predict into roughly 12s.
+fit-and-predict into roughly 12s. Run the following commands from the repository root:
 
 ```bash
-uv run --extra rdblearn python examples/tabpfn_rel_caching.py
+uv run --all-packages --extra tabpfn-rel-local python examples/tabpfn_rel_caching.py
 ```
 
 The expensive step being cached is Deep Feature Synthesis, which runs on CPU. To
 exercise the cache path without a GPU, skip the TabPFN forward pass:
 
 ```bash
 RELARENA_EXAMPLE_SKIP_TFM=1 OMP_NUM_THREADS=1 \
-    uv run --extra rdblearn python examples/tabpfn_rel_caching.py
+    uv run --all-packages --extra tabpfn-rel-local python examples/tabpfn_rel_caching.py
 ```
 
 See the feature-cache section of the [package README](../README.md) for how to

examples/olist_seller_churn.py

@@ -24,7 +24,7 @@
 
 The default uses the hosted TabPFN API. To run the model locally instead:
 
-    uv sync --extra rdblearn
+    uv sync --extra tabpfn-rel-local
     OMP_NUM_THREADS=1 uv run --no-sync python examples/olist_seller_churn.py \
         --backend local
 """

examples/tabpfn_rel_caching.py

@@ -15,7 +15,7 @@
 
 Run (GPU recommended; the first run downloads the RelBench dataset):
 
-    uv run --extra rdblearn python examples/tabpfn_rel_caching.py
+    uv run --extra local python examples/tabpfn_rel_caching.py
 
 RELARENA_EXAMPLE_SKIP_TFM=1 runs only the DFS featurization + cache and skips the
 TabPFN forward pass, so the caching can be exercised on CPU / locally with no GPU. On
@@ -32,13 +32,14 @@
 import numpy as np
 import pandas as pd
 
-from relarena.cache import CacheConfig
-from relarena.dataset import OuterSplit, RelBenchDatasetTask, concat_tables
-from relarena.featurization import build_dfs_features
-from relarena.featurization import dfs as dfs_mod
-from relarena.featurization.warm_cache import warm_dfs_cache
-from relarena.models._shared.tfm.tfm import default_device
+from relarena.core.cache import CacheConfig
+from relarena.core.dataset import OuterSplit, concat_tables
+from relarena.core.featurization import build_dfs_features
+from relarena.core.featurization import dfs as dfs_mod
+from relarena.core.featurization.warm_cache import warm_dfs_cache
+from relarena.dataset import RelBenchDatasetTask
 from relarena.models.tabpfn_rel.model import TABPFN_REL_LOCAL_SPACE, TabPFNRelModel
+from relarena.models.tabpfn_rel.tfm import default_device
 
 #: A reasonably sized RelBench entity task: small enough to run, big enough that the
 #: DFS cost is visible. Swap for e.g. ("rel-hm", "user-churn") for a heavier one.
@@ -50,7 +51,7 @@
 DEBUG_SKIP_TFM = os.environ.get("RELARENA_EXAMPLE_SKIP_TFM", "") == "1"
 
 #: The reference TabPFN-Rel config, minus text embeddings (keeps dependencies to the
-#: `rdblearn` extra; the DFS cache is what this example is about).
+#: `local` extra; the DFS cache is what this example is about).
 CONFIG = {**TABPFN_REL_LOCAL_SPACE.default_overrides}
 
 

packages/relarena/src/relarena/__init__.py

@@ -11,31 +11,33 @@
     predictions as useful metadata for later analysis.
 """
 
-from relarena.cache import CacheConfig, CacheMiss, cache_key, cached_artifact
 from relarena.checksums import (
     database_checksum,
     split_checksums,
     table_checksum,
 )
-from relarena.dataset import InnerSplit, OuterSplit, RelBenchDatasetTask, Split
-from relarena.identity import RunIdentity
-from relarena.model import RelArenaModel
-from relarena.registry import (
+from relarena.core.cache import CacheConfig, CacheMiss, cache_key, cached_artifact
+from relarena.core.dataset import InnerSplit, OuterSplit, Split
+from relarena.core.identity import RunIdentity
+from relarena.core.model import RelArenaModel
+from relarena.core.registry import (
     MethodRegistry,
     ModelRegistry,
     register_model,
     register_system,
     registry,
 )
-from relarena.results import SystemResult, TrialResult, summary_to_dataframe
+from relarena.core.results import SystemResult, TrialResult
+from relarena.core.system import RelArenaSystem
+from relarena.core.tuner import tune
+from relarena.dataset import RelBenchDatasetTask
+from relarena.results import summary_to_dataframe
 from relarena.runner import (
     run_experiment,
     run_model_experiment,
     run_system_experiment,
 )
-from relarena.system import RelArenaSystem
 from relarena.tasks import RELBENCH_V1_DATASETS, TaskSpec, list_entity_tasks
-from relarena.tuner import tune
 
 __all__ = [
     "RELBENCH_V1_DATASETS",