reve 0.1.0__py3-none-any.whl

reve/__init__.py

@@ -0,0 +1,4 @@
+"""Reve Python SDK — A Pythonic interface to the Reve image generation API."""
+
+__version__ = "0.1.0"
+

reve/_client.py

@@ -0,0 +1,180 @@
+"""HTTP client for the Reve API."""
+
+import os
+from typing import Any, Dict, Optional, Tuple, Union
+
+import requests as _requests
+
+from .exceptions import (
+    ReveAPIError,
+    ReveAuthenticationError,
+    ReveBudgetExhaustedError,
+    ReveContentViolationError,
+    ReveRateLimitError,
+    ReveValidationError,
+)
+
+
+_DEFAULT_API_URL = "https://api.reve.com"
+
+
+class ReveClient:
+    """Low-level HTTP client for the Reve API.
+
+    Handles authentication, base URL resolution, and error mapping.
+
+    Args:
+        api_token: Bearer token. Falls back to the ``REVE_API_TOKEN``
+            environment variable if not provided.
+        api_url: Base API URL. Falls back to ``REVE_MONOLITH_LOCATION``
+            env var, then defaults to ``https://api.reve.com``.
+        proxy_authorization: Optional proxy-authorization header value
+            (e.g. for Google IAP). Falls back to
+            ``REVE_PROXY_AUTHORIZATION`` env var.
+        verify: SSL certificate verification. Pass ``False`` to disable
+            SSL verification (e.g. for local development). Defaults to
+            ``True``.
+    """
+
+    def __init__(
+        self,
+        api_token: Optional[str] = None,
+        api_url: Optional[str] = None,
+        proxy_authorization: Optional[str] = None,
+        verify: bool = True,
+    ) -> None:
+        self.api_token: Optional[str] = api_token or os.environ.get("REVE_API_TOKEN")
+        self.api_url: str = (
+            api_url
+            or os.environ.get("REVE_MONOLITH_LOCATION")
+            or _DEFAULT_API_URL
+        )
+        # Strip trailing slash from base URL to avoid double slashes
+        self.api_url = self.api_url.rstrip("/")
+        self.proxy_authorization: Optional[str] = (
+            proxy_authorization
+            or os.environ.get("REVE_PROXY_AUTHORIZATION")
+        )
+        self.verify: bool = verify
+
+    def _headers(self, accept: str = "application/json") -> Dict[str, str]:
+        """Build request headers including auth and accept type.
+
+        Args:
+            accept: Value for the Accept header.
+
+        Returns:
+            Dict of HTTP headers.
+        """
+        headers: Dict[str, str] = {"Accept": accept}
+        if self.api_token:
+            headers["Authorization"] = "Bearer {}".format(self.api_token)
+        if self.proxy_authorization:
+            headers["proxy-authorization"] = self.proxy_authorization
+        return headers
+
+    def _handle_error(self, response: _requests.Response) -> None:
+        """Raise an appropriate exception for error responses.
+
+        Args:
+            response: The HTTP response with a 4xx/5xx status code.
+
+        Raises:
+            ReveValidationError: For HTTP 400.
+            ReveAuthenticationError: For HTTP 401.
+            ReveBudgetExhaustedError: For HTTP 402.
+            ReveRateLimitError: For HTTP 429.
+            ReveAPIError: For all other error status codes.
+        """
+        status = response.status_code
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+
+        message = body.get("message") or body.get("error") or response.text
+        error_code = body.get("error_code")
+
+        if status == 400:
+            raise ReveValidationError(message=message, error_code=error_code)
+        if status == 401:
+            raise ReveAuthenticationError(message=message, error_code=error_code)
+        if status == 402:
+            raise ReveBudgetExhaustedError(message=message, error_code=error_code)
+        if status == 429:
+            retry_after: Optional[Union[float, str]] = response.headers.get("Retry-After")
+            if retry_after is not None:
+                try:
+                    retry_after = float(retry_after)
+                except (ValueError, TypeError):
+                    pass
+            raise ReveRateLimitError(
+                message=message, retry_after=retry_after, error_code=error_code
+            )
+        raise ReveAPIError(
+            message=message, status_code=status, error_code=error_code
+        )
+
+    def post(
+        self,
+        path: str,
+        data: Dict[str, Any],
+        accept: str = "application/json",
+    ) -> Union[Dict[str, Any], Tuple[bytes, Any]]:
+        """Send a POST request to the Reve API.
+
+        Args:
+            path: API path (e.g. ``"/v1/image/create/"``).
+            data: JSON-serializable request body.
+            accept: Accept header value. Use ``"image/jpeg"`` for image
+                endpoints.
+
+        Returns:
+            Parsed JSON dict if *accept* is ``"application/json"``, otherwise
+            a tuple of ``(raw_bytes, response_headers)``.
+
+        Raises:
+            ReveAPIError: If the server returns an error status code.
+        """
+        url = self.api_url + path
+        headers = self._headers(accept=accept)
+        headers["Content-Type"] = "application/json"
+
+        resp = _requests.post(url, json=data, headers=headers, verify=self.verify)
+
+        if resp.status_code >= 400:
+            self._handle_error(resp)
+
+        if accept == "application/json":
+            return resp.json()
+
+        # For image responses, return bytes + headers for metadata extraction
+        return resp.content, resp.headers
+
+    def get(
+        self,
+        path: str,
+        params: Optional[Dict[str, str]] = None,
+    ) -> Any:
+        """Send a GET request to the Reve API.
+
+        Args:
+            path: API path (e.g. ``"/v1/image/balance/"``).
+            params: Optional query parameters dict.
+
+        Returns:
+            Parsed JSON response.
+
+        Raises:
+            ReveAPIError: If the server returns an error status code.
+        """
+        url = self.api_url + path
+        headers = self._headers(accept="application/json")
+
+        resp = _requests.get(url, params=params, headers=headers, verify=self.verify)
+
+        if resp.status_code >= 400:
+            self._handle_error(resp)
+
+        return resp.json()
+

