veri-sdk 0.1.1__tar.gz

veri_sdk-0.1.1/.gitignore

@@ -0,0 +1,38 @@
+*.pt
+*.arrow
+venv/
+data/raw/
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+.env
+.file_locks/
+.DS_Store
+
+# Node
+node_modules/
+dist/
+
+# Large model weights (download separately)
+testing/models/CNNDetection/weights/*.pth
+testing/models/FIRE/ckpt/*.pth
+# Keep small weights that are under GitHub's limit
+!testing/models/UniversalFakeDetect/pretrained_weights/fc_weights.pth
+!testing/models/NPR-DeepfakeDetection/NPR.pth
+!testing/models/NPR-DeepfakeDetection/model_epoch_last_3090.pth
+
+# Terraform secrets
+infrastructure/terraform/secrets.tfvars
+terraform/environments/*/secrets.tfvars
+*.tfstate
+*.tfstate.backup
+.terraform/
+
+
+
+
+# Test dataset (large, don't commit)
+notebooks/genAIdetect/data/test_dataset/
+infrastructure/github-oidc-wrapper/config.sh

veri_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: veri-sdk
+Version: 0.1.1
+Summary: Official Python SDK for Veri AI Deepfake Detection API
+Project-URL: Homepage, https://veri.studio
+Project-URL: Documentation, https://docs.veri.studio
+Author-email: Veri Team <support@veri.studio>
+License-Expression: MIT
+Keywords: ai,api,deepfake,detection,fake,image,machine-learning,sdk,veri
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# veri-sdk
+
+Official Python SDK for the Veri AI Deepfake Detection API.
+
+## Installation
+
+```bash
+pip install veri-sdk
+```
+
+## Quick Start
+
+```python
+from veri import VeriClient
+
+# Create a client with your API key
+client = VeriClient(api_key="your-api-key-here")
+
+# Detect an image
+with open("image.jpg", "rb") as f:
+    result = client.detect(f)
+
+print(f"Prediction: {result.prediction}")
+print(f"Is AI-generated: {result.is_fake}")
+print(f"Confidence: {result.confidence:.1%}")
+```
+
+## Usage Examples
+
+### Detect from File Path
+
+```python
+from pathlib import Path
+from veri import VeriClient
+
+client = VeriClient(api_key="your-api-key")
+
+result = client.detect(Path("suspicious-image.jpg"))
+
+if result.is_fake:
+    print("This image appears to be AI-generated")
+    print(f"Confidence: {result.confidence:.1%}")
+    print(f"Verdict: {result.verdict}")
+else:
+    print("This image appears to be authentic")
+```
+
+### Detect from Bytes
+
+```python
+import requests
+from veri import VeriClient
+
+client = VeriClient(api_key="your-api-key")
+
+# Download image and detect
+response = requests.get("https://example.com/image.jpg")
+result = client.detect(response.content)
+```
+
+### Detect from URL
+
+```python
+result = client.detect_url("https://example.com/image.jpg")
+```
+
+### With Detection Options
+
+```python
+from veri import VeriClient, DetectionOptions
+
+client = VeriClient(api_key="your-api-key")
+
+options = DetectionOptions(
+    threshold=0.6,
+)
+
+result = client.detect(image_bytes, options=options)
+```
+
+### Get Profile
+
+```python
+profile = client.get_profile()
+print(f"User ID: {profile['userId']}")
+print(f"Credits: {profile['credits']}")
+```
+
+### Async Client
+
+```python
+import asyncio
+from veri import AsyncVeriClient
+
+async def main():
+    async with AsyncVeriClient(api_key="your-api-key") as client:
+        # Run multiple detections concurrently
+        tasks = [
+            client.detect(image1_bytes),
+            client.detect(image2_bytes),
+            client.detect(image3_bytes),
+        ]
+        results = await asyncio.gather(*tasks)
+
+        for i, result in enumerate(results):
+            print(f"Image {i+1}: {'FAKE' if result.is_fake else 'REAL'}")
+
+asyncio.run(main())
+```
+
+## Error Handling
+
+```python
+from veri import (
+    VeriClient,
+    VeriAPIError,
+    VeriValidationError,
+    VeriRateLimitError,
+    VeriTimeoutError,
+)
+
+client = VeriClient(api_key="your-api-key")
+
+try:
+    result = client.detect(image_bytes)
+except VeriRateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after} seconds")
+except VeriTimeoutError as e:
+    print(f"Request timed out after {e.timeout_ms}ms")
+except VeriAPIError as e:
+    print(f"API Error: {e.message} (code: {e.code})")
+    print(f"Request ID: {e.request_id}")
+except VeriValidationError as e:
+    print(f"Validation Error: {e.message} (field: {e.field})")
+```
+
+## Configuration
+
+```python
+client = VeriClient(
+    api_key="your-api-key",
+    base_url="https://api.veri.studio/v1",  # Custom API URL
+    timeout=30.0,                         # Request timeout (seconds)
+    max_retries=3,                        # Retry attempts
+)
+```
+
+## Context Manager
+
+Both sync and async clients support context managers:
+
+```python
+# Sync
+with VeriClient(api_key="your-api-key") as client:
+    result = client.detect(image_bytes)
+
+# Async
+async with AsyncVeriClient(api_key="your-api-key") as client:
+    result = await client.detect(image_bytes)
+```
+
+## Model
+
+| Model | Description |
+|-------|-------------|
+| `veri_face` | DenseNet-121 + MoE face forgery detector |
+
+## Type Hints
+
+This SDK is fully typed. Import types for your IDE:
+
+```python
+from veri import (
+    DetectionResult,
+    DetectionOptions,
+    ModelResult,
+)
+```
+
+## Requirements
+
+- Python 3.10+
+- httpx
+- pydantic
+
+## License
+
+MIT

