Commit ·
08646a9
0
Parent(s):
recICL v0
Browse files- .gitattributes +35 -0
- LICENSE +201 -0
- NOTICE +32 -0
- README.md +212 -0
- config.json +233 -0
- eval/results.json +699 -0
- example.py +48 -0
- model.safetensors +3 -0
- recicl/__init__.py +21 -0
- recicl/architecture/__init__.py +10 -0
- recicl/architecture/base.py +117 -0
- recicl/architecture/emb_knn.py +92 -0
- recicl/architecture/recpfn.py +303 -0
- recicl/architecture/util.py +60 -0
- recicl/config.py +107 -0
- recicl/constants.py +37 -0
- recicl/context_selector/__init__.py +9 -0
- recicl/context_selector/selector.py +205 -0
- recicl/inference.py +176 -0
- recicl/util/__init__.py +2 -0
- recicl/util/metrics.py +203 -0
- requirements.txt +4 -0
.gitattributes
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
*.7z filter=lfs diff=lfs merge=lfs -text
|
| 2 |
+
*.arrow filter=lfs diff=lfs merge=lfs -text
|
| 3 |
+
*.bin filter=lfs diff=lfs merge=lfs -text
|
| 4 |
+
*.bz2 filter=lfs diff=lfs merge=lfs -text
|
| 5 |
+
*.ckpt filter=lfs diff=lfs merge=lfs -text
|
| 6 |
+
*.ftz filter=lfs diff=lfs merge=lfs -text
|
| 7 |
+
*.gz filter=lfs diff=lfs merge=lfs -text
|
| 8 |
+
*.h5 filter=lfs diff=lfs merge=lfs -text
|
| 9 |
+
*.joblib filter=lfs diff=lfs merge=lfs -text
|
| 10 |
+
*.lfs.* filter=lfs diff=lfs merge=lfs -text
|
| 11 |
+
*.mlmodel filter=lfs diff=lfs merge=lfs -text
|
| 12 |
+
*.model filter=lfs diff=lfs merge=lfs -text
|
| 13 |
+
*.msgpack filter=lfs diff=lfs merge=lfs -text
|
| 14 |
+
*.npy filter=lfs diff=lfs merge=lfs -text
|
| 15 |
+
*.npz filter=lfs diff=lfs merge=lfs -text
|
| 16 |
+
*.onnx filter=lfs diff=lfs merge=lfs -text
|
| 17 |
+
*.ot filter=lfs diff=lfs merge=lfs -text
|
| 18 |
+
*.parquet filter=lfs diff=lfs merge=lfs -text
|
| 19 |
+
*.pb filter=lfs diff=lfs merge=lfs -text
|
| 20 |
+
*.pickle filter=lfs diff=lfs merge=lfs -text
|
| 21 |
+
*.pkl filter=lfs diff=lfs merge=lfs -text
|
| 22 |
+
*.pt filter=lfs diff=lfs merge=lfs -text
|
| 23 |
+
*.pth filter=lfs diff=lfs merge=lfs -text
|
| 24 |
+
*.rar filter=lfs diff=lfs merge=lfs -text
|
| 25 |
+
*.safetensors filter=lfs diff=lfs merge=lfs -text
|
| 26 |
+
saved_model/**/* filter=lfs diff=lfs merge=lfs -text
|
| 27 |
+
*.tar.* filter=lfs diff=lfs merge=lfs -text
|
| 28 |
+
*.tar filter=lfs diff=lfs merge=lfs -text
|
| 29 |
+
*.tflite filter=lfs diff=lfs merge=lfs -text
|
| 30 |
+
*.tgz filter=lfs diff=lfs merge=lfs -text
|
| 31 |
+
*.wasm filter=lfs diff=lfs merge=lfs -text
|
| 32 |
+
*.xz filter=lfs diff=lfs merge=lfs -text
|
| 33 |
+
*.zip filter=lfs diff=lfs merge=lfs -text
|
| 34 |
+
*.zst filter=lfs diff=lfs merge=lfs -text
|
| 35 |
+
*tfevents* filter=lfs diff=lfs merge=lfs -text
|
LICENSE
ADDED
|
@@ -0,0 +1,201 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
Apache License
|
| 2 |
+
Version 2.0, January 2004
|
| 3 |
+
http://www.apache.org/licenses/
|
| 4 |
+
|
| 5 |
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
| 6 |
+
|
| 7 |
+
1. Definitions.
|
| 8 |
+
|
| 9 |
+
"License" shall mean the terms and conditions for use, reproduction,
|
| 10 |
+
and distribution as defined by Sections 1 through 9 of this document.
|
| 11 |
+
|
| 12 |
+
"Licensor" shall mean the copyright owner or entity authorized by
|
| 13 |
+
the copyright owner that is granting the License.
|
| 14 |
+
|
| 15 |
+
"Legal Entity" shall mean the union of the acting entity and all
|
| 16 |
+
other entities that control, are controlled by, or are under common
|
| 17 |
+
control with that entity. For the purposes of this definition,
|
| 18 |
+
"control" means (i) the power, direct or indirect, to cause the
|
| 19 |
+
direction or management of such entity, whether by contract or
|
| 20 |
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
| 21 |
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
| 22 |
+
|
| 23 |
+
"You" (or "Your") shall mean an individual or Legal Entity
|
| 24 |
+
exercising permissions granted by this License.
|
| 25 |
+
|
| 26 |
+
"Source" form shall mean the preferred form for making modifications,
|
| 27 |
+
including but not limited to software source code, documentation
|
| 28 |
+
source, and configuration files.
|
| 29 |
+
|
| 30 |
+
"Object" form shall mean any form resulting from mechanical
|
| 31 |
+
transformation or translation of a Source form, including but
|
| 32 |
+
not limited to compiled object code, generated documentation,
|
| 33 |
+
and conversions to other media types.
|
| 34 |
+
|
| 35 |
+
"Work" shall mean the work of authorship, whether in Source or
|
| 36 |
+
Object form, made available under the License, as indicated by a
|
| 37 |
+
copyright notice that is included in or attached to the work
|
| 38 |
+
(an example is provided in the Appendix below).
|
| 39 |
+
|
| 40 |
+
"Derivative Works" shall mean any work, whether in Source or Object
|
| 41 |
+
form, that is based on (or derived from) the Work and for which the
|
| 42 |
+
editorial revisions, annotations, elaborations, or other modifications
|
| 43 |
+
represent, as a whole, an original work of authorship. For the purposes
|
| 44 |
+
of this License, Derivative Works shall not include works that remain
|
| 45 |
+
separable from, or merely link (or bind by name) to the interfaces of,
|
| 46 |
+
the Work and Derivative Works thereof.
|
| 47 |
+
|
| 48 |
+
"Contribution" shall mean any work of authorship, including
|
| 49 |
+
the original version of the Work and any modifications or additions
|
| 50 |
+
to that Work or Derivative Works thereof, that is intentionally
|
| 51 |
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
| 52 |
+
or by an individual or Legal Entity authorized to submit on behalf of
|
| 53 |
+
the copyright owner. For the purposes of this definition, "submitted"
|
| 54 |
+
means any form of electronic, verbal, or written communication sent
|
| 55 |
+
to the Licensor or its representatives, including but not limited to
|
| 56 |
+
communication on electronic mailing lists, source code control systems,
|
| 57 |
+
and issue tracking systems that are managed by, or on behalf of, the
|
| 58 |
+
Licensor for the purpose of discussing and improving the Work, but
|
| 59 |
+
excluding communication that is conspicuously marked or otherwise
|
| 60 |
+
designated in writing by the copyright owner as "Not a Contribution."
|
| 61 |
+
|
| 62 |
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
| 63 |
+
on behalf of whom a Contribution has been received by Licensor and
|
| 64 |
+
subsequently incorporated within the Work.
|
| 65 |
+
|
| 66 |
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
| 67 |
+
this License, each Contributor hereby grants to You a perpetual,
|
| 68 |
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
| 69 |
+
copyright license to reproduce, prepare Derivative Works of,
|
| 70 |
+
publicly display, publicly perform, sublicense, and distribute the
|
| 71 |
+
Work and such Derivative Works in Source or Object form.
|
| 72 |
+
|
| 73 |
+
3. Grant of Patent License. Subject to the terms and conditions of
|
| 74 |
+
this License, each Contributor hereby grants to You a perpetual,
|
| 75 |
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
| 76 |
+
(except as stated in this section) patent license to make, have made,
|
| 77 |
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
| 78 |
+
where such license applies only to those patent claims licensable
|
| 79 |
+
by such Contributor that are necessarily infringed by their
|
| 80 |
+
Contribution(s) alone or by combination of their Contribution(s)
|
| 81 |
+
with the Work to which such Contribution(s) was submitted. If You
|
| 82 |
+
institute patent litigation against any entity (including a
|
| 83 |
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
| 84 |
+
or a Contribution incorporated within the Work constitutes direct
|
| 85 |
+
or contributory patent infringement, then any patent licenses
|
| 86 |
+
granted to You under this License for that Work shall terminate
|
| 87 |
+
as of the date such litigation is filed.
|
| 88 |
+
|
| 89 |
+
4. Redistribution. You may reproduce and distribute copies of the
|
| 90 |
+
Work or Derivative Works thereof in any medium, with or without
|
| 91 |
+
modifications, and in Source or Object form, provided that You
|
| 92 |
+
meet the following conditions:
|
| 93 |
+
|
| 94 |
+
(a) You must give any other recipients of the Work or
|
| 95 |
+
Derivative Works a copy of this License; and
|
| 96 |
+
|
| 97 |
+
(b) You must cause any modified files to carry prominent notices
|
| 98 |
+
stating that You changed the files; and
|
| 99 |
+
|
| 100 |
+
(c) You must retain, in the Source form of any Derivative Works
|
| 101 |
+
that You distribute, all copyright, patent, trademark, and
|
| 102 |
+
attribution notices from the Source form of the Work,
|
| 103 |
+
excluding those notices that do not pertain to any part of
|
| 104 |
+
the Derivative Works; and
|
| 105 |
+
|
| 106 |
+
(d) If the Work includes a "NOTICE" text file as part of its
|
| 107 |
+
distribution, then any Derivative Works that You distribute must
|
| 108 |
+
include a readable copy of the attribution notices contained
|
| 109 |
+
within such NOTICE file, excluding those notices that do not
|
| 110 |
+
pertain to any part of the Derivative Works, in at least one
|
| 111 |
+
of the following places: within a NOTICE text file distributed
|
| 112 |
+
as part of the Derivative Works; within the Source form or
|
| 113 |
+
documentation, if provided along with the Derivative Works; or,
|
| 114 |
+
within a display generated by the Derivative Works, if and
|
| 115 |
+
wherever such third-party notices normally appear. The contents
|
| 116 |
+
of the NOTICE file are for informational purposes only and
|
| 117 |
+
do not modify the License. You may add Your own attribution
|
| 118 |
+
notices within Derivative Works that You distribute, alongside
|
| 119 |
+
or as an addendum to the NOTICE text from the Work, provided
|
| 120 |
+
that such additional attribution notices cannot be construed
|
| 121 |
+
as modifying the License.
|
| 122 |
+
|
| 123 |
+
You may add Your own copyright statement to Your modifications and
|
| 124 |
+
may provide additional or different license terms and conditions
|
| 125 |
+
for use, reproduction, or distribution of Your modifications, or
|
| 126 |
+
for any such Derivative Works as a whole, provided Your use,
|
| 127 |
+
reproduction, and distribution of the Work otherwise complies with
|
| 128 |
+
the conditions stated in this License.
|
| 129 |
+
|
| 130 |
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
| 131 |
+
any Contribution intentionally submitted for inclusion in the Work
|
| 132 |
+
by You to the Licensor shall be under the terms and conditions of
|
| 133 |
+
this License, without any additional terms or conditions.
|
| 134 |
+
Notwithstanding the above, nothing herein shall supersede or modify
|
| 135 |
+
the terms of any separate license agreement you may have executed
|
| 136 |
+
with Licensor regarding such Contributions.
|
| 137 |
+
|
| 138 |
+
6. Trademarks. This License does not grant permission to use the trade
|
| 139 |
+
names, trademarks, service marks, or product names of the Licensor,
|
| 140 |
+
except as required for reasonable and customary use in describing the
|
| 141 |
+
origin of the Work and reproducing the content of the NOTICE file.
|
| 142 |
+
|
| 143 |
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
| 144 |
+
agreed to in writing, Licensor provides the Work (and each
|
| 145 |
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
| 146 |
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
| 147 |
+
implied, including, without limitation, any warranties or conditions
|
| 148 |
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
| 149 |
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
| 150 |
+
appropriateness of using or redistributing the Work and assume any
|
| 151 |
+
risks associated with Your exercise of permissions under this License.
|
| 152 |
+
|
| 153 |
+
8. Limitation of Liability. In no event and under no legal theory,
|
| 154 |
+
whether in tort (including negligence), contract, or otherwise,
|
| 155 |
+
unless required by applicable law (such as deliberate and grossly
|
| 156 |
+
negligent acts) or agreed to in writing, shall any Contributor be
|
| 157 |
+
liable to You for damages, including any direct, indirect, special,
|
| 158 |
+
incidental, or consequential damages of any character arising as a
|
| 159 |
+
result of this License or out of the use or inability to use the
|
| 160 |
+
Work (including but not limited to damages for loss of goodwill,
|
| 161 |
+
work stoppage, computer failure or malfunction, or any and all
|
| 162 |
+
other commercial damages or losses), even if such Contributor
|
| 163 |
+
has been advised of the possibility of such damages.
|
| 164 |
+
|
| 165 |
+
9. Accepting Warranty or Additional Liability. While redistributing
|
| 166 |
+
the Work or Derivative Works thereof, You may choose to offer,
|
| 167 |
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
| 168 |
+
or other liability obligations and/or rights consistent with this
|
| 169 |
+
License. However, in accepting such obligations, You may act only
|
| 170 |
+
on Your own behalf and on Your sole responsibility, not on behalf
|
| 171 |
+
of any other Contributor, and only if You agree to indemnify,
|
| 172 |
+
defend, and hold each Contributor harmless for any liability
|
| 173 |
+
incurred by, or claims asserted against, such Contributor by reason
|
| 174 |
+
of your accepting any such warranty or additional liability.
|
| 175 |
+
|
| 176 |
+
END OF TERMS AND CONDITIONS
|
| 177 |
+
|
| 178 |
+
APPENDIX: How to apply the Apache License to your work.
|
| 179 |
+
|
| 180 |
+
To apply the Apache License to your work, attach the following
|
| 181 |
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
| 182 |
+
replaced with your own identifying information. (Don't include
|
| 183 |
+
the brackets!) The text should be enclosed in the appropriate
|
| 184 |
+
comment syntax for the file format. We also recommend that a
|
| 185 |
+
file or class name and description of purpose be included on the
|
| 186 |
+
same "printed page" as the copyright notice for easier
|
| 187 |
+
identification within third-party archives.
|
| 188 |
+
|
| 189 |
+
Copyright [yyyy] [name of copyright owner]
|
| 190 |
+
|
| 191 |
+
Licensed under the Apache License, Version 2.0 (the "License");
|
| 192 |
+
you may not use this file except in compliance with the License.
|
| 193 |
+
You may obtain a copy of the License at
|
| 194 |
+
|
| 195 |
+
http://www.apache.org/licenses/LICENSE-2.0
|
| 196 |
+
|
| 197 |
+
Unless required by applicable law or agreed to in writing, software
|
| 198 |
+
distributed under the License is distributed on an "AS IS" BASIS,
|
| 199 |
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
| 200 |
+
See the License for the specific language governing permissions and
|
| 201 |
+
limitations under the License.
|
NOTICE
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
recICL
|
| 2 |
+
Copyright 2026 devtaji
|
| 3 |
+
|
| 4 |
+
This product includes software developed by SAP SE and the tabular-ai-recpfn contributors:
|
| 5 |
+
|
| 6 |
+
RecPFN - https://github.com/SAP-samples/tabular-ai-recpfn (upstream commit 1af320c)
|
| 7 |
+
Copyright 2026 SAP SE or an SAP affiliate company and tabular-ai-recpfn contributors
|
| 8 |
+
Licensed under the Apache License, Version 2.0 (see LICENSE)
|
| 9 |
+
|
| 10 |
+
Files copied from that project (from its src/ directory) into recicl/. Every copied file is modified, and
|
| 11 |
+
the header of each file states the changes:
|
| 12 |
+
|
| 13 |
+
recicl/config.py header added; code unchanged
|
| 14 |
+
recicl/constants.py header added; code unchanged
|
| 15 |
+
recicl/architecture/__init__.py imports made package-relative
|
| 16 |
+
recicl/architecture/base.py imports made package-relative
|
| 17 |
+
recicl/architecture/util.py imports made package-relative
|
| 18 |
+
recicl/architecture/recpfn.py imports made package-relative
|
| 19 |
+
recicl/architecture/emb_knn.py imports made package-relative; 'last' baseline mode added
|
| 20 |
+
recicl/context_selector/__init__.py imports made package-relative
|
| 21 |
+
recicl/context_selector/selector.py imports made package-relative
|
| 22 |
+
recicl/util/metrics.py imports made package-relative
|
| 23 |
+
|
| 24 |
+
New files (not from SAP): recicl/__init__.py, recicl/inference.py, recicl/util/__init__.py,
|
| 25 |
+
example.py, config.json, requirements.txt, README.md, eval/results.json.
|
| 26 |
+
|
| 27 |
+
Model weights (model.safetensors): trained by devtaji from random initialisation with SAP's training code (upstream
|
| 28 |
+
commit 1af320c plus patches that do not change the training math: resumable checkpoints, logging, NaN diagnostics and
|
| 29 |
+
an extra evaluation baseline) on a synthetic prior built by devtaji. They are not SAP's weights. SAP SE and the
|
| 30 |
+
RecPFN authors have not reviewed or endorsed this model.
|
| 31 |
+
|
| 32 |
+
The RecPFN paper (arXiv:2608.19735, SIGIR '26) is licensed CC BY-NC-ND 4.0. It is cited, not included.
|
README.md
ADDED
|
@@ -0,0 +1,212 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
license: apache-2.0
|
| 3 |
+
library_name: pytorch
|
| 4 |
+
tags:
|
| 5 |
+
- recommendation
|
| 6 |
+
- recommender-system
|
| 7 |
+
- sequential-recommendation
|
| 8 |
+
- next-item-prediction
|
| 9 |
+
- in-context-learning
|
| 10 |
+
- cold-start
|
| 11 |
+
- prior-fitted-networks
|
| 12 |
+
- recpfn
|
| 13 |
+
datasets:
|
| 14 |
+
- BeIR/fiqa
|
| 15 |
+
- BeIR/quora
|
| 16 |
+
- BeIR/fever
|
| 17 |
+
- BeIR/msmarco
|
| 18 |
+
# base_model: none. Trained from random initialisation;
|
| 19 |
+
---
|
| 20 |
+
|
| 21 |
+
# recICL
|
| 22 |
+
|
| 23 |
+
**recICL is a next-item recommender**. We trained this checkpoint ourselves, from scratch, synthetic-data prior, and packaged it for inference. It takes the text embeddings of a user's recent items plus a few other users' sequences as context. From these it ranks a whole catalog in one forward pass, with no training on that catalog. It has 170M parameters and uses 1536-d item embeddings from `gte-Qwen2-1.5B-instruct`.
|
| 24 |
+
|
| 25 |
+
**Status: v0 research checkpoint.** On our 7 Amazon test sets it is clearly better than a mean-of-history embedding baseline. See [Evaluation](#evaluation) and [Limitations](#limitations).
|
| 26 |
+
|
| 27 |
+
## How it works
|
| 28 |
+
|
| 29 |
+
- **Items are text embeddings only.** No item IDs are learned, so any catalog whose items you can describe in text can be scored. The model expects L2-normalised 1536-d embeddings from [`Alibaba-NLP/gte-Qwen2-1.5B-instruct`](https://huggingface.co/Alibaba-NLP/gte-Qwen2-1.5B-instruct) (settings [below](#item-embeddings)).
|
| 30 |
+
- **Input.**
|
| 31 |
+
- The user's last ≤ 14 items, oldest first.
|
| 32 |
+
- Up to 8 context sequences (≤ 15 items each) from other users of the same catalog. pool sequences that contain one of the user's last 2 items, ranked by recency-weighted Jaccard overlap.
|
| 33 |
+
- **Model.** RecPFN has 4 blocks. In each block:
|
| 34 |
+
- causal self-attention runs over the user's sequence, with hard-ALiBi masks: 4 heads see only the 1–4 most recent positions, and 4 heads see the whole prefix;
|
| 35 |
+
- the same layer also encodes the context sequences;
|
| 36 |
+
- the user's positions then cross-attend to all context positions.
|
| 37 |
+
|
| 38 |
+
- **Output.** Each item's score is the dot product of that vector with the item's embedding, ranked over the full catalog.
|
| 39 |
+
- **Training is prior-fitted.** The model only ever sees synthetic data:
|
| 40 |
+
- Every training batch is a fresh synthetic "environment" of 1,000 items, whose embeddings are drawn from a fixed bank of 800,000 text embeddings.
|
| 41 |
+
- Each environment holds 16 query sequences and 128 context sequences, generated from a random transition structure: random graphs in stage 1, plus latent-factor (concept) structure in stage 2. Popularity bias, recency windows and repeats are also sampled.
|
| 42 |
+
- To predict well, the model has to infer each environment's patterns from the context and the item embeddings. **No real user data was used in training.**
|
| 43 |
+
|
| 44 |
+
## Intended use and vision
|
| 45 |
+
|
| 46 |
+
**Intended use today:** research and prototyping of next-item ranking on text-described catalogs, especially cold-start settings where no per-catalog model can be trained. Evaluate it on your own data before relying on it; see the limitations below.
|
| 47 |
+
|
| 48 |
+
**Vision (roadmap, not current capability).** This checkpoint is the first step towards a personalization layer for AI agents:
|
| 49 |
+
|
| 50 |
+
- an API that ranks the options an agent is about to show a person, personalized from that person's first few actions, with no per-customer training;
|
| 51 |
+
- it improves in two loops: per user instantly, through the context, and across users through post-training on real outcomes, gated offline before release;
|
| 52 |
+
- each ranking comes with a calibrated confidence.
|
| 53 |
+
|
| 54 |
+
Roadmap gates, in order:
|
| 55 |
+
|
| 56 |
+
1. beat the last-item baseline and the RecPFN paper's reported results;
|
| 57 |
+
2. cold start on unseen domains;
|
| 58 |
+
3. a free agent API for agentic shopping;
|
| 59 |
+
4. the post-training loop.
|
| 60 |
+
|
| 61 |
+
v0 has not passed gate 1. It does not beat the last-item baseline on HR@10, and its HR@10 is below the paper's reported RecPFN numbers on 5 of the 7 datasets. That comparison is only indicative, because our data build differs from the paper's. v0 also has no confidence calibration (scores are raw dot products) and no post-training loop.
|
| 62 |
+
|
| 63 |
+
## Quick start
|
| 64 |
+
|
| 65 |
+
```bash
|
| 66 |
+
# if the repo is private, set HF_TOKEN to a token that can read it
|
| 67 |
+
pip install huggingface_hub
|
| 68 |
+
python -c "from huggingface_hub import snapshot_download; snapshot_download('devtaji/recICL', local_dir='recICL')"
|
| 69 |
+
cd recICL
|
| 70 |
+
pip install -r requirements.txt # torch==2.8.0, numpy==1.26.4, safetensors==0.5.3 (tested with Python 3.11)
|
| 71 |
+
python example.py
|
| 72 |
+
```
|
| 73 |
+
|
| 74 |
+
`example.py` loads `config.json` and `model.safetensors` and builds a toy catalog of 500 random vectors. It then retrieves context for a 4-item history and prints the top 10. We ran it in a clean Python 3.11 CPU container that had only `requirements.txt` installed (under 10 s):
|
| 75 |
+
|
| 76 |
+
```
|
| 77 |
+
loaded recICL: 169,918,464 parameters, D=1536, device=cpu
|
| 78 |
+
history: [3, 12, 7, 311]
|
| 79 |
+
context: 8 sequences, e.g. [[7, 311, 45, 90], [12, 7, 311, 45, 88], [311, 45, 88, 402]]
|
| 80 |
+
top-10 items (index, score):
|
| 81 |
+
1. item 311 score 11.281
|
| 82 |
+
2. item 7 score 8.659
|
| 83 |
+
3. item 12 score 5.628
|
| 84 |
+
4. item 45 score 4.301
|
| 85 |
+
5. item 253 score 2.690
|
| 86 |
+
...
|
| 87 |
+
```
|
| 88 |
+
|
| 89 |
+
Item 45 comes 4th, right after the user's own recent items. In this random catalog its embedding is unrelated to the user's items; what links it to the user is the context, where 45 follows 311.
|
| 90 |
+
|
| 91 |
+
With your own catalog, the calls are the same as in `example.py`. Run this from the downloaded folder:
|
| 92 |
+
|
| 93 |
+
```python
|
| 94 |
+
import numpy as np
|
| 95 |
+
import recicl as ir
|
| 96 |
+
|
| 97 |
+
model = ir.load_model(".") # config.json + model.safetensors
|
| 98 |
+
catalog = ir.ItemCatalog(np.load("item_embeddings.npy"), dim=model.input_dim) # your [N, 1536] embeddings, row i = item i
|
| 99 |
+
other_users = [[5, 9, 3, 12], [12, 7, 311, 45, 88]] # other users' item indices, oldest first
|
| 100 |
+
retriever = ir.ContextRetriever(other_users, model.config)
|
| 101 |
+
history = [3, 12, 7, 311] # this user's items, oldest first
|
| 102 |
+
items, scores = ir.recommend(model, catalog, history, retriever.retrieve(history), k=10)
|
| 103 |
+
```
|
| 104 |
+
|
| 105 |
+
`recommend(..., exclude_history=True)` drops items the user already has. The reported evaluation does not do this, because repeat purchases count as hits there. `ir.baseline_scores(catalog, history, mode="last" | "balanced")` gives the two EmbKNN baselines. The model runs on the first CUDA device if there is one; set `CUDA_VISIBLE_DEVICES=""` to force the CPU.
|
| 106 |
+
|
| 107 |
+
### Item embeddings
|
| 108 |
+
|
| 109 |
+
Embed item texts with the same encoder and settings as the training prior:
|
| 110 |
+
|
| 111 |
+
| setting | value |
|
| 112 |
+
|---|---|
|
| 113 |
+
| model | `Alibaba-NLP/gte-Qwen2-1.5B-instruct` at revision `a9af15a6372d7d6b25e9fb07c2ccb9e1fe645644` |
|
| 114 |
+
| remote code | `trust_remote_code=True` (required; the model's own bidirectional code and tokenizer) |
|
| 115 |
+
| prompt | none (document mode) |
|
| 116 |
+
| max tokens | 512 |
|
| 117 |
+
| compute dtype | bf16, output float32 |
|
| 118 |
+
| pooling | last token (`<|endoftext|>`, appended by the tokenizer), right padding |
|
| 119 |
+
| normalisation | L2 |
|
| 120 |
+
| item text in our Amazon evaluation | `Title: {title}; Brand: {brand}; Categories: {c1, c2, ...}` |
|
| 121 |
+
|
| 122 |
+
Vectors from any other encoder will not work without retraining.
|
| 123 |
+
|
| 124 |
+
## Evaluation
|
| 125 |
+
|
| 126 |
+
We evaluated on the TEST split of 7 Amazon Reviews 2018 categories, which we rebuilt from the raw ratings and metadata. The protocol:
|
| 127 |
+
|
| 128 |
+
- **Split:** by user, 70/10/20 (seed 42). At most 10,000 users are sampled into the test split, and users with a single interaction are then dropped. This is why Arts and Pantry evaluate about 3,000 of their 10,000 test users.
|
| 129 |
+
- **Task:** predict each test user's last item from up to 14 preceding items.
|
| 130 |
+
- **Context:** 8 sequences retrieved from train-split users.
|
| 131 |
+
- **Scoring:** batch size 1, ranking over the **full item catalog** (no sampled candidates, repeats allowed), HR@10 and MRR@10.
|
| 132 |
+
- **Hardware:** NVIDIA L4, fp32.
|
| 133 |
+
|
| 134 |
+
The two baselines use the same embeddings:
|
| 135 |
+
- **EmbKNN-bal** scores items against the mean of the history embeddings. Its numbers are close to the "EmbKNN" column of the RecPFN paper's Table 2: within about 10% on the five datasets where our data matches the paper's (see †).
|
| 136 |
+
- **EmbKNN-last** scores items against the last history item only. This is the EmbKNN that the paper's text describes.
|
| 137 |
+
|
| 138 |
+
| Dataset | Test users | HR@10 this model | HR@10 EmbKNN-bal | HR@10 EmbKNN-last | MRR@10 this model | MRR@10 EmbKNN-bal | MRR@10 EmbKNN-last |
|
| 139 |
+
|---|---:|---:|---:|---:|---:|---:|---:|
|
| 140 |
+
| Appliances † | 145 | 0.1034 | 0.0621 | 0.1310 | 0.0543 | 0.0191 | 0.0648 |
|
| 141 |
+
| Arts | 2,997 | 0.2206 | 0.2015 | 0.2179 | 0.1576▲ | 0.1394 | 0.1535 |
|
| 142 |
+
| Games | 10,000 | 0.0722 | 0.0479 | 0.0736 | 0.0461▲ | 0.0164 | 0.0432 |
|
| 143 |
+
| Movies | 10,000 | 0.1237 | 0.0695 | 0.1221 | 0.0683▲ | 0.0248 | 0.0612 |
|
| 144 |
+
| Pantry | 3,106 | 0.2347 | 0.2315 | 0.2389 | 0.1954 | 0.1866 | 0.1955 |
|
| 145 |
+
| Scientific † | 5,619 | 0.0616▼ | 0.0411 | 0.0749 | 0.0339▼ | 0.0162 | 0.0376 |
|
| 146 |
+
| Software | 718 | 0.1574 | 0.1309 | 0.1713 | 0.0992 | 0.0390 | 0.1004 |
|
| 147 |
+
| **Mean (7)** | | **0.1391** | 0.1121 | 0.1471 | **0.0936** | 0.0631 | 0.0937 |
|
| 148 |
+
|
| 149 |
+
▲ / ▼ = significantly better / worse than EmbKNN-last (paired bootstrap over test users, 2,000 resamples, 95% CI excludes 0). Against EmbKNN-bal:
|
| 150 |
+
- HR@10 is significantly better on 5 of 7 datasets (not on Appliances or Pantry);
|
| 151 |
+
- MRR@10 is significantly better on all 7.
|
| 152 |
+
|
| 153 |
+
† **Appliances and Scientific:** our data differs from the paper's. Our EmbKNN-bal HR@10 is 42% (Appliances) and 50% (Scientific) below the paper's value for the same baseline, so our data build differs from the authors'. Their filtering is not fully specified. Appliances has only 145 test users.
|
| 154 |
+
|
| 155 |
+
Per-dataset numbers (HR/MRR @3/5/10, both baselines, paired CIs, McNemar p, and the context ablations under [Limitations](#limitations)) are in [`eval/results.json`](eval/results.json). All the numbers come from our own data build and are not directly comparable to the paper's tables.
|
| 156 |
+
|
| 157 |
+
On a CPU the numbers can differ slightly: Software HR@10 is 0.1560 instead of 0.1574, and Appliances MRR@10 is 0.0681 instead of 0.0543. The cause is duplicated items. Some items have identical embeddings (Software: 21,632 items, 21,342 distinct embeddings; Appliances: 30,238 and 30,063), and CPU and GPU order exactly tied scores differently. The reported values lie within the range that tie order allows.
|
| 158 |
+
|
| 159 |
+
## Limitations
|
| 160 |
+
|
| 161 |
+
- **A trivial baseline beats it on HR@10.** EmbKNN-last, which just recommends items similar to the last item, has higher HR@10 on 5 of 7 datasets, and the 7-dataset mean is 0.1471 vs 0.1391. The gap is significant only on Scientific. On MRR@10 the two are level on average (0.0936 vs 0.0937): the model is significantly better on Arts, Games and Movies and worse on Scientific.
|
| 162 |
+
- **Context helps, but less than in the paper, and bad context hurts a lot.** We ran two context ablations on this checkpoint (TEST, same protocol):
|
| 163 |
+
- Removing the 8 context sequences lowers HR@10 by 1% to 47% per dataset (mean −19% over the 7; significant on 5 of 7, not on Games or Software). It lowers MRR@10 by 8% to 63% (mean −29%; significant on 6 of 7, not on Software). The RecPFN paper reports larger drops for its own model: −38% to −82% HR@10 on the four of these datasets it ablates.
|
| 164 |
+
- Eight randomly chosen context sequences are far worse than none: HR@10 falls by 34% to 86%.
|
| 165 |
+
|
| 166 |
+
So context should come from the same catalog and share items with the user's recent history, as the bundled retriever ensures. Significance here means the paired bootstrap 95% CI over test users excludes 0.
|
| 167 |
+
- **Evaluation data.** For Scientific and Appliances, our data does not match the paper's (see †). The Appliances (145) and Software (718) test sets are small, so their numbers are noisy.
|
| 168 |
+
- **One seed, chosen from nine runs.** We picked this checkpoint as the best of our 9 training runs on validation HR@10 (mean over the 7 Amazon validation splits: 0.1315, rank 1 of 9; MRR@10 0.0884, rank 2), so its test numbers may be slightly optimistic. Across 3 seeds of this configuration, test HR@10 ranges from 0.1034 to 0.1379 on Appliances and from 0.1490 to 0.1630 on Software. This checkpoint is the lowest of the three on Appliances.
|
| 169 |
+
- **Numerical-stability risk.** The architecture has no bound on its attention logits: there is no q/k normalisation and the blocks are post-LN. In 1 of our 9 training runs (not this one), the logits reached about 1e9 and the fp32 fused attention backward pass on an H100 returned garbage gradients, ending in NaN weights. This checkpoint trained without incident. If you fine-tune it, skip steps with non-finite gradients or bound the logits.
|
| 170 |
+
- **Scope.**
|
| 171 |
+
- Only the last 14 history items and 15 items per context sequence are used.
|
| 172 |
+
- It works only with the embedding model above.
|
| 173 |
+
- Scores are uncalibrated dot products.
|
| 174 |
+
- It was evaluated offline, on Amazon product categories only: no online tests, no fairness or safety evaluation.
|
| 175 |
+
- The retriever needs a pool of other users' sequences from the same catalog. Without one the model still runs, but expect roughly the no-context numbers above rather than the table.
|
| 176 |
+
|
| 177 |
+
## Training details
|
| 178 |
+
|
| 179 |
+
| | |
|
| 180 |
+
|---|---|
|
| 181 |
+
| model | `n_layers=4`, `n_heads=8`, D=1536, `icl_module_type='alternating'`, `positional_embedding_scheme='hard-alibi'`, `max_sequence_len=15`, dropout 0.2; 169,918,464 parameters, fp32 |
|
| 182 |
+
| optimisation | AdamW, lr 1e-4 (6 warm-up epochs, then cosine decay to 1e-6), batch 16 query sequences, gradient accumulation 2, full-softmax cross-entropy over each environment's items, training seed 0 |
|
| 183 |
+
| context in training | 128 synthetic sequences per batch (8 at inference) |
|
| 184 |
+
| epoch | 500 training batches + 200 synthetic validation batches |
|
| 185 |
+
| early stopping | patience 20 on the ratio HR@10(model) ÷ HR@10(EmbKNN-bal), measured on synthetic validation batches |
|
| 186 |
+
| stage 1 | random-graph prior; 120 epochs (no early stop), best epoch 101; 2.57 h on 1× NVIDIA H200 |
|
| 187 |
+
| stage 2 | random-graph + latent-factor prior, started from the stage-1 checkpoint; stopped early after 47 epochs, best epoch 27; 1.10 h on 1× NVIDIA H100 80GB |
|
| 188 |
+
| total compute | about 3.7 GPU-hours |
|
| 189 |
+
|
| 190 |
+
The exact prior parameters and all other settings are in [`config.json`](config.json) (`training`).
|
| 191 |
+
|
| 192 |
+
**Synthetic prior provenance.** The environments' item embeddings are drawn from a bank of 800,000 texts that we sampled (seed 0) from four BEIR corpora and embedded with the encoder above:
|
| 193 |
+
|
| 194 |
+
| corpus | texts |
|
| 195 |
+
|---|---:|
|
| 196 |
+
| FiQA-2018 (all non-empty documents and queries) | 64,248 |
|
| 197 |
+
| Quora | 200,000 |
|
| 198 |
+
| FEVER | 200,000 |
|
| 199 |
+
| MS MARCO | 335,752 |
|
| 200 |
+
|
| 201 |
+
The model saw only vectors derived from these texts; neither the texts nor the vectors are in this repository. Each corpus has its own terms. In particular, **MS MARCO is released for non-commercial research purposes only**. If you plan commercial use, check whether weights trained on embeddings of MS MARCO passages are acceptable for your case. No user data of any kind was used in training.
|
| 202 |
+
|
| 203 |
+
|
| 204 |
+
## Files
|
| 205 |
+
|
| 206 |
+
| file | content |
|
| 207 |
+
|---|---|
|
| 208 |
+
| `model.safetensors` | weights, fp32, 64 tensors (sha256 `02c4edc3a4944a9e7a0b6025217b3ea7af16e53c9483e85e9a573074a228a60c`) |
|
| 209 |
+
| `config.json` | architecture, inference and embedding settings, training configuration, evaluation protocol, checksums |
|
| 210 |
+
| `example.py` | the tested quick start |
|
| 211 |
+
| `eval/results.json` | the TEST results above, with all metrics, baselines and paired statistics |
|
| 212 |
+
| `requirements.txt` | `torch`, `numpy`, `safetensors` (pinned, tested) |
|
config.json
ADDED
|
@@ -0,0 +1,233 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"name": "recICL",
|
| 3 |
+
"model_type": "icl-recommender",
|
| 4 |
+
"architecture": "RecPFN",
|
| 5 |
+
"architecture_source": "https://github.com/SAP-samples/tabular-ai-recpfn (upstream commit 1af320c, Apache-2.0)",
|
| 6 |
+
"paper": "arXiv:2608.19735 (SIGIR '26), doi:10.1145/3805712.3809696",
|
| 7 |
+
"embedding_dim": 1536,
|
| 8 |
+
"n_parameters": 169918464,
|
| 9 |
+
"dtype": "float32",
|
| 10 |
+
"model_config": {
|
| 11 |
+
"n_layers": 4,
|
| 12 |
+
"n_heads": 8,
|
| 13 |
+
"dropout": 0.2,
|
| 14 |
+
"icl_module_type": "alternating",
|
| 15 |
+
"positional_embedding_scheme": "hard-alibi",
|
| 16 |
+
"max_sequence_len": 15,
|
| 17 |
+
"train_with_icl": true,
|
| 18 |
+
"num_icl_examples": 8,
|
| 19 |
+
"icl_k": 2,
|
| 20 |
+
"weighted_icl_sampling": true,
|
| 21 |
+
"weighted_decay_rate": 1.0,
|
| 22 |
+
"normalize_embs": true,
|
| 23 |
+
"llm": "qwen1b",
|
| 24 |
+
"baseline_config": "balanced"
|
| 25 |
+
},
|
| 26 |
+
"inference": {
|
| 27 |
+
"history_items_used": 14,
|
| 28 |
+
"context_sequence_max_len": 15,
|
| 29 |
+
"num_context_sequences": 8,
|
| 30 |
+
"context_retrieval": "SAP InvertedIndexMatcher: pool sequences cut into windows of 15 (step 7); candidates share one of the query's last 2 items; top 8 by recency-weighted Jaccard (decay 1.0)",
|
| 31 |
+
"score": "dot product of the output at the last history position with each L2-normalised item embedding"
|
| 32 |
+
},
|
| 33 |
+
"item_embeddings": {
|
| 34 |
+
"model_id": "Alibaba-NLP/gte-Qwen2-1.5B-instruct",
|
| 35 |
+
"revision": "a9af15a6372d7d6b25e9fb07c2ccb9e1fe645644",
|
| 36 |
+
"dim": 1536,
|
| 37 |
+
"trust_remote_code": true,
|
| 38 |
+
"compute_dtype": "bf16",
|
| 39 |
+
"max_seq_length": 512,
|
| 40 |
+
"prompt": null,
|
| 41 |
+
"pooling": "last token (<|endoftext|> appended by the remote-code tokenizer), right padding",
|
| 42 |
+
"normalization": "L2 in fp32",
|
| 43 |
+
"amazon_item_text_format": "Title: {title}; Brand: {brand}; Categories: {c1, c2, ...}"
|
| 44 |
+
},
|
| 45 |
+
"training": {
|
| 46 |
+
"code": "SAP-samples/tabular-ai-recpfn src/ at 1af320c + infrastructure patches (resume, logging, NaN diagnostics; opt-in fixes all OFF) - training math as released",
|
| 47 |
+
"config": {
|
| 48 |
+
"train_with_icl": true,
|
| 49 |
+
"num_icl_examples": 128,
|
| 50 |
+
"train_with_synthetic_data": true,
|
| 51 |
+
"n_layers": 4,
|
| 52 |
+
"batch_size": 16,
|
| 53 |
+
"reg_lambda": 0.0001,
|
| 54 |
+
"warmup_epochs": 6,
|
| 55 |
+
"baseline_config": "balanced",
|
| 56 |
+
"learning_rate": 0.0001,
|
| 57 |
+
"early_stopping_patience": 20,
|
| 58 |
+
"positional_embedding_scheme": "hard-alibi",
|
| 59 |
+
"optimizer": "adamw",
|
| 60 |
+
"llm": "qwen1b",
|
| 61 |
+
"max_sequence_len": 15,
|
| 62 |
+
"num_epochs": 120,
|
| 63 |
+
"use_cached_embeddings": true,
|
| 64 |
+
"num_gradient_accumulation_steps": 2,
|
| 65 |
+
"early_stopping_metric": "hr@10",
|
| 66 |
+
"loss": "sce",
|
| 67 |
+
"train_epoch_size": 500,
|
| 68 |
+
"val_epoch_size": 200,
|
| 69 |
+
"num_sdg_items": 1000,
|
| 70 |
+
"normalize_embs": true,
|
| 71 |
+
"n_heads": 8,
|
| 72 |
+
"dropout": 0.2,
|
| 73 |
+
"icl_module_type": "alternating",
|
| 74 |
+
"val_k": 10
|
| 75 |
+
},
|
| 76 |
+
"training_seed": 0,
|
| 77 |
+
"optimizer": "AdamW (torch defaults besides lr), linear warmup for warmup_epochs, then cosine annealing to 0.01*lr",
|
| 78 |
+
"data": "synthetic sequences only (no real user data); each batch = one synthetic environment of 1000 items whose embeddings are sampled from the embedding store below",
|
| 79 |
+
"embedding_store": {
|
| 80 |
+
"rows": 800000,
|
| 81 |
+
"composition": {
|
| 82 |
+
"fiqa": 64248,
|
| 83 |
+
"quora": 200000,
|
| 84 |
+
"fever": 200000,
|
| 85 |
+
"msmarco": 335752
|
| 86 |
+
},
|
| 87 |
+
"sources": "BEIR (FiQA-2018, Quora, FEVER, MS MARCO), sampled with seed 0",
|
| 88 |
+
"encoder": "same as item_embeddings",
|
| 89 |
+
"sha256": "fb9374462837c1b41188d15d50c55faf04096373f918ea31be57ddcdd6a29620"
|
| 90 |
+
},
|
| 91 |
+
"stages": {
|
| 92 |
+
"stage1": {
|
| 93 |
+
"synthetic_prior": "random graph",
|
| 94 |
+
"sdg_params": {
|
| 95 |
+
"transition_matrix_prior": [
|
| 96 |
+
"random_graph"
|
| 97 |
+
],
|
| 98 |
+
"popularity_bias": [
|
| 99 |
+
0.0,
|
| 100 |
+
0.1,
|
| 101 |
+
0.2,
|
| 102 |
+
0.3,
|
| 103 |
+
0.5
|
| 104 |
+
],
|
| 105 |
+
"window_size": [
|
| 106 |
+
1,
|
| 107 |
+
2,
|
| 108 |
+
3
|
| 109 |
+
],
|
| 110 |
+
"decay_coeff": [
|
| 111 |
+
0.5,
|
| 112 |
+
0.8
|
| 113 |
+
],
|
| 114 |
+
"repeated_items": [
|
| 115 |
+
true
|
| 116 |
+
]
|
| 117 |
+
},
|
| 118 |
+
"init": "random (seed 0)",
|
| 119 |
+
"epochs_run": 120,
|
| 120 |
+
"best_epoch": 101,
|
| 121 |
+
"early_stopped": false,
|
| 122 |
+
"best_synthetic_ratio_hr@10": 7.974883964010977,
|
| 123 |
+
"gpu": [
|
| 124 |
+
"NVIDIA H200"
|
| 125 |
+
],
|
| 126 |
+
"wall_hours": 2.573,
|
| 127 |
+
"first_epoch_end": "2026-09-29T07:33:10Z",
|
| 128 |
+
"finished": "2026-09-29T10:05:54Z"
|
| 129 |
+
},
|
| 130 |
+
"stage2": {
|
| 131 |
+
"synthetic_prior": "random graph + latent factor",
|
| 132 |
+
"sdg_params": {
|
| 133 |
+
"transition_matrix_prior": [
|
| 134 |
+
"random_graph",
|
| 135 |
+
"latent_factor"
|
| 136 |
+
],
|
| 137 |
+
"num_latent_concepts": [
|
| 138 |
+
20,
|
| 139 |
+
40,
|
| 140 |
+
60
|
| 141 |
+
],
|
| 142 |
+
"mean_num_concepts_per_item": [
|
| 143 |
+
2,
|
| 144 |
+
3,
|
| 145 |
+
5
|
| 146 |
+
],
|
| 147 |
+
"mean_num_concepts_per_user": [
|
| 148 |
+
2,
|
| 149 |
+
3,
|
| 150 |
+
5
|
| 151 |
+
],
|
| 152 |
+
"popularity_bias": [
|
| 153 |
+
0.0,
|
| 154 |
+
0.1,
|
| 155 |
+
0.2
|
| 156 |
+
],
|
| 157 |
+
"window_size": [
|
| 158 |
+
1,
|
| 159 |
+
2,
|
| 160 |
+
3
|
| 161 |
+
],
|
| 162 |
+
"decay_coeff": [
|
| 163 |
+
0.5,
|
| 164 |
+
0.8
|
| 165 |
+
],
|
| 166 |
+
"logit_scale": [
|
| 167 |
+
9.0,
|
| 168 |
+
12.0
|
| 169 |
+
],
|
| 170 |
+
"concept_matrix_diagonal_deviation_rate": [
|
| 171 |
+
0.0,
|
| 172 |
+
0.1,
|
| 173 |
+
0.3
|
| 174 |
+
],
|
| 175 |
+
"repeated_items": [
|
| 176 |
+
true
|
| 177 |
+
],
|
| 178 |
+
"mean_num_related_items": [
|
| 179 |
+
1,
|
| 180 |
+
3,
|
| 181 |
+
5,
|
| 182 |
+
7
|
| 183 |
+
],
|
| 184 |
+
"repeated_item_probability": [
|
| 185 |
+
0.1,
|
| 186 |
+
0.2,
|
| 187 |
+
0.3
|
| 188 |
+
]
|
| 189 |
+
},
|
| 190 |
+
"init": "stage-1 best checkpoint (epoch 101)",
|
| 191 |
+
"epochs_run": 47,
|
| 192 |
+
"best_epoch": 27,
|
| 193 |
+
"early_stopped": true,
|
| 194 |
+
"best_synthetic_ratio_hr@10": 3.9308144874246915,
|
| 195 |
+
"gpu": [
|
| 196 |
+
"NVIDIA H100 80GB HBM3"
|
| 197 |
+
],
|
| 198 |
+
"wall_hours": 1.099,
|
| 199 |
+
"first_epoch_end": "2026-09-29T10:07:51Z",
|
| 200 |
+
"finished": "2026-09-29T11:11:55Z"
|
| 201 |
+
}
|
| 202 |
+
},
|
| 203 |
+
"early_stopping": "hr@10 ratio (model / EmbKNN-balanced) on synthetic validation batches, patience 20",
|
| 204 |
+
"selection": {
|
| 205 |
+
"note": "best of our 9 training runs by mean validation HR@10 over the 7 Amazon validation splits",
|
| 206 |
+
"amazon7_val_hr@10": 0.13147873010138936,
|
| 207 |
+
"amazon7_val_hr@10_rank": 1,
|
| 208 |
+
"amazon7_val_mrr@10": 0.0884027748063644,
|
| 209 |
+
"amazon7_val_mrr@10_rank": 2,
|
| 210 |
+
"n_runs": 9
|
| 211 |
+
}
|
| 212 |
+
},
|
| 213 |
+
"evaluation_protocol": {
|
| 214 |
+
"split": "user-level 70/10/20, seed 42; at most 10,000 users sampled into the test split, then users with a single interaction dropped",
|
| 215 |
+
"target": "each test user's last item; input = up to 14 preceding items",
|
| 216 |
+
"context": "8 sequences from train-split users (retrieval as in 'inference')",
|
| 217 |
+
"batch_size": 1,
|
| 218 |
+
"ranking": "full item catalog, no candidate sampling, repeated items allowed",
|
| 219 |
+
"metrics": [
|
| 220 |
+
"HR@10",
|
| 221 |
+
"MRR@10"
|
| 222 |
+
],
|
| 223 |
+
"hardware": "NVIDIA L4, fp32, TF32 off"
|
| 224 |
+
},
|
| 225 |
+
"checkpoint": {
|
| 226 |
+
"source": "release_k4_s0/stage2/model.pth",
|
| 227 |
+
"source_sha256": "661fd3415a0b8f2d727898006e6314dcd273e15f59da3383668f7bc1a3997a3a",
|
| 228 |
+
"safetensors_sha256": "02c4edc3a4944a9e7a0b6025217b3ea7af16e53c9483e85e9a573074a228a60c",
|
| 229 |
+
"safetensors_bytes": 679680696,
|
| 230 |
+
"n_tensors": 64,
|
| 231 |
+
"src_fingerprint": "6c3ca6431e028e27"
|
| 232 |
+
}
|
| 233 |
+
}
|
eval/results.json
ADDED
|
@@ -0,0 +1,699 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
{
|
| 2 |
+
"model": "devtaji/recICL",
|
| 3 |
+
"checkpoint_sha256": "661fd3415a0b8f2d727898006e6314dcd273e15f59da3383668f7bc1a3997a3a",
|
| 4 |
+
"split": "test",
|
| 5 |
+
"protocol": {
|
| 6 |
+
"split": "user-level 70/10/20, seed 42; at most 10,000 users sampled into the test split, then users with a single interaction dropped",
|
| 7 |
+
"target": "each test user's last item; input = up to 14 preceding items",
|
| 8 |
+
"context": "8 sequences from train-split users (retrieval as in 'inference')",
|
| 9 |
+
"batch_size": 1,
|
| 10 |
+
"ranking": "full item catalog, no candidate sampling, repeated items allowed",
|
| 11 |
+
"metrics": [
|
| 12 |
+
"HR@10",
|
| 13 |
+
"MRR@10"
|
| 14 |
+
],
|
| 15 |
+
"hardware": "NVIDIA L4, fp32, TF32 off"
|
| 16 |
+
},
|
| 17 |
+
"baselines": {
|
| 18 |
+
"embknn_balanced": "score = dot(mean of the history item embeddings, item embedding); its numbers are close to the EmbKNN column of the RecPFN paper's Table 2 (within about 10% on Arts, Games, Movies, Pantry, Software)",
|
| 19 |
+
"embknn_last": "score = dot(last history item embedding, item embedding); the EmbKNN that the RecPFN paper's text describes"
|
| 20 |
+
},
|
| 21 |
+
"datasets_source": "Amazon Reviews 2018 (McAuley et al.) categories, rebuilt from the raw ratings + metadata: Appliances, Arts_Crafts_and_Sewing, Video_Games, Movies_and_TV, Prime_Pantry, Industrial_and_Scientific, Software",
|
| 22 |
+
"paired_differences_note": "model minus baseline, paired bootstrap over test users (2,000 resamples), 95% CI; McNemar exact p on HR@10 hits",
|
| 23 |
+
"datasets": {
|
| 24 |
+
"Appliances": {
|
| 25 |
+
"n_test_users_evaluated": 145,
|
| 26 |
+
"n_test_users_in_split": 145,
|
| 27 |
+
"flag": "evaluation data differs from the RecPFN paper's (undisclosed filtering)",
|
| 28 |
+
"recicl_v0": {
|
| 29 |
+
"hr@3": 0.06206896551724138,
|
| 30 |
+
"hr@5": 0.06896551724137931,
|
| 31 |
+
"hr@10": 0.10344827586206896,
|
| 32 |
+
"mrr@3": 0.04827586206896552,
|
| 33 |
+
"mrr@5": 0.04965517243434643,
|
| 34 |
+
"mrr@10": 0.05434865910431434,
|
| 35 |
+
"loss": 9.28750396761401
|
| 36 |
+
},
|
| 37 |
+
"embknn_balanced": {
|
| 38 |
+
"hr@3": 0.027586206896551724,
|
| 39 |
+
"hr@5": 0.041379310344827586,
|
| 40 |
+
"hr@10": 0.06206896551724138,
|
| 41 |
+
"mrr@3": 0.013793103448275862,
|
| 42 |
+
"mrr@5": 0.016551724179037688,
|
| 43 |
+
"mrr@10": 0.01906951295918432,
|
| 44 |
+
"loss": 10.228556942117626
|
| 45 |
+
},
|
| 46 |
+
"embknn_last": {
|
| 47 |
+
"hr@3": 0.09655172413793103,
|
| 48 |
+
"hr@5": 0.1103448275862069,
|
| 49 |
+
"hr@10": 0.1310344827586207,
|
| 50 |
+
"mrr@3": 0.05862068986070567,
|
| 51 |
+
"mrr@5": 0.062068965722774636,
|
| 52 |
+
"mrr@10": 0.06475095810561345,
|
| 53 |
+
"loss": 10.193267019863786
|
| 54 |
+
},
|
| 55 |
+
"paired_differences_95ci": {
|
| 56 |
+
"vs_embknn_last": {
|
| 57 |
+
"d_hr@10": -0.027586206896551738,
|
| 58 |
+
"d_hr@10_ci": [
|
| 59 |
+
-0.06206896551724139,
|
| 60 |
+
0.0
|
| 61 |
+
],
|
| 62 |
+
"d_mrr@10": -0.010402298850574712,
|
| 63 |
+
"d_mrr@10_ci": [
|
| 64 |
+
-0.023873084291187747,
|
| 65 |
+
0.0023036398467432624
|
| 66 |
+
],
|
| 67 |
+
"mcnemar_p": 0.21875000000000014
|
| 68 |
+
},
|
| 69 |
+
"vs_embknn_balanced": {
|
| 70 |
+
"d_hr@10": 0.041379310344827586,
|
| 71 |
+
"d_hr@10_ci": [
|
| 72 |
+
0.0,
|
| 73 |
+
0.08275862068965519
|
| 74 |
+
],
|
| 75 |
+
"d_mrr@10": 0.035279146141215106,
|
| 76 |
+
"d_mrr@10_ci": [
|
| 77 |
+
0.007594074986316366,
|
| 78 |
+
0.06752230432402839
|
| 79 |
+
],
|
| 80 |
+
"mcnemar_p": 0.109375
|
| 81 |
+
}
|
| 82 |
+
},
|
| 83 |
+
"eval_gpu": "NVIDIA L4",
|
| 84 |
+
"evaluated_at": "2026-09-29T11:12:17Z",
|
| 85 |
+
"context_ablations": {
|
| 86 |
+
"no_context": {
|
| 87 |
+
"hr@10": 0.05517241379310345,
|
| 88 |
+
"mrr@10": 0.020000000092489967,
|
| 89 |
+
"pct_change_hr@10": -46.666666666666664,
|
| 90 |
+
"pct_change_hr@10_ci95": [
|
| 91 |
+
-75.0,
|
| 92 |
+
-14.261904761904896
|
| 93 |
+
],
|
| 94 |
+
"pct_change_mrr@10": -63.200563873888996,
|
| 95 |
+
"pct_change_mrr@10_ci95": [
|
| 96 |
+
-91.32381136817679,
|
| 97 |
+
-33.380598313527344
|
| 98 |
+
],
|
| 99 |
+
"mean_context_sequences": 0.0
|
| 100 |
+
},
|
| 101 |
+
"random_context": {
|
| 102 |
+
"hr@10": 0.041379310344827586,
|
| 103 |
+
"mrr@10": 0.03103448275862069,
|
| 104 |
+
"pct_change_hr@10": -60.0,
|
| 105 |
+
"pct_change_hr@10_ci95": [
|
| 106 |
+
-85.71428571428572,
|
| 107 |
+
-33.333333333333336
|
| 108 |
+
],
|
| 109 |
+
"pct_change_mrr@10": -42.897426964933,
|
| 110 |
+
"pct_change_mrr@10_ci95": [
|
| 111 |
+
-81.16710629577956,
|
| 112 |
+
6.011155432140703
|
| 113 |
+
],
|
| 114 |
+
"mean_context_sequences": 8.0
|
| 115 |
+
}
|
| 116 |
+
}
|
| 117 |
+
},
|
| 118 |
+
"Arts": {
|
| 119 |
+
"n_test_users_evaluated": 2997,
|
| 120 |
+
"n_test_users_in_split": 10000,
|
| 121 |
+
"flag": null,
|
| 122 |
+
"recicl_v0": {
|
| 123 |
+
"hr@3": 0.1871871871871872,
|
| 124 |
+
"hr@5": 0.20186853520186854,
|
| 125 |
+
"hr@10": 0.22055388722055388,
|
| 126 |
+
"mrr@3": 0.15170726306366053,
|
| 127 |
+
"mrr@5": 0.15502724973786303,
|
| 128 |
+
"mrr@10": 0.15758139124245177,
|
| 129 |
+
"loss": 10.023291922466811
|
| 130 |
+
},
|
| 131 |
+
"embknn_balanced": {
|
| 132 |
+
"hr@3": 0.16049382716049382,
|
| 133 |
+
"hr@5": 0.1828495161828495,
|
| 134 |
+
"hr@10": 0.20153486820153488,
|
| 135 |
+
"mrr@3": 0.131854076474199,
|
| 136 |
+
"mrr@5": 0.1367589814198745,
|
| 137 |
+
"mrr@10": 0.1393652915019849,
|
| 138 |
+
"loss": 12.450908683481558
|
| 139 |
+
},
|
| 140 |
+
"embknn_last": {
|
| 141 |
+
"hr@3": 0.17450784117450785,
|
| 142 |
+
"hr@5": 0.19953286619953287,
|
| 143 |
+
"hr@10": 0.21788455121788455,
|
| 144 |
+
"mrr@3": 0.14547881232447174,
|
| 145 |
+
"mrr@5": 0.15100100122374777,
|
| 146 |
+
"mrr@10": 0.153521643620274,
|
| 147 |
+
"loss": 12.435229098116672
|
| 148 |
+
},
|
| 149 |
+
"paired_differences_95ci": {
|
| 150 |
+
"vs_embknn_last": {
|
| 151 |
+
"d_hr@10": 0.0026693360026693314,
|
| 152 |
+
"d_hr@10_ci": [
|
| 153 |
+
-0.003336670003336678,
|
| 154 |
+
0.00934267600934266
|
| 155 |
+
],
|
| 156 |
+
"d_mrr@10": 0.004059747578266104,
|
| 157 |
+
"d_mrr@10_ci": [
|
| 158 |
+
0.0016380765686321512,
|
| 159 |
+
0.006624263152040991
|
| 160 |
+
],
|
| 161 |
+
"mcnemar_p": 0.46570744577306067
|
| 162 |
+
},
|
| 163 |
+
"vs_embknn_balanced": {
|
| 164 |
+
"d_hr@10": 0.019019019019019007,
|
| 165 |
+
"d_hr@10_ci": [
|
| 166 |
+
0.01167834501167836,
|
| 167 |
+
0.026359693026359682
|
| 168 |
+
],
|
| 169 |
+
"d_mrr@10": 0.018216099697581145,
|
| 170 |
+
"d_mrr@10_ci": [
|
| 171 |
+
0.014113558002446853,
|
| 172 |
+
0.022250213176138966
|
| 173 |
+
],
|
| 174 |
+
"mcnemar_p": 4.3609050114828154e-07
|
| 175 |
+
}
|
| 176 |
+
},
|
| 177 |
+
"eval_gpu": "NVIDIA L4",
|
| 178 |
+
"evaluated_at": "2026-09-29T11:15:00Z",
|
| 179 |
+
"context_ablations": {
|
| 180 |
+
"no_context": {
|
| 181 |
+
"hr@10": 0.18618618618618618,
|
| 182 |
+
"mrr@10": 0.12968577070408438,
|
| 183 |
+
"pct_change_hr@10": -15.582450832072613,
|
| 184 |
+
"pct_change_hr@10_ci95": [
|
| 185 |
+
-19.082868467410457,
|
| 186 |
+
-12.157674772036467
|
| 187 |
+
],
|
| 188 |
+
"pct_change_mrr@10": -17.702357060325546,
|
| 189 |
+
"pct_change_mrr@10_ci95": [
|
| 190 |
+
-20.833086015350958,
|
| 191 |
+
-14.734061825197962
|
| 192 |
+
],
|
| 193 |
+
"mean_context_sequences": 0.0
|
| 194 |
+
},
|
| 195 |
+
"random_context": {
|
| 196 |
+
"hr@10": 0.08541875208541876,
|
| 197 |
+
"mrr@10": 0.048784234107017994,
|
| 198 |
+
"pct_change_hr@10": -61.27080181543116,
|
| 199 |
+
"pct_change_hr@10_ci95": [
|
| 200 |
+
-64.90455212922173,
|
| 201 |
+
-57.557142362952874
|
| 202 |
+
],
|
| 203 |
+
"pct_change_mrr@10": -69.0418813272441,
|
| 204 |
+
"pct_change_mrr@10_ci95": [
|
| 205 |
+
-72.615949611093,
|
| 206 |
+
-65.57546376581101
|
| 207 |
+
],
|
| 208 |
+
"mean_context_sequences": 8.0
|
| 209 |
+
}
|
| 210 |
+
}
|
| 211 |
+
},
|
| 212 |
+
"Games": {
|
| 213 |
+
"n_test_users_evaluated": 10000,
|
| 214 |
+
"n_test_users_in_split": 10000,
|
| 215 |
+
"flag": null,
|
| 216 |
+
"recicl_v0": {
|
| 217 |
+
"hr@3": 0.0513,
|
| 218 |
+
"hr@5": 0.0588,
|
| 219 |
+
"hr@10": 0.0722,
|
| 220 |
+
"mrr@3": 0.04260000007748604,
|
| 221 |
+
"mrr@5": 0.044295000088214874,
|
| 222 |
+
"mrr@10": 0.046121071556210515,
|
| 223 |
+
"loss": 10.213145974993706
|
| 224 |
+
},
|
| 225 |
+
"embknn_balanced": {
|
| 226 |
+
"hr@3": 0.02,
|
| 227 |
+
"hr@5": 0.0303,
|
| 228 |
+
"hr@10": 0.0479,
|
| 229 |
+
"mrr@3": 0.011700000071525574,
|
| 230 |
+
"mrr@5": 0.014055000084638596,
|
| 231 |
+
"mrr@10": 0.01636996045857668,
|
| 232 |
+
"loss": 11.093444060993194
|
| 233 |
+
},
|
| 234 |
+
"embknn_last": {
|
| 235 |
+
"hr@3": 0.0506,
|
| 236 |
+
"hr@5": 0.0585,
|
| 237 |
+
"hr@10": 0.0736,
|
| 238 |
+
"mrr@3": 0.03945000005960465,
|
| 239 |
+
"mrr@5": 0.04121000007241964,
|
| 240 |
+
"mrr@10": 0.04316595249548554,
|
| 241 |
+
"loss": 11.0686561044693
|
| 242 |
+
},
|
| 243 |
+
"paired_differences_95ci": {
|
| 244 |
+
"vs_embknn_last": {
|
| 245 |
+
"d_hr@10": -0.0013999999999999985,
|
| 246 |
+
"d_hr@10_ci": [
|
| 247 |
+
-0.004699999999999996,
|
| 248 |
+
0.0020000000000000018
|
| 249 |
+
],
|
| 250 |
+
"d_mrr@10": 0.002955119047619019,
|
| 251 |
+
"d_mrr@10_ci": [
|
| 252 |
+
0.00160891765873009,
|
| 253 |
+
0.004420426587301565
|
| 254 |
+
],
|
| 255 |
+
"mcnemar_p": 0.43727338509353675
|
| 256 |
+
},
|
| 257 |
+
"vs_embknn_balanced": {
|
| 258 |
+
"d_hr@10": 0.024300000000000002,
|
| 259 |
+
"d_hr@10_ci": [
|
| 260 |
+
0.019600000000000006,
|
| 261 |
+
0.0288
|
| 262 |
+
],
|
| 263 |
+
"d_mrr@10": 0.029751111111111096,
|
| 264 |
+
"d_mrr@10_ci": [
|
| 265 |
+
0.026522191468253967,
|
| 266 |
+
0.03297455158730153
|
| 267 |
+
],
|
| 268 |
+
"mcnemar_p": 1.5319468898317913e-25
|
| 269 |
+
}
|
| 270 |
+
},
|
| 271 |
+
"eval_gpu": "NVIDIA L4",
|
| 272 |
+
"evaluated_at": "2026-09-29T11:16:13Z",
|
| 273 |
+
"context_ablations": {
|
| 274 |
+
"no_context": {
|
| 275 |
+
"hr@10": 0.0716,
|
| 276 |
+
"mrr@10": 0.03594726204872131,
|
| 277 |
+
"pct_change_hr@10": -0.8310249307479256,
|
| 278 |
+
"pct_change_hr@10_ci95": [
|
| 279 |
+
-5.364047361136176,
|
| 280 |
+
3.841910853289687
|
| 281 |
+
],
|
| 282 |
+
"pct_change_mrr@10": -22.058918329965017,
|
| 283 |
+
"pct_change_mrr@10_ci95": [
|
| 284 |
+
-25.54905745074236,
|
| 285 |
+
-18.56859102137774
|
| 286 |
+
],
|
| 287 |
+
"mean_context_sequences": 0.0
|
| 288 |
+
},
|
| 289 |
+
"random_context": {
|
| 290 |
+
"hr@10": 0.0119,
|
| 291 |
+
"mrr@10": 0.004851468288898468,
|
| 292 |
+
"pct_change_hr@10": -83.5180055401662,
|
| 293 |
+
"pct_change_hr@10_ci95": [
|
| 294 |
+
-86.22530832926526,
|
| 295 |
+
-80.73741871966297
|
| 296 |
+
],
|
| 297 |
+
"pct_change_mrr@10": -89.4810156720108,
|
| 298 |
+
"pct_change_mrr@10_ci95": [
|
| 299 |
+
-91.75046365557786,
|
| 300 |
+
-87.02863863527669
|
| 301 |
+
],
|
| 302 |
+
"mean_context_sequences": 8.0
|
| 303 |
+
}
|
| 304 |
+
}
|
| 305 |
+
},
|
| 306 |
+
"Movies": {
|
| 307 |
+
"n_test_users_evaluated": 10000,
|
| 308 |
+
"n_test_users_in_split": 10000,
|
| 309 |
+
"flag": null,
|
| 310 |
+
"recicl_v0": {
|
| 311 |
+
"hr@3": 0.0951,
|
| 312 |
+
"hr@5": 0.1096,
|
| 313 |
+
"hr@10": 0.1237,
|
| 314 |
+
"mrr@3": 0.06308333349823951,
|
| 315 |
+
"mrr@5": 0.06639833351671695,
|
| 316 |
+
"mrr@10": 0.0683068653061986,
|
| 317 |
+
"loss": 10.933070637273788
|
| 318 |
+
},
|
| 319 |
+
"embknn_balanced": {
|
| 320 |
+
"hr@3": 0.0335,
|
| 321 |
+
"hr@5": 0.0491,
|
| 322 |
+
"hr@10": 0.0695,
|
| 323 |
+
"mrr@3": 0.018566666802763938,
|
| 324 |
+
"mrr@5": 0.02212666682302952,
|
| 325 |
+
"mrr@10": 0.02482007957994938,
|
| 326 |
+
"loss": 12.046554122447967
|
| 327 |
+
},
|
| 328 |
+
"embknn_last": {
|
| 329 |
+
"hr@3": 0.0778,
|
| 330 |
+
"hr@5": 0.1049,
|
| 331 |
+
"hr@10": 0.1221,
|
| 332 |
+
"mrr@3": 0.05258333346545696,
|
| 333 |
+
"mrr@5": 0.058868333494663236,
|
| 334 |
+
"mrr@10": 0.061181428787857296,
|
| 335 |
+
"loss": 12.016274190807342
|
| 336 |
+
},
|
| 337 |
+
"paired_differences_95ci": {
|
| 338 |
+
"vs_embknn_last": {
|
| 339 |
+
"d_hr@10": 0.0016000000000000042,
|
| 340 |
+
"d_hr@10_ci": [
|
| 341 |
+
-0.0011999999999999932,
|
| 342 |
+
0.00449999999999999
|
| 343 |
+
],
|
| 344 |
+
"d_mrr@10": 0.0071254365079365944,
|
| 345 |
+
"d_mrr@10_ci": [
|
| 346 |
+
0.005697232142857268,
|
| 347 |
+
0.008514329365079398
|
| 348 |
+
],
|
| 349 |
+
"mcnemar_p": 0.3029036319209554
|
| 350 |
+
},
|
| 351 |
+
"vs_embknn_balanced": {
|
| 352 |
+
"d_hr@10": 0.0542,
|
| 353 |
+
"d_hr@10_ci": [
|
| 354 |
+
0.04870000000000001,
|
| 355 |
+
0.05929999999999999
|
| 356 |
+
],
|
| 357 |
+
"d_mrr@10": 0.04348678571428581,
|
| 358 |
+
"d_mrr@10_ci": [
|
| 359 |
+
0.0402409722222223,
|
| 360 |
+
0.046700817460317574
|
| 361 |
+
],
|
| 362 |
+
"mcnemar_p": 1.4361709413897885e-91
|
| 363 |
+
}
|
| 364 |
+
},
|
| 365 |
+
"eval_gpu": "NVIDIA L4",
|
| 366 |
+
"evaluated_at": "2026-09-29T11:17:56Z",
|
| 367 |
+
"context_ablations": {
|
| 368 |
+
"no_context": {
|
| 369 |
+
"hr@10": 0.102,
|
| 370 |
+
"mrr@10": 0.04952440501749516,
|
| 371 |
+
"pct_change_hr@10": -17.542441390460805,
|
| 372 |
+
"pct_change_hr@10_ci95": [
|
| 373 |
+
-20.496807702572312,
|
| 374 |
+
-14.590643244107216
|
| 375 |
+
],
|
| 376 |
+
"pct_change_mrr@10": -27.497177925685023,
|
| 377 |
+
"pct_change_mrr@10_ci95": [
|
| 378 |
+
-30.157991463516414,
|
| 379 |
+
-24.89154990329349
|
| 380 |
+
],
|
| 381 |
+
"mean_context_sequences": 0.0
|
| 382 |
+
},
|
| 383 |
+
"random_context": {
|
| 384 |
+
"hr@10": 0.0179,
|
| 385 |
+
"mrr@10": 0.010642261940985918,
|
| 386 |
+
"pct_change_hr@10": -85.52950687146321,
|
| 387 |
+
"pct_change_hr@10_ci95": [
|
| 388 |
+
-87.47939468293607,
|
| 389 |
+
-83.4124518447913
|
| 390 |
+
],
|
| 391 |
+
"pct_change_mrr@10": -84.419923395284,
|
| 392 |
+
"pct_change_mrr@10_ci95": [
|
| 393 |
+
-86.68075954394435,
|
| 394 |
+
-81.80099004889513
|
| 395 |
+
],
|
| 396 |
+
"mean_context_sequences": 8.0
|
| 397 |
+
}
|
| 398 |
+
}
|
| 399 |
+
},
|
| 400 |
+
"Pantry": {
|
| 401 |
+
"n_test_users_evaluated": 3106,
|
| 402 |
+
"n_test_users_in_split": 10000,
|
| 403 |
+
"flag": null,
|
| 404 |
+
"recicl_v0": {
|
| 405 |
+
"hr@3": 0.2063747585318738,
|
| 406 |
+
"hr@5": 0.2169993560849968,
|
| 407 |
+
"hr@10": 0.2347070186735351,
|
| 408 |
+
"mrr@3": 0.190759819809345,
|
| 409 |
+
"mrr@5": 0.19320669683405298,
|
| 410 |
+
"mrr@10": 0.19541504426456927,
|
| 411 |
+
"loss": 7.7768060520089834
|
| 412 |
+
},
|
| 413 |
+
"embknn_balanced": {
|
| 414 |
+
"hr@3": 0.19639407598197037,
|
| 415 |
+
"hr@5": 0.20927237604636187,
|
| 416 |
+
"hr@10": 0.23148744365743723,
|
| 417 |
+
"mrr@3": 0.1807791372882268,
|
| 418 |
+
"mrr@5": 0.18370895057014702,
|
| 419 |
+
"mrr@10": 0.18661793887720748,
|
| 420 |
+
"loss": 9.150342638233134
|
| 421 |
+
},
|
| 422 |
+
"embknn_last": {
|
| 423 |
+
"hr@3": 0.20573084352865423,
|
| 424 |
+
"hr@5": 0.2189311010946555,
|
| 425 |
+
"hr@10": 0.23889246619446233,
|
| 426 |
+
"mrr@3": 0.1899012664941074,
|
| 427 |
+
"mrr@5": 0.19294376489967205,
|
| 428 |
+
"mrr@10": 0.19550230500875407,
|
| 429 |
+
"loss": 9.141914023173983
|
| 430 |
+
},
|
| 431 |
+
"paired_differences_95ci": {
|
| 432 |
+
"vs_embknn_last": {
|
| 433 |
+
"d_hr@10": -0.004185447520927227,
|
| 434 |
+
"d_hr@10_ci": [
|
| 435 |
+
-0.008692852543464247,
|
| 436 |
+
0.0003219575016097931
|
| 437 |
+
],
|
| 438 |
+
"d_mrr@10": -8.726070380921103e-05,
|
| 439 |
+
"d_mrr@10_ci": [
|
| 440 |
+
-0.0011988125900714338,
|
| 441 |
+
0.0010856164208545979
|
| 442 |
+
],
|
| 443 |
+
"mcnemar_p": 0.07894069368148691
|
| 444 |
+
},
|
| 445 |
+
"vs_embknn_balanced": {
|
| 446 |
+
"d_hr@10": 0.0032195750160978753,
|
| 447 |
+
"d_hr@10_ci": [
|
| 448 |
+
-0.0028976175144880822,
|
| 449 |
+
0.009014810045074068
|
| 450 |
+
],
|
| 451 |
+
"d_mrr@10": 0.008797105448747455,
|
| 452 |
+
"d_mrr@10_ci": [
|
| 453 |
+
0.0058886282566257536,
|
| 454 |
+
0.011998394684123979
|
| 455 |
+
],
|
| 456 |
+
"mcnemar_p": 0.34814129031920826
|
| 457 |
+
}
|
| 458 |
+
},
|
| 459 |
+
"eval_gpu": "NVIDIA L4",
|
| 460 |
+
"evaluated_at": "2026-09-29T11:13:21Z",
|
| 461 |
+
"context_ablations": {
|
| 462 |
+
"no_context": {
|
| 463 |
+
"hr@10": 0.19671603348358016,
|
| 464 |
+
"mrr@10": 0.15395381714229958,
|
| 465 |
+
"pct_change_hr@10": -16.18655692729768,
|
| 466 |
+
"pct_change_hr@10_ci95": [
|
| 467 |
+
-19.264387170902758,
|
| 468 |
+
-13.167998565647263
|
| 469 |
+
],
|
| 470 |
+
"pct_change_mrr@10": -21.21700879187991,
|
| 471 |
+
"pct_change_mrr@10_ci95": [
|
| 472 |
+
-24.17786279642231,
|
| 473 |
+
-18.26020458277787
|
| 474 |
+
],
|
| 475 |
+
"mean_context_sequences": 0.0
|
| 476 |
+
},
|
| 477 |
+
"random_context": {
|
| 478 |
+
"hr@10": 0.15421764327108822,
|
| 479 |
+
"mrr@10": 0.1047861795327929,
|
| 480 |
+
"pct_change_hr@10": -34.293552812071326,
|
| 481 |
+
"pct_change_hr@10_ci95": [
|
| 482 |
+
-37.772055176467944,
|
| 483 |
+
-30.716229295376298
|
| 484 |
+
],
|
| 485 |
+
"pct_change_mrr@10": -46.37762925206281,
|
| 486 |
+
"pct_change_mrr@10_ci95": [
|
| 487 |
+
-49.80445898826904,
|
| 488 |
+
-43.037569407074
|
| 489 |
+
],
|
| 490 |
+
"mean_context_sequences": 8.0
|
| 491 |
+
}
|
| 492 |
+
}
|
| 493 |
+
},
|
| 494 |
+
"Scientific": {
|
| 495 |
+
"n_test_users_evaluated": 5619,
|
| 496 |
+
"n_test_users_in_split": 5619,
|
| 497 |
+
"flag": "evaluation data differs from the RecPFN paper's (undisclosed filtering)",
|
| 498 |
+
"recicl_v0": {
|
| 499 |
+
"hr@3": 0.043602064424274785,
|
| 500 |
+
"hr@5": 0.05089873642996975,
|
| 501 |
+
"hr@10": 0.06157679302366969,
|
| 502 |
+
"mrr@3": 0.030758735298325443,
|
| 503 |
+
"mrr@5": 0.032431630840354976,
|
| 504 |
+
"mrr@10": 0.033883832448115235,
|
| 505 |
+
"loss": 11.270965716363188
|
| 506 |
+
},
|
| 507 |
+
"embknn_balanced": {
|
| 508 |
+
"hr@3": 0.023313756896244882,
|
| 509 |
+
"hr@5": 0.029364655632674853,
|
| 510 |
+
"hr@10": 0.041110517885744796,
|
| 511 |
+
"mrr@3": 0.01319926444651245,
|
| 512 |
+
"mrr@5": 0.014614106951011927,
|
| 513 |
+
"mrr@10": 0.016231917315561336,
|
| 514 |
+
"loss": 11.957719512629879
|
| 515 |
+
},
|
| 516 |
+
"embknn_last": {
|
| 517 |
+
"hr@3": 0.05196654208933974,
|
| 518 |
+
"hr@5": 0.06371240434240968,
|
| 519 |
+
"hr@10": 0.07492436376579463,
|
| 520 |
+
"mrr@3": 0.03336892694547775,
|
| 521 |
+
"mrr@5": 0.036029542729849914,
|
| 522 |
+
"mrr@10": 0.037563454074025004,
|
| 523 |
+
"loss": 11.922406332712196
|
| 524 |
+
},
|
| 525 |
+
"paired_differences_95ci": {
|
| 526 |
+
"vs_embknn_last": {
|
| 527 |
+
"d_hr@10": -0.013347570742124941,
|
| 528 |
+
"d_hr@10_ci": [
|
| 529 |
+
-0.017262858159814917,
|
| 530 |
+
-0.009432283324434958
|
| 531 |
+
],
|
| 532 |
+
"d_mrr@10": -0.003679621578713932,
|
| 533 |
+
"d_mrr@10_ci": [
|
| 534 |
+
-0.0055008781854083595,
|
| 535 |
+
-0.0017209008833408014
|
| 536 |
+
],
|
| 537 |
+
"mcnemar_p": 1.8819747521132367e-11
|
| 538 |
+
},
|
| 539 |
+
"vs_embknn_balanced": {
|
| 540 |
+
"d_hr@10": 0.020466275137924893,
|
| 541 |
+
"d_hr@10_ci": [
|
| 542 |
+
0.015127246841074922,
|
| 543 |
+
0.025627335824879874
|
| 544 |
+
],
|
| 545 |
+
"d_mrr@10": 0.017651915129224236,
|
| 546 |
+
"d_mrr@10_ci": [
|
| 547 |
+
0.01421929070020367,
|
| 548 |
+
0.02114898572586773
|
| 549 |
+
],
|
| 550 |
+
"mcnemar_p": 8.883400844804864e-14
|
| 551 |
+
}
|
| 552 |
+
},
|
| 553 |
+
"eval_gpu": "NVIDIA L4",
|
| 554 |
+
"evaluated_at": "2026-09-29T11:14:55Z",
|
| 555 |
+
"context_ablations": {
|
| 556 |
+
"no_context": {
|
| 557 |
+
"hr@10": 0.041110517885744796,
|
| 558 |
+
"mrr@10": 0.01950525012033693,
|
| 559 |
+
"pct_change_hr@10": -33.23699421965317,
|
| 560 |
+
"pct_change_hr@10_ci95": [
|
| 561 |
+
-39.64649321266968,
|
| 562 |
+
-26.436781609195403
|
| 563 |
+
],
|
| 564 |
+
"pct_change_mrr@10": -42.43493515615617,
|
| 565 |
+
"pct_change_mrr@10_ci95": [
|
| 566 |
+
-49.3741780404384,
|
| 567 |
+
-35.22245199758977
|
| 568 |
+
],
|
| 569 |
+
"mean_context_sequences": 0.0
|
| 570 |
+
},
|
| 571 |
+
"random_context": {
|
| 572 |
+
"hr@10": 0.019754404698344902,
|
| 573 |
+
"mrr@10": 0.007489329049820195,
|
| 574 |
+
"pct_change_hr@10": -67.91907514450867,
|
| 575 |
+
"pct_change_hr@10_ci95": [
|
| 576 |
+
-73.18456788046039,
|
| 577 |
+
-62.63396894784444
|
| 578 |
+
],
|
| 579 |
+
"pct_change_mrr@10": -77.89704260494068,
|
| 580 |
+
"pct_change_mrr@10_ci95": [
|
| 581 |
+
-82.35918468816068,
|
| 582 |
+
-73.04899679853824
|
| 583 |
+
],
|
| 584 |
+
"mean_context_sequences": 8.0
|
| 585 |
+
}
|
| 586 |
+
}
|
| 587 |
+
},
|
| 588 |
+
"Software": {
|
| 589 |
+
"n_test_users_evaluated": 718,
|
| 590 |
+
"n_test_users_in_split": 718,
|
| 591 |
+
"flag": null,
|
| 592 |
+
"recicl_v0": {
|
| 593 |
+
"hr@3": 0.10167130919220056,
|
| 594 |
+
"hr@5": 0.12256267409470752,
|
| 595 |
+
"hr@10": 0.1573816155988858,
|
| 596 |
+
"mrr@3": 0.08983286916379477,
|
| 597 |
+
"mrr@5": 0.0945682452374182,
|
| 598 |
+
"mrr@10": 0.09920911284417827,
|
| 599 |
+
"loss": 8.473287451898155
|
| 600 |
+
},
|
| 601 |
+
"embknn_balanced": {
|
| 602 |
+
"hr@3": 0.07242339832869081,
|
| 603 |
+
"hr@5": 0.08774373259052924,
|
| 604 |
+
"hr@10": 0.1309192200557103,
|
| 605 |
+
"mrr@3": 0.029944290316204505,
|
| 606 |
+
"mrr@5": 0.03328690872966081,
|
| 607 |
+
"mrr@10": 0.0390475092969399,
|
| 608 |
+
"loss": 9.862932594373698
|
| 609 |
+
},
|
| 610 |
+
"embknn_last": {
|
| 611 |
+
"hr@3": 0.10306406685236769,
|
| 612 |
+
"hr@5": 0.13231197771587744,
|
| 613 |
+
"hr@10": 0.1713091922005571,
|
| 614 |
+
"mrr@3": 0.08890436407085249,
|
| 615 |
+
"mrr@5": 0.09551996299815377,
|
| 616 |
+
"mrr@10": 0.10036034862352614,
|
| 617 |
+
"loss": 9.816932444452908
|
| 618 |
+
},
|
| 619 |
+
"paired_differences_95ci": {
|
| 620 |
+
"vs_embknn_last": {
|
| 621 |
+
"d_hr@10": -0.013927576601671293,
|
| 622 |
+
"d_hr@10_ci": [
|
| 623 |
+
-0.03203342618384403,
|
| 624 |
+
0.005571030640668523
|
| 625 |
+
],
|
| 626 |
+
"d_mrr@10": -0.0011512357960826308,
|
| 627 |
+
"d_mrr@10_ci": [
|
| 628 |
+
-0.009422102290312597,
|
| 629 |
+
0.00782562618826542
|
| 630 |
+
],
|
| 631 |
+
"mcnemar_p": 0.20263875106454401
|
| 632 |
+
},
|
| 633 |
+
"vs_embknn_balanced": {
|
| 634 |
+
"d_hr@10": 0.026462395543175504,
|
| 635 |
+
"d_hr@10_ci": [
|
| 636 |
+
0.0069637883008356605,
|
| 637 |
+
0.04596100278551532
|
| 638 |
+
],
|
| 639 |
+
"d_mrr@10": 0.06016160410310832,
|
| 640 |
+
"d_mrr@10_ci": [
|
| 641 |
+
0.04537651434761468,
|
| 642 |
+
0.07661199263828095
|
| 643 |
+
],
|
| 644 |
+
"mcnemar_p": 0.01445383353382763
|
| 645 |
+
}
|
| 646 |
+
},
|
| 647 |
+
"eval_gpu": "NVIDIA L4",
|
| 648 |
+
"evaluated_at": "2026-09-29T11:12:30Z",
|
| 649 |
+
"context_ablations": {
|
| 650 |
+
"no_context": {
|
| 651 |
+
"hr@10": 0.15459610027855153,
|
| 652 |
+
"mrr@10": 0.09153733946237723,
|
| 653 |
+
"pct_change_hr@10": -1.7699115044247926,
|
| 654 |
+
"pct_change_hr@10_ci95": [
|
| 655 |
+
-12.381163084702909,
|
| 656 |
+
9.890381895332398
|
| 657 |
+
],
|
| 658 |
+
"pct_change_mrr@10": -7.732932148935379,
|
| 659 |
+
"pct_change_mrr@10_ci95": [
|
| 660 |
+
-16.936256020977453,
|
| 661 |
+
1.2985526363363442
|
| 662 |
+
],
|
| 663 |
+
"mean_context_sequences": 0.0
|
| 664 |
+
},
|
| 665 |
+
"random_context": {
|
| 666 |
+
"hr@10": 0.04456824512534819,
|
| 667 |
+
"mrr@10": 0.033185767398986314,
|
| 668 |
+
"pct_change_hr@10": -71.68141592920354,
|
| 669 |
+
"pct_change_hr@10_ci95": [
|
| 670 |
+
-80.17665045682287,
|
| 671 |
+
-62.59908536585367
|
| 672 |
+
],
|
| 673 |
+
"pct_change_mrr@10": -66.54967830313211,
|
| 674 |
+
"pct_change_mrr@10_ci95": [
|
| 675 |
+
-76.83137579538865,
|
| 676 |
+
-54.930787982373936
|
| 677 |
+
],
|
| 678 |
+
"mean_context_sequences": 8.0
|
| 679 |
+
}
|
| 680 |
+
}
|
| 681 |
+
}
|
| 682 |
+
},
|
| 683 |
+
"macro_mean_7": {
|
| 684 |
+
"recicl_v0": {
|
| 685 |
+
"hr@10": 0.1390810843398162,
|
| 686 |
+
"mrr@10": 0.09355228239514829
|
| 687 |
+
},
|
| 688 |
+
"embknn_balanced": {
|
| 689 |
+
"hr@10": 0.11207443075966694,
|
| 690 |
+
"mrr@10": 0.06307460142705772
|
| 691 |
+
},
|
| 692 |
+
"embknn_last": {
|
| 693 |
+
"hr@10": 0.1471064365910456,
|
| 694 |
+
"mrr@10": 0.09372087010221936
|
| 695 |
+
}
|
| 696 |
+
},
|
| 697 |
+
"context_ablations_note": "same checkpoint, TEST split and protocol, batch 1; 'no_context' = 0 context sequences, 'random_context' = 8 randomly chosen train-split sequences instead of the retrieved ones. pct_change = % change vs the reported numbers of this model; ci95 = paired bootstrap over test users (2,000 resamples)",
|
| 698 |
+
"source_files": "our evaluation outputs for this checkpoint: per-dataset TEST results and metadata; paired differences and n_test from our aggregate tables; context ablations from our ablation run"
|
| 699 |
+
}
|
example.py
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# SPDX-FileCopyrightText: 2026 devtaji
|
| 2 |
+
# SPDX-License-Identifier: Apache-2.0
|
| 3 |
+
"""Minimal example: load recICL and rank a toy catalog for one user.
|
| 4 |
+
|
| 5 |
+
It embeds nothing. A real catalog needs precomputed item embeddings from the encoder named in config.json
|
| 6 |
+
("item_embeddings": gte-Qwen2-1.5B-instruct, D=1536). Here the catalog is 500 random unit vectors, so the ranking
|
| 7 |
+
itself carries no meaning; the calls are exactly the ones you would make with real embeddings.
|
| 8 |
+
|
| 9 |
+
pip install -r requirements.txt
|
| 10 |
+
python example.py
|
| 11 |
+
"""
|
| 12 |
+
import os
|
| 13 |
+
|
| 14 |
+
import numpy as np
|
| 15 |
+
|
| 16 |
+
import recicl as ir
|
| 17 |
+
|
| 18 |
+
HERE = os.path.dirname(os.path.abspath(__file__))
|
| 19 |
+
|
| 20 |
+
# 1. model: config.json + model.safetensors
|
| 21 |
+
model = ir.load_model(HERE)
|
| 22 |
+
cfg = ir.load_config(HERE)
|
| 23 |
+
n_params = sum(p.numel() for p in model.parameters())
|
| 24 |
+
print(f"loaded {cfg['name']}: {n_params:,} parameters, D={model.input_dim}, "
|
| 25 |
+
f"device={next(model.parameters()).device}")
|
| 26 |
+
|
| 27 |
+
# 2. catalog: precomputed item embeddings [N, D] (row i = item index i). Toy stand-in here.
|
| 28 |
+
rng = np.random.default_rng(0)
|
| 29 |
+
N = 500
|
| 30 |
+
item_embeddings = rng.standard_normal((N, model.input_dim)).astype(np.float32)
|
| 31 |
+
catalog = ir.ItemCatalog(item_embeddings, dim=model.input_dim)
|
| 32 |
+
|
| 33 |
+
# 3. context pool: other users' item sequences over the same catalog (item indices, oldest first)
|
| 34 |
+
pool = [rng.integers(0, N, size=int(rng.integers(3, 20))).tolist() for _ in range(300)]
|
| 35 |
+
pool += [[12, 7, 311, 45, 88], [7, 311, 45, 90], [311, 45, 88, 402]] # a few users who share this user's items
|
| 36 |
+
retriever = ir.ContextRetriever(pool, model.config)
|
| 37 |
+
|
| 38 |
+
# 4. query: the user's recent items (oldest first) + up to 8 retrieved context sequences
|
| 39 |
+
history = [3, 12, 7, 311]
|
| 40 |
+
context = retriever.retrieve(history)
|
| 41 |
+
print(f"history: {history}")
|
| 42 |
+
print(f"context: {len(context)} sequences, e.g. {context[:3]}")
|
| 43 |
+
|
| 44 |
+
# 5. rank the whole catalog
|
| 45 |
+
items, scores = ir.recommend(model, catalog, history, context, k=10)
|
| 46 |
+
print("top-10 items (index, score):")
|
| 47 |
+
for rank, (i, s) in enumerate(zip(items, scores), 1):
|
| 48 |
+
print(f" {rank:2d}. item {i:3d} score {s:8.3f}")
|
model.safetensors
ADDED
|
@@ -0,0 +1,3 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
version https://git-lfs.github.com/spec/v1
|
| 2 |
+
oid sha256:02c4edc3a4944a9e7a0b6025217b3ea7af16e53c9483e85e9a573074a228a60c
|
| 3 |
+
size 679680696
|
recicl/__init__.py
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# SPDX-FileCopyrightText: 2026 devtaji
|
| 2 |
+
# SPDX-License-Identifier: Apache-2.0
|
| 3 |
+
#
|
| 4 |
+
# New file for recICL (not from SAP).
|
| 5 |
+
"""recICL: an in-context next-item recommender built on SAP's RecPFN architecture.
|
| 6 |
+
|
| 7 |
+
import recicl as ir
|
| 8 |
+
model = ir.load_model("path/to/recICL") # config.json + model.safetensors
|
| 9 |
+
catalog = ir.ItemCatalog(item_embeddings, dim=model.input_dim) # [N, 1536] precomputed item embeddings
|
| 10 |
+
context = ir.ContextRetriever(other_users_sequences, model.config).retrieve(history)
|
| 11 |
+
items, scores = ir.recommend(model, catalog, history, context, k=10)
|
| 12 |
+
"""
|
| 13 |
+
from .architecture import EmbKNN, RecPFN
|
| 14 |
+
from .config import Config
|
| 15 |
+
from .context_selector import InvertedIndexMatcher
|
| 16 |
+
from .inference import (ContextRetriever, ItemCatalog, baseline_scores, load_config, load_model, recommend,
|
| 17 |
+
score_items)
|
| 18 |
+
|
| 19 |
+
__version__ = "0.1.0"
|
| 20 |
+
__all__ = ["load_model", "load_config", "ItemCatalog", "ContextRetriever", "score_items", "recommend",
|
| 21 |
+
"baseline_scores", "RecPFN", "EmbKNN", "Config", "InvertedIndexMatcher"]
|
recicl/architecture/__init__.py
ADDED
|
@@ -0,0 +1,10 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and tabular-ai-recpfn contributors
|
| 2 |
+
# SPDX-License-Identifier: Apache-2.0
|
| 3 |
+
#
|
| 4 |
+
# Copied from src/architecture/__init__.py of https://github.com/SAP-samples/tabular-ai-recpfn (upstream commit 1af320c),
|
| 5 |
+
# redistributed under the Apache License 2.0 (see LICENSE and NOTICE in the repository root).
|
| 6 |
+
# MODIFIED for recICL by devtaji on 2026-09-30:
|
| 7 |
+
# - absolute imports rewritten as package-relative imports (no code change otherwise)
|
| 8 |
+
|
| 9 |
+
from .recpfn import RecPFN
|
| 10 |
+
from .emb_knn import EmbKNN
|
recicl/architecture/base.py
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and tabular-ai-recpfn contributors
|
| 2 |
+
# SPDX-License-Identifier: Apache-2.0
|
| 3 |
+
#
|
| 4 |
+
# Copied from src/architecture/base.py of https://github.com/SAP-samples/tabular-ai-recpfn (upstream commit 1af320c),
|
| 5 |
+
# redistributed under the Apache License 2.0 (see LICENSE and NOTICE in the repository root).
|
| 6 |
+
# MODIFIED for recICL by devtaji on 2026-09-30:
|
| 7 |
+
# - absolute imports rewritten as package-relative imports (no code change otherwise)
|
| 8 |
+
|
| 9 |
+
import torch
|
| 10 |
+
from torch import nn
|
| 11 |
+
import abc
|
| 12 |
+
|
| 13 |
+
from ..config import Config
|
| 14 |
+
from ..util.metrics import MetricCollection
|
| 15 |
+
from ..constants import DEVICE
|
| 16 |
+
|
| 17 |
+
class SeqRec(torch.nn.Module):
|
| 18 |
+
|
| 19 |
+
def __init__(self,
|
| 20 |
+
input_dim:int,
|
| 21 |
+
config:Config,
|
| 22 |
+
device=None):
|
| 23 |
+
"""
|
| 24 |
+
Initialize the sequential recommender base class.
|
| 25 |
+
:param input_dim: Dimensionality of the input embeddings.
|
| 26 |
+
:param config: Configuration object with model and training parameters.
|
| 27 |
+
:param device: Optional device to run the model on. Defaults to constants.DEVICE.
|
| 28 |
+
"""
|
| 29 |
+
super(SeqRec, self).__init__()
|
| 30 |
+
self.device = device if device is not None else DEVICE
|
| 31 |
+
self.config = config
|
| 32 |
+
self.input_dim = input_dim
|
| 33 |
+
|
| 34 |
+
|
| 35 |
+
@abc.abstractmethod
|
| 36 |
+
def forward(self, x:torch.Tensor, mask:torch.Tensor, **kwargs) -> torch.Tensor:
|
| 37 |
+
"""
|
| 38 |
+
Forward pass of the model.
|
| 39 |
+
:param x: Input tensor of shape (batch_size, seq, emb_dim).
|
| 40 |
+
:param mask: Mask tensor indicating valid positions in the sequence.
|
| 41 |
+
"""
|
| 42 |
+
x = None
|
| 43 |
+
return x
|
| 44 |
+
|
| 45 |
+
@staticmethod
|
| 46 |
+
def last_nonzero_position_indices(mask:torch.Tensor) -> torch.Tensor:
|
| 47 |
+
"""
|
| 48 |
+
Get indices of the last non-zero positions for each sequence in the batch.
|
| 49 |
+
:param mask: Mask tensor of shape (batch_size, seq_len) where non-zero indicates valid positions.
|
| 50 |
+
:return: Tensor of shape (batch_size,) with the index of the last non-zero position per sequence.
|
| 51 |
+
"""
|
| 52 |
+
nonzero_mask = mask != 0
|
| 53 |
+
indices = torch.argsort(nonzero_mask, dim=1, descending=True, stable=True)
|
| 54 |
+
last_nonzero_indices = torch.gather(indices, 1, (nonzero_mask.sum(dim=1, keepdim=True) - 1).clamp(min=0))
|
| 55 |
+
return last_nonzero_indices.squeeze()
|
| 56 |
+
|
| 57 |
+
def get_loss(self, outputs:torch.Tensor, targets:torch.Tensor, embeddings:torch.Tensor,
|
| 58 |
+
mask:torch.Tensor=None, evaluate_last_only=False, valid_mask:torch.Tensor=None,
|
| 59 |
+
metrics:MetricCollection=None):
|
| 60 |
+
"""
|
| 61 |
+
Compute the loss between outputs and targets.
|
| 62 |
+
:param outputs: Model outputs (batch_size, seq_len, emb_dim)
|
| 63 |
+
:param targets: Ground truth targets (batch_size, seq_len)
|
| 64 |
+
:param embeddings: Embeddings for computing softmax cross entropy loss
|
| 65 |
+
:param mask: Mask tensor indicating valid positions in the sequence
|
| 66 |
+
:param evaluate_last_only: Whether to evaluate only the last position in the sequence
|
| 67 |
+
:param valid_mask: Optional mask to filter valid items in evaluation
|
| 68 |
+
:return: Loss tensor and metrics dictionary.
|
| 69 |
+
"""
|
| 70 |
+
outputs = outputs.to(self.device)
|
| 71 |
+
targets = targets.to(self.device)
|
| 72 |
+
embeddings = embeddings.to(self.device)
|
| 73 |
+
mask = mask.to(self.device) if mask is not None else None
|
| 74 |
+
|
| 75 |
+
if evaluate_last_only:
|
| 76 |
+
last_nonzero = self.last_nonzero_position_indices(mask)
|
| 77 |
+
outputs = outputs[torch.arange(outputs.shape[0]), last_nonzero, :].view(-1, outputs.shape[-1])
|
| 78 |
+
x = targets[torch.arange(outputs.shape[0]), torch.clamp(last_nonzero-1,0)].view(-1)
|
| 79 |
+
x[last_nonzero==0] = 0
|
| 80 |
+
targets = targets[torch.arange(outputs.shape[0]), last_nonzero].view(-1)
|
| 81 |
+
elif mask is not None:
|
| 82 |
+
outputs = outputs[mask]
|
| 83 |
+
targets = targets[mask]
|
| 84 |
+
|
| 85 |
+
logits = torch.matmul(outputs, embeddings.T)
|
| 86 |
+
if valid_mask is not None:
|
| 87 |
+
logits[:, ~valid_mask] = -1e9
|
| 88 |
+
if self.config.loss == 'mse':
|
| 89 |
+
target_embs = embeddings[targets]
|
| 90 |
+
loss = torch.nn.functional.mse_loss(outputs, target_embs, reduction='mean')
|
| 91 |
+
elif self.config.loss == 'sce':
|
| 92 |
+
loss = torch.nn.functional.cross_entropy(logits, targets, reduction='mean')
|
| 93 |
+
else:
|
| 94 |
+
raise ValueError(f"Unsupported loss function: {self.config.loss}")
|
| 95 |
+
|
| 96 |
+
if self.config.optimizer !='adamw':
|
| 97 |
+
reg_loss = sum(torch.norm(param, p=2) for param in self.parameters())
|
| 98 |
+
size_reg_loss = torch.norm(outputs, p=2)
|
| 99 |
+
loss += self.config.reg_lambda * (reg_loss + size_reg_loss)
|
| 100 |
+
|
| 101 |
+
scores, preds = torch.topk(logits, k=metrics.max_k, dim=-1)
|
| 102 |
+
metrics.update(preds, targets, loss.item())
|
| 103 |
+
|
| 104 |
+
return loss, metrics
|
| 105 |
+
|
| 106 |
+
def get_prediction(self, outputs:torch.Tensor, targets:torch.Tensor, embeddings:torch.Tensor, k:int):
|
| 107 |
+
"""
|
| 108 |
+
Get the top-k predictions from the model outputs.
|
| 109 |
+
:param outputs: Model outputs (batch_size, seq_len, emb_dim)
|
| 110 |
+
:param targets: Ground truth targets (batch_size, seq_len)
|
| 111 |
+
:param embeddings: Embeddings for computing softmax cross entropy loss
|
| 112 |
+
:param k: Number of top predictions to return.
|
| 113 |
+
:return: Top-k predictions and their scores
|
| 114 |
+
"""
|
| 115 |
+
logits = torch.matmul(outputs, embeddings.T)
|
| 116 |
+
scores, preds = torch.topk(logits, k=k, dim=-1)
|
| 117 |
+
return preds, scores
|
recicl/architecture/emb_knn.py
ADDED
|
@@ -0,0 +1,92 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and tabular-ai-recpfn contributors
|
| 2 |
+
# SPDX-License-Identifier: Apache-2.0
|
| 3 |
+
#
|
| 4 |
+
# Copied from src/architecture/emb_knn.py of https://github.com/SAP-samples/tabular-ai-recpfn (upstream commit 1af320c),
|
| 5 |
+
# redistributed under the Apache License 2.0 (see LICENSE and NOTICE in the repository root).
|
| 6 |
+
# MODIFIED for recICL by devtaji on 2026-09-30:
|
| 7 |
+
# - absolute imports rewritten as package-relative imports
|
| 8 |
+
# - added the 'last' baseline mode (score with the most recent item's embedding)
|
| 9 |
+
|
| 10 |
+
import torch
|
| 11 |
+
|
| 12 |
+
from .base import SeqRec
|
| 13 |
+
from ..config import Config
|
| 14 |
+
|
| 15 |
+
class EmbKNN(SeqRec):
|
| 16 |
+
|
| 17 |
+
def __init__(self, input_dim:int, config:Config, device=None):
|
| 18 |
+
"""
|
| 19 |
+
Initialize the embedding-based KNN baseline.
|
| 20 |
+
:param input_dim: Dimensionality of the input embeddings.
|
| 21 |
+
:param config: Configuration with baseline settings.
|
| 22 |
+
:param device: Optional device to run the model on. Defaults to constants.DEVICE.
|
| 23 |
+
"""
|
| 24 |
+
super(EmbKNN, self).__init__(input_dim, config, device)
|
| 25 |
+
|
| 26 |
+
def forward(self, x:torch.Tensor, mask:torch.Tensor):
|
| 27 |
+
"""
|
| 28 |
+
Forward pass for the EmbKNN baseline.
|
| 29 |
+
:param x: Input tensor of shape (batch_size, seq_len, emb_dim).
|
| 30 |
+
:param mask: Mask tensor indicating valid positions in the sequence.
|
| 31 |
+
:return: Aggregated embeddings according to the configured mode(s), with mask applied.
|
| 32 |
+
"""
|
| 33 |
+
modes = self.config.baseline_config
|
| 34 |
+
apply_mask = lambda t: t * mask.unsqueeze(-1).float()
|
| 35 |
+
if isinstance(modes, list):
|
| 36 |
+
return {mode: apply_mask(self._apply_mode(x, mode)) for mode in modes}
|
| 37 |
+
return apply_mask(self._apply_mode(x, modes))
|
| 38 |
+
|
| 39 |
+
def _apply_mode(self, x: torch.Tensor, mode: str) -> torch.Tensor:
|
| 40 |
+
"""
|
| 41 |
+
Apply the selected baseline mode to aggregate embeddings.
|
| 42 |
+
:param x: Input tensor of shape (batch_size, seq_len, emb_dim).
|
| 43 |
+
:param mode: Baseline mode name (e.g., 'balanced', 'recent').
|
| 44 |
+
:return: Aggregated tensor with the same shape as x.
|
| 45 |
+
"""
|
| 46 |
+
if mode == 'balanced':
|
| 47 |
+
return self.normalized_cumsum(x, dim=1)
|
| 48 |
+
if mode == 'last':
|
| 49 |
+
# the EmbKNN described in the RecPFN paper's text: score with the most recent item only
|
| 50 |
+
# (the EmbKNN numbers in the paper's Table 2 are closer to mode 'balanced' in our evaluation)
|
| 51 |
+
return x
|
| 52 |
+
if mode == 'recent':
|
| 53 |
+
decay = self.config.baseline_config.get('recent_decay', 0.9)
|
| 54 |
+
return self.weighted_cumsum(x, dim=1, decay=decay)
|
| 55 |
+
raise ValueError(f"Unknown baseline mode: {mode}")
|
| 56 |
+
|
| 57 |
+
def normalized_cumsum(self, x: torch.Tensor, dim: int = 0) -> torch.Tensor:
|
| 58 |
+
"""
|
| 59 |
+
Compute normalized cumulative sum along a dimension (simple cumulative mean).
|
| 60 |
+
:param x: Input tensor of shape (batch_size, seq_len, emb_dim).
|
| 61 |
+
:param dim: Dimension along which to compute the cumulative sum.
|
| 62 |
+
:return: Tensor where each position is the cumulative mean up to that position.
|
| 63 |
+
"""
|
| 64 |
+
size_dim = x.size(dim)
|
| 65 |
+
shape = [1 if i != dim else size_dim for i in range(x.dim())]
|
| 66 |
+
norm = torch.arange(1, size_dim + 1, device=self.device).view(shape)
|
| 67 |
+
x = x.cumsum(dim=dim) / norm
|
| 68 |
+
return x
|
| 69 |
+
|
| 70 |
+
def weighted_cumsum(self, x: torch.Tensor, dim: int = 1, decay: float = 0.9) -> torch.Tensor:
|
| 71 |
+
"""
|
| 72 |
+
Compute a weighted cumulative mean favoring recent interactions via EMA:
|
| 73 |
+
y_t = (1 - beta) * x_t + beta * y_{t-1}, where beta=decay.
|
| 74 |
+
:param x: Input tensor of shape (batch_size, seq_len, emb_dim).
|
| 75 |
+
:param dim: Sequence dimension (default 1).
|
| 76 |
+
:param decay: EMA decay in [0,1). Higher gives longer memory; lower favors recent more.
|
| 77 |
+
:return: Tensor where each position is the EMA up to that position.
|
| 78 |
+
"""
|
| 79 |
+
if dim != 1:
|
| 80 |
+
x = x.transpose(dim, 1)
|
| 81 |
+
beta = decay
|
| 82 |
+
one_minus_beta = 1.0 - beta
|
| 83 |
+
|
| 84 |
+
b, s, d = x.shape
|
| 85 |
+
y = torch.empty_like(x)
|
| 86 |
+
y[:, 0, :] = x[:, 0, :]
|
| 87 |
+
for t in range(1, s):
|
| 88 |
+
y[:, t, :] = one_minus_beta * x[:, t, :] + beta * y[:, t - 1, :]
|
| 89 |
+
|
| 90 |
+
if dim != 1:
|
| 91 |
+
y = y.transpose(1, dim)
|
| 92 |
+
return y
|
recicl/architecture/recpfn.py
ADDED
|
@@ -0,0 +1,303 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and tabular-ai-recpfn contributors
|
| 2 |
+
# SPDX-License-Identifier: Apache-2.0
|
| 3 |
+
#
|
| 4 |
+
# Copied from src/architecture/recpfn.py of https://github.com/SAP-samples/tabular-ai-recpfn (upstream commit 1af320c),
|
| 5 |
+
# redistributed under the Apache License 2.0 (see LICENSE and NOTICE in the repository root).
|
| 6 |
+
# MODIFIED for recICL by devtaji on 2026-09-30:
|
| 7 |
+
# - absolute imports rewritten as package-relative imports (no code change otherwise)
|
| 8 |
+
|
| 9 |
+
import torch
|
| 10 |
+
from torch import nn
|
| 11 |
+
import torch.nn.functional as F
|
| 12 |
+
import numpy as np
|
| 13 |
+
from collections import Counter
|
| 14 |
+
|
| 15 |
+
from ..constants import DEVICE
|
| 16 |
+
from ..config import Config
|
| 17 |
+
from .util import get_attn_mask
|
| 18 |
+
from .base import SeqRec
|
| 19 |
+
|
| 20 |
+
class SelfAttention(nn.Module):
|
| 21 |
+
|
| 22 |
+
def __init__(self, emb_dim: int,
|
| 23 |
+
bias: bool=False,
|
| 24 |
+
is_causal: bool=False,
|
| 25 |
+
attn_type = 'A',
|
| 26 |
+
hidden_dim:int = None,
|
| 27 |
+
config: Config = None):
|
| 28 |
+
"""
|
| 29 |
+
Initialize a SelfAttention layer.
|
| 30 |
+
|
| 31 |
+
:param emb_dim: Embedding dimension of the input (and output).
|
| 32 |
+
:param bias: Whether to include bias terms in projection layers.
|
| 33 |
+
:param is_causal: If True, applies causal attention masking.
|
| 34 |
+
:param attn_type: Attention variant, one of 'A' or 'B'.
|
| 35 |
+
:param hidden_dim: Per-head hidden dimension; defaults to emb_dim // n_heads.
|
| 36 |
+
:param config: Configuration object containing attention-related parameters.
|
| 37 |
+
"""
|
| 38 |
+
super().__init__()
|
| 39 |
+
|
| 40 |
+
self.config = config
|
| 41 |
+
|
| 42 |
+
self.emb_dim = emb_dim
|
| 43 |
+
self.is_causal = is_causal
|
| 44 |
+
self.attn_type = attn_type
|
| 45 |
+
self.n_heads = config.n_heads
|
| 46 |
+
self.dropout = config.dropout
|
| 47 |
+
self.pos_emb_scheme = config.positional_embedding_scheme if config else 'hard-alibi'
|
| 48 |
+
assert attn_type in ['A', 'B'], "attn_type must be one of 'A', 'B', or 'C'"
|
| 49 |
+
self.attn_type = attn_type
|
| 50 |
+
|
| 51 |
+
if hidden_dim is None:
|
| 52 |
+
hidden_dim = emb_dim // self.n_heads
|
| 53 |
+
assert emb_dim % self.n_heads == 0
|
| 54 |
+
self.hidden_dim = hidden_dim
|
| 55 |
+
|
| 56 |
+
self.k_proj = nn.Linear(emb_dim, self.n_heads*hidden_dim, bias=bias)
|
| 57 |
+
self.q_proj = nn.Linear(emb_dim, self.n_heads*hidden_dim, bias=bias)
|
| 58 |
+
|
| 59 |
+
v_hid_dim = emb_dim if attn_type=='A' else hidden_dim
|
| 60 |
+
self.v_proj = nn.Linear(emb_dim, self.n_heads*v_hid_dim, bias=bias)
|
| 61 |
+
|
| 62 |
+
self.layer_norm = nn.LayerNorm(emb_dim)
|
| 63 |
+
|
| 64 |
+
self.init_weights()
|
| 65 |
+
|
| 66 |
+
if attn_type == 'B':
|
| 67 |
+
self.attn_proj = nn.Linear(self.n_heads * hidden_dim, emb_dim)
|
| 68 |
+
self.attn_dropout = nn.Dropout(self.dropout)
|
| 69 |
+
self.v_proj_out = nn.Sequential(
|
| 70 |
+
nn.Linear(emb_dim, 2*emb_dim),
|
| 71 |
+
nn.ReLU(),
|
| 72 |
+
nn.Linear(2*emb_dim, emb_dim)
|
| 73 |
+
)
|
| 74 |
+
|
| 75 |
+
def apply_ff(self, y:torch.Tensor, x:torch.Tensor) -> torch.Tensor:
|
| 76 |
+
"""
|
| 77 |
+
Apply post-attention feed-forward and residual operations.
|
| 78 |
+
|
| 79 |
+
:param y: Attention output tensor of shape (batch_size, n_heads, seq_len, value_dim).
|
| 80 |
+
:param x: Original input tensor of shape (batch_size, seq_len, emb_dim) for residual connections.
|
| 81 |
+
:return: Output tensor of shape (batch_size, seq_len, emb_dim).
|
| 82 |
+
"""
|
| 83 |
+
b, s = x.size(0), x.size(1)
|
| 84 |
+
if self.attn_type == 'B':
|
| 85 |
+
y = y.transpose(1,2).contiguous().view(b, s, -1)
|
| 86 |
+
y = self.attn_proj(y)
|
| 87 |
+
y = self.attn_dropout(y) + x
|
| 88 |
+
y = self.layer_norm(y)
|
| 89 |
+
y = self.v_proj_out(y)
|
| 90 |
+
y = y + x
|
| 91 |
+
else:
|
| 92 |
+
y = y.sum(1)/self.n_heads
|
| 93 |
+
y = self.layer_norm(y) + x
|
| 94 |
+
return y
|
| 95 |
+
|
| 96 |
+
def forward(self, x:torch.Tensor, attn_mask:torch.Tensor=None) -> torch.Tensor:
|
| 97 |
+
"""
|
| 98 |
+
Forward pass of the SelfAttention layer.
|
| 99 |
+
:param x: Input tensor of shape (batch_size, seq_len, emb_dim).
|
| 100 |
+
:param attn_mask: Optional attention mask of shape (batch_size, n_heads, seq_len, seq_len)
|
| 101 |
+
or a broadcast-compatible shape for scaled dot-product attention.
|
| 102 |
+
:return: Output tensor of shape (batch_size, seq_len, emb_dim).
|
| 103 |
+
"""
|
| 104 |
+
b, s, _ = x.size()
|
| 105 |
+
|
| 106 |
+
q:torch.Tensor = self.q_proj(x)
|
| 107 |
+
k:torch.Tensor = self.k_proj(x)
|
| 108 |
+
q = q.view(b, s, self.n_heads, -1).transpose(1, 2)
|
| 109 |
+
k = k.view(b, s, self.n_heads, -1).transpose(1, 2)
|
| 110 |
+
|
| 111 |
+
v:torch.Tensor = self.v_proj(x)
|
| 112 |
+
v = v.view(b, s, self.n_heads, -1).transpose(1, 2)
|
| 113 |
+
|
| 114 |
+
if self.pos_emb_scheme in ['alibi', 'hard-alibi']:
|
| 115 |
+
attn_mask = get_attn_mask(attn_mask if attn_mask is not None
|
| 116 |
+
else (b, self.n_heads, s, s),
|
| 117 |
+
self.config, self.is_causal)
|
| 118 |
+
|
| 119 |
+
y = F.scaled_dot_product_attention(q, k, v, attn_mask=attn_mask, dropout_p=self.dropout if self.training else 0.0,
|
| 120 |
+
is_causal=self.is_causal if attn_mask is None else False)
|
| 121 |
+
|
| 122 |
+
return self.apply_ff(y, x)
|
| 123 |
+
|
| 124 |
+
def init_weights(self):
|
| 125 |
+
"""
|
| 126 |
+
Initialize projection weights for value, key, and query.
|
| 127 |
+
- For attn_type 'A', initializes value projections to approximate identity per head.
|
| 128 |
+
- For attn_type 'B', initializes value projections with Xavier uniform.
|
| 129 |
+
- Key and query projections are initialized with Xavier uniform; biases are zeroed.
|
| 130 |
+
"""
|
| 131 |
+
if self.attn_type == 'A':
|
| 132 |
+
self.v_proj.weight.data = torch.cat([torch.eye(self.emb_dim) for _ in range(self.n_heads)], dim=0)
|
| 133 |
+
if self.v_proj.bias is not None:
|
| 134 |
+
self.v_proj.bias.data = torch.zeros(self.emb_dim * self.n_heads)
|
| 135 |
+
else:
|
| 136 |
+
nn.init.xavier_uniform_(torch.eye(self.emb_dim))
|
| 137 |
+
if self.v_proj.bias is not None:
|
| 138 |
+
self.v_proj.bias.data = torch.zeros(self.n_heads * (self.emb_dim))
|
| 139 |
+
|
| 140 |
+
nn.init.xavier_uniform_(self.k_proj.weight)
|
| 141 |
+
nn.init.xavier_uniform_(self.q_proj.weight)
|
| 142 |
+
if self.k_proj.bias is not None:
|
| 143 |
+
self.k_proj.bias.data = torch.zeros(self.emb_dim)
|
| 144 |
+
if self.q_proj.bias is not None:
|
| 145 |
+
self.q_proj.bias.data = torch.zeros(self.emb_dim)
|
| 146 |
+
|
| 147 |
+
|
| 148 |
+
class CrossAttention(SelfAttention):
|
| 149 |
+
|
| 150 |
+
def __init__(self, emb_dim: int,
|
| 151 |
+
bias: bool=False,
|
| 152 |
+
is_causal: bool=False,
|
| 153 |
+
attn_type = 'A',
|
| 154 |
+
hidden_dim:int = None,
|
| 155 |
+
config: Config = None):
|
| 156 |
+
"""
|
| 157 |
+
Initialize a CrossAttention layer.
|
| 158 |
+
|
| 159 |
+
:param emb_dim: Embedding dimension of the input (and output).
|
| 160 |
+
:param bias: Whether to include bias terms in projection layers.
|
| 161 |
+
:param is_causal: If True, applies causal attention masking (unused for cross-attention).
|
| 162 |
+
:param attn_type: Attention variant, one of 'A' or 'B'.
|
| 163 |
+
:param hidden_dim: Per-head hidden dimension; defaults to emb_dim // n_heads.
|
| 164 |
+
:param config: Configuration object containing attention-related parameters.
|
| 165 |
+
"""
|
| 166 |
+
super().__init__(emb_dim, bias, is_causal, attn_type, hidden_dim, config)
|
| 167 |
+
|
| 168 |
+
def forward(self, x:torch.Tensor,
|
| 169 |
+
icl:torch.Tensor,
|
| 170 |
+
x_mask:torch.Tensor=None,
|
| 171 |
+
icl_mask:torch.Tensor=None,
|
| 172 |
+
max_kv_size=100000) \
|
| 173 |
+
-> torch.Tensor:
|
| 174 |
+
"""
|
| 175 |
+
Forward pass of the CrossAttention layer.
|
| 176 |
+
:param x: Input tensor of shape (batch_size, seq_len, emb_dim).
|
| 177 |
+
:param icl: In-context learning tensor of shape (n_icl, seq_len, emb_dim).
|
| 178 |
+
:param x_mask: Optional mask for x indicating valid positions in each sequence; shape (batch_size, seq_len).
|
| 179 |
+
:param icl_mask: Optional mask for icl indicating valid positions; shape (n_icl, seq_len).
|
| 180 |
+
:param max_kv_size: Maximum total key/value length to control memory usage when batching queries.
|
| 181 |
+
:return: Output tensor of shape (batch_size, seq_len, emb_dim).
|
| 182 |
+
|
| 183 |
+
Note: No positional embeddings are used in this layer.
|
| 184 |
+
"""
|
| 185 |
+
b, s, _ = x.size()
|
| 186 |
+
h = self.hidden_dim
|
| 187 |
+
b_icl, s_icl, _ = icl.size()
|
| 188 |
+
|
| 189 |
+
q:torch.Tensor = self.q_proj(x)
|
| 190 |
+
q = q.view(b, s, self.n_heads, -1).transpose(1, 2)
|
| 191 |
+
|
| 192 |
+
k:torch.Tensor = self.k_proj(icl).view(1, -1, icl.shape[-1])
|
| 193 |
+
k = k.view(1, -1, self.n_heads, h).transpose(1, 2)
|
| 194 |
+
|
| 195 |
+
v:torch.Tensor = self.v_proj(icl).view(1, -1, icl.shape[-1])
|
| 196 |
+
v = v.view(1, b_icl*s_icl, self.n_heads, -1).transpose(1, 2)
|
| 197 |
+
|
| 198 |
+
if icl_mask is not None:
|
| 199 |
+
v = v[:, :, icl_mask.view(-1).bool(), :]
|
| 200 |
+
k = k[:, :, icl_mask.view(-1).bool(), :]
|
| 201 |
+
|
| 202 |
+
if not v.shape[-2]:
|
| 203 |
+
return x
|
| 204 |
+
|
| 205 |
+
max_seqs_per_batch = max_kv_size // v.shape[-2]
|
| 206 |
+
y = []
|
| 207 |
+
for i in range(0, b, max_seqs_per_batch):
|
| 208 |
+
end = min(i + max_seqs_per_batch, b)
|
| 209 |
+
q_ = q[i:end,:,:,:]
|
| 210 |
+
mask_ = x_mask[i:end,:] if x_mask is not None else None
|
| 211 |
+
attn_mask = None
|
| 212 |
+
k_ = k
|
| 213 |
+
v_ = v
|
| 214 |
+
|
| 215 |
+
tmp = F.scaled_dot_product_attention(
|
| 216 |
+
q_, k_, v_, dropout_p=self.dropout if self.training else 0.0,
|
| 217 |
+
is_causal=False, attn_mask=attn_mask)
|
| 218 |
+
|
| 219 |
+
tmp = self.apply_ff(tmp, x[i:end,:,:])
|
| 220 |
+
y.append(tmp)
|
| 221 |
+
|
| 222 |
+
y = torch.cat(y, dim=0)
|
| 223 |
+
return y
|
| 224 |
+
|
| 225 |
+
class RecPFN(SeqRec):
|
| 226 |
+
def __init__(self, input_dim:int, config:Config, device=None):
|
| 227 |
+
"""
|
| 228 |
+
Initialize the RecPFN model.
|
| 229 |
+
|
| 230 |
+
:param input_dim: Embedding dimension of inputs (and model hidden size).
|
| 231 |
+
:param config: Configuration object with model hyperparameters.
|
| 232 |
+
:param device: Torch device to place model parameters on.
|
| 233 |
+
"""
|
| 234 |
+
super(RecPFN, self).__init__(input_dim, config, device)
|
| 235 |
+
|
| 236 |
+
self.icl_transformer = None
|
| 237 |
+
|
| 238 |
+
if self.config.icl_module_type == 'A':
|
| 239 |
+
cross_attn_type = ['A'] * self.config.n_layers
|
| 240 |
+
self_attn_type = ['A'] * self.config.n_layers
|
| 241 |
+
elif self.config.icl_module_type == 'B':
|
| 242 |
+
cross_attn_type = ['B'] * self.config.n_layers
|
| 243 |
+
self_attn_type = ['B'] * self.config.n_layers
|
| 244 |
+
elif self.config.icl_module_type == 'AB':
|
| 245 |
+
cross_attn_type = ['A' if i < self.config.n_layers // 2 else 'B' for i in range(self.config.n_layers)]
|
| 246 |
+
self_attn_type = ['A' if i < self.config.n_layers // 2 else 'B' for i in range(self.config.n_layers)]
|
| 247 |
+
elif self.config.icl_module_type == 'alternating':
|
| 248 |
+
modes = ['A', 'B']
|
| 249 |
+
cross_attn_type = [modes[i%2] for i in range(self.config.n_layers)]
|
| 250 |
+
self_attn_type = [modes[i%2] for i in range(self.config.n_layers)]
|
| 251 |
+
|
| 252 |
+
self.cross_decoders = nn.ModuleList([
|
| 253 |
+
CrossAttention(emb_dim=input_dim,
|
| 254 |
+
hidden_dim=input_dim // config.n_heads,
|
| 255 |
+
attn_type=cross_attn_type[i],
|
| 256 |
+
config=config).to(self.device)
|
| 257 |
+
for i in range(config.n_layers)
|
| 258 |
+
])
|
| 259 |
+
self.encoders = nn.ModuleList([
|
| 260 |
+
SelfAttention(emb_dim=input_dim,
|
| 261 |
+
hidden_dim=input_dim // config.n_heads,
|
| 262 |
+
attn_type=self_attn_type[i],
|
| 263 |
+
is_causal=True,
|
| 264 |
+
config=self.config).to(self.device)
|
| 265 |
+
for i in range(config.n_layers)
|
| 266 |
+
])
|
| 267 |
+
|
| 268 |
+
self.out_norm = nn.LayerNorm(self.input_dim, elementwise_affine=False).to(device)
|
| 269 |
+
|
| 270 |
+
if self.config.positional_embedding_scheme == 'abs':
|
| 271 |
+
self.positional_embedding = nn.Embedding(config.max_sequence_len, input_dim).to(self.device)
|
| 272 |
+
|
| 273 |
+
def forward(self, x:torch.Tensor, mask:torch.Tensor, icl:torch.Tensor) -> torch.Tensor:
|
| 274 |
+
"""
|
| 275 |
+
Forward pass of the RecPFN model.
|
| 276 |
+
:param x: Input tensor of shape (batch_size, seq_len, emb_dim).
|
| 277 |
+
:param mask: Mask tensor of shape (batch_size, seq_len) indicating valid positions.
|
| 278 |
+
:param icl: In-context learning tensor of shape (n_examples, seq_len, emb_dim).
|
| 279 |
+
:return: Output tensor of shape (batch_size, seq_len, emb_dim).
|
| 280 |
+
"""
|
| 281 |
+
if x.shape[-1] != self.input_dim:
|
| 282 |
+
raise ValueError(f"Input embedding dimension {x.shape[-1]} does not match model input dimension {self.input_dim}.")
|
| 283 |
+
if self.config.positional_embedding_scheme == 'abs':
|
| 284 |
+
positions = torch.arange(x.size(1), device=self.device).unsqueeze(0).expand_as(x[:,:,0])
|
| 285 |
+
pos_emb = self.positional_embedding(positions)
|
| 286 |
+
x = x + pos_emb
|
| 287 |
+
x = x.to(self.device)
|
| 288 |
+
if icl is not None:
|
| 289 |
+
icl = icl.to(self.device)
|
| 290 |
+
icl_mask = icl.abs().sum(dim=-1).not_equal(0)
|
| 291 |
+
|
| 292 |
+
for i in range(self.config.n_layers):
|
| 293 |
+
if icl is not None:
|
| 294 |
+
icl = self.encoders[i](icl)
|
| 295 |
+
icl = icl * icl_mask.unsqueeze(-1).float()
|
| 296 |
+
x = self.encoders[i](x)
|
| 297 |
+
x = x * mask.unsqueeze(-1).float()
|
| 298 |
+
if icl is not None:
|
| 299 |
+
x = self.cross_decoders[i](x, icl, x_mask=mask, icl_mask=icl_mask)
|
| 300 |
+
x = x * mask.unsqueeze(-1).float()
|
| 301 |
+
x = self.out_norm(x)
|
| 302 |
+
x = x * mask.unsqueeze(-1).float()
|
| 303 |
+
return x
|
recicl/architecture/util.py
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and tabular-ai-recpfn contributors
|
| 2 |
+
# SPDX-License-Identifier: Apache-2.0
|
| 3 |
+
#
|
| 4 |
+
# Copied from src/architecture/util.py of https://github.com/SAP-samples/tabular-ai-recpfn (upstream commit 1af320c),
|
| 5 |
+
# redistributed under the Apache License 2.0 (see LICENSE and NOTICE in the repository root).
|
| 6 |
+
# MODIFIED for recICL by devtaji on 2026-09-30:
|
| 7 |
+
# - absolute imports rewritten as package-relative imports (no code change otherwise)
|
| 8 |
+
|
| 9 |
+
import torch
|
| 10 |
+
|
| 11 |
+
from ..constants import DEVICE
|
| 12 |
+
from ..config import Config
|
| 13 |
+
|
| 14 |
+
def get_attn_mask(attn_mask:torch.Tensor|tuple, config:Config, is_causal=True) -> torch.Tensor:
|
| 15 |
+
"""
|
| 16 |
+
Generate an attention mask based on positional embedding scheme and causality.
|
| 17 |
+
|
| 18 |
+
:param attn_mask: Either a tuple (batch_size, num_heads, q_seq_len, k_seq_len) specifying dimensions,
|
| 19 |
+
or a tensor with shape (batch_size, num_heads, q_seq_len, k_seq_len).
|
| 20 |
+
:param config: Configuration object providing positional_embedding_scheme.
|
| 21 |
+
:param is_causal: Whether to use a causal mask when q_seq_len == k_seq_len.
|
| 22 |
+
:return: Attention mask tensor of shape (batch_size, num_heads, q_seq_len, k_seq_len).
|
| 23 |
+
For 'abs'/'nope', a boolean mask. For 'alibi', a float tensor with -inf for masked positions.
|
| 24 |
+
For 'hard-alibi', a boolean mask according to the ALiBi constraints.
|
| 25 |
+
"""
|
| 26 |
+
if isinstance(attn_mask, tuple):
|
| 27 |
+
batch_size, num_heads, q_seq_len, k_seq_len = attn_mask
|
| 28 |
+
if is_causal and q_seq_len == k_seq_len:
|
| 29 |
+
attn_mask = get_causal_mask(q_seq_len, DEVICE).expand(batch_size, num_heads, -1, -1)
|
| 30 |
+
else:
|
| 31 |
+
attn_mask = torch.ones((batch_size, num_heads, q_seq_len, k_seq_len), device=DEVICE).bool()
|
| 32 |
+
else:
|
| 33 |
+
batch_size, num_heads, q_seq_len, k_seq_len = attn_mask.size()
|
| 34 |
+
pos_emb_scheme = config.positional_embedding_scheme if config else 'abs'
|
| 35 |
+
if pos_emb_scheme in ['abs', 'nope']:
|
| 36 |
+
return attn_mask.bool()
|
| 37 |
+
elif pos_emb_scheme in ['alibi', 'hard-alibi']:
|
| 38 |
+
if k_seq_len != q_seq_len:
|
| 39 |
+
return attn_mask.bool()
|
| 40 |
+
else:
|
| 41 |
+
seq_len = k_seq_len
|
| 42 |
+
alibi = torch.arange(seq_len, device=attn_mask.device).unsqueeze(0) - torch.arange(seq_len, device=attn_mask.device).unsqueeze(1)
|
| 43 |
+
alibi = alibi.unsqueeze(0).unsqueeze(0).expand(batch_size, num_heads, -1, -1)
|
| 44 |
+
if pos_emb_scheme == 'alibi':
|
| 45 |
+
alibi = alibi.float().masked_fill(alibi > 0, float('-inf')).masked_fill(attn_mask == 0, float('-inf'))
|
| 46 |
+
elif pos_emb_scheme == 'hard-alibi':
|
| 47 |
+
m = torch.ones(num_heads, device=attn_mask.device) * seq_len
|
| 48 |
+
m[:num_heads//2] = torch.arange(0, num_heads//2, device=attn_mask.device)
|
| 49 |
+
alibi = torch.logical_and(alibi >= (-m.view(1, -1, 1, 1)), alibi <= 0)
|
| 50 |
+
return alibi
|
| 51 |
+
|
| 52 |
+
def get_causal_mask(seq_len:int, device) -> torch.Tensor:
|
| 53 |
+
"""
|
| 54 |
+
Generate a causal mask for self-attention.
|
| 55 |
+
:param seq_len: Length of the sequence.
|
| 56 |
+
:param device: Device to place the mask tensor on.
|
| 57 |
+
:return: Causal mask tensor of shape (1, 1, seq_len, seq_len).
|
| 58 |
+
"""
|
| 59 |
+
mask = torch.tril(torch.ones((seq_len, seq_len), device=device)).unsqueeze(0).unsqueeze(0)
|
| 60 |
+
return mask.bool()
|
recicl/config.py
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and tabular-ai-recpfn contributors
|
| 2 |
+
# SPDX-License-Identifier: Apache-2.0
|
| 3 |
+
#
|
| 4 |
+
# Copied from src/config.py of https://github.com/SAP-samples/tabular-ai-recpfn (upstream commit 1af320c),
|
| 5 |
+
# redistributed under the Apache License 2.0 (see LICENSE and NOTICE in the repository root).
|
| 6 |
+
# MODIFIED for recICL by devtaji on 2026-09-30:
|
| 7 |
+
# - this header added; code unchanged
|
| 8 |
+
|
| 9 |
+
import os
|
| 10 |
+
import sys
|
| 11 |
+
|
| 12 |
+
CURRENT_DIR = os.path.dirname(os.path.abspath(__file__))
|
| 13 |
+
|
| 14 |
+
|
| 15 |
+
class Config:
|
| 16 |
+
|
| 17 |
+
drop_cold_start_items = True
|
| 18 |
+
|
| 19 |
+
max_clickstream_events = None
|
| 20 |
+
|
| 21 |
+
learning_rate = 1e-3
|
| 22 |
+
batch_size = 128
|
| 23 |
+
eval_batch_size = 1
|
| 24 |
+
random_seed = 42
|
| 25 |
+
softmax_sample_size = 4000
|
| 26 |
+
val_k = 10
|
| 27 |
+
train_epoch_size = 500 # num batches
|
| 28 |
+
val_epoch_size = 200 # num batches
|
| 29 |
+
num_epochs = 100
|
| 30 |
+
warmup_epochs = 0
|
| 31 |
+
normalize_embs = True
|
| 32 |
+
early_stopping_patience = 8
|
| 33 |
+
num_gradient_accumulation_steps = 1
|
| 34 |
+
loss = 'sce' # Implemented: sce, mse
|
| 35 |
+
reg_lambda = 0.0 # Regularization coefficient for L2 norm of model parameters
|
| 36 |
+
optimizer = 'adam' # Implemented: adam, adamw
|
| 37 |
+
early_stopping_metric = 'hr@10' # Implemented: 'hr@k', 'mrr@k', k should be in eval_k
|
| 38 |
+
log_time = False
|
| 39 |
+
|
| 40 |
+
# dataset configs
|
| 41 |
+
train_with_synthetic_data = False
|
| 42 |
+
max_dataset_oversampling = 10
|
| 43 |
+
max_test_users = 10000
|
| 44 |
+
train_datasets = []
|
| 45 |
+
test_datasets = []
|
| 46 |
+
llm = 'baai'
|
| 47 |
+
embedding_dim = 128
|
| 48 |
+
sdg_params = None
|
| 49 |
+
num_sdg_items = 1000
|
| 50 |
+
use_cached_embeddings = False
|
| 51 |
+
cached_embedding_folder = os.path.join(CURRENT_DIR, '..', 'emb_store', 'beir')
|
| 52 |
+
data_split_ratio = (0.8, 0.1, 0.1)
|
| 53 |
+
|
| 54 |
+
# backbone configuration
|
| 55 |
+
n_heads = 8
|
| 56 |
+
dropout = 0.2
|
| 57 |
+
n_layers = 2
|
| 58 |
+
baseline_config = 'balanced' # Implemented: 'balanced'
|
| 59 |
+
max_sequence_len = 100
|
| 60 |
+
project_v = True # Whether to project the value embeddings in attention layers
|
| 61 |
+
icl_module_type = 'alternating' # Implemented: 'A', 'B', 'AB', 'alternating'
|
| 62 |
+
positional_embedding_scheme = 'hard-alibi' # Implemented: 'alibi', 'hard-alibi', 'abs', 'nope'
|
| 63 |
+
exclude_mlp = False # Whether to exclude the mlp component in the transformer block
|
| 64 |
+
|
| 65 |
+
# backbone - pfn configs
|
| 66 |
+
pfn_enc_len = 8
|
| 67 |
+
|
| 68 |
+
# icl configs
|
| 69 |
+
train_with_icl = False
|
| 70 |
+
num_icl_examples = 128
|
| 71 |
+
icl_k = 2
|
| 72 |
+
use_query_seq_as_icl = False
|
| 73 |
+
use_random_selection_for_icl = False
|
| 74 |
+
use_transition_matrix_for_icl = False
|
| 75 |
+
weighted_icl_sampling = True
|
| 76 |
+
weighted_decay_rate = 1.0
|
| 77 |
+
truncated_icl_dataset = False
|
| 78 |
+
|
| 79 |
+
save_model = True
|
| 80 |
+
verbose = True
|
| 81 |
+
|
| 82 |
+
# eval configs
|
| 83 |
+
cold_start_eval = False
|
| 84 |
+
save_metrics = False
|
| 85 |
+
metrics = ['hr', 'mrr'] # Implemented: 'hr', 'mrr'
|
| 86 |
+
eval_k = [3,5,10]
|
| 87 |
+
|
| 88 |
+
# synthetic dataset configs
|
| 89 |
+
use_curricular_sdg = False
|
| 90 |
+
# to be filled with lists of variable values
|
| 91 |
+
curricular_sdg_changeable_variables = {'start': None, 'end': None, 'steps': None}
|
| 92 |
+
|
| 93 |
+
def __init__(self, **kwargs):
|
| 94 |
+
|
| 95 |
+
self.__dict__.update(kwargs)
|
| 96 |
+
|
| 97 |
+
def to_dict(self):
|
| 98 |
+
"""
|
| 99 |
+
Convert the configuration to a dictionary
|
| 100 |
+
"""
|
| 101 |
+
d = {
|
| 102 |
+
key: value for key, value in Config.__dict__.items()
|
| 103 |
+
if not key.startswith('__') and not key.startswith('_') # Exclude dunder and private attributes
|
| 104 |
+
and not callable(value) # Exclude methods
|
| 105 |
+
}
|
| 106 |
+
d.update({key: value for key, value in self.__dict__.items()})
|
| 107 |
+
return d
|
recicl/constants.py
ADDED
|
@@ -0,0 +1,37 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and tabular-ai-recpfn contributors
|
| 2 |
+
# SPDX-License-Identifier: Apache-2.0
|
| 3 |
+
#
|
| 4 |
+
# Copied from src/constants.py of https://github.com/SAP-samples/tabular-ai-recpfn (upstream commit 1af320c),
|
| 5 |
+
# redistributed under the Apache License 2.0 (see LICENSE and NOTICE in the repository root).
|
| 6 |
+
# MODIFIED for recICL by devtaji on 2026-09-30:
|
| 7 |
+
# - this header added; code unchanged
|
| 8 |
+
|
| 9 |
+
import torch
|
| 10 |
+
|
| 11 |
+
DEVICE = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")
|
| 12 |
+
|
| 13 |
+
|
| 14 |
+
SDG_STAGE_1_PARAMS = \
|
| 15 |
+
{
|
| 16 |
+
'transition_matrix_prior': ['random_graph'],
|
| 17 |
+
'popularity_bias': [0.0, 0.1, 0.2, 0.3, 0.5],
|
| 18 |
+
'window_size': [1, 2, 3],
|
| 19 |
+
'decay_coeff': [0.5, 0.8],
|
| 20 |
+
'repeated_items': [True],
|
| 21 |
+
}
|
| 22 |
+
|
| 23 |
+
SDG_STAGE_2_PARAMS = \
|
| 24 |
+
{
|
| 25 |
+
'transition_matrix_prior': ['random_graph', 'latent_factor'],
|
| 26 |
+
'num_latent_concepts': [20,40,60],
|
| 27 |
+
'mean_num_concepts_per_item': [2, 3, 5],
|
| 28 |
+
'mean_num_concepts_per_user': [2, 3, 5],
|
| 29 |
+
'popularity_bias': [0.0, 0.1, 0.2],
|
| 30 |
+
'window_size': [1,2,3],
|
| 31 |
+
'decay_coeff': [0.5, 0.8],
|
| 32 |
+
'logit_scale': [9.0, 12.0],
|
| 33 |
+
'concept_matrix_diagonal_deviation_rate': [0.0, 0.1, 0.3],
|
| 34 |
+
'repeated_items': [True],
|
| 35 |
+
'mean_num_related_items': [1,3,5,7],
|
| 36 |
+
'repeated_item_probability': [0.1, 0.2, 0.3],
|
| 37 |
+
}
|
recicl/context_selector/__init__.py
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and tabular-ai-recpfn contributors
|
| 2 |
+
# SPDX-License-Identifier: Apache-2.0
|
| 3 |
+
#
|
| 4 |
+
# Copied from src/context_selector/__init__.py of https://github.com/SAP-samples/tabular-ai-recpfn (upstream commit 1af320c),
|
| 5 |
+
# redistributed under the Apache License 2.0 (see LICENSE and NOTICE in the repository root).
|
| 6 |
+
# MODIFIED for recICL by devtaji on 2026-09-30:
|
| 7 |
+
# - absolute imports rewritten as package-relative imports (no code change otherwise)
|
| 8 |
+
|
| 9 |
+
from .selector import InvertedIndexMatcher
|
recicl/context_selector/selector.py
ADDED
|
@@ -0,0 +1,205 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and tabular-ai-recpfn contributors
|
| 2 |
+
# SPDX-License-Identifier: Apache-2.0
|
| 3 |
+
#
|
| 4 |
+
# Copied from src/context_selector/selector.py of https://github.com/SAP-samples/tabular-ai-recpfn (upstream commit 1af320c),
|
| 5 |
+
# redistributed under the Apache License 2.0 (see LICENSE and NOTICE in the repository root).
|
| 6 |
+
# MODIFIED for recICL by devtaji on 2026-09-30:
|
| 7 |
+
# - absolute imports rewritten as package-relative imports (no code change otherwise)
|
| 8 |
+
|
| 9 |
+
import numpy as np
|
| 10 |
+
from collections import Counter, defaultdict
|
| 11 |
+
import heapq
|
| 12 |
+
from typing import List, Tuple, Dict
|
| 13 |
+
import random
|
| 14 |
+
|
| 15 |
+
import time
|
| 16 |
+
from itertools import chain
|
| 17 |
+
import logging
|
| 18 |
+
|
| 19 |
+
from ..config import Config
|
| 20 |
+
|
| 21 |
+
|
| 22 |
+
class InvertedIndexMatcher(object):
|
| 23 |
+
"""
|
| 24 |
+
Inverted index-based sequence matcher for efficient candidate retrieval.
|
| 25 |
+
|
| 26 |
+
Uses an inverted index to quickly find sequences that share items with a query sequence,
|
| 27 |
+
then ranks candidates by Jaccard similarity (with optional weighted variant).
|
| 28 |
+
"""
|
| 29 |
+
|
| 30 |
+
def __init__(self, sequences: List[List[int]],
|
| 31 |
+
config: Config = None, user_ids: List[int] = None):
|
| 32 |
+
"""
|
| 33 |
+
Initialize the InvertedIndexMatcher.
|
| 34 |
+
|
| 35 |
+
:param sequences: List of sequences where each sequence is a list of item IDs.
|
| 36 |
+
:param config: Configuration object containing matcher parameters.
|
| 37 |
+
:param user_ids: Optional list of user IDs corresponding to each sequence.
|
| 38 |
+
"""
|
| 39 |
+
self.config = config
|
| 40 |
+
self.sequences = sequences
|
| 41 |
+
self.user_ids = user_ids
|
| 42 |
+
self.preprocess_sequences()
|
| 43 |
+
self.build_index()
|
| 44 |
+
self._seq_sets = [set(seq[:-1]) if seq else set() for seq in self.sequences]
|
| 45 |
+
self._seq_lens = np.array([len(s) for s in self._seq_sets], dtype=np.int32)
|
| 46 |
+
|
| 47 |
+
def preprocess_sequences(self):
|
| 48 |
+
"""
|
| 49 |
+
Preprocess sequences by applying maximum sequence length constraint.
|
| 50 |
+
|
| 51 |
+
Splits longer sequences into overlapping chunks using a sliding window approach
|
| 52 |
+
to respect the configured maximum sequence length.
|
| 53 |
+
"""
|
| 54 |
+
max_seq_len = self.config.max_sequence_len
|
| 55 |
+
if max_seq_len is None:
|
| 56 |
+
return
|
| 57 |
+
|
| 58 |
+
step = max(1, int(max_seq_len / 2))
|
| 59 |
+
new_sequences = []
|
| 60 |
+
new_uids = []
|
| 61 |
+
for uid, seq in zip(self.user_ids, self.sequences):
|
| 62 |
+
if len(seq) <= max_seq_len:
|
| 63 |
+
new_sequences.append(seq)
|
| 64 |
+
new_uids.append(uid)
|
| 65 |
+
else:
|
| 66 |
+
new_sequences.extend(seq[start:start + max_seq_len]
|
| 67 |
+
for start in range(0, len(seq), step))
|
| 68 |
+
new_uids.extend([uid] * ((len(seq) - 1) // step + 1))
|
| 69 |
+
self.sequences = new_sequences
|
| 70 |
+
self.user_ids = new_uids
|
| 71 |
+
|
| 72 |
+
def build_index(self):
|
| 73 |
+
"""
|
| 74 |
+
Build inverted index mapping items to sequence indices.
|
| 75 |
+
|
| 76 |
+
Creates a dictionary where each item ID maps to the set of sequence indices
|
| 77 |
+
that contain that item. Excludes the last item in each sequence as it represents
|
| 78 |
+
the prediction target.
|
| 79 |
+
"""
|
| 80 |
+
self.inverted_index = defaultdict(set)
|
| 81 |
+
|
| 82 |
+
for seq_idx, sequence in enumerate(self.sequences):
|
| 83 |
+
for item in set(sequence[:-1]):
|
| 84 |
+
self.inverted_index[item].add(seq_idx)
|
| 85 |
+
|
| 86 |
+
def find_closest_batch(self, query: List[int], k: int = 2, total_k: int = 1) -> List[Tuple[int, float]]:
|
| 87 |
+
"""
|
| 88 |
+
Find the closest sequences to the query using recency-weighted retrieval.
|
| 89 |
+
|
| 90 |
+
Implements a layered candidate retrieval strategy that prioritizes recent items
|
| 91 |
+
in the query sequence(s). Supports both weighted and unweighted Jaccard similarity.
|
| 92 |
+
|
| 93 |
+
:param query: Query sequence (list of item IDs) or batch of sequences (list of lists).
|
| 94 |
+
:param k: Number of recent items to consider for candidate retrieval (recency layers).
|
| 95 |
+
:param total_k: Number of top similar sequences to return.
|
| 96 |
+
:return: List of tuples containing (sequence, similarity_score, user_id) for the top-k
|
| 97 |
+
most similar sequences, sorted by descending similarity.
|
| 98 |
+
"""
|
| 99 |
+
max_candidates = int(getattr(self.config, "max_candidates_cap", total_k * 10))
|
| 100 |
+
if not query:
|
| 101 |
+
return []
|
| 102 |
+
|
| 103 |
+
if isinstance(query[0], list):
|
| 104 |
+
priority_groups = []
|
| 105 |
+
for depth in range(k):
|
| 106 |
+
group = []
|
| 107 |
+
for seq in query:
|
| 108 |
+
if len(seq) > depth:
|
| 109 |
+
group.append(seq[-1 - depth])
|
| 110 |
+
if not group:
|
| 111 |
+
break
|
| 112 |
+
priority_groups.append(group)
|
| 113 |
+
else:
|
| 114 |
+
priority_groups = []
|
| 115 |
+
for depth in range(min(k, len(query))):
|
| 116 |
+
priority_groups.append([query[-1 - depth]])
|
| 117 |
+
|
| 118 |
+
candidate_counter = Counter()
|
| 119 |
+
for i, group in enumerate(priority_groups):
|
| 120 |
+
for item in set(group):
|
| 121 |
+
cand = self.inverted_index.get(item)
|
| 122 |
+
if cand:
|
| 123 |
+
candidate_counter.update(cand)
|
| 124 |
+
if len(candidate_counter) >= max_candidates:
|
| 125 |
+
break
|
| 126 |
+
if i == 1 and not candidate_counter:
|
| 127 |
+
break
|
| 128 |
+
if not candidate_counter:
|
| 129 |
+
return []
|
| 130 |
+
|
| 131 |
+
candidate_indices = [idx for idx, _ in candidate_counter.most_common(max_candidates)]
|
| 132 |
+
query_items = set(chain(*priority_groups))
|
| 133 |
+
|
| 134 |
+
use_weighted = bool(getattr(self.config, "weighted_icl_sampling", False))
|
| 135 |
+
decay_rate = float(getattr(self.config, "weighted_decay_rate", 0.5))
|
| 136 |
+
batch_query = isinstance(query[0], list) if query else False
|
| 137 |
+
|
| 138 |
+
if use_weighted:
|
| 139 |
+
if batch_query:
|
| 140 |
+
weights_dict = {}
|
| 141 |
+
for depth, group in enumerate(priority_groups):
|
| 142 |
+
w = float(np.exp(-decay_rate * depth))
|
| 143 |
+
for item in group:
|
| 144 |
+
if w > weights_dict.get(item, 0.0):
|
| 145 |
+
weights_dict[item] = w
|
| 146 |
+
weighted_items = list(weights_dict.keys())
|
| 147 |
+
weights_container = weights_dict
|
| 148 |
+
else:
|
| 149 |
+
weighted_items = list(query)
|
| 150 |
+
positions = np.arange(len(query), dtype=np.float32)
|
| 151 |
+
weights_list = np.exp(-decay_rate * (len(query) - 1 - positions)).tolist()
|
| 152 |
+
weights_container = weights_list
|
| 153 |
+
|
| 154 |
+
top_k = total_k
|
| 155 |
+
heap: List[Tuple[float, int]] = []
|
| 156 |
+
push = heapq.heappush
|
| 157 |
+
pop = heapq.heappop
|
| 158 |
+
|
| 159 |
+
for idx in candidate_indices:
|
| 160 |
+
seq_set = self._seq_sets[idx]
|
| 161 |
+
if not seq_set:
|
| 162 |
+
continue
|
| 163 |
+
if use_weighted:
|
| 164 |
+
if isinstance(weights_container, dict):
|
| 165 |
+
num = 0.0
|
| 166 |
+
den = 0.0
|
| 167 |
+
all_items = seq_set | set(weighted_items)
|
| 168 |
+
for item in all_items:
|
| 169 |
+
w1 = weights_container.get(item, 0.0)
|
| 170 |
+
w2 = 1.0 if item in seq_set else 0.0
|
| 171 |
+
num += min(w1, w2)
|
| 172 |
+
den += max(w1, w2)
|
| 173 |
+
sim = (num / den) if den > 0.0 else 0.0
|
| 174 |
+
else:
|
| 175 |
+
wdict = {itm: w for itm, w in zip(weighted_items, weights_container)}
|
| 176 |
+
num = 0.0
|
| 177 |
+
den = 0.0
|
| 178 |
+
all_items = seq_set | set(weighted_items)
|
| 179 |
+
for item in all_items:
|
| 180 |
+
w1 = wdict.get(item, 0.0)
|
| 181 |
+
w2 = 1.0 if item in seq_set else 0.0
|
| 182 |
+
num += min(w1, w2)
|
| 183 |
+
den += max(w1, w2)
|
| 184 |
+
sim = (num / den) if den > 0.0 else 0.0
|
| 185 |
+
else:
|
| 186 |
+
inter = len(seq_set & query_items)
|
| 187 |
+
if inter == 0:
|
| 188 |
+
continue
|
| 189 |
+
union = len(seq_set | query_items)
|
| 190 |
+
sim = inter / union if union > 0 else 0.0
|
| 191 |
+
|
| 192 |
+
if len(heap) < top_k:
|
| 193 |
+
push(heap, (sim, idx))
|
| 194 |
+
else:
|
| 195 |
+
if sim > heap[0][0]:
|
| 196 |
+
pop(heap)
|
| 197 |
+
push(heap, (sim, idx))
|
| 198 |
+
|
| 199 |
+
if not heap:
|
| 200 |
+
return []
|
| 201 |
+
|
| 202 |
+
heap.sort(key=lambda x: x[0], reverse=True)
|
| 203 |
+
similarities = [(self.sequences[idx], float(sim),
|
| 204 |
+
self.user_ids[idx] if self.user_ids is not None else None) for sim, idx in heap]
|
| 205 |
+
return similarities
|
recicl/inference.py
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# SPDX-FileCopyrightText: 2026 devtaji
|
| 2 |
+
# SPDX-License-Identifier: Apache-2.0
|
| 3 |
+
#
|
| 4 |
+
# New file for recICL (not from SAP): loading the released weights and a small inference API around
|
| 5 |
+
# SAP's RecPFN model and context selector. The input conventions follow SAP's evaluation code exactly, so that the
|
| 6 |
+
# scores are the ones the reported evaluation computed:
|
| 7 |
+
# * the query history is cut to its last (max_sequence_len - 1) = 14 items (the evaluation feeds the last 15 items
|
| 8 |
+
# of a sequence minus the target);
|
| 9 |
+
# * each in-context sequence is cut to its last max_sequence_len = 15 items;
|
| 10 |
+
# * item embeddings are L2-normalised, and a zero padding row is placed at index 0 internally (callers use item
|
| 11 |
+
# indices 0..N-1; they are shifted by +1 inside);
|
| 12 |
+
# * scores are dot products between the model output at the last history position and every item embedding.
|
| 13 |
+
"""Load recICL and rank a catalog for one user from their history and a few context sequences."""
|
| 14 |
+
import json
|
| 15 |
+
import os
|
| 16 |
+
|
| 17 |
+
import torch
|
| 18 |
+
import torch.nn.functional as F
|
| 19 |
+
|
| 20 |
+
from .architecture import EmbKNN, RecPFN
|
| 21 |
+
from .config import Config
|
| 22 |
+
from .constants import DEVICE
|
| 23 |
+
from .context_selector import InvertedIndexMatcher
|
| 24 |
+
|
| 25 |
+
CONFIG_FILE = "config.json"
|
| 26 |
+
WEIGHTS_FILE = "model.safetensors"
|
| 27 |
+
|
| 28 |
+
|
| 29 |
+
def load_config(model_dir: str) -> dict:
|
| 30 |
+
"""The released config.json as a dict."""
|
| 31 |
+
with open(os.path.join(model_dir, CONFIG_FILE)) as f:
|
| 32 |
+
return json.load(f)
|
| 33 |
+
|
| 34 |
+
|
| 35 |
+
def load_model(model_dir: str) -> RecPFN:
|
| 36 |
+
"""
|
| 37 |
+
Build RecPFN from config.json and load model.safetensors (strict: every tensor must match).
|
| 38 |
+
|
| 39 |
+
The model is placed on constants.DEVICE (the first CUDA device if available, else the CPU; set
|
| 40 |
+
CUDA_VISIBLE_DEVICES="" to force the CPU) and put in eval mode. The config used is available as model.config.
|
| 41 |
+
"""
|
| 42 |
+
from safetensors.torch import load_file
|
| 43 |
+
|
| 44 |
+
cfg_json = load_config(model_dir)
|
| 45 |
+
config = Config(**cfg_json["model_config"])
|
| 46 |
+
model = RecPFN(input_dim=int(cfg_json["embedding_dim"]), config=config)
|
| 47 |
+
state_dict = load_file(os.path.join(model_dir, WEIGHTS_FILE), device="cpu")
|
| 48 |
+
model.load_state_dict(state_dict, strict=True)
|
| 49 |
+
return model.to(DEVICE).eval()
|
| 50 |
+
|
| 51 |
+
|
| 52 |
+
class ItemCatalog:
|
| 53 |
+
"""
|
| 54 |
+
The candidate items: an [N, D] matrix of item embeddings (row i = item index i), made by the same text encoder
|
| 55 |
+
the model was trained with (see config.json "item_embeddings"). Rows are L2-normalised here, and a zero padding
|
| 56 |
+
row is prepended at index 0 (internal indices are item index + 1), as in SAP's data loader.
|
| 57 |
+
"""
|
| 58 |
+
|
| 59 |
+
def __init__(self, item_embeddings, dim: int = None):
|
| 60 |
+
e = torch.as_tensor(item_embeddings).detach().to(torch.float32).cpu()
|
| 61 |
+
if e.dim() != 2:
|
| 62 |
+
raise ValueError(f"item_embeddings must be [N, D], got shape {tuple(e.shape)}")
|
| 63 |
+
if dim is not None and e.shape[1] != dim:
|
| 64 |
+
raise ValueError(f"item_embeddings have D={e.shape[1]}, the model expects D={dim}")
|
| 65 |
+
e = F.normalize(e, dim=-1)
|
| 66 |
+
self.embeddings = torch.cat([torch.zeros(1, e.shape[1]), e], dim=0).to(DEVICE) # [N + 1, D], row 0 = PAD
|
| 67 |
+
self.n_items = e.shape[0]
|
| 68 |
+
|
| 69 |
+
def __len__(self):
|
| 70 |
+
return self.n_items
|
| 71 |
+
|
| 72 |
+
|
| 73 |
+
def _check_indices(seq, n_items, what):
|
| 74 |
+
bad = [i for i in seq if not (0 <= int(i) < n_items)]
|
| 75 |
+
if bad:
|
| 76 |
+
raise IndexError(f"{what} has item indices outside 0..{n_items - 1}: {bad[:5]}")
|
| 77 |
+
|
| 78 |
+
|
| 79 |
+
class ContextRetriever:
|
| 80 |
+
"""
|
| 81 |
+
Picks the in-context sequences for a query with SAP's InvertedIndexMatcher, as in the evaluation: the pool (other
|
| 82 |
+
users' item-index sequences) is cut into windows of max_sequence_len items (step max_sequence_len // 2), candidate
|
| 83 |
+
windows must contain one of the query's last icl_k items, and the top num_icl_examples windows by
|
| 84 |
+
recency-weighted Jaccard similarity (decay weighted_decay_rate) are returned, most similar first.
|
| 85 |
+
"""
|
| 86 |
+
|
| 87 |
+
def __init__(self, pool_sequences, config: Config):
|
| 88 |
+
self.config = config
|
| 89 |
+
seqs = [[int(i) + 1 for i in s] for s in pool_sequences]
|
| 90 |
+
self.matcher = InvertedIndexMatcher(sequences=seqs, config=config, user_ids=list(range(len(seqs))))
|
| 91 |
+
|
| 92 |
+
def retrieve(self, history, n: int = None) -> list:
|
| 93 |
+
""":return: up to n (default config.num_icl_examples = 8) item-index sequences from the pool."""
|
| 94 |
+
if not history:
|
| 95 |
+
return []
|
| 96 |
+
n = self.config.num_icl_examples if n is None else n
|
| 97 |
+
out = self.matcher.find_closest_batch([[int(i) + 1 for i in history]], total_k=n, k=self.config.icl_k)
|
| 98 |
+
return [[i - 1 for i in seq] for seq, _, _ in out]
|
| 99 |
+
|
| 100 |
+
|
| 101 |
+
@torch.no_grad()
|
| 102 |
+
def score_items(model: RecPFN, catalog: ItemCatalog, history, context=None, include_pad: bool = False):
|
| 103 |
+
"""
|
| 104 |
+
Scores of every catalog item as the next item after `history`.
|
| 105 |
+
|
| 106 |
+
:param model: from load_model().
|
| 107 |
+
:param catalog: ItemCatalog of the candidate items.
|
| 108 |
+
:param history: the user's item indices, oldest first (only the last max_sequence_len - 1 are used).
|
| 109 |
+
:param context: optional list of in-context item-index sequences (e.g. ContextRetriever.retrieve(history)); each
|
| 110 |
+
is cut to its last max_sequence_len items. None or [] runs the model without context.
|
| 111 |
+
:param include_pad: if True, return the N + 1 internal scores (index 0 = padding row, index i + 1 = item i).
|
| 112 |
+
:return: float tensor of shape [N] (or [N + 1]).
|
| 113 |
+
"""
|
| 114 |
+
L = model.config.max_sequence_len
|
| 115 |
+
history = [int(i) for i in history]
|
| 116 |
+
if not history:
|
| 117 |
+
raise ValueError("history must contain at least one item")
|
| 118 |
+
_check_indices(history, catalog.n_items, "history")
|
| 119 |
+
E = catalog.embeddings
|
| 120 |
+
hist = [i + 1 for i in history][-(L - 1):]
|
| 121 |
+
x = E[torch.tensor([hist], device=E.device)] # [1, T, D]
|
| 122 |
+
mask = torch.ones((1, len(hist)), dtype=torch.bool, device=E.device)
|
| 123 |
+
icl = None
|
| 124 |
+
ctx = [[int(i) + 1 for i in s][-L:] for s in (context or []) if len(s)]
|
| 125 |
+
if ctx:
|
| 126 |
+
for s in ctx:
|
| 127 |
+
_check_indices([i - 1 for i in s], catalog.n_items, "context")
|
| 128 |
+
width = max(len(s) for s in ctx)
|
| 129 |
+
icl = E[torch.tensor([s + [0] * (width - len(s)) for s in ctx], device=E.device)] # [n_ctx, width, D]
|
| 130 |
+
out = model(x, mask, icl) # [1, T, D]
|
| 131 |
+
h = out[:, len(hist) - 1, :] # [1, D]
|
| 132 |
+
logits = torch.matmul(h, E.T)[0] # [N + 1], as in SeqRec.get_loss
|
| 133 |
+
return logits if include_pad else logits[1:]
|
| 134 |
+
|
| 135 |
+
|
| 136 |
+
def recommend(model: RecPFN, catalog: ItemCatalog, history, context=None, k: int = 10,
|
| 137 |
+
exclude_history: bool = False):
|
| 138 |
+
"""
|
| 139 |
+
Top-k items for one user.
|
| 140 |
+
|
| 141 |
+
:param exclude_history: drop items already in the history (the reported evaluation does NOT do this; repeat
|
| 142 |
+
purchases count as hits there).
|
| 143 |
+
:return: (item_indices, scores), two lists of length k, best first.
|
| 144 |
+
"""
|
| 145 |
+
# rank the internal [N + 1] vector (padding row at 0) exactly as the evaluation does, so that items with identical
|
| 146 |
+
# scores (e.g. duplicate items with identical embeddings) come out in the same order; then drop the padding row
|
| 147 |
+
s = score_items(model, catalog, history, context, include_pad=True)
|
| 148 |
+
if exclude_history:
|
| 149 |
+
s = s.clone()
|
| 150 |
+
s[torch.tensor(sorted(set(int(i) + 1 for i in history)), device=s.device)] = float("-inf")
|
| 151 |
+
k = min(k, catalog.n_items)
|
| 152 |
+
top = torch.topk(s, k=k)
|
| 153 |
+
if 0 in top.indices.tolist():
|
| 154 |
+
top = torch.topk(s, k=k + 1)
|
| 155 |
+
pairs = [(i - 1, v) for i, v in zip(top.indices.tolist(), top.values.tolist()) if i != 0][:k]
|
| 156 |
+
return [i for i, _ in pairs], [v for _, v in pairs]
|
| 157 |
+
|
| 158 |
+
|
| 159 |
+
@torch.no_grad()
|
| 160 |
+
def baseline_scores(catalog: ItemCatalog, history, mode: str = "last", max_sequence_len: int = 15,
|
| 161 |
+
include_pad: bool = False):
|
| 162 |
+
"""
|
| 163 |
+
The EmbKNN baselines of the evaluation table: 'last' = cosine to the most recent item, 'balanced' = dot product
|
| 164 |
+
with the mean of the (last max_sequence_len - 1) history embeddings.
|
| 165 |
+
|
| 166 |
+
:param include_pad: if True, return the N + 1 internal scores (index 0 = padding row, index i + 1 = item i).
|
| 167 |
+
:return: float tensor of shape [N] (or [N + 1]).
|
| 168 |
+
"""
|
| 169 |
+
E = catalog.embeddings
|
| 170 |
+
hist = [int(i) + 1 for i in history][-(max_sequence_len - 1):]
|
| 171 |
+
x = E[torch.tensor([hist], device=E.device)]
|
| 172 |
+
mask = torch.ones((1, len(hist)), dtype=torch.bool, device=E.device)
|
| 173 |
+
knn = EmbKNN(input_dim=E.shape[1], config=Config(baseline_config=mode))
|
| 174 |
+
out = knn(x, mask)
|
| 175 |
+
logits = torch.matmul(out[:, len(hist) - 1, :], E.T)[0]
|
| 176 |
+
return logits if include_pad else logits[1:]
|
recicl/util/__init__.py
ADDED
|
@@ -0,0 +1,2 @@
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# SPDX-License-Identifier: Apache-2.0
|
| 2 |
+
# New file (recICL, devtaji, 2026-09-30): makes util/ a regular package.
|
recicl/util/metrics.py
ADDED
|
@@ -0,0 +1,203 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# SPDX-FileCopyrightText: 2026 SAP SE or an SAP affiliate company and tabular-ai-recpfn contributors
|
| 2 |
+
# SPDX-License-Identifier: Apache-2.0
|
| 3 |
+
#
|
| 4 |
+
# Copied from src/util/metrics.py of https://github.com/SAP-samples/tabular-ai-recpfn (upstream commit 1af320c),
|
| 5 |
+
# redistributed under the Apache License 2.0 (see LICENSE and NOTICE in the repository root).
|
| 6 |
+
# MODIFIED for recICL by devtaji on 2026-09-30:
|
| 7 |
+
# - absolute imports rewritten as package-relative imports (no code change otherwise)
|
| 8 |
+
|
| 9 |
+
from abc import ABC, abstractmethod
|
| 10 |
+
from typing import List, Union
|
| 11 |
+
import torch
|
| 12 |
+
|
| 13 |
+
from ..config import Config
|
| 14 |
+
|
| 15 |
+
|
| 16 |
+
class Metric(ABC):
|
| 17 |
+
"""Base class for all metrics."""
|
| 18 |
+
|
| 19 |
+
def __init__(self):
|
| 20 |
+
self.reset()
|
| 21 |
+
|
| 22 |
+
@abstractmethod
|
| 23 |
+
def update(self, *args, **kwargs):
|
| 24 |
+
"""
|
| 25 |
+
Batch update
|
| 26 |
+
|
| 27 |
+
:param args: Positional arguments for the metric-specific update.
|
| 28 |
+
:param kwargs: Keyword arguments for the metric-specific update.
|
| 29 |
+
:return: None
|
| 30 |
+
"""
|
| 31 |
+
pass
|
| 32 |
+
|
| 33 |
+
@abstractmethod
|
| 34 |
+
def compute(self):
|
| 35 |
+
"""
|
| 36 |
+
Compute the final metric value.
|
| 37 |
+
|
| 38 |
+
:return: The computed metric value.
|
| 39 |
+
"""
|
| 40 |
+
pass
|
| 41 |
+
|
| 42 |
+
@abstractmethod
|
| 43 |
+
def reset(self):
|
| 44 |
+
"""
|
| 45 |
+
Reset metric state.
|
| 46 |
+
|
| 47 |
+
:return: None
|
| 48 |
+
"""
|
| 49 |
+
pass
|
| 50 |
+
|
| 51 |
+
|
| 52 |
+
class HitRate(Metric):
|
| 53 |
+
"""Hit Rate @ K metric."""
|
| 54 |
+
|
| 55 |
+
def __init__(self, k: int = 10):
|
| 56 |
+
self.k = k
|
| 57 |
+
super().__init__()
|
| 58 |
+
|
| 59 |
+
def reset(self):
|
| 60 |
+
self.hits = 0
|
| 61 |
+
self.total = 0
|
| 62 |
+
|
| 63 |
+
def update(self, preds: torch.Tensor, labels: torch.Tensor):
|
| 64 |
+
"""
|
| 65 |
+
Update with batch predictions and labels.
|
| 66 |
+
|
| 67 |
+
:param preds: Tensor of predicted item ids with shape (batch, num_pred), ordered by relevance.
|
| 68 |
+
:param labels: Tensor of true item ids with shape (batch, 1) or (batch,).
|
| 69 |
+
:return: None
|
| 70 |
+
"""
|
| 71 |
+
if labels.dim() == 2 and labels.size(1) == 1:
|
| 72 |
+
labels = labels.squeeze(1)
|
| 73 |
+
preds = preds.detach().cpu()
|
| 74 |
+
labels = labels.detach().cpu()
|
| 75 |
+
|
| 76 |
+
topk = preds[:, :self.k]
|
| 77 |
+
hits_batch = (topk == labels.unsqueeze(1)).any(dim=1).sum().item()
|
| 78 |
+
self.hits += int(hits_batch)
|
| 79 |
+
self.total += preds.size(0)
|
| 80 |
+
|
| 81 |
+
def compute(self):
|
| 82 |
+
return self.hits / self.total if self.total > 0 else 0.0
|
| 83 |
+
|
| 84 |
+
|
| 85 |
+
class MRR(Metric):
|
| 86 |
+
"""Mean Reciprocal Rank metric."""
|
| 87 |
+
|
| 88 |
+
def __init__(self, k: int = 10):
|
| 89 |
+
"""
|
| 90 |
+
Initialize MRR@K metric.
|
| 91 |
+
|
| 92 |
+
:param k: Cutoff for MRR (compute within top-k).
|
| 93 |
+
:return: None
|
| 94 |
+
"""
|
| 95 |
+
self.k = k
|
| 96 |
+
super().__init__()
|
| 97 |
+
|
| 98 |
+
def reset(self):
|
| 99 |
+
self.reciprocal_ranks = 0.0
|
| 100 |
+
self.total = 0
|
| 101 |
+
|
| 102 |
+
def update(self, preds: torch.Tensor, labels: torch.Tensor):
|
| 103 |
+
"""
|
| 104 |
+
Update with batch predictions and labels.
|
| 105 |
+
|
| 106 |
+
:param preds: Tensor of predicted item ids with shape (batch, num_pred), ordered by relevance.
|
| 107 |
+
:param labels: Tensor of true item ids with shape (batch, 1) or (batch,).
|
| 108 |
+
:return: None
|
| 109 |
+
"""
|
| 110 |
+
if labels.dim() == 2 and labels.size(1) == 1:
|
| 111 |
+
labels = labels.squeeze(1)
|
| 112 |
+
preds = preds.detach().cpu()
|
| 113 |
+
labels = labels.detach().cpu()
|
| 114 |
+
|
| 115 |
+
topk = preds[:, :self.k]
|
| 116 |
+
match = topk == labels.unsqueeze(1)
|
| 117 |
+
pos = torch.where(match, torch.arange(1, self.k + 1).unsqueeze(0).expand_as(topk), torch.zeros_like(topk))
|
| 118 |
+
ranks = pos.clone()
|
| 119 |
+
ranks[ranks == 0] = self.k + 1
|
| 120 |
+
min_ranks = ranks.min(dim=1).values
|
| 121 |
+
rr = torch.where(min_ranks <= self.k, 1.0 / min_ranks.float(), torch.zeros_like(min_ranks, dtype=torch.float))
|
| 122 |
+
self.reciprocal_ranks += rr.sum().item()
|
| 123 |
+
self.total += preds.size(0)
|
| 124 |
+
|
| 125 |
+
def compute(self):
|
| 126 |
+
return self.reciprocal_ranks / self.total if self.total > 0 else 0.0
|
| 127 |
+
|
| 128 |
+
|
| 129 |
+
class Loss(Metric):
|
| 130 |
+
"""Average loss metric."""
|
| 131 |
+
|
| 132 |
+
def __init__(self):
|
| 133 |
+
super().__init__()
|
| 134 |
+
|
| 135 |
+
def reset(self):
|
| 136 |
+
self.sum_loss = 0.0
|
| 137 |
+
self.total = 0
|
| 138 |
+
|
| 139 |
+
def update_single(self, loss: float):
|
| 140 |
+
self.sum_loss += loss
|
| 141 |
+
self.total += 1
|
| 142 |
+
|
| 143 |
+
def update(self, losses: Union[List[float], torch.Tensor], batch_size: int = None):
|
| 144 |
+
if isinstance(losses, torch.Tensor):
|
| 145 |
+
if losses.numel() == 1:
|
| 146 |
+
self.sum_loss += losses.item()
|
| 147 |
+
self.total += batch_size if batch_size else 1
|
| 148 |
+
else:
|
| 149 |
+
losses = losses.cpu().numpy()
|
| 150 |
+
for loss in losses:
|
| 151 |
+
self.update_single(float(loss))
|
| 152 |
+
elif isinstance(losses, (list, tuple)):
|
| 153 |
+
for loss in losses:
|
| 154 |
+
self.update_single(loss)
|
| 155 |
+
else:
|
| 156 |
+
self.sum_loss += float(losses)
|
| 157 |
+
self.total += batch_size if batch_size else 1
|
| 158 |
+
|
| 159 |
+
def compute(self):
|
| 160 |
+
return self.sum_loss / self.total if self.total > 0 else 0.0
|
| 161 |
+
|
| 162 |
+
|
| 163 |
+
class MetricCollection:
|
| 164 |
+
"""Collection of multiple metrics."""
|
| 165 |
+
|
| 166 |
+
def __init__(self, config:Config):
|
| 167 |
+
self.metrics = {}
|
| 168 |
+
for metric_name in config.metrics:
|
| 169 |
+
for k in config.eval_k:
|
| 170 |
+
key = f"{metric_name}@{k}"
|
| 171 |
+
if metric_name == 'hr':
|
| 172 |
+
self.metrics[key] = HitRate(k)
|
| 173 |
+
elif metric_name == 'mrr':
|
| 174 |
+
self.metrics[key] = MRR(k)
|
| 175 |
+
else:
|
| 176 |
+
raise ValueError(f"Unknown metric: {metric_name}")
|
| 177 |
+
self.metrics['loss'] = Loss()
|
| 178 |
+
self.max_k = max(config.eval_k)
|
| 179 |
+
|
| 180 |
+
def reset(self):
|
| 181 |
+
for metric in self.metrics.values():
|
| 182 |
+
metric.reset()
|
| 183 |
+
|
| 184 |
+
def update(self, preds: torch.Tensor, labels: torch.Tensor, loss: float = None):
|
| 185 |
+
for metric in self.metrics.values():
|
| 186 |
+
if isinstance(metric, Loss) and loss is not None:
|
| 187 |
+
metric.update(loss)
|
| 188 |
+
else:
|
| 189 |
+
metric.update(preds, labels)
|
| 190 |
+
|
| 191 |
+
def to_dict(self):
|
| 192 |
+
return {name: metric.compute() for name, metric in self.metrics.items()}
|
| 193 |
+
|
| 194 |
+
def get(self, metric_name: str):
|
| 195 |
+
if metric_name not in self.metrics:
|
| 196 |
+
raise ValueError(f"Metric {metric_name} not found in collection.")
|
| 197 |
+
return self.metrics[metric_name].compute()
|
| 198 |
+
|
| 199 |
+
def log_summary(self):
|
| 200 |
+
log_str = ""
|
| 201 |
+
for name, metric in self.metrics.items():
|
| 202 |
+
log_str += f"{name}: {metric.compute():.4f}; "
|
| 203 |
+
return log_str
|
requirements.txt
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
# Tested with Python 3.11 and exactly these versions (clean CPU container, see README "Quick start").
|
| 2 |
+
torch==2.8.0
|
| 3 |
+
numpy==1.26.4
|
| 4 |
+
safetensors==0.5.3
|