# thedeepakreddy/pluto-llm architecture

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

- Interactive diagram: https://gitdiagram.com/thedeepakreddy/pluto-llm
- Repository: https://github.com/thedeepakreddy/pluto-llm

## Overview

Pluto is a from-scratch PyTorch language-model training system, extended with a synthetic-speech dataset and speech-capable model. The primary workflow prepares and cleans text, trains a byte-level tokenizer, builds token shards, trains or resumes a model, then generates and reports results. The speech workflow synthesizes and encodes aligned audio data, trains SpeechGPT, and evaluates or generates speech. README statements establish the documented stages; source-index references support several internal calls, but unsampled implementations are represented only at their known paths.

Main entry points: [`src/llm/cli.py`](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/cli.py) (CLI commands), [`src/llm/speech/build.py`](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/build.py) (Build speech set), [`src/llm/shards.py`](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/shards.py) (Token shards), [`src/llm/speech/generate.py`](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/generate.py) (Speech generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_textdata["Text data pipeline"]
  node_prepare["Prepare text data<br/>[prepare.py]"]
  node_bpe["BPE tokenizer<br/>[bpe.py]"]
  node_shards[("Token shards<br/>[shards.py]")]
end

subgraph group_textmodel["Text model lifecycle"]
  node_gpt["GPT model<br/>[gpt.py]"]
  node_train["Training loop<br/>[loop.py]"]
  node_generate["Text generation<br/>[generate.py]"]
  node_report["Evaluation reports<br/>[report.py]"]
end

subgraph group_speechdata["Speech data pipeline"]
  node_speechbuild["Build speech set<br/>[build.py]"]
  node_speechchunk["Chunk and align<br/>[chunk.py]"]
  node_speechstore[("Speech split store<br/>[store.py]")]
  node_speechdataset["Speech dataset<br/>[dataset.py]"]
  node_speechinterfaces["Speech interfaces<br/>[interfaces.py]"]
  node_adapters["Speech adapters<br/>[adapters.py]"]
end

subgraph group_speechmodel["Speech model lifecycle"]
  node_speechmodel["SpeechGPT<br/>[voice.py]"]
  node_speechtrain["Speech training<br/>[speech_loop.py]"]
  node_speechgen["Speech generation<br/>[generate.py]"]
  node_speecheval["Speech evaluation<br/>[evaluate.py]"]
  node_speechapp["Speech demo<br/>[app.py]"]
end

subgraph group_artifacts["Runs and provenance"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_config["Run config<br/>[config.py]"]
  node_checkpoint[("Checkpoints<br/>[checkpoint.py]")]
  node_manifest["Artifact manifests<br/>[manifest.py]"]
  node_hub["Run hub sync<br/>[hub.py]"]
end

node_user(("Engineer"))
node_external{{"Model services"}}

node_user -->|"runs commands"| node_cli
node_cli -->|"loads config"| node_config
node_cli -->|"invokes preparation"| node_prepare
node_prepare -->|"records dataset"| node_manifest
node_cli -->|"trains tokenizer"| node_bpe
node_cli -->|"builds shards"| node_shards
node_shards -->|"encodes text"| node_bpe
node_shards -->|"records provenance"| node_manifest
node_cli -->|"starts training"| node_train
node_train -->|"reads batches"| node_shards
node_train -->|"trains model"| node_gpt
node_train -->|"saves state"| node_checkpoint
node_cli -->|"resumes run"| node_checkpoint
node_cli -->|"generates text"| node_generate
node_cli -->|"creates reports"| node_report
node_report -->|"reads artifacts"| node_shards
node_report -->|"uses tokenizer"| node_bpe
node_cli -->|"pulls run"| node_hub
node_speechbuild -->|"reads cleaned text"| node_prepare
node_speechbuild -->|"chunks stories"| node_speechchunk
node_speechbuild -->|"creates speech tools"| node_speechinterfaces
node_speechinterfaces -->|"loads integrations"| node_adapters
node_adapters -.->|"uses TTS codec ASR"| node_external
node_speechbuild -->|"writes splits"| node_speechstore
node_speechdataset -->|"reads records"| node_speechstore
node_cli -->|"builds speech data"| node_speechbuild
node_speechtrain -->|"loads training data"| node_speechdataset
node_speechtrain -->|"trains model"| node_speechmodel
node_speechtrain -->|"evaluates samples"| node_speechgen
node_cli -->|"trains speech model"| node_speechtrain
node_cli -->|"speaks or continues"| node_speechgen
node_speechgen -->|"samples frames"| node_speechmodel
node_cli -->|"evaluates speech"| node_speecheval
node_speecheval -->|"generates test audio"| node_speechgen
node_speechapp -->|"serves generation"| node_speechgen
node_cli -->|"launches demo"| node_speechapp

click node_cli "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/cli.py"
click node_config "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/config.py"
click node_prepare "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/data/prepare.py"
click node_bpe "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/tokenizer/bpe.py"
click node_shards "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/shards.py"
click node_gpt "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/model/gpt.py"
click node_train "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/train/loop.py"
click node_checkpoint "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/train/checkpoint.py"
click node_generate "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/generate.py"
click node_report "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/report.py"
click node_manifest "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/manifest.py"
click node_hub "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/hub.py"
click node_speechbuild "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/build.py"
click node_speechchunk "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/chunk.py"
click node_speechstore "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/store.py"
click node_speechdataset "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/dataset.py"
click node_speechinterfaces "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/interfaces.py"
click node_adapters "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/adapters.py"
click node_speechmodel "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/model/voice.py"
click node_speechtrain "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/train/speech_loop.py"
click node_speechgen "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/generate.py"
click node_speecheval "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/evaluate.py"
click node_speechapp "https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/app.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_prepare,node_bpe,node_shards toneBlue
class node_gpt,node_train,node_generate,node_report toneAmber
class node_speechbuild,node_speechchunk,node_speechstore,node_speechdataset,node_speechinterfaces,node_adapters toneMint
class node_speechmodel,node_speechtrain,node_speechgen,node_speecheval,node_speechapp toneRose
class node_cli,node_config,node_checkpoint,node_manifest,node_hub,node_user,node_external toneIndigo
```

## Components

### Text data pipeline

- [Prepare text data](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/data/prepare.py): `src/llm/data/prepare.py`
- [BPE tokenizer](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/tokenizer/bpe.py): `src/llm/tokenizer/bpe.py`
- [Token shards](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/shards.py): `src/llm/shards.py`

### Text model lifecycle

- [GPT model](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/model/gpt.py): `src/llm/model/gpt.py`
- [Training loop](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/train/loop.py): `src/llm/train/loop.py`
- [Text generation](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/generate.py): `src/llm/generate.py`
- [Evaluation reports](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/report.py): `src/llm/report.py`

### Speech data pipeline

- [Build speech set](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/build.py): `src/llm/speech/build.py`
- [Chunk and align](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/chunk.py): `src/llm/speech/chunk.py`
- [Speech split store](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/store.py): `src/llm/speech/store.py`
- [Speech dataset](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/dataset.py): `src/llm/speech/dataset.py`
- [Speech interfaces](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/interfaces.py): `src/llm/speech/interfaces.py`
- [Speech adapters](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/adapters.py): `src/llm/speech/adapters.py`

### Speech model lifecycle

- [SpeechGPT](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/model/voice.py): `src/llm/model/voice.py`
- [Speech training](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/train/speech_loop.py): `src/llm/train/speech_loop.py`
- [Speech generation](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/generate.py): `src/llm/speech/generate.py`
- [Speech evaluation](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/evaluate.py): `src/llm/speech/evaluate.py`
- [Speech demo](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/speech/app.py): `src/llm/speech/app.py`

### Runs and provenance

- [CLI commands](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/cli.py): `src/llm/cli.py`
- [Run config](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/config.py): `src/llm/config.py`
- [Checkpoints](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/train/checkpoint.py): `src/llm/train/checkpoint.py`
- [Artifact manifests](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/manifest.py): `src/llm/manifest.py`
- [Run hub sync](https://github.com/thedeepakreddy/pluto-llm/blob/main/src/llm/hub.py): `src/llm/hub.py`

### Other components

- **Engineer**
- **Model services**

## Connections

- Engineer → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Run config: loads config (evidence: `src/llm/cli.py`)
- CLI commands → Prepare text data: invokes preparation (evidence: `src/llm/cli.py`)
- Prepare text data → Artifact manifests: records dataset (evidence: `src/llm/data/prepare.py`)
- CLI commands → BPE tokenizer: trains tokenizer (evidence: `src/llm/cli.py`)
- CLI commands → Token shards: builds shards (evidence: `src/llm/cli.py`)
- Token shards → BPE tokenizer: encodes text (evidence: `src/llm/shards.py`)
- Token shards → Artifact manifests: records provenance (evidence: `src/llm/shards.py`)
- CLI commands → Training loop: starts training (evidence: `src/llm/cli.py`)
- Training loop → Token shards: reads batches (evidence: `src/llm/train/loop.py`)
- Training loop → GPT model: trains model (evidence: `src/llm/train/loop.py`)
- Training loop → Checkpoints: saves state (evidence: `src/llm/train/loop.py`)
- CLI commands → Checkpoints: resumes run (evidence: `src/llm/cli.py`)
- CLI commands → Text generation: generates text (evidence: `src/llm/cli.py`)
- CLI commands → Evaluation reports: creates reports (evidence: `src/llm/cli.py`)
- Evaluation reports → Token shards: reads artifacts (evidence: `src/llm/report.py`)
- Evaluation reports → BPE tokenizer: uses tokenizer (evidence: `src/llm/report.py`)
- CLI commands → Run hub sync: pulls run (evidence: `README.md`)
- Build speech set → Prepare text data: reads cleaned text (evidence: `src/llm/speech/build.py`)
- Build speech set → Chunk and align: chunks stories (evidence: `src/llm/speech/build.py`)
- Build speech set → Speech interfaces: creates speech tools (evidence: `src/llm/speech/build.py`)
- Speech interfaces → Speech adapters: loads integrations (evidence: `src/llm/speech/interfaces.py`)
- Speech adapters → Model services: uses TTS codec ASR (evidence: `README.md`)
- Build speech set → Speech split store: writes splits (evidence: `src/llm/speech/build.py`)
- Speech dataset → Speech split store: reads records (evidence: `src/llm/speech/dataset.py`)
- CLI commands → Build speech set: builds speech data (evidence: `src/llm/cli.py`)
- Speech training → Speech dataset: loads training data (evidence: `src/llm/train/speech_loop.py`)
- Speech training → SpeechGPT: trains model (evidence: `src/llm/train/speech_loop.py`)
- Speech training → Speech generation: evaluates samples (evidence: `src/llm/train/speech_loop.py`)
- CLI commands → Speech training: trains speech model (evidence: `README.md`)
- CLI commands → Speech generation: speaks or continues (evidence: `src/llm/cli.py`)
- Speech generation → SpeechGPT: samples frames (evidence: `src/llm/speech/generate.py`)
- CLI commands → Speech evaluation: evaluates speech (evidence: `src/llm/cli.py`)
- Speech evaluation → Speech generation: generates test audio (evidence: `src/llm/speech/evaluate.py`)
- Speech demo → Speech generation: serves generation (evidence: `src/llm/speech/app.py`)
- CLI commands → Speech demo: launches demo (evidence: `README.md`)