nawa-sdk 1.1.0

NAWA API SDK - Arabic language intelligence

nawa-sdk

Official Python SDK for the NAWA API — Arabic-first AI comment classification.

Install

pip install nawa-sdk

Quickstart

from nawa import Nawa

client = Nawa(api_key="nawa_live_sk_xxx")

data, error = client.classify(text="متى الجزء الثاني؟")
print(data.dialect)    # "gulf"
print(data.sentiment)  # "neutral"
print(data.suggested_reply.text)  # "قريب إن شاء الله! 🙏"

NAWA is the only API that detects Gulf, Egyptian, Levantine, and MSA Arabic dialects.

Configuration

client = Nawa(
    api_key="nawa_live_sk_xxx",          # required
    base_url="https://api.trynawa.com",  # default
    max_retries=2,                        # default
    timeout=30.0,                         # 30s default
    throw_on_error=False,                 # default — use (data, error) tuple
)

Methods

Classify

data, error = client.classify(
    text="متى الجزء الثاني؟",
    context={"video_title": "Dubai Vlog"},
    provider="claude",  # optional
)

Translate

data, error = client.translate(
    text="Hello, how are you?",
    target="ar",
    dialect="gulf",
    tone="casual",
)
print(data.translated_text)  # "هلا، كيف حالك؟"

Detect

data, error = client.detect(text="وش رايكم بالمحتوى الجديد؟")
print(data.language)  # "ar"
print(data.dialect)   # "gulf"
print(data.script)    # "arabic"

Moderate

data, error = client.moderate(
    text="هذا محتوى رائع جدا",
    strictness="medium",
)
print(data.is_safe)   # True
print(data.verdict)   # "safe"

Rubric Classify

data, error = client.rubric.classify(
    text="أحتاج مساعدة في طلبي رقم ١٢٣٤",
    rubric={
        "categories": [
            {"name": "support", "description": "Customer support requests"},
            {"name": "billing", "description": "Billing questions"},
        ],
        "multi_label": True,
        "confidence_threshold": 0.6,
    },
)

Reply

data, error = client.comments.reply(
    text="هذا المنتج سيء جداً ولا أنصح به",
    tone="professional",
    max_length=500,
)

Feedback (free)

data, error = client.feedback.create(
    classification_id="cls_nw_a1b2c3d4e5f6",
    rating="incorrect",
    corrected_intent=["question"],
    corrected_sentiment="neutral",
)

Webhooks

# Create
data, error = client.webhooks.create(
    url="https://example.com/webhook",
    events=["classification.completed", "credits.low"],
)

# List
data, error = client.webhooks.list()

# Delete
data, error = client.webhooks.delete("webhook-uuid")

# Verify signature
is_valid = client.webhooks.verify(
    payload=raw_body,
    headers={
        "webhook-id": request.headers["webhook-id"],
        "webhook-timestamp": request.headers["webhook-timestamp"],
        "webhook-signature": request.headers["webhook-signature"],
    },
    secret=NAWA_WEBHOOK_SECRET,
    tolerance=300,
)

Async Usage

from nawa import AsyncNawa

client = AsyncNawa(api_key="nawa_live_sk_xxx")
data, error = await client.classify(text="ماشاء الله الفيديو حلو مرة")

Error Handling

data, error = client.classify(text="test")

if error:
    print(error.message)           # Human-readable error
    print(error.code)              # Machine-readable code
    print(error.status)            # HTTP status
    print(error.suggested_action)  # What to do next
else:
    print(data.dialect)

Exception Mode

from nawa import Nawa, NawaRateLimitError, NawaAuthError

client = Nawa(api_key="xxx", throw_on_error=True)

try:
    data, error = client.classify(text="test")
except NawaRateLimitError as e:
    print(f"Retry after {e.retry_after}s")
except NawaAuthError:
    print("Check your API key")

Docs

Full API reference: developers.trynawa.com