# hanmoco/cefr-mcq-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/hanmoco/cefr-mcq-simulator
- Repository: https://github.com/hanmoco/cefr-mcq-simulator

## Overview

CEFR MCQ Learner Simulator converts Cambridge reading-question data into examples with learner response distributions, then uses those examples for zero-shot evaluation or fine-tuning a language model. Its principal workflow is raw data → preprocessing → optional synthetic augmentation → training/evaluation with passage-level splits → saved outputs. The README documents these workflows; excerpts show the data conversion and synthetic-generation logic and parts of both model runners, but not their complete orchestration.

Main entry points: [`src/train.py`](https://github.com/hanmoco/cefr-mcq-simulator/blob/main/src/train.py) (Fine-tuning), [`src/zeroshot.py`](https://github.com/hanmoco/cefr-mcq-simulator/blob/main/src/zeroshot.py) (Zero-shot evaluation), [`data`](https://github.com/hanmoco/cefr-mcq-simulator/tree/main/data) (Processed examples), [`splits/split_ft.json`](https://github.com/hanmoco/cefr-mcq-simulator/blob/main/splits/split_ft.json) (Passage splits)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data_prep["Data preparation"]
  node_convert_data["Dataset conversion"]
  node_synthetic_data_gen["Synthetic augmentation"]
end

subgraph group_model_runs["Model runs"]
  node_zeroshot["Zero-shot evaluation<br/>[zeroshot.py]"]
  node_training["Fine-tuning<br/>[train.py]"]
end

subgraph group_artifacts["Inputs and outputs"]
  node_processed_data["Processed examples"]
  node_synthetic_data["Synthetic examples"]
  node_splits["Passage splits<br/>[split_ft.json]"]
  node_run_outputs["Run outputs"]
end

node_researcher(("Researcher"))
node_cambridge_data["Cambridge dataset"]
node_language_model["Pretrained language model"]

node_researcher -->|"obtains data"| node_cambridge_data
node_cambridge_data -->|"provides JSONL"| node_convert_data
node_convert_data -->|"writes examples"| node_processed_data
node_processed_data -->|"provides input"| node_synthetic_data_gen
node_synthetic_data_gen -->|"writes augmented data"| node_synthetic_data
node_researcher -->|"runs evaluation"| node_zeroshot
node_researcher -->|"runs fine-tuning"| node_training
node_processed_data -->|"supplies examples"| node_zeroshot
node_processed_data -->|"supplies examples"| node_training
node_synthetic_data -->|"supplies augmented examples"| node_training
node_splits -->|"selects passages"| node_zeroshot
node_splits -->|"selects passages"| node_training
node_zeroshot -->|"loads model"| node_language_model
node_training -->|"loads and fine-tunes"| node_language_model
node_zeroshot -->|"writes results"| node_run_outputs
node_training -->|"writes results"| node_run_outputs

click node_convert_data "https://github.com/hanmoco/cefr-mcq-simulator/blob/main/src/generate_dataset.py"
click node_processed_data "https://github.com/hanmoco/cefr-mcq-simulator/tree/main/data"
click node_synthetic_data_gen "https://github.com/hanmoco/cefr-mcq-simulator/blob/main/src/generate_synthetic_dataset.py"
click node_synthetic_data "https://github.com/hanmoco/cefr-mcq-simulator/tree/main/data"
click node_splits "https://github.com/hanmoco/cefr-mcq-simulator/blob/main/splits/split_ft.json"
click node_zeroshot "https://github.com/hanmoco/cefr-mcq-simulator/blob/main/src/zeroshot.py"
click node_training "https://github.com/hanmoco/cefr-mcq-simulator/blob/main/src/train.py"
click node_run_outputs "https://github.com/hanmoco/cefr-mcq-simulator/tree/main/data"

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_convert_data,node_synthetic_data_gen toneBlue
class node_zeroshot,node_training toneAmber
class node_processed_data,node_synthetic_data,node_splits,node_run_outputs toneMint
class node_researcher,node_cambridge_data,node_language_model toneIndigo
```

## Components

### Data preparation

- [Dataset conversion](https://github.com/hanmoco/cefr-mcq-simulator/blob/main/src/generate_dataset.py): `src/generate_dataset.py`
- [Synthetic augmentation](https://github.com/hanmoco/cefr-mcq-simulator/blob/main/src/generate_synthetic_dataset.py): `src/generate_synthetic_dataset.py`

### Model runs

- [Zero-shot evaluation](https://github.com/hanmoco/cefr-mcq-simulator/blob/main/src/zeroshot.py): `src/zeroshot.py`
- [Fine-tuning](https://github.com/hanmoco/cefr-mcq-simulator/blob/main/src/train.py): `src/train.py`

### Inputs and outputs

- [Processed examples](https://github.com/hanmoco/cefr-mcq-simulator/tree/main/data): `data`
- [Synthetic examples](https://github.com/hanmoco/cefr-mcq-simulator/tree/main/data): `data`
- [Passage splits](https://github.com/hanmoco/cefr-mcq-simulator/blob/main/splits/split_ft.json): `splits/split_ft.json`
- [Run outputs](https://github.com/hanmoco/cefr-mcq-simulator/tree/main/data): `data`

### Other components

- **Researcher**
- **Cambridge dataset**
- **Pretrained language model**

## Connections

- Researcher → Cambridge dataset: obtains data (evidence: `README.md`)
- Cambridge dataset → Dataset conversion: provides JSONL (evidence: `README.md`)
- Dataset conversion → Processed examples: writes examples (evidence: `src/generate_dataset.py`)
- Processed examples → Synthetic augmentation: provides input (evidence: `README.md`)
- Synthetic augmentation → Synthetic examples: writes augmented data (evidence: `src/generate_synthetic_dataset.py`)
- Researcher → Zero-shot evaluation: runs evaluation (evidence: `README.md`)
- Researcher → Fine-tuning: runs fine-tuning (evidence: `README.md`)
- Processed examples → Zero-shot evaluation: supplies examples (evidence: `README.md`)
- Processed examples → Fine-tuning: supplies examples (evidence: `README.md`)
- Synthetic examples → Fine-tuning: supplies augmented examples (evidence: `README.md`)
- Passage splits → Zero-shot evaluation: selects passages (evidence: `README.md`)
- Passage splits → Fine-tuning: selects passages (evidence: `README.md`)
- Zero-shot evaluation → Pretrained language model: loads model (evidence: `src/zeroshot.py`)
- Fine-tuning → Pretrained language model: loads and fine-tunes (evidence: `src/train.py`)
- Zero-shot evaluation → Run outputs: writes results (evidence: `README.md`)
- Fine-tuning → Run outputs: writes results (evidence: `README.md`)
