# samankhamesian/guide architecture

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

- Interactive diagram: https://gitdiagram.com/samankhamesian/guide
- Repository: https://github.com/samankhamesian/guide

## Overview

GUIDE is a research framework for learning and evaluating patient-specific behavioral recommendations for type 1 diabetes. Its central workflow prepares patient glucose and behavior data, uses a learned glucose predictor inside a simulation environment, and trains and evaluates reinforcement-learning policies that propose meal or insulin actions. The environment applies bolus safeguards and calculates rewards. The repository also includes multiple offline and online algorithms, action/reward ablations, adherence analysis, and GLIMMER rollout and counterfactual evaluations. Relationships are limited to README claims and source-index references or excerpts; unsampled implementation details are not assumed.

Main entry points: [`environment.py`](https://github.com/samankhamesian/guide/blob/main/environment.py) (RL environment), [`model/cql_bc/main.py`](https://github.com/samankhamesian/guide/blob/main/model/cql_bc/main.py) (CQL-BC runner), [`model/cql_bc/cql_agent.py`](https://github.com/samankhamesian/guide/blob/main/model/cql_bc/cql_agent.py) (CQL-BC agent), [`preprocess.py`](https://github.com/samankhamesian/guide/blob/main/preprocess.py) (Feature preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Patient data"]
  node_preprocess["Feature preparation<br/>[preprocess.py]"]
  node_predictor["Glucose predictor<br/>[predictor.py]"]
end

subgraph group_sim["Simulation"]
  node_simulator["Patient simulator<br/>[simulator.py]"]
  node_environment["RL environment<br/>[environment.py]"]
  node_safeguard["Bolus safeguard<br/>[bolus_safeguard.py]"]
  node_config["Domain configuration<br/>[config.py]"]
end

subgraph group_learning["RL algorithms"]
  node_buffer[("Replay buffer<br/>[replay_buffer.py]")]
  node_cql_main["CQL-BC runner<br/>[main.py]"]
  node_cql_agent["CQL-BC agent<br/>[cql_agent.py]"]
  node_td3_agent["TD3-BC networks<br/>[td3_bc_agent.py]"]
  node_ppo_main["PPO runner<br/>[main.py]"]
  node_ppo_agent["PPO agent<br/>[ppo_agent.py]"]
  node_ppo_buffer[("PPO buffer<br/>[buffer.py]")]
  node_sac_main["SAC runner<br/>[main.py]"]
  node_sac_online_main["Online SAC runner<br/>[main.py]"]
  node_sac_agent["SAC agent<br/>[sac_agent.py]"]
  node_random_main["Random-policy runner<br/>[main.py]"]
  node_random_agent["Random agent<br/>[random_agent.py]"]
  node_td3_main["TD3-BC runner<br/>[main.py]"]
end

subgraph group_research["Evaluation studies"]
  node_ablation["Action/reward ablations<br/>[ablation_common.py]"]
  node_adherence["Adherence analysis<br/>[main_adherence.py]"]
  node_rollout["GLIMMER rollout"]
  node_counterfactual["Counterfactual evaluation"]
  node_metrics["Metrics and behavior analysis<br/>[utils.py]"]
end

node_researcher(("Researcher"))
node_patient_data["Patient data"]

node_researcher -.->|"runs training"| node_cql_main
node_patient_data -.->|"provides records"| node_preprocess
node_preprocess -.->|"prepares inputs"| node_simulator
node_simulator -->|"uses data controller"| node_preprocess
node_simulator -->|"uses predictor"| node_predictor
node_environment -->|"delegates simulation"| node_simulator
node_environment -->|"checks proposed bolus"| node_safeguard
node_cql_main -->|"creates environment"| node_environment
node_cql_main -->|"creates and trains"| node_cql_agent
node_cql_main -->|"fills replay data"| node_buffer
node_cql_agent -->|"uses actor and critic"| node_td3_agent
node_cql_agent -->|"samples batches"| node_buffer
node_ppo_main -->|"creates environment"| node_environment
node_ppo_main -->|"trains and evaluates"| node_ppo_agent
node_ppo_main -->|"trains from buffer"| node_ppo_buffer
node_sac_main -.->|"creates environment"| node_environment
node_sac_main -.->|"trains and evaluates"| node_sac_agent
node_sac_online_main -->|"creates environment"| node_environment
node_sac_online_main -->|"creates agent"| node_sac_agent
node_sac_online_main -->|"stores transitions"| node_buffer
node_random_main -->|"creates environment"| node_environment
node_random_main -->|"uses policy"| node_random_agent
node_td3_main -->|"creates environment"| node_environment
node_td3_main -->|"creates agent"| node_td3_agent
node_td3_main -->|"fills replay data"| node_buffer
node_ablation -->|"runs restricted actions"| node_environment
node_ablation -->|"retains CQL-BC"| node_cql_agent
node_adherence -->|"evaluates policies"| node_environment
node_adherence -->|"uses CQL-BC"| node_cql_agent
node_rollout -->|"uses predictor"| node_predictor
node_rollout -->|"uses preprocessing"| node_preprocess
node_counterfactual -->|"uses predictor"| node_predictor
node_counterfactual -->|"uses preprocessing"| node_preprocess
node_cql_main -->|"reports evaluation"| node_metrics

click node_preprocess "https://github.com/samankhamesian/guide/blob/main/preprocess.py"
click node_predictor "https://github.com/samankhamesian/guide/blob/main/predictor.py"
click node_simulator "https://github.com/samankhamesian/guide/blob/main/simulator.py"
click node_environment "https://github.com/samankhamesian/guide/blob/main/environment.py"
click node_safeguard "https://github.com/samankhamesian/guide/blob/main/bolus_safeguard.py"
click node_config "https://github.com/samankhamesian/guide/blob/main/config.py"
click node_buffer "https://github.com/samankhamesian/guide/blob/main/replay_buffer.py"
click node_cql_main "https://github.com/samankhamesian/guide/blob/main/model/cql_bc/main.py"
click node_cql_agent "https://github.com/samankhamesian/guide/blob/main/model/cql_bc/cql_agent.py"
click node_td3_agent "https://github.com/samankhamesian/guide/blob/main/model/td3_bc/td3_bc_agent.py"
click node_ppo_main "https://github.com/samankhamesian/guide/blob/main/model/ppo/main.py"
click node_ppo_agent "https://github.com/samankhamesian/guide/blob/main/model/ppo/ppo_agent.py"
click node_ppo_buffer "https://github.com/samankhamesian/guide/blob/main/model/ppo/buffer.py"
click node_sac_main "https://github.com/samankhamesian/guide/blob/main/model/sac/main.py"
click node_sac_online_main "https://github.com/samankhamesian/guide/blob/main/model/sac_online/main.py"
click node_sac_agent "https://github.com/samankhamesian/guide/blob/main/model/sac/sac_agent.py"
click node_random_main "https://github.com/samankhamesian/guide/blob/main/model/random/main.py"
click node_random_agent "https://github.com/samankhamesian/guide/blob/main/model/random/random_agent.py"
click node_td3_main "https://github.com/samankhamesian/guide/blob/main/model/td3_bc/main.py"
click node_ablation "https://github.com/samankhamesian/guide/blob/main/ablation_study/ablation_common.py"
click node_adherence "https://github.com/samankhamesian/guide/blob/main/adherence_study/main_adherence.py"
click node_rollout "https://github.com/samankhamesian/guide/blob/main/glimmer_evaluation/glimmer_24h_rollout.py"
click node_counterfactual "https://github.com/samankhamesian/guide/blob/main/glimmer_evaluation/glimmer_counterfactual.py"
click node_metrics "https://github.com/samankhamesian/guide/blob/main/utils.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_preprocess,node_predictor toneBlue
class node_simulator,node_environment,node_safeguard,node_config toneAmber
class node_buffer,node_cql_main,node_cql_agent,node_td3_agent,node_ppo_main,node_ppo_agent,node_ppo_buffer,node_sac_main,node_sac_online_main,node_sac_agent,node_random_main,node_random_agent,node_td3_main toneMint
class node_ablation,node_adherence,node_rollout,node_counterfactual,node_metrics toneRose
class node_researcher,node_patient_data toneIndigo
```

## Components

### Patient data

- [Feature preparation](https://github.com/samankhamesian/guide/blob/main/preprocess.py): `preprocess.py`
- [Glucose predictor](https://github.com/samankhamesian/guide/blob/main/predictor.py): `predictor.py`

### Simulation

- [Patient simulator](https://github.com/samankhamesian/guide/blob/main/simulator.py): `simulator.py`
- [RL environment](https://github.com/samankhamesian/guide/blob/main/environment.py): `environment.py`
- [Bolus safeguard](https://github.com/samankhamesian/guide/blob/main/bolus_safeguard.py): `bolus_safeguard.py`
- [Domain configuration](https://github.com/samankhamesian/guide/blob/main/config.py): `config.py`

### RL algorithms

- [Replay buffer](https://github.com/samankhamesian/guide/blob/main/replay_buffer.py): `replay_buffer.py`
- [CQL-BC runner](https://github.com/samankhamesian/guide/blob/main/model/cql_bc/main.py): `model/cql_bc/main.py`
- [CQL-BC agent](https://github.com/samankhamesian/guide/blob/main/model/cql_bc/cql_agent.py): `model/cql_bc/cql_agent.py`
- [TD3-BC networks](https://github.com/samankhamesian/guide/blob/main/model/td3_bc/td3_bc_agent.py): `model/td3_bc/td3_bc_agent.py`
- [PPO runner](https://github.com/samankhamesian/guide/blob/main/model/ppo/main.py): `model/ppo/main.py`
- [PPO agent](https://github.com/samankhamesian/guide/blob/main/model/ppo/ppo_agent.py): `model/ppo/ppo_agent.py`
- [PPO buffer](https://github.com/samankhamesian/guide/blob/main/model/ppo/buffer.py): `model/ppo/buffer.py`
- [SAC runner](https://github.com/samankhamesian/guide/blob/main/model/sac/main.py): `model/sac/main.py`
- [Online SAC runner](https://github.com/samankhamesian/guide/blob/main/model/sac_online/main.py): `model/sac_online/main.py`
- [SAC agent](https://github.com/samankhamesian/guide/blob/main/model/sac/sac_agent.py): `model/sac/sac_agent.py`
- [Random-policy runner](https://github.com/samankhamesian/guide/blob/main/model/random/main.py): `model/random/main.py`
- [Random agent](https://github.com/samankhamesian/guide/blob/main/model/random/random_agent.py): `model/random/random_agent.py`
- [TD3-BC runner](https://github.com/samankhamesian/guide/blob/main/model/td3_bc/main.py): `model/td3_bc/main.py`

### Evaluation studies

- [Action/reward ablations](https://github.com/samankhamesian/guide/blob/main/ablation_study/ablation_common.py): `ablation_study/ablation_common.py`
- [Adherence analysis](https://github.com/samankhamesian/guide/blob/main/adherence_study/main_adherence.py): `adherence_study/main_adherence.py`
- [GLIMMER rollout](https://github.com/samankhamesian/guide/blob/main/glimmer_evaluation/glimmer_24h_rollout.py): `glimmer_evaluation/glimmer_24h_rollout.py`
- [Counterfactual evaluation](https://github.com/samankhamesian/guide/blob/main/glimmer_evaluation/glimmer_counterfactual.py): `glimmer_evaluation/glimmer_counterfactual.py`
- [Metrics and behavior analysis](https://github.com/samankhamesian/guide/blob/main/utils.py): `utils.py`

### Other components

- **Researcher**
- **Patient data**

## Connections

- Researcher → CQL-BC runner: runs training
- Patient data → Feature preparation: provides records
- Feature preparation → Patient simulator: prepares inputs (evidence: `simulator.py`)
- Patient simulator → Feature preparation: uses data controller (evidence: `simulator.py`)
- Patient simulator → Glucose predictor: uses predictor (evidence: `simulator.py`)
- RL environment → Patient simulator: delegates simulation (evidence: `environment.py`)
- RL environment → Bolus safeguard: checks proposed bolus (evidence: `environment.py`)
- CQL-BC runner → RL environment: creates environment (evidence: `model/cql_bc/main.py`)
- CQL-BC runner → CQL-BC agent: creates and trains (evidence: `model/cql_bc/main.py`)
- CQL-BC runner → Replay buffer: fills replay data (evidence: `model/cql_bc/main.py`)
- CQL-BC agent → TD3-BC networks: uses actor and critic (evidence: `model/cql_bc/cql_agent.py`)
- CQL-BC agent → Replay buffer: samples batches (evidence: `model/cql_bc/cql_agent.py`)
- PPO runner → RL environment: creates environment (evidence: `model/ppo/main.py`)
- PPO runner → PPO agent: trains and evaluates (evidence: `model/ppo/main.py`)
- PPO runner → PPO buffer: trains from buffer (evidence: `model/ppo/main.py`)
- SAC runner → RL environment: creates environment (evidence: `model/sac/main.py`)
- SAC runner → SAC agent: trains and evaluates (evidence: `model/sac/main.py`)
- Online SAC runner → RL environment: creates environment (evidence: `model/sac_online/main.py`)
- Online SAC runner → SAC agent: creates agent (evidence: `model/sac_online/main.py`)
- Online SAC runner → Replay buffer: stores transitions (evidence: `model/sac_online/main.py`)
- Random-policy runner → RL environment: creates environment (evidence: `model/random/main.py`)
- Random-policy runner → Random agent: uses policy (evidence: `model/random/main.py`)
- TD3-BC runner → RL environment: creates environment (evidence: `model/td3_bc/main.py`)
- TD3-BC runner → TD3-BC networks: creates agent (evidence: `model/td3_bc/main.py`)
- TD3-BC runner → Replay buffer: fills replay data (evidence: `model/td3_bc/main.py`)
- Action/reward ablations → RL environment: runs restricted actions (evidence: `ablation_study/ablation_common.py`)
- Action/reward ablations → CQL-BC agent: retains CQL-BC (evidence: `ablation_study/ablation_common.py`)
- Adherence analysis → RL environment: evaluates policies (evidence: `adherence_study/main_adherence.py`)
- Adherence analysis → CQL-BC agent: uses CQL-BC (evidence: `adherence_study/main_adherence.py`)
- GLIMMER rollout → Glucose predictor: uses predictor (evidence: `glimmer_evaluation/glimmer_24h_rollout.py`)
- GLIMMER rollout → Feature preparation: uses preprocessing (evidence: `glimmer_evaluation/glimmer_24h_rollout.py`)
- Counterfactual evaluation → Glucose predictor: uses predictor (evidence: `glimmer_evaluation/glimmer_counterfactual.py`)
- Counterfactual evaluation → Feature preparation: uses preprocessing (evidence: `glimmer_evaluation/glimmer_counterfactual.py`)
- CQL-BC runner → Metrics and behavior analysis: reports evaluation (evidence: `model/cql_bc/main.py`)
