### TextToSpeech Initialization and Usage Example

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/CORE_MODULES.md

Instantiates and starts the TextToSpeech client, then sends a message for synthesis. Ensure the client is started before sending messages.

```python
tts = TextToSpeech(voice="alice")
await tts.start_up()
await tts.send("Hello world")
```

--------------------------------

### Install Project Dependencies with pnpm

Source: https://github.com/kyutai-labs/unmute/blob/main/frontend/README.md

Use this command to install all necessary project dependencies. If Node.js is not installed, this command also helps manage the Node.js version.

```bash
pnpm install
# if you don't have Node:
pnpm env use --global lts
```

--------------------------------

### Run Development Server with pnpm

Source: https://github.com/kyutai-labs/unmute/blob/main/frontend/README.md

Execute this command to start the Next.js development server.

```bash
pnpm run dev
```

--------------------------------

### Setup GPU Swarm Node

Source: https://github.com/kyutai-labs/unmute/blob/main/SWARM.md

Initializes a new machine to be part of the GPU-enabled Docker Swarm. This involves copying a setup script and executing it on the remote machine.

```bash
scp setup_gpu_swarm_node.py llm-wrapper-gpu000:/root/
ssh llm-wrapper-gpu000 python3 /root/setup_gpu_swarm_node.py
```

--------------------------------

### QuestManager.add Example

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/CORE_MODULES.md

Example of adding a quest to the QuestManager. Creates a Quest object from a run step and adds it to the manager.

```python
quest = Quest.from_run_step("stt", stt.start_up)
await manager.add(quest)
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/kyutai-labs/unmute/blob/main/README.md

Install pre-commit hooks globally to ensure consistent code quality. This command sets up the pre-commit hook type.

```bash
pre-commit install --hook-type pre-commit
```

--------------------------------

### Initialize UnmuteHandler

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/BACKEND_HANDLER_API.md

Instantiate and start a new UnmuteHandler session. Ensure to use an async context manager for proper setup and teardown.

```python
handler = UnmuteHandler()
async with handler:
    await handler.start_up()
    # Use handler...
```

--------------------------------

### Example Usage of SessionConfig

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/TYPES_AND_DATA_STRUCTURES.md

This snippet demonstrates how to instantiate and use the SessionConfig model with specific voice and recording settings.

```python
config = SessionConfig(
    voice="alice",
    allow_recording=True,
    instructions=None
)
```

--------------------------------

### Install uv Package Manager

Source: https://github.com/kyutai-labs/unmute/blob/main/README.md

Use this command to install the uv package manager, a dependency for running Unmute without Docker.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

--------------------------------

### Start Unmute Services without Docker

Source: https://github.com/kyutai-labs/unmute/blob/main/README.md

Manually start each Unmute service in separate terminals or tmux sessions. Ensure CUDA 12.1 is installed and accessible.

```bash
./dockerless/start_frontend.sh
./dockerless/start_backend.sh
./dockerless/start_llm.sh        # Needs 6.1GB of vram
./dockerless/start_stt.sh        # Needs 2.5GB of vram
./dockerless/start_tts.sh        # Needs 5.3GB of vram
```

--------------------------------

### Instantiate ConstantInstructions

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/TYPES_AND_DATA_STRUCTURES.md

Example of creating an instance of ConstantInstructions for a fixed system prompt and generating the prompt string.

```python
from unmute.llm.system_prompt import ConstantInstructions

instructions = ConstantInstructions()
prompt = instructions.make_system_prompt()
```

--------------------------------

### Prometheus Metrics Output Example

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/METRICS_AND_MONITORING.md

This is an example of the output format from the /metrics endpoint, showing various metrics like sessions, active sessions, and session duration.

```text
# HELP worker_sessions Total number of WebSocket sessions started
# TYPE worker_sessions counter
worker_sessions 42.0

# HELP worker_active_sessions Currently active WebSocket connections
# TYPE worker_active_sessions gauge
worker_active_sessions 3.0