veri_sdk-0.1.1/README.md

@@ -0,0 +1,188 @@
+# veri-sdk
+
+Official Python SDK for the Veri AI Deepfake Detection API.
+
+## Installation
+
+```bash
+pip install veri-sdk
+```
+
+## Quick Start
+
+```python
+from veri import VeriClient
+
+# Create a client with your API key
+client = VeriClient(api_key="your-api-key-here")
+
+# Detect an image
+with open("image.jpg", "rb") as f:
+    result = client.detect(f)
+
+print(f"Prediction: {result.prediction}")
+print(f"Is AI-generated: {result.is_fake}")
+print(f"Confidence: {result.confidence:.1%}")
+```
+
+## Usage Examples
+
+### Detect from File Path
+
+```python
+from pathlib import Path
+from veri import VeriClient
+
+client = VeriClient(api_key="your-api-key")
+
+result = client.detect(Path("suspicious-image.jpg"))
+
+if result.is_fake:
+    print("This image appears to be AI-generated")
+    print(f"Confidence: {result.confidence:.1%}")
+    print(f"Verdict: {result.verdict}")
+else:
+    print("This image appears to be authentic")
+```
+
+### Detect from Bytes
+
+```python
+import requests
+from veri import VeriClient
+
+client = VeriClient(api_key="your-api-key")
+
+# Download image and detect
+response = requests.get("https://example.com/image.jpg")
+result = client.detect(response.content)
+```
+
+### Detect from URL
+
+```python
+result = client.detect_url("https://example.com/image.jpg")
+```
+
+### With Detection Options
+
+```python
+from veri import VeriClient, DetectionOptions
+
+client = VeriClient(api_key="your-api-key")
+
+options = DetectionOptions(
+    threshold=0.6,
+)
+
+result = client.detect(image_bytes, options=options)
+```
+
+### Get Profile
+
+```python
+profile = client.get_profile()
+print(f"User ID: {profile['userId']}")
+print(f"Credits: {profile['credits']}")
+```
+
+### Async Client
+
+```python
+import asyncio
+from veri import AsyncVeriClient
+
+async def main():
+    async with AsyncVeriClient(api_key="your-api-key") as client:
+        # Run multiple detections concurrently
+        tasks = [
+            client.detect(image1_bytes),
+            client.detect(image2_bytes),
+            client.detect(image3_bytes),
+        ]
+        results = await asyncio.gather(*tasks)
+
+        for i, result in enumerate(results):
+            print(f"Image {i+1}: {'FAKE' if result.is_fake else 'REAL'}")
+
+asyncio.run(main())
+```
+
+## Error Handling
+
+```python
+from veri import (
+    VeriClient,
+    VeriAPIError,
+    VeriValidationError,
+    VeriRateLimitError,
+    VeriTimeoutError,
+)
+
+client = VeriClient(api_key="your-api-key")
+
+try:
+    result = client.detect(image_bytes)
+except VeriRateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after} seconds")
+except VeriTimeoutError as e:
+    print(f"Request timed out after {e.timeout_ms}ms")
+except VeriAPIError as e:
+    print(f"API Error: {e.message} (code: {e.code})")
+    print(f"Request ID: {e.request_id}")
+except VeriValidationError as e:
+    print(f"Validation Error: {e.message} (field: {e.field})")
+```
+
+## Configuration
+
+```python
+client = VeriClient(
+    api_key="your-api-key",
+    base_url="https://api.veri.studio/v1",  # Custom API URL
+    timeout=30.0,                         # Request timeout (seconds)
+    max_retries=3,                        # Retry attempts
+)
+```
+
+## Context Manager
+
+Both sync and async clients support context managers:
+
+```python
+# Sync
+with VeriClient(api_key="your-api-key") as client:
+    result = client.detect(image_bytes)
+
+# Async
+async with AsyncVeriClient(api_key="your-api-key") as client:
+    result = await client.detect(image_bytes)
+```
+
+## Model
+
+| Model | Description |
+|-------|-------------|
+| `veri_face` | DenseNet-121 + MoE face forgery detector |
+
+## Type Hints
+
+This SDK is fully typed. Import types for your IDE:
+
+```python
+from veri import (
+    DetectionResult,
+    DetectionOptions,
+    ModelResult,
+)
+```
+
+## Requirements
+
+- Python 3.10+
+- httpx
+- pydantic
+
+## License
+
+MIT

