.env.example

# Environment Variables
# Copy this file to .env and fill in your API keys
#
# Quick start:
#   cp .env.example .env
#   # Fill in all required sections below, then:
#   python main.py --debug   # runs 1 record to verify your setup
#
# Tip: To verify just the LLM configuration before setting up audio,
# you can run the text-only flow (no ElevenLabs/STT/TTS needed):
#   python scripts/run_text_only.py --record-id 1.1.2

# ==============================================
# API Configs
# ==============================================

# --- ElevenLabs ---
#i ElevenLabs API key for the user simulator.
#d secret
ELEVENLABS_API_KEY=your_elevenlabs_api_key_here

# --- LLM / Text Judge ---
#i OpenAI key for assistant LLM and text judge metrics.
#d secret
OPENAI_API_KEY=your_openai_api_key_here

# --- Audio Judge (Gemini via GCP) ---
#i Path to GCP service-account JSON for Gemini audio judge metrics.
#d path
GOOGLE_APPLICATION_CREDENTIALS=path/to/your/service-account-credentials.json

# --- Faithfulness Metric (Claude via Bedrock) ---
#i AWS access key for Claude via Bedrock (faithfulness metric).
#d secret
AWS_ACCESS_KEY_ID=your_aws_access_key_id_here

#i AWS secret access key.
#d secret
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key_here

# --- Alternative providers (optional) ---
# If you only have an OpenAI key you can skip AWS and set JUDGE_MODEL=gpt-5.2
# to override all text judges. Audio judge metrics still require Gemini.

#i Azure OpenAI key (alternative to direct OpenAI).
#d secret
#v AZURE_OPENAI_API_KEY=your_azure_openai_api_key_here

#i Azure OpenAI endpoint URL.
#d string
#v AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/

#i Google API key (alternative to service-account credentials for Gemini).
#d secret
#v GOOGLE_API_KEY=your_google_api_key_here

# ==============================================
# Voice Pipeline
# ==============================================

#i LLM model alias for the assistant. Must match a model_name in EVA_MODEL_LIST.
#d enum
#x pipeline_mode=LLM
EVA_MODEL__LLM=gpt-5.2

# Pipeline mode is controlled by the UI radio (LLM / S2S / AudioLLM).
# The #x conditions below ensure each variable is only active for the right mode.

# --- LLM mode: STT ---
#i STT provider for the voice pipeline.
#d enum
#e assemblyai,cartesia,cartesia-multilingual,deepgram,deepgram-flux,elevenlabs,nvidia,nvidia-baseten,openai,smallest,soniox
#x pipeline_mode=LLM
EVA_MODEL__STT=cartesia

#i STT provider parameters. Must include "api_key" and "model". Use "urls" for round-robin load balancing.
#i Some providers also accept extra provider-specific tuning parameters here.
#i AssemblyAI example (Universal-3 Pro family — conversation-context carryover is applied automatically
#i so the agent's last reply improves transcription of the user's next turn; set "previous_context_n_turns": 0 to disable).
#i Tuning fields (vad_threshold, min_turn_silence, max_turn_silence) forward to AssemblyAISTTService.Settings;
#i vad_force_turn_endpoint (default true = Pipecat forces the endpoint on VAD stop) is a constructor arg:
#i EVA_MODEL__STT_PARAMS='{"api_key": "your_assemblyai_api_key", "model": "universal-3-5-pro", "vad_threshold": 0.1, "min_turn_silence": 100, "max_turn_silence": 100, "vad_force_turn_endpoint": true}'
#i Soniox example — language_hints takes BCP-47 tags (converted to pipecat Language enums internally);
#i enable_speaker_diarization/enable_language_identification forward to SonioxSTTService.Settings:
#i EVA_MODEL__STT_PARAMS='{"api_key": "your_soniox_api_key", "model": "stt-rt-v5", "language_hints": ["en"], "enable_language_identification": true, "enable_speaker_diarization": true}'
#d json_object
#x pipeline_mode=LLM
EVA_MODEL__STT_PARAMS='{"api_key": "your_cartesia_api_key", "model": "ink-2"}'

# --- TTS (LLM and AudioLLM modes) ---
#i TTS provider for the voice pipeline.
#d enum
#e cartesia,chatterbox,deepgram,deepgram-flux,elevenlabs,gemini,kokoro,nvidia-baseten,openai,smallest,soniox,xtts
#x pipeline_mode=LLM,AudioLLM
EVA_MODEL__TTS=cartesia

