How rizdas/lunagpt works
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