# rizdas/lunagpt architecture

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

- Interactive diagram: https://gitdiagram.com/rizdas/lunagpt
- Repository: https://github.com/rizdas/lunagpt

## Overview

##### What this project is (type + purpose)

**lunaGPT** is a **Python experimental “scratchpad repo”** for prototyping:
- **Character-level GPT training experiments** (from bigram → transformer variants) in `gpt/`
- A **GPT‑2 architecture reimplementation + partial pretrained weight loading** in `gpt2/`
- **Voice assistant primitives** (speech-to-text + text-to-speech) in `head/`
- A **placeholder persistence layer** using text files in `memory/`

##### Training/Model Experiments (Batch)
- `gpt/bigram.py`
- `gpt/v2.py`
- `gpt/v2.2_noDropout.py`
- `gpt/v2.5.py`
- `gpt/v3.py`
- Input: `gpt/input.txt` (Tiny Shakespeare)
- Runtime: `torch`, optional CUDA/GPU
- Output: generated samples to stdout; (no checkpointing currently)

##### GPT‑2 Demo (Batch / Demo)
- `gpt2/train_gpt2.py`
- Internals: `CausalSelfAttention`, `MLP`, `Block`, `GPTConfig`, `GPT`
- External deps:
- `transformers` (to fetch pretrained weights)
- `tiktoken` (tokenization)
- Hugging Face model hub (internet download on first run)
- Output: generated text (top‑k sampling), stdout

##### Voice I/O (Interactive)
- `head/ear.py` (Speech-to-text)
- `speech_recognition` + microphone device
- `recognize_google` (Google Speech API; internet)
- `head/mouth.py` (Text-to-speech)
- `edge-tts` (internet)
- `pygame` audio playback device
- temporary audio file creation/deletion

##### Memory (Local Text Persistence Stub)
- `memory/cache.txt`
- `memory/learning.txt`
- `memory/saved.txt`
- (Not wired into scripts yet, but include as “planned/placeholder storage”)

##### Utilities
- `gpt/check.py` (CUDA availability check)

- `gpt/*.py` → reads → `gpt/input.txt`
- `gpt/*.py` → uses → `torch` → optionally → `CUDA GPU`
- `gpt2/train_gpt2.py` → downloads → **Hugging Face Hub** → loads → weights into local model
- `gpt2/train_gpt2.py` → uses → `tiktoken` (tokenize prompt)
- `head/ear.py` → captures → **Microphone** → sends audio to → **Google Speech Recognition API** → returns → text
- `head/mouth.py` → sends text to → **Edge TTS service** → returns → audio file → plays via → **Audio Output (pygame)**

Nodes:
- **Launcher / Orchestrator (future)**: `assistant.py` (not present yet; show as planned)
- **ASR**: `head/ear.py`
- **LLM Inference**: choose either
- “Local Char-GPT” (from `gpt/` family) or
- “GPT‑2-like model” (from `gpt2/train_gpt2.py`)
- **Memory Store**: `memory/*.txt` (eventually a DB)
- **TTS**: `head/mouth.py`

Edges:
Mic → ASR → text → LLM → response text → Memory read/write → TTS → Speaker

Use this to distinguish *current state vs intended system*; principal engineers will appreciate both.

##### Architectural patterns / principles to highlight (specific to this repo)

- **Research/prototype pipeline**: scripts are “experiments”, not modularized libraries.
- **Decoder-only transformer pattern**: for `gpt/v2+` and `gpt2/train_gpt2.py` (masked self-attention, residual, LN, FFN).
- **Adapter pattern for I/O**: `head/ear.py` and `head/mouth.py` are effectively adapters to external services/hardware.
- **External dependency boundaries**:
- Cloud APIs (Google recognition, Edge TTS)
- Hugging Face Hub downloads
- **Storage boundary**: plaintext files in `memory/` (currently not integrated).

- `gpt/*`: **PyTorch**, optional **CUDA**
- `gpt2/train_gpt2.py`: **PyTorch + transformers + tiktoken**, Hugging Face Hub
- `head/ear.py`: **speech_recognition**, **PyAudio**, **Google Speech API**
- `head/mouth.py`: **edge-tts**, **pygame**, filesystem temp audio
- `memory/*`: filesystem text files

