llamagen-python 0.1.0__py3-none-any.whl

llamagen/__init__.py

@@ -0,0 +1,16 @@
+from ._client import LlamaGenClient
+from ._errors import LlamaGenAPIError, LlamaGenTimeoutError, LlamaGenWebhookSignatureError
+from ._types import SUPPORTED_COMIC_SIZES
+from ._webhooks import construct_webhook_event, verify_webhook_signature
+
+__all__ = [
+    "LlamaGenAPIError",
+    "LlamaGenClient",
+    "LlamaGenTimeoutError",
+    "LlamaGenWebhookSignatureError",
+    "SUPPORTED_COMIC_SIZES",
+    "construct_webhook_event",
+    "verify_webhook_signature",
+]
+
+__version__ = "0.1.0"

llamagen/_client.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from typing import Optional
+
+from ._http import HTTPClient, Transport
+from .resources.animations import AnimationsResource
+from .resources.comics import ComicsResource
+
+DEFAULT_BASE_URL = "https://api.llamagen.ai/v1"
+DEFAULT_TIMEOUT_MS = 30000
+DEFAULT_MAX_RETRIES = 2
+DEFAULT_RETRY_DELAY_MS = 500
+
+
+class LlamaGenClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout_ms: int = DEFAULT_TIMEOUT_MS,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        retry_delay_ms: int = DEFAULT_RETRY_DELAY_MS,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("`api_key` is required to initialize LlamaGenClient.")
+
+        http = HTTPClient(
+            api_key=api_key,
+            base_url=base_url,
+            timeout_ms=timeout_ms,
+            max_retries=max_retries,
+            retry_delay_ms=retry_delay_ms,
+            transport=transport,
+        )
+
+        comic = ComicsResource(http)
+        animation = AnimationsResource(http)
+
+        self.comic = comic
+        self.comics = comic
+        self.animation = animation
+        self.animations = animation

