raidxai 0.1.0__tar.gz

raidxai-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env

raidxai-0.1.0/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) Raid AI. All rights reserved.
+
+Use of the Raid AI SDK is governed by the Raid AI Terms of Service:
+https://raidxai.com
+
+This software is provided to interact with the Raid AI API. It is distributed
+"as is", without warranty of any kind, express or implied.

raidxai-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: raidxai
+Version: 0.1.0
+Summary: Official Python SDK for the Raid AI detection API — detect AI-generated and manipulated media, and fact-check claims.
+Project-URL: Homepage, https://docs.raidxai.com
+Project-URL: Documentation, https://docs.raidxai.com
+Project-URL: Repository, https://github.com/Raid-AI-Corporation/Raid-AI-SDK
+Author-email: Raid AI <info@raidxai.com>
+License-Expression: LicenseRef-Raid-AI-Terms
+License-File: LICENSE
+Keywords: ai-detection,deepfake,fact-checking,forensics,raid,raidxai,sdk
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator>=0.25; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# raidxai
+
+Official Python SDK for the **Raid AI** detection API — detect AI-generated and manipulated media
+(images, audio, video) and fact-check media against the public record.
+
+Sync and async clients, Python 3.10+. Full API reference: **https://docs.raidxai.com**.
+
+## Install
+
+```bash
+pip install raidxai
+```
+
+## Authentication
+
+Every request uses a developer token. Create one in the Raid AI dashboard
+(**Settings → API keys**) and keep it server-side — never ship it in client code.
+
+```python
+from raidxai import RaidClient, FileInput
+
+raid = RaidClient(
+    api_key="<your-api-key>",                 # or os.environ["RAID_API_KEY"]
+    base_url="<raid-ai-api-url>",             # required — or os.environ["RAID_API_BASE_URL"]
+    # timeout=60.0,
+    # max_retries=2,
+    # auth_header="bearer",                   # or "x-api-key"
+)
+```
+
+Each API key carries scopes (`image`, `audio`, `video`, `fact-check`) — a call to a modality
+your key isn't scoped for raises `RaidApiError` with a `403` (`api_key.scope_missing`).
+
+## Usage
+
+### Images (synchronous)
+
+```python
+res = raid.images.process(FileInput.from_path("suspect.jpg"))
+print(res.images[0].verdict, res.images[0].confidence)
+
+# …or from a URL:
+raid.images.process_from_url("https://example.com/photo.jpg")
+```
+
+### Audio (synchronous)
+
+```python
+from raidxai import VoiceWorkflow
+
+res = raid.audio.process(
+    FileInput.from_path("clip.mp3"),
+    workflow_type=VoiceWorkflow.AI_DETECTION_ONLY,
+)
+print(res.is_ai_detected, res.detection_confidence)
+```
+
+### Video (asynchronous — submit then poll)
+
+```python
+# One call: submit and wait for the terminal verdict.
+job = raid.video.submit_and_wait(
+    FileInput.from_path("clip.mp4"),
+    client_duration_seconds=42,
+    interval_seconds=3,
+    timeout_seconds=300,
+)
+print(job.status, job.result.verdict if job.result else None)
+
+# …or drive it yourself:
+submitted = raid.video.submit(FileInput.from_path("clip.mp4"), client_duration_seconds=42)
+state = raid.video.get_job(submitted.job_id)
+```
+
+### Fact-checking (asynchronous)
+
+```python
+job = raid.fact_checking.submit_and_wait(
+    FileInput.from_path("photo.jpg"),
+    "image",
+    user_context="Claimed to be from the 2024 election.",
+)
+print(job.result.summary if job.result else None)
+```
+
+## Async
+
+Every resource has an async twin on `AsyncRaidClient` with the same method names:
+
+```python
+import asyncio
+from raidxai import AsyncRaidClient, FileInput
+
+async def main():
+    async with AsyncRaidClient(api_key="<your-api-key>") as raid:
+        res = await raid.images.process(FileInput.from_path("photo.jpg"))
+        print(res.images[0].verdict)
+
+asyncio.run(main())
+```
+
+## Errors
+
+Non-2xx responses raise `RaidApiError` (`.status`, `.code`, `.message`, `.body`, plus `.is_auth` /
+`.is_payment_required` / `.is_rate_limited`). Transient `429`/`5xx` responses are retried automatically
+with exponential backoff (`max_retries`). A `submit_and_wait` that never finishes raises `RaidTimeoutError`.
+
+```python
+from raidxai import RaidApiError, RaidTimeoutError
+
+try:
+    raid.images.process(file)
+except RaidApiError as err:
+    if err.is_auth:
+        print("bad or unscoped token:", err.code)
+    elif err.is_payment_required:
+        print("out of credits:", err.code)
+    else:
+        print(err.status, err.code, err.message)
+except RaidTimeoutError as err:
+    print("job did not finish in time; last status:", err.last_status)
+```
+
+## Types
+
+Response models are Pydantic v2 classes generated from the API's OpenAPI spec (`ImageForensicsResponse`,
+`VideoJob`, `Verdict`, `JobStatus`, …), so attributes are snake_case and tracked against the server contract.
+
+## Development
+
+```bash
+uv venv --python 3.12 && source .venv/bin/activate
+uv pip install -e ".[dev]"
+./scripts/generate.sh   # regenerate src/raidxai/_generated/models.py from ../spec/openapi.yaml
+ruff check .
+pytest
+```
+
+Run the live smoke test against a real tier (auto-skips without the key):
+
+```bash
+RAID_API_KEY=<your-api-key> RAID_API_BASE_URL=<raid-ai-api-url> pytest tests/test_live_smoke.py
+```