#i TTS provider parameters. Must include "api_key" and "model". Use "urls" for round-robin load balancing, and "voice_id" to select a voice.
#i Some providers also accept extra provider-specific tuning parameters here.
#i Soniox example — omit "voice_id" to use pipecat's default voice ("Adrian"):
#i EVA_MODEL__TTS_PARAMS='{"api_key": "your_soniox_api_key", "model": "tts-rt-v2", "voice": "Sarah"}'
#i Deepgram Flux example (EVA_MODEL__TTS=deepgram-flux) — "voice" is the full flux-{voice}-{lang} model
#i string (defaults to "flux-alexis-en" if omitted); "model" is not used for Flux:
#i EVA_MODEL__TTS_PARAMS='{"api_key": "your_deepgram_api_key", "voice": "flux-haley-en"}'
#d json_object
#x pipeline_mode=LLM,AudioLLM
EVA_MODEL__TTS_PARAMS='{"api_key": "your_cartesia_api_key", "model": "sonic"}'

#i TTS gender for the voice pipeline. For use in gendered languages to ensure the LLM generates speech
#i which matches the gender of the TTS voice.
#d enum
#e M,F,none
#x pipeline_mode=LLM,AudioLLM
#v EVA_MODEL__ASSISTANT_GENDER=none

# --- LLM mode: cascade latency optimizations ---
#i Prompt a model-generated lead-in before a tool call: 'off' or 'auto'.
#d enum
#e off,auto
#x pipeline_mode=LLM,AudioLLM
#v EVA_MODEL__PRE_TOOL_SPEECH=off

#i Stream Chat Completions output to TTS sentence-by-sentence; Responses API falls back with a warning.
#d bool
#x pipeline_mode=LLM,AudioLLM
#v EVA_MODEL__LLM_STREAMING=false

#i Forward provider parallel_tool_calls when tools are present; leave unset for defaults.
#d bool
#x pipeline_mode=LLM,AudioLLM
#v EVA_MODEL__PARALLEL_TOOL_CALLS=false

# --- S2S mode ---
#i Speech-to-speech model name.
#d string
#x pipeline_mode=S2S
#v EVA_MODEL__S2S=openai

#i Speech-to-speech model parameters.
#d json_object
#x pipeline_mode=S2S
#v EVA_MODEL__S2S_PARAMS='{"model": "gpt-realtime-mini", "api_key": ""}'

# Smallest Hydra S2S (set EVA_FRAMEWORK=smallest_hydra). Hydra emits no transcript
# on the wire, so a batch STT transcribes each turn for the audit log; it defaults
# to Smallest Pulse keyed on the same api_key. Override via the "transcription" block
# (provider: smallest|openai|deepgram). voice: wren|sloane|marlowe|reed|knox|tate.
#x pipeline_mode=S2S
#v EVA_MODEL__S2S=hydra
#v EVA_MODEL__S2S_PARAMS='{"model": "hydra", "api_key": "", "voice": "wren", "generate_initial_response": true, "transcription": {"provider": "smallest", "model": "pulse-pro", "language": "en"}}'

# --- AudioLLM mode ---
#i Audio-input LLM model name.
#d string
#x pipeline_mode=AudioLLM
#v EVA_MODEL__AUDIO_LLM=

#i Audio-input LLM model parameters.
#d json_object
#x pipeline_mode=AudioLLM
#v EVA_MODEL__AUDIO_LLM_PARAMS='{"url": "", "api_key": ""}'

# --- Framework (S2S / AudioLLM) ---
#i Base framework for S2S or AudioLLM pipelines.
#d enum
#e pipecat,openai_realtime,gemini_live,elevenlabs,grok_voice,smallest_hydra
#v EVA_FRAMEWORK=openai_realtime

# ==============================================
# LiteLLM Deployments
# ==============================================

#i LiteLLM Router deployments. Use "os.environ/VAR_NAME" to reference other env vars.
#d json_deployment_list
EVA_MODEL_LIST='[
  {
    "model_name": "gpt-5.2",
    "litellm_params": {
      "model": "openai/gpt-5.2",
      "api_key": "os.environ/OPENAI_API_KEY",
      "max_parallel_requests": 5
    },
    "model_info": {"base_model": "gpt-5.2"}
  },
  {
    "model_name": "gemini-3.1-pro-preview",
    "litellm_params": {
      "model": "vertex_ai/gemini-3.1-pro-preview",
      "vertex_project": "your-gcp-project-id",
      "vertex_location": "global",
      "vertex_credentials": "os.environ/GOOGLE_APPLICATION_CREDENTIALS",
      "max_parallel_requests": 5
    }
  },
  {
    "model_name": "us.anthropic.claude-opus-4-6",
    "litellm_params": {
      "model": "bedrock/us.anthropic.claude-opus-4-6-v1",
      "aws_access_key_id": "os.environ/AWS_ACCESS_KEY_ID",
      "aws_secret_access_key": "os.environ/AWS_SECRET_ACCESS_KEY",
      "max_parallel_requests": 5
    }
  }
]'

