.env.example

# CAAL Voice Framework Configuration
# Copy to .env and update values

# =============================================================================
# Platform - Choose your hardware
# =============================================================================
#
# NVIDIA GPU (Linux):
#   - Run: docker compose up -d
#   - Uses Speaches (CUDA) for STT, Kokoro (CUDA) for TTS
#
# Apple Silicon (M1/M2/M3/M4):
#   - Run: docker compose -f docker-compose.apple.yaml up -d
#   - Uses mlx-audio on host for STT/TTS (Metal acceleration)
#   - See "Apple Silicon Setup" section below
#
# =============================================================================
# Network Configuration
# =============================================================================
#
# HTTPS is enabled by default. Self-signed certificates are auto-generated
# if none exist in ./certs/. This is required because browsers block
# microphone access on HTTP (except localhost).
#
# Setup:
#   1. Set CAAL_HOST_IP to your LAN IP
#   2. Run: docker compose up -d
#   3. Access: https://<CAAL_HOST_IP>:3443
#
# First-time HTTPS setup:
#   Accept the self-signed certificate warning at https://<CAAL_HOST_IP>:3443
#   and voice will work from any device on your network.
#
# Tailscale (remote access):
#   1. Set CAAL_HOST_IP to your Tailscale IP (tailscale ip -4)
#   2. Uncomment HTTPS_DOMAIN and set to your Tailscale domain
#   3. Generate certs: tailscale cert <domain> (put in ./certs/)
#   4. Access: https://<TAILSCALE_DOMAIN>:3443
#
# Trusted certs (no browser warnings):
#   Use mkcert: mkcert -install && mkcert <IP>
#   Copy <IP>.pem to certs/server.crt and <IP>-key.pem to certs/server.key
#
# -----------------------------------------------------------------------------

# Your machine's IP address (required)
# Find it: ip addr show | grep "inet " | grep -v 127.0.0.1
CAAL_HOST_IP=192.168.1.100

# HTTPS domain - only needed for Tailscale where domain differs from IP
# For LAN use, leave commented (auto-derived from CAAL_HOST_IP)
#HTTPS_DOMAIN=your-machine.tailnet.ts.net

# TURN TLS port for remote WebRTC connectivity (only used with HTTPS_DOMAIN)
# Default 443 is required for iOS/mobile. Change only if 443 is already in use.
#TURN_TLS_PORT=443

# =============================================================================
# LiveKit Configuration
# =============================================================================
LIVEKIT_URL=ws://localhost:7880
# IMPORTANT: These keys must match those in livekit.yaml and livekit-tailscale.yaml.template
# For production, generate new keys: docker run --rm livekit/livekit-server generate-keys
LIVEKIT_API_KEY=devkey
LIVEKIT_API_SECRET=secret

# =============================================================================
# STT Configuration (Speaches - Faster-Whisper)
# =============================================================================
# URL for Speaches STT server (localhost for local dev, docker-compose overrides)
SPEACHES_URL=http://localhost:8000

# Whisper model for STT (full HuggingFace name)
WHISPER_MODEL=Systran/faster-whisper-medium

# GPU ID to bind Speaches to (multi-GPU hosts). Default: 0
# Find IDs with: nvidia-smi -L
#SPEACHES_GPU_ID=0

# =============================================================================
# TTS Configuration (Kokoro via remsky/kokoro-fastapi)
# =============================================================================
# URL for Kokoro TTS server (localhost for local dev, docker-compose overrides)
KOKORO_URL=http://localhost:8880

# Kokoro voice for TTS
# Options: af_heart, af_bella, af_sarah (female), am_adam, am_puck (male)
TTS_VOICE=am_puck

# GPU ID to bind Kokoro to (multi-GPU hosts). Default: 0
# Set to a different ID than your local Ollama (CUDA_VISIBLE_DEVICES) to avoid OOM.
#KOKORO_GPU_ID=0

# =============================================================================
# LLM Configuration
# =============================================================================
# Choose your LLM provider: "ollama" (local), "groq" (cloud), "openrouter" (cloud), or "openai_compatible"
LLM_PROVIDER=ollama

# =============================================================================
# LLM - Ollama (Local)
# =============================================================================
# Ollama server URL
# - If Ollama runs on the same machine as Docker: http://host.docker.internal:11434
# - If Ollama runs on a different machine: http://<OLLAMA_IP>:11434
# NOTE: Don't use localhost - it won't work from inside Docker containers
OLLAMA_HOST=http://host.docker.internal:11434