# HELP worker_session_duration Duration of WebSocket sessions
# TYPE worker_session_duration histogram
worker_session_duration_bucket{le="1.0"} 10.0
worker_session_duration_bucket{le="10.0"} 35.0
...
```

--------------------------------

### Install pnpm Package Manager

Source: https://github.com/kyutai-labs/unmute/blob/main/README.md

Use this command to install pnpm, a dependency for running Unmute without Docker.

```bash
curl -fsSL https://get.pnpm.io/install.sh | sh -
```

--------------------------------

### GET /v1/voice-donation Response Example

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/VOICE_SYSTEM.md

This JSON is returned when starting the voice donation process. It provides a verification ID and the text the user needs to read.

```json
{
  "id": "verification_id",
  "text": "The text to read",
  "language": "en"
}
```

--------------------------------

### Python Loadtest Client Example

Source: https://github.com/kyutai-labs/unmute/blob/main/README.md

A Python script used for benchmarking the latency and throughput of the Unmute backend.

```python
import asyncio

from unmute.loadtest.loadtest_client import LoadtestClient


def main():
    client = LoadtestClient()
    asyncio.run(client.run())


if __name__ == "__main__":
    main()
```

--------------------------------

### start_up

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/BACKEND_HANDLER_API.md

Initializes and connects to Speech-to-Text (STT), Text-to-Speech (TTS), and other necessary services. It performs health checks, establishes WebSocket connections, and starts background tasks for service discovery.

```APIDOC
## async start_up()

### Description
Initializes and connects to STT, TTS, and other services. Performs health checks, establishes WebSocket connections, and starts quest manager tasks for service discovery.

### Method
`async def start_up(self) -> None`

### Raises
- `MissingServiceAtCapacity`: A service is at capacity
- `MissingServiceTimeout`: A service connection timed out
- `Exception`: Unexpected service error

### Example
```python
handler = UnmuteHandler()
async with handler:
    try:
        await handler.start_up()
        # Services are now connected
    except MissingServiceTimeout:
        print("Could not connect to services")
```
```

--------------------------------

### Instantiate GradioUpdate Model

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/TYPES_AND_DATA_STRUCTURES.md

Example of how to create an instance of the GradioUpdate model with sample data for chat history, debug information, and plot data.

```python
update = GradioUpdate(
    chat_history=[...],
    debug_dict={
        "timing": {"to_first_token": 0.234},
        "connection": {"stt": "connected"}
    },
    debug_plot_data=[]
)
```

--------------------------------

### Setup and Shutdown Audio Processing

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/FRONTEND_HOOKS_API.md

Initializes audio capture with a media stream and provides functions to start and stop processing. The `onOpusRecorded` callback is invoked when an Opus frame is ready.

```typescript
const { setupAudio, shutdownAudio, audioProcessor } = useAudioProcessor(
  onOpusRecorded
);

// Start audio capture
const mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true });
await setupAudio(mediaStream);

// Stop audio capture
shutdownAudio();
```

--------------------------------

### Install Rust and Cargo

Source: https://github.com/kyutai-labs/unmute/blob/main/README.md

Use this command to install Rust and Cargo, which are required for the Rust-based processes (tts and stt) when running Unmute without Docker.

```bash
curl https://sh.rustup.rs -sSf | sh
```

--------------------------------

### Create VoiceDonationSubmission Instance

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/TYPES_AND_DATA_STRUCTURES.md

Example of creating a VoiceDonationSubmission object with sample data for a voice donation.

```python
submission = VoiceDonationSubmission(
    verification_id="verify_12345",
    name="Alice",
    email="alice@example.com",
    language="en",
    license="cc-by-4.0"
)
```

--------------------------------

### GET /v1/voices Response Example

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/VOICE_SYSTEM.md

This JSON structure represents the response when retrieving a list of available voices. It includes voice name, server path, language, and a 'good' flag.

```json
[
  {
    "name": "voice_name",
    "path_on_server": "voices/path.wav",
    "language": "en",
    "good": true
  }
]
```

--------------------------------

### Initialize and Connect to Services

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/BACKEND_HANDLER_API.md

Initializes and connects to STT, TTS, and other required services. Use this method to establish WebSocket connections and start background tasks before processing audio.

```python
async def start_up(self) -> None
```

```python
handler = UnmuteHandler()
async with handler:
    try:
        await handler.start_up()
        # Services are now connected
    except MissingServiceTimeout:
        print("Could not connect to services")