# ==============================================
# Framework & Runtime
# ==============================================

#i Domain determines dataset, agent config, and scenario paths (data/{domain}_dataset.json etc).
#d enum
#e airline,itsm,medical_hr
#v EVA_DOMAIN=airline

#i Maximum number of concurrent conversations.
#d int
#r 1,100,1
#v EVA_MAX_CONCURRENT_CONVERSATIONS=1

#i Conversation time limit in seconds.
#d int
#r 30,10000,10
#v EVA_CONVERSATION_TIME_LIMIT_SECONDS=600

#i Seconds of user silence after the assistant stops speaking before nudging it to reprompt
#i the caller (Pipecat cascade + audio-LLM pipelines). Cancelled the moment the user starts
#i speaking, so it only fires on genuine silence when turn detection drops a user turn.
#i Leave unset to keep the old behavior of ending the conversation once the provider's
#i inactivity timeout elapses.
#d int
#r 1,120,1
#v EVA_TURN_END_FALLBACK_TIME=

#i Maximum rerun attempts for failed records.
#d int
#r 0,20,1
#v EVA_MAX_RERUN_ATTEMPTS=3

#i Output directory for results.
#d path
#v EVA_OUTPUT_DIR=output

#i Starting port for WebSocket servers.
#d int
#r 1024,65000,1
#v EVA_BASE_PORT=10000

#i Number of ports in the pool.
#d int
#r 10,500,1
#v EVA_PORT_POOL_SIZE=150

#i Comma-separated metric names to run. Leave empty to run all metrics.
#d csv_list
#v EVA_METRICS=

# ==============================================
# Turn Detection & VAD
# ==============================================

# Leave all of these inactive to use smart defaults.

#i Turn start strategy: when to consider the user has started speaking.
#d enum
#e vad,transcription,external
#v EVA_MODEL__TURN_START_STRATEGY=vad

#i Turn start strategy parameters (JSON).
#d json_object
#v EVA_MODEL__TURN_START_STRATEGY_PARAMS='{}'

#i Turn stop strategy: when to consider the user has finished speaking.
#i krisp_viva_turn uses Krisp's VIVA SDK turn detection v3 (streaming, frame-by-frame).
#i It needs the proprietary krisp_audio SDK installed plus KRISP_VIVA_TURN_MODEL_PATH
#i (path to a .kef model file) and KRISP_VIVA_API_KEY set below.
#d enum
#e turn_analyzer,speech_timeout,krisp_viva_turn,external
#v EVA_MODEL__TURN_STOP_STRATEGY=turn_analyzer

#i Turn stop strategy parameters. For speech_timeout: {"user_speech_timeout": 0.8}.
#i For krisp_viva_turn: {"threshold": 0.5, "frame_duration_ms": 20} (model_path/api_key
#i can also be passed here to override the env vars).
#d json_object
#v EVA_MODEL__TURN_STOP_STRATEGY_PARAMS='{}'

#i Krisp VIVA SDK credentials (only used when TURN_STOP_STRATEGY=krisp_viva_turn).
#i The turn model ships in the Krisp VIVA "Turn-Taking models" download (krisp-viva-tt-models);
#i point at the krisp-viva-tp-v3.kef file. VAD is supplied by Silero, so no Krisp VAD model needed.
#v KRISP_VIVA_TURN_MODEL_PATH=vendor/krisp/krisp-viva-tp-v3.kef
#v KRISP_VIVA_API_KEY=your_krisp_license_key

#i VAD (Voice Activity Detection) analyzer.
#d enum
#e silero,none
#v EVA_MODEL__VAD=silero

#i VAD parameters. Keys: confidence (0-1), start_secs, stop_secs, min_volume (0-1).
#d json_object
#v EVA_MODEL__VAD_PARAMS='{"start_secs": 0.2, "stop_secs": 0.2, "min_volume": 0.6, "confidence": 0.7}'

# ==============================================
# User Config
# ==============================================

# --- User simulator provider ---
#i Caller provider. ElevenLabs is the backward-compatible default.
#d enum
#e elevenlabs,openai_realtime
EVA_USER_SIMULATOR__PROVIDER=elevenlabs