raidxai-0.1.0/README.md

@@ -0,0 +1,143 @@
+# raidxai
+
+Official Python SDK for the **Raid AI** detection API — detect AI-generated and manipulated media
+(images, audio, video) and fact-check media against the public record.
+
+Sync and async clients, Python 3.10+. Full API reference: **https://docs.raidxai.com**.
+
+## Install
+
+```bash
+pip install raidxai
+```
+
+## Authentication
+
+Every request uses a developer token. Create one in the Raid AI dashboard
+(**Settings → API keys**) and keep it server-side — never ship it in client code.
+
+```python
+from raidxai import RaidClient, FileInput
+
+raid = RaidClient(
+    api_key="<your-api-key>",                 # or os.environ["RAID_API_KEY"]
+    base_url="<raid-ai-api-url>",             # required — or os.environ["RAID_API_BASE_URL"]
+    # timeout=60.0,
+    # max_retries=2,
+    # auth_header="bearer",                   # or "x-api-key"
+)
+```
+
+Each API key carries scopes (`image`, `audio`, `video`, `fact-check`) — a call to a modality
+your key isn't scoped for raises `RaidApiError` with a `403` (`api_key.scope_missing`).
+
+## Usage
+
+### Images (synchronous)
+
+```python
+res = raid.images.process(FileInput.from_path("suspect.jpg"))
+print(res.images[0].verdict, res.images[0].confidence)
+
+# …or from a URL:
+raid.images.process_from_url("https://example.com/photo.jpg")
+```
+
+### Audio (synchronous)
+
+```python
+from raidxai import VoiceWorkflow
+
+res = raid.audio.process(
+    FileInput.from_path("clip.mp3"),
+    workflow_type=VoiceWorkflow.AI_DETECTION_ONLY,
+)
+print(res.is_ai_detected, res.detection_confidence)
+```
+
+### Video (asynchronous — submit then poll)
+
+```python
+# One call: submit and wait for the terminal verdict.
+job = raid.video.submit_and_wait(
+    FileInput.from_path("clip.mp4"),
+    client_duration_seconds=42,
+    interval_seconds=3,
+    timeout_seconds=300,
+)
+print(job.status, job.result.verdict if job.result else None)
+
+# …or drive it yourself:
+submitted = raid.video.submit(FileInput.from_path("clip.mp4"), client_duration_seconds=42)
+state = raid.video.get_job(submitted.job_id)
+```
+
+### Fact-checking (asynchronous)
+
+```python
+job = raid.fact_checking.submit_and_wait(
+    FileInput.from_path("photo.jpg"),
+    "image",
+    user_context="Claimed to be from the 2024 election.",
+)
+print(job.result.summary if job.result else None)
+```
+
+## Async
+
+Every resource has an async twin on `AsyncRaidClient` with the same method names:
+
+```python
+import asyncio
+from raidxai import AsyncRaidClient, FileInput
+
+async def main():
+    async with AsyncRaidClient(api_key="<your-api-key>") as raid:
+        res = await raid.images.process(FileInput.from_path("photo.jpg"))
+        print(res.images[0].verdict)
+
+asyncio.run(main())
+```
+
+## Errors
+
+Non-2xx responses raise `RaidApiError` (`.status`, `.code`, `.message`, `.body`, plus `.is_auth` /
+`.is_payment_required` / `.is_rate_limited`). Transient `429`/`5xx` responses are retried automatically
+with exponential backoff (`max_retries`). A `submit_and_wait` that never finishes raises `RaidTimeoutError`.
+
+```python
+from raidxai import RaidApiError, RaidTimeoutError
+
+try:
+    raid.images.process(file)
+except RaidApiError as err:
+    if err.is_auth:
+        print("bad or unscoped token:", err.code)
+    elif err.is_payment_required:
+        print("out of credits:", err.code)
+    else:
+        print(err.status, err.code, err.message)
+except RaidTimeoutError as err:
+    print("job did not finish in time; last status:", err.last_status)
+```
+
+## Types
+
+Response models are Pydantic v2 classes generated from the API's OpenAPI spec (`ImageForensicsResponse`,
+`VideoJob`, `Verdict`, `JobStatus`, …), so attributes are snake_case and tracked against the server contract.
+
+## Development
+
+```bash
+uv venv --python 3.12 && source .venv/bin/activate
+uv pip install -e ".[dev]"
+./scripts/generate.sh   # regenerate src/raidxai/_generated/models.py from ../spec/openapi.yaml
+ruff check .
+pytest
+```
+
+Run the live smoke test against a real tier (auto-skips without the key):
+
+```bash
+RAID_API_KEY=<your-api-key> RAID_API_BASE_URL=<raid-ai-api-url> pytest tests/test_live_smoke.py
+```

