# soheilaansari/persian-culture-aware-translation architecture

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

- Interactive diagram: https://gitdiagram.com/soheilaansari/persian-culture-aware-translation
- Repository: https://github.com/soheilaansari/persian-culture-aware-translation

## Overview

The repository releases three research capabilities: a text-only Persian→English translation baseline, its audio-conditioned extension, and a culture-specific-item (CSI) tagging and evaluation pipeline. The principal user-facing workflow is supplying English hypotheses and CSI-tagged test data plus lexicons to compute CSI-Recall. The documented stages connect corpus preparation, model training, annotation, alignment, lexicon construction, and evaluation. The CSI pipeline links are documented in the README; sampled source excerpts provide additional implementation evidence, but unsampled internals are not assumed.

Main entry points: [`src/csi_evaluation/annotate_corpus.py`](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/csi_evaluation/annotate_corpus.py) (Corpus Annotation), [`data/Masnavi coprus`](https://github.com/soheilaansari/persian-culture-aware-translation/tree/main/data/Masnavi%20coprus) (Masnavi Pairs), [`src/text_baseline/finetune.py`](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/text_baseline/finetune.py) (Parallel Fine-tuning), [`src/csi_evaluation/csi_recall_metric.py`](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/csi_evaluation/csi_recall_metric.py) (CSI-Recall)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_text["Text Baseline"]
  node_dap["Domain Pretraining<br/>[domain_pretrain.py]"]
  node_finetune["Parallel Fine-tuning<br/>[finetune.py]"]
  node_text_eval["Translation Metrics<br/>[evaluate.py]"]
end

subgraph group_audio["Multimodal Translation"]
  node_mm_config["Training Config<br/>[config.py]"]
  node_mm_loader["Text Audio Loader<br/>[data_loader.py]"]
  node_mm_model["Fusion Model<br/>[model.py]"]
  node_mm_train["Multimodal Training<br/>[train.py]"]
end

subgraph group_csi["CSI Evaluation"]
  node_annotations["Gold CSI Spans"]
  node_bio["BIO Dataset Prep"]
  node_tagger_train["CSI Tagger Training<br/>[train_tagger.py]"]
  node_annotate["Corpus Annotation<br/>[annotate_corpus.py]"]
  node_align_prep["Alignment Preparation"]
  node_align["Awesome-align"]
  node_lexicon["CSI Lexicon<br/>[extract_lexicon.py]"]
  node_recall["CSI-Recall"]
  node_report["Recall Results"]
end

subgraph group_data["Research Data"]
  node_poetry["Persian Poetry"]
  node_parallel["Masnavi Pairs"]
end

node_hypotheses["English Hypotheses"]

node_poetry -->|"trains on"| node_dap
node_dap -->|"provides checkpoint"| node_finetune
node_parallel -->|"fine-tunes on"| node_finetune
node_finetune -->|"evaluates model"| node_text_eval
node_parallel -->|"test split"| node_text_eval
node_mm_config -->|"configures"| node_mm_train
node_mm_loader -->|"supplies batches"| node_mm_train
node_finetune -->|"initializes text encoder"| node_mm_model
node_mm_model -->|"trained by"| node_mm_train
node_parallel -->|"aligned text rows"| node_mm_loader
node_annotations -->|"converts spans"| node_bio
node_bio -->|"trains from"| node_tagger_train
node_tagger_train -->|"provides tagger"| node_annotate
node_parallel -->|"annotates corpus"| node_annotate
node_annotate -->|"prepares tagged pairs"| node_align_prep
node_align_prep -->|"provides alignment input"| node_align
node_align -->|"provides alignments"| node_lexicon
node_annotate -->|"provides tagged pairs"| node_lexicon
node_hypotheses -->|"scores translations"| node_recall
node_lexicon -->|"judges CSI spans"| node_recall
node_annotate -->|"supplies tagged test data"| node_recall
node_recall -->|"reports scores"| node_report

click node_parallel "https://github.com/soheilaansari/persian-culture-aware-translation/tree/main/data/Masnavi%20coprus"
click node_dap "https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/text_baseline/domain_pretrain.py"
click node_finetune "https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/text_baseline/finetune.py"
click node_text_eval "https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/text_baseline/evaluate.py"
click node_mm_config "https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/multi-modal/config.py"
click node_mm_loader "https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/multi-modal/data_loader.py"
click node_mm_model "https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/multi-modal/model.py"
click node_mm_train "https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/multi-modal/train.py"
click node_bio "https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/csi_evaluation/prepare_bio_dataset.py"
click node_tagger_train "https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/csi_evaluation/train_tagger.py"
click node_annotate "https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/csi_evaluation/annotate_corpus.py"
click node_align_prep "https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/csi_evaluation/prepare_alignment_input.py"
click node_lexicon "https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/csi_evaluation/extract_lexicon.py"
click node_recall "https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/csi_evaluation/csi_recall_metric.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_dap,node_finetune,node_text_eval toneBlue
class node_mm_config,node_mm_loader,node_mm_model,node_mm_train toneAmber
class node_annotations,node_bio,node_tagger_train,node_annotate,node_align_prep,node_align,node_lexicon,node_recall,node_report toneMint
class node_poetry,node_parallel toneRose
class node_hypotheses toneIndigo
```

## Components

### Text Baseline

- [Domain Pretraining](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/text_baseline/domain_pretrain.py): `src/text_baseline/domain_pretrain.py`
- [Parallel Fine-tuning](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/text_baseline/finetune.py): `src/text_baseline/finetune.py`
- [Translation Metrics](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/text_baseline/evaluate.py): `src/text_baseline/evaluate.py`

### Multimodal Translation

- [Training Config](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/multi-modal/config.py): `src/multi-modal/config.py`
- [Text Audio Loader](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/multi-modal/data_loader.py): `src/multi-modal/data_loader.py`
- [Fusion Model](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/multi-modal/model.py): `src/multi-modal/model.py`
- [Multimodal Training](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/multi-modal/train.py): `src/multi-modal/train.py`

### CSI Evaluation

- **Gold CSI Spans**
- [BIO Dataset Prep](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/csi_evaluation/prepare_bio_dataset.py): `src/csi_evaluation/prepare_bio_dataset.py`
- [CSI Tagger Training](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/csi_evaluation/train_tagger.py): `src/csi_evaluation/train_tagger.py`
- [Corpus Annotation](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/csi_evaluation/annotate_corpus.py): `src/csi_evaluation/annotate_corpus.py`
- [Alignment Preparation](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/csi_evaluation/prepare_alignment_input.py): `src/csi_evaluation/prepare_alignment_input.py`
- **Awesome-align**
- [CSI Lexicon](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/csi_evaluation/extract_lexicon.py): `src/csi_evaluation/extract_lexicon.py`
- [CSI-Recall](https://github.com/soheilaansari/persian-culture-aware-translation/blob/main/src/csi_evaluation/csi_recall_metric.py): `src/csi_evaluation/csi_recall_metric.py`
- **Recall Results**

### Research Data

- **Persian Poetry**
- [Masnavi Pairs](https://github.com/soheilaansari/persian-culture-aware-translation/tree/main/data/Masnavi%20coprus): `data/Masnavi coprus`

### Other components

- **English Hypotheses**

## Connections

- Persian Poetry → Domain Pretraining: trains on (evidence: `README.md`)
- Domain Pretraining → Parallel Fine-tuning: provides checkpoint (evidence: `README.md`)
- Masnavi Pairs → Parallel Fine-tuning: fine-tunes on (evidence: `README.md`)
- Parallel Fine-tuning → Translation Metrics: evaluates model (evidence: `README.md`)
- Masnavi Pairs → Translation Metrics: test split (evidence: `README.md`)
- Training Config → Multimodal Training: configures (evidence: `src/multi-modal/train.py`)
- Text Audio Loader → Multimodal Training: supplies batches (evidence: `src/multi-modal/train.py`)
- Parallel Fine-tuning → Fusion Model: initializes text encoder (evidence: `README.md`)
- Fusion Model → Multimodal Training: trained by (evidence: `README.md`)
- Masnavi Pairs → Text Audio Loader: aligned text rows (evidence: `README.md`)
- Gold CSI Spans → BIO Dataset Prep: converts spans (evidence: `README.md`)
- BIO Dataset Prep → CSI Tagger Training: trains from (evidence: `README.md`)
- CSI Tagger Training → Corpus Annotation: provides tagger (evidence: `README.md`)
- Masnavi Pairs → Corpus Annotation: annotates corpus (evidence: `README.md`)
- Corpus Annotation → Alignment Preparation: prepares tagged pairs (evidence: `README.md`)
- Alignment Preparation → Awesome-align: provides alignment input (evidence: `README.md`)
- Awesome-align → CSI Lexicon: provides alignments (evidence: `README.md`)
- Corpus Annotation → CSI Lexicon: provides tagged pairs (evidence: `README.md`)
- English Hypotheses → CSI-Recall: scores translations (evidence: `README.md`)
- CSI Lexicon → CSI-Recall: judges CSI spans (evidence: `README.md`)
- Corpus Annotation → CSI-Recall: supplies tagged test data (evidence: `README.md`)
- CSI-Recall → Recall Results: reports scores (evidence: `README.md`)
