Environment

Default env file:

/etc/ai-operator/ai-operator.env

Priority:

CLI --env.
AI_OPERATOR_ENV_FILE.
/etc/ai-operator/ai-operator.env.

Required:

APP_ENV: dev, staging, or prod.
LOG_LEVEL: debug, info, warn, or error.
ASTERISK_ARI_URL: must be localhost HTTP.
ASTERISK_ARI_WS_URL: must be localhost WebSocket.
ASTERISK_ARI_USER.
ASTERISK_ARI_PASSWORD.
ASTERISK_ARI_APP.
ASTERISK_ARI_WS_AUTH_MODE: optional, defaults to basic; allowed basic, query_api_key, auto.
ASTERISK_MEDIA_MODE: expected chan_websocket for MVP.
ASTERISK_MEDIA_CODEC: expected slin16 for MVP.

Optional for now:

OPENAI_API_KEY.
OPENAI_REALTIME_MODEL.
OPENAI_REALTIME_INITIAL_GREETING: defaults to true; live OpenAI calls create an audible natural Жанна greeting after session setup.
DATABASE_URL.

Example without real secrets:

APP_ENV=dev
LOG_LEVEL=debug
ASTERISK_ARI_URL=http://127.0.0.1:8088/ari
ASTERISK_ARI_WS_URL=ws://127.0.0.1:8088/ari/events
ASTERISK_ARI_USER=ai_operator
ASTERISK_ARI_PASSWORD=CHANGE_ME
ASTERISK_ARI_APP=ai-operator
ASTERISK_ARI_WS_AUTH_MODE=basic
ASTERISK_MEDIA_MODE=chan_websocket
ASTERISK_MEDIA_CODEC=slin16
OPENAI_API_KEY=
OPENAI_REALTIME_MODEL=
DATABASE_URL=

Voice Provider / OpenAI

VOICE_PROVIDER defaults to fake. Allowed values are fake, openai_realtime, pipeline_elevenlabs, and pipeline_elevenlabs_streaming. OPENAI_API_KEY is optional for build, tests, and doctor. It is required only for live OpenAI modes and explicit smoke commands.

ElevenLabs Streaming Pipeline

The low-latency live pipeline uses pipeline_elevenlabs_streaming:

STT_PROVIDER=elevenlabs
ELEVENLABS_STT_MODE=realtime
ELEVENLABS_STT_MODEL=scribe_realtime_v2
ELEVENLABS_STT_LANGUAGE_AUTO=true
ELEVENLABS_STT_SAMPLE_RATE=16000
ELEVENLABS_STT_INPUT_FORMAT=pcm_16000
ELEVENLABS_STT_PARTIAL_ENABLED=true
ELEVENLABS_STT_COMMITTED_ONLY_FOR_LLM=true

LLM_PROVIDER=openai
LLM_MODEL=gpt-4.1-nano
LLM_STREAM=true
LLM_FIRST_CHUNK_TIMEOUT_MS=1200
LLM_STREAM_CHUNK_MIN_CHARS=30
LLM_STREAM_CHUNK_MAX_CHARS=160

ELEVENLABS_API_KEY=
ELEVENLABS_VOICE_ID_RU=
ELEVENLABS_VOICE_ID_KK=
ELEVENLABS_TTS_MODE=websocket
ELEVENLABS_TTS_MODEL_ID=eleven_flash_v2_5
ELEVENLABS_TTS_OUTPUT_FORMAT=pcm_16000
ELEVENLABS_TTS_SAMPLE_RATE=16000

VOICE_NATURALNESS_ENABLED=true
VOICE_AUDIO_TAGS_ENABLED=true
VOICE_AUDIO_TAGS_MODE=controlled
VOICE_ALLOW_COUGH=false

PIPELINE_INITIAL_GREETING=true
PIPELINE_BARGE_IN=true
PIPELINE_FLUSH_ON_USER_SPEECH=true
PIPELINE_TTS_START_AFTER_CHARS=60
PIPELINE_TTS_START_AFTER_PUNCTUATION=true

Live pipeline_elevenlabs_streaming requires ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID_RU, and OPENAI_API_KEY. If ELEVENLABS_VOICE_ID_KK is empty, the RU voice is used for Kazakh with a sanitized warning.

Dialogue Variables

DIALOGUE_DEFAULT_LANGUAGE=
DIALOGUE_DEFAULT_REGION_CODE=
DIALOGUE_ENFORCE_LANGUAGE_REGION=false
AGENT_NAME=Жанна
AGENT_COMPANY=QazAimaqGas
AGENT_INITIAL_GREETING_MODE=natural
AGENT_REQUIRE_EXPLICIT_LANGUAGE=false
AGENT_REQUIRE_REGION_BEFORE_HELP=false
AGENT_ALLOW_GLOBAL_KB_WITHOUT_REGION=true

The live operator now uses a natural Жанна/QazAimaqGas flow: language is inferred from speech, global KB can be searched without a selected region, and region is requested only for regional questions.

Language Selection Variables

LANGUAGE_SELECTION_ENABLED=false
LANGUAGE_CONFIDENCE_THRESHOLD=0.70
LANGUAGE_CHANGE_CONFIDENCE_THRESHOLD=0.90
LANGUAGE_ALLOW_CHANGE_AFTER_SELECTION=true
LANGUAGE_DEFAULT_ON_TIMEOUT=

Classic IVR-style language selection is disabled for live dialogue. Explicit language-change phrases are still supported.

TZ-08 Region Resolver Update

TZ-08 adds an offline Kazakhstan Region Resolver with 20 enabled regions, stable region_code values, Almaty city/region clarification, false-positive protection, and explicit region-change policy. Production routing remains disabled; OpenAI, PostgreSQL, and Knowledge Base/RAG are still not used at this stage.

TZ-09 Knowledge Base Update

TZ-09 adds PostgreSQL + pgvector, KGA JSONL ingestion, fake embeddings, hybrid KB search, cross-language fallback for KK queries, citations, and search_knowledge_base integration. In natural dialogue mode, global KB search is allowed without a selected region; regional branch/address/contact questions ask for region first. OpenAI is not called automatically and production routing remains disabled.

TZ-10 Agent Prompt and Tools

No new required environment variables were added in TZ-10. DATABASE_URL is required for agent-self-test because it validates real KB search. OPENAI_API_KEY is only required for explicit OpenAI smoke commands and is not needed for fake-provider validation.

TZ-11 Handoff / Fallback

Default handoff settings are safe and do not transfer calls:

HANDOFF_MODE=disabled_stub
HANDOFF_ENABLED=false
HANDOFF_ALLOW_IN_TEST_ROUTE_ONLY=true

Real transfer modes require explicit target configuration and must remain disabled until approved.

Audit Environment

TZ-12 adds AUDIT_* retention, transcript storage and redaction settings. Defaults are safe: audit enabled, PostgreSQL sink, fail-open, raw transcripts disabled, redacted transcripts enabled, full phone/IIN/card logging disabled.

5.2 KiB Raw Permalink Blame History