154 lines
5.2 KiB
Markdown
154 lines
5.2 KiB
Markdown
# 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.
|