sync: migrate ai-operator to Gitea (2026-08-10)

2026-08-10 15:26:52 +00:00
commit 53652b95ad
173 changed files with 16676 additions and 0 deletions
@@ -0,0 +1,153 @@
+# 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.