veri_sdk-0.1.1/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "veri-sdk"
+version = "0.1.1"
+description = "Official Python SDK for Veri AI Deepfake Detection API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Veri Team", email = "support@veri.studio" }
+]
+keywords = [
+    "veri",
+    "deepfake",
+    "detection",
+    "ai",
+    "image",
+    "fake",
+    "sdk",
+    "api",
+    "machine-learning"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.24.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "pytest-cov>=4.0.0",
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://veri.studio"
+Documentation = "https://docs.veri.studio"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/veri"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/veri"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

veri_sdk-0.1.1/src/veri/__init__.py

@@ -0,0 +1,36 @@
+"""
+Veri SDK - Python client for Veri Deepfake Detection API
+"""
+
+from veri.client import AsyncVeriClient, VeriClient
+from veri.errors import (
+    VeriAPIError,
+    VeriError,
+    VeriInsufficientCreditsError,
+    VeriRateLimitError,
+    VeriTimeoutError,
+    VeriValidationError,
+)
+from veri.types import (
+    DetectionOptions,
+    DetectionResult,
+    ModelResult,
+)
+
+__version__ = "0.1.1"
+__all__ = [
+    # Clients
+    "VeriClient",
+    "AsyncVeriClient",
+    # Types
+    "DetectionResult",
+    "DetectionOptions",
+    "ModelResult",
+    # Errors
+    "VeriError",
+    "VeriAPIError",
+    "VeriValidationError",
+    "VeriTimeoutError",
+    "VeriRateLimitError",
+    "VeriInsufficientCreditsError",
+]

veri_sdk-0.1.1/src/veri/client.py

@@ -0,0 +1,468 @@
+"""
+Veri API Client implementations
+"""
+
+from __future__ import annotations
+
+import base64
+import time
+from pathlib import Path
+from typing import Any, BinaryIO, Union
+
+import httpx
+
+from veri.errors import (
+    VeriAPIError,
+    VeriInsufficientCreditsError,
+    VeriRateLimitError,
+    VeriTimeoutError,
+    VeriValidationError,
+)
+from veri.types import (
+    DetectionOptions,
+    DetectionResult,
+)
+
+DEFAULT_BASE_URL = "https://api.veri.studio/v1"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+
+
+ImageInput = Union[bytes, str, Path, BinaryIO]  # noqa: UP007 - Union needed for mypy type alias
+
+
+class VeriClient:
+    """
+    Synchronous Veri API client.
+
+    Example:
+        >>> from veri import VeriClient
+        >>> client = VeriClient(api_key="your-api-key")
+        >>> result = client.detect(open("image.jpg", "rb"))
+        >>> print(f"Is fake: {result.is_fake} ({result.confidence:.1%})")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        """
+        Initialize the Veri client.
+
+        Args:
+            api_key: Your Veri API key
+            base_url: Base URL for the API
+            timeout: Request timeout in seconds
+            max_retries: Number of retry attempts for failed requests
+        """
+        if not api_key:
+            raise VeriValidationError("API key is required", "api_key")
+
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "X-API-Key": api_key,
+                "User-Agent": "veri-sdk-python/0.1.0",
+                "Content-Type": "application/json",
+            },
+        )
+
+    def __enter__(self) -> VeriClient:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the client and release resources."""
+        self._client.close()
+
+    def detect(
+        self,
+        image: ImageInput,
+        *,
+        options: DetectionOptions | None = None,
+    ) -> DetectionResult:
+        """
+        Detect whether an image is AI-generated.
+
+        Args:
+            image: Image data as bytes, file path, file object, or base64 string
+            options: Detection options
+
+        Returns:
+            Detection result with confidence scores
+
+        Example:
+            >>> # From file path
+            >>> result = client.detect(Path("image.jpg"))
+            >>>
+            >>> # From bytes
+            >>> result = client.detect(image_bytes)
+            >>>
+            >>> # With options
+            >>> result = client.detect(
+            ...     image_bytes,
+            ...     options=DetectionOptions(models=["veri_face"])
+            ... )
+        """
+        image_b64 = self._image_to_base64(image)
+        payload: dict[str, Any] = {"image": image_b64}
+
+        if options:
+            payload.update(options.model_dump(by_alias=True, exclude_none=True))
+
+        response = self._request("POST", "/api/detect", json=payload)
+        return DetectionResult.model_validate(response)
+
+    def detect_url(
+        self,
+        url: str,
+        *,
+        options: DetectionOptions | None = None,
+    ) -> DetectionResult:
+        """
+        Detect an image from a URL.
+
+        Args:
+            url: URL of the image to analyze
+            options: Detection options
+
+        Returns:
+            Detection result
+        """
+        if not url.startswith(("http://", "https://")):
+            raise VeriValidationError("Invalid URL format", "url")
+
+        payload: dict[str, Any] = {"url": url}
+        if options:
+            payload.update(options.model_dump(by_alias=True, exclude_none=True))
+
+        response = self._request("POST", "/api/detect/url", json=payload)
+        return DetectionResult.model_validate(response)
+
+    def get_profile(self) -> dict[str, Any]:
+        """
+        Get the authenticated user's profile.
+
+        Returns:
+            User profile data including userId, email, credits, etc.
+        """
+        return self._request("GET", "/api/user/profile")
+
+    # ============ Private methods ============
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        **kwargs: Any,
+    ) -> Any:
+        """Make an HTTP request with retries."""
+        last_error: Exception | None = None
+
+        for attempt in range(self.max_retries):
+            try:
+                response = self._client.request(method, endpoint, **kwargs)
+
+                if response.status_code == 429:
+                    retry_after = int(response.headers.get("retry-after", "60"))
+                    request_id = response.headers.get("x-request-id")
+                    raise VeriRateLimitError(
+                        "Rate limit exceeded",
+                        retry_after,
+                        request_id,
+                    )
+
+                if response.status_code == 402:
+                    error_data = self._safe_json(response)
+                    request_id = response.headers.get("x-request-id")
+                    raise VeriInsufficientCreditsError(
+                        error_data.get("message", "Insufficient credits"),
+                        request_id,
+                    )
+
+                if not response.is_success:
+                    error_data = self._safe_json(response)
+                    request_id = response.headers.get("x-request-id")
+                    raise VeriAPIError(
+                        error_data.get("message", f"Request failed: {response.status_code}"),
+                        response.status_code,
+                        error_data.get("code", "UNKNOWN_ERROR"),
+                        request_id,
+                    )
+
+                return self._safe_json(response)
+
+            except httpx.TimeoutException as e:
+                raise VeriTimeoutError(
+                    f"Request timed out after {self.timeout}s",
+                    int(self.timeout * 1000),
+                ) from e
+
+            except VeriAPIError as e:
+                if not e.is_retryable:
+                    raise
+                last_error = e
+
+            except httpx.HTTPError as e:
+                last_error = e
+
+            # Exponential backoff
+            if attempt < self.max_retries - 1:
+                time.sleep(2**attempt)
+
+        if last_error:
+            raise last_error
+        raise VeriAPIError("Request failed after retries", 500, "RETRY_EXHAUSTED")
+
+    def _safe_json(self, response: httpx.Response) -> dict[str, Any]:
+        """Safely parse JSON response, returning empty dict on failure."""
+        if not response.content:
+            return {}
+        try:
+            return response.json()
+        except Exception:
+            return {"message": response.text[:500] if response.text else "Unknown error"}
+
+    def _image_to_base64(self, image: ImageInput) -> str:
+        """Convert various image inputs to base64 string."""
+        # Already base64 string
+        if isinstance(image, str):
+            if image.startswith("data:"):
+                return image.split(",", 1)[1]
+            # Assume it's already base64 or a file path
+            if Path(image).exists():
+                with open(image, "rb") as f:
+                    return base64.b64encode(f.read()).decode("utf-8")
+            return image
+
+        # Path object
+        if isinstance(image, Path):
+            with open(image, "rb") as f:
+                return base64.b64encode(f.read()).decode("utf-8")
+
+        # Bytes
+        if isinstance(image, bytes):
+            return base64.b64encode(image).decode("utf-8")
+
+        # File-like object
+        if hasattr(image, "read"):
+            content = image.read()
+            if isinstance(content, str):
+                content = content.encode("utf-8")
+            return base64.b64encode(content).decode("utf-8")
+
+        raise VeriValidationError(
+            "Invalid image format. Expected bytes, Path, file object, or base64 string",
+            "image",
+        )
+
+
+class AsyncVeriClient:
+    """
+    Asynchronous Veri API client.
+
+    Example:
+        >>> import asyncio
+        >>> from veri import AsyncVeriClient
+        >>>
+        >>> async def main():
+        ...     async with AsyncVeriClient(api_key="your-api-key") as client:
+        ...         result = await client.detect(image_bytes)
+        ...         print(f"Is fake: {result.is_fake}")
+        >>>
+        >>> asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        if not api_key:
+            raise VeriValidationError("API key is required", "api_key")
+
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "X-API-Key": api_key,
+                "User-Agent": "veri-sdk-python/0.1.0",
+                "Content-Type": "application/json",
+            },
+        )
+
+    async def __aenter__(self) -> AsyncVeriClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the client and release resources."""
+        await self._client.aclose()
+
+    async def detect(
+        self,
+        image: ImageInput,
+        *,
+        options: DetectionOptions | None = None,
+    ) -> DetectionResult:
+        """Detect whether an image is AI-generated (async version)."""
+        image_b64 = self._image_to_base64(image)
+        payload: dict[str, Any] = {"image": image_b64}
+
+        if options:
+            payload.update(options.model_dump(by_alias=True, exclude_none=True))
+
+        response = await self._request("POST", "/api/detect", json=payload)
+        return DetectionResult.model_validate(response)
+
+    async def detect_url(
+        self,
+        url: str,
+        *,
+        options: DetectionOptions | None = None,
+    ) -> DetectionResult:
+        """Detect an image from a URL (async version)."""
+        if not url.startswith(("http://", "https://")):
+            raise VeriValidationError("Invalid URL format", "url")
+
+        payload: dict[str, Any] = {"url": url}
+        if options:
+            payload.update(options.model_dump(by_alias=True, exclude_none=True))
+
+        response = await self._request("POST", "/api/detect/url", json=payload)
+        return DetectionResult.model_validate(response)
+
+    async def get_profile(self) -> dict[str, Any]:
+        """Get the authenticated user's profile (async version)."""
+        return await self._request("GET", "/api/user/profile")
+
+    # ============ Private methods ============
+
+    async def _request(
+        self,
+        method: str,
+        endpoint: str,
+        **kwargs: Any,
+    ) -> Any:
+        """Make an async HTTP request with retries."""
+        import asyncio
+
+        last_error: Exception | None = None
+
+        for attempt in range(self.max_retries):
+            try:
+                response = await self._client.request(method, endpoint, **kwargs)
+
+                if response.status_code == 429:
+                    retry_after = int(response.headers.get("retry-after", "60"))
+                    request_id = response.headers.get("x-request-id")
+                    raise VeriRateLimitError(
+                        "Rate limit exceeded",
+                        retry_after,
+                        request_id,
+                    )
+
+                if response.status_code == 402:
+                    error_data = self._safe_json(response)
+                    request_id = response.headers.get("x-request-id")
+                    raise VeriInsufficientCreditsError(
+                        error_data.get("message", "Insufficient credits"),
+                        request_id,
+                    )
+
+                if not response.is_success:
+                    error_data = self._safe_json(response)
+                    request_id = response.headers.get("x-request-id")
+                    raise VeriAPIError(
+                        error_data.get("message", f"Request failed: {response.status_code}"),
+                        response.status_code,
+                        error_data.get("code", "UNKNOWN_ERROR"),
+                        request_id,
+                    )
+
+                return self._safe_json(response)
+
+            except httpx.TimeoutException as e:
+                raise VeriTimeoutError(
+                    f"Request timed out after {self.timeout}s",
+                    int(self.timeout * 1000),
+                ) from e
+
+            except VeriAPIError as e:
+                if not e.is_retryable:
+                    raise
+                last_error = e
+
+            except httpx.HTTPError as e:
+                last_error = e
+
+            # Exponential backoff
+            if attempt < self.max_retries - 1:
+                await asyncio.sleep(2**attempt)
+
+        if last_error:
+            raise last_error
+        raise VeriAPIError("Request failed after retries", 500, "RETRY_EXHAUSTED")
+
+    def _safe_json(self, response: httpx.Response) -> dict[str, Any]:
+        """Safely parse JSON response, returning empty dict on failure."""
+        if not response.content:
+            return {}
+        try:
+            return response.json()
+        except Exception:
+            return {"message": response.text[:500] if response.text else "Unknown error"}
+
+    def _image_to_base64(self, image: ImageInput) -> str:
+        """Convert various image inputs to base64 string."""
+        # Already base64 string
+        if isinstance(image, str):
+            if image.startswith("data:"):
+                return image.split(",", 1)[1]
+            if Path(image).exists():
+                with open(image, "rb") as f:
+                    return base64.b64encode(f.read()).decode("utf-8")
+            return image
+
+        # Path object
+        if isinstance(image, Path):
+            with open(image, "rb") as f:
+                return base64.b64encode(f.read()).decode("utf-8")
+
+        # Bytes
+        if isinstance(image, bytes):
+            return base64.b64encode(image).decode("utf-8")
+
+        # File-like object
+        if hasattr(image, "read"):
+            content = image.read()
+            if isinstance(content, str):
+                content = content.encode("utf-8")
+            return base64.b64encode(content).decode("utf-8")
+
+        raise VeriValidationError(
+            "Invalid image format. Expected bytes, Path, file object, or base64 string",
+            "image",
+        )

