# Environment

Default env file:

```text
/etc/ai-operator/ai-operator.env
```

Priority:

1. CLI `--env`.
2. `AI_OPERATOR_ENV_FILE`.
3. `/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:

```text
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`:

```env
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

```env
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

```env
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:

```env
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.