### CLI Quickstart Installation

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/INSTALLATION.md

Clone the repository and run the install script followed by the agent setup command for a command-line based installation.

```bash
git clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git
cd Asterisk-AI-Voice-Agent

./install.sh
agent setup
```

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

### Traditional Development Setup

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/CONTRIBUTING.md

Use this method for a traditional development setup. It involves cloning the repository and running an installation script.

```bash
git clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git
cd Asterisk-AI-Voice-Agent
./install.sh   # guided setup; or follow README for manual steps
```

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

### Start Admin UI and AI Engine Containers

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/INSTALLATION.md

Start the Admin UI container first to complete the visual setup wizard, then start the AI engine container.

```bash
# Start Admin UI first
docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui

# Complete the Setup Wizard in Admin UI, then start ai_engine
docker compose -p asterisk-ai-voice-agent up -d --build ai_engine
```

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

### Install and Setup Ava AI Voice Agent CLI

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/README.md

Run the installation script and then the setup command for interactive CLI setup. Legacy commands are available but new workflows should use documented commands.

```bash
./install.sh
agent setup
```

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

### Run Interactive Setup Wizard

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/contributing/milestones/milestone-12-setup-validation-tools.md

Execute the `agent init` command to launch the interactive setup wizard. This guides new operators through configuration, template selection, and credential management, generating necessary configuration files.

```bash
./bin/agent init

🚀 AI Voice Agent Setup Wizard
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Select configuration template:
1) Local (fully offline)
2) Cloud (Deepgram + OpenAI)
3) Hybrid (local STT/TTS + cloud LLM)
4) OpenAI Realtime (monolithic)
5) Deepgram Voice Agent (monolithic)

Choice [1-5]: 4

Enter OpenAI API key: sk-...
Enter Asterisk ARI password: ********

✅ Configuration generated: config/ai-agent.yaml
✅ Environment file created: .env
✅ Ready to start!

Next steps:
1. ./bin/agent doctor     # Validate environment
2. docker compose up -d   # Start services
3. Make test call to extension 1000
```

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

### Manual Installation Script

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/INSTALLATION.md

Use this script for manual setup and installation of the AVA AI Voice Agent for Asterisk. It guides through baseline choices, API key prompts, and optional CLI tool installation.

```bash
git clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git
cd Asterisk-AI-Voice-Agent
./install.sh
```

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

### Start Services for CPU-Only Setup

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/LOCAL_ONLY_SETUP.md

Command to start the necessary Docker services for the local AI server, AI engine, and admin UI in a CPU-only topology.

```bash
docker compose -p asterisk-ai-voice-agent up -d --build local_ai_server ai_engine admin_ui
```

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

### Setup Contributor Environment

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/README.md

Clone the repository, navigate to the directory, and run the setup script to prepare your environment for contributing.

```bash
git clone -b develop https://github.com/hkjarral/Asterisk-AI-Voice-Agent.git
cd Asterisk-AI-Voice-Agent
./scripts/setup-contributor.sh
```

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

### Manual Setup for Ava AI Voice Agent

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/README.md

Manually configure environment variables by copying the example file and editing it with API keys. Then, start the Docker services in detached mode.

```bash
# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Start services
docker compose -p asterisk-ai-voice-agent up -d
```

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

### Environment Example for Vertex AI Setup

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/contributing/milestones/milestone-25-google-vertex.md

This section in the .env.example file provides documented, step-by-step instructions for configuring Vertex AI. It includes necessary environment variables like project ID, location, and the path to service account credentials.

```env
# Vertex AI configuration
GOOGLE_CLOUD_PROJECT=my-gcp-project-id
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_APPLICATION_CREDENTIALS=/app/project/secrets/gcp-service-account.json

```

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

### Run Interactive Setup Wizard

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/TROUBLESHOOTING_GUIDE.md

Execute 'agent setup' to run the interactive setup wizard for configuring Asterisk ARI credentials, audio transport, AI provider, and pipeline settings. Use '--list-targets' to view discovered targets without modifying configuration files.

```bash
# Run setup wizard
agent setup
```

```bash
# Show targets discovered from base and local configuration without changing files
agent setup --list-targets
```

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

### List Available Setup Targets

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/CLI_TOOLS_GUIDE.md

Lists the available configuration targets for the agent setup without making any changes. Useful for previewing options before running the full setup.

```bash
agent setup --list-targets
```

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

### Setup Contributor Script

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/CONTRIBUTING.md

Run this script to set up your development environment for contributing. It automates initial setup steps.