veri_sdk-0.1.1/src/veri/errors.py

@@ -0,0 +1,98 @@
+"""
+Custom exception classes for Veri SDK
+"""
+
+from __future__ import annotations
+
+
+class VeriError(Exception):
+    """Base exception for all Veri errors"""
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(message)
+
+
+class VeriAPIError(VeriError):
+    """Exception raised when the API returns an error response"""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        code: str,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+
+    @property
+    def is_retryable(self) -> bool:
+        """Whether the error is retryable"""
+        return (
+            self.status_code >= 500
+            or self.status_code == 429
+            or self.code in ("RATE_LIMITED", "SERVICE_UNAVAILABLE")
+        )
+
+    def __str__(self) -> str:
+        base = f"[{self.code}] {self.message} (HTTP {self.status_code})"
+        if self.request_id:
+            base += f" [Request ID: {self.request_id}]"
+        return base
+
+
+class VeriValidationError(VeriError):
+    """Exception raised when input validation fails"""
+
+    def __init__(self, message: str, field: str | None = None) -> None:
+        super().__init__(message)
+        self.field = field
+
+    def __str__(self) -> str:
+        if self.field:
+            return f"Validation error on '{self.field}': {self.message}"
+        return f"Validation error: {self.message}"
+
+
+class VeriTimeoutError(VeriError):
+    """Exception raised when a request times out"""
+
+    def __init__(self, message: str, timeout_ms: int) -> None:
+        super().__init__(message)
+        self.timeout_ms = timeout_ms
+
+    def __str__(self) -> str:
+        return f"Timeout after {self.timeout_ms}ms: {self.message}"
+
+
+class VeriRateLimitError(VeriAPIError):
+    """Exception raised when rate limit is exceeded"""
+
+    def __init__(
+        self,
+        message: str,
+        retry_after: int,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message, 429, "RATE_LIMITED", request_id)
+        self.retry_after = retry_after
+
+    def __str__(self) -> str:
+        return f"Rate limited. Retry after {self.retry_after} seconds: {self.message}"
+
+
+class VeriInsufficientCreditsError(VeriAPIError):
+    """Exception raised when user has insufficient credits (402 Payment Required)"""
+
+    def __init__(
+        self,
+        message: str,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message, 402, "INSUFFICIENT_CREDITS", request_id)
+
+    def __str__(self) -> str:
+        return f"Insufficient credits: {self.message}"

