# lsx-uniwue/semeval-2025-task-2 architecture

> Architecture diagram of the GitHub repository lsx-uniwue/semeval-2025-task-2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lsx-uniwue/semeval-2025-task-2
- Repository: https://github.com/lsx-uniwue/semeval-2025-task-2

## Overview

##### Project Overview
- Type & Purpose: This is a specialized machine translation system that augments translations by incorporating entity-aware knowledge extracted via SQL-based retrieval. It is designed for competitive performance in entity-aware MT tasks without relying on gold-standard entity IDs.
- Key Features: Two-stage approach (entity retrieval followed by knowledge integration) and the use of configurations (via Hydra) and the uv package manager to streamline experiments and training runs.

##### Main Components
a. External Data & Support Systems:
- Wikidata Database: An external, pre-built database derived from the Wikidata dump (located in /data/wikidata). It serves as the entity knowledge base.
- Data Inputs: Raw input text to be translated and associated Wikidata-derived information.

b. Core Processing Modules:
- Entity Retrieval Module:
- Implements normalized string matching using SQL.
- Retrieves and scores candidate entities based on relevance and string length.
- This as a dedicated component that interacts with the Wikidata database.
- Knowledge Integration Module:
- Augments the source text with entity-translation pairs.
- Implements pointer generation and logit biasing during beam search.
- Translation Module:
- Uses the augmented input for translation output.
- Likely built using models defined in src/models (e.g., entity_aware_m2m100_model, translation_module, entity_reranker_model).

c. Configuration and Management:
- Configuration Management: Handled by Hydra using configuration files (such as src/conf/translation_config.yaml) to manage hyperparameters (e.g., pointer generator flag, sequence bias weight).
- Package/Environment Management: Managed via uv (see the uv.sync and uv.run commands in the README).

d. Auxiliary Components:
- Data Management: Data ingestion and preparation components (found in directories like src/data and dspy-approach) that prepare inputs and manage predictions.
- Evaluation & Experimentation: Notebooks in eval_notebooks and Slurm scripts (semeval_slurm.sh, slurm_runs.sh, slurm_ablations.sh) for running ablation studies and cluster-based experiments.
- Baselines/Comparative Pipelines: Multiple baseline directories under /data/predictions (e.g., Baseline_Deepl, Baseline_Google, Mask&Translate, etc.) showing experimental comparisons.

##### Architectural Patterns and Technologies
- Layered Architecture: Separate modules for data ingestion/preprocessing, entity retrieval, knowledge integration, and translation.
- Config Driven Execution: The system leverages Hydra to manage configurations robustly.
- Containerization & CI: The presence of GitHub workflows (in .github/workflows) and uv as a package manager indicate a structured deployment and testing mechanism.
- Experimental Design: Multiple baselines are maintained, and evaluation scripts and notebooks facilitate comparative analysis.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Inputs and Data Management
    raw_input["Raw Input Text"]:::input
    data_dir["Data Directory"]:::data
    data_prep["Data Prep Script"]:::data
    wikidata["Wikidata Database"]:::database

    %% Core Processing Modules
    ER["Entity Retrieval Module"]:::processing
    KI["Knowledge Integration Module"]:::processing
    TM["Translation Module"]:::processing

    %% Management and Configuration
    config["Hydra Config"]:::config
    pkg["Package/Environment Management"]:::management

    %% Evaluation and Experimentation
    eval_nb["Eval Notebooks"]:::evaluation
    slurm["Slurm Scripts"]:::evaluation

    %% Flow Connections - Vertical Layout
    raw_input --> ER
    ER --> KI
    KI --> TM
    TM -->|"Produces"| final["Final Translated Output"]:::output

    %% Data Management supports raw input preparation
    data_dir --> raw_input
    data_prep --> raw_input

    %% Entity Retrieval queries Wikidata Database
    ER -->|"queries"| wikidata

    %% Configuration influences processing modules
    config --- ER
    config --- KI
    config --- TM

    %% Package management supports configuration and system execution
    pkg --- config

    %% Evaluation receives output and compares with baselines
    final --> eval_nb
    final --> slurm

    %% Styles and Colors
    classDef input fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef data fill:#ADFF2F,stroke:#333,stroke-width:2px;
    classDef processing fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef database fill:#98FB98,stroke:#333,stroke-width:2px,stroke-dasharray: 5 5;
    classDef config fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef management fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef evaluation fill:#DA70D6,stroke:#333,stroke-width:2px;
    classDef output fill:#D3D3D3,stroke:#333,stroke-width:2px;

    %% Click Events for Components with Mapped Paths
    click wikidata "https://github.com/lsx-uniwue/semeval-2025-task-2/tree/main//data/wikidata"
    click ER "https://github.com/lsx-uniwue/semeval-2025-task-2/blob/main//src/utils/entity_retrieval.py"
    click KI "https://github.com/lsx-uniwue/semeval-2025-task-2/blob/main//dspy-approach/translation-job.yaml"
    click TM "https://github.com/lsx-uniwue/semeval-2025-task-2/blob/main//src/models/translation_module.py"
    click config "https://github.com/lsx-uniwue/semeval-2025-task-2/blob/main//src/conf/translation_config.yaml"
    click pkg "https://github.com/lsx-uniwue/semeval-2025-task-2/blob/main/uv.lock"
    click data_dir "https://github.com/lsx-uniwue/semeval-2025-task-2/tree/main//src/data"
    click data_prep "https://github.com/lsx-uniwue/semeval-2025-task-2/blob/main/dspy-approach/process_finetuned_translations.py"
    click eval_nb "https://github.com/lsx-uniwue/semeval-2025-task-2/tree/main/eval_notebooks"
    click slurm "https://github.com/lsx-uniwue/semeval-2025-task-2/blob/main/semeval_slurm.sh"
    
    %% Additional Click Events for Translation Module Supporting Files
    click TM "https://github.com/lsx-uniwue/semeval-2025-task-2/blob/main//src/models/translation_module.py"
    %% Supporting translation module files:
    click m2m "https://github.com/lsx-uniwue/semeval-2025-task-2/blob/main/src/models/entity_aware_m2m100_model.py"
    click reranker "https://github.com/lsx-uniwue/semeval-2025-task-2/blob/main/src/models/entity_reranker_model.py"

    %% Note: The supporting translation module files are represented by:
    m2m["Entity Aware M2M100 Model"]:::processing
    reranker["Entity Reranker Model"]:::processing
    TM --- m2m
    TM --- reranker
```