#i OpenAI Realtime caller model. Used only when provider=openai_realtime.
#d string
#x EVA_USER_SIMULATOR__PROVIDER=openai_realtime
#v EVA_USER_SIMULATOR__MODEL=gpt-realtime-1.5

#i OpenAI voice for the female caller persona.
#d string
#x EVA_USER_SIMULATOR__PROVIDER=openai_realtime
#v EVA_USER_SIMULATOR__FEMALE_VOICE=marin

#i OpenAI voice for the male caller persona.
#d string
#x EVA_USER_SIMULATOR__PROVIDER=openai_realtime
#v EVA_USER_SIMULATOR__MALE_VOICE=cedar

# --- Language (mutually exclusive with Accent and Behavior) ---
#i ISO 639-1 language code for the user simulator. Datasets must exist for the selected language. Pattern for the agent ID pairs below: EVA_{LANG}_USER_{F|M}.
#d enum
#e en,fr,fr-CA,es,de,hi,ko,nl,it,ja
#x perturbation_mode=Language
#v EVA_LANGUAGE=en

# --- Language agent IDs ---
#i ElevenLabs agent ID — Dutch, female voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=nl
#v EVA_NL_USER_F=

#i ElevenLabs agent ID — Dutch, male voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=nl
#v EVA_NL_USER_M=

#i ElevenLabs agent ID — Italian, female voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=it
#v EVA_IT_USER_F=

#i ElevenLabs agent ID — Italian, male voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=it
#v EVA_IT_USER_M=

#i ElevenLabs agent ID — Japanese, female voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=ja
#v EVA_JA_USER_F=

#i ElevenLabs agent ID — Japanese, male voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=ja
#v EVA_JA_USER_M=

#i ElevenLabs agent ID — Korean, female voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=ko
#v EVA_KO_USER_F=

#i ElevenLabs agent ID — Korean, male voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=ko
#v EVA_KO_USER_M=

#i ElevenLabs agent ID — Hindi, female voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=hi
#v EVA_HI_USER_F=

#i ElevenLabs agent ID — Hindi, male voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=hi
#v EVA_HI_USER_M=

#i ElevenLabs agent ID — German, female voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=de
#v EVA_DE_USER_F=

#i ElevenLabs agent ID — German, male voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=de
#v EVA_DE_USER_M=

#i ElevenLabs agent ID — Spanish, female voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=es
#v EVA_ES_USER_F=

#i ElevenLabs agent ID — Spanish, male voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=es
#v EVA_ES_USER_M=

#i ElevenLabs agent ID — Canadian French, female voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=fr-CA
#v EVA_FR_CA_USER_F=

#i ElevenLabs agent ID — Canadian French, male voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=fr-CA
#v EVA_FR_CA_USER_M=

#i ElevenLabs agent ID — European French, female voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=fr
#v EVA_FR_USER_F=

#i ElevenLabs agent ID — European French, male voice.
#d string
#x perturbation_mode=Language
#x EVA_LANGUAGE=fr
#v EVA_FR_USER_M=

#i ElevenLabs agent ID — English (default), female voice.
#d string
EVA_EN_USER_F=your_elevenlabs_agent_id_for_default_user_f

#i ElevenLabs agent ID — English (default), male voice.
#d string
EVA_EN_USER_M=your_elevenlabs_agent_id_for_default_user_m

# --- Perturbations ---
# accent and behavior are MUTUALLY EXCLUSIVE (each claims the agent ID slot).
# background_noise and connection_degradation can stack with either.

# --- Background noise ---
# Requires assets in assets/noise/. Download with: python scripts/download_noise_assets.py
#i Ambient noise to mix into user speech.
#d enum
#e airport_gate,baby_crying,background_music,bad_connection_static,coffee_shop,loud_construction,nyc_street,road_noise
#x background_noise_enabled=true
#v EVA_PERTURBATION__BACKGROUND_NOISE=coffee_shop

#i Signal-to-noise ratio in dB. Higher = cleaner user speech.
#d float
#r 0,40,1
#x background_noise_enabled=true
#v EVA_PERTURBATION__SNR_DB=15

# --- Connection degradation ---
#i Apply G.711 codec + gaussian static + 3% packet loss + random gain.
#d bool
#v EVA_PERTURBATION__CONNECTION_DEGRADATION=false

# --- Accent (mutually exclusive with Behavior) ---
#i Accent to apply to the user simulator. Requires matching agent IDs below.
#d enum
#e french,indian,spanish,chinese
#x perturbation_mode=Accent
#v EVA_PERTURBATION__ACCENT=french