veri_sdk-0.1.1/src/veri/py.typed

@@ -0,0 +1,17 @@
+# Veri SDK - typed stub file
+from veri.client import VeriClient as VeriClient, AsyncVeriClient as AsyncVeriClient
+from veri.types import (
+    DetectionResult as DetectionResult,
+    DetectionOptions as DetectionOptions,
+    ModelResult as ModelResult,
+)
+from veri.errors import (
+    VeriError as VeriError,
+    VeriAPIError as VeriAPIError,
+    VeriValidationError as VeriValidationError,
+    VeriTimeoutError as VeriTimeoutError,
+    VeriRateLimitError as VeriRateLimitError,
+    VeriInsufficientCreditsError as VeriInsufficientCreditsError,
+)
+
+__version__: str

veri_sdk-0.1.1/src/veri/types.py

@@ -0,0 +1,60 @@
+"""
+Type definitions for Veri SDK
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class DetectionModel(str, Enum):
+    """Available detection models"""
+
+    VERI_FACE = "veri_face"
+
+
+class ModelResult(BaseModel):
+    """Individual model result from the detection pipeline"""
+
+    score: float | None = Field(default=None, description="Model score (0-1)")
+    status: str = Field(description="Model status (success/error)")
+    latency_ms: int | None = Field(default=None, description="Inference latency in ms")
+    error: str | None = Field(default=None, description="Error message if failed")
+
+
+class DetectionResult(BaseModel):
+    """Complete detection result"""
+
+    # Original fields from the API
+    prediction: str = Field(description="Prediction: 'ai', 'real', or 'uncertain'")
+    confidence: float = Field(description="Overall confidence score (0-1)")
+    ensemble_score: float | None = Field(default=None, description="Weighted ensemble score")
+    verdict: str = Field(description="Verdict: 'ai_generated', 'uncertain', or 'likely_real'")
+    models_succeeded: int = Field(description="Number of models that succeeded")
+    models_total: int = Field(description="Total models invoked")
+    model_results: dict[str, ModelResult] = Field(description="Per-model results")
+    detection_latency_ms: int = Field(description="Total detection latency in ms")
+
+    # SDK-friendly fields
+    is_fake: bool | None = Field(
+        alias="isFake", default=None, description="Whether image is AI-generated"
+    )
+    processing_time_ms: int = Field(
+        alias="processingTimeMs", description="Total processing time in ms"
+    )
+    image_hash: str = Field(alias="imageHash", description="SHA-256 hash of image")
+    cached: bool = Field(description="Whether result was from cache")
+    timestamp: str = Field(description="Detection timestamp (ISO 8601)")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class DetectionOptions(BaseModel):
+    """Options for detection request"""
+
+    models: list[str] | None = Field(default=None, description="Specific models to use")
+    threshold: float = Field(default=0.5, ge=0, le=1, description="Classification threshold")
+
+    model_config = ConfigDict(populate_by_name=True)