Metadata-Version: 2.4
Name: zora-ai-email-sdk
Version: 0.1.0
Summary: Production-grade Python SDK for Zora AI Email fraud/phishing 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,email,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-email-sdk

Production-grade async Python SDK for the **Zora AI Email Fraud Detection** API.

## Features

- Analyse raw emails (sender + subject + body) for phishing / fraud
- Optional LLM-powered explanation
- Rich result dataclass: `risk_score`, `fraud_type`, `confidence`, sub-scores, similarity, LLM fields
- Automatic retries with exponential back-off
- Async-first (`httpx`) with `async with` / `aclose()` support

## Installation

```bash
pip install -e packages/email_package   # editable local install
```

## Quick Start

```python
import asyncio
from zora_ai_email import ZoraAIEmailClient, EmailAnalyzer

async def main():
    async with ZoraAIEmailClient(api_key="zora_...") as client:
        analyzer = EmailAnalyzer(client)
        result = await analyzer.analyze(
            sender="offers@totally-real-bank.xyz",
            subject="Urgent: Verify your account",
            body="Click here immediately to avoid suspension: http://evil.xyz/login",
            with_llm_explanation=True,
        )
        print(result.risk_score, result.fraud_type, result.llm_explanation)

asyncio.run(main())
```

## API Reference

### `ZoraAIEmailClient`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `api_key` | `str` | required | Your Zora AI API key |
| `base_url` | `str` | `http://localhost:8000` | API base URL |
| `timeout` | `float` | `30.0` | Request timeout in seconds |
| `max_retries` | `int` | `3` | Number of retry attempts |
| `backoff_factor` | `float` | `0.5` | Exponential back-off base |

### `EmailAnalyzer.analyze(sender, subject, body, *, with_llm_explanation)`

Returns an `EmailAnalysisResult` dataclass.

### `EmailAnalysisResult` fields

| Field | Type | Description |
|---|---|---|
| `request_id` | `str \| None` | UUID of the stored analysis |
| `message_id` | `str` | Echo of the message_id |
| `sender` | `str` | Sender address |
| `subject` | `str` | Email subject |
| `body` | `str` | Body preview (truncated by server) |
| `risk_score` | `float` | 0–1 overall threat score |
| `fraud_type` | `str` | e.g. `phishing`, `safe` |
| `confidence` | `float` | Model confidence 0–1 |
| `sub_scores` | `dict` | `nlp_score`, `similarity_score`, `stylometry_score` |
| `llm_enhanced` | `bool` | Whether LLM explanation was generated |
| `llm_explanation` | `str \| None` | Human-readable explanation |
| `llm_label` | `str \| None` | LLM verdict label |
| `llm_confidence` | `float \| None` | LLM confidence |
| `similarity` | `dict` | Raw similarity search result |
| `nlp_prediction` | `dict` | Raw NLP model prediction |
| `raw_response` | `dict` | Full API response |
