zora-ai-sms-sdk 0.1.0

Production-grade Python SDK for Zora AI SMS fraud detection APIs

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:

pip install .

Or from repository root:

pip install ./packages/sms_package

Quickstart

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

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:

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.