# akalikong/minionerec architecture

> Architecture diagram of the GitHub repository akalikong/minionerec, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akalikong/minionerec
- Repository: https://github.com/akalikong/minionerec

## Overview

1. **What this repository is**
   - MiniOneRec is an end-to-end generative recommendation pipeline.
   - The architecture is staged: raw item/user data is cleaned, item text is embedded, those embeddings are compressed into discrete item codes called SIDs, and then an LLM is trained and refined for recommendation.

2. **Core data flow**
   - Raw Amazon review data enters the preprocessing layer.
   - Preprocessed user histories and item metadata feed the embedding/SID construction layer.
   - SID mappings and converted interaction sequences feed supervised fine-tuning.
   - The fine-tuned model then enters a reinforcement-learning stage.
   - Offline evaluation consumes generated recommendations and computes ranking metrics.

3. **Dataset preparation boundary**
   - `data/amazon18_data_process.py`, `data/amazon23_data_process.py`, and their `.sh` wrappers build train/valid/test splits from Amazon datasets.
   - These scripts produce time-filtered interaction CSVs plus item info files.
   - There are GPR-flavored variants that enrich the dataset with heterogeneous signals for the “unified input representation” path.
   - The checked-in `data/Amazon/...` directory contains ready-to-use processed splits for Industrial and Office datasets.

4. **Text-to-embedding subsystem**
   - `rq/text2emb/amazon_text2emb.py` turns each product’s title/description into a dense embedding.
   - This stage depends on an external embedding model checkpoint and, optionally, multi-GPU orchestration via Accelerate.
   - Output is a `.npy` embedding matrix that becomes the input to SID construction.

5. **SID construction subsystem**
   - The `rq/` package is the discrete-item-code factory.
   - It contains multiple alternatives: `rqvae.py` for RQ-VAE, `rqkmeans_faiss.py` for standard RQ-Kmeans, `rqkmeans_constrained.py` for constrained clustering, and `rqkmeans_plus.py` for the plus variant.
   - `rq/generate_indices.py` and `rq/generate_indices_plus.py` export the final SID-to-item indices and item metadata mappings used downstream.
   - The checked-in `data/Amazon/index/*.json` and `.npy` files are artifacts of this stage.

6. **Role of the SID artifacts**
   - SIDs are the central boundary object in the system.
   - They bridge continuous semantic item representations and discrete token generation.
   - Downstream training no longer predicts raw item IDs directly; it predicts SID tokens that correspond to catalog items through the generated index files.

7. **Training-data conversion layer**
   - `convert_dataset.py` reshapes the interaction data into the sequence format expected by the recommendation LLM.
   - The GPR variant injects simulated heterogeneous tokens to match the unified representation used in that line of experiments.
   - This is the main handoff between the SID construction world and the model-training world.

8. **Supervised fine-tuning stage**
   - `sft.py` is the main SFT entrypoint, with `sft_gpr.py` providing the GPR-inspired variant.
   - `minionerec_trainer.py` contains the specialized trainer logic for the generative recommendation objective.
   - `LogitProcessor.py` handles constrained decoding so generation stays within the valid SID/item space.
   - `zero2_opt.yaml` indicates DeepSpeed-style distributed training support for large models.

9. **Reinforcement-learning stage**
   - `rl.py` and `rl_gpr.py` implement the post-SFT optimization phase.
   - This stage refines recommendation quality using group-based policy optimization logic and reward shaping.
   - The trainer remains grounded in the SID vocabulary, so RL is optimizing over a closed item-code action space rather than open-ended text.

10. **Evaluation and diagnostics**
   - `evaluate.py` computes offline ranking metrics such as HR@K and NDCG@K.
   - `calc.py` appears to handle validity/constrained-decoding diagnostics, including detection of invalid generated items.
   - `evaluate.sh` is the top-level evaluation wrapper for reproducing reported results.

11. **Supporting model code and legacy components**
   - `sasrec.py` and `SASRecModules_ori.py` provide SASRec-style sequential recommendation components or baselines.
   - `utility.py`, `split.py`, and `merge.py` support data manipulation and experiment plumbing.
   - `rq/models/` contains the architectural pieces used by the SID-construction models, including RQ/VQ-related layers.

