# ani3h/semcom architecture

> Architecture diagram of the GitHub repository ani3h/semcom, 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/ani3h/semcom
- Repository: https://github.com/ani3h/semcom

## Overview

semcom is a semantic-communication research package: its current runtime supports modality-specific dataset loading, transceiver training through simulated channels, task-metric evaluation across SNR values, and experiment reporting. The main workflow is the Week 4 training entry point, which instantiates configured task, channel, and datasets, trains and evaluates, then saves results and plots. The README also documents audio, image, and text tasks plus AWGN/Rayleigh comparisons. Some dataset and modality wiring is configured dynamically; the graph shows only relationships evidenced by the README, source index, or excerpts.

Main entry points: [`experiments/week4_train.py`](https://github.com/ani3h/semcom/blob/main/experiments/week4_train.py) (Training driver), [`src/semcom/encoders/base.py`](https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/base.py) (Task interface), [`src/semcom/data/base.py`](https://github.com/ani3h/semcom/blob/main/src/semcom/data/base.py) (Dataset interface), [`src/semcom/encoders/audio/task.py`](https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/audio/task.py) (Audio task)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data loading"]
  node_dataset_base["Dataset interface<br/>[base.py]"]
  node_splits["Dataset splitting<br/>[splits.py]"]
  node_audio_data["Edinburgh audio<br/>[audio_edinburgh.py]"]
  node_image_data["CIFAR-10 and MNIST"]
  node_text_data["Europarl text<br/>[text_europarl.py]"]
end

subgraph group_transmission["Transceivers and channels"]
  node_task_base["Task interface<br/>[base.py]"]
  node_audio_task["Audio task<br/>[task.py]"]
  node_audio_model["Audio transceiver<br/>[model.py]"]
  node_image_task["Image tasks<br/>[task.py]"]
  node_image_model["Image transceiver<br/>[model.py]"]
  node_text_task["Text task<br/>[task.py]"]
  node_text_model["Text transceiver<br/>[model.py]"]
  node_tokenizer["Word tokenizer<br/>[tokenizer.py]"]
  node_channel_base["Channel interface<br/>[base.py]"]
  node_awgn["AWGN simulation<br/>[awgn.py]"]
  node_rayleigh["Rayleigh simulation<br/>[rayleigh.py]"]
end

subgraph group_evaluation["Training and evaluation"]
  node_train["Training driver<br/>[week4_train.py]"]
  node_config["Experiment config<br/>[week4.yaml]"]
  node_audio_metrics["Audio metrics<br/>[metrics.py]"]
  node_results["Metrics and artifacts<br/>[week4_train.py]"]
end

subgraph group_tracking["Experiment tracking"]
  node_naming["Run naming<br/>[run_naming.py]"]
  node_seeding["Random seeding<br/>[seed.py]"]
  node_wandb["W&amp;B logging<br/>[wandb_logger.py]"]
  node_plots["SNR plots<br/>[plots.py]"]
end

node_engineer(("Experiment user"))

node_engineer -->|"runs"| node_train
node_train -->|"loads config"| node_config
node_train -->|"runs task methods"| node_task_base
node_train -->|"instantiates channel"| node_channel_base
node_train -->|"instantiates datasets"| node_dataset_base
node_audio_data -->|"implements"| node_dataset_base
node_audio_data -->|"gets split indices"| node_splits
node_image_data -->|"uses interface"| node_dataset_base
node_image_data -->|"uses split indices"| node_splits
node_text_data -->|"uses interface"| node_dataset_base
node_text_data -->|"uses split indices"| node_splits
node_audio_task -->|"implements"| node_task_base
node_audio_task -->|"builds model"| node_audio_model
node_audio_task -->|"computes metrics"| node_audio_metrics
node_image_task -->|"implements"| node_task_base
node_image_task -->|"builds model"| node_image_model
node_text_task -->|"implements"| node_task_base
node_text_task -->|"builds model"| node_text_model
node_text_task -->|"batches text"| node_tokenizer
node_audio_model -->|"implements transceiver"| node_task_base
node_text_model -->|"implements transceiver"| node_task_base
node_text_model -->|"uses token IDs"| node_tokenizer
node_awgn -->|"implements"| node_channel_base
node_rayleigh -->|"implements"| node_channel_base
node_train -->|"sets seed"| node_seeding
node_train -->|"names run"| node_naming
node_train -->|"starts and logs run"| node_wandb
node_train -->|"plots SNR curves"| node_plots
node_train -->|"writes evaluation results"| node_results

click node_train "https://github.com/ani3h/semcom/blob/main/experiments/week4_train.py"
click node_config "https://github.com/ani3h/semcom/blob/main/configs/week4.yaml"
click node_dataset_base "https://github.com/ani3h/semcom/blob/main/src/semcom/data/base.py"
click node_splits "https://github.com/ani3h/semcom/blob/main/src/semcom/data/splits.py"
click node_audio_data "https://github.com/ani3h/semcom/blob/main/src/semcom/data/audio_edinburgh.py"
click node_image_data "https://github.com/ani3h/semcom/tree/main/src/semcom/data"
click node_text_data "https://github.com/ani3h/semcom/blob/main/src/semcom/data/text_europarl.py"
click node_task_base "https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/base.py"
click node_audio_task "https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/audio/task.py"
click node_audio_model "https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/audio/model.py"
click node_audio_metrics "https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/audio/metrics.py"
click node_image_task "https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/image/task.py"
click node_image_model "https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/image/model.py"
click node_text_task "https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/text/task.py"
click node_text_model "https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/text/model.py"
click node_tokenizer "https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/text/tokenizer.py"
click node_channel_base "https://github.com/ani3h/semcom/blob/main/src/semcom/channel/base.py"
click node_awgn "https://github.com/ani3h/semcom/blob/main/src/semcom/channel/awgn.py"
click node_rayleigh "https://github.com/ani3h/semcom/blob/main/src/semcom/channel/rayleigh.py"
click node_results "https://github.com/ani3h/semcom/blob/main/experiments/week4_train.py"
click node_naming "https://github.com/ani3h/semcom/blob/main/src/semcom/tracking/run_naming.py"
click node_seeding "https://github.com/ani3h/semcom/blob/main/src/semcom/tracking/seed.py"
click node_wandb "https://github.com/ani3h/semcom/blob/main/src/semcom/tracking/wandb_logger.py"
click node_plots "https://github.com/ani3h/semcom/blob/main/src/semcom/tracking/plots.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_dataset_base,node_splits,node_audio_data,node_image_data,node_text_data,node_engineer toneBlue
class node_task_base,node_audio_task,node_audio_model,node_image_task,node_image_model,node_text_task,node_text_model,node_tokenizer,node_channel_base,node_awgn,node_rayleigh toneAmber
class node_train,node_config,node_audio_metrics,node_results toneMint
class node_naming,node_seeding,node_wandb,node_plots toneRose
```

## Components

### Data loading

- [Dataset interface](https://github.com/ani3h/semcom/blob/main/src/semcom/data/base.py): `src/semcom/data/base.py`
- [Dataset splitting](https://github.com/ani3h/semcom/blob/main/src/semcom/data/splits.py): `src/semcom/data/splits.py`
- [Edinburgh audio](https://github.com/ani3h/semcom/blob/main/src/semcom/data/audio_edinburgh.py): `src/semcom/data/audio_edinburgh.py`
- [CIFAR-10 and MNIST](https://github.com/ani3h/semcom/tree/main/src/semcom/data): `src/semcom/data`
- [Europarl text](https://github.com/ani3h/semcom/blob/main/src/semcom/data/text_europarl.py): `src/semcom/data/text_europarl.py`

### Transceivers and channels

- [Task interface](https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/base.py): `src/semcom/encoders/base.py`
- [Audio task](https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/audio/task.py): `src/semcom/encoders/audio/task.py`
- [Audio transceiver](https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/audio/model.py): `src/semcom/encoders/audio/model.py`
- [Image tasks](https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/image/task.py): `src/semcom/encoders/image/task.py`
- [Image transceiver](https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/image/model.py): `src/semcom/encoders/image/model.py`
- [Text task](https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/text/task.py): `src/semcom/encoders/text/task.py`
- [Text transceiver](https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/text/model.py): `src/semcom/encoders/text/model.py`
- [Word tokenizer](https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/text/tokenizer.py): `src/semcom/encoders/text/tokenizer.py`
- [Channel interface](https://github.com/ani3h/semcom/blob/main/src/semcom/channel/base.py): `src/semcom/channel/base.py`
- [AWGN simulation](https://github.com/ani3h/semcom/blob/main/src/semcom/channel/awgn.py): `src/semcom/channel/awgn.py`
- [Rayleigh simulation](https://github.com/ani3h/semcom/blob/main/src/semcom/channel/rayleigh.py): `src/semcom/channel/rayleigh.py`

### Training and evaluation

- [Training driver](https://github.com/ani3h/semcom/blob/main/experiments/week4_train.py): `experiments/week4_train.py`
- [Experiment config](https://github.com/ani3h/semcom/blob/main/configs/week4.yaml): `configs/week4.yaml`
- [Audio metrics](https://github.com/ani3h/semcom/blob/main/src/semcom/encoders/audio/metrics.py): `src/semcom/encoders/audio/metrics.py`
- [Metrics and artifacts](https://github.com/ani3h/semcom/blob/main/experiments/week4_train.py): `experiments/week4_train.py`

### Experiment tracking

- [Run naming](https://github.com/ani3h/semcom/blob/main/src/semcom/tracking/run_naming.py): `src/semcom/tracking/run_naming.py`
- [Random seeding](https://github.com/ani3h/semcom/blob/main/src/semcom/tracking/seed.py): `src/semcom/tracking/seed.py`
- [W&B logging](https://github.com/ani3h/semcom/blob/main/src/semcom/tracking/wandb_logger.py): `src/semcom/tracking/wandb_logger.py`
- [SNR plots](https://github.com/ani3h/semcom/blob/main/src/semcom/tracking/plots.py): `src/semcom/tracking/plots.py`

### Other components

- **Experiment user**

## Connections

- Experiment user → Training driver: runs (evidence: `README.md`)
- Training driver → Experiment config: loads config (evidence: `experiments/week4_train.py`)
- Training driver → Task interface: runs task methods (evidence: `experiments/week4_train.py`)
- Training driver → Channel interface: instantiates channel (evidence: `experiments/week4_train.py`)
- Training driver → Dataset interface: instantiates datasets (evidence: `experiments/week4_train.py`)
- Edinburgh audio → Dataset interface: implements (evidence: `src/semcom/data/audio_edinburgh.py`)
- Edinburgh audio → Dataset splitting: gets split indices (evidence: `src/semcom/data/audio_edinburgh.py`)
- CIFAR-10 and MNIST → Dataset interface: uses interface (evidence: `src/semcom/data/image_cifar10.py`)
- CIFAR-10 and MNIST → Dataset splitting: uses split indices (evidence: `src/semcom/data/image_cifar10.py`)
- Europarl text → Dataset interface: uses interface (evidence: `src/semcom/data/text_europarl.py`)
- Europarl text → Dataset splitting: uses split indices (evidence: `src/semcom/data/text_europarl.py`)
- Audio task → Task interface: implements (evidence: `src/semcom/encoders/audio/task.py`)
- Audio task → Audio transceiver: builds model (evidence: `src/semcom/encoders/audio/task.py`)
- Audio task → Audio metrics: computes metrics (evidence: `src/semcom/encoders/audio/task.py`)
- Image tasks → Task interface: implements (evidence: `src/semcom/encoders/image/task.py`)
- Image tasks → Image transceiver: builds model (evidence: `src/semcom/encoders/image/task.py`)
- Text task → Task interface: implements (evidence: `src/semcom/encoders/text/task.py`)
- Text task → Text transceiver: builds model (evidence: `src/semcom/encoders/text/task.py`)
- Text task → Word tokenizer: batches text (evidence: `src/semcom/encoders/text/task.py`)
- Audio transceiver → Task interface: implements transceiver (evidence: `src/semcom/encoders/audio/model.py`)
- Text transceiver → Task interface: implements transceiver (evidence: `src/semcom/encoders/text/model.py`)
- Text transceiver → Word tokenizer: uses token IDs (evidence: `src/semcom/encoders/text/model.py`)
- AWGN simulation → Channel interface: implements (evidence: `src/semcom/channel/awgn.py`)
- Rayleigh simulation → Channel interface: implements (evidence: `src/semcom/channel/rayleigh.py`)
- Training driver → Random seeding: sets seed (evidence: `experiments/week4_train.py`)
- Training driver → Run naming: names run (evidence: `experiments/week4_train.py`)
- Training driver → W&B logging: starts and logs run (evidence: `experiments/week4_train.py`)
- Training driver → SNR plots: plots SNR curves (evidence: `experiments/week4_train.py`)
- Training driver → Metrics and artifacts: writes evaluation results (evidence: `experiments/week4_train.py`)