```

--------------------------------

### Example voices.yaml entry for a new voice

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/VOICE_SYSTEM.md

Add this entry to your voices.yaml file to register a new voice. Ensure the path_on_server matches the voice file's location.

```yaml
- name: alice
  path_on_server: voices/alice.wav
  language: en
  good: true
```

--------------------------------

### GET /

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/HTTP_API_REFERENCE.md

Root health check endpoint to verify server availability.

```APIDOC
## GET /

### Description
Root health check endpoint.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **message** (string) - A confirmation message from the server.

### Response Example
```json
{
  "message": "You've reached the Unmute backend server."
}
```
```

--------------------------------

### VoiceInfo Fields Example

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/TYPES_AND_DATA_STRUCTURES.md

Illustrates the typical fields and their expected data types for voice metadata, loaded from voices.yaml.

```python
{
    "name": "alice",
    "path_on_server": "voices/alice.wav",
    "language": "en",
    "good": True,
    "comment": "Default voice"
}
```

--------------------------------

### Get Instructions Object

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/CORE_MODULES.md

Retrieves the current instructions object. Returns None if default instructions are in use.

```python
def get_instructions(self) -> Instructions | None
```

--------------------------------

### Start Unmute with Docker Compose

Source: https://github.com/kyutai-labs/unmute/blob/main/README.md

Build and run the Unmute services using Docker Compose. Ensure the HUGGING_FACE_HUB_TOKEN environment variable is set.

```bash
# Make sure you have the environment variable with the token: 
echo $HUGGING_FACE_HUB_TOKEN  # This should print hf_...something...

docker compose up --build
```

--------------------------------

### Example Voice Entry in voices.yaml

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/VOICE_SYSTEM.md

Illustrates the structure of a single voice entry within the 'voices.yaml' configuration file. This format is used to define voice properties.

```yaml
- name: "alice"
  path_on_server: "voices/alice.wav"
  language: "en"
  good: true
  comment: "Default friendly voice"
```

--------------------------------

### Verify NVIDIA Container Toolkit Installation

Source: https://github.com/kyutai-labs/unmute/blob/main/README.md

Run this command to ensure Docker can access your GPU via the NVIDIA Container Toolkit.

```bash
sudo docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi
```

--------------------------------

### Run Complete Unmute Session

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/BACKEND_HANDLER_API.md

An example demonstrating a full session lifecycle, including connecting to services, simulating audio input, and emitting events. Ensure necessary imports are present.

```python
import asyncio
from unmute.unmute_handler import UnmuteHandler
import numpy as np

async def run_session():
    handler = UnmuteHandler()
    
    async with handler:
        # Connect to services
        await handler.start_up()
        
        # Simulate receiving audio
        audio_frame = (24000, np.random.randn(1, 1920).astype(np.float32))
        await handler.receive(audio_frame)
        
        # Emit events
        for _ in range(1000):
            output = await handler.emit()
            if output is None:
                await asyncio.sleep(0.01)
                continue
            
            if isinstance(output, tuple):
                sr, pcm = output
                print(f"Audio chunk: {len(pcm)} samples")
            elif hasattr(output, 'type'):
                print(f"Event: {output.type}")

asyncio.run(run_session())
```

--------------------------------

### Example voices.yaml entry for a community-contributed voice

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/VOICE_SYSTEM.md

Use this format to add a community-contributed voice to your voices.yaml. Include a comment to note its origin.

```yaml
- name: haku
  path_on_server: voice-donations/Haku.wav
  language: ja
  good: true
  comment: "Voice donation from community"