12. **TS-Rec extension**
   - The `ts_rec_*` files and `ts_rec_data/` directory form a newer branch of the codebase focused on fine-grained semantics integration.
   - This is structurally parallel to the main MiniOneRec pipeline, but aimed at the TS-Rec method described in the README announcement.

13. **Infrastructure and external dependencies**
   - The repository is Python-based and assumes GPU training.
   - Important runtime dependencies include DeepSpeed/Accelerate-style distributed training, FAISS for k-means acceleration, and `k_means_constrained`/`polars` for constrained clustering workflows.
   - External LLM providers are used for text enrichment tasks; the repo supports OpenAI, DeepSeek, and MiniMax through a provider abstraction.

14. **How to draw the architecture**
   - A useful diagram should show four major layers: data preprocessing, SID construction, model training, and evaluation.
   - The key artifacts flowing between them are processed interaction CSVs, item text embeddings, SID index files, and model checkpoints.
   - The main architectural constraint is that all recommendation generation is ultimately grounded in the discrete SID catalog built from item semantics.

Main entry points: [`data/Amazon/index/Industrial_and_Scientific.emb-qwen-td.npy`](https://github.com/akalikong/minionerec/blob/main/data/Amazon/index/Industrial_and_Scientific.emb-qwen-td.npy) (Emb matrices), [`sft.py`](https://github.com/akalikong/minionerec/blob/main/sft.py) (SFT), [`rq/generate_indices.py`](https://github.com/akalikong/minionerec/blob/main/rq/generate_indices.py) (SID export), [`data/Amazon`](https://github.com/akalikong/minionerec/tree/main/data/Amazon) (Processed data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data prep"]
  node_amazon_process["Amazon splits<br/>preprocess scripts"]
  node_amazon_data["Processed data<br/>dataset artifacts"]
  node_convert_dataset["Sequence convert<br/>dataset conversion<br/>[convert_dataset.py]"]
end

subgraph group_sid["SID pipeline"]
  node_text2emb["Text embeddings<br/>embedding stage<br/>[amazon_text2emb.py]"]
  node_embeddings["Emb matrices<br/>embedding artifacts"]
  node_rqvae["RQ-VAE<br/>codebook model<br/>[rqvae.py]"]
  node_rqkmeans["RQ-Kmeans<br/>clustering<br/>[rqkmeans_faiss.py]"]
  node_rqkmeans_plus["Plus variant<br/>clustering<br/>[rqkmeans_plus.py]"]
  node_sid_generate["SID export<br/>index builder"]
  node_sid_artifacts["SID catalog<br/>index artifacts"]
end

subgraph group_train["Training"]
  node_sft["SFT<br/>supervised training<br/>[sft.py]"]
  node_minionerec_trainer["Rec trainer"]
  node_logit_processor["Decode guard<br/>constrained decoding<br/>[LogitProcessor.py]"]
  node_rl["RL optimize<br/>policy optimization<br/>[rl.py]"]
end

subgraph group_eval["Evaluation"]
  node_evaluate["Offline eval<br/>metrics<br/>[evaluate.py]"]
  node_calc["Validity check<br/>diagnostics<br/>[calc.py]"]
end

subgraph group_tsrec["TS-Rec"]
  node_tsrec_data["TS-Rec data<br/>semantic data"]
  node_tsrec_sft["TS-Rec SFT<br/>variant training<br/>[ts_rec_sft.py]"]
end

node_amazon_process -->|"builds"| node_amazon_data
node_amazon_data -->|"feeds"| node_text2emb
node_amazon_data -->|"feeds"| node_convert_dataset
node_text2emb -->|"writes"| node_embeddings
node_embeddings -->|"input"| node_rqvae
node_embeddings -->|"input"| node_rqkmeans
node_embeddings -->|"input"| node_rqkmeans_plus
node_rqvae -->|"codes"| node_sid_generate
node_rqkmeans -->|"codes"| node_sid_generate
node_rqkmeans_plus -->|"codes"| node_sid_generate
node_sid_generate -->|"writes"| node_sid_artifacts
node_sid_artifacts -->|"grounds"| node_convert_dataset
node_convert_dataset -->|"train data"| node_sft
node_sft -->|"uses"| node_minionerec_trainer
node_sft -->|"decodes with"| node_logit_processor
node_sft -->|"handoff"| node_rl
node_rl -->|"outputs"| node_evaluate
node_evaluate -->|"checks"| node_calc
node_tsrec_data -->|"feeds"| node_tsrec_sft
node_sid_artifacts -->|"grounds"| node_tsrec_sft

click node_amazon_process "https://github.com/akalikong/minionerec/blob/main/data/amazon18_data_process.py"
click node_amazon_data "https://github.com/akalikong/minionerec/tree/main/data/Amazon"
click node_convert_dataset "https://github.com/akalikong/minionerec/blob/main/convert_dataset.py"
click node_text2emb "https://github.com/akalikong/minionerec/blob/main/rq/text2emb/amazon_text2emb.py"
click node_embeddings "https://github.com/akalikong/minionerec/blob/main/data/Amazon/index/Industrial_and_Scientific.emb-qwen-td.npy"
click node_rqvae "https://github.com/akalikong/minionerec/blob/main/rq/rqvae.py"
click node_rqkmeans "https://github.com/akalikong/minionerec/blob/main/rq/rqkmeans_faiss.py"
click node_rqkmeans_plus "https://github.com/akalikong/minionerec/blob/main/rq/rqkmeans_plus.py"
click node_sid_generate "https://github.com/akalikong/minionerec/blob/main/rq/generate_indices.py"
click node_sid_artifacts "https://github.com/akalikong/minionerec/blob/main/data/Amazon/index/Industrial_and_Scientific.index.json"
click node_sft "https://github.com/akalikong/minionerec/blob/main/sft.py"
click node_minionerec_trainer "https://github.com/akalikong/minionerec/blob/main/minionerec_trainer.py"
click node_logit_processor "https://github.com/akalikong/minionerec/blob/main/LogitProcessor.py"
click node_rl "https://github.com/akalikong/minionerec/blob/main/rl.py"
click node_evaluate "https://github.com/akalikong/minionerec/blob/main/evaluate.py"
click node_calc "https://github.com/akalikong/minionerec/blob/main/calc.py"
click node_tsrec_data "https://github.com/akalikong/minionerec/tree/main/ts_rec_data"
click node_tsrec_sft "https://github.com/akalikong/minionerec/blob/main/ts_rec_sft.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_amazon_process,node_amazon_data,node_convert_dataset toneBlue
class node_text2emb,node_embeddings,node_rqvae,node_rqkmeans,node_rqkmeans_plus,node_sid_generate,node_sid_artifacts toneAmber
class node_sft,node_minionerec_trainer,node_logit_processor,node_rl toneMint
class node_evaluate,node_calc toneRose
class node_tsrec_data,node_tsrec_sft toneIndigo
```

## Components

### Data prep

Raw Amazon reviews are filtered, split, and reshaped into model-ready interaction files.

- [Amazon splits](https://github.com/akalikong/minionerec/blob/main/data/amazon18_data_process.py): preprocess scripts · Builds train/valid/test splits and item info from Amazon review data. · `data/amazon18_data_process.py`
- [Processed data](https://github.com/akalikong/minionerec/tree/main/data/Amazon): dataset artifacts · Checked-in Amazon CSV splits and info files used by training and SID construction. · `data/Amazon`
- [Sequence convert](https://github.com/akalikong/minionerec/blob/main/convert_dataset.py): dataset conversion · Reshapes interactions into the sequence format consumed by recommendation training. · `convert_dataset.py`

### SID pipeline

Item text is embedded, clustered, and converted into discrete SID catalogs and mappings.

- [Text embeddings](https://github.com/akalikong/minionerec/blob/main/rq/text2emb/amazon_text2emb.py): embedding stage · Turns item title/description text into dense embeddings for clustering. · `rq/text2emb/amazon_text2emb.py`
- [Emb matrices](https://github.com/akalikong/minionerec/blob/main/data/Amazon/index/Industrial_and_Scientific.emb-qwen-td.npy): embedding artifacts · Saved item embedding matrices used as input to SID construction. · `data/Amazon/index/Industrial_and_Scientific.emb-qwen-td.npy`
- [RQ-VAE](https://github.com/akalikong/minionerec/blob/main/rq/rqvae.py): codebook model · Alternative discrete representation model for item code learning. · `rq/rqvae.py`
- [RQ-Kmeans](https://github.com/akalikong/minionerec/blob/main/rq/rqkmeans_faiss.py): clustering · Main clustering path for building discrete item codes from embeddings. · `rq/rqkmeans_faiss.py`
- [Plus variant](https://github.com/akalikong/minionerec/blob/main/rq/rqkmeans_plus.py): clustering · Variant clustering path for the plus formulation and constrained settings. · `rq/rqkmeans_plus.py`
- [SID export](https://github.com/akalikong/minionerec/blob/main/rq/generate_indices.py): index builder · Produces SID-to-item index files and item mappings for downstream training. · `rq/generate_indices.py`
- [SID catalog](https://github.com/akalikong/minionerec/blob/main/data/Amazon/index/Industrial_and_Scientific.index.json): index artifacts · Checked-in SID index, item map, and embedding artifacts used as the discrete catalog boundary. · `data/Amazon/index/Industrial_and_Scientific.index.json`

### Training

Supervised fine-tuning and reinforcement learning over the SID vocabulary.

- [SFT](https://github.com/akalikong/minionerec/blob/main/sft.py): supervised training · Main supervised fine-tuning entrypoint for recommendation generation. · `sft.py`
- [Rec trainer](https://github.com/akalikong/minionerec/blob/main/minionerec_trainer.py): trainer · Specialized training logic for the generative recommendation objective. · `minionerec_trainer.py`
- [Decode guard](https://github.com/akalikong/minionerec/blob/main/LogitProcessor.py): constrained decoding · Restricts generation to valid SID/item outputs during decoding. · `LogitProcessor.py`
- [RL optimize](https://github.com/akalikong/minionerec/blob/main/rl.py): policy optimization · Post-SFT reinforcement learning stage that refines recommendation quality. · `rl.py`

### Evaluation

Offline metrics and validity checks for generated recommendations.

- [Offline eval](https://github.com/akalikong/minionerec/blob/main/evaluate.py): metrics · Computes ranking metrics such as HR@K and NDCG@K. · `evaluate.py`
- [Validity check](https://github.com/akalikong/minionerec/blob/main/calc.py): diagnostics · Checks constrained-decoding validity and generated item diagnostics. · `calc.py`

### TS-Rec

Parallel branch for fine-grained semantic integration and TS-Rec experiments.

- [TS-Rec data](https://github.com/akalikong/minionerec/tree/main/ts_rec_data): semantic data · Parallel TS-Rec dataset and keyword artifacts for fine-grained semantic experiments. · `ts_rec_data`
- [TS-Rec SFT](https://github.com/akalikong/minionerec/blob/main/ts_rec_sft.py): variant training · TS-Rec branch for supervised fine-tuning with semantic integration. · `ts_rec_sft.py`

## Connections

- Amazon splits → Processed data: builds · Raw Amazon data is filtered and split into processed datasets.
- Processed data → Text embeddings: feeds · Processed item metadata and histories drive text embedding generation.
- Processed data → Sequence convert: feeds · Processed interactions are reshaped into model sequences.
- Text embeddings → Emb matrices: writes · Text embedding stage outputs dense item vectors.
- Emb matrices → RQ-VAE: input · Embeddings can be modeled by RQ-VAE.
- Emb matrices → RQ-Kmeans: input · Embeddings are clustered into discrete codes.
- Emb matrices → Plus variant: input · Embeddings feed the plus/constrained clustering variants.
- RQ-VAE → SID export: codes · Learned codes are exported into index mappings.
- RQ-Kmeans → SID export: codes · Cluster assignments are exported as SID mappings.
- Plus variant → SID export: codes · Plus variant assignments are exported as SID mappings.
- SID export → SID catalog: writes · SID indices and item maps are materialized as artifacts.
- SID catalog → Sequence convert: grounds · Discrete SID catalog constrains sequence conversion.
- Sequence convert → SFT: train data · Converted sequences become supervised training inputs.
- SFT → Rec trainer: uses · SFT delegates optimization to the specialized trainer.
- SFT → Decode guard: decodes with · Constrained decoding keeps outputs inside the SID space.
- SFT → RL optimize: handoff · Fine-tuned checkpoints feed the RL refinement stage.
- RL optimize → Offline eval: outputs · RL-generated recommendations are evaluated offline.
- Offline eval → Validity check: checks · Evaluation is paired with validity and constraint diagnostics.
- TS-Rec data → TS-Rec SFT: feeds · TS-Rec semantic data supports the parallel training branch.
- SID catalog → TS-Rec SFT: grounds · TS-Rec training remains tied to the SID catalog boundary.