llamagen/_errors.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class LlamaGenAPIError(Exception):
+    """Raised when the LlamaGen API returns a non-2xx response."""
+
+    def __init__(self, message: str, status: int, data: Optional[Any] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.data = data
+
+
+class LlamaGenTimeoutError(TimeoutError):
+    """Raised when a request or polling operation times out."""
+
+
+class LlamaGenWebhookSignatureError(ValueError):
+    """Raised when webhook signature verification fails."""

llamagen/_http.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import json
+import socket
+import time
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Mapping, Optional, Protocol, Tuple
+
+from ._errors import LlamaGenAPIError, LlamaGenTimeoutError
+
+
+class Transport(Protocol):
+    def request(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: Optional[bytes],
+        timeout: float,
+    ) -> Tuple[int, Mapping[str, str], bytes]:
+        ...
+
+
+class UrllibTransport:
+    def request(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: Optional[bytes],
+        timeout: float,
+    ) -> Tuple[int, Mapping[str, str], bytes]:
+        request = urllib.request.Request(url, data=body, method=method, headers=dict(headers))
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                return response.status, dict(response.headers.items()), response.read()
+        except urllib.error.HTTPError as error:
+            return error.code, dict(error.headers.items()), error.read()
+
+
+class HTTPClient:
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str,
+        timeout_ms: int,
+        max_retries: int,
+        retry_delay_ms: int,
+        transport: Optional[Transport] = None,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout_ms / 1000
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay_ms / 1000
+        self.transport = transport or UrllibTransport()
+
+    def request(
+        self,
+        path: str,
+        *,
+        method: str = "GET",
+        json_body: Optional[Mapping[str, Any]] = None,
+        body: Optional[bytes] = None,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Any:
+        if json_body is not None and body is not None:
+            raise ValueError("Pass either json_body or body, not both.")
+
+        prepared_headers: Dict[str, str] = {"Authorization": f"Bearer {self.api_key}"}
+        if json_body is not None:
+            body = json.dumps(json_body, separators=(",", ":")).encode("utf-8")
+            prepared_headers["Content-Type"] = "application/json"
+        if headers:
+            prepared_headers.update(headers)
+
+        attempt = 0
+        url = f"{self.base_url}{path}"
+
+        while True:
+            try:
+                status, response_headers, response_body = self.transport.request(
+                    method,
+                    url,
+                    prepared_headers,
+                    body,
+                    self.timeout,
+                )
+            except Exception as error:
+                if _is_timeout_error(error):
+                    raise LlamaGenTimeoutError(f"Request timed out after {int(self.timeout * 1000)}ms") from error
+                raise
+
+            data = _decode_response(response_body, response_headers)
+            if 200 <= status < 300:
+                return data
+
+            if _should_retry(status) and attempt < self.max_retries:
+                attempt += 1
+                time.sleep(self.retry_delay * attempt)
+                continue
+
+            raise LlamaGenAPIError(f"LlamaGen API request failed with status {status}", status, data)
+
+
+def _decode_response(body: bytes, headers: Mapping[str, str]) -> Any:
+    if not body:
+        return None
+
+    text = body.decode("utf-8", errors="replace")
+    content_type = ""
+    for key, value in headers.items():
+        if key.lower() == "content-type":
+            content_type = value
+            break
+
+    if "application/json" in content_type.lower():
+        return json.loads(text)
+
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return text
+
+
+def _should_retry(status: int) -> bool:
+    return status == 429 or status >= 500
+
+
+def _is_timeout_error(error: BaseException) -> bool:
+    if isinstance(error, (TimeoutError, socket.timeout)):
+        return True
+    if isinstance(error, urllib.error.URLError):
+        return isinstance(error.reason, (TimeoutError, socket.timeout))
+    return False

llamagen/_types.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Mapping, MutableMapping, Optional, Sequence, TypedDict, Union
+
+
+SUPPORTED_COMIC_SIZES = (
+    "1024x1024",
+    "512x768",
+    "512x1024",
+    "576x1024",
+    "768x1024",
+    "1024x768",
+    "768x512",
+    "1024x576",
+    "1024x512",
+)
+
+JSONValue = Union[None, bool, int, float, str, List["JSONValue"], Dict[str, "JSONValue"]]
+Headers = Mapping[str, Union[str, Sequence[str], None]]
+Params = MutableMapping[str, Any]
+
+
+class ComicPagination(TypedDict, total=False):
+    totalPages: int
+    panelsPerPage: int
+
+
+class ComicRole(TypedDict, total=False):
+    name: str
+    image: str
+    age: Union[int, str]
+    gender: str
+    clothing: str
+    description: str
+
+
+class ComicLocation(TypedDict, total=False):
+    name: str
+    image: str
+    description: str
+
+
+class ComicAttachment(TypedDict, total=False):
+    url: str
+    type: str
+
+
+class CreateComicParams(TypedDict, total=False):
+    prompt: str
+    size: str
+    model: str
+    preset: str
+    style: str
+    promptUrl: str
+    fixPanelNum: int
+    pagination: ComicPagination
+    images: List[str]
+    comicRoles: List[ComicRole]
+    comicLocations: List[ComicLocation]
+    attachments: List[ComicAttachment]
+    language: str
+    upscale: Union[bool, str]
+
+
+class ContinueComicParams(TypedDict, total=False):
+    prompt: str
+    fixPanelNum: int
+    pagination: ComicPagination
+    attachments: List[ComicAttachment]
+    images: List[str]
+
+
+class UpdateComicPanelParams(TypedDict, total=False):
+    page: int
+    pageIndex: int
+    page_index: int
+    panel: int
+    panelIndex: int
+    panel_index: int
+    panelPrompt: str
+    prompt: str
+    panel_prompt: str
+    images: List[str]
+    images_url: Union[str, List[str]]
+    caption: str
+
+
+class AnimationVideoOptions(TypedDict, total=False):
+    duration: int
+    resolution: str
+    aspect_ratio: str
+    image: str
+    last_frame_image: str
+    reference_images: List[str]
+    reference_videos: List[str]
+    reference_audios: List[str]
+    generate_audio: bool
+    seed: int
+
+
+class CreateAnimationParams(TypedDict, total=False):
+    prompt: str
+    videoOptions: AnimationVideoOptions
+
+
+class WaitOptions(TypedDict, total=False):
+    interval_ms: int
+    timeout_ms: int
+    done_statuses: Sequence[str]
+
+
+ComicArtworkResponse = Dict[str, Any]
+AnimationArtworkResponse = Dict[str, Any]
+ComicUsage = Dict[str, Any]
+ComicUploadResponse = Dict[str, Any]
+WebhookEvent = Dict[str, Any]
+
+
+__all__ = [
+    "AnimationArtworkResponse",
+    "AnimationVideoOptions",
+    "ComicArtworkResponse",
+    "ComicAttachment",
+    "ComicLocation",
+    "ComicPagination",
+    "ComicRole",
+    "ComicUploadResponse",
+    "ComicUsage",
+    "ContinueComicParams",
+    "CreateAnimationParams",
+    "CreateComicParams",
+    "Headers",
+    "Params",
+    "SUPPORTED_COMIC_SIZES",
+    "UpdateComicPanelParams",
+    "WaitOptions",
+    "WebhookEvent",
+]

llamagen/_webhooks.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Mapping, Optional, Sequence, Union
+
+from ._errors import LlamaGenWebhookSignatureError
+from ._types import Headers, WebhookEvent
+
+DEFAULT_TOLERANCE_SECONDS = 300
+Payload = Union[str, bytes, bytearray]
+
+
+def verify_webhook_signature(
+    payload: Payload,
+    headers: Headers,
+    secret: str,
+    *,
+    tolerance_seconds: int = DEFAULT_TOLERANCE_SECONDS,
+    now: Optional[int] = None,
+) -> bool:
+    try:
+        _assert_valid_signature(
+            payload,
+            headers,
+            secret,
+            tolerance_seconds=tolerance_seconds,
+            now=now,
+        )
+        return True
+    except LlamaGenWebhookSignatureError:
+        return False
+
+
+def construct_webhook_event(
+    payload: Payload,
+    headers: Headers,
+    secret: str,
+    *,
+    tolerance_seconds: int = DEFAULT_TOLERANCE_SECONDS,
+    now: Optional[int] = None,
+) -> WebhookEvent:
+    _assert_valid_signature(
+        payload,
+        headers,
+        secret,
+        tolerance_seconds=tolerance_seconds,
+        now=now,
+    )
+    body = _payload_bytes(payload).decode("utf-8")
+    event = json.loads(body)
+    request_id = _get_header(headers, "x-llama-webhook-request-id")
+    event_id = event.get("id") or _get_header(headers, "x-llama-webhook-id")
+    if event_id:
+        event["id"] = event_id
+    if request_id:
+        event["requestId"] = request_id
+    return event
+
+
+def _assert_valid_signature(
+    payload: Payload,
+    headers: Headers,
+    secret: str,
+    *,
+    tolerance_seconds: int,
+    now: Optional[int],
+) -> None:
+    if not secret:
+        raise LlamaGenWebhookSignatureError("Webhook secret is required.")
+
+    timestamp = _get_header(headers, "x-llama-webhook-timestamp")
+    signature = _get_header(headers, "x-llama-webhook-signature")
+    if not timestamp or not signature:
+        raise LlamaGenWebhookSignatureError("Missing LlamaGen webhook signature headers.")
+
+    try:
+        parsed_timestamp = int(timestamp)
+    except ValueError as error:
+        raise LlamaGenWebhookSignatureError("Invalid LlamaGen webhook timestamp.") from error
+
+    current_time = int(time.time()) if now is None else now
+    if tolerance_seconds > 0 and abs(current_time - parsed_timestamp) > tolerance_seconds:
+        raise LlamaGenWebhookSignatureError("LlamaGen webhook timestamp is outside tolerance.")
+
+    expected = _sign_payload(payload, secret, timestamp)
+    candidates = [
+        part.strip().removeprefix("v1=")
+        for part in signature.split(",")
+        if part.strip()
+    ]
+    if not any(hmac.compare_digest(candidate, expected) for candidate in candidates):
+        raise LlamaGenWebhookSignatureError("No matching LlamaGen webhook signature found.")
+
+
+def _sign_payload(payload: Payload, secret: str, timestamp: str) -> str:
+    body = _payload_bytes(payload)
+    signer = hmac.new(secret.encode("utf-8"), digestmod=hashlib.sha256)
+    signer.update(f"{timestamp}.".encode("utf-8"))
+    signer.update(body)
+    return signer.hexdigest()
+
+
+def _payload_bytes(payload: Payload) -> bytes:
+    if isinstance(payload, bytes):
+        return payload
+    if isinstance(payload, bytearray):
+        return bytes(payload)
+    return payload.encode("utf-8")
+
+
+def _get_header(headers: Headers, name: str) -> Optional[str]:
+    lower = name.lower()
+    getter = getattr(headers, "get", None)
+    if callable(getter):
+        direct = getter(name) or getter(lower)
+        if direct is not None:
+            return _header_value_to_string(direct)
+
+    if isinstance(headers, Mapping):
+        for key, value in headers.items():
+            if key.lower() == lower:
+                return _header_value_to_string(value)
+    return None
+
+
+def _header_value_to_string(value: Union[str, Sequence[str], None]) -> Optional[str]:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return value
+    return ",".join(value)
+
+
+verifyWebhookSignature = verify_webhook_signature
+constructWebhookEvent = construct_webhook_event

llamagen/py.typed

@@ -0,0 +1 @@
+

llamagen/resources/__init__.py

@@ -0,0 +1,4 @@
+from .animations import AnimationsResource
+from .comics import ComicsResource
+
+__all__ = ["AnimationsResource", "ComicsResource"]

llamagen/resources/animations.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import time
+from typing import Mapping, Optional, Sequence
+
+from .._errors import LlamaGenTimeoutError
+from .._http import HTTPClient
+from .._types import AnimationArtworkResponse
+
+DEFAULT_DONE_STATUSES = ("SUCCEEDED", "FAILED", "PROCESSED", "COMPLETED", "CANCELLED")
+
+
+class AnimationsResource:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def create(self, params: Mapping[str, object]) -> AnimationArtworkResponse:
+        _assert_non_empty(params.get("prompt") if params else None, "`prompt` is required and must be a non-empty string.")
+        return self._http.request("/artworks/generations", method="POST", json_body=params)
+
+    def get(self, artwork_id: str) -> AnimationArtworkResponse:
+        _assert_non_empty(artwork_id, "`artwork_id` is required and must be a non-empty string.")
+        return self._http.request(f"/artworks/generations/{artwork_id}", method="GET")
+
+    def wait_for_completion(
+        self,
+        artwork_id: str,
+        *,
+        interval_ms: int = 5000,
+        timeout_ms: int = 300000,
+        done_statuses: Optional[Sequence[str]] = None,
+    ) -> AnimationArtworkResponse:
+        done = {status.upper() for status in (done_statuses or DEFAULT_DONE_STATUSES)}
+        start = time.monotonic()
+
+        while True:
+            result = self.get(artwork_id)
+            if str(result.get("status", "")).upper() in done:
+                return result
+
+            if (time.monotonic() - start) * 1000 >= timeout_ms:
+                raise LlamaGenTimeoutError(
+                    f"Artwork {artwork_id} did not reach a completed status within {timeout_ms}ms"
+                )
+
+            time.sleep(interval_ms / 1000)
+
+    def create_and_wait(
+        self,
+        params: Mapping[str, object],
+        *,
+        interval_ms: int = 5000,
+        timeout_ms: int = 300000,
+        done_statuses: Optional[Sequence[str]] = None,
+    ) -> AnimationArtworkResponse:
+        created = self.create(params)
+        return self.wait_for_completion(
+            created["id"],
+            interval_ms=interval_ms,
+            timeout_ms=timeout_ms,
+            done_statuses=done_statuses,
+        )
+
+    waitForCompletion = wait_for_completion
+    createAndWait = create_and_wait
+
+
+def _assert_non_empty(value: object, message: str) -> None:
+    if not isinstance(value, str) or not value.strip():
+        raise TypeError(message)

llamagen/resources/comics.py

@@ -0,0 +1,308 @@
+from __future__ import annotations
+
+import concurrent.futures
+import mimetypes
+import os
+import time
+import uuid
+from pathlib import Path
+from typing import Any, BinaryIO, Dict, Iterable, List, Mapping, Optional, Sequence, Union
+from urllib.parse import urlencode
+
+from .._errors import LlamaGenTimeoutError
+from .._http import HTTPClient
+from .._types import ComicArtworkResponse, ComicUploadResponse, ComicUsage, SUPPORTED_COMIC_SIZES
+
+DEFAULT_SIZE = "1024x1024"
+DEFAULT_PRESET = "neutral"
+DEFAULT_DONE_STATUSES = ("SUCCEEDED", "FAILED", "PROCESSED", "COMPLETED", "CANCELLED")
+SUPPORTED_COMIC_SIZE_SET = set(SUPPORTED_COMIC_SIZES)
+FileInput = Union[str, os.PathLike[str], bytes, bytearray, BinaryIO]
+
+
+class ComicsResource:
+    def __init__(self, http: HTTPClient) -> None:
+        self._http = http
+
+    def create(self, params: Mapping[str, Any]) -> ComicArtworkResponse:
+        _assert_non_empty(params.get("prompt") if params else None, "`prompt` is required and must be a non-empty string.")
+        if params.get("size") is not None:
+            _assert_supported_size(str(params["size"]))
+        _assert_layout_options(params)
+
+        body: Dict[str, Any] = {"preset": DEFAULT_PRESET, "size": DEFAULT_SIZE}
+        body.update(params)
+        return self._http.request("/comics/generations", method="POST", json_body=body)
+
+    def get(self, artwork_id: str, *, page: Optional[int] = None, panel: Optional[int] = None) -> ComicArtworkResponse:
+        _assert_non_empty(artwork_id, "`artwork_id` is required and must be a non-empty string.")
+        query: Dict[str, int] = {}
+        if page is not None:
+            _assert_non_negative_integer(page, "`page` must be a non-negative integer.")
+            query["page"] = page
+        if panel is not None:
+            _assert_non_negative_integer(panel, "`panel` must be a non-negative integer.")
+            query["panel"] = panel
+
+        suffix = f"?{urlencode(query)}" if query else ""
+        return self._http.request(f"/comics/generations/{artwork_id}{suffix}", method="GET")
+
+    def continue_write(self, generation_id: str, params: Mapping[str, Any]) -> ComicArtworkResponse:
+        _assert_non_empty(generation_id, "`generation_id` is required and must be a non-empty string.")
+        _assert_non_empty(params.get("prompt") if params else None, "`prompt` is required and must be a non-empty string.")
+        _assert_layout_options(params)
+        body = dict(params)
+        body["action"] = "continueWrite"
+        return self._http.request(f"/comics/generations/{generation_id}", method="PATCH", json_body=body)
+
+    def update_panel(self, generation_id: str, params: Mapping[str, Any]) -> ComicArtworkResponse:
+        _assert_non_empty(generation_id, "`generation_id` is required and must be a non-empty string.")
+        _assert_panel_locator(params)
+        _assert_panel_update_payload(params)
+        body = dict(params)
+        body["action"] = "regeneratePanel"
+        return self._http.request(f"/comics/generations/{generation_id}", method="PATCH", json_body=body)
+
+    def usage(self) -> ComicUsage:
+        return self._http.request("/comics/usage", method="GET")
+
+    def upload(
+        self,
+        file: FileInput,
+        filename: Optional[str] = None,
+        *,
+        content_type: Optional[str] = None,
+    ) -> ComicUploadResponse:
+        payload, resolved_name = _read_file_input(file, filename)
+        multipart_body, multipart_content_type = _build_multipart(
+            field_name="file",
+            filename=resolved_name,
+            payload=payload,
+            content_type=content_type or mimetypes.guess_type(resolved_name)[0] or "application/octet-stream",
+        )
+        return self._http.request(
+            "/comics/upload",
+            method="POST",
+            body=multipart_body,
+            headers={"Content-Type": multipart_content_type},
+        )
+
+    def wait_for_completion(
+        self,
+        artwork_id: str,
+        *,
+        interval_ms: int = 5000,
+        timeout_ms: int = 180000,
+        done_statuses: Optional[Sequence[str]] = None,
+    ) -> ComicArtworkResponse:
+        done = {status.upper() for status in (done_statuses or DEFAULT_DONE_STATUSES)}
+        start = time.monotonic()
+
+        while True:
+            result = self.get(artwork_id)
+            if str(result.get("status", "")).upper() in done:
+                return result
+
+            if (time.monotonic() - start) * 1000 >= timeout_ms:
+                raise LlamaGenTimeoutError(
+                    f"Artwork {artwork_id} did not reach a completed status within {timeout_ms}ms"
+                )
+
+            time.sleep(interval_ms / 1000)
+
+    def create_and_wait(
+        self,
+        params: Mapping[str, Any],
+        *,
+        interval_ms: int = 5000,
+        timeout_ms: int = 180000,
+        done_statuses: Optional[Sequence[str]] = None,
+    ) -> ComicArtworkResponse:
+        created = self.create(params)
+        return self.wait_for_completion(
+            created["id"],
+            interval_ms=interval_ms,
+            timeout_ms=timeout_ms,
+            done_statuses=done_statuses,
+        )
+
+    def create_batch(
+        self,
+        params_list: Sequence[Mapping[str, Any]],
+        *,
+        concurrency: int = 3,
+        stop_on_error: bool = False,
+    ) -> List[Dict[str, Any]]:
+        if not params_list:
+            raise TypeError("`params_list` must be a non-empty sequence.")
+
+        def worker(params: Mapping[str, Any]) -> Dict[str, Any]:
+            try:
+                return {"input": params, "result": self.create(params)}
+            except Exception as error:
+                if stop_on_error:
+                    raise
+                return {"input": params, "error": error}
+
+        return _run_with_concurrency(params_list, max(1, concurrency), worker)
+
+    def wait_for_many(
+        self,
+        artwork_ids: Sequence[str],
+        *,
+        concurrency: int = 3,
+        interval_ms: int = 5000,
+        timeout_ms: int = 180000,
+        done_statuses: Optional[Sequence[str]] = None,
+    ) -> List[ComicArtworkResponse]:
+        if not artwork_ids:
+            raise TypeError("`artwork_ids` must be a non-empty sequence.")
+
+        def worker(artwork_id: str) -> ComicArtworkResponse:
+            return self.wait_for_completion(
+                artwork_id,
+                interval_ms=interval_ms,
+                timeout_ms=timeout_ms,
+                done_statuses=done_statuses,
+            )
+
+        return _run_with_concurrency(artwork_ids, max(1, concurrency), worker)
+
+    createComic = create
+    getComic = get
+    continueComic = continue_write
+    continueWrite = continue_write
+    regeneratePanel = update_panel
+    updateComicPanel = update_panel
+    updatePanel = update_panel
+    waitForCompletion = wait_for_completion
+    createAndWait = create_and_wait
+    createBatch = create_batch
+    waitForMany = wait_for_many
+
+
+def _run_with_concurrency(items: Sequence[Any], concurrency: int, worker: Any) -> List[Any]:
+    results: List[Any] = [None] * len(items)
+    with concurrent.futures.ThreadPoolExecutor(max_workers=min(concurrency, len(items))) as executor:
+        future_to_index = {executor.submit(worker, item): index for index, item in enumerate(items)}
+        for future in concurrent.futures.as_completed(future_to_index):
+            results[future_to_index[future]] = future.result()
+    return results
+
+
+def _read_file_input(file: FileInput, filename: Optional[str]) -> tuple[bytes, str]:
+    if isinstance(file, (str, os.PathLike)):
+        path = Path(file)
+        return path.read_bytes(), filename or path.name
+    if isinstance(file, (bytes, bytearray)):
+        return bytes(file), filename or "upload"
+    data = file.read()
+    if isinstance(data, str):
+        data = data.encode("utf-8")
+    resolved_name = filename or Path(getattr(file, "name", "upload")).name
+    return data, resolved_name
+
+
+def _build_multipart(*, field_name: str, filename: str, payload: bytes, content_type: str) -> tuple[bytes, str]:
+    boundary = f"----llamagen-{uuid.uuid4().hex}"
+    chunks = [
+        f"--{boundary}\r\n".encode("utf-8"),
+        (
+            f'Content-Disposition: form-data; name="{field_name}"; filename="{filename}"\r\n'
+            f"Content-Type: {content_type}\r\n\r\n"
+        ).encode("utf-8"),
+        payload,
+        b"\r\n",
+        f"--{boundary}--\r\n".encode("utf-8"),
+    ]
+    return b"".join(chunks), f"multipart/form-data; boundary={boundary}"
+
+
+def _assert_supported_size(value: str) -> None:
+    if value not in SUPPORTED_COMIC_SIZE_SET:
+        raise TypeError(f"`size` must be one of: {', '.join(SUPPORTED_COMIC_SIZES)}. Received: {value}")
+
+
+def _assert_layout_options(params: Mapping[str, Any]) -> None:
+    if params.get("fixPanelNum") is not None and params.get("pagination") is not None:
+        raise TypeError("`fixPanelNum` and `pagination` cannot be used together.")
+
+    if params.get("fixPanelNum") is not None:
+        _assert_integer_in_range(params["fixPanelNum"], 1, 20, "`fixPanelNum` must be an integer from 1 to 20.")
+
+    if params.get("pagination") is not None:
+        pagination = params["pagination"]
+        if not isinstance(pagination, Mapping):
+            raise TypeError("`pagination` must be a mapping.")
+        _assert_integer_in_range(
+            pagination.get("totalPages"),
+            1,
+            20,
+            "`pagination.totalPages` must be an integer from 1 to 20.",
+        )
+        _assert_integer_in_range(
+            pagination.get("panelsPerPage"),
+            1,
+            20,
+            "`pagination.panelsPerPage` must be an integer from 1 to 20.",
+        )
+
+
+def _assert_panel_locator(params: Mapping[str, Any]) -> None:
+    panel = _first_defined(params, "panel", "panelIndex", "panel_index")
+    if panel is None:
+        raise TypeError("`panel`, `panelIndex`, or `panel_index` is required.")
+    _assert_non_negative_integer(panel, "`panel` must be a non-negative integer.")
+
+    page = _first_defined(params, "page", "pageIndex", "page_index")
+    if page is not None:
+        _assert_non_negative_integer(page, "`page` must be a non-negative integer.")
+
+
+def _assert_panel_update_payload(params: Mapping[str, Any]) -> None:
+    has_payload = (
+        _has_non_empty_string(params.get("panelPrompt"))
+        or _has_non_empty_string(params.get("prompt"))
+        or _has_non_empty_string(params.get("panel_prompt"))
+        or _has_non_empty_string(params.get("caption"))
+        or _has_images(params.get("images"))
+        or _has_image_alias(params.get("images_url"))
+    )
+    if not has_payload:
+        raise TypeError("One of `panelPrompt`, `prompt`, `images`, or `caption` is required.")
+
+
+def _first_defined(params: Mapping[str, Any], *keys: str) -> Any:
+    for key in keys:
+        if params.get(key) is not None:
+            return params[key]
+    return None
+
+
+def _assert_non_empty(value: object, message: str) -> None:
+    if not isinstance(value, str) or not value.strip():
+        raise TypeError(message)
+
+
+def _assert_non_negative_integer(value: object, message: str) -> None:
+    if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+        raise TypeError(message)
+
+
+def _assert_integer_in_range(value: object, minimum: int, maximum: int, message: str) -> None:
+    if not isinstance(value, int) or isinstance(value, bool) or value < minimum or value > maximum:
+        raise TypeError(message)
+
+
+def _has_non_empty_string(value: object) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def _has_images(value: object) -> bool:
+    return isinstance(value, Iterable) and not isinstance(value, (str, bytes, bytearray, Mapping)) and any(
+        _has_non_empty_string(item) for item in value
+    )
+
+
+def _has_image_alias(value: object) -> bool:
+    return _has_non_empty_string(value) or _has_images(value)

llamagen_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,199 @@
+Metadata-Version: 2.4
+Name: llamagen-python
+Version: 0.1.0
+Summary: Official Python SDK for LlamaGen Comic API and Animation API
+Project-URL: Homepage, https://llamagen.ai/comic-api
+Project-URL: Documentation, https://llamagen.ai/comic-api/docs
+Project-URL: Source, https://github.com/LlamaGenAI/llamagen-python
+Project-URL: Issues, https://github.com/LlamaGenAI/llamagen-python/issues
+Author-email: "llamagen.ai" <support@llamagen.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,ai comic api,animation,comic,image-to-video,llamagen,sdk,text-to-video
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# llamagen-python
+
+Official Python SDK for LlamaGen's Comic API and Animation API.
+
+Homepage: <https://llamagen.ai/comic-api>
+
+## Install
+
+```bash
+pip install llamagen-python
+```
+
+## Quick Start
+
+```python
+import os
+from llamagen import LlamaGenClient
+
+llamagen = LlamaGenClient(api_key=os.environ["LLAMAGEN_API_KEY"])
+
+created = llamagen.comic.create({
+    "prompt": "A 4-panel comic about Leo finding a glowing key in a quiet library.",
+    "style": "manga",
+    "fixPanelNum": 4,
+})
+
+done = llamagen.comic.wait_for_completion(created["id"])
+print(done["status"], done.get("comics"))
+```
+
+## Client
+
+```python
+llamagen = LlamaGenClient(
+    api_key="YOUR_API_KEY",
+    base_url="https://api.llamagen.ai/v1",
+    timeout_ms=30000,
+    max_retries=2,
+    retry_delay_ms=500,
+)
+```
+
+The SDK uses Python's standard library HTTP stack and does not require runtime
+dependencies.
+
+## Comic API
+
+Use `llamagen.comic` to create comics, manga, webtoons, storyboards,
+consistent-character pages, and panel edits.
+
+```python
+generation = llamagen.comic.create({
+    "prompt": "The Little Prince meets the Fox in a luminous desert.",
+    "style": "storybook manga",
+    "size": "1024x1024",
+    "pagination": {"totalPages": 2, "panelsPerPage": 4},
+    "comicRoles": [
+        {
+            "name": "The Little Prince",
+            "image": "https://example.com/prince.png",
+            "clothing": "green coat and yellow scarf",
+        }
+    ],
+    "attachments": [{"type": "image", "url": "https://example.com/reference.png"}],
+    "language": "en",
+    "upscale": "2K",
+})
+```
+
+Comic methods:
+
+- `llamagen.comic.create(params)` calls `POST /v1/comics/generations`.
+- `llamagen.comic.get(id, page=None, panel=None)` calls `GET /v1/comics/generations/{id}`.
+- `llamagen.comic.continue_write(id, params)` extends an existing comic.
+- `llamagen.comic.update_panel(id, params)` regenerates one panel.
+- `llamagen.comic.usage()` calls `GET /v1/comics/usage`.
+- `llamagen.comic.upload(file, filename=None)` calls `POST /v1/comics/upload`.
+- `llamagen.comic.wait_for_completion(id, **options)` polls until a terminal status.
+- `llamagen.comic.create_and_wait(params, **options)` creates and polls.
+- `llamagen.comic.create_batch(params_list, concurrency=3)` submits many jobs.
+- `llamagen.comic.wait_for_many(ids, concurrency=3)` polls many jobs.
+
+JavaScript-style aliases are also available: `createComic`, `getComic`,
+`continueComic`, `regeneratePanel`, `updateComicPanel`, `waitForCompletion`,
+`createAndWait`, and `waitForMany`.
+
+## Animation API
+
+```python
+video = llamagen.animation.create({
+    "prompt": "A heroic fox detective walks through neon rain, cinematic camera move.",
+    "videoOptions": {
+        "duration": 5,
+        "resolution": "720p",
+        "aspect_ratio": "16:9",
+        "image": "https://example.com/first-frame.png",
+        "last_frame_image": "https://example.com/last-frame.png",
+        "reference_images": ["https://example.com/character.png"],
+    },
+})
+
+finished = llamagen.animation.wait_for_completion(
+    video["id"],
+    interval_ms=5000,
+    timeout_ms=300000,
+)
+```
+
+Animation methods:
+
+- `llamagen.animation.create(params)` calls `POST /v1/artworks/generations`.
+- `llamagen.animation.get(id)` calls `GET /v1/artworks/generations/{id}`.
+- `llamagen.animation.wait_for_completion(id, **options)` polls video status.
+- `llamagen.animation.create_and_wait(params, **options)` creates and polls.
+
+`llamagen.animations` is an alias for `llamagen.animation`.
+
+## Webhooks
+
+```python
+from llamagen import construct_webhook_event
+
+event = construct_webhook_event(
+    payload=raw_body,
+    headers=request_headers,
+    secret=os.environ["LLAMAGEN_WEBHOOK_SECRET"],
+)
+```
+
+The helper verifies `X-Llama-Webhook-Timestamp` and
+`X-Llama-Webhook-Signature` with HMAC SHA-256 and a default 5-minute tolerance.
+
+## Publishing
+
+Detailed release notes are in [`docs/RELEASE.md`](docs/RELEASE.md).
+
+1. Update `version` in `pyproject.toml`.
+2. Run tests and packaging checks:
+
+```bash
+python -m unittest discover -s tests
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+3. Publish to TestPyPI first:
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+4. Install from TestPyPI in a clean environment and smoke-test:
+
+```bash
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ llamagen-python
+```
+
+5. Publish to PyPI:
+
+```bash
+python -m twine upload dist/*
+```
+
+Use a PyPI API token through `TWINE_USERNAME=__token__` and
+`TWINE_PASSWORD=pypi-...` or configure a trusted publisher in PyPI for GitHub
+Actions.
+
+## Local Dev
+
+```bash
+python -m unittest discover -s tests
+python -m compileall src tests
+```

llamagen_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+llamagen/__init__.py,sha256=osyUmWp3zU978J28oTJyF2mkS9F_hczoDOhRLHYaghc,483
+llamagen/_client.py,sha256=V7t7dQF4aHWpIhxaXpa8KxTpfAmMbd7AGgWJzNLF2KM,1238
+llamagen/_errors.py,sha256=R00heV5tr1iLyA2ICjFYG0PA9uhEdqkjdHdiFgWHYGc,568
+llamagen/_http.py,sha256=Pq80dU768eW6KXINMFe3AC6cXnlA-fePrNbbDhkuK1o,4177
+llamagen/_types.py,sha256=o7dYuEA6w9m12vFFOWOafH_bPotAHiWvVhmCO0o8tTw,2909
+llamagen/_webhooks.py,sha256=wqW1ZDgJzkw5ntgSRcVf5Nu8FO9QpbcKH0YEuW9m_PA,4073
+llamagen/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+llamagen/resources/__init__.py,sha256=UEj0KBEmRdLJ7YIrGQU9EA5e0HMcVj93ilje_jBHnpY,130
+llamagen/resources/animations.py,sha256=7jAU4j3JRq37wsRyWzByvtL72o_Uc8H1pMeuAp7hr_k,2444
+llamagen/resources/comics.py,sha256=G5O7uDhotS693YhcZZNGU8W6M6rGEItGd2LCVtLdg7E,11871
+llamagen_python-0.1.0.dist-info/METADATA,sha256=fC2rahmB1SnjedNghaq4ren9Oct5b2cUk1E8swOUpUc,5875
+llamagen_python-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+llamagen_python-0.1.0.dist-info/licenses/LICENSE,sha256=sXRfe02p4AEZbNiSUd4r4V8peINjbArVYj921Lx7M-U,1068
+llamagen_python-0.1.0.dist-info/RECORD,,

llamagen_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

llamagen_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 llamagen.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.