151 lines
6.0 KiB
Markdown
151 lines
6.0 KiB
Markdown
# 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
|
|
|
|
```sh
|
|
make build
|
|
```
|
|
|
|
## Test
|
|
|
|
```sh
|
|
make fmt
|
|
make test
|
|
```
|
|
|
|
## Doctor
|
|
|
|
```sh
|
|
./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
|
|
|
|
```sh
|
|
./bin/ai-operator run --env /etc/ai-operator/ai-operator.env --dry-run
|
|
```
|
|
|
|
## Runtime Env
|
|
|
|
The server env file is expected at:
|
|
|
|
```text
|
|
/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
|
|
|
|
```sh
|
|
./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
|
|
|
|
```sh
|
|
./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
|
|
|
|
```sh
|
|
./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
|
|
|
|
```sh
|
|
./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`.
|
|
|
|
```sh
|
|
./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:
|
|
|
|
```sh
|
|
./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.
|
|
|
|
```bash
|
|
./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.
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
./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.
|