# mmonad/feynman architecture

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

- Interactive diagram: https://gitdiagram.com/mmonad/feynman
- Repository: https://github.com/mmonad/feynman

## Overview

This repository is primarily a Feynman-style LLM and machine-learning tutoring curriculum, organized as topical course directories containing lesson documents. A learner chooses a course and follows its lessons; the README describes a progression from adaptation methods to verification, cryptography, and broader ML theory. The tree also contains two distinct research tools: token-level entropy evaluation and hidden-state topology experiments. Their internal edges below are limited to relationships visible in the supplied source index or excerpts; the curriculum’s lesson-level content and unsampled implementations are not expanded.

Main entry points: [`llm-information-theory/run.py`](https://github.com/mmonad/feynman/blob/main/llm-information-theory/run.py) (Entropy Evaluation), [`llm-topology-tda/run_experiment.py`](https://github.com/mmonad/feynman/blob/main/llm-topology-tda/run_experiment.py) (TDA Experiment), [`course-1-icl-vs-finetuning`](https://github.com/mmonad/feynman/tree/main/course-1-icl-vs-finetuning) (ICL vs Fine-Tuning), [`course-2-lora`](https://github.com/mmonad/feynman/tree/main/course-2-lora) (LoRA)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_adapt["LLM Adaptation"]
  node_c1["ICL vs Fine-Tuning"]
  node_c2["LoRA"]
  node_c5["Self-Improving Harness"]
  node_c19["LoRA Practice"]
end

subgraph group_verification["Verification Systems"]
  node_c3["Adapter Committees"]
  node_c4["Verification Enterprise"]
end

subgraph group_crypto["Cryptography"]
  node_c6["Crypto Foundations"]
  node_c7["Crypto Toolkit"]
  node_c8["BABE Protocol"]
end

subgraph group_ml["ML Foundations"]
  node_c9["Remedial Topics"]
  node_c10["Statistical Learning"]
  node_c11["Optimization"]
  node_c12["Probabilistic ML"]
  node_c13["Deep Learning Theory"]
  node_c14["Vision and NLP"]
  node_c15["Reinforcement Learning"]
  node_c16["Generalization and GNNs"]
  node_c17["Causality and Practice"]
  node_c18["Robustness Frontier"]
  node_c20["Intelligence Theory"]
end

subgraph group_research["Research Tools"]
  node_entropy["Entropy Evaluation<br/>[run.py]"]
  node_fineweb["FineWeb Holdout<br/>[data.py]"]
  node_model["Model Loader<br/>[models.py]"]
  node_window["Windowed Scoring<br/>[windowed_eval.py]"]
  node_report["Entropy Report<br/>[report.py]"]
  node_experiment["TDA Experiment<br/>[run_experiment.py]"]
  node_datasets["Benchmarks and Graders<br/>[datasets_lib.py]"]
  node_extract["State Extraction<br/>[pipeline.py]"]
  node_analysis["PCA and Persistence<br/>[analyze.py]"]
  node_failure["Failure Landscape"]
end

node_learner(("Learner"))

node_learner -->|"studies lessons"| node_c1
node_learner -->|"studies lessons"| node_c2
node_learner -->|"studies lessons"| node_c3
node_learner -->|"studies lessons"| node_c4
node_learner -->|"studies lessons"| node_c5
node_learner -->|"studies lessons"| node_c6
node_learner -->|"studies lessons"| node_c7
node_learner -->|"studies lessons"| node_c8
node_learner -->|"studies lessons"| node_c9
node_learner -->|"studies lessons"| node_c10
node_learner -->|"studies lessons"| node_c11
node_learner -->|"studies lessons"| node_c12
node_learner -->|"studies lessons"| node_c13
node_learner -->|"studies lessons"| node_c14
node_learner -->|"studies lessons"| node_c15
node_learner -->|"studies lessons"| node_c16
node_learner -->|"studies lessons"| node_c17
node_learner -->|"studies lessons"| node_c18
node_learner -->|"studies lessons"| node_c19
node_learner -->|"studies lessons"| node_c20
node_entropy -->|"loads holdout"| node_fineweb
node_entropy -->|"loads model"| node_model
node_entropy -->|"scores documents"| node_window
node_experiment -->|"loads and grades"| node_datasets
node_experiment -->|"extracts states"| node_extract
node_experiment -->|"runs analysis"| node_analysis

click node_c1 "https://github.com/mmonad/feynman/tree/main/course-1-icl-vs-finetuning"
click node_c2 "https://github.com/mmonad/feynman/tree/main/course-2-lora"
click node_c3 "https://github.com/mmonad/feynman/tree/main/course-3-orthogonal-adapters-code-review"
click node_c4 "https://github.com/mmonad/feynman/tree/main/course-4-from-architecture-to-enterprise"
click node_c5 "https://github.com/mmonad/feynman/tree/main/course-5-self-improving-harness"
click node_c6 "https://github.com/mmonad/feynman/tree/main/course-6-crypto-foundations"
click node_c7 "https://github.com/mmonad/feynman/tree/main/course-7-crypto-toolkit"
click node_c8 "https://github.com/mmonad/feynman/tree/main/course-8-babe-protocol"
click node_c9 "https://github.com/mmonad/feynman/tree/main/course-9-remedial"
click node_c10 "https://github.com/mmonad/feynman/tree/main/course-10-statistical-learning-theory"
click node_c11 "https://github.com/mmonad/feynman/tree/main/course-11-optimization"
click node_c12 "https://github.com/mmonad/feynman/tree/main/course-12-probabilistic-ml"
click node_c13 "https://github.com/mmonad/feynman/tree/main/course-13-deep-learning-theory"
click node_c14 "https://github.com/mmonad/feynman/tree/main/course-14-vision-and-nlp"
click node_c15 "https://github.com/mmonad/feynman/tree/main/course-15-reinforcement-learning"
click node_c16 "https://github.com/mmonad/feynman/tree/main/course-16-generalization-and-gnns"
click node_c17 "https://github.com/mmonad/feynman/tree/main/course-17-causality-and-practical-ml"
click node_c18 "https://github.com/mmonad/feynman/tree/main/course-18-systems-robustness-frontier"
click node_c19 "https://github.com/mmonad/feynman/tree/main/course-19-lora-practice"
click node_c20 "https://github.com/mmonad/feynman/tree/main/course-20-mathematical-theory-of-intelligence"
click node_entropy "https://github.com/mmonad/feynman/blob/main/llm-information-theory/run.py"
click node_fineweb "https://github.com/mmonad/feynman/blob/main/llm-information-theory/data.py"
click node_model "https://github.com/mmonad/feynman/blob/main/llm-information-theory/models.py"
click node_window "https://github.com/mmonad/feynman/blob/main/llm-information-theory/windowed_eval.py"
click node_report "https://github.com/mmonad/feynman/blob/main/llm-information-theory/report.py"
click node_experiment "https://github.com/mmonad/feynman/blob/main/llm-topology-tda/run_experiment.py"
click node_datasets "https://github.com/mmonad/feynman/blob/main/llm-topology-tda/datasets_lib.py"
click node_extract "https://github.com/mmonad/feynman/blob/main/llm-topology-tda/pipeline.py"
click node_analysis "https://github.com/mmonad/feynman/blob/main/llm-topology-tda/analyze.py"
click node_failure "https://github.com/mmonad/feynman/blob/main/llm-topology-tda/failure_landscape_tda.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_c1,node_c2,node_c5,node_c19 toneBlue
class node_c3,node_c4 toneAmber
class node_c6,node_c7,node_c8 toneMint
class node_c9,node_c10,node_c11,node_c12,node_c13,node_c14,node_c15,node_c16,node_c17,node_c18,node_c20 toneRose
class node_entropy,node_fineweb,node_model,node_window,node_report,node_experiment,node_datasets,node_extract,node_analysis,node_failure,node_learner toneIndigo
```

## Components

### LLM Adaptation

- [ICL vs Fine-Tuning](https://github.com/mmonad/feynman/tree/main/course-1-icl-vs-finetuning): `course-1-icl-vs-finetuning`
- [LoRA](https://github.com/mmonad/feynman/tree/main/course-2-lora): `course-2-lora`
- [Self-Improving Harness](https://github.com/mmonad/feynman/tree/main/course-5-self-improving-harness): `course-5-self-improving-harness`
- [LoRA Practice](https://github.com/mmonad/feynman/tree/main/course-19-lora-practice): `course-19-lora-practice`

### Verification Systems

- [Adapter Committees](https://github.com/mmonad/feynman/tree/main/course-3-orthogonal-adapters-code-review): `course-3-orthogonal-adapters-code-review`
- [Verification Enterprise](https://github.com/mmonad/feynman/tree/main/course-4-from-architecture-to-enterprise): `course-4-from-architecture-to-enterprise`

### Cryptography

- [Crypto Foundations](https://github.com/mmonad/feynman/tree/main/course-6-crypto-foundations): `course-6-crypto-foundations`
- [Crypto Toolkit](https://github.com/mmonad/feynman/tree/main/course-7-crypto-toolkit): `course-7-crypto-toolkit`
- [BABE Protocol](https://github.com/mmonad/feynman/tree/main/course-8-babe-protocol): `course-8-babe-protocol`

### ML Foundations

- [Remedial Topics](https://github.com/mmonad/feynman/tree/main/course-9-remedial): `course-9-remedial`
- [Statistical Learning](https://github.com/mmonad/feynman/tree/main/course-10-statistical-learning-theory): `course-10-statistical-learning-theory`
- [Optimization](https://github.com/mmonad/feynman/tree/main/course-11-optimization): `course-11-optimization`
- [Probabilistic ML](https://github.com/mmonad/feynman/tree/main/course-12-probabilistic-ml): `course-12-probabilistic-ml`
- [Deep Learning Theory](https://github.com/mmonad/feynman/tree/main/course-13-deep-learning-theory): `course-13-deep-learning-theory`
- [Vision and NLP](https://github.com/mmonad/feynman/tree/main/course-14-vision-and-nlp): `course-14-vision-and-nlp`
- [Reinforcement Learning](https://github.com/mmonad/feynman/tree/main/course-15-reinforcement-learning): `course-15-reinforcement-learning`
- [Generalization and GNNs](https://github.com/mmonad/feynman/tree/main/course-16-generalization-and-gnns): `course-16-generalization-and-gnns`
- [Causality and Practice](https://github.com/mmonad/feynman/tree/main/course-17-causality-and-practical-ml): `course-17-causality-and-practical-ml`
- [Robustness Frontier](https://github.com/mmonad/feynman/tree/main/course-18-systems-robustness-frontier): `course-18-systems-robustness-frontier`
- [Intelligence Theory](https://github.com/mmonad/feynman/tree/main/course-20-mathematical-theory-of-intelligence): `course-20-mathematical-theory-of-intelligence`

### Research Tools

- [Entropy Evaluation](https://github.com/mmonad/feynman/blob/main/llm-information-theory/run.py): `llm-information-theory/run.py`
- [FineWeb Holdout](https://github.com/mmonad/feynman/blob/main/llm-information-theory/data.py): `llm-information-theory/data.py`
- [Model Loader](https://github.com/mmonad/feynman/blob/main/llm-information-theory/models.py): `llm-information-theory/models.py`
- [Windowed Scoring](https://github.com/mmonad/feynman/blob/main/llm-information-theory/windowed_eval.py): `llm-information-theory/windowed_eval.py`
- [Entropy Report](https://github.com/mmonad/feynman/blob/main/llm-information-theory/report.py): `llm-information-theory/report.py`
- [TDA Experiment](https://github.com/mmonad/feynman/blob/main/llm-topology-tda/run_experiment.py): `llm-topology-tda/run_experiment.py`
- [Benchmarks and Graders](https://github.com/mmonad/feynman/blob/main/llm-topology-tda/datasets_lib.py): `llm-topology-tda/datasets_lib.py`
- [State Extraction](https://github.com/mmonad/feynman/blob/main/llm-topology-tda/pipeline.py): `llm-topology-tda/pipeline.py`
- [PCA and Persistence](https://github.com/mmonad/feynman/blob/main/llm-topology-tda/analyze.py): `llm-topology-tda/analyze.py`
- [Failure Landscape](https://github.com/mmonad/feynman/blob/main/llm-topology-tda/failure_landscape_tda.py): `llm-topology-tda/failure_landscape_tda.py`

### Other components

- **Learner**

## Connections

- Learner → ICL vs Fine-Tuning: studies lessons (evidence: `README.md`)
- Learner → LoRA: studies lessons (evidence: `README.md`)
- Learner → Adapter Committees: studies lessons (evidence: `README.md`)
- Learner → Verification Enterprise: studies lessons (evidence: `README.md`)
- Learner → Self-Improving Harness: studies lessons (evidence: `README.md`)
- Learner → Crypto Foundations: studies lessons (evidence: `README.md`)
- Learner → Crypto Toolkit: studies lessons (evidence: `README.md`)
- Learner → BABE Protocol: studies lessons (evidence: `README.md`)
- Learner → Remedial Topics: studies lessons (evidence: `README.md`)
- Learner → Statistical Learning: studies lessons (evidence: `README.md`)
- Learner → Optimization: studies lessons (evidence: `README.md`)
- Learner → Probabilistic ML: studies lessons (evidence: `README.md`)
- Learner → Deep Learning Theory: studies lessons (evidence: `README.md`)
- Learner → Vision and NLP: studies lessons (evidence: `README.md`)
- Learner → Reinforcement Learning: studies lessons (evidence: `README.md`)
- Learner → Generalization and GNNs: studies lessons (evidence: `README.md`)
- Learner → Causality and Practice: studies lessons (evidence: `README.md`)
- Learner → Robustness Frontier: studies lessons (evidence: `README.md`)
- Learner → LoRA Practice: studies lessons (evidence: `README.md`)
- Learner → Intelligence Theory: studies lessons (evidence: `README.md`)
- Entropy Evaluation → FineWeb Holdout: loads holdout (evidence: `llm-information-theory/run.py`)
- Entropy Evaluation → Model Loader: loads model (evidence: `llm-information-theory/run.py`)
- Entropy Evaluation → Windowed Scoring: scores documents (evidence: `llm-information-theory/run.py`)
- TDA Experiment → Benchmarks and Graders: loads and grades (evidence: `llm-topology-tda/run_experiment.py`)
- TDA Experiment → State Extraction: extracts states (evidence: `llm-topology-tda/run_experiment.py`)
- TDA Experiment → PCA and Persistence: runs analysis (evidence: `llm-topology-tda/run_experiment.py`)
