# rhasspy/gruut architecture

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

- Interactive diagram: https://gitdiagram.com/rhasspy/gruut
- Repository: https://github.com/rhasspy/gruut

## Overview

Gruut turns plain text or SSML into language-aware sentences and word records, including normalized/verbalized text, POS tags where available, and IPA pronunciations. Its central workflow is exposed through the Python API and CLI; language settings and installed language packs provide locale-specific resources. The README also documents number/date/currency/time expansion and an optional eSpeak pronunciation mode. Relationships between the main processing stages are documented at a high level, but the excerpts do not show the complete runtime call chain, so uncertain internal links are omitted.

Main entry points: [`gruut/text_processor.py`](https://github.com/rhasspy/gruut/blob/master/gruut/text_processor.py) (Text Processor), [`gruut/lang.py`](https://github.com/rhasspy/gruut/blob/master/gruut/lang.py) (Language Settings), [`gruut/__init__.py`](https://github.com/rhasspy/gruut/blob/master/gruut/__init__.py) (Python API), [`gruut/__main__.py`](https://github.com/rhasspy/gruut/blob/master/gruut/__main__.py) (Command Line)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["User Interfaces"]
  node_api["Python API<br/>[__init__.py]"]
  node_cli["Command Line<br/>[__main__.py]"]
end

subgraph group_pipeline["Text Processing"]
  node_processor["Text Processor<br/>[text_processor.py]"]
  node_types["Text Data Types<br/>[const.py]"]
end

subgraph group_linguistics["Language and Pronunciation"]
  node_settings["Language Settings<br/>[lang.py]"]
  node_phonemizer["Lexicon Lookup<br/>[phonemize.py]"]
  node_g2p["Grapheme-to-Phoneme<br/>[g2p.py]"]
  node_pos["POS Tagger<br/>[pos.py]"]
  node_espeak["eSpeak Mode<br/>[espeak_word.py]"]
end

subgraph group_models["Language Resources"]
  node_resources["Resource Discovery<br/>[utils.py]"]
  node_languagepacks["Language Packs<br/>[__init__.py]"]
end

node_user(("Text or SSML"))
node_result["Sentence and Word Records"]
node_espeakservice["eSpeak NG"]

node_user -->|"submits text"| node_api
node_user -->|"submits text"| node_cli
node_api -.->|"processes text"| node_processor
node_cli -.->|"processes text"| node_processor
node_processor -->|"produces records"| node_result
node_processor -.->|"uses language settings"| node_settings
node_processor -.->|"gets pronunciations"| node_phonemizer
node_processor -.->|"gets POS tags"| node_pos
node_settings -.->|"discovers resources"| node_resources
node_resources -->|"searches installed packs"| node_languagepacks
node_settings -.->|"loads G2P model"| node_g2p
node_settings -.->|"loads POS model"| node_pos
node_phonemizer -->|"supplies phonemes"| node_result
node_espeak -->|"calls phonemizer"| node_espeakservice
node_user -->|"selects mode"| node_espeak

click node_api "https://github.com/rhasspy/gruut/blob/master/gruut/__init__.py"
click node_cli "https://github.com/rhasspy/gruut/blob/master/gruut/__main__.py"
click node_processor "https://github.com/rhasspy/gruut/blob/master/gruut/text_processor.py"
click node_types "https://github.com/rhasspy/gruut/blob/master/gruut/const.py"
click node_settings "https://github.com/rhasspy/gruut/blob/master/gruut/lang.py"
click node_phonemizer "https://github.com/rhasspy/gruut/blob/master/gruut/phonemize.py"
click node_g2p "https://github.com/rhasspy/gruut/blob/master/gruut/g2p.py"
click node_pos "https://github.com/rhasspy/gruut/blob/master/gruut/pos.py"
click node_resources "https://github.com/rhasspy/gruut/blob/master/gruut/utils.py"
click node_languagepacks "https://github.com/rhasspy/gruut/blob/master/gruut-lang-en/gruut_lang_en/__init__.py"
click node_espeak "https://github.com/rhasspy/gruut/blob/master/bin/espeak_word.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_api,node_cli toneBlue
class node_processor,node_types toneAmber
class node_settings,node_phonemizer,node_g2p,node_pos,node_espeak toneMint
class node_resources,node_languagepacks toneRose
class node_user,node_result,node_espeakservice toneIndigo
```

## Components

### User Interfaces

- [Python API](https://github.com/rhasspy/gruut/blob/master/gruut/__init__.py): `gruut/__init__.py`
- [Command Line](https://github.com/rhasspy/gruut/blob/master/gruut/__main__.py): `gruut/__main__.py`

### Text Processing

- [Text Processor](https://github.com/rhasspy/gruut/blob/master/gruut/text_processor.py): `gruut/text_processor.py`
- [Text Data Types](https://github.com/rhasspy/gruut/blob/master/gruut/const.py): `gruut/const.py`

### Language and Pronunciation

- [Language Settings](https://github.com/rhasspy/gruut/blob/master/gruut/lang.py): `gruut/lang.py`
- [Lexicon Lookup](https://github.com/rhasspy/gruut/blob/master/gruut/phonemize.py): `gruut/phonemize.py`
- [Grapheme-to-Phoneme](https://github.com/rhasspy/gruut/blob/master/gruut/g2p.py): `gruut/g2p.py`
- [POS Tagger](https://github.com/rhasspy/gruut/blob/master/gruut/pos.py): `gruut/pos.py`
- [eSpeak Mode](https://github.com/rhasspy/gruut/blob/master/bin/espeak_word.py): `bin/espeak_word.py`

### Language Resources

- [Resource Discovery](https://github.com/rhasspy/gruut/blob/master/gruut/utils.py): `gruut/utils.py`
- [Language Packs](https://github.com/rhasspy/gruut/blob/master/gruut-lang-en/gruut_lang_en/__init__.py): `gruut-lang-en/gruut_lang_en/__init__.py`

### Other components

- **Text or SSML**
- **Sentence and Word Records**
- **eSpeak NG**

## Connections

- Text or SSML → Python API: submits text
- Text or SSML → Command Line: submits text
- Python API → Text Processor: processes text
- Command Line → Text Processor: processes text
- Text Processor → Sentence and Word Records: produces records
- Text Processor → Language Settings: uses language settings (evidence: `gruut/text_processor.py`)
- Text Processor → Lexicon Lookup: gets pronunciations
- Text Processor → POS Tagger: gets POS tags
- Language Settings → Resource Discovery: discovers resources (evidence: `gruut/lang.py`)
- Resource Discovery → Language Packs: searches installed packs (evidence: `gruut/utils.py`)
- Language Settings → Grapheme-to-Phoneme: loads G2P model (evidence: `gruut/lang.py`)
- Language Settings → POS Tagger: loads POS model (evidence: `gruut/lang.py`)
- Lexicon Lookup → Sentence and Word Records: supplies phonemes
- eSpeak Mode → eSpeak NG: calls phonemizer (evidence: `bin/espeak_word.py`)
- Text or SSML → eSpeak Mode: selects mode