```

--------------------------------

### CORS Configuration Example

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/HTTP_API_REFERENCE.md

Update the CORS_ALLOW_ORIGINS variable in main_websocket.py for production deployments to specify allowed origins.

```python
# CORS Configuration
# By default, CORS is enabled for:
# - http://localhost
# - http://localhost:3000
#
# For production deployments, update CORS_ALLOW_ORIGINS in main_websocket.py.
CORS_ALLOW_ORIGINS = [
    "http://localhost",
    "http://localhost:3000",
    # Add your production origin here
]
```

--------------------------------

### Request Microphone Access and Setup Audio

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/FRONTEND_HOOKS_API.md

Requests microphone permission from the user and, if granted, sets up the audio processing with the obtained media stream. Returns the media stream if permission is granted, otherwise null.

```typescript
const { microphoneAccess, askMicrophoneAccess } = useMicrophoneAccess();

// Request permission
const mediaStream = await askMicrophoneAccess();

if (mediaStream) {
  // User granted permission
  await setupAudio(mediaStream);
}
```

--------------------------------

### POST /v1/voices Response Example

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/VOICE_SYSTEM.md

The response after uploading a custom voice for cloning. It returns a unique identifier for the cloned voice.

```json
{
  "name": "cloned_voice_id"
}
```

--------------------------------

### Run Backend in Dev Mode

Source: https://github.com/kyutai-labs/unmute/blob/main/README.md

Start the Unmute backend server in development mode with autoreloading enabled. This command uses `uv` to run the FastAPI application.

```bash
uv run fastapi dev unmute/main_websocket.py
```

--------------------------------

### Configure GPU Reservation for Docker Services

Source: https://github.com/kyutai-labs/unmute/blob/main/README.md

Add this snippet to the 'stt', 'tts', and 'llm' services in 'docker-compose.yml' to allocate specific GPUs. This is useful for multi-GPU setups to improve latency.

```yaml
  stt: # Similarly for `tts` and `llm`
    # ...other configuration
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
```

--------------------------------

### Initialize and Use VLLMStream Client

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/CORE_MODULES.md

Demonstrates how to initialize the VLLMStream client with an OpenAI async client and a specified temperature, and then use it to stream chat completions.

```python
from unmute.llm.llm_utils import get_openai_client, VLLMStream

client = get_openai_client()
llm = VLLMStream(client, temperature=0.7)

async for word in llm.chat_completion(messages):
    print(word, end="")
```

--------------------------------

### Initialize Recorder

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/CORE_MODULES.md

Constructs a Recorder instance, specifying the directory where recordings will be saved.

```python
def __init__(self, recordings_dir: Path)
```

--------------------------------

### QuestManager Class

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/BACKEND_HANDLER_API.md

Coordinates startup of STT, TTS, and LLM services as parallel tasks.

```APIDOC
## QuestManager

Coordinates startup of STT, TTS, and LLM services as parallel tasks.

**Import:** `from unmute.quest_manager import QuestManager`
```

--------------------------------

### Implement Custom LLM Instructions

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/README.md

Shows how to define custom system prompts for the chatbot by subclassing Instructions. Use this to tailor the LLM's behavior and persona.

```python
from unmute.llm.system_prompt import Instructions

class CustomInstructions(Instructions):
    def make_system_prompt(self) -> str:
        return "You are an expert in..."