```bash
git clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git
cd Asterisk-AI-Voice-Agent
./scripts/setup-contributor.sh
```

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

### Start local_ai_server with local-core profile

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/LOCAL_PROFILES.md

After building, use this command to start the services defined in the 'local-core' profile.

```bash
docker compose up -d
```

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

### Install Dependencies

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/admin_ui/frontend/README.md

Navigate to the frontend directory and install project dependencies using npm.

```bash
cd admin_ui/frontend
npm install
```

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

### Install CLI

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/cli/README.md

Installs the agent CLI using a provided script. This is the recommended method for installing released binaries.

```bash
curl -sSL https://raw.githubusercontent.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/main/scripts/install-cli.sh | bash
```

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

### Start local_ai_server with GPU profile

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/LOCAL_PROFILES.md

Start the services for the 'local-gpu' profile after building. This command assumes the necessary GPU prerequisites are met.

```bash
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d local_ai_server
```

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

### Example .env File with Defaults

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/contributing/milestones/milestone-13-config-cleanup-migration.md

This example shows the default values for diagnostic and logging settings in an .env file. These settings are opt-in and provide production-safe defaults.

```bash
# .env.example
DIAG_EGRESS_SWAP_MODE=none
DIAG_ENABLE_TAPS=false
LOG_LEVEL=INFO
LOG_FORMAT=json
LOG_TO_FILE=true
```

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

### Build and Start Docker Containers

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/Vicidial-Setup.md

Build all necessary Docker services and then start them in detached mode. Verify that the containers are running.

```bash
# Build all services
docker compose build

# Start services
docker compose up -d

# Verify containers are running
docker ps
```

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

### Run Interactive Agent Setup

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/CLI_TOOLS_GUIDE.md

Initiates the interactive setup wizard for the agent CLI. This wizard configures ARI, transport, and the active provider or pipeline.

```bash
agent setup
```

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

### Start ai_engine and admin_ui

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/LOCAL_ONLY_SETUP.md

Starts the ai_engine and admin_ui services, which do not require GPU.

```bash
docker compose -p asterisk-ai-voice-agent up -d --build ai_engine admin_ui

```

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

### Setup Local AI Models

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/TROUBLESHOOTING_GUIDE.md

Run the model setup command to download necessary models for local AI services. This is crucial for loading STT, LLM, and TTS models.

```bash
make model-setup
```

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

### Install Docker and Docker Compose

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/PRODUCTION_DEPLOYMENT.md

Installs Docker and Docker Compose on a new server as part of the disaster recovery provisioning step. Ensure the server meets the necessary specifications.

```bash
# Install Docker
curl -fsSL https://get.docker.com | sh

# Install Docker Compose
apt-get install docker-compose-plugin
```

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

### Run AVA AI Voice Agent Installation Script

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/INSTALLATION.md

Execute the main installation script. Use sudo if Docker requires elevated permissions.

```bash
./install.sh
```

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

### Personalized Support Context Example

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/Provider-ElevenLabs-Setup.md

Demonstrates a personalized context configuration using dynamic variables for greeting and prompt. This example uses '{caller_name}' and '{caller_id}' to tailor the agent's interaction.

```yaml
contexts:
  personalized_support:
    provider: elevenlabs_agent
    greeting: "Hi {caller_name}, thank you for calling! How can I help?"
    prompt: |
      You are speaking with {caller_name} (phone: {caller_id}).
      Personalize responses using their name.
```

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

### Install google-api-python-client

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/Google-calendar-tool.md

Install the required Google API client library for Python. This is necessary for the tool to interact with the Google Calendar API.

```bash
pip install google-api-python-client>=2.0.0
```

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

### Install Python Dependencies

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/admin_ui/UI_Setup_Guide.md

Change directory to the backend and install the required Python packages using pip.

```bash
cd ../backend
pip install -r requirements.txt
```

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

### Start Admin UI with Docker Compose

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/README.md

Use this command to build and start the Admin UI container. Access the UI at http://localhost:3003. Retrieve the one-time password from the container logs.

```bash
docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui
```

```bash
# Access at: http://localhost:3003
# Retrieve one-time password: docker compose -p asterisk-ai-voice-agent logs admin_ui | grep -i password
```

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

### Start Admin UI Container

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/admin_ui/UI_Setup_Guide.md

Use this command to build and start the Admin UI container in detached mode. View logs using the second command if needed.

```bash
docker compose up -d --build admin_ui
```

```bash
docker compose logs -f admin_ui
```

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