reve/_response.py

@@ -0,0 +1,81 @@
+"""Response classes for the Reve Python SDK."""
+
+import io
+from typing import Optional
+
+from PIL import Image as PILImage
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class ImageResponse(BaseModel):
+    """Response from an image generation API call.
+
+    Contains the generated image as a PIL Image object along with
+    metadata about the request.
+
+    Attributes:
+        image: PIL.Image.Image object containing the generated image.
+        request_id: Unique identifier for the API request.
+        credits_used: Number of API credits consumed by this request.
+        credits_remaining: Number of API credits remaining in the budget.
+        version: Model version used for generation.
+        content_violation: Whether a content policy violation was detected.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    image: PILImage.Image
+    request_id: Optional[str] = None
+    credits_used: Optional[int] = None
+    credits_remaining: Optional[int] = None
+    version: Optional[str] = None
+    content_violation: bool = False
+
+    @classmethod
+    def from_raw(
+        cls,
+        image_bytes: bytes,
+        request_id: Optional[str] = None,
+        credits_used: Optional[str] = None,
+        credits_remaining: Optional[str] = None,
+        version: Optional[str] = None,
+        content_violation: bool = False,
+    ) -> "ImageResponse":
+        """Create an ImageResponse from raw image bytes and header values.
+
+        Args:
+            image_bytes: Raw image file bytes (JPEG, PNG, etc.).
+            request_id: Value from x-reve-request-id header.
+            credits_used: Value from x-reve-credits-used header (string).
+            credits_remaining: Value from x-reve-credits-remaining header (string).
+            version: Value from x-reve-version header.
+            content_violation: Whether content violation was flagged.
+
+        Returns:
+            ImageResponse with parsed image and metadata.
+        """
+        img = PILImage.open(io.BytesIO(image_bytes))
+        return cls(
+            image=img,
+            request_id=request_id,
+            credits_used=int(credits_used) if credits_used is not None else None,
+            credits_remaining=int(credits_remaining) if credits_remaining is not None else None,
+            version=version,
+            content_violation=content_violation,
+        )
+
+    def save(self, *args, **kwargs):
+        """Save the image to a file. Delegates to PIL.Image.save().
+
+        Args:
+            *args: Positional arguments passed to PIL.Image.save().
+            **kwargs: Keyword arguments passed to PIL.Image.save().
+        """
+        return self.image.save(*args, **kwargs)
+
+    def __repr__(self) -> str:
+        w, h = self.image.size
+        return "<ImageResponse request_id={!r} size={}x{}>".format(
+            self.request_id, w, h
+        )
+

reve/exceptions.py

@@ -0,0 +1,115 @@
+"""Exception classes for the Reve Python SDK."""
+
+from typing import Optional, Union
+
+
+class ReveAPIError(Exception):
+    """Base exception for all Reve API errors.
+
+    Attributes:
+        message: Human-readable error description.
+        status_code: HTTP status code that triggered the error, if any.
+        error_code: Machine-readable error code from the API, if any.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        error_code: Optional[str] = None,
+    ) -> None:
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code
+        super().__init__(self.message)
+
+    def __str__(self) -> str:
+        parts = []
+        if self.status_code is not None:
+            parts.append("status={}".format(self.status_code))
+        if self.error_code is not None:
+            parts.append("error_code={}".format(self.error_code))
+        parts.append(self.message)
+        return " ".join(parts)
+
+
+class ReveAuthenticationError(ReveAPIError):
+    """Raised when authentication fails (HTTP 401).
+
+    This typically means the API token is missing, expired, or invalid.
+    """
+
+    def __init__(
+        self,
+        message: str = "Authentication failed",
+        error_code: Optional[str] = None,
+    ) -> None:
+        super().__init__(message, status_code=401, error_code=error_code)
+
+
+class ReveBudgetExhaustedError(ReveAPIError):
+    """Raised when the credit budget is exhausted (HTTP 402).
+
+    Check your balance with :func:`reve.v1.image.get_balance` and
+    top up credits to continue.
+    """
+
+    def __init__(
+        self,
+        message: str = "Budget exhausted",
+        error_code: Optional[str] = None,
+    ) -> None:
+        super().__init__(message, status_code=402, error_code=error_code)
+
+
+class ReveRateLimitError(ReveAPIError):
+    """Raised when the rate limit is exceeded (HTTP 429).
+
+    Attributes:
+        retry_after: Seconds to wait before retrying, if provided by the API.
+    """
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after: Optional[Union[float, str]] = None,
+        error_code: Optional[str] = None,
+    ) -> None:
+        self.retry_after = retry_after
+        super().__init__(message, status_code=429, error_code=error_code)
+
+    def __str__(self) -> str:
+        base = super().__str__()
+        if self.retry_after is not None:
+            return "{} (retry_after={})".format(base, self.retry_after)
+        return base
+
+
+class ReveContentViolationError(ReveAPIError):
+    """Raised when the content violates safety policies.
+
+    This can occur either on input (prompt/images) or on the generated output.
+    """
+
+    def __init__(
+        self,
+        message: str = "Content violation detected",
+        status_code: Optional[int] = None,
+        error_code: Optional[str] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, error_code=error_code)
+
+
+class ReveValidationError(ReveAPIError):
+    """Raised when the request fails validation (HTTP 400).
+
+    Check the ``message`` attribute for details on which parameter was invalid.
+    """
+
+    def __init__(
+        self,
+        message: str = "Validation error",
+        error_code: Optional[str] = None,
+    ) -> None:
+        super().__init__(message, status_code=400, error_code=error_code)
+

