# kartikeybishnoi/grow21-ml architecture

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

- Interactive diagram: https://gitdiagram.com/kartikeybishnoi/grow21-ml
- Repository: https://github.com/kartikeybishnoi/grow21-ml

## Overview

Grow21 is a course-project ML research layer for an existing adaptive learning app, not a replacement app or service. Its central experiment workflow generates learner events through a read-only bridge to the external simulator, builds causal features, and compares classical models; separate experiments investigate touch-slip trust weighting, Q-learning controllers, and cold-start clustering. The collection page supplies touch trials for the slip investigation. The README documents these capability branches, while the sampled sources establish only some internal calls; uncertain wiring is omitted.

Main entry points: [`src/grow21_ml/simulator_bridge.py`](https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/simulator_bridge.py) (Simulator bridge), [`run_hyperparameter_tuning.py`](https://github.com/kartikeybishnoi/grow21-ml/blob/main/run_hyperparameter_tuning.py) (Model comparison), [`run_q_learning.py`](https://github.com/kartikeybishnoi/grow21-ml/blob/main/run_q_learning.py) (Controller comparison), [`src/grow21_ml/slip_and_trust.py`](https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/slip_and_trust.py) (Slip and trust)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation data"]
  node_simbridge["Simulator bridge"]
end

subgraph group_prediction["Skill prediction"]
  node_features["Causal features"]
  node_bkt["BKT baseline"]
  node_model_zoo["Classical models"]
end

subgraph group_reliability["Motor reliability"]
  node_touch_page["Touch collection<br/>[index.html]"]
  node_touch_data["Touch trials"]
  node_slip_trust["Slip and trust<br/>[slip_and_trust.py]"]
end

subgraph group_adaptation["Adaptive policies"]
  node_qlearning["Q-learning"]
  node_coldstart["Cold-start clustering"]
end

subgraph group_evaluation["Experiments"]
  node_tuning["Model comparison"]
  node_controller_eval["Controller comparison<br/>[run_q_learning.py]"]
  node_results["Experiment results"]
end

node_researcher(("Researcher"))
node_external_sim["Grow21 simulator"]

node_researcher -->|"runs experiments"| node_simbridge
node_simbridge -->|"imports simulator"| node_external_sim
node_tuning -->|"generates splits"| node_simbridge
node_tuning -->|"builds features"| node_features
node_features -.->|"provides features"| node_model_zoo
node_researcher -->|"collects trials"| node_touch_page
node_touch_page -->|"downloads JSON"| node_touch_data
node_touch_data -->|"loads trials"| node_slip_trust
node_simbridge -.->|"supplies simulated events"| node_slip_trust
node_slip_trust -->|"uses simulator helpers"| node_qlearning
node_coldstart -.->|"uses simulator helpers"| node_qlearning
node_coldstart -.->|"uses simulator bridge"| node_simbridge
node_researcher -->|"runs comparison"| node_tuning
node_researcher -->|"runs comparison"| node_controller_eval
node_controller_eval -->|"trains and evaluates"| node_qlearning
node_tuning -->|"writes metrics"| node_results
node_controller_eval -->|"writes metrics"| node_results

click node_simbridge "https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/simulator_bridge.py"
click node_features "https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/feature_engineering.py"
click node_bkt "https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/bayesian_knowledge_tracing.py"
click node_model_zoo "https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/classification_models.py"
click node_touch_page "https://github.com/kartikeybishnoi/grow21-ml/blob/main/collect/index.html"
click node_slip_trust "https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/slip_and_trust.py"
click node_qlearning "https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/q_learning_controller.py"
click node_coldstart "https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/clustering_coldstart.py"
click node_tuning "https://github.com/kartikeybishnoi/grow21-ml/blob/main/run_hyperparameter_tuning.py"
click node_controller_eval "https://github.com/kartikeybishnoi/grow21-ml/blob/main/run_q_learning.py"
click node_results "https://github.com/kartikeybishnoi/grow21-ml/tree/main/results"

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_simbridge toneBlue
class node_features,node_bkt,node_model_zoo toneAmber
class node_touch_page,node_touch_data,node_slip_trust toneMint
class node_qlearning,node_coldstart toneRose
class node_tuning,node_controller_eval,node_results,node_researcher,node_external_sim toneIndigo
```

## Components

### Simulation data

- [Simulator bridge](https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/simulator_bridge.py): `src/grow21_ml/simulator_bridge.py`

### Skill prediction

- [Causal features](https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/feature_engineering.py): `src/grow21_ml/feature_engineering.py`
- [BKT baseline](https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/bayesian_knowledge_tracing.py): `src/grow21_ml/bayesian_knowledge_tracing.py`
- [Classical models](https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/classification_models.py): `src/grow21_ml/classification_models.py`

### Motor reliability

- [Touch collection](https://github.com/kartikeybishnoi/grow21-ml/blob/main/collect/index.html): `collect/index.html`
- **Touch trials**
- [Slip and trust](https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/slip_and_trust.py): `src/grow21_ml/slip_and_trust.py`

### Adaptive policies

- [Q-learning](https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/q_learning_controller.py): `src/grow21_ml/q_learning_controller.py`
- [Cold-start clustering](https://github.com/kartikeybishnoi/grow21-ml/blob/main/src/grow21_ml/clustering_coldstart.py): `src/grow21_ml/clustering_coldstart.py`

### Experiments

- [Model comparison](https://github.com/kartikeybishnoi/grow21-ml/blob/main/run_hyperparameter_tuning.py): `run_hyperparameter_tuning.py`
- [Controller comparison](https://github.com/kartikeybishnoi/grow21-ml/blob/main/run_q_learning.py): `run_q_learning.py`
- [Experiment results](https://github.com/kartikeybishnoi/grow21-ml/tree/main/results): `results`

### Other components

- **Researcher**
- **Grow21 simulator**

## Connections

- Researcher → Simulator bridge: runs experiments (evidence: `README.md`)
- Simulator bridge → Grow21 simulator: imports simulator (evidence: `src/grow21_ml/simulator_bridge.py`)
- Model comparison → Simulator bridge: generates splits (evidence: `run_hyperparameter_tuning.py`)
- Model comparison → Causal features: builds features (evidence: `run_hyperparameter_tuning.py`)
- Causal features → Classical models: provides features
- Researcher → Touch collection: collects trials (evidence: `README.md`)
- Touch collection → Touch trials: downloads JSON (evidence: `README.md`)
- Touch trials → Slip and trust: loads trials (evidence: `README.md`)
- Simulator bridge → Slip and trust: supplies simulated events (evidence: `src/grow21_ml/slip_and_trust.py`)
- Slip and trust → Q-learning: uses simulator helpers (evidence: `src/grow21_ml/slip_and_trust.py`)
- Cold-start clustering → Q-learning: uses simulator helpers (evidence: `src/grow21_ml/clustering_coldstart.py`)
- Cold-start clustering → Simulator bridge: uses simulator bridge (evidence: `src/grow21_ml/clustering_coldstart.py`)
- Researcher → Model comparison: runs comparison (evidence: `README.md`)
- Researcher → Controller comparison: runs comparison (evidence: `README.md`)
- Controller comparison → Q-learning: trains and evaluates (evidence: `run_q_learning.py`)
- Model comparison → Experiment results: writes metrics (evidence: `run_hyperparameter_tuning.py`)
- Controller comparison → Experiment results: writes metrics (evidence: `run_q_learning.py`)