### Install Docker on CentOS/Rocky/Alma

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/INSTALLATION.md

Installs Docker CE and related components on CentOS, Rocky, or AlmaLinux systems. Enables and starts the Docker service, then verifies the installation.

```bash
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io
sudo systemctl enable --now docker
docker --version && docker compose version
```

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

### Clone and Setup GPU Server

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/LOCAL_ONLY_SETUP.md

Clones the repository and runs the preflight script with local-server flag on the GPU machine.

```bash
git clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git
cd Asterisk-AI-Voice-Agent

# --local-server skips Asterisk/Admin UI checks (not needed on GPU-only box)
sudo ./preflight.sh --apply-fixes --local-server

```

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

### Install Ava AI Voice Agent CLI

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/README.md

Installs the production-ready CLI tool for Asterisk AI Voice Agent operations and setup.

```bash
curl -sSL https://raw.githubusercontent.com/hkjarral/Asterisk-AI-Voice-Agent/main/scripts/install-cli.sh | bash
```

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

### Start Asterisk AI Admin UI

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/FS-PBX-Setup-Instructions.md

Starts the Asterisk AI Admin UI container in detached mode. Ensure Docker is installed and running.

```bash
# Start the Admin UI container
docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate admin_ui
```

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

### Clone and Configure Repository

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/Vicidial-Setup.md

Initial setup involves cloning or updating the repository, copying the environment file, and configuring ARI credentials and ViciDial settings.

```bash
# Clone or update the repository
cd /root/Asterisk-AI-Voice-Agent
git checkout main
git pull origin main

# Copy example env and configure
cp .env.example .env
# Edit .env with your ARI credentials and experimental ViciDial settings (see Section 4)
```

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

### Clone and Setup PBX Server

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/LOCAL_ONLY_SETUP.md

Clones the repository and runs the preflight script on the PBX machine.

```bash
git clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git
cd Asterisk-AI-Voice-Agent
sudo ./preflight.sh --apply-fixes

```

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

### Prompt Example: Get Free Slots

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/Google-calendar-tool.md

Example of a caller's request to find available appointment times and the corresponding Google Calendar tool action.

```text
"When are you free for a 30-minute appointment next Tuesday?"
-> `get_free_slots` with `time_min` / `time_max` for that day, `duration: 30`, and (if not in config) `free_prefix` / `busy_prefix` as needed.
```

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

### Start Admin UI Container

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/admin_ui/UI_Setup_Guide.md

Use Docker Compose to start the Admin UI service in detached mode. This command assumes Docker Compose is installed and configured.

```bash
docker compose up -d admin_ui
```

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

### Copy Configurations for Side-by-Side Install

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/contributing/testing-from-source.md

Copies configuration files from an existing AVA installation to the new 'AVA-test' directory for a side-by-side setup. This ensures the new instance uses the same settings.

```bash
cp /path/to/existing/AVA-AI-Voice-Agent-for-Asterisk/config/ai-agent.yaml config/
cp /path/to/existing/AVA-AI-Voice-Agent-for-Asterisk/config/ai-agent.local.yaml config/ 2>/dev/null || true
cp /path/to/existing/AVA-AI-Voice-Agent-for-Asterisk/.env .
cp -r /path/to/existing/AVA-AI-Voice-Agent-for-Asterisk/config/contexts config/ 2>/dev/null || true
```

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

### Sample Pipeline Configurations

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/contributing/milestones/milestone-7-configurable-pipelines.md

Example pipeline configurations demonstrating different provider combinations. These files showcase how to set up local-only, hybrid (local STT with cloud TTS/LLM), and cloud-only pipelines.

```yaml
local_only.yaml
```

```yaml
hybrid_deepgram_openai.yaml
```

```yaml
cloud_only_google.yaml
```

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

### Alertmanager Configuration Example

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/PRODUCTION_DEPLOYMENT.md

Example configuration for Alertmanager, defining routing rules for critical and warning alerts to PagerDuty and Slack respectively. This setup helps manage notifications based on severity.

```yaml
route:
  group_by: ['alertname', 'cluster']
  receiver: 'team-pager'
  routes:
    - match:
        severity: critical
      receiver: team-pager
      
    - match:
        severity: warning
      receiver: team-slack

receivers:
  - name: 'team-pager'
    pagerduty_configs:
      - service_key: '<key>'
        
  - name: 'team-slack'
    slack_configs:
      - api_url: '<webhook>'
        channel: '#ai-voice-alerts'
```

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

