Metadata-Version: 2.4
Name: zora-ai-sms-sdk
Version: 0.1.0
Summary: Production-grade Python SDK for Zora AI SMS fraud detection APIs
Author: Zora AI
Project-URL: Homepage, https://example.com/zora-ai
Project-URL: Documentation, https://example.com/zora-ai/docs
Keywords: fraud-detection,phishing,sms,sdk,api-client
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0

# Zora AI SMS SDK

A production-grade Python SDK for the Zora AI fraud detection platform's SMS analysis APIs.

## Installation

From the package folder:

```bash
pip install .
```

Or from repository root:

```bash
pip install ./packages/sms_package
```

## Quickstart

```python
import asyncio

from zora_ai import ZoraAIClient, SmsAnalyzer

async def main() -> None:
    client = ZoraAIClient(
        api_key="zora_xxx",
        base_url="http://localhost:8000",
        timeout=30,
        max_retries=3,
    )
    sms = SmsAnalyzer(client)

    try:
        result = await sms.analyze(
            text="Your account is blocked. Verify now: http://fake-link.example",
            with_llm_explanation=True,
        )

        print(result.request_id)
        print(result.risk_score)
        print(result.fraud_type)
        print(result.sub_scores)
    finally:
        await client.aclose()

asyncio.run(main())
```

## What You Get

- API-key Bearer authentication
- Retry with exponential backoff
- Typed result models
- Structured exceptions by error type
- Optional request/response logging
- Request ID propagation when available

## API Surface

### `ZoraAIClient` (async)

- `await get(path, params=None, timeout=None)`
- `await post(path, json=None, timeout=None)`
- Handles status codes:
  - `400` -> `APIError`
  - `401` -> `AuthenticationError`
  - `429` -> `RateLimitError`
  - `5xx` -> `APIError`

### `SmsAnalyzer`

- `await analyze(text, with_llm_explanation=False)` -> `SMSAnalysisResult`

## Models

`SMSAnalysisResult` includes:

- `request_id`
- `risk_score`
- `confidence`
- `fraud_type`
- `explanation`
- `sub_scores` (`nlp_score`, `similarity_score`, `stylometry_score`)
- raw response access for advanced use

## Error Handling Example

```python
import asyncio

from zora_ai import ZoraAIClient, SmsAnalyzer
from zora_ai.exceptions import AuthenticationError, RateLimitError, APIError

async def main() -> None:
    client = ZoraAIClient(api_key="zora_xxx")
    sms = SmsAnalyzer(client)

    try:
        result = await sms.analyze("hello")
        print(result)
    except AuthenticationError:
        print("Invalid API key")
    except RateLimitError as exc:
        print(f"Rate limited. Retry after: {exc.retry_after}")
    except APIError as exc:
        print(f"API failed: {exc.status_code} {exc}")
    finally:
        await client.aclose()

asyncio.run(main())
```

## Local Testing Checklist

1. Ensure backend is running at `http://localhost:8000`.
2. Generate an API key from your profile page (`/home/profile`) or via `POST /api-keys/request`.
3. Install SDK: `pip install ./packages/sms_package`.
4. Run a quick script:

```python
import asyncio

from zora_ai import ZoraAIClient, SmsAnalyzer

async def main() -> None:
    client = ZoraAIClient(api_key="<YOUR_KEY>")
    sms = SmsAnalyzer(client)
    try:
        print(await sms.analyze("Urgent: update bank KYC now", with_llm_explanation=True))
    finally:
        await client.aclose()

asyncio.run(main())
```

## Notes

- This SDK is currently focused on SMS analysis.
- `base_url` is configurable for local/staging/prod environments.