reve/v1/__init__.py

@@ -0,0 +1,2 @@
+"""Reve API v1 module."""
+

reve/v1/image.py

@@ -0,0 +1,321 @@
+"""Reve v1 image API functions.
+
+Provides high-level functions for image generation, remixing, editing,
+balance checking, and effect listing.
+"""
+
+import base64
+import io
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+from PIL import Image
+
+from .._client import ReveClient
+from .._response import ImageResponse
+from ..exceptions import ReveContentViolationError
+
+
+#: Types accepted as image inputs for remix/edit.
+ImageInput = Union[str, bytes, Image.Image]
+
+
+def _encode_image(img: ImageInput) -> str:
+    """Convert an image input to a base64-encoded string.
+
+    Args:
+        img: An image as a file path (str), raw bytes, or PIL Image.
+
+    Returns:
+        Base64-encoded string of the image data.
+
+    Raises:
+        TypeError: If ``img`` is not a supported type.
+    """
+    if isinstance(img, str):
+        with open(img, "rb") as f:
+            data = f.read()
+    elif isinstance(img, bytes):
+        data = img
+    elif isinstance(img, Image.Image):
+        buf = io.BytesIO()
+        img.save(buf, format="JPEG")
+        data = buf.getvalue()
+    else:
+        raise TypeError(
+            "Image must be a file path (str), bytes, or PIL.Image; got {}".format(
+                type(img).__name__
+            )
+        )
+    return base64.b64encode(data).decode("ascii")
+
+
+def _make_client(
+    api_token: Optional[str] = None,
+    api_url: Optional[str] = None,
+    proxy_authorization: Optional[str] = None,
+    verify: bool = True,
+) -> ReveClient:
+    """Create a ReveClient from explicit args or environment."""
+    return ReveClient(
+        api_token=api_token,
+        api_url=api_url,
+        proxy_authorization=proxy_authorization,
+        verify=verify,
+    )
+
+
+def _parse_image_response(raw_bytes: bytes, headers: Any) -> ImageResponse:
+    """Parse raw image bytes and response headers into an ImageResponse.
+
+    Args:
+        raw_bytes: Raw image bytes from the API response.
+        headers: Response headers containing metadata.
+
+    Returns:
+        An ImageResponse wrapping the decoded image and metadata.
+
+    Raises:
+        ReveContentViolationError: If the response indicates a content violation.
+    """
+    content_violation = headers.get("x-reve-content-violation", "").lower() in (
+        "true", "1", "yes",
+    )
+    if content_violation:
+        raise ReveContentViolationError(
+            message="Content violation detected in response"
+        )
+
+    return ImageResponse.from_raw(
+        image_bytes=raw_bytes,
+        request_id=headers.get("x-reve-request-id"),
+        credits_used=headers.get("x-reve-credits-used"),
+        credits_remaining=headers.get("x-reve-credits-remaining"),
+        version=headers.get("x-reve-version"),
+        content_violation=content_violation,
+    )
+
+
+_EXCLUDE_KEYS = frozenset(("api_token", "api_url", "proxy_authorization", "verify", "client"))
+
+
+def _build_body(params: Dict[str, Any], exclude: frozenset = _EXCLUDE_KEYS) -> Dict[str, Any]:
+    """Build a JSON body dict, excluding client-config keys and None values."""
+    return {k: v for k, v in params.items() if k not in exclude and v is not None}
+
+
+def create(
+    prompt: str,
+    *,
+    aspect_ratio: Optional[str] = None,
+    version: Optional[str] = None,
+    test_time_scaling: Optional[int] = None,
+    postprocessing: Optional[List[Dict[str, Any]]] = None,
+    api_token: Optional[str] = None,
+    api_url: Optional[str] = None,
+    proxy_authorization: Optional[str] = None,
+    verify: bool = True,
+) -> ImageResponse:
+    """Generate an image from a text prompt.
+
+    Args:
+        prompt: Text description of the image to generate.
+        aspect_ratio: Aspect ratio string. One of ``"16:9"``, ``"3:2"``,
+            ``"4:3"``, ``"1:1"``, ``"3:4"``, ``"2:3"``, ``"9:16"``, or
+            ``"auto"`` (default ``"auto"``).
+        version: Model version identifier or ``"latest"`` (default).
+        test_time_scaling: Quality scaling factor from 1 to 5. Higher values
+            produce better quality but consume more credits.
+        postprocessing: List of postprocessing operation dicts built with
+            helpers from :mod:`reve.v1.postprocessing`.
+        api_token: Override the API token for this request. Falls back to
+            the ``REVE_API_TOKEN`` environment variable.
+        api_url: Override the base API URL. Falls back to
+            ``REVE_MONOLITH_LOCATION`` or ``https://api.reve.com``.
+        proxy_authorization: Override the proxy-authorization header value.
+        verify: SSL certificate verification. Pass ``False`` to disable
+            SSL verification (e.g. for local development).
+
+    Returns:
+        An :class:`~reve._response.ImageResponse` containing the generated
+        PIL Image and response metadata (request_id, credits_used, etc.).
+
+    Raises:
+        ReveAuthenticationError: If the API token is invalid (HTTP 401).
+        ReveBudgetExhaustedError: If the credit budget is exhausted (HTTP 402).
+        ReveRateLimitError: If the rate limit is exceeded (HTTP 429).
+        ReveValidationError: If the request parameters are invalid (HTTP 400).
+        ReveContentViolationError: If the generated content violates policies.
+        ReveAPIError: For other API errors.
+    """
+    client = _make_client(api_token, api_url, proxy_authorization, verify=verify)
+    body = _build_body(locals())
+    raw_bytes, headers = client.post("/v1/image/create/", body, accept="image/jpeg")
+    return _parse_image_response(raw_bytes, headers)
+
+
+def remix(
+    prompt: str,
+    reference_images: Sequence[ImageInput],
+    *,
+    aspect_ratio: Optional[str] = None,
+    version: Optional[str] = None,
+    test_time_scaling: Optional[int] = None,
+    postprocessing: Optional[List[Dict[str, Any]]] = None,
+    api_token: Optional[str] = None,
+    api_url: Optional[str] = None,
+    proxy_authorization: Optional[str] = None,
+    verify: bool = True,
+) -> ImageResponse:
+    """Generate a new image by remixing reference images with a text prompt.
+
+    Reference images can be referred to in the prompt using ``<ref>0</ref>``,
+    ``<ref>1</ref>``, etc.
+
+    Args:
+        prompt: Text prompt describing the desired output. Use
+            ``<ref>N</ref>`` tags to reference images by index.
+        reference_images: Sequence of reference images. Each element can be
+            a file path (str), raw bytes, or a PIL Image.
+        aspect_ratio: Aspect ratio string (see :func:`create`).
+        version: Model version identifier or ``"latest"``.
+        test_time_scaling: Quality scaling factor (1–5).
+        postprocessing: List of postprocessing operation dicts.
+        api_token: Override API token for this request.
+        api_url: Override base API URL.
+        proxy_authorization: Override proxy-authorization header value.
+        verify: SSL certificate verification. Pass ``False`` to disable
+            SSL verification (e.g. for local development).
+
+    Returns:
+        An :class:`~reve._response.ImageResponse` containing the generated
+        PIL Image and response metadata.
+
+    Raises:
+        ReveAuthenticationError: If the API token is invalid (HTTP 401).
+        ReveBudgetExhaustedError: If the credit budget is exhausted (HTTP 402).
+        ReveRateLimitError: If the rate limit is exceeded (HTTP 429).
+        ReveValidationError: If the request parameters are invalid (HTTP 400).
+        ReveContentViolationError: If the generated content violates policies.
+        ReveAPIError: For other API errors.
+        TypeError: If a reference image has an unsupported type.
+    """
+    client = _make_client(api_token, api_url, proxy_authorization, verify=verify)
+    body = _build_body(locals())
+    # Encode reference images to base64
+    body["reference_images"] = [_encode_image(img) for img in reference_images]
+    raw_bytes, headers = client.post("/v1/image/remix/", body, accept="image/jpeg")
+    return _parse_image_response(raw_bytes, headers)
+
+
+def edit(
+    edit_instruction: str,
+    reference_image: ImageInput,
+    *,
+    aspect_ratio: Optional[str] = None,
+    version: Optional[str] = None,
+    test_time_scaling: Optional[int] = None,
+    postprocessing: Optional[List[Dict[str, Any]]] = None,
+    api_token: Optional[str] = None,
+    api_url: Optional[str] = None,
+    proxy_authorization: Optional[str] = None,
+    verify: bool = True,
+) -> ImageResponse:
+    """Edit an existing image using a natural-language instruction.
+
+    Args:
+        edit_instruction: A description of the edit to apply
+            (e.g. ``"Make the sky more dramatic"``).
+        reference_image: The source image to edit. Can be a file path (str),
+            raw bytes, or a PIL Image.
+        aspect_ratio: Aspect ratio string (see :func:`create`).
+        version: Model version identifier or ``"latest"``.
+        test_time_scaling: Quality scaling factor (1–5).
+        postprocessing: List of postprocessing operation dicts.
+        api_token: Override API token for this request.
+        api_url: Override base API URL.
+        proxy_authorization: Override proxy-authorization header value.
+        verify: SSL certificate verification. Pass ``False`` to disable
+            SSL verification (e.g. for local development).
+
+    Returns:
+        An :class:`~reve._response.ImageResponse` containing the edited
+        PIL Image and response metadata.
+
+    Raises:
+        ReveAuthenticationError: If the API token is invalid (HTTP 401).
+        ReveBudgetExhaustedError: If the credit budget is exhausted (HTTP 402).
+        ReveRateLimitError: If the rate limit is exceeded (HTTP 429).
+        ReveValidationError: If the request parameters are invalid (HTTP 400).
+        ReveContentViolationError: If the edited content violates policies.
+        ReveAPIError: For other API errors.
+        TypeError: If the reference image has an unsupported type.
+    """
+    client = _make_client(api_token, api_url, proxy_authorization, verify=verify)
+    body = _build_body(locals())
+    # Encode reference image to base64
+    body["reference_image"] = _encode_image(reference_image)
+    raw_bytes, headers = client.post("/v1/image/edit/", body, accept="image/jpeg")
+    return _parse_image_response(raw_bytes, headers)
+
+
+def get_balance(
+    *,
+    api_token: Optional[str] = None,
+    api_url: Optional[str] = None,
+    proxy_authorization: Optional[str] = None,
+    verify: bool = True,
+) -> Dict[str, Any]:
+    """Get the current credit balance.
+
+    Args:
+        api_token: Override API token for this request.
+        api_url: Override base API URL.
+        proxy_authorization: Override proxy-authorization header value.
+        verify: SSL certificate verification. Pass ``False`` to disable
+            SSL verification (e.g. for local development).
+
+    Returns:
+        A dict with ``budget_id`` (str) and ``new_balance`` (number) keys.
+
+    Raises:
+        ReveAuthenticationError: If the API token is invalid (HTTP 401).
+        ReveAPIError: For other API errors.
+    """
+    client = _make_client(api_token, api_url, proxy_authorization, verify=verify)
+    return client.get("/api/misc/balance/")
+
+
+def list_effects(
+    source: Optional[str] = None,
+    *,
+    api_token: Optional[str] = None,
+    api_url: Optional[str] = None,
+    proxy_authorization: Optional[str] = None,
+    verify: bool = True,
+) -> List[Dict[str, Any]]:
+    """List available effects for postprocessing.
+
+    Args:
+        source: Filter effects by source. One of ``"all"``, ``"project"``,
+            or ``"preset"``. If ``None``, returns all effects.
+        api_token: Override API token for this request.
+        api_url: Override base API URL.
+        proxy_authorization: Override proxy-authorization header value.
+        verify: SSL certificate verification. Pass ``False`` to disable
+            SSL verification (e.g. for local development).
+
+    Returns:
+        A list of dicts, each with ``name``, ``description``, ``source``,
+        and ``category`` keys describing an available effect.
+
+    Raises:
+        ReveAuthenticationError: If the API token is invalid (HTTP 401).
+        ReveAPIError: For other API errors.
+    """
+    client = _make_client(api_token, api_url, proxy_authorization, verify=verify)
+    params: Optional[Dict[str, str]] = None
+    if source is not None:
+        params = {"source": source}
+    resp = client.get("/v1/image/effect/", params=params)
+    return resp.get("effects", [])
+