### Get Signed URL Response

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/contributing/references/Provider-ElevenLabs-Implementation.md

Example JSON response from the ElevenLabs API containing the signed WebSocket URL.

```json
{
  "signed_url": "wss://api.elevenlabs.io/v1/convai/conversation?agent_id=agent_xxxx&..."
}
```

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

### Check PROJECT_ROOT for standalone setup

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/admin_ui/UI_Setup_Guide.md

For standalone installations, confirm that the PROJECT_ROOT environment variable points to the correct project directory.

```bash
echo $PROJECT_ROOT
```

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

### Tool Execution Log Example

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/contributing/references/Pipeline-Local_Hybrid-Implementation.md

These logs indicate the start and completion of a tool's execution, including its name and result.

```log
DEBUG: Processing tool call name=<tool_name>
Executing pipeline tool tool=<tool_name>
Tool execution result tool=<tool_name> result={...}
```

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

### Compare Configuration Files

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/contributing/testing-from-source.md

Use diff or vimdiff to compare your local configuration with the example configuration.

```bash
diff config/ai-agent.yaml config/ai-agent.example.yaml
```

```bash
vimdiff config/ai-agent.yaml config/ai-agent.example.yaml
```

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

### Get Capabilities

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/local-ai-server/PROTOCOL.md

Query installed backends without loading models. Useful for Admin UI to show available options.

```APIDOC
## POST /capabilities

### Description
Retrieves a list of available AI capabilities (e.g., STT, TTS, LLM) installed on the server.

### Method
POST

### Endpoint
/capabilities

### Request Body
- **type** (string) - Required - Must be "capabilities"

### Request Example
```json
{
  "type": "capabilities"
}
```

### Response
#### Success Response (200)
- **type** (string) - The type of the response, "capabilities_response".
- **capabilities** (object) - An object containing boolean flags for each supported capability.
  - **vosk** (boolean) - Indicates if Vosk STT is available.
  - **sherpa** (boolean) - Indicates if Sherpa STT is available.
  - **kroko_embedded** (boolean) - Indicates if Kroko embedded STT is available.
  - **tone** (boolean) - Indicates if T-one TTS is available.
  - **faster_whisper** (boolean) - Indicates if Faster Whisper STT is available.
  - **whisper_cpp** (boolean) - Indicates if Whisper.cpp STT is available.
  - **piper** (boolean) - Indicates if Piper TTS is available.
  - **kokoro** (boolean) - Indicates if Kokoro TTS is available.
  - **melotts** (boolean) - Indicates if Melotts TTS is available.
  - **silero** (boolean) - Indicates if Silero TTS is available.
  - **llama** (boolean) - Indicates if Llama LLM is available.

#### Response Example
```json
{
  "type": "capabilities_response",
  "capabilities": {
    "vosk": true,
    "sherpa": true,
    "kroko_embedded": true,
    "tone": false,
    "faster_whisper": true,
    "whisper_cpp": false,
    "piper": true,
    "kokoro": true,
    "melotts": false,
    "silero": true,
    "llama": true
  }
}
```
```

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

### Run AVA in Side-by-Side Installation

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/contributing/testing-from-source.md

Builds and starts the AVA AI Voice Agent for Asterisk services using Docker Compose in detached mode for a side-by-side installation. This command assumes configurations have been copied and any necessary port adjustments made.

```bash
docker compose up -d --build
```

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

### Successful Call Log Pattern

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/case-studies/Google-Live-Golden-Baseline.md

Example log output for a successfully completed call, showing the sequence of events from start to cleanup.

```log
[info] Call started
[info] Google Live WebSocket connected
[info] Session setup successful
[debug] Tracked conversation message (role=user)
[debug] Tracked conversation message (role=assistant)
[info] Google Live tool call: request_transcript
[info] Transcript email saved for end-of-call sending
[info] Email summary scheduled for sending
[info] 📧 Sent end-of-call transcript
[info] Call cleanup completed
```

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

### Configure Bridge Network Port Mappings

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/TROUBLESHOOTING_GUIDE.md

Example configuration for port mappings when using a custom bridge network in docker-compose.yml. This is an advanced setup.

```yaml
ports:
  - "8090:8090"      # AudioSocket
  - "18080:18080/udp"  # RTP
  - "15000:15000"    # Health
```

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

### Before v4 Config Example (YAML)

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/contributing/milestones/milestone-13-config-cleanup-migration.md

Illustrates the structure of the older v3 configuration file, highlighting diagnostic settings embedded within the YAML.

