# eulemitkeule/speaker-recognition architecture

> Architecture diagram of the GitHub repository eulemitkeule/speaker-recognition, 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/eulemitkeule/speaker-recognition
- Repository: https://github.com/eulemitkeule/speaker-recognition

## Overview

This repository provides speaker identification as a service, a Python client, a Home Assistant integration, and an addon deployment. The main workflow trains on voice samples, caches speaker embeddings, and recognizes speakers from incoming audio. Home Assistant can send voice samples and recognition audio to the backend; its STT entity also shares recent recognition results with the conversation agent to enrich user context. The addon is documented as a deployment option, but its runtime wiring was not sampled.

Main entry points: [`speaker_recognition/api.py`](https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/api.py) (REST API), [`speaker_recognition/__main__.py`](https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/__main__.py) (Service CLI), [`custom_components/speaker_recognition/stt.py`](https://github.com/eulemitkeule/speaker-recognition/blob/master/custom_components/speaker_recognition/stt.py) (STT entity), [`speaker_recognition/client.py`](https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/client.py) (Python client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["Recognition service"]
  node_service_entry["Service CLI<br/>[__main__.py]"]
  node_api["REST API<br/>[api.py]"]
  node_models["Request models<br/>[models.py]"]
  node_recognizer["Speaker recognizer<br/>[recognizer.py]"]
  node_embedding_files[("Embedding files<br/>[recognizer.py]")]
  node_service_config["Service settings<br/>[const.py]"]
  node_logging["Logging setup<br/>[logging_config.py]"]
end

subgraph group_client["Python client"]
  node_python_client["Python client<br/>[client.py]"]
end

subgraph group_ha["Home Assistant integration"]
  node_config_flow["Integration setup<br/>[config_flow.py]"]
  node_ha_runtime["Integration lifecycle<br/>[__init__.py]"]
  node_ha_settings["Integration settings<br/>[const.py]"]
  node_ha_recognition["HA recognition client<br/>[recognition.py]"]
  node_stt["STT entity<br/>[stt.py]"]
  node_conversation["Conversation agent<br/>[conversation.py]"]
end

subgraph group_deploy["Home Assistant addon"]
  node_addon["Addon runtime<br/>[run]"]
end

node_service_user(("API consumer"))
node_ha_user(("Home Assistant user"))
node_source_stt["Source STT platform"]
node_source_agent["Source conversation agent"]
node_ha_events["HA event and state data"]

node_service_user -->|"sends API requests"| node_api
node_service_entry -->|"serves"| node_api
node_service_entry -->|"configures"| node_logging
node_service_entry -->|"sets"| node_service_config
node_api -->|"uses schemas"| node_models
node_api -->|"dispatches training and recognition"| node_recognizer
node_recognizer -->|"accepts and returns"| node_models
node_recognizer -->|"reads and writes"| node_embedding_files
node_service_user -->|"calls"| node_python_client
node_python_client -->|"sends HTTP requests"| node_api
node_python_client -->|"serializes and parses"| node_models
node_ha_user -->|"configures"| node_config_flow
node_config_flow -->|"uses settings"| node_ha_settings
node_ha_runtime -->|"uses settings"| node_ha_settings
node_ha_runtime -->|"sets up"| node_ha_recognition
node_ha_user -->|"provides voice samples"| node_ha_runtime
node_ha_recognition -->|"calls backend client"| node_python_client
node_ha_recognition -->|"trains and recognizes via HTTP"| node_api
node_stt -->|"recognizes buffered audio"| node_ha_recognition
node_stt -->|"forwards audio stream"| node_source_stt
node_stt -->|"fires event and stores result"| node_ha_events
node_conversation -->|"reads recent result"| node_ha_events
node_conversation -->|"forwards enriched input"| node_source_agent
node_ha_user -->|"uses speech-to-text"| node_stt
node_ha_user -->|"uses voice commands"| node_conversation
node_addon -.->|"launches service"| node_service_entry

click node_service_entry "https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/__main__.py"
click node_api "https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/api.py"
click node_models "https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/models.py"
click node_recognizer "https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/recognizer.py"
click node_embedding_files "https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/recognizer.py"
click node_service_config "https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/const.py"
click node_logging "https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/logging_config.py"
click node_python_client "https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/client.py"
click node_config_flow "https://github.com/eulemitkeule/speaker-recognition/blob/master/custom_components/speaker_recognition/config_flow.py"
click node_ha_runtime "https://github.com/eulemitkeule/speaker-recognition/blob/master/custom_components/speaker_recognition/__init__.py"
click node_ha_settings "https://github.com/eulemitkeule/speaker-recognition/blob/master/custom_components/speaker_recognition/const.py"
click node_ha_recognition "https://github.com/eulemitkeule/speaker-recognition/blob/master/custom_components/speaker_recognition/recognition.py"
click node_stt "https://github.com/eulemitkeule/speaker-recognition/blob/master/custom_components/speaker_recognition/stt.py"
click node_conversation "https://github.com/eulemitkeule/speaker-recognition/blob/master/custom_components/speaker_recognition/conversation.py"
click node_addon "https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition_addon/rootfs/etc/s6-overlay/s6-rc.d/speaker-recognition/run"

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_service_entry,node_api,node_models,node_recognizer,node_embedding_files,node_service_config,node_logging,node_ha_user toneBlue
class node_python_client toneAmber
class node_config_flow,node_ha_runtime,node_ha_settings,node_ha_recognition,node_stt,node_conversation,node_service_user toneMint
class node_addon toneRose
class node_source_stt,node_source_agent,node_ha_events toneIndigo
```

## Components

### Recognition service

- [Service CLI](https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/__main__.py): `speaker_recognition/__main__.py`
- [REST API](https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/api.py): `speaker_recognition/api.py`
- [Request models](https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/models.py): `speaker_recognition/models.py`
- [Speaker recognizer](https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/recognizer.py): `speaker_recognition/recognizer.py`
- [Embedding files](https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/recognizer.py): `speaker_recognition/recognizer.py`
- [Service settings](https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/const.py): `speaker_recognition/const.py`
- [Logging setup](https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/logging_config.py): `speaker_recognition/logging_config.py`

### Python client

- [Python client](https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition/client.py): `speaker_recognition/client.py`

### Home Assistant integration

- [Integration setup](https://github.com/eulemitkeule/speaker-recognition/blob/master/custom_components/speaker_recognition/config_flow.py): `custom_components/speaker_recognition/config_flow.py`
- [Integration lifecycle](https://github.com/eulemitkeule/speaker-recognition/blob/master/custom_components/speaker_recognition/__init__.py): `custom_components/speaker_recognition/__init__.py`
- [Integration settings](https://github.com/eulemitkeule/speaker-recognition/blob/master/custom_components/speaker_recognition/const.py): `custom_components/speaker_recognition/const.py`
- [HA recognition client](https://github.com/eulemitkeule/speaker-recognition/blob/master/custom_components/speaker_recognition/recognition.py): `custom_components/speaker_recognition/recognition.py`
- [STT entity](https://github.com/eulemitkeule/speaker-recognition/blob/master/custom_components/speaker_recognition/stt.py): `custom_components/speaker_recognition/stt.py`
- [Conversation agent](https://github.com/eulemitkeule/speaker-recognition/blob/master/custom_components/speaker_recognition/conversation.py): `custom_components/speaker_recognition/conversation.py`

### Home Assistant addon

- [Addon runtime](https://github.com/eulemitkeule/speaker-recognition/blob/master/speaker_recognition_addon/rootfs/etc/s6-overlay/s6-rc.d/speaker-recognition/run): `speaker_recognition_addon/rootfs/etc/s6-overlay/s6-rc.d/speaker-recognition/run`

### Other components

- **API consumer**
- **Home Assistant user**
- **Source STT platform**
- **Source conversation agent**
- **HA event and state data**

## Connections

- API consumer → REST API: sends API requests (evidence: `README.md`)
- Service CLI → REST API: serves (evidence: `speaker_recognition/__main__.py`)
- Service CLI → Logging setup: configures (evidence: `speaker_recognition/__main__.py`)
- Service CLI → Service settings: sets (evidence: `speaker_recognition/__main__.py`)
- REST API → Request models: uses schemas (evidence: `speaker_recognition/api.py`)
- REST API → Speaker recognizer: dispatches training and recognition (evidence: `speaker_recognition/api.py`)
- Speaker recognizer → Request models: accepts and returns (evidence: `speaker_recognition/recognizer.py`)
- Speaker recognizer → Embedding files: reads and writes (evidence: `speaker_recognition/recognizer.py`)
- API consumer → Python client: calls (evidence: `README.md`)
- Python client → REST API: sends HTTP requests (evidence: `speaker_recognition/client.py`)
- Python client → Request models: serializes and parses (evidence: `speaker_recognition/client.py`)
- Home Assistant user → Integration setup: configures (evidence: `README.md`)
- Integration setup → Integration settings: uses settings (evidence: `custom_components/speaker_recognition/config_flow.py`)
- Integration lifecycle → Integration settings: uses settings (evidence: `custom_components/speaker_recognition/__init__.py`)
- Integration lifecycle → HA recognition client: sets up (evidence: `custom_components/speaker_recognition/__init__.py`)
- Home Assistant user → Integration lifecycle: provides voice samples (evidence: `README.md`)
- HA recognition client → Python client: calls backend client (evidence: `custom_components/speaker_recognition/recognition.py`)
- HA recognition client → REST API: trains and recognizes via HTTP (evidence: `README.md`)
- STT entity → HA recognition client: recognizes buffered audio (evidence: `custom_components/speaker_recognition/stt.py`)
- STT entity → Source STT platform: forwards audio stream (evidence: `custom_components/speaker_recognition/stt.py`)
- STT entity → HA event and state data: fires event and stores result (evidence: `custom_components/speaker_recognition/stt.py`)
- Conversation agent → HA event and state data: reads recent result (evidence: `custom_components/speaker_recognition/conversation.py`)
- Conversation agent → Source conversation agent: forwards enriched input (evidence: `custom_components/speaker_recognition/conversation.py`)
- Home Assistant user → STT entity: uses speech-to-text (evidence: `README.md`)
- Home Assistant user → Conversation agent: uses voice commands (evidence: `README.md`)
- Addon runtime → Service CLI: launches service (evidence: `README.md`)
