1455 Code Path Guide F3b59050

# VoiceMode Converse Code Path Guide

## Overview
This guide traces the code path from running `voicemode converse` through all the relevant files.

## Code Path

### 1. Entry Point: Package Configuration
**File:** `pyproject.toml`
**Lines:** 100-102
```toml
[project.scripts]
voice-mode = "voice_mode.cli:voice_mode"
voicemode = "voice_mode.cli:voice_mode"
```
Both commands map to the `voice_mode()` function in the CLI module.

### 2. CLI Entry Function
**File:** `voice_mode/cli.py`
**Function:** `voice_mode()`
**Lines:** 74-76
```python
def voice_mode() -> None:
    """Entry point for voicemode command - starts the MCP server or runs subcommands."""
    voice_mode_main_cli()
```
This calls the main CLI group.

### 3. Main CLI Group
**File:** `voice_mode/cli.py`
**Function:** `voice_mode_main_cli()`
**Lines:** 40-72
This is a Click command group that handles all subcommands. Without a subcommand, it starts the MCP server. With subcommands, it routes to the appropriate handler.

### 4. Converse Subcommand
**File:** `voice_mode/cli.py`
**Decorator:** `@voice_mode_main_cli.command()`
**Function:** `converse()`
**Lines:** 1650-1815

Key parameters:
- `--message, -m`: Initial message to speak
- `--wait/--no-wait`: Whether to wait for response
- `--duration, -d`: Listen duration
- `--voice`: TTS voice to use
- `--tts-provider`: OpenAI or Kokoro
- `--continuous, -c`: Continuous conversation mode

The function creates an async wrapper (line 1690) that calls the actual tool implementation.

### 5. Converse Tool Implementation
**File:** `voice_mode/tools/converse.py`
**Decorator:** `@mcp.tool()`
**Function:** `converse()`
**Lines:** 1194-1195 (and beyond)

This is the main MCP tool that handles:
- Voice synthesis (TTS)
- Voice recognition (STT)
- Provider selection
- Audio playback and recording
- Conversation logging

Key imports:
- Line 61-70: Core functions from `voice_mode.core`
- Line 60: Provider registry from `voice_mode.provider_discovery`
- Line 28: Conversation logger

### 6. Core Audio Functions
**File:** `voice_mode/core.py`

Key functions:
- `get_openai_clients()` - Line 131: Initialize API clients
- `text_to_speech()` - Line 163: Convert text to audio
- `play_chime_start()` - Line 612: Play start chime
- `play_chime_end()` - Line 644: Play end chime
- `generate_chime()` - Line 528: Generate chime audio
- `cleanup()` - Line 676: Cleanup resources

### 7. Provider Discovery
**File:** `voice_mode/provider_discovery.py`

Discovers and manages TTS/STT providers:
- OpenAI API (cloud)
- Whisper.cpp (local STT)
- Kokoro (local TTS)
- LiveKit (real-time communication)

The provider registry is imported at line 60 of converse.py and used to select the best available provider.

### 8. Configuration
**File:** `voice_mode/config.py`

Loaded by converse.py (lines 29-58), provides:
- Audio settings (sample rate, channels)
- Service endpoints
- Debug flags
- Audio feedback settings
- Silence detection parameters

---

## Demonstration Script

### Setup
```bash
# Terminal control pattern: Use show tool with neovim panes
# After each step, use look tool to confirm the pane is showing correctly
```

### Step 1: Show Entry Point
```bash
# Show pyproject.toml focusing on scripts section
show pyproject.toml
look  # Confirm it's visible
# Highlight lines 100-102 in neovim
```

### Step 2: Show CLI Entry Functions
```bash
# Show the voice_mode() entry point
show voice_mode/cli.py:74-76
look  # Confirm visible

# Show the main CLI group
show voice_mode/cli.py:40-72
look  # Confirm visible
```

### Step 3: Show Converse Command
```bash
# Show the converse subcommand definition
show voice_mode/cli.py:1650-1700
look  # Confirm visible

# Search for the async wrapper
# Navigate to line 1690 to show how it calls the tool
```

### Step 4: Show Tool Implementation
```bash
# Open the converse tool file
show voice_mode/tools/converse.py:1194
look  # Confirm visible

# Show the key imports
show voice_mode/tools/converse.py:1-100
look  # Confirm visible
```

### Step 5: Show Core Functions
```bash
# Show the core module with TTS/STT functions
show voice_mode/core.py
look  # Confirm visible

# Highlight text_to_speech function
# Search for: /^async def text_to_speech
```

### Step 6: Show Provider Discovery
```bash
# Show provider discovery system
show voice_mode/provider_discovery.py
look  # Confirm visible
```

---

## Voice Demonstration Script

While showing each file, use voice to narrate:

```python
converse("Let's trace the voicemode converse command. First, the entry point is in pyproject.toml.", wait_for_response=False)
# Then show pyproject.toml

converse("When you run voicemode converse, it calls voice_mode function in cli.py", wait_for_response=False)
# Then show cli.py entry

converse("This routes to the converse subcommand, which is a Click command", wait_for_response=False)
# Then show converse function

converse("The CLI wraps the actual MCP tool, which is in tools/converse.py", wait_for_response=False)
# Then show tools/converse.py

converse("The tool uses core functions for text-to-speech and speech-to-text", wait_for_response=False)
# Then show core.py

converse("Provider discovery finds available TTS and STT services", wait_for_response=False)
# Then show provider_discovery.py
```

---

## Summary Flow

```
User runs: voicemode converse
    ↓
pyproject.toml (scripts) → voice_mode.cli:voice_mode
    ↓
cli.py:voice_mode() → voice_mode_main_cli()
    ↓
cli.py:converse() command (Click subcommand)
    ↓
tools/converse.py:converse() (MCP tool)
    ↓
Parallel operations:
- core.py:text_to_speech() → Speak the message
- Recording → Listen for response
- core.py:play_chime_start/end() → Audio feedback
- provider_discovery.py → Select TTS/STT providers
    ↓
Return transcribed response to user
```

## Key Concepts

1. **Click CLI Framework**: Handles command parsing and routing
2. **FastMCP Tools**: MCP tool decorator makes functions available to AI
3. **Provider Registry**: Dynamic discovery of local/cloud services
4. **Async/Await**: All voice operations are asynchronous
5. **Configuration**: Environment-based with sensible defaults