synapsai 0.1.0__py3-none-any.whl

synapsai/__init__.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+from ._client import (
+    _AsyncTransport,
+    _SyncTransport,
+    _DEFAULT_BASE_URL,
+    _DEFAULT_MAX_RETRIES,
+    _DEFAULT_TIMEOUT,
+)
+from ._errors import (
+    AuthError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    SynapsAIError,
+    ValidationError,
+)
+from ._types import (
+    ClaimResult,
+    ClaimStatus,
+    DocumentVerifyResult,
+    HealthStatus,
+    HistoryEntry,
+    HistoryPage,
+    ImageVerifyResult,
+    KeyInfo,
+    ProtocolStats,
+    RawImageScores,
+    TrustScore,
+    UsageStats,
+    VisualAuthResult,
+    Webhook,
+    WebhookCreateResult,
+    WebhookDelivery,
+)
+from .resources.account import AccountResource, AsyncAccountResource
+from .resources.health import AsyncHealthResource, HealthResource
+from .resources.trust import AsyncTrustResource, TrustResource
+from .resources.verify import AsyncVerifyResource, VerifyResource
+from .resources.webhooks import AsyncWebhooksResource, WebhooksResource
+
+__version__ = "0.1.0"
+__all__ = [
+    "SynapsAI",
+    "AsyncSynapsAI",
+    # errors
+    "SynapsAIError",
+    "AuthError",
+    "RateLimitError",
+    "ValidationError",
+    "NotFoundError",
+    "ServerError",
+    # types
+    "ClaimResult",
+    "ClaimStatus",
+    "ImageVerifyResult",
+    "RawImageScores",
+    "DocumentVerifyResult",
+    "VisualAuthResult",
+    "TrustScore",
+    "Webhook",
+    "WebhookCreateResult",
+    "WebhookDelivery",
+    "KeyInfo",
+    "UsageStats",
+    "HistoryEntry",
+    "HistoryPage",
+    "HealthStatus",
+    "ProtocolStats",
+]
+
+
+def _resolve_api_key(api_key: Optional[str]) -> str:
+    key = api_key or os.environ.get("SYNAPSAI_API_KEY")
+    if not key:
+        raise ValueError(
+            "No API key provided. Pass api_key= to the constructor "
+            "or set the SYNAPSAI_API_KEY environment variable."
+        )
+    return key
+
+
+class SynapsAI:
+    """Synchronous SynapsAI client.
+
+    Example::
+
+        from synapsai import SynapsAI
+        client = SynapsAI(api_key="taas_your_key")
+        result = client.verify.image(image=Path("photo.jpg"))
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        transport = _SyncTransport(
+            api_key=_resolve_api_key(api_key),
+            base_url=base_url,
+            max_retries=max_retries,
+            timeout=timeout,
+        )
+        self.verify = VerifyResource(transport)
+        self.trust = TrustResource(transport)
+        self.webhooks = WebhooksResource(transport)
+        self.account = AccountResource(transport)
+        self.health = HealthResource(transport)
+        self._transport = transport
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> SynapsAI:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+class AsyncSynapsAI:
+    """Asynchronous SynapsAI client for use with asyncio / FastAPI.
+
+    Example::
+
+        from synapsai import AsyncSynapsAI
+        async with AsyncSynapsAI(api_key="taas_your_key") as client:
+            result = await client.verify.image(image=Path("photo.jpg"))
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        transport = _AsyncTransport(
+            api_key=_resolve_api_key(api_key),
+            base_url=base_url,
+            max_retries=max_retries,
+            timeout=timeout,
+        )
+        self.verify = AsyncVerifyResource(transport)
+        self.trust = AsyncTrustResource(transport)
+        self.webhooks = AsyncWebhooksResource(transport)
+        self.account = AsyncAccountResource(transport)
+        self.health = AsyncHealthResource(transport)
+        self._transport = transport
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncSynapsAI:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.aclose()

