Using the API

Languages & dialects

English, Arabic dialects and mixed speech — detected automatically, with nothing to configure.

You never tell Nabra what language someone speaks. Every request runs through one pipeline that works out, from the input itself, whether it is English, Arabic or both mixed, and — for Arabic — which dialect family and dialect.

Pipeline

speech-to-text → language + dialect detection → extraction → deterministic validation → clarification → JSON

Supported

Each dialect — its characteristic words, phone format, currency and measured detection accuracy — is shown on the Languages & dialects page.

Override	What	Notes
`auto`	Auto (default)	Language (English, Arabic, mixed) and Arabic dialect detected per input. Nothing to configure.
`en · en-US · en-GB`	English	First-class. en-US / en-GB add US / UK phone formats and currency.
`ar`	Arabic, dialect detected	Forces Arabic; the dialect is still detected.
`ar-JO · ar-PS · ar-LB · ar-SY`	Levantine: Jordan, Palestine, Lebanon, Syria	Forces the dialect: its phone format is enforced, its currency reported.
`ar-SA · ar-AE · ar-KW · ar-QA · ar-BH · ar-OM`	Gulf: Saudi Arabia, UAE, Kuwait, Qatar, Bahrain, Oman	Same, for the Gulf.
`ar-IQ · ar-EG · ar-YE`	Experimental: Iraq, Egypt, Yemen	Registered with phone rules and basic dialect notes; not benchmarked yet.

Overrides are optional (locale, dialect). A requested locale is enforced — its phone format is the only one accepted. A detected dialect only adds preferences, so a wrong guess can never make valid data fail. Schemas stay the same for every language: there is one restaurant_order, not one per dialect.

How detection works

Language — Arabic-script words against Latin words; both present means mixed (code switching). The speech model's own guess breaks ties.
Dialect family — characteristic words («بدي، هلق، شو» against «أبغى، باجر، الحين، وايد») add up; a family is chosen only with a clear margin.
Dialect — only with strong evidence: a place name, a calling code, a local phone number or currency, or several distinctive words. Otherwise "dialect": "auto" and processing stays generic Arabic.

The result says what was decided, and why:

language + clarification

"language": {
  "requested": "auto", "detected": "ar", "locale": "ar", "dialect": "auto", "dialectGroup": "gulf",
  "direction": "rtl", "mixedLanguage": true, "secondaryLanguages": ["en"], "source": "detected"
},
"fields": {
  "time": {
    "value": null, "type": "time", "status": "invalid", "reason": "ambiguous_alternatives",
    "heard": "الساعة خمس أو ست المسا", "options": ["17:00", "18:00"], "requiresConfirmation": true
  }
},
"clarification": {
  "needed": true, "language": "ar", "locale": "ar", "style": "ar", "direction": "rtl",
  "field": "time", "message": "هل تقصد 5 مساءً أم 6 مساءً؟",
  "questions": [
    { "field": "time", "kind": "choose", "reason": "ambiguous_alternatives", "message": "هل تقصد 5 مساءً أم 6 مساءً؟",
      "options": ["17:00", "18:00"] },
    { "field": "customerName", "kind": "missing", "message": "ما اسمك؟" }
  ]
}

What converges

«بكرا» · «بكرة» · «باجر» · «باچر» · tomorrow → the same date (with referenceTime). «باكر» counts only for Gulf speakers: in the Levant it means “early”.
«بعد بكرا» · «عقب باجر» · the day after tomorrow; «الاثنين الجاي» · «الاثنين الياي» · next Monday.
«الساعة خمس العصر» · «الساعة five المسا» · at 5 pm → 17:00.
«ثنتين» · «تنتين» · «شاورمتين» · two; «خمسة عشر» · «خمسطعش» · fifteen; «ميه وخمسين» · a hundred and fifty.
Phones in every supported format — 079… (JO), 059… (PS), 03 / 70… (LB), 09… (SY), 05… (SA, AE), 8-digit Kuwaiti, Qatari, Bahraini and Omani numbers, US and UK — as digits or words, with or without the country code.

What never converges

Normalization is conservative. It never turns uncertain speech into a value:

«بعد الظهر», “in the afternoon” → not a time. The field is invalid, and the user is asked for the hour.
«خمسة أو يمكن ستة» → no choice is made; both come back as options.
«يمكن خمسة», “around five” → kept, but uncertain (approximate).
A relative date («بكرا») without referenceTime → invalid, never guessed.

Clarification in the user's language

Kind	When	Example
`choose`	Two values were offered: «خمسة أو ستة», “five or six”.	هل تقصد 5 مساءً أم 6 مساءً؟ / Did you mean 5 PM or 6 PM?
`invalid`	Said, but not usable: a phone a digit short, «بعد الظهر» without an hour, «بكرا» with no referenceTime.	«بعد الظهر»: في أي ساعة تحديدًا؟
`missing`	A required field was not said (or was rejected).	ما وقت النهاية؟ / What's the customer name?
`confirm`	A value to check: am/pm assumed, approximate («يمكن»), mapped by the model, money.	وقت البداية: الساعة 5 صباحًا أم مساءً؟

Questions follow the detected language: English, or clear Modern Standard Arabic for every Arabic speaker, whatever the dialect — the dialect is used to understand the input, not to word the questions. Field names in questions come from the schema's labels ({"ar": "رقم الهاتف"}), or from the field type.

Measured

The benchmark (python -m scripts.benchmark_language) has 250 conversational cases: 20 per dialect, 30 English and 20 mixed. The cases are synthetic and have not yet been reviewed by native speakers of every dialect. Speech-to-text accuracy per dialect is not measured yet — it needs recordings in each dialect.