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.
Files changed (152) hide show
  1. sdm/__init__.py +58 -0
  2. sdm/_constants.py +6 -0
  3. sdm/_inference.py +42 -0
  4. sdm/_kernels/__init__.py +10 -0
  5. sdm/_kernels/rmsnorm_cast.py +92 -0
  6. sdm/_kernels/segment_multi_reduce.py +141 -0
  7. sdm/_kernels/triton/__init__.py +7 -0
  8. sdm/_kernels/triton/rmsnorm_cast.py +136 -0
  9. sdm/_kernels/triton/segment_multi_reduce.py +173 -0
  10. sdm/_memory.py +34 -0
  11. sdm/_warnings.py +29 -0
  12. sdm/cache.py +163 -0
  13. sdm/ensemble.py +501 -0
  14. sdm/evaluation/__init__.py +11 -0
  15. sdm/evaluation/classification.py +205 -0
  16. sdm/explain/__init__.py +12 -0
  17. sdm/explain/base.py +123 -0
  18. sdm/explain/gradient.py +112 -0
  19. sdm/models/__init__.py +20 -0
  20. sdm/models/_huggingface.py +58 -0
  21. sdm/models/base.py +966 -0
  22. sdm/models/callback.py +106 -0
  23. sdm/models/ecoc.py +197 -0
  24. sdm/models/kumo/__init__.py +13 -0
  25. sdm/models/kumo/relational/NOTICE +5 -0
  26. sdm/models/kumo/relational/__init__.py +11 -0
  27. sdm/models/kumo/relational/graph.py +101 -0
  28. sdm/models/kumo/relational/invariant_gnn.py +122 -0
  29. sdm/models/kumo/relational/model.py +602 -0
  30. sdm/models/kumo/relational/recipe.py +18 -0
  31. sdm/models/kumo/relational/task.py +113 -0
  32. sdm/models/kumo/tabular/__init__.py +17 -0
  33. sdm/models/kumo/tabular/batching.py +139 -0
  34. sdm/models/kumo/tabular/block.py +100 -0
  35. sdm/models/kumo/tabular/cell_embedding.py +85 -0
  36. sdm/models/kumo/tabular/icl.py +136 -0
  37. sdm/models/kumo/tabular/model.py +299 -0
  38. sdm/models/kumo/tabular/recipe.py +71 -0
  39. sdm/models/kumo/tabular/row_embedding.py +214 -0
  40. sdm/models/tabfm/LICENSE +209 -0
  41. sdm/models/tabfm/__init__.py +11 -0
  42. sdm/models/tabfm/block.py +94 -0
  43. sdm/models/tabfm/cell_embedding.py +219 -0
  44. sdm/models/tabfm/ckpt.py +242 -0
  45. sdm/models/tabfm/icl.py +107 -0
  46. sdm/models/tabfm/model.py +261 -0
  47. sdm/models/tabfm/recipe.py +46 -0
  48. sdm/models/tabfm/row_embedding.py +241 -0
  49. sdm/models/tabiclv2/LICENSE +33 -0
  50. sdm/models/tabiclv2/__init__.py +11 -0
  51. sdm/models/tabiclv2/block.py +81 -0
  52. sdm/models/tabiclv2/ckpt.py +134 -0
  53. sdm/models/tabiclv2/icl.py +420 -0
  54. sdm/models/tabiclv2/model.py +293 -0
  55. sdm/models/tabiclv2/recipe.py +46 -0
  56. sdm/models/tabiclv2/row_embedding.py +254 -0
  57. sdm/nn/__init__.py +28 -0
  58. sdm/nn/_buffer.py +91 -0
  59. sdm/nn/attention.py +825 -0
  60. sdm/nn/glu.py +78 -0
  61. sdm/nn/linear.py +46 -0
  62. sdm/nn/rms_norm.py +59 -0
  63. sdm/nn/rope.py +107 -0
  64. sdm/nn/scaling.py +240 -0
  65. sdm/nn/set_transformer.py +162 -0
  66. sdm/nn/softplus.py +65 -0
  67. sdm/processing/__init__.py +96 -0
  68. sdm/processing/base.py +254 -0
  69. sdm/processing/categorical/__init__.py +16 -0
  70. sdm/processing/categorical/_categorical.py +60 -0
  71. sdm/processing/categorical/align.py +540 -0
  72. sdm/processing/categorical/count.py +121 -0
  73. sdm/processing/categorical/impute.py +107 -0
  74. sdm/processing/categorical/shuffle.py +204 -0
  75. sdm/processing/common/__init__.py +32 -0
  76. sdm/processing/common/callable.py +29 -0
  77. sdm/processing/common/choice.py +185 -0
  78. sdm/processing/common/drop.py +28 -0
  79. sdm/processing/common/ensemble.py +187 -0
  80. sdm/processing/common/identity.py +18 -0
  81. sdm/processing/common/select.py +107 -0
  82. sdm/processing/common/sequential.py +158 -0
  83. sdm/processing/common/shuffle.py +195 -0
  84. sdm/processing/common/stype.py +199 -0
  85. sdm/processing/common/table.py +120 -0
  86. sdm/processing/common/task.py +135 -0
  87. sdm/processing/common/to_numerical.py +60 -0
  88. sdm/processing/datetime/__init__.py +8 -0
  89. sdm/processing/datetime/calendar.py +196 -0
  90. sdm/processing/ensemble.py +203 -0
  91. sdm/processing/execution.py +418 -0
  92. sdm/processing/numerical/__init__.py +38 -0
  93. sdm/processing/numerical/_stats.py +29 -0
  94. sdm/processing/numerical/cast.py +33 -0
  95. sdm/processing/numerical/clip.py +48 -0
  96. sdm/processing/numerical/clip_soft.py +54 -0
  97. sdm/processing/numerical/constant.py +235 -0
  98. sdm/processing/numerical/flip_sign.py +78 -0
  99. sdm/processing/numerical/impute.py +52 -0
  100. sdm/processing/numerical/pca.py +62 -0
  101. sdm/processing/numerical/power.py +325 -0
  102. sdm/processing/numerical/quantile.py +306 -0
  103. sdm/processing/numerical/quantile_clip.py +63 -0
  104. sdm/processing/numerical/random_projection.py +86 -0
  105. sdm/processing/numerical/rank_gaussian.py +168 -0
  106. sdm/processing/numerical/robust_scale.py +88 -0
  107. sdm/processing/numerical/sigma_clip.py +123 -0
  108. sdm/processing/numerical/standardize.py +71 -0
  109. sdm/processing/output/__init__.py +14 -0
  110. sdm/processing/output/reduce.py +86 -0
  111. sdm/processing/output/softmax.py +48 -0
  112. sdm/processing/output/sort.py +16 -0
  113. sdm/processing/recipe.py +154 -0
  114. sdm/processing/text/__init__.py +12 -0
  115. sdm/processing/text/sentence_transformer.py +451 -0
  116. sdm/processing/text/tfidf.py +478 -0
  117. sdm/relational/__init__.py +16 -0
  118. sdm/relational/backend/__init__.py +12 -0
  119. sdm/relational/backend/_cugraph.py +546 -0
  120. sdm/relational/backend/_pyg_lib.py +175 -0
  121. sdm/relational/data.py +393 -0
  122. sdm/relational/join.py +173 -0
  123. sdm/relational/sampler.py +259 -0
  124. sdm/relational/task.py +465 -0
  125. sdm/stype.py +396 -0
  126. sdm/task.py +53 -0
  127. sdm/tensor/__init__.py +20 -0
  128. sdm/tensor/categorical.py +953 -0
  129. sdm/tensor/columnar.py +1127 -0
  130. sdm/tensor/io/__init__.py +22 -0
  131. sdm/tensor/io/arrow.py +120 -0
  132. sdm/tensor/io/cudf.py +47 -0
  133. sdm/tensor/mixin.py +124 -0
  134. sdm/tensor/nullable.py +963 -0
  135. sdm/tensor/string.py +526 -0
  136. sdm/tensor/table.py +2035 -0
  137. sdm/tensor/var_len.py +1486 -0
  138. sdm/testing/__init__.py +14 -0
  139. sdm/testing/decorators.py +61 -0
  140. sdm/testing/memory.py +92 -0
  141. structured_data_models-0.2.0.dist-info/METADATA +142 -0
  142. structured_data_models-0.2.0.dist-info/RECORD +152 -0
  143. structured_data_models-0.2.0.dist-info/WHEEL +5 -0
  144. structured_data_models-0.2.0.dist-info/licenses/LICENSE +204 -0
  145. structured_data_models-0.2.0.dist-info/licenses/THIRD_PARTY_LICENSES.md +40 -0
  146. structured_data_models-0.2.0.dist-info/licenses/sdm/models/kumo/relational/NOTICE +5 -0
  147. structured_data_models-0.2.0.dist-info/licenses/sdm/models/tabfm/LICENSE +209 -0
  148. structured_data_models-0.2.0.dist-info/licenses/sdm/models/tabiclv2/LICENSE +33 -0
  149. structured_data_models-0.2.0.dist-info/licenses/third_party/contributor-covenant/LICENSE +20 -0
  150. structured_data_models-0.2.0.dist-info/licenses/third_party/pytorch/LICENSE +84 -0
  151. structured_data_models-0.2.0.dist-info/licenses/third_party/tabpfn-extensions/LICENSE +202 -0
  152. 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
+ )