ai-operator/README.md

AI Operator

Go skeleton for an Asterisk-based AI call-center operator.

Current status: skeleton only. The project does not accept live calls, does not connect to ARI events, does not create media channels, and does not call OpenAI.

Build

make build

Test

make fmt
make test

Doctor

./bin/ai-operator doctor --env /etc/ai-operator/ai-operator.env

The doctor command validates local-only ARI configuration and checks authenticated HTTP 200 plus unauthenticated HTTP 401.

Dry Run

./bin/ai-operator run --env /etc/ai-operator/ai-operator.env --dry-run

Runtime Env

The server env file is expected at:

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

Do not commit real secrets. Use .env.example as the only repository env template.

Next Steps

• TZ-02: Asterisk inbound routing preparation.
• TZ-03: ARI Call Manager.
• TZ-04: Media Gateway.
• TZ-05: Voice Provider Adapter.

ARI Observe-only

./bin/ai-operator run --env /etc/ai-operator/ai-operator.env --ari-events --observe-only

This registers ARI app ai-operator and reads events without answering or hanging up channels.

ARI Test Call-control

./bin/ai-operator run --env /etc/ai-operator/ai-operator.env --ari-events --call-control --test-call-hangup-after 5s

Call-control is limited to the test route Stasis(ai-operator,test). Media and OpenAI are not implemented in TZ-03.

Media Self-test

./bin/ai-operator media-self-test --env /etc/ai-operator/ai-operator.env --duration 3s

This creates a temporary Asterisk externalMedia WebSocket channel, connects to /media/{connection_id}, waits for MEDIA_START, sends GET_STATUS, and cleans up. It does not make a real phone call and does not record audio.

ARI Media Test Mode

./bin/ai-operator run --env /etc/ai-operator/ai-operator.env --ari-events --call-control --media --media-test-mode stats --test-call-hangup-after 10s

This is restricted to the test route Stasis(ai-operator,test). Production Kazakhtelecom routes remain disabled.

Voice Provider

Default provider is fake. Live modes are explicit: openai_realtime or pipeline_elevenlabs_streaming. The ElevenLabs streaming pipeline requires ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID_RU, and OPENAI_API_KEY.

./bin/ai-operator voice-provider-self-test --env /etc/ai-operator/ai-operator.env --provider fake
./bin/ai-operator doctor --env /etc/ai-operator/ai-operator.env --check-openai-config
./bin/ai-operator pipeline-streaming-self-test --env /etc/ai-operator/ai-operator.env

Live ElevenLabs streaming test command:

./bin/ai-operator run --env /etc/ai-operator/ai-operator.env --ari-events --call-control --media --voice-provider pipeline_elevenlabs_streaming --media-test-mode stats --test-call-hangup-after 180s

Conversation State Machine

TZ-06 adds a code-enforced conversation state machine. The current live behavior is natural dialogue: language can be inferred from caller speech, and global KB search is allowed without a selected region. Region is requested only for regional questions.

./bin/ai-operator doctor --env /etc/ai-operator/ai-operator.env --check-dialogue
./bin/ai-operator dialogue-self-test --env /etc/ai-operator/ai-operator.env

The state machine uses the fake provider by default and does not call OpenAI.

Language Selection

TZ-07 adds a language detector for Russian and Kazakh. It supports codes, Cyrillic/Latin phrases, ASR-like variants, ambiguity detection, and false-positive protection.

./bin/ai-operator doctor --env /etc/ai-operator/ai-operator.env --check-language
./bin/ai-operator language-self-test --env /etc/ai-operator/ai-operator.env

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 behind the existing language/region guardrail. OpenAI is not called automatically and production routing remains disabled.

TZ-10 Agent Prompt and Tools

Agent Prompt and Tools are implemented for safe test mode. The live operator is Жанна, AI-operator of QazAimaqGas. The prompt no longer uses IVR-style language/region selection: language is inferred from caller speech, global KB can be searched without region, and region is requested only for regional branch/address/contact questions. search_knowledge_base returns answer_text, citations, no-answer behavior, and cross-language fallback metadata. VoiceProvider ToolCall events are relayed through Dialogue Orchestrator and ToolResults are sent back to the provider.

Offline validation:

./bin/ai-operator agent-self-test --env /etc/ai-operator/ai-operator.env
./bin/ai-operator natural-dialogue-self-test --env /etc/ai-operator/ai-operator.env

TZ-11 Human Handoff / Fallback

Human Handoff / Fallback is implemented in safe default mode. HANDOFF_MODE=disabled_stub and HANDOFF_ENABLED=false record the handoff request and move the conversation to HANDOFF without real transfer. ARI redirect and dialplan continue actions exist behind config gates and are covered by tests.

Safe validation:

./bin/ai-operator handoff-self-test --env /etc/ai-operator/ai-operator.env
./bin/ai-operator fallback-self-test --env /etc/ai-operator/ai-operator.env

TZ-12 Logging, Transcripts and Audit

Audit logging now uses PostgreSQL tables from migrations/003_audit_tables.sql. Use audit-health, audit-self-test, redaction-self-test, audit-show-call, audit-export-call, audit-prune --dry-run, and doctor --check-audit. Raw transcripts/audio and secrets are not stored by default.