Metadata-Version: 2.4
Name: zora-ai-url-sdk
Version: 0.1.0
Summary: Production-grade Python SDK for Zora AI URL 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,url,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-url-sdk

Production-grade async Python SDK for the **Zora AI URL Phishing Detection** API.

## Features

- Analyse any URL for phishing / fraud risk
- Deep pipeline: static URL features, domain WHOIS, TLS, homoglyph, Playwright sandbox, cookies, behavioral heuristics, fingerprint beacons, and fused ML model
- Optional LLM-powered explanation with key indicators and recommendations
- Rich result dataclass with risk scores, risk components, pipeline checks, and all feature dictionaries
- Automatic retries with exponential back-off
- Async-first (`httpx`) with `async with` / `aclose()` support

## Installation

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

## Quick Start

```python
import asyncio
from zora_ai_url import ZoraAIURLClient, URLAnalyzer

async def main():
    async with ZoraAIURLClient(api_key="zora_...") as client:
        analyzer = URLAnalyzer(client)
        result = await analyzer.analyze(
            "https://secure-login.totally-real-bank.xyz/verify",
            with_llm_explanation=True,
        )
        print(result.risk_score, result.risk_level, result.phishing_probability)
        print(result.llm_explanation)

asyncio.run(main())
```

## `URLAnalysisResult` fields

| Field | Type | Description |
|---|---|---|
| `request_id` | `str \| None` | UUID of the stored analysis |
| `url` | `str` | Normalized URL that was analyzed |
| `phishing_probability` | `float` | 0–1 ML phishing probability |
| `risk_score` | `float` | 0–1 composite risk score |
| `risk_level` | `str` | `Low`, `Medium`, `High`, `Critical` |
| `model` | `str` | Model used for prediction |
| `risk_components` | `dict` | `url_score`, `content_score`, `cookie_score`, `infra_score`, `behavior_score` |
| `pipeline_checks` | `dict` | Which analysis phases ran successfully |
| `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 |
| `llm_key_indicators` | `list[str]` | Key phishing indicators found |
| `llm_recommendations` | `list[str]` | Safety recommendations |
| `url_features` | `dict` | Static URL features |
| `domain_features` | `dict` | WHOIS / domain intelligence |
| `tls_features` | `dict` | TLS certificate analysis |
| `homoglyph_features` | `dict` | Homoglyph / typosquatting detection |
| `sandbox_features` | `dict` | Playwright sandbox results |
| `cookie_features` | `dict` | Cookie risk analysis |
| `phishing_behavior_features` | `dict` | Behavioral heuristic signals |
| `fingerprint_beacon_features` | `dict` | Fingerprint / beacon detection |
| `fused_features` | `dict` | Feature-fusion engine output |
