# iehok/dualcse architecture

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

- Interactive diagram: https://gitdiagram.com/iehok/dualcse
- Repository: https://github.com/iehok/dualcse

## Overview

1. **What this repo is**
   DualCSE is a research codebase for learning and evaluating dual semantic representations: one geared toward explicit meaning and one toward implicit meaning. The repository is organized around a full experiment pipeline: dataset ingestion, preprocessing, model training, offline evaluation, and external LLM baselines.

2. **Primary execution boundary**
   There are two main experiment paths:
   - **Local DualCSE training/evaluation** under `src/`
   - **LLM baseline + scoring** under `src/llm_*` and `src/test_accuracy_llm.py`
   
   This is an important architectural boundary because the first path trains a model in-repo, while the second depends on external API providers.

3. **Data sources and external datasets**
   The project consumes two external datasets:
   - **INLI** cloned into `datasets/inli`
   - **ImpScore/Wang’s dataset** downloaded as `datasets/impscore/all_data.csv`
   
   These are not generated by the repo; the repo expects them to be placed in fixed locations and then standardized before training or evaluation.

4. **Preprocessing subsystem**
   `src/prepare_data.py` is the data normalization step. Its job is to convert the raw dataset formats into a common structure that the rest of the code can use. This preprocessing step is a hard dependency for training and testing, so it sits between raw dataset acquisition and all downstream experiments.

5. **Dataset and loading layer**
   `src/datasets.py` and `src/data_loader.py` form the data-access boundary. Together they likely define task-specific dataset objects and batching/iteration logic for training and evaluation. `src/config.py` probably centralizes dataset/model/run settings so the loaders and trainers can stay aligned.

6. **Modeling layer**
   `src/models.py` contains the core DualCSE architecture and related model components. Based on the paper title and repo structure, this is where the explicit/implicit embedding objectives and contrastive learning machinery live. This module is the central computational dependency for training and most in-repo evaluations.

7. **Training pipeline**
   `src/train.py` is the main training entry point, invoked by `scripts/train.sh`. The training flow appears to be: load standardized data → build dataset/dataloader → instantiate model → optimize embeddings/contrastive objectives → save a run identified by `run_name`. `src/utils.py` likely supports logging, checkpointing, metric computation, and reproducibility.

8. **Evaluation for the learned model**
   There are dedicated evaluation scripts for the trained DualCSE model:
   - `src/test_rte.py` for RTE-style evaluation
   - `src/test_implicitness_scoring.py` for implicitness scoring
   - `src/test_implicitness_scoring_length.py` for length-related analysis
   - `src/test_implicitness_scoring_pretrained.py` for comparing against pretrained baselines
   - `src/test_rte_simcse.py` for a SimCSE comparison point
   
   These form the post-training validation layer and are separated by task, baseline, or analysis variant.

9. **LLM baseline subsystem**
   `src/llm_baseline.py`, `src/llm_data_prep.py`, `src/llms_api.py`, and `src/test_accuracy_llm.py` implement the external-LLM experiment path. The flow is: prepare prompts/data → call a selected model provider via API → store responses in spreadsheet-like output → compute accuracy from those results. This subsystem is isolated from the trained DualCSE model and serves as a comparison baseline.

10. **Prompting and provider integration**
   `prompt/prompt.txt` stores the prompt template used for LLM experiments. `src/llms_api.py` is the integration boundary to multiple providers, with API keys supplied via `.env` as documented in the README. Supported providers include OpenAI, DeepSeek, Gemini, Claude, and Mistral, which makes the repo multi-vendor at the experiment layer.

11. **Analysis and reporting**
   `src/analyze_data.py` and `src/analyze_retrieval_results.py` are downstream analysis tools. They likely summarize dataset properties, retrieval behavior, or experiment outputs rather than driving core training. These scripts are useful for post-hoc interpretation and paper figures/results, but they are not part of the main training graph.

12. **Operational tooling**
   `scripts/train.sh` is the main shell wrapper for reproducible training runs. `requirements.txt` defines the Python environment, while `README.md` provides the required filesystem layout and setup steps. The `figures/` directory stores paper assets rather than runtime artifacts.

13. **How the pieces fit together**
   The end-to-end flow is:
   raw datasets in `datasets/` → `prepare_data` standardization → loaders/datasets → DualCSE model training → task-specific evaluation scripts.
   
   In parallel, the LLM path is:
   prompt template + prepared data → API calls → saved predictions/results → accuracy/evaluation scripts.

