# swlee9087/acmrs2026_challenge architecture

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

- Interactive diagram: https://gitdiagram.com/swlee9087/acmrs2026_challenge
- Repository: https://github.com/swlee9087/acmrs2026_challenge

## Overview

This repository is a RecSys Challenge conversational music recommender. Its submitted workflow turns each Blind B session into a deepest-turn request, retrieves tracks from the full catalog using BM25, dense text similarity and listening history, fuses rankings, then generates a grounded rationale and a user-facing response. The graph reflects the documented v10 submission pipeline; sampled source excerpts are partial, so internal wiring beyond documented stages is omitted. The v11 reranker is shown separately because it was written but not scored.

Main entry points: [`src/crs_blind_b_v10.py`](https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py) (Blind B pipeline), [`analysis/eval_composite_2026-06-24.py`](https://github.com/swlee9087/acmrs2026_challenge/blob/main/analysis/eval_composite_2026-06-24.py) (Composite evaluator), [`src/build_blind_b_v7.py`](https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/build_blind_b_v7.py) (Blind B builder), [`src/crs_blind_b_v11.py`](https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v11.py) (Cross-encoder reranker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Input preparation"]
  node_builder["Blind B builder"]
  node_turns["Deepest-turn inputs"]
end

subgraph group_retrieval["Track retrieval"]
  node_catalog["Track catalog"]
  node_pipeline["Blind B pipeline<br/>[crs_blind_b_v10.py]"]
  node_query["Request query<br/>[crs_blind_b_v10.py]"]
  node_bm25["BM25 retrieval<br/>[crs_blind_b_v10.py]"]
  node_dense["Dense retrieval<br/>[crs_blind_b_v10.py]"]
  node_history["History centroid<br/>[crs_blind_b_v10.py]"]
  node_rrf["RRF fusion<br/>[crs_blind_b_v10.py]"]
  node_reranker["Cross-encoder reranker<br/>[crs_blind_b_v11.py]"]
end

subgraph group_response["Response generation"]
  node_candidates["Ranked candidates"]
  node_reasoner["Rationale generation<br/>[crs_blind_b_v10.py]"]
  node_summarizer["Response rewriting<br/>[crs_blind_b_v10.py]"]
  node_submission["Prediction output"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluator["Composite evaluator"]
  node_groundtruth["Ground truth"]
  node_metrics["Recommendation metrics"]
end

node_organizer(("Challenge data"))
node_models["Local model checkpoints"]

node_organizer -->|"provides sessions"| node_builder
node_catalog -->|"reads metadata"| node_builder
node_builder -->|"writes turns"| node_turns
node_turns -->|"feeds inference"| node_pipeline
node_pipeline -->|"loads catalog"| node_catalog
node_pipeline -->|"builds request"| node_query
node_pipeline -->|"runs retrieval"| node_bm25
node_pipeline -->|"runs retrieval"| node_dense
node_pipeline -->|"scores history"| node_history
node_query -->|"scores text"| node_bm25
node_query -->|"encodes request"| node_dense
node_catalog -->|"supplies track text"| node_bm25
node_catalog -->|"supplies track vectors"| node_dense
node_bm25 -->|"sends rankings"| node_rrf
node_dense -->|"sends rankings"| node_rrf
node_history -->|"sends scores"| node_rrf
node_rrf -->|"returns candidates"| node_pipeline
node_pipeline -->|"writes rankings"| node_candidates
node_candidates -->|"grounds rationale"| node_reasoner
node_reasoner -->|"passes rationale"| node_summarizer
node_summarizer -->|"writes response"| node_submission
node_models -->|"loads embedder"| node_dense
node_models -->|"loads Qwen3-32B"| node_reasoner
node_models -->|"loads phi-4"| node_summarizer
node_pipeline -.->|"optionally reranks"| node_reranker
node_models -.->|"loads cross-encoder"| node_reranker
node_submission -->|"scores predictions"| node_evaluator
node_groundtruth -->|"compares outcomes"| node_evaluator
node_catalog -->|"provides catalog size"| node_evaluator
node_evaluator -->|"computes metrics"| node_metrics

click node_builder "https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/build_blind_b_v7.py"
click node_pipeline "https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py"
click node_query "https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py"
click node_bm25 "https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py"
click node_dense "https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py"
click node_history "https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py"
click node_rrf "https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py"
click node_reranker "https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v11.py"
click node_reasoner "https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py"
click node_summarizer "https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py"
click node_evaluator "https://github.com/swlee9087/acmrs2026_challenge/blob/main/analysis/eval_composite_2026-06-24.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_builder,node_turns toneBlue
class node_catalog,node_pipeline,node_query,node_bm25,node_dense,node_history,node_rrf,node_reranker toneAmber
class node_candidates,node_reasoner,node_summarizer,node_submission toneMint
class node_evaluator,node_groundtruth,node_metrics toneRose
class node_organizer,node_models toneIndigo
```

## Components

### Input preparation

- [Blind B builder](https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/build_blind_b_v7.py): `src/build_blind_b_v7.py`
- **Deepest-turn inputs**

### Track retrieval

- **Track catalog**
- [Blind B pipeline](https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py): `src/crs_blind_b_v10.py`
- [Request query](https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py): `src/crs_blind_b_v10.py`
- [BM25 retrieval](https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py): `src/crs_blind_b_v10.py`
- [Dense retrieval](https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py): `src/crs_blind_b_v10.py`
- [History centroid](https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py): `src/crs_blind_b_v10.py`
- [RRF fusion](https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py): `src/crs_blind_b_v10.py`
- [Cross-encoder reranker](https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v11.py): `src/crs_blind_b_v11.py`

### Response generation

- **Ranked candidates**
- [Rationale generation](https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py): `src/crs_blind_b_v10.py`
- [Response rewriting](https://github.com/swlee9087/acmrs2026_challenge/blob/main/src/crs_blind_b_v10.py): `src/crs_blind_b_v10.py`
- **Prediction output**

### Evaluation

- [Composite evaluator](https://github.com/swlee9087/acmrs2026_challenge/blob/main/analysis/eval_composite_2026-06-24.py): `analysis/eval_composite_2026-06-24.py`
- **Ground truth**
- **Recommendation metrics**

### Other components

- **Challenge data**
- **Local model checkpoints**

## Connections

- Challenge data → Blind B builder: provides sessions
- Track catalog → Blind B builder: reads metadata
- Blind B builder → Deepest-turn inputs: writes turns
- Deepest-turn inputs → Blind B pipeline: feeds inference
- Blind B pipeline → Track catalog: loads catalog
- Blind B pipeline → Request query: builds request
- Blind B pipeline → BM25 retrieval: runs retrieval
- Blind B pipeline → Dense retrieval: runs retrieval
- Blind B pipeline → History centroid: scores history
- Request query → BM25 retrieval: scores text
- Request query → Dense retrieval: encodes request
- Track catalog → BM25 retrieval: supplies track text
- Track catalog → Dense retrieval: supplies track vectors
- BM25 retrieval → RRF fusion: sends rankings
- Dense retrieval → RRF fusion: sends rankings
- History centroid → RRF fusion: sends scores
- RRF fusion → Blind B pipeline: returns candidates
- Blind B pipeline → Ranked candidates: writes rankings
- Ranked candidates → Rationale generation: grounds rationale
- Rationale generation → Response rewriting: passes rationale
- Response rewriting → Prediction output: writes response
- Local model checkpoints → Dense retrieval: loads embedder
- Local model checkpoints → Rationale generation: loads Qwen3-32B
- Local model checkpoints → Response rewriting: loads phi-4
- Blind B pipeline → Cross-encoder reranker: optionally reranks
- Local model checkpoints → Cross-encoder reranker: loads cross-encoder
- Prediction output → Composite evaluator: scores predictions
- Ground truth → Composite evaluator: compares outcomes
- Track catalog → Composite evaluator: provides catalog size
- Composite evaluator → Recommendation metrics: computes metrics