ai-operator/docs/region-resolver.md

Region Resolver

Purpose

TZ-08 adds an offline Kazakhstan Region Resolver for the dialogue layer. It normalizes user text, maps Russian/Kazakh/Latin aliases to stable region_code values, and prevents the conversation from reaching READY_TO_HELP until a supported region is selected.

The resolver does not call external APIs, does not infer region from caller number, and does not use default region fallback.

Supported Active Regions

Active catalog size: 20 regions.

Republic cities:

• astana_city - Астана / Астана
• almaty_city - город Алматы / Алматы қаласы
• shymkent_city - Шымкент / Шымкент

Oblasts:

• akmola_region - Акмолинская область / Ақмола облысы
• aktobe_region - Актюбинская область / Ақтөбе облысы
• almaty_region - Алматинская область / Алматы облысы
• atyrau_region - Атырауская область / Атырау облысы
• east_kazakhstan_region - Восточно-Казахстанская область / Шығыс Қазақстан облысы
• zhambyl_region - Жамбылская область / Жамбыл облысы
• west_kazakhstan_region - Западно-Казахстанская область / Батыс Қазақстан облысы
• karaganda_region - Карагандинская область / Қарағанды облысы
• kostanay_region - Костанайская область / Қостанай облысы
• kyzylorda_region - Кызылординская область / Қызылорда облысы
• mangystau_region - Мангистауская область / Маңғыстау облысы
• pavlodar_region - Павлодарская область / Павлодар облысы
• north_kazakhstan_region - Северо-Казахстанская область / Солтүстік Қазақстан облысы
• turkistan_region - Туркестанская область / Түркістан облысы
• abai_region - область Абай / Абай облысы
• jetisu_region - область Жетісу / Жетісу облысы
• ulytau_region - область Ұлытау / Ұлытау облысы

Optional disabled special region:

• baikonur_special - Байконур / Байқоңыр, disabled by default.

Aliases And Normalization

The resolver supports RU, KK, Latin, abbreviations, legacy names, and ASR-ish spellings. Examples include нурсултан, нұр-сұлтан, alma-ata, shymkent, chimkent, ВКО, ЗКО, СКО, vko, zko, and sko.

Normalization trims spaces, lowercases, converts ё to е, treats hyphens as spaces, collapses repeated spaces, removes harmless punctuation, preserves Kazakh Cyrillic letters, and handles forms like г. Алматы, Алматы қаласы, and Алматинская обл..

Ambiguity

Bare Алматы and almaty are intentionally ambiguous because they can mean the city or Almaty region. The orchestrator stores pending candidates and asks:

• RU: Вы имеете в виду город Алматы или Алматинскую область?
• KK: Алматы қаласын айттыңыз ба, әлде Алматы облысын ба?

Then these clarifications are accepted:

• город, қала, Алматы қаласы -> almaty_city
• область, облыс, Алматинская область, Алматы облысы -> almaty_region

Selection Policy

• LANGUAGE_SELECTION: region mentions are ignored; language must be selected first.
• REGION_SELECTION: clear enabled region applies; ambiguous input asks clarification; unsupported region is denied.
• READY_TO_HELP and QUESTION_ANSWERING: region changes only on explicit request such as сменить регион на Астану.
• HANDOFF, CLOSING, ENDED: region changes are denied.

The hard guardrail remains in code: search_knowledge_base is denied unless language is ru or kk, region status is selected, region_code is non-empty, and state is READY_TO_HELP or QUESTION_ANSWERING.

Integration

Dialogue Orchestrator calls the resolver from HandleUserText and set_region tool handling. Stored region display names come from the catalog, not from tool arguments.

VoiceEventUserTranscriptDone continues to route through HandleUserText, so future ASR transcripts use the same resolver path. Assistant transcript and audio events do not trigger region changes.

CLI

Run resolver checks:

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

Run deterministic self-test without Asterisk, OpenAI, or DB:

./bin/ai-operator region-self-test --env /etc/ai-operator/ai-operator.env

Safety

TZ-08 does not change Asterisk configs, does not reload/restart Asterisk, does not call OpenAI, does not install PostgreSQL, and does not switch production routing.

Not Implemented Yet

• Knowledge Base / RAG
• final business prompt
• real business tools
• production route switching

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 Integration

The agent prompt keeps region selection as the second required action. Business questions in REGION_SELECTION must repeat the region request and must not trigger KB search. Region changes after readiness remain explicit-only.