# dilht/customersupportvoiceagent architecture

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

- Interactive diagram: https://gitdiagram.com/dilht/customersupportvoiceagent
- Repository: https://github.com/dilht/customersupportvoiceagent

## Overview

This is a LiveKit Python voice assistant starter, shown here as a member speaking with a financial-services assistant and receiving spoken answers or a recorded complaint. LiveKit starts and connects the session; the assistant uses configured language and speech services, searches company Markdown for factual answers, and can validate and record complaints in SQLite. The README also documents expressive speech, turn detection, noise cancellation, broad model-provider support, and observability. Those integrations are represented from documentation where source wiring was not shown; unsampled internals are not inferred.

Main entry points: [`src/agent.py`](https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py) (Voice pipeline), [`src/complaints.py`](https://github.com/dilht/customersupportvoiceagent/blob/main/src/complaints.py) (Complaint store), [`src/knowledge.py`](https://github.com/dilht/customersupportvoiceagent/blob/main/src/knowledge.py) (Chunk loading), [`company_knowledge`](https://github.com/dilht/customersupportvoiceagent/tree/main/company_knowledge) (Knowledge documents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Voice runtime"]
  node_livekit["LiveKit session"]
  node_agent_entry["Session entry<br/>[agent.py]"]
  node_voice_pipeline["Voice pipeline<br/>[agent.py]"]
  node_turn_detector["Turn detector<br/>[agent.py]"]
  node_noise_cancel["Noise cancellation<br/>[agent.py]"]
  node_llm["Language model<br/>[agent.py]"]
  node_speech_models["Speech models<br/>[agent.py]"]
  node_observability["Session insights"]
end

subgraph group_assistant["Assistant behavior"]
  node_assistant_logic["Assistant tools<br/>[agent.py]"]
end

subgraph group_knowledge["Company knowledge"]
  node_knowledge_tool["Knowledge search tool<br/>[agent.py]"]
  node_knowledge_docs["Knowledge documents"]
  node_chunk_loader["Chunk loading<br/>[knowledge.py]"]
  node_keyword_search["Keyword search<br/>[knowledge.py]"]
end

subgraph group_complaints["Complaint handling"]
  node_complaint_tool["Complaint intake tool<br/>[agent.py]"]
  node_complaint_validation["Complaint validation<br/>[complaints.py]"]
  node_complaint_routing["Complaint routing<br/>[complaints.py]"]
  node_complaint_store["Complaint store<br/>[complaints.py]"]
  node_sqlite[("SQLite complaints<br/>[complaints.py]")]
end

node_member(("Member"))

node_member -->|"speaks to"| node_livekit
node_livekit -->|"starts session"| node_agent_entry
node_agent_entry -->|"starts"| node_voice_pipeline
node_agent_entry -->|"connects room"| node_livekit
node_voice_pipeline -->|"runs agent"| node_assistant_logic
node_voice_pipeline -.->|"uses"| node_turn_detector
node_voice_pipeline -->|"enhances audio"| node_noise_cancel
node_voice_pipeline -->|"uses"| node_llm
node_voice_pipeline -.->|"uses"| node_speech_models
node_voice_pipeline -.->|"reports insights"| node_observability
node_assistant_logic -->|"exposes"| node_knowledge_tool
node_assistant_logic -->|"exposes"| node_complaint_tool
node_knowledge_tool -->|"searches with"| node_chunk_loader
node_knowledge_tool -->|"queries"| node_keyword_search
node_chunk_loader -->|"loads Markdown"| node_knowledge_docs
node_keyword_search -->|"matches chunks"| node_knowledge_docs
node_complaint_tool -->|"validates"| node_complaint_validation
node_complaint_tool -->|"saves complaint"| node_complaint_store
node_complaint_store -->|"routes category"| node_complaint_routing
node_complaint_store -->|"writes and counts"| node_sqlite

click node_agent_entry "https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py"
click node_voice_pipeline "https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py"
click node_turn_detector "https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py"
click node_noise_cancel "https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py"
click node_llm "https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py"
click node_speech_models "https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py"
click node_assistant_logic "https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py"
click node_knowledge_tool "https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py"
click node_knowledge_docs "https://github.com/dilht/customersupportvoiceagent/tree/main/company_knowledge"
click node_chunk_loader "https://github.com/dilht/customersupportvoiceagent/blob/main/src/knowledge.py"
click node_keyword_search "https://github.com/dilht/customersupportvoiceagent/blob/main/src/knowledge.py"
click node_complaint_tool "https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py"
click node_complaint_validation "https://github.com/dilht/customersupportvoiceagent/blob/main/src/complaints.py"
click node_complaint_routing "https://github.com/dilht/customersupportvoiceagent/blob/main/src/complaints.py"
click node_complaint_store "https://github.com/dilht/customersupportvoiceagent/blob/main/src/complaints.py"
click node_sqlite "https://github.com/dilht/customersupportvoiceagent/blob/main/src/complaints.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_livekit,node_agent_entry,node_voice_pipeline,node_turn_detector,node_noise_cancel,node_llm,node_speech_models,node_observability toneBlue
class node_assistant_logic toneAmber
class node_knowledge_tool,node_knowledge_docs,node_chunk_loader,node_keyword_search toneMint
class node_complaint_tool,node_complaint_validation,node_complaint_routing,node_complaint_store,node_sqlite toneRose
class node_member toneIndigo
```

## Components

### Voice runtime

- **LiveKit session**
- [Session entry](https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py): `src/agent.py`
- [Voice pipeline](https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py): `src/agent.py`
- [Turn detector](https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py): `src/agent.py`
- [Noise cancellation](https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py): `src/agent.py`
- [Language model](https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py): `src/agent.py`
- [Speech models](https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py): `src/agent.py`
- **Session insights**

### Assistant behavior

- [Assistant tools](https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py): `src/agent.py`

### Company knowledge

- [Knowledge search tool](https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py): `src/agent.py`
- [Knowledge documents](https://github.com/dilht/customersupportvoiceagent/tree/main/company_knowledge): `company_knowledge`
- [Chunk loading](https://github.com/dilht/customersupportvoiceagent/blob/main/src/knowledge.py): `src/knowledge.py`
- [Keyword search](https://github.com/dilht/customersupportvoiceagent/blob/main/src/knowledge.py): `src/knowledge.py`

### Complaint handling

- [Complaint intake tool](https://github.com/dilht/customersupportvoiceagent/blob/main/src/agent.py): `src/agent.py`
- [Complaint validation](https://github.com/dilht/customersupportvoiceagent/blob/main/src/complaints.py): `src/complaints.py`
- [Complaint routing](https://github.com/dilht/customersupportvoiceagent/blob/main/src/complaints.py): `src/complaints.py`
- [Complaint store](https://github.com/dilht/customersupportvoiceagent/blob/main/src/complaints.py): `src/complaints.py`
- [SQLite complaints](https://github.com/dilht/customersupportvoiceagent/blob/main/src/complaints.py): `src/complaints.py`

### Other components

- **Member**

## Connections

- Member → LiveKit session: speaks to (evidence: `README.md`)
- LiveKit session → Session entry: starts session (evidence: `src/agent.py`)
- Session entry → Voice pipeline: starts (evidence: `src/agent.py`)
- Session entry → LiveKit session: connects room (evidence: `src/agent.py`)
- Voice pipeline → Assistant tools: runs agent (evidence: `src/agent.py`)
- Voice pipeline → Turn detector: uses (evidence: `README.md`)
- Voice pipeline → Noise cancellation: enhances audio (evidence: `src/agent.py`)
- Voice pipeline → Language model: uses (evidence: `src/agent.py`)
- Voice pipeline → Speech models: uses (evidence: `README.md`)
- Voice pipeline → Session insights: reports insights (evidence: `README.md`)
- Assistant tools → Knowledge search tool: exposes (evidence: `src/agent.py`)
- Assistant tools → Complaint intake tool: exposes (evidence: `src/agent.py`)
- Knowledge search tool → Chunk loading: searches with (evidence: `src/agent.py`)
- Knowledge search tool → Keyword search: queries (evidence: `src/agent.py`)
- Chunk loading → Knowledge documents: loads Markdown (evidence: `src/knowledge.py`)
- Keyword search → Knowledge documents: matches chunks (evidence: `src/knowledge.py`)
- Complaint intake tool → Complaint validation: validates (evidence: `src/agent.py`)
- Complaint intake tool → Complaint store: saves complaint (evidence: `src/agent.py`)
- Complaint store → Complaint routing: routes category (evidence: `src/complaints.py`)
- Complaint store → SQLite complaints: writes and counts (evidence: `src/complaints.py`)
