devtaji commited on
Commit
08646a9
·
0 Parent(s):

recICL v0

Browse files
.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