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
sdm/models/callback.py ADDED
@@ -0,0 +1,106 @@
1
+ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ from typing import ClassVar
5
+
6
+ import torch
7
+
8
+ from sdm import RelatedTables, TableTensor
9
+
10
+
11
+ class Callback:
12
+ r"""Base class for callbacks applied to one model call."""
13
+
14
+ #: Whether this callback requires gradient calculation during model calls.
15
+ requires_grad: ClassVar[bool] = False
16
+
17
+ def on_context_preprocessing_end(
18
+ self,
19
+ model: torch.nn.Module,
20
+ x: TableTensor,
21
+ y: TableTensor,
22
+ related_tables: RelatedTables[TableTensor] | None,
23
+ ) -> tuple[TableTensor, TableTensor, RelatedTables[TableTensor] | None]:
24
+ r"""Run after context preprocessing.
25
+
26
+ Args:
27
+ model: Model receiving the callback.
28
+ x: The feature tensor of in-context examples with shape
29
+ ``[..., R, D]`` with ``R`` rows and ``D`` columns.
30
+ y: The targets of in-context examples with shape ``[..., R, 1]``.
31
+ related_tables: Related context for in-context examples.
32
+ """
33
+ return x, y, related_tables
34
+
35
+ def on_query_preprocessing_end(
36
+ self,
37
+ model: torch.nn.Module,
38
+ x: TableTensor,
39
+ related_tables: RelatedTables[TableTensor] | None,
40
+ ) -> tuple[TableTensor, RelatedTables[TableTensor] | None]:
41
+ r"""Run after query preprocessing.
42
+
43
+ Args:
44
+ model: Model receiving the callback.
45
+ x: The feature tensor of query examples with shape ``[..., R, D]``
46
+ with ``R`` rows and ``D`` columns.
47
+ related_tables: Related context for query examples.
48
+ """
49
+ return x, related_tables
50
+
51
+ def on_model_forward_end(
52
+ self,
53
+ model: torch.nn.Module,
54
+ out: TableTensor,
55
+ ) -> TableTensor:
56
+ """Run after the model forward pass.
57
+
58
+ Args:
59
+ model: Model receiving the callback.
60
+ out: The output produced by the model.
61
+ """
62
+ return out
63
+
64
+
65
+ class EnableInputGradients(Callback):
66
+ """Enable gradients for preprocessed numerical query inputs."""
67
+
68
+ requires_grad = True
69
+
70
+ def on_query_preprocessing_end( # noqa: D102
71
+ self,
72
+ model: torch.nn.Module,
73
+ x: TableTensor,
74
+ related_tables: RelatedTables[TableTensor] | None,
75
+ ) -> tuple[TableTensor, RelatedTables[TableTensor] | None]:
76
+ x = x.replace_blocks(
77
+ numerical=x.numerical.detach().requires_grad_(True)
78
+ )
79
+ if related_tables is not None:
80
+ related_tables = related_tables.replace_tables(
81
+ {
82
+ name: table.replace_blocks(
83
+ numerical=table.numerical.detach().requires_grad_(True)
84
+ )
85
+ for name, table in related_tables.tables.items()
86
+ }
87
+ )
88
+ return x, related_tables
89
+
90
+
91
+ class CaptureInputs(Callback):
92
+ """Collect preprocessed query inputs."""
93
+
94
+ def __init__(self) -> None:
95
+ self.inputs: list[
96
+ tuple[TableTensor, RelatedTables[TableTensor] | None]
97
+ ] = []
98
+
99
+ def on_query_preprocessing_end( # noqa: D102
100
+ self,
101
+ model: torch.nn.Module,
102
+ x: TableTensor,
103
+ related_tables: RelatedTables[TableTensor] | None,
104
+ ) -> tuple[TableTensor, RelatedTables[TableTensor] | None]:
105
+ self.inputs.append((x, related_tables))
106
+ return x, related_tables
sdm/models/ecoc.py ADDED
@@ -0,0 +1,197 @@
1
+ # Portions derived from TabPFN Extensions:
2
+ # Copyright 2025 Prior Labs GmbH
3
+ #
4
+ # Licensed under the Apache License, Version 2.0 (the "License");
5
+ # you may not use this file except in compliance with the License.
6
+ # You may obtain a copy of the License at
7
+ #
8
+ # http://www.apache.org/licenses/LICENSE-2.0
9
+ #
10
+ # Unless required by applicable law or agreed to in writing, software
11
+ # distributed under the License is distributed on an "AS IS" BASIS,
12
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
+ # See the License for the specific language governing permissions and
14
+ # limitations under the License.
15
+
16
+ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
17
+ # SPDX-License-Identifier: Apache-2.0
18
+
19
+ import math
20
+ from typing import Any, cast
21
+
22
+ import torch
23
+ from torch import Tensor
24
+
25
+ from sdm.cache import Cache
26
+
27
+
28
+ class ECOC(torch.nn.Module):
29
+ """Extend a classifier with `error-correcting output codes <https://arxiv.org/abs/cs/9501101>`_.
30
+
31
+ For more than ``max_classes`` classes, this uses the approach from
32
+ `TabPFN Extensions <https://github.com/PriorLabs/tabpfn-extensions>`__:
33
+ batched tasks each separate ``max_classes - 1`` classes and merge the rest.
34
+ Scores average log probabilities over tasks where each class is separate.
35
+ Apply softmax to normalize them.
36
+
37
+ Args:
38
+ max_classes: Number of classes supported by the model.
39
+ """
40
+
41
+ def __init__(self, max_classes: int) -> None:
42
+ super().__init__()
43
+ self.max_classes = max_classes
44
+
45
+ def forward(
46
+ self,
47
+ model: torch.nn.Module,
48
+ x: Tensor,
49
+ y: Tensor,
50
+ *,
51
+ num_classes: int,
52
+ num_members: int = 1,
53
+ cache: Cache | None = None,
54
+ generator: torch.Generator | None = None,
55
+ **kwargs: Any,
56
+ ) -> Tensor:
57
+ """Predict scores over the original classes.
58
+
59
+ Args:
60
+ model: Classifier accepting ``model(x, y, **kwargs)`` with leading
61
+ batch dimensions and returning ``[..., R_query, max_classes]``
62
+ logits. Must accept ``cache`` when caching is used.
63
+ x: Context then query features of shape ``[..., R, C]``, for
64
+ ``R`` rows and ``C`` columns.
65
+ y: Integer context labels in ``[0, num_classes)``, of shape
66
+ ``[..., R_context]``.
67
+ num_classes: Total number of target classes ``K``, including those
68
+ absent from the context.
69
+ num_members: Number of ensemble members stacked along the first
70
+ dimension of ``x`` and ``y``. Each member draws its own
71
+ codebook, in member order, as separate calls would.
72
+ cache: Cache for model state and the codebook. On replay, pass
73
+ query-only ``x``, an empty context axis in ``y``, and the same
74
+ ``num_classes``.
75
+ generator: Codebook sampling generator on ``x.device``. Ignored
76
+ on cache replay.
77
+ kwargs: Model arguments. Tensors must broadcast over the leading
78
+ task dimension.
79
+
80
+ Returns:
81
+ Scores of shape ``[..., R_query, K]`` for the query rows: model
82
+ logits within class capacity, otherwise averaged log probabilities.
83
+ """
84
+ if num_classes <= self.max_classes:
85
+ if cache is not None:
86
+ kwargs["cache"] = cache
87
+ return model(x, y, **kwargs)[..., :num_classes]
88
+
89
+ if cache is not None and cache.is_replaying:
90
+ codebook = cast(Tensor, cache["ecoc_codebook"])
91
+ if num_classes != codebook.size(-1):
92
+ raise ValueError(
93
+ "'num_classes' must match the cached ECOC codebook "
94
+ f"(expected {codebook.size(-1)}, got {num_classes})"
95
+ )
96
+ kwargs["cache"] = cast(Cache, cache["ecoc_model"])
97
+ elif num_members == 1:
98
+ # [T, K]
99
+ codebook = self._draw_codebook(num_classes, x.device, generator)
100
+ else:
101
+ # [E, T, K]
102
+ codebook = torch.stack(
103
+ [
104
+ self._draw_codebook(num_classes, x.device, generator)
105
+ for _ in range(num_members)
106
+ ]
107
+ )
108
+ if cache is not None and not cache.is_replaying:
109
+ cache["ecoc_codebook"] = codebook
110
+ kwargs["cache"] = cache["ecoc_model"] = Cache()
111
+
112
+ T = codebook.size(-2)
113
+ if codebook.dim() == 2:
114
+ y = codebook.index_select(dim=1, index=y.reshape(-1)).view(
115
+ T, *y.shape
116
+ ) # [T, ..., R_context]
117
+ else:
118
+ E = codebook.size(0)
119
+ y = (
120
+ codebook.gather(
121
+ dim=-1,
122
+ index=y.long().reshape(E, 1, -1).expand(E, T, -1),
123
+ ) # [E, T, N]
124
+ .view(E, T, *y.shape[1:])
125
+ .movedim(1, 0)
126
+ ) # [T, E, ..., R_context]
127
+ logits = model(x=x.expand(T, *x.shape), y=y, **kwargs)
128
+ if codebook.dim() == 2:
129
+ index = codebook.view(T, *(1,) * (logits.dim() - 2), num_classes)
130
+ else:
131
+ index = codebook.movedim(1, 0).reshape(
132
+ T, E, *(1,) * (logits.dim() - 3), num_classes
133
+ )
134
+ scores = logits.log_softmax(dim=-1).gather(
135
+ dim=-1,
136
+ index=index.expand(*logits.shape[:-1], num_classes),
137
+ ) # [T, ..., R_query, K]
138
+ active = index != self.max_classes - 1
139
+ return scores.masked_fill(~active, 0).sum(dim=0) / active.sum(dim=0)
140
+
141
+ def _draw_codebook(
142
+ self,
143
+ num_classes: int,
144
+ device: torch.device,
145
+ generator: torch.Generator | None,
146
+ ) -> Tensor:
147
+ rest_idx = self.max_classes - 1
148
+ num_codes = max(
149
+ # Give every class its own output in at least one task.
150
+ math.ceil(num_classes / rest_idx),
151
+ 4 * math.ceil(math.log(num_classes, self.max_classes)),
152
+ )
153
+ # Bound the quadratic distance search for large targets.
154
+ num_draws = 50 if num_classes <= 200 else 1
155
+ codebook = torch.full(
156
+ size=(num_draws, num_codes, num_classes),
157
+ fill_value=rest_idx,
158
+ dtype=torch.long,
159
+ device=device,
160
+ )
161
+ coverage = torch.zeros(num_draws, num_classes, device=device)
162
+ for code in codebook.unbind(dim=1):
163
+ priority = coverage + 0.1 * torch.rand(
164
+ num_draws, num_classes, device=device, generator=generator
165
+ )
166
+ chosen = priority.argsort(dim=-1)[:, :rest_idx]
167
+ symbols = torch.rand(
168
+ num_draws, rest_idx, device=device, generator=generator
169
+ ).argsort(dim=-1)
170
+ code.scatter_(dim=-1, index=chosen, src=symbols)
171
+ coverage.scatter_add_(
172
+ dim=-1,
173
+ index=chosen,
174
+ src=torch.ones_like(chosen, dtype=coverage.dtype),
175
+ )
176
+
177
+ if num_draws == 1:
178
+ return codebook[0]
179
+
180
+ distance = torch.zeros(
181
+ num_draws,
182
+ num_classes,
183
+ num_classes,
184
+ dtype=torch.long,
185
+ device=device,
186
+ )
187
+ for code in codebook.unbind(dim=1):
188
+ distance += code.unsqueeze(-1) != code.unsqueeze(-2)
189
+ rows, cols = torch.triu_indices(
190
+ num_classes, num_classes, offset=1, device=device
191
+ )
192
+ pairwise = distance[:, rows, cols]
193
+ # Prefer minimum distance, breaking ties by total pairwise distance.
194
+ score = pairwise.amin(dim=-1) * (
195
+ pairwise.size(-1) * num_codes + 1
196
+ ) + pairwise.sum(dim=-1)
197
+ return codebook.index_select(0, score.argmax().view(1)).squeeze(0)
@@ -0,0 +1,13 @@
1
+ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ """Kumo model components."""
5
+
6
+ from sdm.models.kumo.relational import KumoRelational
7
+ from sdm.models.kumo.tabular import KumoTabular
8
+
9
+
10
+ __all__ = [
11
+ "KumoRelational",
12
+ "KumoTabular",
13
+ ]
@@ -0,0 +1,5 @@
1
+ Kumo-Relational reuses TabICLv2-derived model components and finetunes
2
+ pretrained TabICLv2 weights, licensed under BSD-3-Clause.
3
+
4
+ See the TabICLv2 third-party license notice at:
5
+ sdm/models/tabiclv2/LICENSE
@@ -0,0 +1,11 @@
1
+ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ """Kumo-Relational."""
5
+
6
+ from sdm.models.kumo.relational.model import KumoRelational
7
+
8
+
9
+ __all__ = [
10
+ "KumoRelational",
11
+ ]
@@ -0,0 +1,101 @@
1
+ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ from collections.abc import Mapping, Sequence
5
+ from dataclasses import dataclass
6
+ from typing import Self
7
+
8
+ import torch
9
+ from torch import Tensor
10
+
11
+ from sdm import Relationship, TableTensor
12
+ from sdm.relational.join import join_index
13
+
14
+
15
+ @dataclass(frozen=True)
16
+ class HomogeneousGraph: # noqa: D101
17
+ row: Tensor
18
+ col: Tensor
19
+ colptr: Tensor
20
+ edge_type: Tensor
21
+ num_edge_types: int
22
+ start_node_offsets: dict[str, int]
23
+ end_node_offsets: dict[str, int]
24
+
25
+ @property
26
+ def num_nodes(self) -> int: # noqa: D102
27
+ return self.colptr.numel() - 1
28
+
29
+ @property
30
+ def num_edges(self) -> int: # noqa: D102
31
+ return self.row.numel()
32
+
33
+ def node_slice(self, name: str) -> slice: # noqa: D102
34
+ start = self.start_node_offsets[name]
35
+ end = self.end_node_offsets[name]
36
+ return slice(start, end)
37
+
38
+ @classmethod
39
+ def from_tables( # noqa: D102
40
+ cls,
41
+ tables: Mapping[str, TableTensor],
42
+ relationships: Sequence[Relationship],
43
+ ) -> Self:
44
+ start = 0
45
+ start_node_offsets: dict[str, int] = {}
46
+ end_node_offsets: dict[str, int] = {}
47
+ for table_name, table in tables.items():
48
+ assert table.dim() == 2
49
+ start_node_offsets[table_name] = start
50
+ start += table.size(0)
51
+ end_node_offsets[table_name] = start
52
+
53
+ rows: list[Tensor] = []
54
+ cols: list[Tensor] = []
55
+ edge_types: list[Tensor] = []
56
+ for i, rel in enumerate(relationships):
57
+ if rel.left_table not in tables or rel.right_table not in tables:
58
+ continue
59
+ row, col = join_index(
60
+ left_table=tables[rel.left_table],
61
+ right_table=tables[rel.right_table],
62
+ left_keys=rel.left_columns,
63
+ right_keys=rel.right_columns,
64
+ how="inner",
65
+ )
66
+ row += start_node_offsets[rel.left_table]
67
+ col += start_node_offsets[rel.right_table]
68
+ edge_type = row.new_full((row.size(0),), 2 * i)
69
+ rows.extend([row, col])
70
+ cols.extend([col, row])
71
+ edge_types.extend([edge_type, edge_type + 1])
72
+
73
+ if len(rows) == 0:
74
+ table = next(iter(tables.values()))
75
+ row = torch.empty(0, dtype=torch.long, device=table.device)
76
+ col = torch.empty(0, dtype=torch.long, device=table.device)
77
+ colptr = torch.zeros(
78
+ start + 1, dtype=torch.long, device=table.device
79
+ )
80
+ edge_type = torch.empty(0, dtype=torch.long, device=table.device)
81
+ else:
82
+ row = torch.cat(rows, dim=0)
83
+ col = torch.cat(cols, dim=0)
84
+ edge_type = torch.cat(edge_types, dim=0)
85
+
86
+ col, perm = col.sort()
87
+ row = row[perm]
88
+ edge_type = edge_type[perm]
89
+ colptr = torch._convert_indices_from_coo_to_csr(
90
+ col, start, out_int32=col.dtype != torch.int64
91
+ )
92
+
93
+ return cls(
94
+ row=row,
95
+ col=col,
96
+ colptr=colptr,
97
+ edge_type=edge_type,
98
+ num_edge_types=2 * len(relationships),
99
+ start_node_offsets=start_node_offsets,
100
+ end_node_offsets=end_node_offsets,
101
+ )
@@ -0,0 +1,122 @@
1
+ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ # ruff: noqa: D102
5
+
6
+ from typing import Any, cast
7
+
8
+ import torch
9
+ import torch.nn.functional as F
10
+ from torch import Tensor
11
+ from torch.nn import LayerNorm, Linear
12
+
13
+ from sdm._kernels import segment_multi_reduce
14
+ from sdm.cache import Cache
15
+ from sdm.models.kumo.relational.graph import HomogeneousGraph
16
+
17
+
18
+ class InvariantGNN(torch.nn.Module):
19
+ r"""Schema-agnostic message passing over heterogeneous graphs.
20
+
21
+ Args:
22
+ channels: The number of input and output channels.
23
+ device: The device.
24
+ dtype: The dtype.
25
+ """
26
+
27
+ def __init__(
28
+ self,
29
+ channels: int,
30
+ device: torch.device | str | None = None,
31
+ dtype: torch.dtype | None = None,
32
+ ) -> None:
33
+ super().__init__()
34
+ factory_kwargs: dict[str, Any] = {"device": device, "dtype": dtype}
35
+
36
+ self.edge_type_lin = Linear(channels, channels, **factory_kwargs)
37
+
38
+ self.skip_lin = Linear(channels, channels, **factory_kwargs)
39
+ self.src_lin = Linear(channels, channels, **factory_kwargs)
40
+
41
+ self.aggregation_lin = Linear(
42
+ 5 * channels,
43
+ channels,
44
+ bias=False,
45
+ **factory_kwargs,
46
+ )
47
+
48
+ self.norm = LayerNorm(channels, **factory_kwargs)
49
+
50
+ self.out_lin = Linear(channels, channels, **factory_kwargs)
51
+ self.out_norm = LayerNorm(channels, **factory_kwargs)
52
+
53
+ def get_edge_type_emb(
54
+ self,
55
+ num_edge_types: int,
56
+ dtype: torch.dtype | None = None,
57
+ generator: torch.Generator | None = None,
58
+ ) -> Tensor:
59
+ edge_type_emb = torch.randn(
60
+ (num_edge_types, self.edge_type_lin.weight.size(-1)),
61
+ dtype=dtype,
62
+ device=self.edge_type_lin.weight.device,
63
+ generator=generator,
64
+ )
65
+ edge_type_emb = F.normalize(edge_type_emb, dim=-1)
66
+ return self.edge_type_lin(edge_type_emb)
67
+
68
+ def forward(
69
+ self,
70
+ x: Tensor,
71
+ graph: HomogeneousGraph,
72
+ *,
73
+ readout_table: str,
74
+ readout_index: Tensor,
75
+ num_hops: int,
76
+ cache: Cache | None = None,
77
+ generator: torch.Generator | None = None,
78
+ ) -> Tensor:
79
+
80
+ if num_hops == 0:
81
+ start = graph.start_node_offsets[readout_table]
82
+ end = graph.end_node_offsets[readout_table]
83
+ return x[start:end][readout_index]
84
+
85
+ if cache is None or cache.is_recording:
86
+ edge_type_emb = torch.randn(
87
+ (graph.num_edge_types, self.edge_type_lin.weight.size(-1)),
88
+ dtype=x.dtype,
89
+ device=x.device,
90
+ generator=generator,
91
+ )
92
+ edge_type_emb = F.normalize(edge_type_emb, dim=-1)
93
+ edge_type_emb = self.edge_type_lin(edge_type_emb)
94
+ if cache is not None and cache.is_recording:
95
+ cache["edge_type_emb"] = edge_type_emb
96
+ else:
97
+ edge_type_emb = cast(Tensor, cache["edge_type_emb"])
98
+
99
+ for i in range(num_hops):
100
+ stats = segment_multi_reduce(
101
+ src=self.src_lin(x),
102
+ index=graph.row,
103
+ edge_attr=edge_type_emb,
104
+ offsets=graph.colptr,
105
+ edge_type=graph.edge_type,
106
+ )
107
+ x = torch.addmm(
108
+ self.skip_lin(x),
109
+ stats.flatten(1),
110
+ self.aggregation_lin.weight.T,
111
+ )
112
+ # Release before allocating the next hop's statistics.
113
+ del stats
114
+
115
+ if i == num_hops - 1:
116
+ start = graph.start_node_offsets[readout_table]
117
+ end = graph.end_node_offsets[readout_table]
118
+ x = x[start:end][readout_index]
119
+
120
+ x = F.gelu(self.norm(x))
121
+
122
+ return self.out_norm(self.out_lin(x))