# dch2r/chasing-the-aha-moment architecture

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

- Interactive diagram: https://gitdiagram.com/dch2r/chasing-the-aha-moment
- Repository: https://github.com/dch2r/chasing-the-aha-moment

## Overview

This repository is an instrumented GRPO post-training and evaluation study, not a new RL algorithm. Its main workflow trains a reward-design arm, records per-response rewards and training diagnostics, evaluates the saved adapter against the same base model under a fixed protocol, then compares paired outcomes and exports changed responses. It also supports resumable GPU replay and CPU-side evidence verification. The graph includes the documented ablation and replay branches; unsampled notebook wiring is represented only where the README establishes it.

Main entry points: [`scripts/train_arm.py`](https://github.com/dch2r/chasing-the-aha-moment/blob/main/scripts/train_arm.py) (Train reward arm), [`scripts/evaluate.py`](https://github.com/dch2r/chasing-the-aha-moment/blob/main/scripts/evaluate.py) (Paired evaluator), [`src/experiment_rewards.py`](https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/experiment_rewards.py) (Reward arms), [`src/eval_scoring.py`](https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/eval_scoring.py) (Evaluation scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["Training and rewards"]
  node_arm_runner["Train reward arm<br/>[train_arm.py]"]
  node_arm_rewards["Reward arms"]
  node_reward_parser["Training parser<br/>[rewards.py]"]
  node_arm_logger["Response logger<br/>[arm_logging.py]"]
  node_diagnostics["Training diagnostics<br/>[diagnostics.py]"]
  node_grpo_compat["GRPO compatibility<br/>[grpo_compat.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluator["Paired evaluator<br/>[evaluate.py]"]
  node_eval_parser["Evaluation scoring<br/>[eval_scoring.py]"]
  node_eval_io["Resumable evaluation I/O<br/>[evaluation_io.py]"]
  node_artifact_checks["Adapter fingerprints<br/>[artifact_checks.py]"]
end

subgraph group_analysis["Analysis and audit"]
  node_analyzer["Result analyzer<br/>[analyze_results.py]"]
  node_paired_stats["Paired statistics<br/>[paired_analysis.py]"]
  node_ablation_summary["Ablation summarizer"]
  node_verifier["Evidence verifier<br/>[verify_results.py]"]
  node_demo["Saved-answer demo<br/>[demo.py]"]
end

subgraph group_evidence["Saved evidence"]
  node_adapter["Saved LoRA adapter"]
  node_training_records["Pilot training records"]
  node_training_logs["Training logs"]
  node_eval_results["Evaluation results"]
  node_replay_results["Replay results"]
  node_changed_answers["Changed responses"]
  node_ablation_rewards["Ablation logs"]
end

subgraph group_external["External dependencies"]
  node_trl["TRL GRPO"]
  node_base_model["Hugging Face model"]
end

node_engineer(("Researcher"))

node_engineer -->|"selects arm"| node_arm_runner
node_arm_runner -->|"loads records"| node_training_records
node_arm_runner -->|"loads model"| node_base_model
node_arm_runner -->|"selects reward"| node_arm_rewards
node_arm_rewards -->|"scores historically"| node_reward_parser
node_arm_rewards -->|"scores corrected"| node_eval_parser
node_arm_runner -->|"creates logger"| node_arm_logger
node_arm_logger -->|"computes components"| node_arm_rewards
node_arm_logger -->|"writes responses"| node_training_logs
node_arm_runner -->|"configures training"| node_grpo_compat
node_arm_runner -->|"summarizes run"| node_diagnostics
node_arm_runner -->|"trains with"| node_trl
node_arm_runner -->|"saves adapter"| node_adapter
node_engineer -->|"runs evaluation"| node_evaluator
node_evaluator -->|"loads base"| node_base_model
node_evaluator -->|"loads adapter"| node_adapter
node_evaluator -->|"checks fingerprints"| node_artifact_checks
node_evaluator -->|"scores answers"| node_eval_parser
node_evaluator -->|"resumes and writes"| node_eval_io
node_evaluator -->|"records evaluation"| node_eval_results
node_evaluator -->|"records replay"| node_replay_results
node_engineer -->|"analyzes results"| node_analyzer
node_analyzer -->|"scores responses"| node_eval_parser
node_analyzer -->|"computes paired tests"| node_paired_stats
node_analyzer -->|"exports changes"| node_changed_answers
node_engineer -->|"summarizes ablation"| node_ablation_summary
node_ablation_summary -->|"uses arm scoring"| node_arm_rewards
node_ablation_summary -->|"summarizes runs"| node_ablation_rewards
node_engineer -->|"audits evidence"| node_verifier
node_verifier -->|"rechecks scores"| node_eval_parser
node_verifier -->|"checks adapter"| node_artifact_checks
node_verifier -->|"recomputes analysis"| node_paired_stats
node_engineer -->|"replays saved answers"| node_demo
node_demo -->|"scores live"| node_eval_parser
node_demo -.->|"reads saved run"| node_training_logs

click node_arm_runner "https://github.com/dch2r/chasing-the-aha-moment/blob/main/scripts/train_arm.py"
click node_arm_rewards "https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/experiment_rewards.py"
click node_reward_parser "https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/rewards.py"
click node_arm_logger "https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/arm_logging.py"
click node_diagnostics "https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/diagnostics.py"
click node_grpo_compat "https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/grpo_compat.py"
click node_adapter "https://github.com/dch2r/chasing-the-aha-moment/tree/main/adapter"
click node_training_records "https://github.com/dch2r/chasing-the-aha-moment/tree/main/results/pilot/run_metadata"
click node_training_logs "https://github.com/dch2r/chasing-the-aha-moment/tree/main/results/pilot"
click node_evaluator "https://github.com/dch2r/chasing-the-aha-moment/blob/main/scripts/evaluate.py"
click node_eval_parser "https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/eval_scoring.py"
click node_eval_io "https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/evaluation_io.py"
click node_artifact_checks "https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/artifact_checks.py"
click node_eval_results "https://github.com/dch2r/chasing-the-aha-moment/tree/main/results/evaluation"
click node_replay_results "https://github.com/dch2r/chasing-the-aha-moment/tree/main/results/replay"
click node_analyzer "https://github.com/dch2r/chasing-the-aha-moment/blob/main/scripts/analyze_results.py"
click node_paired_stats "https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/paired_analysis.py"
click node_changed_answers "https://github.com/dch2r/chasing-the-aha-moment/blob/main/results/analysis/changed_responses.json"
click node_ablation_summary "https://github.com/dch2r/chasing-the-aha-moment/blob/main/scripts/summarize_ablation.py"
click node_ablation_rewards "https://github.com/dch2r/chasing-the-aha-moment/tree/main/results/ablation/stage1"
click node_verifier "https://github.com/dch2r/chasing-the-aha-moment/blob/main/scripts/verify_results.py"
click node_demo "https://github.com/dch2r/chasing-the-aha-moment/blob/main/scripts/demo.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_arm_runner,node_arm_rewards,node_reward_parser,node_arm_logger,node_diagnostics,node_grpo_compat toneBlue
class node_evaluator,node_eval_parser,node_eval_io,node_artifact_checks toneAmber
class node_analyzer,node_paired_stats,node_ablation_summary,node_verifier,node_demo toneMint
class node_adapter,node_training_records,node_training_logs,node_eval_results,node_replay_results,node_changed_answers,node_ablation_rewards toneRose
class node_trl,node_base_model,node_engineer toneIndigo
```

## Components

### Training and rewards

- [Train reward arm](https://github.com/dch2r/chasing-the-aha-moment/blob/main/scripts/train_arm.py): `scripts/train_arm.py`
- [Reward arms](https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/experiment_rewards.py): `src/experiment_rewards.py`
- [Training parser](https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/rewards.py): `src/rewards.py`
- [Response logger](https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/arm_logging.py): `src/arm_logging.py`
- [Training diagnostics](https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/diagnostics.py): `src/diagnostics.py`
- [GRPO compatibility](https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/grpo_compat.py): `src/grpo_compat.py`

### Evaluation

- [Paired evaluator](https://github.com/dch2r/chasing-the-aha-moment/blob/main/scripts/evaluate.py): `scripts/evaluate.py`
- [Evaluation scoring](https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/eval_scoring.py): `src/eval_scoring.py`
- [Resumable evaluation I/O](https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/evaluation_io.py): `src/evaluation_io.py`
- [Adapter fingerprints](https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/artifact_checks.py): `src/artifact_checks.py`

### Analysis and audit

- [Result analyzer](https://github.com/dch2r/chasing-the-aha-moment/blob/main/scripts/analyze_results.py): `scripts/analyze_results.py`
- [Paired statistics](https://github.com/dch2r/chasing-the-aha-moment/blob/main/src/paired_analysis.py): `src/paired_analysis.py`
- [Ablation summarizer](https://github.com/dch2r/chasing-the-aha-moment/blob/main/scripts/summarize_ablation.py): `scripts/summarize_ablation.py`
- [Evidence verifier](https://github.com/dch2r/chasing-the-aha-moment/blob/main/scripts/verify_results.py): `scripts/verify_results.py`
- [Saved-answer demo](https://github.com/dch2r/chasing-the-aha-moment/blob/main/scripts/demo.py): `scripts/demo.py`

### Saved evidence

- [Saved LoRA adapter](https://github.com/dch2r/chasing-the-aha-moment/tree/main/adapter): `adapter`
- [Pilot training records](https://github.com/dch2r/chasing-the-aha-moment/tree/main/results/pilot/run_metadata): `results/pilot/run_metadata`
- [Training logs](https://github.com/dch2r/chasing-the-aha-moment/tree/main/results/pilot): `results/pilot`
- [Evaluation results](https://github.com/dch2r/chasing-the-aha-moment/tree/main/results/evaluation): `results/evaluation`
- [Replay results](https://github.com/dch2r/chasing-the-aha-moment/tree/main/results/replay): `results/replay`
- [Changed responses](https://github.com/dch2r/chasing-the-aha-moment/blob/main/results/analysis/changed_responses.json): `results/analysis/changed_responses.json`
- [Ablation logs](https://github.com/dch2r/chasing-the-aha-moment/tree/main/results/ablation/stage1): `results/ablation/stage1`

### External dependencies

- **TRL GRPO**
- **Hugging Face model**

### Other components

- **Researcher**

## Connections

- Researcher → Train reward arm: selects arm (evidence: `README.md`)
- Train reward arm → Pilot training records: loads records (evidence: `scripts/train_arm.py`)
- Train reward arm → Hugging Face model: loads model (evidence: `scripts/train_arm.py`)
- Train reward arm → Reward arms: selects reward (evidence: `scripts/train_arm.py`)
- Reward arms → Training parser: scores historically (evidence: `src/experiment_rewards.py`)
- Reward arms → Evaluation scoring: scores corrected (evidence: `src/experiment_rewards.py`)
- Train reward arm → Response logger: creates logger (evidence: `scripts/train_arm.py`)
- Response logger → Reward arms: computes components (evidence: `src/arm_logging.py`)
- Response logger → Training logs: writes responses (evidence: `src/arm_logging.py`)
- Train reward arm → GRPO compatibility: configures training (evidence: `scripts/train_arm.py`)
- Train reward arm → Training diagnostics: summarizes run (evidence: `scripts/train_arm.py`)
- Train reward arm → TRL GRPO: trains with (evidence: `scripts/train_arm.py`)
- Train reward arm → Saved LoRA adapter: saves adapter (evidence: `scripts/train_arm.py`)
- Researcher → Paired evaluator: runs evaluation (evidence: `README.md`)
- Paired evaluator → Hugging Face model: loads base (evidence: `README.md`)
- Paired evaluator → Saved LoRA adapter: loads adapter (evidence: `README.md`)
- Paired evaluator → Adapter fingerprints: checks fingerprints (evidence: `scripts/evaluate.py`)
- Paired evaluator → Evaluation scoring: scores answers (evidence: `scripts/evaluate.py`)
- Paired evaluator → Resumable evaluation I/O: resumes and writes (evidence: `scripts/evaluate.py`)
- Paired evaluator → Evaluation results: records evaluation (evidence: `README.md`)
- Paired evaluator → Replay results: records replay (evidence: `README.md`)
- Researcher → Result analyzer: analyzes results (evidence: `README.md`)
- Result analyzer → Evaluation scoring: scores responses (evidence: `scripts/analyze_results.py`)
- Result analyzer → Paired statistics: computes paired tests (evidence: `scripts/analyze_results.py`)
- Result analyzer → Changed responses: exports changes (evidence: `README.md`)
- Researcher → Ablation summarizer: summarizes ablation (evidence: `README.md`)
- Ablation summarizer → Reward arms: uses arm scoring (evidence: `scripts/summarize_ablation.py`)
- Ablation summarizer → Ablation logs: summarizes runs (evidence: `README.md`)
- Researcher → Evidence verifier: audits evidence (evidence: `README.md`)
- Evidence verifier → Evaluation scoring: rechecks scores (evidence: `scripts/verify_results.py`)
- Evidence verifier → Adapter fingerprints: checks adapter (evidence: `scripts/verify_results.py`)
- Evidence verifier → Paired statistics: recomputes analysis (evidence: `scripts/verify_results.py`)
- Researcher → Saved-answer demo: replays saved answers (evidence: `README.md`)
- Saved-answer demo → Evaluation scoring: scores live (evidence: `scripts/demo.py`)
- Saved-answer demo → Training logs: reads saved run (evidence: `README.md`)