handler.chatbot.set_instructions(CustomInstructions())
```

--------------------------------

### Input Audio Buffer Speech Started Event

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/WEBSOCKET_PROTOCOL.md

Signals that the Speech-to-Text (STT) service has detected the start of speech. This event is based on STT output and may differ from VAD-based events.

```json
{
  "type": "input_audio_buffer.speech_started",
  "event_id": "event_..."
}
```

--------------------------------

### Service Timeout Error Example

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/WEBSOCKET_PROTOCOL.md

This JSON structure indicates a fatal error where a service has timed out.

```json
{
  "type": "error",
  "error": {
    "type": "fatal",
    "message": "Service 'tts' timed out. Please try again later."
  }
}
```

--------------------------------

### Run Backend in Production

Source: https://github.com/kyutai-labs/unmute/blob/main/README.md

Execute the Unmute backend server in a production-ready configuration. This command uses `uv` to run the FastAPI application.

```bash
uv run fastapi run unmute/main_websocket.py
```

--------------------------------

### GET /v1/voice-donation

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/HTTP_API_REFERENCE.md

Initiate a voice donation process by requesting a verification text for the user to read.

```APIDOC
## GET /v1/voice-donation

### Description
Initiate a voice donation by requesting a verification text.

### Method
GET

### Endpoint
/v1/voice-donation

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for this verification.
- **text** (string) - The text the user must read for verification.
- **language** (string) - The language of the verification text.

### Response Example
```json
{
  "id": "verification_id",
  "text": "The text user must read",
  "language": "en"
}
```

### Usage Example
```typescript
const verification = await fetch('/v1/voice-donation').then(r => r.json());
console.log('User must read:', verification.text);
```
```

--------------------------------

### Deploy Production or Staging Stack

Source: https://github.com/kyutai-labs/unmute/blob/main/SWARM.md

Executes the deployment script for either the production or staging environment. Ensure required environment variables like HUGGING_FACE_HUB_TOKEN and PROVIDERS_GOOGLE_CLIENT_SECRET are set.

```bash
./bake_deploy_prod.sh
```

```bash
./bake_deploy_staging.sh
```

--------------------------------

### STTWordMessage Definition

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/TYPES_AND_DATA_STRUCTURES.md

Represents a transcribed word from the STT service. Includes the word text and its start time.

```python
class STTWordMessage(BaseModel):
    type: Literal["Word"]
    text: str
    start_time: float
```

--------------------------------

### Run Unmute Backend

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/README.md

Commands to run the Unmute backend server using `uv` for development with auto-reloading or for production.

```bash
# Development (with auto-reload)
uv run fastapi dev unmute/main_websocket.py

```

```bash
# Production
uv run fastapi run unmute/main_websocket.py

```

--------------------------------

### input_audio_buffer.speech_started

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/WEBSOCKET_PROTOCOL.md

Signals that the Speech-to-Text (STT) service has detected the start of speech. This event is based on STT output.

```APIDOC
## input_audio_buffer.speech_started

### Description
STT detected the start of speech.

### Message
```json
{
  "type": "input_audio_buffer.speech_started",
  "event_id": "event_..."
}
```

### Note
This event is based on STT output, not VAD. It may differ from the VAD-based `input_audio_buffer.speech_stopped`.
```

--------------------------------

### Define Instructions Base Class

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/TYPES_AND_DATA_STRUCTURES.md

Defines the base class for system prompt configurations, including a method to generate the system prompt string.

```python
from unmute.llm.system_prompt import Instructions

class Instructions(BaseModel):
    """Base class for system prompt configurations."""
    def make_system_prompt(self) -> str:
        """Generate the system prompt string."""
        ...
```

--------------------------------

### Create a Response Instance

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/TYPES_AND_DATA_STRUCTURES.md

Instantiate the Response model with a specific status, voice, and conversation history. The chat_history defaults to an empty list if not provided.

```python
response = Response(
    status="in_progress",
    voice="default_voice",
    chat_history=[
        {"role": "system", "content": "You are helpful..."},
        {"role": "user", "content": "Hello"},
    ]
)
```

--------------------------------

### JSON Parse Error Example

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/WEBSOCKET_PROTOCOL.md

This JSON structure indicates an error due to invalid JSON formatting in the request.

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid JSON: Expecting value: line 1 column 2 (char 1)"
  }
}
```

