Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

7.2 KB
Raw Blame
"""Request policy for the Pixal3D worker: resolution tiers and transient-fetch retry.

Free of torch, CUDA and the Pixal3D source tree so the decisions that shape
every generation import and unit test on any machine (see test_request_policy.py).
main.py imports every public name here; nothing in this file touches the GPU.

Two policies live here:

  1. Resolution resolution. Pixal3D only exposes two cascade pipelines (unlike
     TRELLIS.2's three-tier grid): 1024_cascade and 1536_cascade. A caller sends
     an optional `resolution` (1024 or 1536) and/or a named `tier`; this module
     turns that into the pipeline type, texture size and decimation target the
     worker runs with, and says how to step down when the GPU cannot hold the
     requested size.
  2. Transient-fetch retry. Caller-supplied image URLs are fetched over the
     public internet, where a single read timeout would otherwise fail a whole
     generation. `call_with_retry` re-runs the fetch for errors worth retrying
     and gives up at once on the ones that are not.
"""

from __future__ import annotations

from typing import Callable, Optional

import httpx

# Pixal3D's own inference scripts only ever build a "<resolution>_cascade"
# pipeline type for resolution in {1024, 1536} (inference.py / inference_mv.py:
# `f"{resolution if resolution > 0 else (1024 if low_vram else 1536)}_cascade"`).
# There is no bare 512 lane the way TRELLIS.2 has one.
RESOLUTIONS = (1024, 1536)
DEFAULT_RESOLUTION = 1536
LOW_VRAM_RESOLUTION = 1024

PIPELINE_TYPES = {
    1024: "1024_cascade",
    1536: "1536_cascade",
}

# What each resolution bakes. Texture size must stay a power of two (the bake
# builds a mip stack); the decimation target is the face budget handed to the
# mesh simplifier before UV unwrapping.
RESOLUTION_PRESETS = {
    1024: {"texture_size": 2048, "decimation_target": 700_000},
    1536: {"texture_size": 4096, "decimation_target": 1_000_000},
}

# The forge lanes already speak quality tiers; map them onto the resolutions so a
# tier request and a resolution request land on the same presets. Pixal3D has no
# "draft" lane of its own: the fastest tier still runs the smaller cascade.
TIER_RESOLUTION = {
    "draft": 1024,
    "standard": 1024,
    "high": 1536,
    "max": 1536,
}

TEXTURE_SIZE_MIN = 512
TEXTURE_SIZE_MAX = 4096
DECIMATION_MIN = 50_000
DECIMATION_MAX = 1_500_000


def normalize_tier(tier: Optional[str]) -> Optional[str]:
    """Lowercase and trim a caller's tier string, or None when none was sent."""
    if tier is None:
        return None
    key = str(tier).strip().lower()
    return key or None


def resolve_resolution(resolution: Optional[int], tier: Optional[str] = None) -> int:
    """The grid resolution to run at.

    An explicit `resolution` wins and snaps to the nearest supported size (a
    caller asking for 1200 gets 1024, a 2000 gets 1536). With none, the named
    tier decides, and with neither the platform default applies. An
    unparseable value falls back to the default rather than failing the job.
    """
    if resolution is not None:
        try:
            wanted = int(resolution)
        except (TypeError, ValueError):
            return DEFAULT_RESOLUTION
        return min(RESOLUTIONS, key=lambda r: (abs(r - wanted), r))
    return TIER_RESOLUTION.get(normalize_tier(tier) or "", DEFAULT_RESOLUTION)


def clamp_to_ceiling(resolution: int, ceiling: Optional[int]) -> int:
    """Cap a resolution at what this deployment's GPU class can serve."""
    if not ceiling:
        return resolution
    allowed = [r for r in RESOLUTIONS if r <= ceiling]
    return min(resolution, max(allowed)) if allowed else RESOLUTIONS[0]


def step_down(resolution: int) -> Optional[int]:
    """The next smaller resolution to retry at after an out-of-memory failure."""
    smaller = [r for r in RESOLUTIONS if r < resolution]
    return max(smaller) if smaller else None


def bake_params(
    resolution: int,
    texture_size: Optional[int] = None,
    decimation_target: Optional[int] = None,
) -> dict:
    """The clamped bake parameters for a resolution plus optional overrides.

    texture_size snaps DOWN to a power of two inside the envelope: the texture
    bake hard-fails on any other extent. Unparseable overrides fall back to the
    resolution's preset.
    """
    preset = RESOLUTION_PRESETS[resolution]

    def number(raw, fallback, lo, hi):
        if raw is None:
            return fallback
        try:
            value = int(raw)
        except (TypeError, ValueError):
            return fallback
        return max(lo, min(hi, value))

    tex = number(texture_size, preset["texture_size"], TEXTURE_SIZE_MIN, TEXTURE_SIZE_MAX)
    tex = 1 << (tex.bit_length() - 1)
    return {
        "texture_size": tex,
        "decimation_target": number(
            decimation_target, preset["decimation_target"], DECIMATION_MIN, DECIMATION_MAX
        ),
    }


# Total attempts (not extra retries) for one caller-supplied image URL, and the
# first backoff gap. Three attempts at 1s then 2s costs at most a few seconds of
# an already-asynchronous job, and covers the single-blip read timeouts that
# were failing whole generations from the public internet.
FETCH_ATTEMPTS = 3
FETCH_RETRY_BASE_SECONDS = 1.0

# Upstream status codes worth a second try. Everything else (404, 403, 400) is a
# statement about the URL itself and will fail identically on every attempt.
_RETRYABLE_STATUS = frozenset({408, 425, 429, 500, 502, 503, 504})


def retry_delays(
    attempts: int = FETCH_ATTEMPTS, base: float = FETCH_RETRY_BASE_SECONDS
) -> list[float]:
    """Exponential backoff gaps between attempts (one fewer than `attempts`)."""
    return [base * (2 ** i) for i in range(max(0, attempts - 1))]


def is_transient_fetch_error(exc: BaseException) -> bool:
    """True when re-fetching the same URL could plausibly succeed.

    Timeouts and connection-level failures are the blips this exists for. An
    HTTP error is transient only for the status codes above; a 404 is not going
    to become a 200 on the next attempt.
    """
    if isinstance(exc, httpx.HTTPStatusError):
        return exc.response.status_code in _RETRYABLE_STATUS
    return isinstance(
        exc, (httpx.TimeoutException, httpx.NetworkError, httpx.RemoteProtocolError)
    )


def call_with_retry(
    fn: Callable[[], object],
    *,
    attempts: int = FETCH_ATTEMPTS,
    should_retry: Callable[[BaseException], bool] = is_transient_fetch_error,
    sleep: Callable[[float], None],
    on_retry: Optional[Callable[[int, float, BaseException], None]] = None,
):
    """Call `fn`, retrying with exponential backoff while `should_retry` holds.

    Re-raises the last exception once the attempts are spent or the error is not
    retryable. `sleep` is injected so the policy stays testable without wall
    clock time; `on_retry` receives (attempt_number, delay, exception) for
    logging.
    """
    delays = retry_delays(attempts)
    last: BaseException
    for index in range(max(1, attempts)):
        try:
            return fn()
        except BaseException as exc:  # noqa: BLE001 - re-raised below after the budget
            last = exc
            if index >= len(delays) or not should_retry(exc):
                raise
            delay = delays[index]
            if on_retry:
                on_retry(index + 1, delay, exc)
            sleep(delay)
    raise last