# Model name (ministral-3:8b recommended for tool calling + low latency. Requires Ollama 0.13.3+)
OLLAMA_MODEL=ministral-3:8b

# Disable thinking mode for lower latency (important for voice!)
OLLAMA_THINK=false
OLLAMA_TEMPERATURE=0.15
# Context window size (default 8192, increase for better tool response handling)
OLLAMA_NUM_CTX=8192
# Max conversation turns to keep in sliding window (prevents context overflow)
OLLAMA_MAX_TURNS=20

# Number of tool responses to cache for follow-up queries
TOOL_CACHE_SIZE=3

# =============================================================================
# LLM - Groq (Cloud)
# =============================================================================
# Get your API key from https://console.groq.com/keys
# Required when LLM_PROVIDER=groq
GROQ_API_KEY=

# Groq model (see https://console.groq.com/docs/models)
# Recommended: llama-3.3-70b-versatile (best quality, good for tool calling)
# Alternatives: llama-3.1-8b-instant (faster), mixtral-8x7b-32768
GROQ_MODEL=llama-3.3-70b-versatile

# =============================================================================
# LLM - OpenRouter (Cloud)
# =============================================================================
# Unified API for 200+ LLM models. Get your API key from https://openrouter.ai/keys
# Required when LLM_PROVIDER=openrouter
OPENROUTER_API_KEY=
OPENROUTER_MODEL=google/gemini-2.0-flash-001

# =============================================================================
# LLM - OpenAI-Compatible (Any Provider)
# =============================================================================
# Connect to any OpenAI-compatible API (vLLM, LM Studio, text-generation-inference, etc.)
# Required when LLM_PROVIDER=openai_compatible
OPENAI_API_KEY=
OPENAI_BASE_URL=http://localhost:8000/v1
OPENAI_MODEL=

# =============================================================================
# MCP Server Configuration
# =============================================================================
# n8n is the foundational MCP server, configured here in .env
# Additional MCP servers can be configured in mcp_servers.json (see mcp_servers.json.example)

# n8n MCP endpoint URL (required for workflow tools)
N8N_MCP_URL=http://192.168.1.100:5678/mcp-server/http

# n8n MCP access token (required - get from n8n Settings > MCP Access)
N8N_MCP_TOKEN=your_n8n_mcp_token_here

# =============================================================================
# Wake Word Detection (Picovoice Porcupine)
# =============================================================================
# Get your access key from https://console.picovoice.ai/
# Leave empty to disable wake word feature
# Also requires hey_cal.ppn and porcupine_params.pv in frontend/public/
PORCUPINE_ACCESS_KEY=

# =============================================================================
# General
# =============================================================================
# IANA timezone ID - see: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
TIMEZONE=America/Los_Angeles
# Display name spoken by CAAL (optional, defaults to "Pacific Time")
TIMEZONE_DISPLAY=Pacific Time

# =============================================================================
# Chat API (Headless Mode)
# =============================================================================
# System prompt for the /api/chat endpoint. Resolves to prompt/{language}/{CHAT_PROMPT}.md
# "headless" uses text-optimized formatting (numbers, dates, markdown).
# Leave unset to use the default voice prompt.
#CHAT_PROMPT=headless

# =============================================================================
# Apple Silicon Setup (M1/M2/M3/M4)
# =============================================================================
# Docker can't access Metal GPU, so STT/TTS run on host via mlx-audio.
# See README.md for full setup instructions.
#
# 1. Install: pip install "mlx-audio[all]"
# 2. Start server: python -m mlx_audio.server --host 0.0.0.0 --port 8001
# 3. Pre-load models:
#    curl -X POST "http://localhost:8001/v1/models?model_name=mlx-community/whisper-medium-mlx"
#    curl -X POST "http://localhost:8001/v1/models?model_name=prince-canuma/Kokoro-82M"
# 4. Run: docker compose -f docker-compose.apple.yaml up -d
#
# mlx-audio URL (defaults to host.docker.internal:8001 for local Mac)
# MLX_AUDIO_URL=http://host.docker.internal:8001
#
# Optional: Override default MLX models
# WHISPER_MODEL=mlx-community/whisper-medium-mlx
# TTS_MODEL=prince-canuma/Kokoro-82M
#
# Other whisper options: whisper-tiny, whisper-small, whisper-large-v3-turbo