raidxai 0.1.0__py3-none-any.whl

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/_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

raidxai/_generated/models.py

@@ -0,0 +1,460 @@
+# generated by datamodel-codegen:
+#   filename:  openapi.yaml
+#   timestamp: 2026-07-26T10:34:39+00:00
+
+from __future__ import annotations
+from typing import Annotated, Any
+from pydantic import AwareDatetime, BaseModel, Field, RootModel
+from enum import Enum, IntEnum
+from uuid import UUID
+
+
+class Error1(BaseModel):
+    code: Annotated[str, Field(examples=["IMAGE_FORENSICS:FILE_TOO_LARGE"])]
+    """
+    Stable machine-readable error code.
+    """
+    message: str
+    """
+    Human-readable explanation, safe to log.
+    """
+    source_host: Annotated[str | None, Field(alias="sourceHost")] = None
+    """
+    For URL-based endpoints, the host that could not be resolved.
+    """
+    user_message: Annotated[str | None, Field(alias="userMessage")] = None
+    """
+    A display-friendly variant of the message (URL-based endpoints only).
+    """
+
+
+class Error(BaseModel):
+    """
+    Standard error envelope returned by every endpoint on failure.
+    """
+
+    error: Error1
+
+
+class Verdict(Enum):
+    """
+    Overall classification of the media.
+    - `real` — no manipulation detected
+    - `ai_generated` — produced by a generative model
+    - `ai_edited` — a real asset modified with AI tools
+    - `digitally_edited` — conventional (non-AI) editing
+    - `unknown` — the analysis was inconclusive
+
+    """
+
+    real = "real"
+    ai_generated = "ai_generated"
+    ai_edited = "ai_edited"
+    digitally_edited = "digitally_edited"
+    unknown = "unknown"
+
+
+class JobStatus(Enum):
+    """
+    Lifecycle state of an asynchronous job.
+    """
+
+    queued = "Queued"
+    processing = "Processing"
+    completed = "Completed"
+    failed = "Failed"
+    cancelled = "Cancelled"
+
+
+class Modality(Enum):
+    """
+    The kind of media being submitted.
+    """
+
+    image = "image"
+    audio = "audio"
+    video = "video"
+
+
+class VoiceWorkflowType(IntEnum):
+    """
+    Which voice workflow to run:
+    - `1` — Transcription only
+    - `2` — Intelligence (text analysis) only
+    - `3` — Combined transcription + intelligence
+    - `4` — AI-voice detection only (default)
+
+    """
+
+    integer_1 = 1
+    integer_2 = 2
+    integer_3 = 3
+    integer_4 = 4
+
+
+class Generators(RootModel[dict[str, Any] | None]):
+    root: dict[str, Any] | None
+    """
+    Generator attribution as a map of generator name → score (0–1), e.g.
+    `{ "midjourney": 0.95 }`. Keys are returned dynamically by the detector.
+    Null on basic plans.
+
+    """
+
+
+class Stage(Enum):
+    """
+    Which analysis stage decided the verdict.
+    """
+
+    full_image = "full_image"
+    face_crop = "face_crop"
+    full_image_no_face = "full_image_no_face"
+    raw = "raw"
+
+
+class ImageFace(BaseModel):
+    """
+    One detected face, located in original image pixels.
+    """
+
+    x: float
+    """
+    Left edge of the face rectangle, in pixels.
+    """
+    y: float
+    """
+    Top edge of the face rectangle, in pixels.
+    """
+    width: float
+    height: float
+    confidence: Annotated[float, Field(ge=0.0, le=1.0)]
+    """
+    Confidence that this region is a face.
+    """
+    deepfake_score: Annotated[float, Field(alias="deepfakeScore", ge=0.0, le=1.0)]
+    """
+    Likelihood this face is synthetic, from 0 to 1.
+    """
+
+
+class VoiceAnalysisResponse(BaseModel):
+    is_successful: Annotated[bool, Field(alias="isSuccessful")]
+    error_message: Annotated[str | None, Field(alias="errorMessage")] = None
+    workflow_type: Annotated[VoiceWorkflowType, Field(alias="workflowType")]
+    transcript: str | None = None
+    """
+    Transcribed text. Populated for Transcription and Combined workflows.
+    """
+    analysis: str | None = None
+    """
+    Intelligence analysis text. Populated for Intelligence and Combined workflows.
+    """
+    context_used: Annotated[str | None, Field(alias="contextUsed")] = None
+    """
+    The context hints that were applied, if any.
+    """
+    is_ai_detected: Annotated[bool | None, Field(alias="isAiDetected")] = None
+    """
+    Whether the voice is AI-generated. Populated for the AI-detection workflow.
+    """
+    detection_confidence: Annotated[
+        float | None, Field(alias="detectionConfidence", ge=0.0, le=1.0)
+    ] = None
+    """
+    Confidence of the AI-voice detection (0–1).
+    """
+    detection_classification: Annotated[str | None, Field(alias="detectionClassification")] = None
+    """
+    Classification label for detection, e.g. `real`, `suspicious`, or `fake`.
+    """
+    processing_time_ms: Annotated[int, Field(alias="processingTimeMs")]
+    credits_used: Annotated[int, Field(alias="creditsUsed")]
+    metadata: dict[str, Any] | None = None
+    """
+    Additional workflow metadata, when available.
+    """
+
+
+class JobSubmitResponse(BaseModel):
+    """
+    Returned when an asynchronous fact-checking job is accepted.
+    """
+
+    job_id: Annotated[UUID, Field(alias="jobId")]
+    """
+    Identifier to poll for status and results.
+    """
+    status: JobStatus | None = None
+    credits_reserved: Annotated[int, Field(alias="creditsReserved")]
+    """
+    Credits held pending completion; confirmed on success and refunded on failure/cancel.
+    """
+
+
+class VideoSubmitResponse(BaseModel):
+    """
+    Returned when a video job is accepted.
+    """
+
+    job_id: Annotated[UUID, Field(alias="jobId")]
+    """
+    Identifier to poll for status and results.
+    """
+    credits_reserved: Annotated[int, Field(alias="creditsReserved")]
+    """
+    Credits held pending completion; confirmed on success and refunded on failure/cancel.
+    """
+
+
+class VideoProvider(BaseModel):
+    """
+    Per-provider breakdown (detailed plans only).
+    """
+
+    name: str
+    """
+    Provider identifier.
+    """
+    verdict: Verdict
+    confidence: Annotated[float, Field(ge=0.0, le=1.0)]
+    frames_analyzed: Annotated[int | None, Field(alias="framesAnalyzed")] = None
+
+
+class VideoResult(BaseModel):
+    """
+    Populated on a video job once `status` is `Completed`.
+    """
+
+    verdict: Verdict
+    confidence: Annotated[float, Field(ge=0.0, le=1.0)]
+    is_ai_generated: Annotated[bool, Field(alias="isAiGenerated")]
+    frames_analyzed: Annotated[int, Field(alias="framesAnalyzed")]
+    duration_seconds: Annotated[float | None, Field(alias="durationSeconds")] = None
+    summary: str | None = None
+    """
+    Short human-readable summary of the finding.
+    """
+    providers: list[VideoProvider] | None = None
+    """
+    Per-provider breakdown. Null on basic plans.
+    """
+    has_detailed_report: Annotated[bool, Field(alias="hasDetailedReport")]
+    """
+    True when detailed fields (e.g. `providers`) are populated. False on basic plans.
+    """
+
+
+class VideoJob(BaseModel):
+    id: UUID
+    file_name: Annotated[str, Field(alias="fileName")]
+    file_size_bytes: Annotated[int | None, Field(alias="fileSizeBytes")] = None
+    duration_seconds: Annotated[float | None, Field(alias="durationSeconds")] = None
+    status: JobStatus
+    progress: Annotated[int, Field(ge=0, le=100)]
+    """
+    Percent complete.
+    """
+    status_message: Annotated[str | None, Field(alias="statusMessage")] = None
+    credits_reserved: Annotated[int, Field(alias="creditsReserved")]
+    credits_used: Annotated[int, Field(alias="creditsUsed")]
+    frames_analyzed: Annotated[int | None, Field(alias="framesAnalyzed")] = None
+    processing_time_ms: Annotated[int, Field(alias="processingTimeMs")]
+    error_message: Annotated[str | None, Field(alias="errorMessage")] = None
+    created_at: Annotated[AwareDatetime, Field(alias="createdAt")]
+    modified_at: Annotated[AwareDatetime | None, Field(alias="modifiedAt")] = None
+    result: VideoResult | None = None
+    """
+    Null until the job completes.
+    """
+
+
+class ProvenanceUrl(BaseModel):
+    url: str
+    page_title: Annotated[str | None, Field(alias="pageTitle")] = None
+    first_seen_at: Annotated[AwareDatetime | None, Field(alias="firstSeenAt")] = None
+    match_type: Annotated[str | None, Field(alias="matchType")] = None
+    """
+    How the media matched this URL, e.g. `full`, `partial`, `page`, `entity`.
+    """
+    relevance: str | None = None
+    """
+    Assessed relevance — `high`, `medium`, or `low`.
+    """
+
+
+class ProvenanceItem(BaseModel):
+    """
+    A domain where the media (or closely matching media) was found.
+    """
+
+    domain: Annotated[str, Field(examples=["bbc.com"])]
+    tier: str
+    """
+    Source tier — `authoritative`, `news`, `social`, or `unknown`.
+    """
+    urls: list[ProvenanceUrl]
+    is_earliest_seen: Annotated[bool | None, Field(alias="isEarliestSeen")] = None
+    """
+    True for the earliest-known appearance across the result.
+    """
+
+
+class Claim(BaseModel):
+    """
+    A checkable claim extracted from audio/video. Null/absent for image jobs.
+    """
+
+    claim_text: Annotated[str, Field(alias="claimText")]
+    verbatim_quote: Annotated[str | None, Field(alias="verbatimQuote")] = None
+    verdict: str | None = None
+    """
+    Assessment — `supported`, `contradicted`, `mixed`, or `unverified`.
+    """
+    confidence: Annotated[float | None, Field(ge=0.0, le=1.0)] = None
+    speaker: str | None = None
+
+
+class FactCheckResult(BaseModel):
+    """
+    Populated on a fact-checking job once `status` is `Completed`. Additional fields may be
+    present for detailed reports — clients should ignore unknown fields (see Versioning).
+
+    """
+
+    modality: Modality
+    has_detailed_report: Annotated[bool, Field(alias="hasDetailedReport")]
+    summary: str
+    """
+    One-paragraph synthesis of the finding.
+    """
+    provenance: list[ProvenanceItem]
+    """
+    Domains where the media was found, grouped by source.
+    """
+    claims: list[Claim] | None = None
+    """
+    Extracted claims with verdicts (audio/video only).
+    """
+    transcript: str | None = None
+    """
+    Diarized transcript (audio/video only).
+    """
+
+
+class FactCheckJob(BaseModel):
+    id: UUID
+    modality: Modality
+    file_name: Annotated[str, Field(alias="fileName")]
+    file_size_bytes: Annotated[int | None, Field(alias="fileSizeBytes")] = None
+    duration_seconds: Annotated[float | None, Field(alias="durationSeconds")] = None
+    status: JobStatus
+    progress: Annotated[int, Field(ge=0, le=100)]
+    status_message: Annotated[str | None, Field(alias="statusMessage")] = None
+    credits_reserved: Annotated[int, Field(alias="creditsReserved")]
+    credits_used: Annotated[int, Field(alias="creditsUsed")]
+    processing_time_ms: Annotated[int, Field(alias="processingTimeMs")]
+    error_message: Annotated[str | None, Field(alias="errorMessage")] = None
+    user_context: Annotated[str | None, Field(alias="userContext")] = None
+    """
+    The context you supplied at submit, echoed back.
+    """
+    created_at: Annotated[AwareDatetime, Field(alias="createdAt")]
+    modified_at: Annotated[AwareDatetime | None, Field(alias="modifiedAt")] = None
+    result: FactCheckResult | None = None
+    """
+    Null until the job completes.
+    """
+
+
+class ImageFaceAnalysis(BaseModel):
+    """
+    How the verdict was reached at face level. When `stage` is `face_crop`, every
+    detected face was scored individually; when the whole image decided
+    (`full_image`, or `full_image_no_face` when no face was detected),
+    `decidingFace` and `faces` are null by design.
+
+    """
+
+    stage: Stage
+    """
+    Which analysis stage decided the verdict.
+    """
+    full_image_score: Annotated[float | None, Field(alias="fullImageScore", ge=0.0, le=1.0)] = None
+    """
+    Whole image synthetic score from the first analysis stage.
+    """
+    deciding_face: Annotated[ImageFace | None, Field(alias="decidingFace")] = None
+    """
+    The face that determined the verdict; null when the whole image decided.
+    """
+    faces: list[ImageFace] | None = None
+    """
+    Every detected face, largest first; null when the whole image decided.
+    """
+
+
+class ImageResult(BaseModel):
+    id: UUID | None = None
+    """
+    Stable record ID for this image (null if the image failed to process).
+    """
+    file_name: Annotated[str, Field(alias="fileName")]
+    """
+    Original file name (or a derived name for URL inputs).
+    """
+    verdict: Verdict
+    confidence: Annotated[float, Field(examples=[0.972], ge=0.0, le=1.0)]
+    """
+    Confidence in the verdict, from 0 to 1.
+    """
+    is_manipulated: Annotated[bool, Field(alias="isManipulated")]
+    """
+    Convenience flag — true when `verdict` is anything other than `real`.
+    """
+    credits_used: Annotated[int, Field(alias="creditsUsed")]
+    """
+    Credits charged for this image.
+    """
+    processing_time_ms: Annotated[int, Field(alias="processingTimeMs")]
+    """
+    Server-side processing time in milliseconds.
+    """
+    error_message: Annotated[str | None, Field(alias="errorMessage")] = None
+    """
+    Failure reason when this image could not be analyzed; otherwise null.
+    """
+    created_at: Annotated[AwareDatetime, Field(alias="createdAt")]
+    deepfake_score: Annotated[float | None, Field(alias="deepfakeScore")] = None
+    """
+    Likelihood the image is a deepfake (0–1). Null on basic plans.
+    """
+    generators: Generators | None = None
+    heatmap_url: Annotated[str | None, Field(alias="heatmapUrl")] = None
+    """
+    URL to a manipulation heatmap visualization. Null on basic plans.
+    """
+    face_analysis: Annotated[ImageFaceAnalysis | None, Field(alias="faceAnalysis")] = None
+    """
+    Face level analysis of the detection. Present only when face details are
+    enabled on your account; null otherwise, and null on images where the
+    analysis did not run face by face.
+
+    """
+
+
+class ImageForensicsResponse(BaseModel):
+    images: list[ImageResult]
+    total_credits_used: Annotated[int, Field(alias="totalCreditsUsed")]
+    total_processing_time_ms: Annotated[int, Field(alias="totalProcessingTimeMs")]
+    is_successful: Annotated[bool, Field(alias="isSuccessful")]
+    """
+    True when at least one image was analyzed successfully.
+    """
+    error_message: Annotated[str | None, Field(alias="errorMessage")] = None
+    has_detailed_report: Annotated[bool, Field(alias="hasDetailedReport")]
+    """
+    True when the response includes detailed fields (`generators`, `deepfakeScore`,
+    `heatmapUrl`). False on basic plans, where those fields are null.
+
+    """