```yaml
# config/ai-agent.yaml (16K, 374 lines)
app:
  name: "AI Voice Agent"
  log_level: DEBUG        # Mixed concerns
  log_format: json
  
diagnostics:
  egress_swap_mode: auto  # Diagnostic in YAML
  enable_taps: true
  tap_pre_secs: 3
  tap_post_secs: 5
  tap_output_dir: diagnostics/taps
  
streaming:
  log_level: DEBUG        # Diagnostic in YAML
  min_start_ms: 800
  ...
```

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

### Verify Asterisk AI Engine Health

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/FS-PBX-Setup-Instructions.md

Starts the ai_engine container and checks its health status. This is a required step for health checks and verifying the installation.

```bash
# Start ai_engine (required for health checks)
docker compose -p asterisk-ai-voice-agent up -d --build ai_engine

# Check ai_engine health
curl http://localhost:15000/health
# Expected: {"status":"healthy"}

# View logs for any errors
docker compose -p asterisk-ai-voice-agent logs ai_engine | tail -20
```

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

### Get Signed URL Request

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/contributing/references/Provider-ElevenLabs-Implementation.md

Example HTTP POST request to obtain a signed URL for establishing a WebSocket connection with the ElevenLabs API. Requires an API key and agent ID.

```http
POST https://api.elevenlabs.io/v1/convai/conversation/get_signed_url
Headers:
  xi-api-key: YOUR_API_KEY
Body:
  {"agent_id": "agent_xxxx"}
```

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

### After v4 Config Example (YAML)

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/contributing/milestones/milestone-13-config-cleanup-migration.md

Shows the simplified v4 configuration file after migrating diagnostic settings, including the new config_version field.

```yaml
# config/ai-agent.yaml (8.1K, 294 lines)
config_version: 4

app:
  name: "AI Voice Agent"
  # Logging in .env
  
# No diagnostics section
  
streaming:
  # No log_level here
  min_start_ms: 800
  ...
```

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

### Streaming TTS Audio Metadata (v2)

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/local-ai-server/PROTOCOL.md

Example of 'tts_audio' metadata for multi-chunk streaming TTS, including utterance grouping and chunk sequencing. This enables clients to start playback before the entire utterance is generated.

```json
{ "type": "tts_audio", "call_id": "c1", "mode": "full", "request_id": "r1", "encoding": "mulaw", "sample_rate_hz": 8000, "byte_length": 8000, "utterance_id": "utt-c1-1712345678", "chunk_index": 0, "is_final": false }
```

```json
{ "type": "tts_audio", "call_id": "c1", "mode": "full", "request_id": "r1", "encoding": "mulaw", "sample_rate_hz": 8000, "byte_length": 6400, "utterance_id": "utt-c1-1712345678", "chunk_index": 1, "is_final": true }
```

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

### Upgrade Steps (v5.x to v6.0.0)

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/MIGRATION.md

Follow these steps to upgrade from v5.x to v6.0.0. This includes backing up configuration, pulling code, running preflight checks, and restarting containers.

```bash
# 1. Backup your configuration
cp .env .env.backup
cp config/ai-agent.yaml config/ai-agent.yaml.backup

# 2. Pull the latest code
git pull

# 3. Run preflight to update environment
sudo ./preflight.sh --apply-fixes

# 4. Rebuild and restart all containers
docker compose -p asterisk-ai-voice-agent up -d --build --force-recreate

# 5. Verify health
curl http://localhost:15000/health
agent check
```

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

### Successful Outbound Call Log Example

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/Vicidial-Setup.md

A successful outbound call log should include messages about originating the call, SIP connection, ARI StasisStart event, AMD result, and call streaming setup.

```text
Outbound originate → endpoint=Local/915551234567@default
Called 915551234567@default
SIP/carrier answered
HYBRID ARI - StasisStart event received → args=['outbound_amd', ...]
Outbound AMD result → amd_status=HUMAN
HYBRID ARI - Caller channel entered Stasis
STREAMING OUTBOUND - Setup → stream_id=stream:greeting:...
```

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

### Tool Adapter Initialization in Python

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/case-studies/Google-Live-Golden-Baseline.md

Initialize the tool adapter in the `__init__` method and use context filtering for tool lists to ensure proper dependency injection and correct tool setup. Creating the adapter during session start is too late.

```python
def __init__(self, ...):
    from src.tools.registry import tool_registry
    self._tool_adapter = GoogleToolAdapter(tool_registry)  # Early creation

async def _send_setup(self, context):
    tool_names = context.get('tools', [])  # Get filtered list
    tools = self._tool_adapter.format_tools(tool_names)  # Only context tools
```

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