Runtime requirements next to boundaries:
- “Internet required” for Hugging Face / Google / Edge TTS
- “Audio device required” for mic/speaker
- “GPU optional” for training speed

##### Inside each subsystem, scripts as components

This matches the repo’s structure 1:1 and avoids inventing nonexistent services.

- “audio stream”
- “text”
- “tokens”
- “model weights”
- “characters (training corpus)”

##### Detail level (don’t under-specify)
Because the repo is script-heavy, “detailed” means:
- **each external API/service** as a separate node
- **all files that are true inputs/outputs** (`gpt/input.txt`, temp TTS audio, `memory/*.txt`)
- **runtime dependencies** that are architectural (not every pip package, but the ones that define boundaries)

- `gpt/bigram.py`, `gpt/v2.py`, `gpt/v2.2_noDropout.py`, `gpt/v2.5.py`, `gpt/v3.py`
- `gpt/input.txt`
- `gpt2/train_gpt2.py`
- Hugging Face Hub (cloud)
- `transformers`, `tiktoken`, `torch`
- `head/ear.py` + Microphone + Google Speech API
- `head/mouth.py` + Edge TTS + Temp audio file + Speaker (pygame)
- `memory/cache.txt`, `memory/learning.txt`, `memory/saved.txt` (as placeholder store)
- Optional: GPU/CUDA + `gpt/check.py`

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Repo Boundary (Current)
%% =========================
subgraph REPO["lunaGPT (local machine) — Current State (script-level components)"]
direction TB

README["README (overview + intended usage)"]:::doc

%% -------- gpt/ --------
subgraph GPTSYS["gpt/ — Training & Model Experiments (Batch)"]
direction TB

GPTDIR["gpt/ (folder)"]:::folder

GPT_CORPUS[("gpt/input.txt (Tiny Shakespeare corpus)")]:::storage

GPT_EXPERIMENTS["Char-level GPT experiments (stdout samples; no checkpoints)"]:::group

BIGRAM("bigram.py\n(PyTorch)"):::script
V2("v2.py\n(Transformer variant; PyTorch)"):::script
V22("v2.2_noDropout.py\n(Transformer variant; PyTorch)"):::script
V25("v2.5.py\n(Transformer variant; PyTorch)"):::script
V3("v3.py\n(Transformer variant; PyTorch)"):::script

CUDA_CHECK("check.py\n(CUDA availability check)"):::util

TORCH["torch (PyTorch runtime)"]:::lib
GPU[/"CUDA GPU (optional)"/]:::device

end

%% -------- gpt2/ --------
subgraph GPT2SYS["gpt2/ — GPT‑2 Architecture Reimplementation (Batch/Demo)"]
direction TB

GPT2DIR["gpt2/ (folder)"]:::folder

GPT2_MAIN("train_gpt2.py\n(GPT‑2-like model + pretrained import + generation)"):::script
GPT2_ALT("train2_gpt2.py\n(alt demo/training script)"):::script
GPT2_NB["(test)dummy.ipynb\n(notebook stub/test)"]:::doc

TRANSFORMERS["transformers\n(pretrained weight fetch/compat)"]:::lib
TIKTOKEN["tiktoken\n(tokenization)"]:::lib
HFHUB["Hugging Face Hub\n(internet download on first run)"]:::cloud

end

%% -------- head/ --------
subgraph HEADSYS["head/ — Voice I/O Adapters (Interactive)"]
direction TB

HEADDR["head/ (folder)"]:::folder

EAR("ear.py\n(ASR adapter)"):::script
MOUTH("mouth.py\n(TTS adapter)"):::script

SRLIB["speech_recognition + PyAudio\n(mic capture + client)"]:::lib
GOOGLEASR["Google Speech Recognition API\n(internet)"]:::cloud

EDGETTS["edge-tts\n(internet)"]:::cloud
PYGAME["pygame\n(audio playback)"]:::lib

MIC[/"Microphone device"/]:::device
SPK[/"Speaker/Audio output device"/]:::device
TMPAUDIO[("Temp audio file\n(create/delete)")]:::storage

end

%% -------- memory/ --------
subgraph MEMSYS["memory/ — Local Text Persistence Stub (Planned/Placeholder)"]
direction TB

