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,205 @@
1
+ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ from typing import cast
5
+
6
+ import torch
7
+ from torch import Tensor
8
+
9
+ from sdm import CategoricalTensor, StringTensor, Stype, TableTensor
10
+
11
+
12
+ def to_class_indices(
13
+ pred: TableTensor,
14
+ target: TableTensor | CategoricalTensor,
15
+ *,
16
+ missing_score: float | None = None,
17
+ ) -> tuple[Tensor, Tensor]:
18
+ r"""Convert classification predictions and targets to class-index form.
19
+
20
+ Args:
21
+ pred: Prediction table whose numerical columns contain class scores.
22
+ Column names define the class order.
23
+ target: Single-column categorical target.
24
+ missing_score: Score assigned to target classes that are absent from
25
+ the prediction columns. If ``None``, will raise an error when a
26
+ ``target`` value refers to an absent class in ``pred``.
27
+
28
+ >>> import torch
29
+ >>> import sdm
30
+ >>> from sdm.evaluation import to_class_indices
31
+ >>> pred = sdm.TableTensor.from_tensor(
32
+ ... torch.tensor([[0.8, 0.1, 0.1], [0.1, 0.2, 0.7]]),
33
+ ... columns=["cat", "dog", "bird"],
34
+ ... )
35
+ >>> target = sdm.CategoricalTensor(
36
+ ... code=torch.tensor([[0], [2]]),
37
+ ... categories=(sdm.StringTensor.from_list(["cat", "dog", "bird"]),),
38
+ ... )
39
+ >>> class_scores, class_indices = to_class_indices(pred, target)
40
+ >>> class_scores
41
+ tensor([[0.8000, 0.1000, 0.1000],
42
+ [0.1000, 0.2000, 0.7000]])
43
+ >>> class_indices
44
+ tensor([0, 2])
45
+ >>> pred = sdm.TableTensor.from_tensor(
46
+ ... torch.tensor([[0.1, 0.8, 0.1], [0.7, 0.1, 0.2]]),
47
+ ... columns=["bird", "cat", "dog"],
48
+ ... )
49
+ >>> class_scores, class_indices = to_class_indices(pred, target)
50
+ >>> class_scores
51
+ tensor([[0.8000, 0.1000, 0.1000],
52
+ [0.1000, 0.2000, 0.7000]])
53
+ >>> class_indices
54
+ tensor([0, 2])
55
+ """
56
+ if isinstance(target, TableTensor):
57
+ if target.size(-1) != 1:
58
+ raise ValueError(
59
+ f"Expected a single categorical target column "
60
+ f"(got {target.size(-1)} columns)"
61
+ )
62
+ target = target.categorical
63
+
64
+ if target.size(-1) != 1:
65
+ raise ValueError(
66
+ f"Expected a single categorical target column "
67
+ f"(got {target.size(-1)} columns)"
68
+ )
69
+
70
+ if target.isnan().any():
71
+ raise ValueError("Expected target to not contain missing values")
72
+
73
+ if pred.size()[:-1] != target.size()[:-1]:
74
+ raise ValueError(
75
+ f"Expected prediction and target row dimensions to match "
76
+ f"(got {tuple(pred.size()[:-1])} and "
77
+ f"{tuple(target.size())[:-1]})"
78
+ )
79
+
80
+ columns = pred.columns[Stype.numerical]
81
+ pred: Tensor = pred.numerical
82
+
83
+ category = target.categories[0]
84
+ code = target.code.squeeze(-1).to(torch.int64)
85
+
86
+ if isinstance(category, StringTensor):
87
+ classes = StringTensor.from_list(
88
+ [_parse_column(column, category) for column in columns],
89
+ device=category.device,
90
+ )
91
+ else:
92
+ classes = torch.tensor(
93
+ [_parse_column(column, category) for column in columns],
94
+ dtype=category.dtype,
95
+ device=category.device,
96
+ )
97
+
98
+ match = category.unsqueeze(-1) == classes.unsqueeze(0) # [C_t, C_p]
99
+ if missing_score is None and not match.any(dim=-1)[code].all():
100
+ raise ValueError("Target contains classes missing from prediction")
101
+
102
+ matched_target, matched_pred = match.nonzero(as_tuple=True)
103
+ aligned = pred.new_full(
104
+ (*pred.size()[:-1], category.size(0)),
105
+ fill_value=missing_score or 0,
106
+ )
107
+ aligned[..., matched_target] = pred[..., matched_pred]
108
+ return aligned, code
109
+
110
+
111
+ def to_binary_class(
112
+ pred: TableTensor,
113
+ target: TableTensor | CategoricalTensor,
114
+ positive_class: bool | int | float | str,
115
+ ) -> tuple[Tensor, Tensor]:
116
+ r"""Convert binary predictions and targets to positive-class form.
117
+
118
+ Args:
119
+ pred: Prediction table whose numerical columns contain class scores.
120
+ Column names define the class order.
121
+ target: Single-column categorical target.
122
+ positive_class: Class value treated as the positive class.
123
+
124
+ >>> import torch
125
+ >>> import sdm
126
+ >>> from sdm.evaluation import to_binary_class
127
+ >>> pred = sdm.TableTensor.from_tensor(
128
+ ... torch.tensor([[0.8, 0.2], [0.1, 0.9], [0.4, 0.6]]),
129
+ ... columns=["false", "true"],
130
+ ... )
131
+ >>> target = sdm.CategoricalTensor(
132
+ ... code=torch.tensor([[0], [1], [1]]),
133
+ ... categories=(sdm.StringTensor.from_list(["false", "true"]),),
134
+ ... )
135
+ >>> positive_scores, binary_target = to_binary_class(
136
+ ... pred,
137
+ ... target,
138
+ ... positive_class="true",
139
+ ... )
140
+ >>> positive_scores
141
+ tensor([0.2000, 0.9000, 0.6000])
142
+ >>> binary_target
143
+ tensor([False, True, True])
144
+ >>> pred = sdm.TableTensor.from_tensor(
145
+ ... torch.tensor([[0.2, 0.8], [0.9, 0.1], [0.6, 0.4]]),
146
+ ... columns=["true", "false"],
147
+ ... )
148
+ >>> positive_scores, binary_target = to_binary_class(
149
+ ... pred,
150
+ ... target,
151
+ ... positive_class="true",
152
+ ... )
153
+ >>> positive_scores
154
+ tensor([0.2000, 0.9000, 0.6000])
155
+ >>> binary_target
156
+ tensor([False, True, True])
157
+ """
158
+ if isinstance(target, TableTensor):
159
+ if target.size(-1) != 1:
160
+ raise ValueError(
161
+ f"Expected a single categorical target column "
162
+ f"(got {target.size(-1)} columns)"
163
+ )
164
+ target = target.categorical
165
+
166
+ if target.size(-1) != 1:
167
+ raise ValueError(
168
+ f"Expected a single categorical target column "
169
+ f"(got {target.size(-1)} columns)"
170
+ )
171
+
172
+ if pred.size()[:-1] != target.size()[:-1]:
173
+ raise ValueError(
174
+ f"Expected prediction and target row dimensions to match "
175
+ f"(got {tuple(pred.size()[:-1])} and "
176
+ f"{tuple(target.size())[:-1]})"
177
+ )
178
+
179
+ score = pred[str(positive_class)].numerical.squeeze(-1)
180
+ match = cast(Tensor, target.categories[0] == positive_class)
181
+ index = match.nonzero().view(-1)
182
+ if index.numel() != 1:
183
+ raise ValueError(
184
+ f"Expected positive class {positive_class!r} to appear exactly "
185
+ f"once in target categories (found {index.numel()} matches)"
186
+ )
187
+
188
+ return score, target.code.squeeze(-1) == index
189
+
190
+
191
+ def _parse_column(
192
+ column: str,
193
+ category: Tensor,
194
+ ) -> bool | int | float | str:
195
+ if isinstance(category, StringTensor):
196
+ return column
197
+ if category.dtype == torch.bool:
198
+ if column == "True":
199
+ return True
200
+ if column == "False":
201
+ return False
202
+ raise ValueError(f"Cannot parse prediction column {column!r} as bool")
203
+ if category.is_floating_point():
204
+ return float(column)
205
+ return int(column)
@@ -0,0 +1,12 @@
1
+ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ """Explainability modules for structured data models."""
5
+
6
+ from sdm.explain.base import ICLExplainer
7
+ from sdm.explain.gradient import GradientExplainer
8
+
9
+ __all__ = [
10
+ "ICLExplainer",
11
+ "GradientExplainer",
12
+ ]
sdm/explain/base.py ADDED
@@ -0,0 +1,123 @@
1
+ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ import abc
5
+ from typing import Any, Generic, TypeVar, final, overload
6
+
7
+ import torch
8
+ from torch import Tensor
9
+
10
+ from sdm import Recipe, RelatedTables, TableTensor
11
+ from sdm.models import ICLModel
12
+
13
+ T = TypeVar("T", covariant=True)
14
+
15
+
16
+ class ICLExplainer(abc.ABC, Generic[T]): # noqa: D101
17
+ @overload
18
+ def explain(
19
+ self,
20
+ model: ICLModel,
21
+ x_query: Tensor | TableTensor,
22
+ related_query_tables: RelatedTables[TableTensor] | None = None,
23
+ *,
24
+ x_context: Tensor | TableTensor,
25
+ y_context: Tensor | TableTensor,
26
+ related_context_tables: RelatedTables[TableTensor] | None = None,
27
+ recipe: Recipe | None = None,
28
+ generator: torch.Generator | None = None,
29
+ **kwargs: Any,
30
+ ) -> T: ...
31
+
32
+ @overload
33
+ def explain(
34
+ self,
35
+ model: ICLModel,
36
+ x_query: Tensor | TableTensor,
37
+ related_query_tables: RelatedTables[TableTensor] | None = None,
38
+ ) -> T: ...
39
+
40
+ @final
41
+ def explain( # noqa: D102
42
+ self,
43
+ model: ICLModel,
44
+ x_query: Tensor | TableTensor,
45
+ related_query_tables: RelatedTables[TableTensor] | None = None,
46
+ *,
47
+ x_context: Tensor | TableTensor | None = None,
48
+ y_context: Tensor | TableTensor | None = None,
49
+ related_context_tables: RelatedTables[TableTensor] | None = None,
50
+ recipe: Recipe | None = None,
51
+ generator: torch.Generator | None = None,
52
+ **kwargs: Any,
53
+ ) -> T:
54
+
55
+ if x_context is not None:
56
+ assert y_context is not None
57
+ return self._explain_forward(
58
+ model,
59
+ x_context,
60
+ y_context,
61
+ x_query,
62
+ related_context_tables,
63
+ related_query_tables,
64
+ recipe=recipe,
65
+ generator=generator,
66
+ **kwargs,
67
+ )
68
+
69
+ if model._cache is None:
70
+ raise RuntimeError(
71
+ f"{model.__class__.__name__!r} is not fitted. Pass required "
72
+ f"context to 'explain()' or call "
73
+ f"'{model.__class__.__name__}.fit()' first."
74
+ )
75
+
76
+ return self._explain_predict(
77
+ model,
78
+ x_query,
79
+ related_query_tables,
80
+ generator=generator,
81
+ )
82
+
83
+ def _explain_forward(
84
+ self,
85
+ model: ICLModel,
86
+ x_context: Tensor | TableTensor,
87
+ y_context: Tensor | TableTensor,
88
+ x_query: Tensor | TableTensor,
89
+ related_context_tables: RelatedTables[TableTensor] | None = None,
90
+ related_query_tables: RelatedTables[TableTensor] | None = None,
91
+ *,
92
+ recipe: Recipe | None = None,
93
+ generator: torch.Generator | None = None,
94
+ **kwargs: Any,
95
+ ) -> T:
96
+ kwargs.pop("callbacks", None)
97
+ model.fit(
98
+ x=x_context,
99
+ y=y_context,
100
+ related_tables=related_context_tables,
101
+ recipe=recipe,
102
+ generator=generator,
103
+ **kwargs,
104
+ )
105
+ try:
106
+ return self._explain_predict(
107
+ model,
108
+ x_query,
109
+ related_query_tables,
110
+ generator=generator,
111
+ )
112
+ finally:
113
+ model.clear()
114
+
115
+ @abc.abstractmethod
116
+ def _explain_predict(
117
+ self,
118
+ model: ICLModel,
119
+ x_query: Tensor | TableTensor,
120
+ related_query_tables: RelatedTables[TableTensor] | None = None,
121
+ *,
122
+ generator: torch.Generator | None = None,
123
+ ) -> T: ...
@@ -0,0 +1,112 @@
1
+ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ from __future__ import annotations
5
+
6
+ from typing import cast
7
+
8
+ import torch
9
+ from torch import Tensor
10
+
11
+ from sdm import RelatedTables, TableTensor
12
+ from sdm.explain.base import ICLExplainer
13
+ from sdm.models import ICLModel
14
+ from sdm.models.callback import CaptureInputs, EnableInputGradients
15
+
16
+
17
+ class GradientExplainer(
18
+ ICLExplainer[tuple[TableTensor, RelatedTables[TableTensor] | None]]
19
+ ):
20
+ """Return gradients showing how small input changes affect predictions.
21
+
22
+ Gradients describe model predictions with respect to preprocessed
23
+ numerical query inputs, not the original input data.
24
+
25
+ For each output column, differentiate the sum of predictions over query
26
+ rows and batch dimensions. Requires exactly one estimator.
27
+
28
+ Attribution tables have shape ``[C, ..., R, D]``, where ``C`` is the output
29
+ count, ``R`` the query rows, and ``D`` the preprocessed input columns.
30
+ """
31
+
32
+ def _explain_predict(
33
+ self,
34
+ model: ICLModel,
35
+ x_query: Tensor | TableTensor,
36
+ related_query_tables: RelatedTables[TableTensor] | None = None,
37
+ *,
38
+ generator: torch.Generator | None = None,
39
+ ) -> tuple[TableTensor, RelatedTables[TableTensor] | None]:
40
+ callbacks = (EnableInputGradients(), CaptureInputs())
41
+ prediction = model.predict(
42
+ x=x_query,
43
+ related_tables=related_query_tables,
44
+ callbacks=callbacks,
45
+ )
46
+ if len(callbacks[1].inputs) != 1:
47
+ raise RuntimeError(
48
+ "GradientExplainer requires exactly one estimator"
49
+ )
50
+ x, related_tables = callbacks[1].inputs[0]
51
+
52
+ scores = prediction.numerical
53
+
54
+ leaves = [x.numerical]
55
+ if related_tables is not None:
56
+ leaves.extend(
57
+ table.numerical for table in related_tables.tables.values()
58
+ )
59
+ # scores: [..., R, C] -> explanations: [C, ..., R, D]
60
+ gradient_x, *gradient_related = zip(
61
+ *[
62
+ torch.autograd.grad(
63
+ scores[..., index].sum(),
64
+ leaves,
65
+ retain_graph=index < scores.size(-1) - 1,
66
+ allow_unused=True,
67
+ )
68
+ for index in range(scores.size(-1))
69
+ ]
70
+ )
71
+ x_attributions = cast(
72
+ TableTensor,
73
+ torch.stack(
74
+ [
75
+ x.replace_blocks(
76
+ numerical=(
77
+ torch.zeros_like(x.numerical)
78
+ if gradient is None
79
+ else gradient
80
+ )
81
+ )
82
+ for gradient in gradient_x
83
+ ]
84
+ ),
85
+ )
86
+ if related_tables is None:
87
+ return x_attributions, None
88
+
89
+ related_attributions = related_tables.replace_tables(
90
+ tables={
91
+ name: cast(
92
+ TableTensor,
93
+ torch.stack(
94
+ [
95
+ table.replace_blocks(
96
+ numerical=(
97
+ torch.zeros_like(table.numerical)
98
+ if gradient is None
99
+ else gradient
100
+ )
101
+ )
102
+ for gradient in gradients
103
+ ]
104
+ ),
105
+ )
106
+ for (name, table), gradients in zip(
107
+ related_tables.tables.items(),
108
+ gradient_related,
109
+ )
110
+ }
111
+ )
112
+ return x_attributions, related_attributions
sdm/models/__init__.py ADDED
@@ -0,0 +1,20 @@
1
+ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ """Structured Data Models."""
5
+
6
+ from sdm.models.base import ICLModel
7
+ from sdm.models.ecoc import ECOC
8
+ from sdm.models.tabiclv2 import TabICLv2
9
+ from sdm.models.tabfm import TabFM
10
+ from sdm.models.kumo import KumoTabular, KumoRelational
11
+
12
+
13
+ __all__ = [
14
+ "ICLModel",
15
+ "ECOC",
16
+ "TabICLv2",
17
+ "TabFM",
18
+ "KumoTabular",
19
+ "KumoRelational",
20
+ ]
@@ -0,0 +1,58 @@
1
+ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2
+ # SPDX-License-Identifier: Apache-2.0
3
+
4
+ from pathlib import Path
5
+
6
+ from huggingface_hub import hf_hub_download
7
+ from huggingface_hub.utils import LocalEntryNotFoundError
8
+
9
+
10
+ def download_checkpoint(
11
+ repo_id: str,
12
+ filename: str,
13
+ *,
14
+ revision: str | None = None,
15
+ cache_dir: str | Path | None = None,
16
+ local_files_only: bool = False,
17
+ license_prompt: str | None = None,
18
+ config_filename: str | None = None,
19
+ ) -> str:
20
+ r"""Resolve a checkpoint from the Hugging Face cache or Hub.
21
+
22
+ Authentication is delegated to :mod:`huggingface_hub`, which uses its
23
+ configured login or the ``HF_TOKEN`` environment variable for private
24
+ repositories.
25
+ """
26
+ try:
27
+ return hf_hub_download(
28
+ repo_id=repo_id,
29
+ filename=filename,
30
+ revision=revision,
31
+ cache_dir=cache_dir,
32
+ local_files_only=True,
33
+ )
34
+ except LocalEntryNotFoundError:
35
+ if local_files_only:
36
+ raise
37
+ if license_prompt is not None:
38
+ print(f"{license_prompt}\n") # noqa: T201
39
+ answer = input("Accept license terms? [y/N] ")
40
+ if answer.lower() not in {"y", "yes"}:
41
+ raise RuntimeError(
42
+ "Checkpoint download requires license acceptance"
43
+ ) from None
44
+ if config_filename is not None:
45
+ hf_hub_download(
46
+ repo_id=repo_id,
47
+ filename=config_filename,
48
+ revision=revision,
49
+ cache_dir=cache_dir,
50
+ local_files_only=False,
51
+ )
52
+ return hf_hub_download(
53
+ repo_id=repo_id,
54
+ filename=filename,
55
+ revision=revision,
56
+ cache_dir=cache_dir,
57
+ local_files_only=False,
58
+ )