Torch RecSys Model Dev

When to use

• Building or debugging

  torch.nn.Module

  recommender models.
• Working with Transformer, HSTU, attention, FiLM, RAB, MTP, dual-mask, dense/list/sparse feature fusion, pCVR/CTR heads, or ablation axes.
• A repo already has many model designs and bugs come from interface drift, shape mismatch, masking, config flags, or train/eval mismatch.

• Full official competition rule interpretation or submission policy review; use the domain skill such as

  taac-unirec-dl

  when those facts are uncertain.
• Broad literature review or historical plan synthesis.

Context Budget

1. Start from the current task, error, or module name; do not read broad archives first.
2. Keep a compact Data Facts Snapshot in context before model work: target label, train/test field differences, sequence/static feature groups, padding/null rules, metric/loss alignment, and leakage constraints.
3. Prefer

   configs/base.yaml

   , the directly touched

   src/model/*.py

   , the relevant

   src/data/*

   contract file, and the current train/eval entrypoint.
4. Read tests narrowly: one focused test file for the touched module plus one smoke/integration test only when the boundary crosses data -> model -> loss -> eval.
5. Do not load large historical planning or synthesis documents unless the user explicitly asks for design archaeology.

Workflow

1. Identify the active boundary.
   • Choose exactly one primary boundary: data/collate, embedding/fusion, sequence block, head/loss, train loop, evaluator, or config wiring.
   • If the task spans multiple boundaries, write the handoff contract first and change one side at a time.
2. Establish the Data Facts Snapshot.
   • Pull only the facts needed for model design from local official docs, schema code, dataset sample readers, or the domain skill.
   • Include facts in the working context; do not keep model work blind to labels, test shape, missing fields, metric, or leakage constraints.
   • See references/model-contracts.md.
3. Establish contracts before editing.
   • Batch contract: input keys, shape, dtype, padding/null convention, device, and expected missing fields.
   • Model contract:

     forward()

     inputs, output keys, score/logit shape, optional auxiliary outputs only if the current architecture already uses them, and train/eval behavior.
   • Config contract: each optional component has a flag, default, and test-visible behavior.
   • See references/model-contracts.md.
4. Debug systematically.
   • Reproduce the smallest failure command first.
   • Classify the failure as schema, collate, shape, mask, feature fusion, loss, training instability, metric, or config wiring.
   • Fix the first broken contract, then rerun only the smallest relevant verification.
   • See references/debugging-protocol.md.
5. Keep experiments disciplined.
   • One architecture idea per patch.
   • New modules must be ablation-friendly and not silently change baseline behavior.
   • Do not add another model idea while baseline smoke or focused tests are red.
   • See references/experiment-discipline.md.

Inline Example

rg -n "class .*Model|def forward|PcvrConfig|use_|loss|logit" src/model src/train_eval.py configs