MEMDIR["memory/ (folder)"]:::folder
CACHE[("cache.txt")]:::storage
LEARN[("learning.txt")]:::storage
SAVED[("saved.txt")]:::storage
end

%% -------- Cross-cutting boundary notes --------
INTERNET["Internet required\n(HF Hub, Google ASR, Edge TTS)"]:::note
AUDIOHW["Audio device required\n(Mic/Speaker)"]:::note

end

%% =========================
%% Current State Dataflows
%% =========================
README -->|"describes"| GPTSYS
README -->|"describes"| GPT2SYS
README -->|"describes"| HEADSYS
README -->|"mentions_placeholder"| MEMSYS

%% gpt: corpus + torch + gpu
BIGRAM -->|"reads_characters"| GPT_CORPUS
V2 -->|"reads_characters"| GPT_CORPUS
V22 -->|"reads_characters"| GPT_CORPUS
V25 -->|"reads_characters"| GPT_CORPUS
V3 -->|"reads_characters"| GPT_CORPUS

BIGRAM -->|"uses"| TORCH
V2 -->|"uses"| TORCH
V22 -->|"uses"| TORCH
V25 -->|"uses"| TORCH
V3 -->|"uses"| TORCH

CUDA_CHECK -->|"checks"| TORCH
TORCH -->|"optional_acceleration"| GPU

GPT_EXPERIMENTS -->|"groups"| BIGRAM
GPT_EXPERIMENTS -->|"groups"| V2
GPT_EXPERIMENTS -->|"groups"| V22
GPT_EXPERIMENTS -->|"groups"| V25
GPT_EXPERIMENTS -->|"groups"| V3

%% gpt2: torch + transformers/tiktoken + hf hub
GPT2_MAIN -->|"uses"| TORCH
GPT2_MAIN -->|"uses"| TRANSFORMERS
GPT2_MAIN -->|"uses"| TIKTOKEN
TRANSFORMERS -->|"downloads_weights"| HFHUB
HFHUB -->|"model_weights"| GPT2_MAIN

GPT2_ALT -->|"uses"| TORCH
GPT2_ALT -->|"uses"| TRANSFORMERS
GPT2_ALT -->|"uses"| TIKTOKEN

%% head: mic->asr->text ; text->tts->audiofile->speaker
MIC -->|"audio_stream"| EAR
EAR -->|"uses"| SRLIB
SRLIB -->|"recognize_google(audio)"| GOOGLEASR
GOOGLEASR -->|"recognized_text"| EAR

MOUTH -->|"sends_text"| EDGETTS
EDGETTS -->|"audio_file_bytes"| MOUTH
MOUTH -->|"writes"| TMPAUDIO
TMPAUDIO -->|"played_by"| PYGAME
PYGAME -->|"audio_out"| SPK

%% boundary notes
HFHUB -->|"requires"| INTERNET
GOOGLEASR -->|"requires"| INTERNET
EDGETTS -->|"requires"| INTERNET
MIC -->|"requires"| AUDIOHW
SPK -->|"requires"| AUDIOHW

%% memory: placeholder (not wired yet)
MEMDIR -.->|"placeholder_storage"| CACHE
MEMDIR -.->|"placeholder_storage"| LEARN
MEMDIR -.->|"placeholder_storage"| SAVED

%% =========================
%% Target (Future) Integrated Assistant
%% =========================
subgraph TARGET["Target Architecture (Future/Planned) — Integrated Voice Assistant"]
direction TB

ASSIST("assistant.py\n(Launcher/Orchestrator — planned)"):::planned

ASR("ASR: head/ear.py"):::planned
LLMSEL{"LLM Inference (choose)"}:::planned
CHARLLM["Local Char-GPT\n(gpt/* variants)"]:::planned
GPT2LLM["GPT‑2-like Model\n(gpt2/train_gpt2.py)"]:::planned
MEMSTORE["Memory Store\n(memory/*.txt → later DB)"]:::planned
TTS("TTS: head/mouth.py"):::planned

MIC2[/"Microphone"/]:::device
SPK2[/"Speaker"/]:::device