--------------------------------

### Recorder Constructor

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/CORE_MODULES.md

Initializes the Recorder, specifying the directory where recordings will be saved.

```APIDOC
## Recorder Constructor

### Description
Initializes the Recorder.

### Method Signature
```python
def __init__(self, recordings_dir: Path)
```

### Parameters
#### `recordings_dir` (Path)
- **Type**: Path
- **Description**: Directory to save recordings
```

--------------------------------

### Get Conversation State

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/BACKEND_HANDLER_API.md

Retrieve the current state of the conversation. Possible states include 'waiting_for_user', 'user_speaking', and 'bot_speaking'.

```python
state = handler.chatbot.conversation_state()
# Returns: "waiting_for_user" | "user_speaking" | "bot_speaking"
```

--------------------------------

### GET /metrics

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/HTTP_API_REFERENCE.md

Exposes Prometheus metrics if enabled, providing performance and operational data in Prometheus text format.

```APIDOC
## GET /metrics

### Description
Prometheus metrics endpoint (if enabled by Instrumentator).

### Method
GET

### Endpoint
/metrics

### Response
#### Success Response (200)
Metrics in Prometheus text format.
```

--------------------------------

### GET /v1/voices

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/HTTP_API_REFERENCE.md

Retrieve a list of available voices for Text-to-Speech, including their names, server paths, languages, and quality.

```APIDOC
## GET /v1/voices

### Description
Retrieve the list of available voices for Text-to-Speech output.

### Method
GET

### Endpoint
/v1/voices

### Response
#### Success Response (200)
- **name** (string) - The name of the voice.
- **path_on_server** (string) - The server path to the voice file.
- **language** (string) - The language of the voice.
- **good** (boolean) - Indicates if the voice is marked as good for use.

### Response Example
```json
[
  {
    "name": "voice_name",
    "path_on_server": "path/to/voice.wav",
    "language": "en",
    "good": true
  }
]
```

### Usage Example
```typescript
const voices = await fetch('/v1/voices').then(r => r.json());
voices.forEach(voice => {
  console.log(`${voice.name}: ${voice.language}`);
});
```
```

--------------------------------

### Start Voice Donation Process

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/VOICE_SYSTEM.md

Initiates the voice donation process by providing a verification ID, text to read, and language.

```APIDOC
## GET /v1/voice-donation

Start voice donation process.

**Response:**
```json
{
  "id": "verification_id",
  "text": "The text to read",
  "language": "en"
}
```

User must read the text in `text` field and submit with `id`.
```

--------------------------------

### GET /v1/health

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/HTTP_API_REFERENCE.md

Check the health status of essential backend services including TTS, STT, LLM, and voice cloning.

```APIDOC
## GET /v1/health

### Description
Check the health status of all required services.

### Method
GET

### Endpoint
/v1/health

### Response
#### Success Response (200)
- **tts_up** (boolean) - Whether the Text-to-Speech service is responding
- **stt_up** (boolean) - Whether the Speech-to-Text service is responding
- **llm_up** (boolean) - Whether the LLM service is responding
- **voice_cloning_up** (boolean) - Whether the voice cloning service is responding
- **ok** (boolean) - Computed field: true if TTS, STT, and LLM are all up (voice cloning is optional)

### Response Example
```json
{
  "tts_up": true,
  "stt_up": true,
  "llm_up": true,
  "voice_cloning_up": false,
  "ok": true
}
```

### Usage Example
```typescript
const response = await fetch('/v1/health');
const health = await response.json();
if (health.ok) {
  console.log('All services operational');
} else {
  console.log('Server is degraded:', health);
}
```
```

--------------------------------

### get_instructions()

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/CORE_MODULES.md

Retrieves the current instructions object. Returns None if default instructions are being used.

```APIDOC
## get_instructions()

### Description
Get the current instructions object.

### Returns
`Instructions | None` - The current instructions object, or `None` if default instructions are in use.

### Source
`unmute/llm/chatbot.py:109-110`
```

