[feat] SID: add sid_quality_report tool for offline collision/codebook stats

[WhiteSwan1]

What

Adds tzrec/tools/sid_quality_report.py — a single-process CLI that measures the quality of generated Semantic IDs (SIDs) over a whole item corpus. It is the exact, global complement to the per-batch tzrec/metrics/unique_ratio.py::UniqueRatio (which is batch-size-biased and never sees the full corpus at once).

It reads the codes column of a tzrec.predict output for a SID model and reports:

• corpus summary (one row): no_collision_rate, collision_free_item_rate, max_collision, gini, entropy, max_entropy, entropy_ratio;
• per-layer codebook table (one row per layer): coverage, dead_codes, perplexity.

Design

• Framework I/O via create_reader/create_writer — CSV / Parquet / MaxCompute for both read and write; reads only the codes column (no dependency on predict --reserved_columns).
• Counting via mixed-radix int64 SID ids + np.unique (no per-row Python Counter) — ~9x faster at 5M rows; overflow-guarded (product of codebook sizes must fit int64).
• Entropy via torch.special.entr (~10x vs numpy on CPU, multithreaded); numpy elsewhere.
• --codebook is required and validated; out-of-range codes are clamped with a one-shot warning.
• Two all-scalar output tables, so both write natively to CSV/Parquet/ODPS.

Testing

Differentially tested against a Counter reference (200 random trials over L=1..4 codebooks + a 200k-row fixture): identical unique count / frequency distribution / decoded top-SIDs, ~9x faster counting. Edge cases verified: out-of-range clamping, int64 overflow guard, and the CSV string-codes path. ruff check + ruff format clean.

[github-actions]

Review summary

Solid, well-engineered tool. The mixed-radix int64 encoding → single terminal np.unique is sound, the overflow guard correctly keeps every id < capacity ≤ int64.max, docstrings are thorough and accurate (the uniquely_identified_item_rate rename is consistent throughout — no stale collision_free_item_rate left in code/comments), and the gini-over-count-histogram is a genuinely good optimization. Malformed/out-of-range handling is careful and the intent to drop rather than clamp is correct. Divide-by-zero paths are all guarded.

Noteworthy items posted inline: opaque KeyError on a wrong --codes_field; uncaught OverflowError on an out-of-int64 token in the string-codes path; the core pipeline being trapped under __main__ (blocks in-process unit tests of the overflow guard, --log_top_sids decode, entropy_ratio nan, and CSV/string paths); and an end-to-end test whose symmetric 16,16,16 codebook can't catch a radix-ordering bug.

Minor (non-blocking):

• Peak memory: all_ids (list of per-row int64) stays alive through np.concatenate + np.unique (which flattens internally), ~3× the id array at the end. A del all_ids right after ids = np.concatenate(all_ids) sheds one full copy at the top of the advertised row range.
• entropy_ratio denominator: normalized against log(capacity), so when total << capacity (the common case) the ratio can never approach 1.0 even for a perfectly uniform collision-free assignment. If intentional, a one-line note that entropy_ratio < 1 is expected whenever total < capacity would keep readers from misreading it as collisions.
• Docs: other tzrec.tools.* entry points are referenced from docs/; a short invocation snippet in sid_rqkmeans.md/sid_rqvae.md (which already discuss the no-collision-rate target this tool computes) would help discoverability.

[github-actions]

Static review complete. The mixed-radix encoding and malformed/out-of-range row handling are thoughtfully structured. I left five focused inline findings covering input-type correctness, histogram/top-N scaling, Gini interpretation, and cross-batch coverage.

Please also refresh the PR description before merge: it still points to tzrec/tools/sid_quality_report.py, says out-of-range codes are clamped, and names collision_free_item_rate; the implementation is now under tzrec/tools/sid/, drops out-of-range rows, and emits uniquely_identified_item_rate.

No tests or builds were run, per the static-review request.

[github-actions]

n_malformed and n_oob only reach the log, while the saved summary calls the surviving count total. A wrong codebook can therefore drop much of the corpus yet persist healthy-looking global rates. Could we include input/skipped counts in the summary, or fail on out-of-range input?

[github-actions]

type=int accepts zero. Once the shared reader buffers data, a zero batch size repeatedly takes an empty slice without consuming that buffer, so --batch_size 0 can hang on nonempty input. Please reuse _positive_int here.

[github-actions]

Please reject output targets that overlap the input or each other before creating these writers. CSV/Parquet writers overwrite part-0 and ODPS uses overwrite mode, so an output in the input directory/table can destroy the source; equal output paths also make layer stats replace the summary.

[github-actions]

Static review complete. I left three inline findings covering auditable skipped-row accounting, validation of non-positive batch sizes, and protection against output targets overwriting source data or each other. Other specialist suggestions were either already present on the PR or not material enough to repeat. No tests or builds were run.