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,73 @@
+# 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`.