raidxai-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "raidxai"
+version = "0.1.0"
+description = "Official Python SDK for the Raid AI detection API — detect AI-generated and manipulated media, and fact-check claims."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "LicenseRef-Raid-AI-Terms"
+license-files = ["LICENSE"]
+authors = [{ name = "Raid AI", email = "info@raidxai.com" }]
+keywords = ["raid", "raidxai", "deepfake", "ai-detection", "forensics", "fact-checking", "sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+]
+dependencies = [
+  "httpx>=0.27",
+  "pydantic>=2.7",
+]
+
+[project.urls]
+Homepage = "https://docs.raidxai.com"
+Documentation = "https://docs.raidxai.com"
+Repository = "https://github.com/Raid-AI-Corporation/Raid-AI-SDK"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+  "ruff>=0.6",
+  "datamodel-code-generator>=0.25",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/raidxai"]
+
+# Ship only the public SDK in the source distribution — no tests, internal dev
+# scripts, or dotfiles. (The wheel already ships only the `raidxai` package.)
+[tool.hatch.build.targets.sdist]
+ignore-vcs = true
+only-include = ["src/raidxai", "README.md", "LICENSE"]
+exclude = ["**/.gitignore", "**/__pycache__"]
+
+# target-version matches the package's requires-python floor (3.10), so the
+# linter never suggests 3.11/3.12-only syntax (StrEnum, PEP 695 generics) that
+# would break older supported interpreters. line-length 100 follows the workspace.
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/raidxai/_generated/*" = ["E501", "UP", "B", "I"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

raidxai-0.1.0/src/raidxai/__init__.py

@@ -0,0 +1,78 @@
+"""Official Python SDK for the Raid AI detection API.
+
+Detect AI-generated and manipulated media (images, audio, video) and fact-check
+media against the public record.
+
+    from raidxai import RaidClient, FileInput
+
+    raid = RaidClient(api_key="<your-api-key>")
+    res = raid.images.process(FileInput.from_path("photo.jpg"))
+    print(res.images[0].verdict)
+
+Full reference: https://docs.raidxai.com
+"""
+
+from __future__ import annotations
+
+from ._specs import PagedResult
+from .aio import AsyncRaidClient
+from .client import RaidClient
+from .errors import RaidApiError, RaidTimeoutError
+from .files import FileInput
+from .models import (
+    Claim,
+    FactCheckJob,
+    FactCheckResult,
+    Generators,
+    ImageFace,
+    ImageFaceAnalysis,
+    ImageForensicsResponse,
+    ImageResult,
+    JobStatus,
+    JobSubmitResponse,
+    Modality,
+    ProvenanceItem,
+    ProvenanceUrl,
+    Verdict,
+    VideoJob,
+    VideoProvider,
+    VideoResult,
+    VideoSubmitResponse,
+    VoiceAnalysisResponse,
+    VoiceWorkflowType,
+)
+from .resources.audio import VoiceWorkflow
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "RaidClient",
+    "AsyncRaidClient",
+    "FileInput",
+    "PagedResult",
+    "RaidApiError",
+    "RaidTimeoutError",
+    "VoiceWorkflow",
+    # models
+    "Claim",
+    "FactCheckJob",
+    "FactCheckResult",
+    "Generators",
+    "ImageFace",
+    "ImageFaceAnalysis",
+    "ImageForensicsResponse",
+    "ImageResult",
+    "JobStatus",
+    "JobSubmitResponse",
+    "Modality",
+    "ProvenanceItem",
+    "ProvenanceUrl",
+    "Verdict",
+    "VideoJob",
+    "VideoProvider",
+    "VideoResult",
+    "VideoSubmitResponse",
+    "VoiceAnalysisResponse",
+    "VoiceWorkflowType",
+    "__version__",
+]

raidxai-0.1.0/src/raidxai/_core.py

@@ -0,0 +1,125 @@
+"""Transport-agnostic request plumbing shared by the sync and async clients.
+
+A :class:`RequestSpec` is a pure description of one HTTP call (built by the
+functions in ``_specs.py``). The sync and async clients each know how to execute
+a spec with retries; everything else — header/URL building, response parsing,
+error mapping, backoff math — lives here so both paths behave identically.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+import httpx
+
+from .errors import RaidApiError, extract_error
+
+# A multipart file part: (field_name, (filename, data, content_type)).
+FilePart = tuple[str, tuple[str, bytes, str]]
+
+
+@dataclass
+class RequestSpec:
+    method: str
+    path: str
+    json: Any = None
+    data: dict[str, str] = field(default_factory=dict)
+    files: list[FilePart] = field(default_factory=list)
+    params: dict[str, Any] = field(default_factory=dict)
+
+    def httpx_kwargs(self) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {}
+        if self.files:
+            kwargs["files"] = self.files
+            if self.data:
+                kwargs["data"] = self.data
+        elif self.json is not None:
+            kwargs["json"] = self.json
+        if self.params:
+            kwargs["params"] = {k: v for k, v in self.params.items() if v is not None}
+        return kwargs
+
+
+def build_headers(api_key: str, auth_header: str) -> dict[str, str]:
+    headers = {"Accept": "application/json"}
+    if auth_header == "x-api-key":
+        headers["X-Api-Key"] = api_key
+    else:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+def is_retryable_status(status: int) -> bool:
+    return status == 429 or status >= 500
+
+
+def backoff_seconds(attempt: int) -> float:
+    """0.5s, 1s, 2s, … (attempt is 1-based)."""
+    return 0.5 * (2 ** (attempt - 1))
+
+
+def retry_after_seconds(response: httpx.Response) -> float | None:
+    """Parse a ``Retry-After`` header — either delta-seconds or an HTTP-date.
+
+    Returns ``None`` when absent/unparseable; ``0.0`` is a valid "retry now" value
+    and is preserved (callers must not treat it as falsy).
+    """
+    header = response.headers.get("retry-after")
+    if not header:
+        return None
+    try:
+        return max(0.0, float(header))
+    except ValueError:
+        pass
+    # HTTP-date form, e.g. "Wed, 16 Jul 2026 12:00:05 GMT" (sent by many proxies/CDNs).
+    try:
+        when = parsedate_to_datetime(header)
+    except (TypeError, ValueError):
+        return None
+    if when is None:
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+    return max(0.0, (when - datetime.now(timezone.utc)).total_seconds())
+
+
+def retry_delay(response: httpx.Response, attempt: int) -> float:
+    """The delay before a retry: the server's ``Retry-After`` if given, else backoff.
+
+    Uses an explicit ``None`` check so a ``Retry-After: 0`` (retry immediately) is honored
+    rather than falling through to exponential backoff.
+    """
+    after = retry_after_seconds(response)
+    return after if after is not None else backoff_seconds(attempt)
+
+
+def parse_response(response: httpx.Response, path: str) -> Any:
+    """Return the parsed JSON body, or raise :class:`RaidApiError` on a non-2xx."""
+    request_id = response.headers.get("request-id") or response.headers.get("x-request-id")
+
+    if response.status_code == 204:
+        return None
+
+    text = response.text
+    parsed: Any = text
+    if "application/json" in response.headers.get("content-type", "") and text:
+        try:
+            parsed = _json.loads(text)
+        except ValueError:
+            parsed = text
+
+    if not response.is_success:
+        message, code = extract_error(parsed)
+        raise RaidApiError(
+            response.status_code,
+            message or f"API error {response.status_code}: {response.reason_phrase}",
+            code=code,
+            body=parsed,
+            request_id=request_id,
+        )
+
+    return parsed