reve/v1/postprocessing.py

@@ -0,0 +1,87 @@
+"""Postprocessing helper functions for building postprocessing pipelines.
+
+These functions return dicts that can be passed in the ``postprocessing``
+list of image generation calls.
+
+Example::
+
+    from reve.v1.postprocessing import upscale, remove_background
+
+    img = create(
+        prompt="A red dragon",
+        postprocessing=[upscale(factor=2), remove_background()],
+    )
+"""
+
+from typing import Any, Dict, Optional
+
+
+def upscale(factor: int = 2) -> Dict[str, Any]:
+    """Upscale the generated image by a given factor.
+
+    Args:
+        factor: Upscale multiplier (default 2).
+
+    Returns:
+        A postprocessing operation dict suitable for the ``postprocessing``
+        parameter of image generation functions.
+    """
+    return {"process": "upscale", "upscale_factor": factor}
+
+
+def remove_background() -> Dict[str, Any]:
+    """Remove the image background, producing a transparent PNG.
+
+    Returns:
+        A postprocessing operation dict suitable for the ``postprocessing``
+        parameter of image generation functions.
+    """
+    return {"process": "remove_background"}
+
+
+def fit_image(
+    max_width: Optional[int] = None,
+    max_height: Optional[int] = None,
+    max_dim: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Constrain image dimensions to fit within given bounds.
+
+    At least one constraint should be provided.
+
+    Args:
+        max_width: Maximum width in pixels (1–1024).
+        max_height: Maximum height in pixels (1–1024).
+        max_dim: Maximum dimension for both width and height (1–1024).
+
+    Returns:
+        A postprocessing operation dict suitable for the ``postprocessing``
+        parameter of image generation functions.
+    """
+    result: Dict[str, Any] = {"process": "fit_image"}
+    if max_width is not None:
+        result["max_width"] = max_width
+    if max_height is not None:
+        result["max_height"] = max_height
+    if max_dim is not None:
+        result["max_dim"] = max_dim
+    return result
+
+
+def effect(name: str, parameters: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """Apply a named effect to the generated image.
+
+    Use :func:`reve.v1.image.list_effects` to discover available effect names.
+
+    Args:
+        name: Effect name (e.g. ``"sepia"``, ``"blur"``).
+        parameters: Optional dict of effect-specific parameters.
+
+    Returns:
+        A postprocessing operation dict suitable for the ``postprocessing``
+        parameter of image generation functions.
+    """
+    result: Dict[str, Any] = {"process": "effect", "effect_name": name}
+    if parameters is not None:
+        result["effect_parameters"] = parameters
+    return result
+

reve-0.1.0.dist-info/METADATA

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: reve
+Version: 0.1.0
+Summary: Python SDK for the Reve image generation API
+License-Expression: CC-BY-SA-4.0
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.20.0
+Requires-Dist: Pillow>=8.0.0
+Requires-Dist: pydantic>=1.10.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: responses>=0.20.0; extra == "dev"
+
+# Reve Python SDK
+
+A Pythonic interface to the [Reve](https://reve.art) image-generation API.
+Generate, remix, and edit images with a handful of function calls.
+
+## Installation
+
+From PyPI:
+
+```bash
+pip install reve
+```
+
+From source:
+
+```bash
+git clone https://github.com/reve-ai/reve-core.git
+cd reve-core/sdk/python
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from reve.v1.image import create
+
+img = create(prompt="A beautiful sunset over the ocean")
+img.save("sunset.jpg")
+print(img.credits_remaining)
+```
+
+> Set the `REVE_API_TOKEN` environment variable before running,
+> or pass `api_token=` directly to any function.
+
+## Authentication
+
+The SDK reads credentials from environment variables by default:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `REVE_API_TOKEN` | Bearer token (required) | — |
+| `REVE_MONOLITH_LOCATION` | API base URL | `https://api.reve.com` |
+| `REVE_PROXY_AUTHORIZATION` | Proxy-authorization header | — |
+
+```bash
+export REVE_API_TOKEN="papi.your-token-here"
+```
+
+You can also pass them per-call:
+
+```python
+img = create(
+    prompt="A sunset",
+    api_token="papi.your-token-here",
+    api_url="https://custom-endpoint.example.com",
+)
+```
+
+## API Reference
+
+All image functions live in `reve.v1.image`.
+
+### `create(prompt, *, aspect_ratio, version, test_time_scaling, postprocessing, ...)`
+
+Generate an image from a text prompt.
+
+```python
+from reve.v1.image import create
+from reve.v1.postprocessing import upscale, remove_background
+
+img = create(
+    prompt="A red dragon flying over mountains",
+    aspect_ratio="16:9",
+    version="latest",
+    test_time_scaling=3,
+    postprocessing=[upscale(factor=2), remove_background()],
+)
+img.save("dragon.png")
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `prompt` | `str` | Text description of the image (positional). |
+| `aspect_ratio` | `str \| None` | One of `"16:9"`, `"3:2"`, `"4:3"`, `"1:1"`, `"3:4"`, `"2:3"`, `"9:16"`, `"auto"`. Default `"auto"`. |
+| `version` | `str \| None` | Model version identifier or `"latest"`. |
+| `test_time_scaling` | `int \| None` | Quality factor 1–5. Higher = better quality, more credits. |
+| `postprocessing` | `list[dict] \| None` | Postprocessing pipeline (see below). |
+
+### `remix(prompt, reference_images, *, ...)`
+
+Remix reference images into a new image guided by a prompt.
+Use `<ref>0</ref>`, `<ref>1</ref>`, … to refer to each reference image.
+
+```python
+from reve.v1.image import remix
+
+img = remix(
+    prompt="The subject from <ref>0</ref> standing in a magical forest",
+    reference_images=["photo.jpg"],
+    aspect_ratio="1:1",
+)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `prompt` | `str` | Text prompt with optional `<ref>N</ref>` tags (positional). |
+| `reference_images` | `Sequence[str \| bytes \| PIL.Image]` | Reference images — file paths, raw bytes, or PIL Images (positional). |
+| `aspect_ratio` | `str \| None` | Aspect ratio (see `create`). |
+| `version` | `str \| None` | Model version. |
+| `test_time_scaling` | `int \| None` | Quality factor 1–5. |
+| `postprocessing` | `list[dict] \| None` | Postprocessing pipeline. |
+
+### `edit(edit_instruction, reference_image, *, ...)`
+
+Edit an existing image with a natural-language instruction.
+
+```python
+from reve.v1.image import edit
+
+img = edit(
+    edit_instruction="Make the sky more dramatic with storm clouds",
+    reference_image="original.jpg",
+)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `edit_instruction` | `str` | Description of the edit (positional). |
+| `reference_image` | `str \| bytes \| PIL.Image` | Source image (positional). |
+| `aspect_ratio` | `str \| None` | Aspect ratio (see `create`). |
+| `version` | `str \| None` | Model version. |
+| `test_time_scaling` | `int \| None` | Quality factor 1–5. |
+| `postprocessing` | `list[dict] \| None` | Postprocessing pipeline. |
+
+### `get_balance(*, ...)`
+
+Return the current credit balance.
+
+```python
+from reve.v1.image import get_balance
+
+balance = get_balance()
+print(balance)  # {"budget_id": "abc123", "new_balance": 500}
+```
+
+Returns a `dict` with keys `budget_id` (str) and `new_balance` (number).
+
+### `list_effects(source=None, *, ...)`
+
+List available effects for postprocessing.
+
+```python
+from reve.v1.image import list_effects
+
+effects = list_effects(source="preset")
+for e in effects:
+    print(e["name"], "-", e["description"])
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `source` | `str \| None` | Filter by source: `"all"`, `"project"`, or `"preset"`. |
+
+Returns a list of dicts with `name`, `description`, `source`, and `category` keys.
+
+## Postprocessing
+
+Build postprocessing pipelines with helpers from `reve.v1.postprocessing`:
+
+```python
+from reve.v1.postprocessing import upscale, remove_background, fit_image, effect
+```
+
+| Helper | Description |
+|--------|-------------|
+| `upscale(factor=2)` | Upscale the image by the given factor. |
+| `remove_background()` | Remove the background (produces transparent PNG). |
+| `fit_image(max_width=None, max_height=None, max_dim=None)` | Constrain dimensions (pixels, 1–1024). |
+| `effect(name, parameters=None)` | Apply a named effect. Use `list_effects()` for available names. |
+
+Pass them as a list to the `postprocessing` parameter:
+
+```python
+img = create(
+    prompt="A cat astronaut",
+    postprocessing=[upscale(factor=2), remove_background()],
+)
+```
+
+## Response Object
+
+`create()`, `remix()`, and `edit()` return an `ImageResponse` (a Pydantic BaseModel):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `image` | `PIL.Image.Image` | The generated image. |
+| `request_id` | `str \| None` | Unique request identifier. |
+| `credits_used` | `int \| None` | Credits consumed by this request. |
+| `credits_remaining` | `int \| None` | Credits remaining in the budget. |
+| `version` | `str \| None` | Model version used. |
+| `content_violation` | `bool` | Whether a content violation was flagged. |
+
+```python
+img = create(prompt="A sunset")
+img.image              # PIL.Image.Image
+img.request_id         # "req_abc123"
+img.credits_used       # 10
+img.credits_remaining  # 490
+img.version            # "v1.2"
+img.save("out.jpg")    # delegates to PIL.Image.save()
+```
+
+## Error Handling
+
+All exceptions inherit from `ReveAPIError`:
+
+```
+ReveAPIError                  # Base — any API error
+├── ReveAuthenticationError   # HTTP 401 — bad or missing token
+├── ReveBudgetExhaustedError  # HTTP 402 — out of credits
+├── ReveRateLimitError        # HTTP 429 — rate limited (has .retry_after)
+├── ReveValidationError       # HTTP 400 — invalid parameters
+└── ReveContentViolationError # Content policy violation
+```
+
+```python
+from reve.exceptions import ReveAPIError, ReveRateLimitError
+from reve.v1.image import create
+
+try:
+    img = create(prompt="A sunset")
+except ReveRateLimitError as exc:
+    print(f"Rate limited — retry after {exc.retry_after}s")
+except ReveAPIError as exc:
+    print(f"API error (status {exc.status_code}): {exc.message}")
+```
+
+## Examples
+
+Working example scripts are in the [`examples/`](examples/) directory:
+
+- [`create_image.py`](examples/create_image.py) — Generate images with optional postprocessing.
+- [`remix_image.py`](examples/remix_image.py) — Remix a reference image with a prompt.
+- [`edit_image.py`](examples/edit_image.py) — Edit an existing image.
+
+## Development
+
+Install development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run the test suite:
+
+```bash
+pytest
+```
+
+## License
+
+This SDK is released under the [Creative Commons Attribution-ShareAlike 4.0 International License](https://creativecommons.org/licenses/by-sa/4.0/).

reve-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+reve/__init__.py,sha256=SDa-YQGjlx3yWXw3ps4cNe7P00Fs7M_zayGUdhB2AEw,105
+reve/_client.py,sha256=7RhPAXRFZc1wZW36fwx_cXbnOdc0ki2CHCnP8D1oz1s,5927
+reve/_response.py,sha256=YbaENxOS2ZLzHJehZEzj4t8h40LYv6sRq8QH3TFvyIA,2856
+reve/exceptions.py,sha256=YgtOX9oL4YeHOfHIWa93uWhim9UOooQA8qCXhIOUbUY,3394
+reve/v1/__init__.py,sha256=KSCzZtSzU7QPunuKVfAEuLt-hcgM_DL8bD8pfsoXE6o,27
+reve/v1/image.py,sha256=b0apa2Du3PFm9Eiq26p2XjaqzUsnd6iZBzL38AUvyIs,12355
+reve/v1/postprocessing.py,sha256=48GZbTRr6iMRO5llr3G2rCaI80MiOXbuQ7wYZQMZyI0,2648
+reve-0.1.0.dist-info/METADATA,sha256=cYhDV5x-BFzC59lSPL8Kf3UtZaT6m9fzFbZYTTeCA5s,8163
+reve-0.1.0.dist-info/WHEEL,sha256=YCfwYGOYMi5Jhw2fU4yNgwErybb2IX5PEwBKV4ZbdBo,91
+reve-0.1.0.dist-info/top_level.txt,sha256=u_WgbUwgdd-a5Zq9cqf9RDMEu1N24r4kpbEkKsxUPeg,5
+reve-0.1.0.dist-info/RECORD,,

reve-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

reve-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+reve