synapsai/_client.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import random
+import time
+from typing import Any, Dict, List, Optional
+
+import httpx
+
+from ._errors import (
+    AuthError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    SynapsAIError,
+    ValidationError,
+)
+
+_DEFAULT_BASE_URL = "https://api.synapsai.org"
+_DEFAULT_MAX_RETRIES = 3
+_DEFAULT_TIMEOUT = 30.0  # seconds
+
+
+def _map_error(response: httpx.Response) -> SynapsAIError:
+    try:
+        body = response.json()
+    except Exception:
+        body = {}
+    code = body.get("error", "unknown_error")
+    message = body.get("message", response.text or f"HTTP {response.status_code}")
+    status = response.status_code
+
+    if status == 401:
+        return AuthError(message, status=status, code=code)
+    if status == 404:
+        return NotFoundError(message, status=status, code=code)
+    if status == 429:
+        retry_after_s = body.get("retryAfter", 60)
+        return RateLimitError(
+            message,
+            status=status,
+            code=code,
+            retry_after_ms=int(retry_after_s * 1000),
+        )
+    if status == 400:
+        return ValidationError(message, status=status, code=code, field=body.get("field"))
+    return ServerError(message, status=status, code=code)
+
+
+def _backoff(attempt: int) -> float:
+    """Exponential backoff with ±20% jitter, in seconds."""
+    base = 0.5 * (2 ** attempt)
+    return base * (0.8 + 0.4 * random.random())
+
+
+class _SyncTransport:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        max_retries: int,
+        timeout: float,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._headers = {
+            "x-api-key": api_key,
+            "ngrok-skip-browser-warning": "true",
+        }
+        self._http = httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> _SyncTransport:
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Dict[str, Any]:
+        url = self._base_url + path
+        kwargs.setdefault("headers", {}).update(self._headers)
+        last_exc: Optional[SynapsAIError] = None
+
+        for attempt in range(self._max_retries + 1):
+            resp = self._http.request(method, url, **kwargs)
+            if resp.status_code < 500:
+                if resp.status_code >= 400:
+                    raise _map_error(resp)
+                return resp.json() if resp.content else {}
+            last_exc = _map_error(resp)
+            if attempt < self._max_retries:
+                time.sleep(_backoff(attempt))
+
+        raise last_exc  # type: ignore[misc]
+
+    def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, json: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return self._request("POST", path, json=json)
+
+    def post_form(self, path: str, files: list) -> Dict[str, Any]:
+        return self._request("POST", path, files=files)
+
+    def delete(self, path: str) -> Dict[str, Any]:
+        return self._request("DELETE", path)
+
+
+class _AsyncTransport:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        max_retries: int,
+        timeout: float,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._headers = {
+            "x-api-key": api_key,
+            "ngrok-skip-browser-warning": "true",
+        }
+        self._http = httpx.AsyncClient(timeout=timeout)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> _AsyncTransport:
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Dict[str, Any]:
+        import asyncio
+        url = self._base_url + path
+        kwargs.setdefault("headers", {}).update(self._headers)
+        last_exc: Optional[SynapsAIError] = None
+
+        for attempt in range(self._max_retries + 1):
+            resp = await self._http.request(method, url, **kwargs)
+            if resp.status_code < 500:
+                if resp.status_code >= 400:
+                    raise _map_error(resp)
+                return resp.json() if resp.content else {}
+            last_exc = _map_error(resp)
+            if attempt < self._max_retries:
+                await asyncio.sleep(_backoff(attempt))
+
+        raise last_exc  # type: ignore[misc]
+
+    async def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return await self._request("GET", path, params=params)
+
+    async def post(self, path: str, json: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return await self._request("POST", path, json=json)
+
+    async def post_form(self, path: str, files: list) -> Dict[str, Any]:
+        return await self._request("POST", path, files=files)
+
+    async def delete(self, path: str) -> Dict[str, Any]:
+        return await self._request("DELETE", path)

synapsai/_errors.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Optional
+
+
+class SynapsAIError(Exception):
+    """Base exception for all SynapsAI SDK errors."""
+
+    def __init__(self, message: str, *, status: int, code: str) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+
+
+class AuthError(SynapsAIError):
+    """API key is missing or invalid (HTTP 401)."""
+
+
+class RateLimitError(SynapsAIError):
+    """Rate limit exceeded (HTTP 429)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str,
+        retry_after_ms: int,
+    ) -> None:
+        super().__init__(message, status=status, code=code)
+        self.retry_after_ms = retry_after_ms  # milliseconds, consistent with TS SDK
+
+
+class ValidationError(SynapsAIError):
+    """Request payload is invalid (HTTP 400)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str,
+        field: Optional[str] = None,
+    ) -> None:
+        super().__init__(message, status=status, code=code)
+        self.field = field
+
+
+class NotFoundError(SynapsAIError):
+    """Requested resource does not exist (HTTP 404)."""
+
+
+class ServerError(SynapsAIError):
+    """Server returned 5xx after all retries exhausted."""

synapsai/_multipart.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import BinaryIO, List, Tuple, Union
+
+ImageInput = Union[Path, bytes, BinaryIO]
+
+# httpx file tuple: (filename, content, content_type)
+_FileTuple = Tuple[str, bytes, str]
+
+
+def _to_bytes(inp: ImageInput, fallback_name: str = "file") -> Tuple[str, bytes]:
+    if isinstance(inp, Path):
+        return inp.name, inp.read_bytes()
+    if isinstance(inp, bytes):
+        return fallback_name, inp
+    # file-like object
+    raw_name = getattr(inp, "name", fallback_name)
+    name = Path(raw_name).name if raw_name else fallback_name
+    return name, inp.read()
+
+
+def build_files(
+    field: str,
+    inputs: Union[ImageInput, List[ImageInput]],
+    extra: Union[dict, None] = None,
+) -> list:
+    """Return httpx-compatible `files` list for multipart upload."""
+    items = inputs if isinstance(inputs, list) else [inputs]
+    result: list = []
+    for i, inp in enumerate(items):
+        name, content = _to_bytes(inp, f"file{i}")
+        result.append((field, (name, content, "application/octet-stream")))
+    if extra:
+        for k, v in extra.items():
+            if v is not None:
+                result.append((k, (None, str(v), "text/plain")))
+    return result