MIC2 -->|"audio"| ASR
ASR -->|"text"| ASSIST
ASSIST -->|"prompt/context"| LLMSEL
LLMSEL -->|"option"| CHARLLM
LLMSEL -->|"option"| GPT2LLM
CHARLLM -->|"response_text"| ASSIST
GPT2LLM -->|"response_text"| ASSIST
ASSIST -.->|"read/write"| MEMSTORE
ASSIST -->|"text"| TTS
TTS -->|"audio"| SPK2
end

%% -------------------------
%% Dotted integration hints from current components
%% -------------------------
EAR -.->|"future_integration(text)"| GPT2_MAIN
EAR -.->|"future_integration(text)"| GPT_EXPERIMENTS
GPT2_MAIN -.->|"future_response_text"| MOUTH
GPT_EXPERIMENTS -.->|"future_response_text"| MOUTH
GPT2_MAIN -.->|"future_memory_io"| MEMSYS
GPT_EXPERIMENTS -.->|"future_memory_io"| MEMSYS

%% =========================
%% Click Events (mapped paths)
%% =========================
click GPTDIR "https://github.com/rizdas/lunagpt/tree/main/gpt/"
click BIGRAM "https://github.com/rizdas/lunagpt/blob/main/gpt/bigram.py"
click V2 "https://github.com/rizdas/lunagpt/blob/main/gpt/v2.py"
click V22 "https://github.com/rizdas/lunagpt/blob/main/gpt/v2.2_noDropout.py"
click V25 "https://github.com/rizdas/lunagpt/blob/main/gpt/v2.5.py"
click V3 "https://github.com/rizdas/lunagpt/blob/main/gpt/v3.py"
click GPT_CORPUS "https://github.com/rizdas/lunagpt/blob/main/gpt/input.txt"
click CUDA_CHECK "https://github.com/rizdas/lunagpt/blob/main/gpt/check.py"

click GPT2DIR "https://github.com/rizdas/lunagpt/tree/main/gpt2/"
click GPT2_MAIN "https://github.com/rizdas/lunagpt/blob/main/gpt2/train_gpt2.py"
click GPT2_ALT "https://github.com/rizdas/lunagpt/blob/main/gpt2/train2_gpt2.py"
click GPT2_NB "https://github.com/rizdas/lunagpt/blob/main/gpt2/(test)dummy.ipynb"

click HEADDR "https://github.com/rizdas/lunagpt/tree/main/head/"
click EAR "https://github.com/rizdas/lunagpt/blob/main/head/ear.py"
click MOUTH "https://github.com/rizdas/lunagpt/blob/main/head/mouth.py"

click MEMDIR "https://github.com/rizdas/lunagpt/tree/main/memory/"
click CACHE "https://github.com/rizdas/lunagpt/blob/main/memory/cache.txt"
click LEARN "https://github.com/rizdas/lunagpt/blob/main/memory/learning.txt"
click SAVED "https://github.com/rizdas/lunagpt/blob/main/memory/saved.txt"

click README "https://github.com/rizdas/lunagpt/blob/main/README.md"

%% =========================
%% Styles
%% =========================
classDef script fill:#1f6feb,stroke:#0b3d91,stroke-width:1.5px,color:#ffffff
classDef util fill:#2d8cff,stroke:#0b3d91,stroke-width:1.5px,color:#ffffff
classDef lib fill:#0ea5e9,stroke:#075985,stroke-width:1.2px,color:#ffffff
classDef storage fill:#f59e0b,stroke:#92400e,stroke-width:1.5px,color:#1f1300
classDef cloud fill:#6b7280,stroke:#374151,stroke-width:1.5px,color:#ffffff
classDef device fill:#111827,stroke:#374151,stroke-width:1.5px,color:#ffffff
classDef folder fill:#7c3aed,stroke:#4c1d95,stroke-width:1.5px,color:#ffffff
classDef doc fill:#22c55e,stroke:#166534,stroke-width:1.5px,color:#062b14
classDef note fill:#fde68a,stroke:#b45309,stroke-width:1.2px,color:#3b2f05
classDef group fill:#2563eb,stroke:#1e40af,stroke-width:2px,color:#ffffff
classDef planned fill:#94a3b8,stroke:#475569,stroke-width:1.5px,color:#0f172a,stroke-dasharray: 6 4
```