--------------------------------

### Manage Unmute Session with Async Handler

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/README.md

Demonstrates how to initialize and manage an Unmute session using the UnmuteHandler. This pattern is useful for setting up concurrent request processing loops.

```python
from unmute.unmute_handler import UnmuteHandler

async def manage_session():
    handler = UnmuteHandler()
    
    async with handler:
        # Connect to services
        await handler.start_up()
        
        # Process requests in parallel loops
        async with asyncio.TaskGroup() as tg:
            tg.create_task(receive_loop())  # Get input
            tg.create_task(emit_loop())      # Send output
```

--------------------------------

### POST /v1/voice-donation Response Example

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/VOICE_SYSTEM.md

The response for completing a voice donation. It returns an empty JSON object upon successful submission.

```json
{}
```

--------------------------------

### Service Unavailable Error Example

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/WEBSOCKET_PROTOCOL.md

This JSON structure represents a fatal error where a service is temporarily unavailable due to high load.

```json
{
  "type": "error",
  "error": {
    "type": "fatal",
    "message": "Too many people are connected to service 'stt'. Please try again later."
  }
}
```

--------------------------------

### set_instructions(instructions)

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/CORE_MODULES.md

Updates the system prompt for the chatbot. This method allows for dynamic modification of the chatbot's behavior and persona.

```APIDOC
## set_instructions(instructions)

### Description
Update the system prompt.

### Method
`def set_instructions(self, instructions: Instructions) -> None`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **instructions** (Instructions) - Required - New system prompt configuration.

### Behavior
- Generates the system prompt from the provided instructions.
- Updates the first message in the chat history.
- Caches the instructions object.

### Example
```python
from unmute.llm.system_prompt import ConstantInstructions

new_instructions = ConstantInstructions()
chatbot.set_instructions(new_instructions)
```
```

--------------------------------

### Increment Session Counter

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/METRICS_AND_MONITORING.md

Use this snippet to increment the total number of WebSocket sessions started. This metric is typically incremented at startup.

```python
from unmute import metrics as mt

mt.SESSIONS.inc()
```

--------------------------------

### Initialize SpeechToText Client

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/CORE_MODULES.md

Instantiate the SpeechToText client using default environment variables or a custom WebSocket URL. The delay_sec parameter specifies expected STT latency.

```python
stt = SpeechToText()  # Uses defaults from environment
stt = SpeechToText(stt_instance="ws://custom:8090")
```

--------------------------------

### Response Created Event

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/WEBSOCKET_PROTOCOL.md

Indicates the start of a new assistant response. It includes the response status, voice used, and chat history.

```json
{
  "type": "response.created",
  "event_id": "event_...",
  "response": {
    "object": "realtime.response",
    "status": "in_progress",
    "voice": "voice_name",
    "chat_history": [/* messages */]
  }
}
```

--------------------------------

### Get System Prompt Text

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/CORE_MODULES.md

Retrieves the current system prompt text. Use this to inspect the active instructions given to the chatbot.

```python
def get_system_prompt(self) -> str
```

```python
prompt = chatbot.get_system_prompt()
print(prompt)  # "You are a helpful assistant..."
```

--------------------------------

### Chatbot Constructor

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/CORE_MODULES.md

Initializes the Chatbot with a system prompt and an empty chat history.

```python
def __init__(self) -> None
```

```python
chatbot = Chatbot()
print(chatbot.chat_history)
# [{"role": "system", "content": "You are..."}]
```

--------------------------------

### TTSTextMessage Definition

Source: https://github.com/kyutai-labs/unmute/blob/main/_autodocs/TYPES_AND_DATA_STRUCTURES.md

Represents text chunk timing information received from the TTS service. Includes the synthesized text and its start and stop times.

```python
class TTSTextMessage(BaseModel):
    type: Literal["Text"]
    text: str
    start_s: float
    stop_s: float
```