74 lines
3.6 KiB
Markdown
74 lines
3.6 KiB
Markdown
# Architecture
|
|
|
|
Target architecture:
|
|
|
|
```text
|
|
Kazakhtelecom SIP
|
|
-> Asterisk / PJSIP
|
|
-> inbound dialplan
|
|
-> Stasis(ai-operator)
|
|
-> Go AI Operator
|
|
-> ARI Call Manager
|
|
-> chan_websocket Media Gateway
|
|
-> Voice Provider Adapter
|
|
-> OpenAI Realtime or future provider
|
|
-> Knowledge Base / RAG
|
|
```
|
|
|
|
TZ-01 status:
|
|
|
|
- Stasis route is not enabled.
|
|
- Media gateway is not implemented.
|
|
- OpenAI provider is not implemented.
|
|
- Knowledge Base / RAG is not implemented.
|
|
- Live call handling is disabled.
|
|
|
|
Created package boundaries:
|
|
|
|
- `internal/asterisk/ari`: local ARI health-check client.
|
|
- `internal/call`: call session, language, and state types.
|
|
- `internal/media`: media gateway interfaces and audio chunk types.
|
|
- `internal/ai`: voice provider interfaces and events.
|
|
- `internal/dialogue`: orchestrator interface and skeleton stub.
|
|
- `internal/knowledge`: search repository interface.
|
|
- `internal/tools`: future tool names.
|
|
|
|
## TZ-03 status
|
|
|
|
The Go service can register ARI app `ai-operator`, read ARI events, parse Stasis and hangup lifecycle events, and manage in-memory sessions. Media Gateway, OpenAI provider, and production route switching are still not implemented.
|
|
|
|
## TZ-04 status
|
|
|
|
The service can create ARI externalMedia WebSocket channels, connect to `/media/{connection_id}`, parse media control events, send media control commands, and collect basic media stats. OpenAI and production routing remain disabled.
|
|
|
|
## TZ-05 status
|
|
|
|
The service now has a replaceable VoiceProvider layer with a fake provider and OpenAI Realtime skeleton. OpenAI remains behind an adapter. Conversation policy, language/region flow, tools execution, and RAG are not implemented yet.
|
|
|
|
## TZ-06 Conversation Layer
|
|
|
|
Call Manager now delegates dialogue state to `internal/dialogue`. The state machine enforces language and region selection before any knowledge-base or business-tool flow. Production routing remains unchanged.
|
|
|
|
## TZ-07 Language Selection
|
|
|
|
`internal/dialogue/language` normalizes user text, detects Russian/Kazakh choices, and applies state-aware selection policy. It feeds the Dialogue Orchestrator, which stores strict `ru`/`kk` only.
|
|
|
|
## 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
|
|
|
|
The agent behavior layer sits above Dialogue Orchestrator and below VoiceProvider. It builds the final state-aware prompt, formats KB-grounded answers, preserves no-hallucination behavior, and relays VoiceProvider ToolCall results back through `SendToolResult`.
|
|
## TZ-11 Human Handoff / Fallback
|
|
|
|
The handoff layer sits beside Dialogue Orchestrator. User requests for an operator are detected from transcript text or tool calls, converted into structured handoff requests, policy-gated, and executed by a safe executor. Default mode is `disabled_stub`.
|
|
|
|
|
|
## TZ-12 Audit Layer
|
|
|
|
The audit layer records call lifecycle, state transitions, redacted transcript events, tool calls, KB searches, handoff/fallback events, provider/media stats, exports and retention dry-runs through `internal/audit`.
|