# carsonmulligan/local-voice-agent-language-teacher architecture

> Architecture diagram of the GitHub repository carsonmulligan/local-voice-agent-language-teacher, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/carsonmulligan/local-voice-agent-language-teacher
- Repository: https://github.com/carsonmulligan/local-voice-agent-language-teacher

## Overview

##### Project type and purpose
- This is a local, command-line language assistant tool. It captures audio, transcribes speech, sends text to a locally-hosted AI model, and returns spoken responses.
- Key use-cases: Spanish (primary) and Chinese assistants via separate module folders.

##### File structure
- Root script: bertosito_chat.py (orchestrator)
- Language folders:
· spanish/… various CLI implementations and broom_closet experiments
· chinese/… guanguan_v1.py
- Utility folders:
· voices/voiceCheck.py (audio device test)
· viz/… scripts for publishing docs
- Config and metadata: requirements.txt, .github/workflows, README.md

##### README insights
- Dependencies: whisper (openAI), edge-tts, ollama serving llama2-uncensored
- Runtime flow: audio recording → transcription → AI model call → TTS → playback
- Local services: ollama is a long-running local server on localhost:11434

A. Client Orchestrator (Python script bertosito_chat.py)
B. Audio Input Module (mic capture via Python audio library)
C. Whisper Transcription Module (Python interface to whisper)
D. AI Model Service (Ollama server hosting llama2-uncensored)
E. Text-to-Speech Module (edge-tts library)
F. Audio Playback Module (system audio output)
G. Language-specific extensions (spanish/, chinese/ folders)

##### Relationships & interactions
1. Microphone → Audio Input Module
2. Audio Input Module → Whisper Transcription Module → Transcribed Text
3. Transcribed Text → HTTP request → Ollama AI Model Service → AI-generated Text
4. AI-generated Text → Text-to-Speech Module → Audio File
5. Audio File → Audio Playback Module → Speaker
6. Loop back for next user utterance
- That the orchestrator script ties these steps together.

##### Architectural patterns & design principles
- Pipeline pattern: a linear flow of data through discrete processing stages
- Separation of concerns: each module handles one responsibility (capture, ASR, LLM, TTS, playback)
- Local microservice (Ollama) accessed via REST API
- Modular code: language-specific submodules live under their own directories

##### Technologies, frameworks, and libraries
- Python 3.x as the host language
- whisper (OpenAI) for ASR
- ollama server hosting llama-based models
- edge-tts for text-to-speech
- pydub or similar for audio I/O (implicit in requirements)
- shell scripts for setup in spanish/broom_closet (setup.sh)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core orchestrator
    Orchestrator["Client Orchestrator<br/>(bertosito_chat.py)"]:::core

    %% Main Pipeline
    subgraph "Main Audio→ASR→LLM→TTS Pipeline"
        direction TB
        Mic["Microphone"]:::io
        AudioIn["Audio Input Module<br/>(PyAudio)"]:::proc
        Whisper["Whisper ASR Module"]:::proc
        LLMService["Ollama LLM Service<br/>localhost:11434"]:::svc
        TTS["Text-to-Speech Module<br/>(edge-tts)"]:::proc
        Playback["Audio Playback Module<br/>(System Audio)"]:::io
    end

    %% Extensions
    subgraph "Language Extensions"
        direction TB
        SpanishExt["Spanish Module<br/>(spanish/)"]:::util
        WhisperSpan["Whisper Spanish Script<br/>(whisper_spanish.py)"]:::proc
        SpanishShell["Spanish Shell Wrapper<br/>(whisper_spanish.sh)"]:::proc
        ChineseExt["Chinese Module<br/>(guanguan_v1.py)"]:::util
    end

    %% Utilities
    subgraph Utilities
        direction TB
        VoiceCheck["Audio Device Test<br/>(voiceCheck.py)"]:::util
        Viz["Documentation & Visualization<br/>(viz/)"]:::util
        CI["CI/CD Workflows<br/>(.github/workflows/)"]:::util
    end

    %% Configuration & Metadata
    subgraph "Config & Metadata"
        direction TB
        Req["requirements.txt"]:::util
        Readme["README.md"]:::util
        License["LICENSE"]:::util
    end

    %% Generated Artifacts
    subgraph Artifacts
        direction TB
        WAV["response.wav"]:::data
        MP3["response.mp3"]:::data
    end

    %% Pipeline Connections
    Orchestrator --> Mic
    Mic --> AudioIn
    AudioIn --> Whisper
    Whisper --> LLMService
    LLMService --> TTS
    TTS --> Playback
    Playback --> Orchestrator

    %% Orchestrator Connections
    Orchestrator --> SpanishExt
    SpanishExt --> WhisperSpan
    SpanishExt --> SpanishShell
    Orchestrator --> ChineseExt
    Orchestrator --> VoiceCheck
    Orchestrator --> Viz
    Orchestrator --> CI
    Orchestrator --> Req
    Orchestrator --> Readme
    Orchestrator --> License

    %% Artifacts flow
    TTS --> WAV
    TTS --> MP3

    %% Click Events
    click Orchestrator "https://github.com/carsonmulligan/local-voice-agent-language-teacher/blob/main/bertosito_chat.py"
    click VoiceCheck "https://github.com/carsonmulligan/local-voice-agent-language-teacher/blob/main/voices/voiceCheck.py"
    click WhisperSpan "https://github.com/carsonmulligan/local-voice-agent-language-teacher/blob/main/spanish/whisper_spanish.py"
    click SpanishShell "https://github.com/carsonmulligan/local-voice-agent-language-teacher/blob/main/spanish/whisper_spanish.sh"
    click SpanishExt "https://github.com/carsonmulligan/local-voice-agent-language-teacher/tree/main/spanish/"
    click ChineseExt "https://github.com/carsonmulligan/local-voice-agent-language-teacher/blob/main/chinese/guanguan_v1.py"
    click Viz "https://github.com/carsonmulligan/local-voice-agent-language-teacher/tree/main/viz/"
    click CI "https://github.com/carsonmulligan/local-voice-agent-language-teacher/tree/main/.github/workflows/"
    click Req "https://github.com/carsonmulligan/local-voice-agent-language-teacher/blob/main/requirements.txt"
    click Readme "https://github.com/carsonmulligan/local-voice-agent-language-teacher/blob/main/README.md"
    click License "https://github.com/carsonmulligan/local-voice-agent-language-teacher/tree/main/LICENSE"

    %% Styles
    classDef io fill:#a2f5a2,stroke:#333,stroke-width:1px
    classDef proc fill:#a2d0f5,stroke:#333,stroke-width:1px
    classDef svc fill:#f5c89f,stroke:#333,stroke-width:1px
    classDef util fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef core fill:#e0b3ff,stroke:#333,stroke-width:1px
    classDef data fill:#fff2a8,stroke:#333,stroke-width:1px
```