14. **Key architecture takeaway**
   The repo is best viewed as a research workflow with three layers: **data preparation**, **modeling/evaluation**, and **LLM baseline comparison**. The strongest boundary is between the in-repo learned embedding model and the external API-driven baseline system; both consume the same task framing but produce results through very different runtimes.

Main entry points: [`src/train.py`](https://github.com/iehok/dualcse/blob/main/src/train.py) (Train), [`src/prepare_data.py`](https://github.com/iehok/dualcse/blob/main/src/prepare_data.py) (Prepare data), [`src/llm_baseline.py`](https://github.com/iehok/dualcse/blob/main/src/llm_baseline.py) (Baseline run), [`src/config.py`](https://github.com/iehok/dualcse/blob/main/src/config.py) (Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ops["Operational"]
  node_readme["README<br/>docs<br/>[README.md]"]
  node_requirements["Dependencies<br/>env<br/>[requirements.txt]"]
  node_train_sh["Train script<br/>shell<br/>[train.sh]"]
end

subgraph group_data["Data Pipeline"]
  node_raw_inli[("INLI data<br/>external dataset")]
  node_raw_impscore[("ImpScore data<br/>external dataset")]
  node_prepare_data["Prepare data<br/>preprocess<br/>[prepare_data.py]"]
  node_datasets_mod["Datasets<br/>dataset layer<br/>[datasets.py]"]
  node_data_loader["Loader<br/>batching<br/>[data_loader.py]"]
  node_config["Config<br/>settings<br/>[config.py]"]
end

subgraph group_model["DualCSE"]
  node_models{{"DualCSE<br/>model<br/>[models.py]"}}
  node_train["Train<br/>entrypoint<br/>[train.py]"]
  node_test_rte["RTE eval<br/>evaluation<br/>[test_rte.py]"]
  node_test_imp["Implicitness<br/>evaluation"]
  node_test_imp_len["Length analysis<br/>analysis eval"]
  node_test_imp_pre["Pretrained compare<br/>baseline eval"]
  node_test_rte_simcse["SimCSE eval<br/>baseline eval<br/>[test_rte_simcse.py]"]
  node_utils["Utils<br/>support<br/>[utils.py]"]
end

subgraph group_llm["LLM Baseline"]
  node_prompt_template["Prompt<br/>template<br/>[prompt.txt]"]
  node_llm_data_prep["LLM prep<br/>prompt prep<br/>[llm_data_prep.py]"]
  node_llms_api["LLM API<br/>provider bridge<br/>[llms_api.py]"]
  node_llm_baseline["Baseline run<br/>experiment<br/>[llm_baseline.py]"]
  node_test_accuracy_llm["LLM accuracy<br/>evaluation"]
end

subgraph group_analysis["Analysis"]
  node_analyze_data["Data analysis<br/>[analyze_data.py]"]
  node_analyze_retrieval["Retrieval analysis"]
end

node_readme -->|"describes"| node_prepare_data
node_readme -->|"documents"| node_train_sh
node_requirements -->|"supports"| node_train
node_raw_inli -->|"input"| node_prepare_data
node_raw_impscore -->|"input"| node_prepare_data
node_prepare_data -->|"feeds"| node_datasets_mod
node_datasets_mod -->|"used by"| node_data_loader
node_config -->|"configures"| node_datasets_mod
node_config -->|"configures"| node_train
node_config -->|"configures"| node_llm_baseline
node_data_loader -->|"supplies batches"| node_train
node_models -->|"core dependency"| node_train
node_utils -->|"supports"| node_train
node_train -->|"evaluated by"| node_test_rte
node_train -->|"evaluated by"| node_test_imp
node_train -->|"analyzed by"| node_test_imp_len
node_train -->|"compared by"| node_test_imp_pre
node_train -->|"compared by"| node_test_rte_simcse
node_prompt_template -->|"drives"| node_llm_data_prep
node_llm_data_prep -->|"calls"| node_llms_api
node_llms_api -->|"provides responses"| node_llm_baseline
node_llm_baseline -->|"scored by"| node_test_accuracy_llm
node_prepare_data -->|"inspected by"| node_analyze_data
node_llm_baseline -->|"inspected by"| node_analyze_retrieval

click node_readme "https://github.com/iehok/dualcse/blob/main/README.md"
click node_requirements "https://github.com/iehok/dualcse/blob/main/requirements.txt"
click node_train_sh "https://github.com/iehok/dualcse/blob/main/scripts/train.sh"
click node_prompt_template "https://github.com/iehok/dualcse/blob/main/prompt/prompt.txt"
click node_prepare_data "https://github.com/iehok/dualcse/blob/main/src/prepare_data.py"
click node_datasets_mod "https://github.com/iehok/dualcse/blob/main/src/datasets.py"
click node_data_loader "https://github.com/iehok/dualcse/blob/main/src/data_loader.py"
click node_config "https://github.com/iehok/dualcse/blob/main/src/config.py"
click node_models "https://github.com/iehok/dualcse/blob/main/src/models.py"
click node_train "https://github.com/iehok/dualcse/blob/main/src/train.py"
click node_test_rte "https://github.com/iehok/dualcse/blob/main/src/test_rte.py"
click node_test_imp "https://github.com/iehok/dualcse/blob/main/src/test_implicitness_scoring.py"
click node_test_imp_len "https://github.com/iehok/dualcse/blob/main/src/test_implicitness_scoring_length.py"
click node_test_imp_pre "https://github.com/iehok/dualcse/blob/main/src/test_implicitness_scoring_pretrained.py"
click node_test_rte_simcse "https://github.com/iehok/dualcse/blob/main/src/test_rte_simcse.py"
click node_utils "https://github.com/iehok/dualcse/blob/main/src/utils.py"
click node_llm_data_prep "https://github.com/iehok/dualcse/blob/main/src/llm_data_prep.py"
click node_llms_api "https://github.com/iehok/dualcse/blob/main/src/llms_api.py"
click node_llm_baseline "https://github.com/iehok/dualcse/blob/main/src/llm_baseline.py"
click node_test_accuracy_llm "https://github.com/iehok/dualcse/blob/main/src/test_accuracy_llm.py"
click node_analyze_data "https://github.com/iehok/dualcse/blob/main/src/analyze_data.py"
click node_analyze_retrieval "https://github.com/iehok/dualcse/blob/main/src/analyze_retrieval_results.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_readme,node_requirements,node_train_sh toneBlue
class node_raw_inli,node_raw_impscore,node_prepare_data,node_datasets_mod,node_data_loader,node_config toneAmber
class node_models,node_train,node_test_rte,node_test_imp,node_test_imp_len,node_test_imp_pre,node_test_rte_simcse,node_utils toneMint
class node_prompt_template,node_llm_data_prep,node_llms_api,node_llm_baseline,node_test_accuracy_llm toneRose
class node_analyze_data,node_analyze_retrieval toneIndigo
```

## Components

### Operational

Project setup, docs, and run wrappers.

- [README](https://github.com/iehok/dualcse/blob/main/README.md): docs · Setup, dataset layout, and experiment instructions. · `README.md`
- [Dependencies](https://github.com/iehok/dualcse/blob/main/requirements.txt): env · Python package requirements for the repo. · `requirements.txt`
- [Train script](https://github.com/iehok/dualcse/blob/main/scripts/train.sh): shell · Wrapper for reproducible training runs. · `scripts/train.sh`

### Data Pipeline

Raw datasets, standardization, and loading for experiments.

- **INLI data**: external dataset · External dataset expected under datasets/inli.
- **ImpScore data**: external dataset · External CSV expected at datasets/impscore/all_data.csv.
- [Prepare data](https://github.com/iehok/dualcse/blob/main/src/prepare_data.py): preprocess · Normalizes raw dataset formats into a shared structure. · `src/prepare_data.py`
- [Datasets](https://github.com/iehok/dualcse/blob/main/src/datasets.py): dataset layer · Task-specific dataset objects and examples. · `src/datasets.py`
- [Loader](https://github.com/iehok/dualcse/blob/main/src/data_loader.py): batching · Batching and iteration for training and evaluation. · `src/data_loader.py`
- [Config](https://github.com/iehok/dualcse/blob/main/src/config.py): settings · Central run, dataset, and model configuration. · `src/config.py`

### DualCSE

In-repo learned representation training and evaluation.

- [DualCSE](https://github.com/iehok/dualcse/blob/main/src/models.py): model · Core explicit/implicit representation model and objectives. · `src/models.py`
- [Train](https://github.com/iehok/dualcse/blob/main/src/train.py): entrypoint · Main training entry point for the learned model. · `src/train.py`
- [RTE eval](https://github.com/iehok/dualcse/blob/main/src/test_rte.py): evaluation · Task evaluation for the trained model. · `src/test_rte.py`
- [Implicitness](https://github.com/iehok/dualcse/blob/main/src/test_implicitness_scoring.py): evaluation · Implicitness scoring evaluation. · `src/test_implicitness_scoring.py`
- [Length analysis](https://github.com/iehok/dualcse/blob/main/src/test_implicitness_scoring_length.py): analysis eval · Implicitness scoring by length. · `src/test_implicitness_scoring_length.py`
- [Pretrained compare](https://github.com/iehok/dualcse/blob/main/src/test_implicitness_scoring_pretrained.py): baseline eval · Comparison against pretrained baselines. · `src/test_implicitness_scoring_pretrained.py`
- [SimCSE eval](https://github.com/iehok/dualcse/blob/main/src/test_rte_simcse.py): baseline eval · RTE comparison against SimCSE. · `src/test_rte_simcse.py`
- [Utils](https://github.com/iehok/dualcse/blob/main/src/utils.py): support · Shared support for logging, checkpoints, and metrics. · `src/utils.py`

### LLM Baseline

External-model comparison pipeline driven by prompts and APIs.

- [Prompt](https://github.com/iehok/dualcse/blob/main/prompt/prompt.txt): template · Prompt template used for LLM experiments. · `prompt/prompt.txt`
- [LLM prep](https://github.com/iehok/dualcse/blob/main/src/llm_data_prep.py): prompt prep · Prepares data and prompts for external model runs. · `src/llm_data_prep.py`
- [LLM API](https://github.com/iehok/dualcse/blob/main/src/llms_api.py): provider bridge · Integration boundary to external model providers. · `src/llms_api.py`
- [Baseline run](https://github.com/iehok/dualcse/blob/main/src/llm_baseline.py): experiment · Runs the external-LLM comparison pipeline. · `src/llm_baseline.py`
- [LLM accuracy](https://github.com/iehok/dualcse/blob/main/src/test_accuracy_llm.py): evaluation · Computes accuracy from saved LLM outputs. · `src/test_accuracy_llm.py`

### Analysis

Post-hoc inspection and result summaries.

- [Data analysis](https://github.com/iehok/dualcse/blob/main/src/analyze_data.py): analysis · Summarizes dataset properties and structure. · `src/analyze_data.py`
- [Retrieval analysis](https://github.com/iehok/dualcse/blob/main/src/analyze_retrieval_results.py): analysis · Summarizes retrieval results and experiment outputs. · `src/analyze_retrieval_results.py`

## Connections

- README → Prepare data: describes · Documents dataset layout and preprocessing steps.
- README → Train script: documents · Explains the training wrapper and run flow.
- Dependencies → Train: supports · Defines the runtime environment used by scripts.
- INLI data → Prepare data: input · Raw INLI dataset is standardized for downstream use.
- ImpScore data → Prepare data: input · Raw ImpScore CSV is standardized for downstream use.
- Prepare data → Datasets: feeds · Produces normalized examples consumed by dataset objects.
- Datasets → Loader: used by · Dataset objects are batched and iterated for experiments.
- Config → Datasets: configures · Controls dataset and run selection.
- Config → Train: configures · Provides training hyperparameters and run settings.
- Config → Baseline run: configures · Controls baseline run settings and provider choice.
- Loader → Train: supplies batches · Provides training and evaluation batches.
- DualCSE → Train: core dependency · Training instantiates and optimizes the DualCSE model.
- Utils → Train: supports · Handles common training utilities.
- Train → RTE eval: evaluated by · Trained model is validated on RTE-style tasks.
- Train → Implicitness: evaluated by · Trained model is validated on implicitness scoring.
- Train → Length analysis: analyzed by · Training outputs are analyzed by sentence length.
- Train → Pretrained compare: compared by · Trained model is compared against pretrained baselines.
- Train → SimCSE eval: compared by · Trained model is compared against SimCSE.
- Prompt → LLM prep: drives · Prompt template shapes the prepared LLM inputs.
- LLM prep → LLM API: calls · Prepared prompts are sent to provider APIs.
- LLM API → Baseline run: provides responses · External API completions are consumed by the baseline runner.
- Baseline run → LLM accuracy: scored by · Saved predictions are turned into accuracy metrics.
- Prepare data → Data analysis: inspected by · Prepared data can be summarized for analysis.
- Baseline run → Retrieval analysis: inspected by · Baseline outputs can be summarized post hoc.
