structured-data-models 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sdm/__init__.py +58 -0
- sdm/_constants.py +6 -0
- sdm/_inference.py +42 -0
- sdm/_kernels/__init__.py +10 -0
- sdm/_kernels/rmsnorm_cast.py +92 -0
- sdm/_kernels/segment_multi_reduce.py +141 -0
- sdm/_kernels/triton/__init__.py +7 -0
- sdm/_kernels/triton/rmsnorm_cast.py +136 -0
- sdm/_kernels/triton/segment_multi_reduce.py +173 -0
- sdm/_memory.py +34 -0
- sdm/_warnings.py +29 -0
- sdm/cache.py +163 -0
- sdm/ensemble.py +501 -0
- sdm/evaluation/__init__.py +11 -0
- sdm/evaluation/classification.py +205 -0
- sdm/explain/__init__.py +12 -0
- sdm/explain/base.py +123 -0
- sdm/explain/gradient.py +112 -0
- sdm/models/__init__.py +20 -0
- sdm/models/_huggingface.py +58 -0
- sdm/models/base.py +966 -0
- sdm/models/callback.py +106 -0
- sdm/models/ecoc.py +197 -0
- sdm/models/kumo/__init__.py +13 -0
- sdm/models/kumo/relational/NOTICE +5 -0
- sdm/models/kumo/relational/__init__.py +11 -0
- sdm/models/kumo/relational/graph.py +101 -0
- sdm/models/kumo/relational/invariant_gnn.py +122 -0
- sdm/models/kumo/relational/model.py +602 -0
- sdm/models/kumo/relational/recipe.py +18 -0
- sdm/models/kumo/relational/task.py +113 -0
- sdm/models/kumo/tabular/__init__.py +17 -0
- sdm/models/kumo/tabular/batching.py +139 -0
- sdm/models/kumo/tabular/block.py +100 -0
- sdm/models/kumo/tabular/cell_embedding.py +85 -0
- sdm/models/kumo/tabular/icl.py +136 -0
- sdm/models/kumo/tabular/model.py +299 -0
- sdm/models/kumo/tabular/recipe.py +71 -0
- sdm/models/kumo/tabular/row_embedding.py +214 -0
- sdm/models/tabfm/LICENSE +209 -0
- sdm/models/tabfm/__init__.py +11 -0
- sdm/models/tabfm/block.py +94 -0
- sdm/models/tabfm/cell_embedding.py +219 -0
- sdm/models/tabfm/ckpt.py +242 -0
- sdm/models/tabfm/icl.py +107 -0
- sdm/models/tabfm/model.py +261 -0
- sdm/models/tabfm/recipe.py +46 -0
- sdm/models/tabfm/row_embedding.py +241 -0
- sdm/models/tabiclv2/LICENSE +33 -0
- sdm/models/tabiclv2/__init__.py +11 -0
- sdm/models/tabiclv2/block.py +81 -0
- sdm/models/tabiclv2/ckpt.py +134 -0
- sdm/models/tabiclv2/icl.py +420 -0
- sdm/models/tabiclv2/model.py +293 -0
- sdm/models/tabiclv2/recipe.py +46 -0
- sdm/models/tabiclv2/row_embedding.py +254 -0
- sdm/nn/__init__.py +28 -0
- sdm/nn/_buffer.py +91 -0
- sdm/nn/attention.py +825 -0
- sdm/nn/glu.py +78 -0
- sdm/nn/linear.py +46 -0
- sdm/nn/rms_norm.py +59 -0
- sdm/nn/rope.py +107 -0
- sdm/nn/scaling.py +240 -0
- sdm/nn/set_transformer.py +162 -0
- sdm/nn/softplus.py +65 -0
- sdm/processing/__init__.py +96 -0
- sdm/processing/base.py +254 -0
- sdm/processing/categorical/__init__.py +16 -0
- sdm/processing/categorical/_categorical.py +60 -0
- sdm/processing/categorical/align.py +540 -0
- sdm/processing/categorical/count.py +121 -0
- sdm/processing/categorical/impute.py +107 -0
- sdm/processing/categorical/shuffle.py +204 -0
- sdm/processing/common/__init__.py +32 -0
- sdm/processing/common/callable.py +29 -0
- sdm/processing/common/choice.py +185 -0
- sdm/processing/common/drop.py +28 -0
- sdm/processing/common/ensemble.py +187 -0
- sdm/processing/common/identity.py +18 -0
- sdm/processing/common/select.py +107 -0
- sdm/processing/common/sequential.py +158 -0
- sdm/processing/common/shuffle.py +195 -0
- sdm/processing/common/stype.py +199 -0
- sdm/processing/common/table.py +120 -0
- sdm/processing/common/task.py +135 -0
- sdm/processing/common/to_numerical.py +60 -0
- sdm/processing/datetime/__init__.py +8 -0
- sdm/processing/datetime/calendar.py +196 -0
- sdm/processing/ensemble.py +203 -0
- sdm/processing/execution.py +418 -0
- sdm/processing/numerical/__init__.py +38 -0
- sdm/processing/numerical/_stats.py +29 -0
- sdm/processing/numerical/cast.py +33 -0
- sdm/processing/numerical/clip.py +48 -0
- sdm/processing/numerical/clip_soft.py +54 -0
- sdm/processing/numerical/constant.py +235 -0
- sdm/processing/numerical/flip_sign.py +78 -0
- sdm/processing/numerical/impute.py +52 -0
- sdm/processing/numerical/pca.py +62 -0
- sdm/processing/numerical/power.py +325 -0
- sdm/processing/numerical/quantile.py +306 -0
- sdm/processing/numerical/quantile_clip.py +63 -0
- sdm/processing/numerical/random_projection.py +86 -0
- sdm/processing/numerical/rank_gaussian.py +168 -0
- sdm/processing/numerical/robust_scale.py +88 -0
- sdm/processing/numerical/sigma_clip.py +123 -0
- sdm/processing/numerical/standardize.py +71 -0
- sdm/processing/output/__init__.py +14 -0
- sdm/processing/output/reduce.py +86 -0
- sdm/processing/output/softmax.py +48 -0
- sdm/processing/output/sort.py +16 -0
- sdm/processing/recipe.py +154 -0
- sdm/processing/text/__init__.py +12 -0
- sdm/processing/text/sentence_transformer.py +451 -0
- sdm/processing/text/tfidf.py +478 -0
- sdm/relational/__init__.py +16 -0
- sdm/relational/backend/__init__.py +12 -0
- sdm/relational/backend/_cugraph.py +546 -0
- sdm/relational/backend/_pyg_lib.py +175 -0
- sdm/relational/data.py +393 -0
- sdm/relational/join.py +173 -0
- sdm/relational/sampler.py +259 -0
- sdm/relational/task.py +465 -0
- sdm/stype.py +396 -0
- sdm/task.py +53 -0
- sdm/tensor/__init__.py +20 -0
- sdm/tensor/categorical.py +953 -0
- sdm/tensor/columnar.py +1127 -0
- sdm/tensor/io/__init__.py +22 -0
- sdm/tensor/io/arrow.py +120 -0
- sdm/tensor/io/cudf.py +47 -0
- sdm/tensor/mixin.py +124 -0
- sdm/tensor/nullable.py +963 -0
- sdm/tensor/string.py +526 -0
- sdm/tensor/table.py +2035 -0
- sdm/tensor/var_len.py +1486 -0
- sdm/testing/__init__.py +14 -0
- sdm/testing/decorators.py +61 -0
- sdm/testing/memory.py +92 -0
- structured_data_models-0.2.0.dist-info/METADATA +142 -0
- structured_data_models-0.2.0.dist-info/RECORD +152 -0
- structured_data_models-0.2.0.dist-info/WHEEL +5 -0
- structured_data_models-0.2.0.dist-info/licenses/LICENSE +204 -0
- structured_data_models-0.2.0.dist-info/licenses/THIRD_PARTY_LICENSES.md +40 -0
- structured_data_models-0.2.0.dist-info/licenses/sdm/models/kumo/relational/NOTICE +5 -0
- structured_data_models-0.2.0.dist-info/licenses/sdm/models/tabfm/LICENSE +209 -0
- structured_data_models-0.2.0.dist-info/licenses/sdm/models/tabiclv2/LICENSE +33 -0
- structured_data_models-0.2.0.dist-info/licenses/third_party/contributor-covenant/LICENSE +20 -0
- structured_data_models-0.2.0.dist-info/licenses/third_party/pytorch/LICENSE +84 -0
- structured_data_models-0.2.0.dist-info/licenses/third_party/tabpfn-extensions/LICENSE +202 -0
- structured_data_models-0.2.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,602 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
# ruff: noqa: D205
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
from collections.abc import Iterable, Sequence
|
|
8
|
+
from typing import Any, ClassVar, cast
|
|
9
|
+
|
|
10
|
+
import torch
|
|
11
|
+
from torch import Tensor
|
|
12
|
+
from torch.nn import ModuleDict
|
|
13
|
+
|
|
14
|
+
from sdm import (
|
|
15
|
+
NaT,
|
|
16
|
+
RelatedTables,
|
|
17
|
+
Relationship,
|
|
18
|
+
Stype,
|
|
19
|
+
TableTensor,
|
|
20
|
+
Task,
|
|
21
|
+
TaskLike,
|
|
22
|
+
)
|
|
23
|
+
from sdm.cache import Cache
|
|
24
|
+
from sdm.models import ICLModel
|
|
25
|
+
from sdm.models._huggingface import download_checkpoint
|
|
26
|
+
from sdm.models.kumo.relational.invariant_gnn import InvariantGNN
|
|
27
|
+
from sdm.models.kumo.relational.recipe import default_recipe
|
|
28
|
+
from sdm.models.kumo.relational.task import TaskGraph
|
|
29
|
+
from sdm.models.tabiclv2.icl import ICLBlock
|
|
30
|
+
from sdm.models.tabiclv2.row_embedding import RowEmbedding
|
|
31
|
+
from sdm.processing import Recipe, Standardize
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class KumoRelational(ICLModel):
|
|
35
|
+
r"""An adapted version of the relational foundation model
|
|
36
|
+
from the `"KumoRFM-2: Scaling Foundation Models for Relational Learning"
|
|
37
|
+
<https://arxiv.org/abs/2604.12596>`_ paper.
|
|
38
|
+
|
|
39
|
+
.. figure:: /images/kumo_relational_light.svg
|
|
40
|
+
:figclass: light-only
|
|
41
|
+
:width: 100%
|
|
42
|
+
|
|
43
|
+
.. figure:: /images/kumo_relational_dark.svg
|
|
44
|
+
:figclass: dark-only
|
|
45
|
+
:width: 100%
|
|
46
|
+
|
|
47
|
+
:class:`KumoRelational` extends the in-context learning structure of
|
|
48
|
+
tabular foundation models from single tables to relational, multi-table
|
|
49
|
+
inputs.
|
|
50
|
+
It processes task rows together with one or more related tables, avoiding
|
|
51
|
+
manual flattening of relational data into a single table.
|
|
52
|
+
|
|
53
|
+
This implementation follows the high-level KumoRFM-2 architecture.
|
|
54
|
+
It consists of three stages:
|
|
55
|
+
|
|
56
|
+
* **Intra-table row embeddings:** Each related table is embedded
|
|
57
|
+
independently with a :class:`TabICLv2`-style row embedding stack.
|
|
58
|
+
Target information is injected by distributing context targets over the
|
|
59
|
+
relational graph.
|
|
60
|
+
* **Inter-table message passing:** A schema-agnostic GNN exchanges the row
|
|
61
|
+
embeddings along pre-defined relationships for ``num_hops`` rounds,
|
|
62
|
+
before it reads out the rows linked to the task table.
|
|
63
|
+
* **In-context learning over samples:** The readout embeddings for context
|
|
64
|
+
and query task rows are processed by a :class:`TabICLv2`-style
|
|
65
|
+
dataset-level ICL block.
|
|
66
|
+
Context rows carry target information, while query rows attend to the
|
|
67
|
+
labeled context to produce class logits or regression quantiles.
|
|
68
|
+
|
|
69
|
+
.. testcode::
|
|
70
|
+
|
|
71
|
+
from sdm import RelatedTables, TableTensor
|
|
72
|
+
from sdm.models import KumoRelational
|
|
73
|
+
|
|
74
|
+
task_table = TableTensor.from_columns(
|
|
75
|
+
{"user_id": [0, 1, 2, 3], "churn": [True, False, True, False]},
|
|
76
|
+
stypes={"user_id": "id", "churn": "categorical"},
|
|
77
|
+
device="cuda",
|
|
78
|
+
)
|
|
79
|
+
|
|
80
|
+
related_tables = RelatedTables(
|
|
81
|
+
tables={
|
|
82
|
+
"users": TableTensor.from_columns(
|
|
83
|
+
{"user_id": [0, 1, 2, 3], "age": [42, 23, 31, 26]},
|
|
84
|
+
stypes={"user_id": "id", "age": "numerical"},
|
|
85
|
+
device="cuda",
|
|
86
|
+
),
|
|
87
|
+
"orders": TableTensor.from_columns(
|
|
88
|
+
{
|
|
89
|
+
"user_id": [0, 0, 1, 3, 3, 3],
|
|
90
|
+
"amount": [9.99, 4.99, 12.99, 7.99, 3.99, 5.99],
|
|
91
|
+
},
|
|
92
|
+
stypes={"user_id": "id", "amount": "numerical"},
|
|
93
|
+
device="cuda",
|
|
94
|
+
),
|
|
95
|
+
},
|
|
96
|
+
relationships=[{
|
|
97
|
+
"left_table": "orders",
|
|
98
|
+
"left_columns": "user_id",
|
|
99
|
+
"right_table": "users",
|
|
100
|
+
"right_columns": "user_id",
|
|
101
|
+
}],
|
|
102
|
+
task_links=[{
|
|
103
|
+
"task_columns": "user_id",
|
|
104
|
+
"table": "users",
|
|
105
|
+
"table_columns": "user_id",
|
|
106
|
+
}],
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
x_context = task_table[:2].drop_columns("churn")
|
|
110
|
+
y_context = task_table[:2, "churn"]
|
|
111
|
+
x_query = task_table[2:].drop_columns("churn")
|
|
112
|
+
|
|
113
|
+
related_context_tables = related_tables.replace_tables({
|
|
114
|
+
"users": related_tables.tables["users"][:2],
|
|
115
|
+
"orders": related_tables.tables["orders"][:3],
|
|
116
|
+
})
|
|
117
|
+
related_query_tables = related_tables.replace_tables({
|
|
118
|
+
"users": related_tables.tables["users"][2:],
|
|
119
|
+
"orders": related_tables.tables["orders"][3:],
|
|
120
|
+
})
|
|
121
|
+
|
|
122
|
+
model = KumoRelational(device="cuda")
|
|
123
|
+
|
|
124
|
+
# Default in-context learning forward pass:
|
|
125
|
+
out = model(
|
|
126
|
+
x_context=x_context,
|
|
127
|
+
y_context=y_context,
|
|
128
|
+
x_query=x_query,
|
|
129
|
+
related_context_tables=related_context_tables,
|
|
130
|
+
related_query_tables=related_query_tables,
|
|
131
|
+
num_hops=1,
|
|
132
|
+
)
|
|
133
|
+
|
|
134
|
+
# Fit+Predict forward pass via key/value caching:
|
|
135
|
+
model.fit(x_context, y_context, related_context_tables, num_hops=1)
|
|
136
|
+
out = model.predict(x_query, related_query_tables)
|
|
137
|
+
|
|
138
|
+
Args:
|
|
139
|
+
task: The tasks to initialize. If ``None``, all tasks supported by this
|
|
140
|
+
model are initialized.
|
|
141
|
+
pretrained: Whether to load the pretrained checkpoint.
|
|
142
|
+
device: The device.
|
|
143
|
+
"""
|
|
144
|
+
|
|
145
|
+
supported_feature_stypes: ClassVar[frozenset[Stype]] = frozenset(
|
|
146
|
+
{Stype.numerical, Stype.datetime}
|
|
147
|
+
)
|
|
148
|
+
supported_target_stypes: ClassVar[frozenset[Stype]] = frozenset(
|
|
149
|
+
{Stype.numerical, Stype.categorical}
|
|
150
|
+
)
|
|
151
|
+
supports_multi_target: ClassVar[bool] = False
|
|
152
|
+
supports_related_tables: ClassVar[bool] = True
|
|
153
|
+
|
|
154
|
+
def __init__(
|
|
155
|
+
self,
|
|
156
|
+
task: TaskLike | Iterable[TaskLike] | None = None,
|
|
157
|
+
pretrained: bool = True,
|
|
158
|
+
device: torch.device | str | None = None,
|
|
159
|
+
) -> None:
|
|
160
|
+
super().__init__(task=task)
|
|
161
|
+
|
|
162
|
+
self.models: ModuleDict[TaskLike, torch.nn.Module] = ModuleDict()
|
|
163
|
+
for task in self.tasks:
|
|
164
|
+
self.models[task] = _KumoRelational(
|
|
165
|
+
num_classes=10 if task == Task.classification else 0,
|
|
166
|
+
num_quantiles=999 if task == Task.regression else 0,
|
|
167
|
+
norm_bias=task == Task.classification,
|
|
168
|
+
device="meta" if pretrained else device,
|
|
169
|
+
)
|
|
170
|
+
|
|
171
|
+
if pretrained:
|
|
172
|
+
self._load_from_pretrained(device=device)
|
|
173
|
+
|
|
174
|
+
self.eval()
|
|
175
|
+
|
|
176
|
+
def _load_from_pretrained(
|
|
177
|
+
self,
|
|
178
|
+
device: torch.device | str | None,
|
|
179
|
+
) -> KumoRelational:
|
|
180
|
+
device = torch.get_default_device() if device is None else device
|
|
181
|
+
|
|
182
|
+
for task, model in self.models.items():
|
|
183
|
+
if task == Task.classification:
|
|
184
|
+
filename = "classifier.pt"
|
|
185
|
+
else:
|
|
186
|
+
assert task == Task.regression
|
|
187
|
+
filename = "regressor.pt"
|
|
188
|
+
|
|
189
|
+
path = download_checkpoint(
|
|
190
|
+
repo_id="nvidia/Kumo-Relational",
|
|
191
|
+
filename=filename,
|
|
192
|
+
revision="v1.0.1",
|
|
193
|
+
config_filename="config.json",
|
|
194
|
+
)
|
|
195
|
+
ckpt = torch.load(path, map_location=device, weights_only=True)
|
|
196
|
+
model.load_state_dict(ckpt, assign=True)
|
|
197
|
+
|
|
198
|
+
return self
|
|
199
|
+
|
|
200
|
+
def _forward(
|
|
201
|
+
self,
|
|
202
|
+
x_context: TableTensor | None, # [..., R_context, D]
|
|
203
|
+
y_context: TableTensor | None, # [..., R_context, 1]
|
|
204
|
+
x_query: TableTensor | None, # [..., R_query, D]
|
|
205
|
+
related_context_tables: RelatedTables[TableTensor] | None,
|
|
206
|
+
related_query_tables: RelatedTables[TableTensor] | None,
|
|
207
|
+
cache: Cache | None,
|
|
208
|
+
generator: torch.Generator | None,
|
|
209
|
+
**kwargs: Any,
|
|
210
|
+
) -> TableTensor: # [..., R_query, *]
|
|
211
|
+
|
|
212
|
+
classes: Tensor | None = None
|
|
213
|
+
if y_context is not None and y_context.categorical.size(-1) > 0:
|
|
214
|
+
classes = y_context.categorical.categories[0]
|
|
215
|
+
elif cache is not None:
|
|
216
|
+
classes = cast(Tensor | None, cache["classes"])
|
|
217
|
+
|
|
218
|
+
task = Task.classification if classes is not None else Task.regression
|
|
219
|
+
out = self.models[task](
|
|
220
|
+
x_context=x_context,
|
|
221
|
+
y_context=y_context,
|
|
222
|
+
x_query=x_query,
|
|
223
|
+
related_context_tables=related_context_tables,
|
|
224
|
+
related_query_tables=related_query_tables,
|
|
225
|
+
cache=cache,
|
|
226
|
+
generator=generator,
|
|
227
|
+
num_hops=kwargs.get("num_hops"),
|
|
228
|
+
)
|
|
229
|
+
|
|
230
|
+
if classes is None:
|
|
231
|
+
return TableTensor(
|
|
232
|
+
columns={
|
|
233
|
+
Stype.numerical: [f"q{i:03d}" for i in range(1, 1000)]
|
|
234
|
+
},
|
|
235
|
+
numerical=out,
|
|
236
|
+
)
|
|
237
|
+
|
|
238
|
+
return TableTensor(
|
|
239
|
+
columns={Stype.numerical: [str(i) for i in classes.tolist()]},
|
|
240
|
+
numerical=out[..., : len(classes)],
|
|
241
|
+
)
|
|
242
|
+
|
|
243
|
+
@classmethod
|
|
244
|
+
def default_recipe(cls) -> Recipe:
|
|
245
|
+
r""":meta private:""" # noqa: D415
|
|
246
|
+
return default_recipe()
|
|
247
|
+
|
|
248
|
+
|
|
249
|
+
class _KumoRelational(torch.nn.Module):
|
|
250
|
+
def __init__(
|
|
251
|
+
self,
|
|
252
|
+
num_classes: int,
|
|
253
|
+
num_quantiles: int,
|
|
254
|
+
channels: int = 128,
|
|
255
|
+
num_embedding_layers: int = 3,
|
|
256
|
+
num_embedding_heads: int = 8,
|
|
257
|
+
num_inducing_points: int = 128,
|
|
258
|
+
group_size: int = 3,
|
|
259
|
+
num_readout_tokens: int = 4,
|
|
260
|
+
num_icl_layers: int = 12,
|
|
261
|
+
num_icl_heads: int = 8,
|
|
262
|
+
norm_bias: bool = True,
|
|
263
|
+
max_train_size: int = 20_000,
|
|
264
|
+
device: torch.device | str | None = None,
|
|
265
|
+
dtype: torch.dtype | None = None,
|
|
266
|
+
) -> None:
|
|
267
|
+
super().__init__()
|
|
268
|
+
factory_kwargs: dict[str, Any] = {"device": device, "dtype": dtype}
|
|
269
|
+
|
|
270
|
+
self.max_train_size = max_train_size
|
|
271
|
+
|
|
272
|
+
self.row_embedding = RowEmbedding(
|
|
273
|
+
num_classes=num_classes,
|
|
274
|
+
channels=channels,
|
|
275
|
+
num_layers=num_embedding_layers,
|
|
276
|
+
num_heads=num_embedding_heads,
|
|
277
|
+
group_size=group_size,
|
|
278
|
+
num_inducing_points=num_inducing_points,
|
|
279
|
+
num_readout_tokens=num_readout_tokens,
|
|
280
|
+
norm_bias=norm_bias,
|
|
281
|
+
**factory_kwargs,
|
|
282
|
+
)
|
|
283
|
+
self.gnn = InvariantGNN(
|
|
284
|
+
channels=num_readout_tokens * channels,
|
|
285
|
+
**factory_kwargs,
|
|
286
|
+
)
|
|
287
|
+
self.icl_block = ICLBlock(
|
|
288
|
+
num_classes=num_classes,
|
|
289
|
+
out_channels=num_classes or num_quantiles,
|
|
290
|
+
channels=num_readout_tokens * channels,
|
|
291
|
+
num_layers=num_icl_layers,
|
|
292
|
+
num_heads=num_icl_heads,
|
|
293
|
+
norm_bias=norm_bias,
|
|
294
|
+
temperature=0.9,
|
|
295
|
+
**factory_kwargs,
|
|
296
|
+
)
|
|
297
|
+
|
|
298
|
+
def forward(
|
|
299
|
+
self,
|
|
300
|
+
x_context: TableTensor | None, # [..., R_context, D]
|
|
301
|
+
y_context: TableTensor | None, # [..., R_context, 1]
|
|
302
|
+
x_query: TableTensor | None, # [..., R_query, D]
|
|
303
|
+
related_context_tables: RelatedTables[TableTensor] | None,
|
|
304
|
+
related_query_tables: RelatedTables[TableTensor] | None,
|
|
305
|
+
*,
|
|
306
|
+
cache: Cache | None = None,
|
|
307
|
+
generator: torch.Generator | None = None,
|
|
308
|
+
num_hops: int | None = None,
|
|
309
|
+
) -> Tensor: # [..., R_query, *]
|
|
310
|
+
|
|
311
|
+
num_classes: int | None = None # Extract `y` as tensor:
|
|
312
|
+
if y_context is not None and y_context.categorical.size(-1) > 0:
|
|
313
|
+
y = y_context.categorical.code.squeeze(-1)
|
|
314
|
+
num_classes = len(y_context.categorical.categories[0])
|
|
315
|
+
elif y_context is not None and y_context.numerical.size(-1) > 0:
|
|
316
|
+
y = y_context.numerical.squeeze(-1)
|
|
317
|
+
else:
|
|
318
|
+
assert cache is not None
|
|
319
|
+
if isinstance(cache["classes"], Tensor):
|
|
320
|
+
num_classes = len(cache["classes"])
|
|
321
|
+
y = torch.empty(
|
|
322
|
+
(0,), # NOTE Guaranteed to be 1D for now.
|
|
323
|
+
dtype=torch.float32 if num_classes is None else torch.int64,
|
|
324
|
+
device=next(self.parameters()).device,
|
|
325
|
+
)
|
|
326
|
+
|
|
327
|
+
context: TaskGraph | None = None
|
|
328
|
+
if x_context is not None:
|
|
329
|
+
if related_context_tables is None:
|
|
330
|
+
raise ValueError(
|
|
331
|
+
f"{self.__class__.__name__!r} requires related tables"
|
|
332
|
+
)
|
|
333
|
+
context = TaskGraph.from_input(
|
|
334
|
+
x=x_context,
|
|
335
|
+
related_tables=related_context_tables,
|
|
336
|
+
num_hops=num_hops,
|
|
337
|
+
)
|
|
338
|
+
if cache is not None and cache.is_recording:
|
|
339
|
+
cache["relationships"] = context.related_tables.relationships
|
|
340
|
+
cache["num_hops"] = context.num_hops
|
|
341
|
+
|
|
342
|
+
query: TaskGraph | None = None
|
|
343
|
+
if x_query is not None:
|
|
344
|
+
if related_query_tables is None:
|
|
345
|
+
raise ValueError(
|
|
346
|
+
f"{self.__class__.__name__!r} requires related tables"
|
|
347
|
+
)
|
|
348
|
+
if context is not None:
|
|
349
|
+
relationships = context.related_tables.relationships
|
|
350
|
+
num_hops = context.num_hops
|
|
351
|
+
else:
|
|
352
|
+
assert cache is not None
|
|
353
|
+
assert cache.is_replaying
|
|
354
|
+
relationships = cast(
|
|
355
|
+
Sequence[Relationship], cache["relationships"]
|
|
356
|
+
)
|
|
357
|
+
num_hops = cast(int, cache["num_hops"])
|
|
358
|
+
query = TaskGraph.from_input(
|
|
359
|
+
x=x_query,
|
|
360
|
+
related_tables=RelatedTables(
|
|
361
|
+
tables=related_query_tables.tables,
|
|
362
|
+
relationships=relationships,
|
|
363
|
+
task_links=related_query_tables.task_links,
|
|
364
|
+
),
|
|
365
|
+
num_hops=num_hops,
|
|
366
|
+
)
|
|
367
|
+
|
|
368
|
+
# TODO Inject random heterogeneous GNN.
|
|
369
|
+
|
|
370
|
+
# Reason within each Table ############################################
|
|
371
|
+
if context is not None:
|
|
372
|
+
table_names = list(context.related_tables.tables)
|
|
373
|
+
readout_table = context.readout_table
|
|
374
|
+
else:
|
|
375
|
+
assert query is not None
|
|
376
|
+
table_names = list(query.related_tables.tables)
|
|
377
|
+
readout_table = query.readout_table
|
|
378
|
+
|
|
379
|
+
xs_context: dict[str, Tensor] = {}
|
|
380
|
+
xs_query: dict[str, Tensor] = {}
|
|
381
|
+
for name in table_names:
|
|
382
|
+
standardizer = Standardize() # Relative time standardization.
|
|
383
|
+
x_context_i = context_task_row_i = None
|
|
384
|
+
if context is not None:
|
|
385
|
+
assert x_context is not None
|
|
386
|
+
x_context_i = context.related_tables.tables[name].numerical
|
|
387
|
+
context_task_row_i = context.task_row_by_table[name]
|
|
388
|
+
if name == readout_table: # Inject task features:
|
|
389
|
+
x_context_i = self._inject_task(
|
|
390
|
+
x=x_context_i,
|
|
391
|
+
task=x_context.numerical,
|
|
392
|
+
readout_index=context.readout_index,
|
|
393
|
+
)
|
|
394
|
+
if cache is not None and cache.is_recording:
|
|
395
|
+
cache[f"table_{name}.standardizer"] = standardizer
|
|
396
|
+
rel_time_i = self._get_rel_time( # Inject relative time:
|
|
397
|
+
datetime=context.related_tables.tables[name].datetime,
|
|
398
|
+
seed_datetime=x_context.datetime,
|
|
399
|
+
task_row=context_task_row_i,
|
|
400
|
+
standardizer=standardizer,
|
|
401
|
+
)
|
|
402
|
+
if rel_time_i is not None:
|
|
403
|
+
rel_time_i = rel_time_i.to(x_context_i.dtype)
|
|
404
|
+
x_context_i = torch.cat([x_context_i, rel_time_i], dim=-1)
|
|
405
|
+
|
|
406
|
+
x_query_i = None
|
|
407
|
+
if query is not None and name in query.related_tables.tables:
|
|
408
|
+
assert x_query is not None
|
|
409
|
+
x_query_i = query.related_tables.tables[name].numerical
|
|
410
|
+
query_task_row_i = query.task_row_by_table[name]
|
|
411
|
+
if name == readout_table: # Inject task features:
|
|
412
|
+
x_query_i = self._inject_task(
|
|
413
|
+
x=x_query_i,
|
|
414
|
+
task=x_query.numerical,
|
|
415
|
+
readout_index=query.readout_index,
|
|
416
|
+
)
|
|
417
|
+
rel_time_i = self._get_rel_time( # Inject relative time:
|
|
418
|
+
datetime=query.related_tables.tables[name].datetime,
|
|
419
|
+
seed_datetime=x_query.datetime,
|
|
420
|
+
task_row=query_task_row_i,
|
|
421
|
+
standardizer=cast(
|
|
422
|
+
Standardize, cache[f"table_{name}.standardizer"]
|
|
423
|
+
)
|
|
424
|
+
if cache is not None and cache.is_replaying
|
|
425
|
+
else standardizer,
|
|
426
|
+
)
|
|
427
|
+
if rel_time_i is not None:
|
|
428
|
+
rel_time_i = rel_time_i.to(x_query_i.dtype)
|
|
429
|
+
x_query_i = torch.cat([x_query_i, rel_time_i], dim=-1)
|
|
430
|
+
|
|
431
|
+
xs_context[name], xs_query[name] = self._embed_table(
|
|
432
|
+
x_context=x_context_i,
|
|
433
|
+
x_query=x_query_i,
|
|
434
|
+
y=y,
|
|
435
|
+
task_row=context_task_row_i,
|
|
436
|
+
num_classes=num_classes,
|
|
437
|
+
cache_key=f"table_{name}",
|
|
438
|
+
cache=cache,
|
|
439
|
+
generator=generator,
|
|
440
|
+
)
|
|
441
|
+
|
|
442
|
+
# Inter-Message Passing ###############################################
|
|
443
|
+
gnn_cache = cache or Cache()
|
|
444
|
+
if context is not None:
|
|
445
|
+
x_context: Tensor = torch.cat(
|
|
446
|
+
[xs_context[name] for name in context.related_tables.tables],
|
|
447
|
+
dim=-2,
|
|
448
|
+
)
|
|
449
|
+
del xs_context
|
|
450
|
+
x_context = self.gnn(
|
|
451
|
+
x=x_context,
|
|
452
|
+
graph=context.graph,
|
|
453
|
+
readout_table=context.readout_table,
|
|
454
|
+
readout_index=context.readout_index,
|
|
455
|
+
num_hops=context.num_hops,
|
|
456
|
+
cache=gnn_cache,
|
|
457
|
+
generator=generator,
|
|
458
|
+
)
|
|
459
|
+
|
|
460
|
+
if query is not None:
|
|
461
|
+
x_query: Tensor = torch.cat(
|
|
462
|
+
[xs_query[name] for name in query.related_tables.tables],
|
|
463
|
+
dim=-2,
|
|
464
|
+
)
|
|
465
|
+
del xs_query
|
|
466
|
+
x_query = self.gnn(
|
|
467
|
+
x=x_query,
|
|
468
|
+
graph=query.graph,
|
|
469
|
+
readout_table=query.readout_table,
|
|
470
|
+
readout_index=query.readout_index,
|
|
471
|
+
num_hops=query.num_hops,
|
|
472
|
+
cache=gnn_cache.freeze() if cache is None else cache,
|
|
473
|
+
)
|
|
474
|
+
|
|
475
|
+
# Reason across Tables ################################################
|
|
476
|
+
if x_query is None and x_context is not None:
|
|
477
|
+
x = x_context
|
|
478
|
+
elif x_context is None and x_query is not None:
|
|
479
|
+
x = x_query
|
|
480
|
+
else:
|
|
481
|
+
assert x_context is not None
|
|
482
|
+
assert x_query is not None
|
|
483
|
+
x = torch.cat([x_context, x_query], dim=-2)
|
|
484
|
+
del x_context, x_query
|
|
485
|
+
return self.icl_block(
|
|
486
|
+
x=x,
|
|
487
|
+
y=y,
|
|
488
|
+
num_classes=num_classes,
|
|
489
|
+
cache=cache,
|
|
490
|
+
)
|
|
491
|
+
|
|
492
|
+
def _embed_table(
|
|
493
|
+
self,
|
|
494
|
+
x_context: Tensor | None,
|
|
495
|
+
x_query: Tensor | None,
|
|
496
|
+
y: Tensor,
|
|
497
|
+
task_row: Tensor | None,
|
|
498
|
+
num_classes: int | None,
|
|
499
|
+
cache_key: str,
|
|
500
|
+
cache: Cache | None,
|
|
501
|
+
generator: torch.Generator | None,
|
|
502
|
+
) -> tuple[Tensor, Tensor]:
|
|
503
|
+
# Embed context and query rows jointly per table. Targets are injected
|
|
504
|
+
# by distributing them to related tables via task-row assignment:
|
|
505
|
+
_cache: Cache | None = None
|
|
506
|
+
if cache is not None and cache.is_recording:
|
|
507
|
+
_cache = Cache()
|
|
508
|
+
elif cache is not None:
|
|
509
|
+
_cache = cast(Cache, cache[cache_key])
|
|
510
|
+
|
|
511
|
+
train_mask: Tensor | None = None
|
|
512
|
+
if x_context is not None:
|
|
513
|
+
assert task_row is not None
|
|
514
|
+
x = x_context
|
|
515
|
+
train_mask = task_row >= 0
|
|
516
|
+
valid_task_row = task_row[train_mask] # Unavoidable device sync.
|
|
517
|
+
y = y[valid_task_row]
|
|
518
|
+
if valid_task_row.numel() == task_row.numel():
|
|
519
|
+
train_mask = None
|
|
520
|
+
if x_query is not None:
|
|
521
|
+
x = torch.cat([x, x_query], dim=-2)
|
|
522
|
+
if train_mask is not None:
|
|
523
|
+
test_mask = train_mask.new_zeros(x_query.size(-2))
|
|
524
|
+
train_mask = torch.cat([train_mask, test_mask])
|
|
525
|
+
else:
|
|
526
|
+
assert x_query is not None
|
|
527
|
+
x = x_query
|
|
528
|
+
|
|
529
|
+
x = self.row_embedding(
|
|
530
|
+
x=x,
|
|
531
|
+
y=y,
|
|
532
|
+
train_mask=train_mask,
|
|
533
|
+
max_keys=self.max_train_size,
|
|
534
|
+
num_classes=num_classes,
|
|
535
|
+
cache=_cache,
|
|
536
|
+
generator=generator,
|
|
537
|
+
)
|
|
538
|
+
|
|
539
|
+
if cache is not None and cache.is_recording:
|
|
540
|
+
cache[cache_key] = cast(Cache, _cache)
|
|
541
|
+
|
|
542
|
+
sections = [
|
|
543
|
+
x_context.size(-2) if x_context is not None else 0,
|
|
544
|
+
x_query.size(-2) if x_query is not None else 0,
|
|
545
|
+
]
|
|
546
|
+
return x.split(sections, dim=-2)
|
|
547
|
+
|
|
548
|
+
def _inject_task(
|
|
549
|
+
self,
|
|
550
|
+
x: Tensor,
|
|
551
|
+
task: Tensor,
|
|
552
|
+
readout_index: Tensor,
|
|
553
|
+
) -> Tensor:
|
|
554
|
+
|
|
555
|
+
if task.size(-1) == 0:
|
|
556
|
+
return x
|
|
557
|
+
|
|
558
|
+
x = torch.cat(
|
|
559
|
+
[x, x.new_zeros(*x.size()[:-1], task.size(-1))],
|
|
560
|
+
dim=-1,
|
|
561
|
+
)
|
|
562
|
+
x[..., readout_index, -task.size(-1) :] = task
|
|
563
|
+
return x
|
|
564
|
+
|
|
565
|
+
def _get_rel_time(
|
|
566
|
+
self,
|
|
567
|
+
datetime: Tensor,
|
|
568
|
+
seed_datetime: Tensor,
|
|
569
|
+
task_row: Tensor,
|
|
570
|
+
standardizer: Standardize,
|
|
571
|
+
) -> Tensor | None:
|
|
572
|
+
|
|
573
|
+
if datetime.size(-1) == 0 or seed_datetime.size(-1) == 0:
|
|
574
|
+
return None
|
|
575
|
+
|
|
576
|
+
seed_datetime = seed_datetime[task_row]
|
|
577
|
+
|
|
578
|
+
na_mask = (task_row < 0).unsqueeze(-1) | (seed_datetime == NaT)
|
|
579
|
+
na_mask = na_mask.unsqueeze(-2) | (datetime == NaT).unsqueeze(-1)
|
|
580
|
+
na_mask = na_mask.flatten(-2)
|
|
581
|
+
|
|
582
|
+
rel_time = seed_datetime.unsqueeze(-2) - datetime.unsqueeze(-1)
|
|
583
|
+
rel_time = rel_time.flatten(-2) / (24 * 60 * 60 * 1_000_000)
|
|
584
|
+
rel_time = rel_time.sign() * rel_time.abs().log1p()
|
|
585
|
+
|
|
586
|
+
if not standardizer.is_fitted:
|
|
587
|
+
rel_time[na_mask] = float("NaN")
|
|
588
|
+
rel_time = torch.where(
|
|
589
|
+
na_mask,
|
|
590
|
+
rel_time.nanmean(dim=-2, keepdim=True).nan_to_num(0.0),
|
|
591
|
+
rel_time,
|
|
592
|
+
)
|
|
593
|
+
rel_time = standardizer.fit_transform(
|
|
594
|
+
TableTensor.from_tensor(rel_time)
|
|
595
|
+
).numerical
|
|
596
|
+
else:
|
|
597
|
+
rel_time = standardizer.transform(
|
|
598
|
+
TableTensor.from_tensor(rel_time)
|
|
599
|
+
).numerical
|
|
600
|
+
rel_time[na_mask] = 0.0
|
|
601
|
+
|
|
602
|
+
return rel_time
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
2
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
3
|
+
|
|
4
|
+
import sdm
|
|
5
|
+
import sdm.processing as sp
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def default_recipe() -> sp.Recipe: # noqa: D103
|
|
9
|
+
# Add calendar features to related tables:
|
|
10
|
+
return sdm.models.TabICLv2.default_recipe().prepend_features(
|
|
11
|
+
sp.TableDispatch(
|
|
12
|
+
related=sp.StypeDispatch(
|
|
13
|
+
datetime=sp.AddCalendarFields(
|
|
14
|
+
("minute", "hour", "weekday", "day_of_month", "month"),
|
|
15
|
+
),
|
|
16
|
+
),
|
|
17
|
+
)
|
|
18
|
+
)
|