Metadata-Version: 2.4
Name: nawa-sdk
Version: 1.0.0
Summary: NAWA API SDK - Arabic-first AI comment classification
License: MIT
Keywords: nawa,arabic,ai,classification,dialect,nlp
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24.0
Provides-Extra: async
Requires-Dist: httpx[http2]; extra == "async"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: respx>=0.20; extra == "dev"

# nawa-sdk

Official Python SDK for the [NAWA API](https://developers.trynawa.com) — Arabic-first AI comment classification.

## Install

```bash
pip install nawa-sdk
```

## Quickstart

```python
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

```python
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

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

### Rubric Classify

```python
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

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

### Feedback (free)

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

### Webhooks

```python
# 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

```python
from nawa import AsyncNawa

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

## Error Handling

```python
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

```python
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](https://developers.trynawa.com)
