SIDInspector checks exported item-to-semantic-ID mappings before you train or evaluate a downstream generator. Use it to find collisions, check which prefixes preserve item neighborhoods, and see how unique codes are distributed across popular and rare items.
ACM paper | arXiv preprint | Project page | CIKM 2026 Resource Track | Release v1.0.1
The CPU demo requires Python 3.9 or later. Use the CIKM 2026 Resource Track
artifact tagged sidinspector-cikm2026-resource-v1.0.1 (package version 1.0.0).
Install it from a checkout; the package is not on PyPI.
git clone https://github.com/jdding/sidinspector.git
cd sidinspector
git checkout sidinspector-cikm2026-resource-v1.0.1
python3 -m pip install -e .
python3 examples/run_reviewer_quickstart.pyThe demo normalizes a bundled music-like export, checks its joins, and writes
preflight_summary.json and D1–D5 CSV reports to
examples/reviewer_quickstart_output/. The notebook
runs the same demo from an installed checkout. This checks that the workflow
runs. For the paper tables and their evidence, see the
reproducibility matrix.
On the same catalog of 23,742 Musical Instruments items, a larger GRID-style budget reduced aliasing and ReSID/GAOQ had no full-code collisions. The category-prefix control scored highest on neighborhood alignment (D3).
| Artifact | Unique SIDs | D2 full-code aliasing | D3 level-1 neighborhood alignment |
|---|---|---|---|
| GRID-style feature-text (seed 42, widths 64/64/64) | 3,749 | 0.977 | 0.055 |
| GRID-style capacity (budget 32/1280/1280) | 9,874 | 0.779 | 0.080 |
| ReSID/GAOQ | 23,742 | 0.000 | 0.154 |
| Category-prefix control | 23,742 | 0.000 | 0.447 |
The unrounded Table 2 values are included in the repo. The GRID-style feature-text row is a controlled export from a released residual k-means module; it does not reproduce GRID end to end. The deterministic category-prefix row calibrates D3. Recommendation quality requires downstream evaluation.
On the same catalog, the RQ-min reference has 17,247 unique SIDs (D2: 0.440; D3: 0.065). On a separate Instruments index of 9,922 items, LETTER and LC-Rec each have 9,897 unique full SIDs, with D3 of 0.109 and 0.052, respectively.
Workflow figure from Ding et al., CIKM 2026 (arXiv:2606.10375), reproduced under CC BY 4.0.
| Probe | Signal | Typical next check |
|---|---|---|
| D1 utilization | Per-level code use, entropy, and imbalance | Compare active codes with the intended budget. |
| D2 aliasing | Full-code and prefix collisions | Inspect duplicate groups and capacity settings. |
| D3 neighborhood alignment | Prefix recovery of co-occurrence neighborhoods | Compare same-dataset controls and candidate exposure. |
| D4 popularity allocation | Head/mid/tail allocation of unique SIDs | Check whether tail items are disproportionately compressed. |
| D5 structural cost | SID depth, unique IDs, and active prefixes | Inspect fan-out and depth before choosing a decoding stack. |
| D6 churn (optional) | Refresh-to-refresh mapping stability | Trace changed items and affected prefixes. |
The workflow validates sid_assignments, item_metadata, and interactions
before running the probes. D7 accepts optional generator traces; the CIKM paper
does not report D7 results.
For an export with one row per item:
item_id,sid_0,sid_1,sid_2
1,12,3,91
2,12,8,17normalize and inspect it:
python3 examples/minimal_adapter.py \
--input-csv path/to/item_codes.csv \
--output-dir runs/my_tokenizer \
--method my_tokenizer \
--dataset my_dataset
python3 -m sidinspector.preflight \
--sid-assignments runs/my_tokenizer/sid_assignments.parquet \
--item-metadata runs/my_tokenizer/item_metadata.parquet \
--interactions runs/my_tokenizer/interactions.parquet \
--run-metric-smoke
python3 -m sidinspector.metrics \
--sid-assignments runs/my_tokenizer/sid_assignments.parquet \
--item-metadata runs/my_tokenizer/item_metadata.parquet \
--interactions runs/my_tokenizer/interactions.parquet \
--output-dir runs/my_tokenizer/diagnosticsSee the adapter template, validated adapters, and probe interpretation guide for the full contract and supported official artifact paths.
- D2 measures code sharing. It cannot establish causal harm to recommendations.
- D3 depends on the dataset. Compare against controls on the same catalog.
- D5 describes structure. Measure serving latency separately.
- The fixed-reranker probe measures candidate exposure. Assess trained generator quality downstream.
Run the package, quickstart, table, and test checks with:
python3 tools/verify_package.pyThe software is released under the MIT License.
@inproceedings{ding2026sidinspector,
author = {Jiandong Ding and Heng Chang and Huijie Qin and Tianying Liu},
title = {{SIDInspector}: A Mapping-First Diagnostic Resource for
Semantic-ID Tokenizers},
booktitle = {Proceedings of the 35th ACM International Conference on
Information and Knowledge Management},
series = {CIKM '26},
year = {2026},
address = {New York, NY, USA},
location = {Rome, Italy},
publisher = {ACM},
doi = {10.1145/3799682.3840174},
url = {https://doi.org/10.1145/3799682.3840174},
isbn = {979-8-4007-2539-5},
pages = {8890--8894},
numpages = {5}
}GitHub's Cite this repository uses the same reference from
CITATION.cff. The proceedings cover 7–11 November 2026 in
Rome, including the main conference on 9–11 November.
