# tingofurro/keep_it_simple architecture

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

## Overview

Keep It Simple is a neural text-simplification system: users provide a paragraph and receive candidate rewrites with insertions and deletions highlighted. Its training workflow samples rewrites, scores them for coverage, simplicity, fluency, and guardrail violations, then updates the generator with reinforcement learning. The repository also includes a human-evaluation study interface and its study data. Connections reflect the README and shown source-index references; unsampled implementation details and interface wiring are not assumed.

Main entry points: [`train_keep_it_simple.py`](https://github.com/tingofurro/keep_it_simple/blob/main/train_keep_it_simple.py) (Training loop), [`model_generator.py`](https://github.com/tingofurro/keep_it_simple/blob/main/model_generator.py) (Text generator), [`run_keep_it_simple.py`](https://github.com/tingofurro/keep_it_simple/blob/main/run_keep_it_simple.py) (Run interface), [`model_salience.py`](https://github.com/tingofurro/keep_it_simple/blob/main/model_salience.py) (Coverage scorer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inference["Simplification"]
  node_run["Run interface"]
  node_generator["Text generator<br/>[model_generator.py]"]
  node_edits["Edit rendering<br/>[utils_edits.py]"]
end

subgraph group_rewards["Reward Scoring"]
  node_coverage["Coverage scorer<br/>[model_salience.py]"]
  node_masking["Text masking<br/>[utils_masking.py]"]
  node_fluency["Fluency scorer<br/>[model_fluency.py]"]
  node_simplicity["Simplicity scorer"]
  node_guardrails["Output guardrails"]
  node_scoring["Score aggregation<br/>[utils_scoring.py]"]
end

subgraph group_training["Model Training"]
  node_trainer["Training loop"]
  node_optim["Optimizer utilities<br/>[utils_optim.py]"]
  node_rl["Reinforcement utilities<br/>[utils_rl.py]"]
  node_misc["Runtime utilities<br/>[utils_misc.py]"]
  node_timing["Training timing<br/>[utils_timing.py]"]
end

subgraph group_evaluation["Human Evaluation"]
  node_study_ui["Study interface<br/>[simpli_study.html]"]
  node_study_data["Study materials"]
end

node_user(("Text user"))
node_study_user(("Study participant"))

node_user -->|"submits text"| node_run
node_run -->|"generates candidates"| node_generator
node_run -->|"renders changes"| node_edits
node_trainer -->|"samples rewrites"| node_generator
node_trainer -->|"scores candidates"| node_scoring
node_trainer -->|"configures reward"| node_coverage
node_trainer -->|"configures reward"| node_fluency
node_trainer -->|"configures reward"| node_simplicity
node_trainer -->|"configures penalties"| node_guardrails
node_trainer -->|"uses updates"| node_rl
node_trainer -->|"uses optimization"| node_optim
node_trainer -->|"records timing"| node_timing
node_trainer -->|"uses utilities"| node_misc
node_generator -->|"applies constraints"| node_guardrails
node_generator -->|"uses masking"| node_masking
node_generator -->|"uses scoring"| node_scoring
node_generator -->|"uses batching"| node_misc
node_coverage -->|"masks source"| node_masking
node_fluency -->|"builds optimizer"| node_optim
node_study_user -.->|"takes evaluation"| node_study_ui
node_study_ui -->|"uses materials"| node_study_data

click node_run "https://github.com/tingofurro/keep_it_simple/blob/main/run_keep_it_simple.py"
click node_generator "https://github.com/tingofurro/keep_it_simple/blob/main/model_generator.py"
click node_edits "https://github.com/tingofurro/keep_it_simple/blob/main/utils_edits.py"
click node_trainer "https://github.com/tingofurro/keep_it_simple/blob/main/train_keep_it_simple.py"
click node_coverage "https://github.com/tingofurro/keep_it_simple/blob/main/model_salience.py"
click node_masking "https://github.com/tingofurro/keep_it_simple/blob/main/utils_masking.py"
click node_fluency "https://github.com/tingofurro/keep_it_simple/blob/main/model_fluency.py"
click node_simplicity "https://github.com/tingofurro/keep_it_simple/blob/main/model_simplicity.py"
click node_guardrails "https://github.com/tingofurro/keep_it_simple/blob/main/model_guardrails.py"
click node_scoring "https://github.com/tingofurro/keep_it_simple/blob/main/utils_scoring.py"
click node_optim "https://github.com/tingofurro/keep_it_simple/blob/main/utils_optim.py"
click node_rl "https://github.com/tingofurro/keep_it_simple/blob/main/utils_rl.py"
click node_misc "https://github.com/tingofurro/keep_it_simple/blob/main/utils_misc.py"
click node_timing "https://github.com/tingofurro/keep_it_simple/blob/main/utils_timing.py"
click node_study_ui "https://github.com/tingofurro/keep_it_simple/blob/main/study_interface/simpli_study.html"
click node_study_data "https://github.com/tingofurro/keep_it_simple/blob/main/study_interface/simplification_user_study.json"

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_run,node_generator,node_edits,node_user toneBlue
class node_coverage,node_masking,node_fluency,node_simplicity,node_guardrails,node_scoring toneAmber
class node_trainer,node_optim,node_rl,node_misc,node_timing toneMint
class node_study_ui,node_study_data toneRose
class node_study_user toneIndigo
```

## Components

### Simplification

- [Run interface](https://github.com/tingofurro/keep_it_simple/blob/main/run_keep_it_simple.py): `run_keep_it_simple.py`
- [Text generator](https://github.com/tingofurro/keep_it_simple/blob/main/model_generator.py): `model_generator.py`
- [Edit rendering](https://github.com/tingofurro/keep_it_simple/blob/main/utils_edits.py): `utils_edits.py`

### Reward Scoring

- [Coverage scorer](https://github.com/tingofurro/keep_it_simple/blob/main/model_salience.py): `model_salience.py`
- [Text masking](https://github.com/tingofurro/keep_it_simple/blob/main/utils_masking.py): `utils_masking.py`
- [Fluency scorer](https://github.com/tingofurro/keep_it_simple/blob/main/model_fluency.py): `model_fluency.py`
- [Simplicity scorer](https://github.com/tingofurro/keep_it_simple/blob/main/model_simplicity.py): `model_simplicity.py`
- [Output guardrails](https://github.com/tingofurro/keep_it_simple/blob/main/model_guardrails.py): `model_guardrails.py`
- [Score aggregation](https://github.com/tingofurro/keep_it_simple/blob/main/utils_scoring.py): `utils_scoring.py`

### Model Training

- [Training loop](https://github.com/tingofurro/keep_it_simple/blob/main/train_keep_it_simple.py): `train_keep_it_simple.py`
- [Optimizer utilities](https://github.com/tingofurro/keep_it_simple/blob/main/utils_optim.py): `utils_optim.py`
- [Reinforcement utilities](https://github.com/tingofurro/keep_it_simple/blob/main/utils_rl.py): `utils_rl.py`
- [Runtime utilities](https://github.com/tingofurro/keep_it_simple/blob/main/utils_misc.py): `utils_misc.py`
- [Training timing](https://github.com/tingofurro/keep_it_simple/blob/main/utils_timing.py): `utils_timing.py`

### Human Evaluation

- [Study interface](https://github.com/tingofurro/keep_it_simple/blob/main/study_interface/simpli_study.html): `study_interface/simpli_study.html`
- [Study materials](https://github.com/tingofurro/keep_it_simple/blob/main/study_interface/simplification_user_study.json): `study_interface/simplification_user_study.json`

### Other components

- **Text user**
- **Study participant**

## Connections

- Text user → Run interface: submits text (evidence: `README.md`)
- Run interface → Text generator: generates candidates (evidence: `run_keep_it_simple.py`)
- Run interface → Edit rendering: renders changes (evidence: `run_keep_it_simple.py`)
- Training loop → Text generator: samples rewrites (evidence: `train_keep_it_simple.py`)
- Training loop → Score aggregation: scores candidates (evidence: `train_keep_it_simple.py`)
- Training loop → Coverage scorer: configures reward (evidence: `train_keep_it_simple.py`)
- Training loop → Fluency scorer: configures reward (evidence: `train_keep_it_simple.py`)
- Training loop → Simplicity scorer: configures reward (evidence: `train_keep_it_simple.py`)
- Training loop → Output guardrails: configures penalties (evidence: `train_keep_it_simple.py`)
- Training loop → Reinforcement utilities: uses updates (evidence: `train_keep_it_simple.py`)
- Training loop → Optimizer utilities: uses optimization (evidence: `train_keep_it_simple.py`)
- Training loop → Training timing: records timing (evidence: `train_keep_it_simple.py`)
- Training loop → Runtime utilities: uses utilities (evidence: `train_keep_it_simple.py`)
- Text generator → Output guardrails: applies constraints (evidence: `model_generator.py`)
- Text generator → Text masking: uses masking (evidence: `model_generator.py`)
- Text generator → Score aggregation: uses scoring (evidence: `model_generator.py`)
- Text generator → Runtime utilities: uses batching (evidence: `model_generator.py`)
- Coverage scorer → Text masking: masks source (evidence: `model_salience.py`)
- Fluency scorer → Optimizer utilities: builds optimizer (evidence: `model_fluency.py`)
- Study participant → Study interface: takes evaluation (evidence: `README.md`)
- Study interface → Study materials: uses materials (evidence: `README.md`)