### Example Configuration Changes

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/contributing/milestones/TEMPLATE.md

Illustrates how to add a new provider configuration to the AI agent's settings. Ensure the API key is securely managed, potentially using environment variables.

```yaml
# Example config changes
providers:
  new_provider:
    api_key: "${NEW_PROVIDER_API_KEY}"
    model: "model-name"
```

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

### Create Media Path Symlink (If Missing)

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/FreePBX-Integration-Guide.md

Manually create the necessary directory and symlink for AI-generated media if it was not created by the installer. Ensure correct ownership.

```bash
REPO_DIR="/path/to/Asterisk-AI-Voice-Agent"
sudo mkdir -p "${REPO_DIR}/asterisk_media/ai-generated" /var/lib/asterisk/sounds
sudo ln -sfn "${REPO_DIR}/asterisk_media/ai-generated" /var/lib/asterisk/sounds/ai-generated
sudo chown -R asterisk:asterisk "${REPO_DIR}/asterisk_media/ai-generated"
```

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

### Install Agent CLI and Check Version

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/CLI_TOOLS_GUIDE.md

Installs the agent CLI using a curl script and then checks the installed version. This is a common first step after obtaining the installer.

```bash
curl -sSL https://raw.githubusercontent.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk/main/scripts/install-cli.sh | bash
agent version
```

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

### Install Ollama

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/OLLAMA_SETUP.md

Run these commands to install Ollama on macOS or Linux. For Windows, download the installer from the official website.

```bash
# macOS
curl -fsSL https://ollama.ai/install.sh | sh

# Linux
curl -fsSL https://ollama.ai/install.sh | sh

# Windows
# Download from https://ollama.ai/download
```

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

### Preflight Script Success Criteria Examples

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/CROSS_PLATFORM_PLAN.md

These examples demonstrate the expected output of the preflight script on different operating systems and configurations, including success, SELinux warnings, and rootless Docker detection.

```bash
# Ubuntu 22.04 (typical setup):
./preflight.sh
# ✓ All checks pass, ready to start

# Rocky 9 with SELinux + missing semanage:
./preflight.sh
# Shows: sudo dnf install policycoreutils-python-utils
# Shows: sudo semanage fcontext ... (after tools installed)

# Fedora with rootless Docker:
./preflight.sh
# Detects rootless mode, skips usermod suggestion
```

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

### Preview Production Build

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/admin_ui/frontend/README.md

Locally preview the production build of the application.

```bash
npm run preview
```

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

### Clone and Prepare AAVA Project

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/CROSS_PLATFORM_PLAN.md

This is the primary user flow for setting up AAVA. It involves cloning the repository, running a new pre-flight script for automated checks and fixes, and then starting the Docker Compose services.

```bash
git clone https://github.com/hkjarral/AVA-AI-Voice-Agent-for-Asterisk.git
cd AVA-AI-Voice-Agent-for-Asterisk
./preflight.sh          # ← NEW: Detects, fixes, prepares everything
docker compose up -d
# Open http://localhost:3003 → Clean UI, no errors, ready to configure
```

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

### Example .env File for Ava AI Voice Agent

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/README.md

Sets up secrets and API keys required for the Ava AI Voice Agent. Ensure these are kept secure and not committed to version control.

```bash
OPENAI_API_KEY=sk-your-key-here
DEEPGRAM_API_KEY=your-key-here
ASTERISK_ARI_USERNAME=asterisk
ASTERISK_ARI_PASSWORD=your-password
```

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

### Start Local Hybrid Services (AI Server)

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/docs/FreePBX-Integration-Guide.md

Manually start the local AI server service for local hybrid configurations using Docker Compose. Ensure the server is healthy before starting the AI engine.

```bash
# Start local_ai_server first
docker compose -p asterisk-ai-voice-agent up -d local_ai_server

# Wait for health (first start may take 5-10 min to load models)
docker compose -p asterisk-ai-voice-agent logs -f local_ai_server

# Once healthy, start ai_engine
docker compose -p asterisk-ai-voice-agent up -d --build ai_engine
```

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

### Rebuild and start Admin UI container

Source: https://github.com/hkjarral/ava-ai-voice-agent-for-asterisk/blob/main/admin_ui/UI_Setup_Guide.md

Force a rebuild of the admin_ui container and start it in detached mode.

```bash
docker compose up -d --build admin_ui
```