# --- Accent agent IDs ---
#i ElevenLabs agent ID — French accent, female voice.
#d string
#x perturbation_mode=Accent
#x EVA_PERTURBATION__ACCENT=french
#v EVA_FRENCH_ACCENT_USER_F=

#i ElevenLabs agent ID — French accent, male voice.
#d string
#x perturbation_mode=Accent
#x EVA_PERTURBATION__ACCENT=french
#v EVA_FRENCH_ACCENT_USER_M=

#i ElevenLabs agent ID — Indian accent, female voice.
#d string
#x perturbation_mode=Accent
#x EVA_PERTURBATION__ACCENT=indian
#v EVA_INDIAN_ACCENT_USER_F=

#i ElevenLabs agent ID — Indian accent, male voice.
#d string
#x perturbation_mode=Accent
#x EVA_PERTURBATION__ACCENT=indian
#v EVA_INDIAN_ACCENT_USER_M=

#i ElevenLabs agent ID — Spanish accent, female voice.
#d string
#x perturbation_mode=Accent
#x EVA_PERTURBATION__ACCENT=spanish
#v EVA_SPANISH_ACCENT_USER_F=

#i ElevenLabs agent ID — Spanish accent, male voice.
#d string
#x perturbation_mode=Accent
#x EVA_PERTURBATION__ACCENT=spanish
#v EVA_SPANISH_ACCENT_USER_M=

#i ElevenLabs agent ID — Chinese accent, female voice.
#d string
#x perturbation_mode=Accent
#x EVA_PERTURBATION__ACCENT=chinese
#v EVA_CHINESE_ACCENT_USER_F=

#i ElevenLabs agent ID — Chinese accent, male voice.
#d string
#x perturbation_mode=Accent
#x EVA_PERTURBATION__ACCENT=chinese
#v EVA_CHINESE_ACCENT_USER_M=

# --- Behavior (mutually exclusive with Accent) ---
#i Behavior persona for the user simulator. Requires matching agent IDs below.
#d enum
#e aggressive_impatient,elderly_slow,forgetful_disorganized
#x perturbation_mode=Behavior
#v EVA_PERTURBATION__BEHAVIOR=forgetful_disorganized

# --- Behavior agent IDs ---
#i ElevenLabs agent ID — Aggressive/impatient persona, female voice.
#d string
#x perturbation_mode=Behavior
#x EVA_PERTURBATION__BEHAVIOR=aggressive_impatient
#v EVA_AGGRESSIVE_IMPATIENT_USER_F=

#i ElevenLabs agent ID — Aggressive/impatient persona, male voice.
#d string
#x perturbation_mode=Behavior
#x EVA_PERTURBATION__BEHAVIOR=aggressive_impatient
#v EVA_AGGRESSIVE_IMPATIENT_USER_M=

#i ElevenLabs agent ID — Elderly/slow persona, female voice.
#d string
#x perturbation_mode=Behavior
#x EVA_PERTURBATION__BEHAVIOR=elderly_slow
#v EVA_ELDERLY_SLOW_USER_F=

#i ElevenLabs agent ID — Elderly/slow persona, male voice.
#d string
#x perturbation_mode=Behavior
#x EVA_PERTURBATION__BEHAVIOR=elderly_slow
#v EVA_ELDERLY_SLOW_USER_M=

#i ElevenLabs agent ID — Forgetful/disorganized persona, female voice.
#d string
#x perturbation_mode=Behavior
#x EVA_PERTURBATION__BEHAVIOR=forgetful_disorganized
#v EVA_FORGETFUL_DISORGANIZED_USER_F=

#i ElevenLabs agent ID — Forgetful/disorganized persona, male voice.
#d string
#x perturbation_mode=Behavior
#x EVA_PERTURBATION__BEHAVIOR=forgetful_disorganized
#v EVA_FORGETFUL_DISORGANIZED_USER_M=

# ==============================================
# Debug & Logging
# ==============================================

#i Run only 1 record regardless of dataset size.
#d bool
#v EVA_DEBUG=false

#i Comma-separated record IDs to run. Empty = run all.
#d csv_list
#v EVA_RECORD_IDS=

#i Comma-separated record IDs to skip (applied after EVA_RECORD_IDS). Empty = skip none.
#d csv_list
#v EVA_EXCLUDE_RECORD_IDS=

#i Logging verbosity.
#d enum
#e DEBUG,INFO,WARNING,ERROR,CRITICAL
#v EVA_LOG_LEVEL=INFO