Skip to content

Align classify docs with Arabizi support #79

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Align classify docs with Arabizi support #79

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
235 changes: 166 additions & 69 deletions api-reference/classify.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,22 +78,28 @@ result = nawa.classify(
{
"success": true,
"result": {
"text": "متى الجزء الثاني؟",
"id": "cls_nw_a1b2c3d4e5f6",
"object": "classification",
"intent": "question",
"intent_confidence": 0.97,
"sentiment": "neutral",
"sentiment_confidence": 0.91,
"language": "ar",
"dialect": "gulf",
"dialect_confidence": 0.95,
"toxicity": "none",
"toxicity_confidence": 0.99,
"categories": ["engagement"],
"language": "ar",
"requires_response": true,
"priority": "medium",
"suggested_reply": {
"text": "إن شاء الله الجزء الثاني قريب!",
"direction": "rtl"
},
"provider": "allam",
"model": "nagl-v1",
"cached": false
"fallback_used": false,
"tokens_used": null,
"cost_usd": 0.006,
"credits_used": 6
},
"errors": [],
"request_id": "req_abc123def456"
"request_id": "req_nw_a1b2c3d4e5f67890"
}
```

Expand All @@ -108,24 +114,36 @@ result = nawa.classify(
| `X-NAWA-Balance` | Current credit balance in USD |
| `X-NAWA-Balance-Warning` | `low_balance` when below $5 |
| `X-NAWA-Cache` | `HIT` if served from semantic cache (no cost) |
| `X-NAWA-Provider` | AI provider used for this request (`allam` or `claude`) |
| `X-NAWA-Latency` | Server-side latency in milliseconds |
| `X-NAWA-Calibration-Version` | Active calibration version for your account |

### Result fields

| Field | Type | Description |
|-------|------|-------------|
| `text` | string | The original input text |
| `id` | string | Classification ID (`cls_nw_xxx` format) |
| `object` | string | Always `"classification"` |
| `intent` | string | `question`, `complaint`, `praise`, `suggestion`, `spam`, `other` |
| `intent_confidence` | number | Confidence score (0–1) |
| `sentiment` | string | `positive`, `negative`, `neutral`, `mixed` |
| `sentiment_confidence` | number | Confidence score (0–1) |
| `language` | string | Detected language code (`ar`, `en`, `mixed`) |
| `dialect` | string \| null | `gulf`, `egyptian`, `levantine`, `msa`. Returns `null` for English text. |
| `dialect_confidence` | number \| null | Confidence score (0-1). Returns `null` for English text. |
| `toxicity` | string | `none`, `mild`, `moderate`, `severe` |
| `toxicity_confidence` | number | Confidence score (0–1) |
| `categories` | string[] | Content categories: `engagement`, `support`, `feedback`, `spam` |
| `language` | string | Detected language code (e.g., `ar`, `en`) |
| `model` | string | Model version used for classification |
| `cached` | boolean | Whether this was served from semantic cache |
| `requires_response` | boolean | Whether the comment expects a reply (e.g., questions, complaints) |
| `priority` | string | Suggested priority level for the comment |
| `suggested_reply` | object | Auto-generated reply suggestion |
| `suggested_reply.text` | string | Reply text. Empty string for `arabizi-rubric` model results. |
| `suggested_reply.direction` | string | Text direction: `rtl` for Arabic, `ltr` for English |
| `provider` | string | AI provider used: `allam`, `claude`, or `gemini` |
| `model` | string | Model used: `nagl-v1`, `claude-v1`, or `arabizi-rubric` |
| `fallback_used` | boolean | Whether a fallback provider was used |
| `tokens_used` | number \| null | Token count (when available) |
| `cost_usd` | number | Cost of this request in USD |
| `credits_used` | integer | Credits consumed (6 per request) |

<Info>
When the input is Arabizi (Arabic written in Latin script, e.g., "9ba7oooo ya 7abibi"), NAWA automatically detects and classifies it using the `arabizi-rubric` model. The `suggested_reply.text` field is empty for these results because the rubric handles classification without generating a reply.
</Info>

### Error responses

Expand All @@ -140,6 +158,49 @@ result = nawa.classify(
### More examples

<AccordionGroup>
<Accordion title="Arabizi (Latin-script Arabic)">
```bash
curl -X POST https://api.trynawa.com/v1/classify \
-H "Authorization: Bearer nawa_test_sk_xxx" \
-H "Content-Type: application/json" \
-d '{"text": "9ba7oooo ya 7abibi el video", "platform": "youtube"}'
```

Response:
```json
{
"success": true,
"result": {
"id": "cls_nw_arb1a2b3c4d5",
"object": "classification",
"intent": "praise",
"sentiment": "positive",
"language": "ar",
"dialect": "gulf",
"dialect_confidence": 0.88,
"requires_response": false,
"priority": "low",
"suggested_reply": {
"text": "",
"direction": "rtl"
},
"provider": "allam",
"model": "arabizi-rubric",
"fallback_used": false,
"tokens_used": null,
"cost_usd": 0.006,
"credits_used": 6
},
"errors": [],
"request_id": "req_nw_arb1a2b3c4d5e"
}
```

<Note>
Arabizi input is detected automatically. The `model` field returns `arabizi-rubric` and `suggested_reply.text` is empty because the rubric fast-path classifies without generating a reply.
</Note>
</Accordion>

<Accordion title="English - Praise">
```bash
curl -X POST https://api.trynawa.com/v1/classify \
Expand All @@ -153,19 +214,25 @@ result = nawa.classify(
{
"success": true,
"result": {
"text": "This is hands down the best review I have seen on this phone. Subscribed!",
"id": "cls_nw_en_praise_001",
"object": "classification",
"intent": "praise",
"intent_confidence": 0.96,
"sentiment": "positive",
"sentiment_confidence": 0.98,
"language": "en",
"dialect": null,
"dialect_confidence": null,
"toxicity": "none",
"toxicity_confidence": 0.99,
"categories": ["engagement"],
"language": "en",
"requires_response": false,
"priority": "low",
"suggested_reply": {
"text": "Thank you so much! Glad you found it helpful.",
"direction": "ltr"
},
"provider": "claude",
"model": "claude-v1",
"cached": false
"fallback_used": false,
"tokens_used": null,
"cost_usd": 0.006,
"credits_used": 6
},
"errors": [],
"request_id": "req_en_praise_001"
Expand All @@ -186,19 +253,25 @@ result = nawa.classify(
{
"success": true,
"result": {
"text": "The audio quality is terrible in this one. Can barely hear anything after the 5 minute mark.",
"id": "cls_nw_en_comp_001",
"object": "classification",
"intent": "complaint",
"intent_confidence": 0.94,
"sentiment": "negative",
"sentiment_confidence": 0.96,
"language": "en",
"dialect": null,
"dialect_confidence": null,
"toxicity": "none",
"toxicity_confidence": 0.97,
"categories": ["feedback"],
"language": "en",
"requires_response": true,
"priority": "high",
"suggested_reply": {
"text": "Sorry about the audio issues! We're looking into this.",
"direction": "ltr"
},
"provider": "claude",
"model": "claude-v1",
"cached": false
"fallback_used": false,
"tokens_used": null,
"cost_usd": 0.006,
"credits_used": 6
},
"errors": [],
"request_id": "req_en_complaint_001"
Expand All @@ -219,27 +292,33 @@ result = nawa.classify(
{
"success": true,
"result": {
"text": "What camera and lens setup are you using for these shots?",
"id": "cls_nw_en_quest_001",
"object": "classification",
"intent": "question",
"intent_confidence": 0.97,
"sentiment": "neutral",
"sentiment_confidence": 0.92,
"language": "en",
"dialect": null,
"dialect_confidence": null,
"toxicity": "none",
"toxicity_confidence": 0.99,
"categories": ["engagement"],
"language": "en",
"requires_response": true,
"priority": "medium",
"suggested_reply": {
"text": "Great question! We use a Sony A7IV with a 24-70mm f/2.8 lens.",
"direction": "ltr"
},
"provider": "claude",
"model": "claude-v1",
"cached": false
"fallback_used": false,
"tokens_used": null,
"cost_usd": 0.006,
"credits_used": 6
},
"errors": [],
"request_id": "req_en_question_001"
}
```
</Accordion>

<Accordion title="Gulf Arabic - Praise">
<Accordion title="Gulf Arabic - Praise">
```bash
curl -X POST https://api.trynawa.com/v1/classify \
-H "Authorization: Bearer nawa_test_sk_xxx" \
Expand All @@ -252,27 +331,33 @@ result = nawa.classify(
{
"success": true,
"result": {
"text": "ما شاء الله عليك، محتوى رهيب!",
"id": "cls_nw_ghi789jkl012",
"object": "classification",
"intent": "praise",
"intent_confidence": 0.98,
"sentiment": "positive",
"sentiment_confidence": 0.97,
"language": "ar",
"dialect": "gulf",
"dialect_confidence": 0.93,
"toxicity": "none",
"toxicity_confidence": 0.99,
"categories": ["engagement"],
"language": "ar",
"requires_response": false,
"priority": "low",
"suggested_reply": {
"text": "الله يسعدك! شكرا على دعمك",
"direction": "rtl"
},
"provider": "allam",
"model": "nagl-v1",
"cached": false
"fallback_used": false,
"tokens_used": null,
"cost_usd": 0.006,
"credits_used": 6
},
"errors": [],
"request_id": "req_ghi789jkl012"
}
```
</Accordion>

<Accordion title="Egyptian Arabic - Complaint">
<Accordion title="Egyptian Arabic - Complaint">
```bash
curl -X POST https://api.trynawa.com/v1/classify \
-H "Authorization: Bearer nawa_test_sk_xxx" \
Expand All @@ -285,27 +370,33 @@ result = nawa.classify(
{
"success": true,
"result": {
"text": "الصوت وحش أوي في الفيديو ده",
"id": "cls_nw_mno345pqr678",
"object": "classification",
"intent": "complaint",
"intent_confidence": 0.94,
"sentiment": "negative",
"sentiment_confidence": 0.96,
"language": "ar",
"dialect": "egyptian",
"dialect_confidence": 0.97,
"toxicity": "none",
"toxicity_confidence": 0.95,
"categories": ["feedback"],
"language": "ar",
"requires_response": true,
"priority": "high",
"suggested_reply": {
"text": "معلش على الإزعاج! هنشوف الموضوع ده",
"direction": "rtl"
},
"provider": "allam",
"model": "nagl-v1",
"cached": false
"fallback_used": false,
"tokens_used": null,
"cost_usd": 0.006,
"credits_used": 6
},
"errors": [],
"request_id": "req_mno345pqr678"
}
```
</Accordion>

<Accordion title="Levantine Arabic - Suggestion">
<Accordion title="Levantine Arabic - Suggestion">
```bash
curl -X POST https://api.trynawa.com/v1/classify \
-H "Authorization: Bearer nawa_test_sk_xxx" \
Expand All @@ -318,19 +409,25 @@ result = nawa.classify(
{
"success": true,
"result": {
"text": "لو سمحت حاول تحكي عن المطاعم بلبنان",
"id": "cls_nw_stu901vwx234",
"object": "classification",
"intent": "suggestion",
"intent_confidence": 0.92,
"sentiment": "neutral",
"sentiment_confidence": 0.88,
"language": "ar",
"dialect": "levantine",
"dialect_confidence": 0.96,
"toxicity": "none",
"toxicity_confidence": 0.99,
"categories": ["engagement"],
"language": "ar",
"requires_response": false,
"priority": "medium",
"suggested_reply": {
"text": "فكرة حلوة! رح ناخدها بعين الاعتبار",
"direction": "rtl"
},
"provider": "allam",
"model": "nagl-v1",
"cached": false
"fallback_used": false,
"tokens_used": null,
"cost_usd": 0.006,
"credits_used": 6
},
"errors": [],
"request_id": "req_stu901vwx234"
Expand Down
Loading