# synerise/recsys2025 architecture

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

- Interactive diagram: https://gitdiagram.com/synerise/recsys2025
- Repository: https://github.com/synerise/recsys2025

## Overview

This repository is a behavioral-profiles challenge baseline plus its organizer-side evaluation pipeline. Participants generate per-user representations from interaction history; the pipeline validates those embeddings, prepares task-specific targets, trains a separate model per task, and aggregates scores. The baseline’s event-feature aggregation is only one representation approach. The README also documents open and hidden downstream tasks. Some modules are indexed but not excerpted, so their internal relationships are omitted unless the index or README establishes them.

Main entry points: [`training_pipeline/train_runner.py`](https://github.com/synerise/recsys2025/blob/main/training_pipeline/train_runner.py) (Training runner), [`baseline/aggregated_features_baseline/create_embeddings.py`](https://github.com/synerise/recsys2025/blob/main/baseline/aggregated_features_baseline/create_embeddings.py) (Profile generation), [`validator/validate.py`](https://github.com/synerise/recsys2025/blob/main/validator/validate.py) (Validation entry), [`training_pipeline/task_constructor.py`](https://github.com/synerise/recsys2025/blob/main/training_pipeline/task_constructor.py) (Task setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_baseline["Profile baseline"]
  node_profile_generation["Profile generation"]
  node_feature_aggregation["Feature aggregation"]
  node_feature_calculators["Feature calculators<br/>[calculators.py]"]
end

subgraph group_data["Challenge data"]
  node_data_directory["Data directory<br/>[data_dir.py]"]
  node_event_loading["Event loading<br/>[utils.py]"]
end

subgraph group_evaluation["Validation"]
  node_validation_entry["Validation entry<br/>[validate.py]"]
  node_embedding_loading["Embedding loading"]
  node_embedding_checks["Embedding checks"]
end

subgraph group_training["Task training and scoring"]
  node_training_runner["Training runner<br/>[train_runner.py]"]
  node_task_definitions["Task definitions<br/>[tasks.py]"]
  node_task_setup["Task setup"]
  node_target_calculators["Target calculators"]
  node_target_data["Target data<br/>[target_data.py]"]
  node_data_module["Training data module<br/>[data_module.py]"]
  node_model["Task model<br/>[model.py]"]
  node_metric_calculators["Metric calculators"]
  node_metric_containers["Metric results"]
  node_score_aggregator["Score aggregation"]
  node_training_logger["Training logging<br/>[logger_factory.py]"]
  node_logging_config["Logging configuration"]
end

node_participants(("Participants"))
node_event_data["Interaction data"]
node_embedding_files["Embedding files"]
node_evaluation_scores["Evaluation scores"]

node_participants -->|"generate profiles"| node_profile_generation
node_event_data -->|"provides events"| node_profile_generation
node_profile_generation -->|"loads events"| node_event_loading
node_profile_generation -->|"builds features"| node_feature_aggregation
node_feature_aggregation -->|"computes features"| node_feature_calculators
node_participants -->|"submit representations"| node_embedding_files
node_embedding_files -->|"loads for evaluation"| node_validation_entry
node_training_runner -->|"validates and loads"| node_validation_entry
node_validation_entry -->|"loads arrays"| node_embedding_loading
node_validation_entry -->|"checks embeddings"| node_embedding_checks
node_training_runner -->|"reads targets"| node_target_data
node_training_runner -->|"constructs task"| node_task_setup
node_task_setup -->|"dispatches task"| node_task_definitions
node_task_setup -->|"configures targets"| node_target_calculators
node_training_runner -->|"sets up data"| node_data_module
node_training_runner -->|"runs training"| node_model
node_model -->|"calculates metrics"| node_metric_calculators
node_metric_calculators -->|"returns metrics"| node_metric_containers
node_training_runner -->|"aggregates scores"| node_score_aggregator
node_score_aggregator -->|"weights results"| node_metric_containers
node_training_runner -->|"sets up logger"| node_training_logger
node_training_runner -->|"uses configuration"| node_logging_config
node_training_logger -->|"uses configuration"| node_logging_config
node_score_aggregator -->|"saves scores"| node_evaluation_scores

click node_profile_generation "https://github.com/synerise/recsys2025/blob/main/baseline/aggregated_features_baseline/create_embeddings.py"
click node_feature_aggregation "https://github.com/synerise/recsys2025/blob/main/baseline/aggregated_features_baseline/features_aggregator.py"
click node_feature_calculators "https://github.com/synerise/recsys2025/blob/main/baseline/aggregated_features_baseline/calculators.py"
click node_data_directory "https://github.com/synerise/recsys2025/blob/main/data_utils/data_dir.py"
click node_event_loading "https://github.com/synerise/recsys2025/blob/main/data_utils/utils.py"
click node_validation_entry "https://github.com/synerise/recsys2025/blob/main/validator/validate.py"
click node_embedding_loading "https://github.com/synerise/recsys2025/blob/main/validator/loading_validator.py"
click node_embedding_checks "https://github.com/synerise/recsys2025/blob/main/validator/embeddings_validator.py"
click node_training_runner "https://github.com/synerise/recsys2025/blob/main/training_pipeline/train_runner.py"
click node_task_definitions "https://github.com/synerise/recsys2025/blob/main/training_pipeline/tasks.py"
click node_task_setup "https://github.com/synerise/recsys2025/blob/main/training_pipeline/task_constructor.py"
click node_target_calculators "https://github.com/synerise/recsys2025/blob/main/training_pipeline/target_calculators.py"
click node_target_data "https://github.com/synerise/recsys2025/blob/main/training_pipeline/target_data.py"
click node_data_module "https://github.com/synerise/recsys2025/blob/main/training_pipeline/data_module.py"
click node_model "https://github.com/synerise/recsys2025/blob/main/training_pipeline/model.py"
click node_metric_calculators "https://github.com/synerise/recsys2025/blob/main/training_pipeline/metric_calculators.py"
click node_metric_containers "https://github.com/synerise/recsys2025/blob/main/training_pipeline/metrics_containers.py"
click node_score_aggregator "https://github.com/synerise/recsys2025/blob/main/training_pipeline/metric_aggregator.py"
click node_training_logger "https://github.com/synerise/recsys2025/blob/main/training_pipeline/logger_factory.py"
click node_logging_config "https://github.com/synerise/recsys2025/blob/main/training_pipeline/train_logging_config.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_profile_generation,node_feature_aggregation,node_feature_calculators toneBlue
class node_data_directory,node_event_loading toneAmber
class node_validation_entry,node_embedding_loading,node_embedding_checks toneMint
class node_training_runner,node_task_definitions,node_task_setup,node_target_calculators,node_target_data,node_data_module,node_model,node_metric_calculators,node_metric_containers,node_score_aggregator,node_training_logger,node_logging_config toneRose
class node_participants,node_event_data,node_embedding_files,node_evaluation_scores toneIndigo
```

## Components

### Profile baseline

- [Profile generation](https://github.com/synerise/recsys2025/blob/main/baseline/aggregated_features_baseline/create_embeddings.py): `baseline/aggregated_features_baseline/create_embeddings.py`
- [Feature aggregation](https://github.com/synerise/recsys2025/blob/main/baseline/aggregated_features_baseline/features_aggregator.py): `baseline/aggregated_features_baseline/features_aggregator.py`
- [Feature calculators](https://github.com/synerise/recsys2025/blob/main/baseline/aggregated_features_baseline/calculators.py): `baseline/aggregated_features_baseline/calculators.py`

### Challenge data

- [Data directory](https://github.com/synerise/recsys2025/blob/main/data_utils/data_dir.py): `data_utils/data_dir.py`
- [Event loading](https://github.com/synerise/recsys2025/blob/main/data_utils/utils.py): `data_utils/utils.py`

### Validation

- [Validation entry](https://github.com/synerise/recsys2025/blob/main/validator/validate.py): `validator/validate.py`
- [Embedding loading](https://github.com/synerise/recsys2025/blob/main/validator/loading_validator.py): `validator/loading_validator.py`
- [Embedding checks](https://github.com/synerise/recsys2025/blob/main/validator/embeddings_validator.py): `validator/embeddings_validator.py`

### Task training and scoring

- [Training runner](https://github.com/synerise/recsys2025/blob/main/training_pipeline/train_runner.py): `training_pipeline/train_runner.py`
- [Task definitions](https://github.com/synerise/recsys2025/blob/main/training_pipeline/tasks.py): `training_pipeline/tasks.py`
- [Task setup](https://github.com/synerise/recsys2025/blob/main/training_pipeline/task_constructor.py): `training_pipeline/task_constructor.py`
- [Target calculators](https://github.com/synerise/recsys2025/blob/main/training_pipeline/target_calculators.py): `training_pipeline/target_calculators.py`
- [Target data](https://github.com/synerise/recsys2025/blob/main/training_pipeline/target_data.py): `training_pipeline/target_data.py`
- [Training data module](https://github.com/synerise/recsys2025/blob/main/training_pipeline/data_module.py): `training_pipeline/data_module.py`
- [Task model](https://github.com/synerise/recsys2025/blob/main/training_pipeline/model.py): `training_pipeline/model.py`
- [Metric calculators](https://github.com/synerise/recsys2025/blob/main/training_pipeline/metric_calculators.py): `training_pipeline/metric_calculators.py`
- [Metric results](https://github.com/synerise/recsys2025/blob/main/training_pipeline/metrics_containers.py): `training_pipeline/metrics_containers.py`
- [Score aggregation](https://github.com/synerise/recsys2025/blob/main/training_pipeline/metric_aggregator.py): `training_pipeline/metric_aggregator.py`
- [Training logging](https://github.com/synerise/recsys2025/blob/main/training_pipeline/logger_factory.py): `training_pipeline/logger_factory.py`
- [Logging configuration](https://github.com/synerise/recsys2025/blob/main/training_pipeline/train_logging_config.py): `training_pipeline/train_logging_config.py`

### Other components

- **Participants**
- **Interaction data**
- **Embedding files**
- **Evaluation scores**

## Connections

- Participants → Profile generation: generate profiles (evidence: `README.md`)
- Interaction data → Profile generation: provides events (evidence: `README.md`)
- Profile generation → Event loading: loads events (evidence: `baseline/aggregated_features_baseline/create_embeddings.py`)
- Profile generation → Feature aggregation: builds features (evidence: `baseline/aggregated_features_baseline/create_embeddings.py`)
- Feature aggregation → Feature calculators: computes features (evidence: `baseline/aggregated_features_baseline/features_aggregator.py`)
- Participants → Embedding files: submit representations (evidence: `README.md`)
- Embedding files → Validation entry: loads for evaluation
- Training runner → Validation entry: validates and loads (evidence: `training_pipeline/train_runner.py`)
- Validation entry → Embedding loading: loads arrays (evidence: `validator/validate.py`)
- Validation entry → Embedding checks: checks embeddings (evidence: `validator/validate.py`)
- Training runner → Target data: reads targets (evidence: `training_pipeline/train_runner.py`)
- Training runner → Task setup: constructs task (evidence: `training_pipeline/train_runner.py`)
- Task setup → Task definitions: dispatches task (evidence: `training_pipeline/task_constructor.py`)
- Task setup → Target calculators: configures targets (evidence: `training_pipeline/task_constructor.py`)
- Training runner → Training data module: sets up data (evidence: `training_pipeline/train_runner.py`)
- Training runner → Task model: runs training (evidence: `training_pipeline/train_runner.py`)
- Task model → Metric calculators: calculates metrics (evidence: `training_pipeline/model.py`)
- Metric calculators → Metric results: returns metrics (evidence: `training_pipeline/metric_calculators.py`)
- Training runner → Score aggregation: aggregates scores (evidence: `training_pipeline/train_runner.py`)
- Score aggregation → Metric results: weights results (evidence: `training_pipeline/metric_aggregator.py`)
- Training runner → Training logging: sets up logger (evidence: `training_pipeline/train_runner.py`)
- Training runner → Logging configuration: uses configuration (evidence: `training_pipeline/train_runner.py`)
- Training logging → Logging configuration: uses configuration (evidence: `training_pipeline/logger_factory.py`)
- Score aggregation → Evaluation scores: saves scores
