# tarun7r/vocal-agent architecture

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

- Interactive diagram: https://gitdiagram.com/tarun7r/vocal-agent
- Repository: https://github.com/tarun7r/vocal-agent

## Overview

##### Project type and purpose
- This is a real-time, full-stack (audio-to-audio) voice assistant written in Python.
- It captures audio, runs speech-to-text (STT), invokes an LLM agent (with tool calls), and then synthesizes speech (TTS).
- Key features: Whisper + Silero VAD for STT, Agno agent framework with Llama 3.1 via Ollama, Kokoro ONNX for TTS, plus web-search tool integrations.

##### File structure
- Top-level scripts:
- main.py – orchestrator of the audio pipeline
- agent_client.py – encapsulates LLM tool calls and reasoning
- vocal_agent_mac.sh – setup/install script for macOS
- Models in the root (kokoro-v1.0.onnx, voices-v1.0.bin) indicate TTS assets loaded at runtime
- requirements.txt lists Python dependencies; .gitignore, LICENSE, README.md are ancillary

##### README for additional insights
- Describes pipeline stages, configuration constants in main.py (sample rate, phoneme length, speed, voice profile)
- Emphasizes real-time, low-latency audio processing and extensible tool system
- Outlines external dependencies (Ollama service, System TTS engine espeak-ng)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Orchestrator Layer"
        direction TB
        AC["Audio Capture & Preprocessing"]:::script
        VAD["Silero VAD"]:::script
        STT["Whisper STT"]:::localModel
        TTS["Kokoro ONNX TTS"]:::localModel
        OUT["Audio Playback"]:::script
    end

    subgraph "Agent Layer"
        direction TB
        AG["Agno Agent Client"]:::agent
        OLL["Ollama LLM Service\n(Llama 3.1:8b)"]:::agent
    end

    subgraph "External Services"
        direction TB
        GS["Google Search"]:::external
        WP["Wikipedia"]:::external
        AR["ArXiv"]:::external
    end

    subgraph "Project Docs & Setup"
        direction TB
        README["Project Documentation & Instructions"]:::script
        SETUP["Environment Setup Script (macOS)"]:::script
        REQ["Python Dependencies"]:::script
        GITIGNORE["Version Control Exclusions"]:::script
        LIC["License Information"]:::script
    end

    AC --> VAD
    VAD --> STT
    STT --> AG
    AG --> OLL
    OLL --> AG
    AG --> TTS
    TTS --> OUT

    AG --> GS
    AG --> WP
    AG --> AR

    click AC "https://github.com/tarun7r/vocal-agent/blob/main/main.py"
    click VAD "https://github.com/tarun7r/vocal-agent/blob/main/main.py"
    click STT "https://github.com/tarun7r/vocal-agent/blob/main/main.py"
    click TTS "https://github.com/tarun7r/vocal-agent/blob/main/main.py"
    click OUT "https://github.com/tarun7r/vocal-agent/blob/main/main.py"
    click AG "https://github.com/tarun7r/vocal-agent/blob/main/agent_client.py"
    click GS "https://github.com/tarun7r/vocal-agent/blob/main/agent_client.py"
    click WP "https://github.com/tarun7r/vocal-agent/blob/main/agent_client.py"
    click AR "https://github.com/tarun7r/vocal-agent/blob/main/agent_client.py"
    click OLL "https://github.com/tarun7r/vocal-agent/blob/main/README.md"
    click README "https://github.com/tarun7r/vocal-agent/blob/main/README.md"
    click SETUP "https://github.com/tarun7r/vocal-agent/blob/main/vocal_agent_mac.sh"
    click REQ "https://github.com/tarun7r/vocal-agent/blob/main/requirements.txt"
    click GITIGNORE "https://github.com/tarun7r/vocal-agent/blob/main/.gitignore"
    click LIC "https://github.com/tarun7r/vocal-agent/tree/main/LICENSE"

    classDef localModel fill:#ADD8E6,stroke:#000
    classDef agent fill:#90EE90,stroke:#000
    classDef external fill:#D3D3D3,stroke:#000
    classDef script fill:#FFA500,stroke:#000
```
