# metesertkan/emorec architecture

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

- Interactive diagram: https://gitdiagram.com/metesertkan/emorec
- Repository: https://github.com/metesertkan/emorec

## Overview

EmoRec is a research implementation of emotion-aware neural news recommendation. The data workflow prepares news text, emotion features, and user-impression examples; training loads those examples and fits a model with separate semantic and emotional representations. The model scores candidate stories against a user representation, while the documented test workflow evaluates a selected checkpoint. The source excerpts show the model’s internal encoder calls and training wiring; test implementation and some preprocessing orchestration are not sampled, so those links are conservative.

Main entry points: [`project/models/emorec/__init__.py`](https://github.com/metesertkan/emorec/blob/main/project/models/emorec/__init__.py) (EMOREC scoring), [`project/train.py`](https://github.com/metesertkan/emorec/blob/main/project/train.py) (Training entry), [`project/data/parse_news.py`](https://github.com/metesertkan/emorec/blob/main/project/data/parse_news.py) (News preprocessing), [`project/models/utils.py`](https://github.com/metesertkan/emorec/blob/main/project/models/utils.py) (Attention utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_news_parse["News preprocessing<br/>[parse_news.py]"]
  node_behavior_parse["Behavior preprocessing<br/>[parse_behavior.py]"]
  node_dataset["Batch dataset<br/>[dataset.py]"]
  node_taxonomy_config["Emotion taxonomies"]
end

subgraph group_model["Recommendation model"]
  node_emorec["EMOREC scoring<br/>[__init__.py]"]
  node_semantic["Semantic encoder"]
  node_emotion_pool["Emotion pooling<br/>[emotion_pooling.py]"]
  node_emotion_user["Emotion encoder<br/>[emotion_encoder.py]"]
  node_semantic_user["User encoder<br/>[user_encoder.py]"]
  node_attention["Attention utilities<br/>[utils.py]"]
  node_metrics["Ranking metrics<br/>[metrics.py]"]
end

subgraph group_run["Training and evaluation"]
  node_train["Training entry<br/>[train.py]"]
  node_test["Test entry<br/>[test.py]"]
end

node_researcher(("Researcher"))
node_mind["MIND data"]
node_embeddings["Word embeddings"]
node_recommendations["Candidate scores"]

node_researcher -->|"prepares news"| node_news_parse
node_researcher -->|"prepares behavior"| node_behavior_parse
node_mind -->|"provides articles"| node_news_parse
node_embeddings -->|"provides vectors"| node_news_parse
node_news_parse -.->|"news features"| node_dataset
node_behavior_parse -.->|"impression examples"| node_dataset
node_researcher -->|"starts training"| node_train
node_researcher -->|"runs evaluation"| node_test
node_train -->|"loads examples"| node_dataset
node_train -->|"initializes model"| node_emorec
node_taxonomy_config -->|"configures run"| node_train
node_emorec -->|"encodes text"| node_semantic
node_emorec -->|"pools emotions"| node_emotion_pool
node_emorec -->|"encodes user emotion"| node_emotion_user
node_emorec -->|"encodes user history"| node_semantic_user
node_semantic -->|"uses attention"| node_attention
node_emotion_pool -->|"uses attention"| node_attention
node_emotion_user -->|"uses attention"| node_attention
node_semantic_user -->|"uses attention"| node_attention
node_emorec -->|"updates metrics"| node_metrics
node_emorec -->|"returns scores"| node_recommendations
node_test -.->|"evaluates checkpoint"| node_emorec

click node_news_parse "https://github.com/metesertkan/emorec/blob/main/project/data/parse_news.py"
click node_behavior_parse "https://github.com/metesertkan/emorec/blob/main/project/data/parse_behavior.py"
click node_dataset "https://github.com/metesertkan/emorec/blob/main/project/data/dataset.py"
click node_taxonomy_config "https://github.com/metesertkan/emorec/tree/main/project/config/model/emorec"
click node_train "https://github.com/metesertkan/emorec/blob/main/project/train.py"
click node_test "https://github.com/metesertkan/emorec/blob/main/project/test.py"
click node_emorec "https://github.com/metesertkan/emorec/blob/main/project/models/emorec/__init__.py"
click node_semantic "https://github.com/metesertkan/emorec/blob/main/project/models/emorec/semantic_encoder.py"
click node_emotion_pool "https://github.com/metesertkan/emorec/blob/main/project/models/emorec/emotion_pooling.py"
click node_emotion_user "https://github.com/metesertkan/emorec/blob/main/project/models/emorec/emotion_encoder.py"
click node_semantic_user "https://github.com/metesertkan/emorec/blob/main/project/models/emorec/user_encoder.py"
click node_attention "https://github.com/metesertkan/emorec/blob/main/project/models/utils.py"
click node_metrics "https://github.com/metesertkan/emorec/blob/main/project/models/metrics.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_news_parse,node_behavior_parse,node_dataset,node_taxonomy_config toneBlue
class node_emorec,node_semantic,node_emotion_pool,node_emotion_user,node_semantic_user,node_attention,node_metrics toneAmber
class node_train,node_test toneMint
class node_researcher,node_mind,node_embeddings,node_recommendations toneIndigo
```

## Components

### Data preparation

- [News preprocessing](https://github.com/metesertkan/emorec/blob/main/project/data/parse_news.py): `project/data/parse_news.py`
- [Behavior preprocessing](https://github.com/metesertkan/emorec/blob/main/project/data/parse_behavior.py): `project/data/parse_behavior.py`
- [Batch dataset](https://github.com/metesertkan/emorec/blob/main/project/data/dataset.py): `project/data/dataset.py`
- [Emotion taxonomies](https://github.com/metesertkan/emorec/tree/main/project/config/model/emorec): `project/config/model/emorec`

### Recommendation model

- [EMOREC scoring](https://github.com/metesertkan/emorec/blob/main/project/models/emorec/__init__.py): `project/models/emorec/__init__.py`
- [Semantic encoder](https://github.com/metesertkan/emorec/blob/main/project/models/emorec/semantic_encoder.py): `project/models/emorec/semantic_encoder.py`
- [Emotion pooling](https://github.com/metesertkan/emorec/blob/main/project/models/emorec/emotion_pooling.py): `project/models/emorec/emotion_pooling.py`
- [Emotion encoder](https://github.com/metesertkan/emorec/blob/main/project/models/emorec/emotion_encoder.py): `project/models/emorec/emotion_encoder.py`
- [User encoder](https://github.com/metesertkan/emorec/blob/main/project/models/emorec/user_encoder.py): `project/models/emorec/user_encoder.py`
- [Attention utilities](https://github.com/metesertkan/emorec/blob/main/project/models/utils.py): `project/models/utils.py`
- [Ranking metrics](https://github.com/metesertkan/emorec/blob/main/project/models/metrics.py): `project/models/metrics.py`

### Training and evaluation

- [Training entry](https://github.com/metesertkan/emorec/blob/main/project/train.py): `project/train.py`
- [Test entry](https://github.com/metesertkan/emorec/blob/main/project/test.py): `project/test.py`

### Other components

- **Researcher**
- **MIND data**
- **Word embeddings**
- **Candidate scores**

## Connections

- Researcher → News preprocessing: prepares news (evidence: `README.md`)
- Researcher → Behavior preprocessing: prepares behavior (evidence: `README.md`)
- MIND data → News preprocessing: provides articles (evidence: `README.md`)
- Word embeddings → News preprocessing: provides vectors (evidence: `project/data/parse_news.py`)
- News preprocessing → Batch dataset: news features
- Behavior preprocessing → Batch dataset: impression examples
- Researcher → Training entry: starts training (evidence: `README.md`)
- Researcher → Test entry: runs evaluation (evidence: `README.md`)
- Training entry → Batch dataset: loads examples (evidence: `project/train.py`)
- Training entry → EMOREC scoring: initializes model (evidence: `project/train.py`)
- Emotion taxonomies → Training entry: configures run (evidence: `README.md`)
- EMOREC scoring → Semantic encoder: encodes text (evidence: `project/models/emorec/__init__.py`)
- EMOREC scoring → Emotion pooling: pools emotions (evidence: `project/models/emorec/__init__.py`)
- EMOREC scoring → Emotion encoder: encodes user emotion (evidence: `project/models/emorec/__init__.py`)
- EMOREC scoring → User encoder: encodes user history (evidence: `project/models/emorec/__init__.py`)
- Semantic encoder → Attention utilities: uses attention (evidence: `project/models/emorec/semantic_encoder.py`)
- Emotion pooling → Attention utilities: uses attention (evidence: `project/models/emorec/emotion_pooling.py`)
- Emotion encoder → Attention utilities: uses attention (evidence: `project/models/emorec/emotion_encoder.py`)
- User encoder → Attention utilities: uses attention (evidence: `project/models/emorec/user_encoder.py`)
- EMOREC scoring → Ranking metrics: updates metrics (evidence: `project/models/emorec/__init__.py`)
- EMOREC scoring → Candidate scores: returns scores (evidence: `project/models/emorec/__init__.py`)
- Test entry → EMOREC scoring: evaluates checkpoint
