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.

30.9 KB
Raw Blame
"""
Stylize service — one-click geometric stylization filters for 3D meshes.

Turns any input mesh into a stylized variant using pure geometry processing
(trimesh + numpy + scipy). No model inference, no GPU — fast and cheap on CPU.

Filters (extensible — register more in STYLES):
  - voxel    : voxelize to a grid, rebuild the surface as solid cubes.
  - brick    : voxel grid + cylindrical studs on every top face (LEGO-like).
  - voronoi  : decimate to a coarse shell, thicken its edges into an open
               strut lattice with spherical nodes (Voronoi/wireframe shell).
  - lowpoly  : quadric-decimate, then hard flat-shade for a faceted look.

Source color/material is preserved where the style allows by sampling the
nearest source-surface face color per output element; otherwise a tasteful
default material is applied.

API contract:
  POST /process  {
    mesh: url,                       # https GLB/GLTF/OBJ/STL/PLY/OFF/DAE URL (required; FBX is refused)
    style: "voxel"|"brick"|"voronoi"|"lowpoly",   # default: "voxel"
    resolution?: int,                # style-specific density (see /styles)
    output_format?: "glb"|"obj"|"stl"|"ply",      # default: "glb"
  } → 202 { task_id, status }

  GET /tasks/:id → { task_id, status, result_url?, face_count?, style?, error? }

  GET /styles    → { styles: [ { key, name, description, resolution: {...} } ] }

  GET /health    → { ok }

Environment variables:
  API_KEY        — bearer secret (required)
  GCS_BUCKET     — output bucket (required)
  MAX_CONCURRENT — default 2
"""

from __future__ import annotations

import asyncio
import io
import logging
import os
import tempfile
import time
import uuid
from contextlib import asynccontextmanager
from pathlib import Path
from typing import Callable, Optional

from fastapi import FastAPI, HTTPException, Header, BackgroundTasks
from google.cloud import storage
from google.cloud.storage.retry import DEFAULT_RETRY
from pydantic import BaseModel, Field, field_validator

import oin
from gltf_meshopt import decode_if_meshopt
from oin_upload import make_result_sink
from worker_security import (
    UnsafeUrlError,
    fetch_remote_bytes,
    require_api_key,
    safe_error,
)

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s %(levelname)s %(name)s %(message)s",
)
log = logging.getLogger("stylize")

API_KEY = os.environ["API_KEY"]
GCS_BUCKET = os.environ["GCS_BUCKET"]
MAX_CONCURRENT = int(os.environ.get("MAX_CONCURRENT", "2"))

_bucket: Optional[storage.Bucket] = None
_sem: Optional[asyncio.Semaphore] = None
_tasks: dict[str, dict] = {}

# Instances are kept warm (min-instances=1), so an unbounded task dict would grow
# for the life of the instance. At ten seconds a job this is hours of history,
# far beyond any caller's poll window, and the results themselves live in GCS.
MAX_TRACKED_TASKS = 500

# Every input trimesh 4.x reads in this image (DAE through pycollada, which
# trimesh[easy] installs). FBX is deliberately absent: trimesh has no FBX reader
# and this image carries no converter, so an FBX is refused up front with the
# list below instead of failing inside the parser as an internal error.
SUPPORTED_INPUT_FORMATS = {".glb", ".gltf", ".obj", ".stl", ".ply", ".off", ".dae"}
SUPPORTED_INPUT_LABEL = "GLB, GLTF, OBJ, STL, PLY, OFF or DAE"
FBX_UNSUPPORTED_MESSAGE = (
    f"FBX input is not supported by stylize: supply {SUPPORTED_INPUT_LABEL}. "
    "To restyle an FBX, convert it to GLB first (the remesh worker's convert "
    "operation reads FBX)."
)
# Binary FBX opens with this fixed magic; ASCII FBX with a `; FBX` comment line.
FBX_BINARY_MAGIC = b"Kaydara FBX Binary  \x00"
FBX_ASCII_HEADER = b"; FBX"
SUPPORTED_OUTPUT_FORMATS = {"glb", "obj", "stl", "ply"}
MAX_MESH_BYTES = 128 * 1024 * 1024

# Hard safety caps so a hostile/huge input can never exhaust memory.
MAX_VOXELS = 60_000          # occupied surface cells rebuilt as cubes
MAX_LATTICE_EDGES = 6_000    # struts emitted for the voronoi shell
DEFAULT_COLOR = [196, 198, 214, 255]  # tasteful cool-neutral when source has none

# google-cloud-storage defaults uploads to a ConditionalRetryPolicy that only
# engages when the caller passes if_generation_match, so out of the box a
# transient TLS blip on the upload leg discards a job whose geometry work already
# succeeded (five such losses in the 30 days to 2026-08-11, every one an
# SSLError: UNEXPECTED_EOF_WHILE_READING). Each result blob is a fresh uuid, so
# re-sending it is idempotent: retry unconditionally instead.
UPLOAD_RETRY = DEFAULT_RETRY
UPLOAD_TIMEOUT_S = 120


# ── style catalog ────────────────────────────────────────────────────────────────
# A single source of truth for the available filters: their human-facing copy and
# the bounds + default of their one density knob. Adding a new filter is a matter
# of describing it here and registering its transform in STYLES below.

STYLE_CATALOG = {
    "voxel": {
        "name": "Voxel",
        "description": "Blocky cubes snapped to a 3D grid — a clean Minecraft-style rebuild of the surface.",
        "resolution": {"label": "Grid resolution", "default": 32, "min": 8, "max": 96},
    },
    "brick": {
        "name": "Brick",
        "description": "Voxel grid topped with studs on every up-facing block — a buildable, toy-brick look.",
        "resolution": {"label": "Brick resolution", "default": 24, "min": 8, "max": 64},
    },
    "voronoi": {
        "name": "Voronoi shell",
        "description": "An open lattice of struts and nodes traced over the surface — light, sculptural, 3D-print ready.",
        "resolution": {"label": "Cell density", "default": 48, "min": 12, "max": 120},
    },
    "lowpoly": {
        "name": "Low-poly",
        "description": "Decimated to crisp facets with hard flat shading — the classic stylized game-asset aesthetic.",
        "resolution": {"label": "Detail", "default": 40, "min": 8, "max": 120},
    },
}


def _remember_task(task: dict) -> None:
    """Track a task, evicting the oldest finished ones past MAX_TRACKED_TASKS.

    Eviction never touches a queued or running job: a caller polling live work
    must not get a 404 because someone else's job pushed theirs out.
    """
    _tasks[task["task_id"]] = task
    if len(_tasks) <= MAX_TRACKED_TASKS:
        return
    for task_id, tracked in list(_tasks.items()):
        if len(_tasks) <= MAX_TRACKED_TASKS:
            break
        if tracked.get("status") in ("done", "failed"):
            del _tasks[task_id]


def _clamp_resolution(style: str, resolution: Optional[int]) -> int:
    spec = STYLE_CATALOG[style]["resolution"]
    if resolution is None:
        return spec["default"]
    return max(spec["min"], min(spec["max"], int(resolution)))


@asynccontextmanager
async def lifespan(app: FastAPI):
    global _bucket, _sem
    # A local OIN run (OIN_RESULT_DIR set) stores artifacts on disk instead of
    # GCS, so the bucket client is skipped: no credentials needed on a laptop.
    if not os.environ.get("OIN_RESULT_DIR"):
        _bucket = storage.Client().bucket(GCS_BUCKET)
    else:
        log.info("OIN_RESULT_DIR set: skipping GCS client (bucket %s unused)", GCS_BUCKET)
    _sem = asyncio.Semaphore(MAX_CONCURRENT)
    import trimesh
    log.info("stylize service ready — trimesh %s, styles=%s", trimesh.__version__, ",".join(STYLE_CATALOG))
    yield


app = FastAPI(title="stylize-service", lifespan=lifespan)


def _require_api_key(authorization: Optional[str]) -> None:
    """Reject a missing or wrong bearer token with 401.

    The header is declared optional on the routes so this runs on a missing one
    too: with `Header(...)` FastAPI answers a credential-less caller with a 422
    validation dump instead of the 401 the contract promises.
    """
    try:
        require_api_key(authorization, API_KEY)
    except PermissionError as exc:
        raise HTTPException(status_code=401, detail=str(exc)) from exc


# ── mesh IO ───────────────────────────────────────────────────────────────────────


class InputFormatError(ValueError):
    """The caller's file is in a format this worker cannot read.

    Its message names the formats that do work and is returned on the task
    verbatim (error_kind "input"), unlike internal failures, which stay opaque."""


def _url_suffix(url: str) -> str:
    return Path(url.split("?")[0].split("#")[0]).suffix.lower()


def _is_fbx(data: bytes) -> bool:
    if data.startswith(FBX_BINARY_MAGIC):
        return True
    return data[:64].lstrip(b"\xef\xbb\xbf").lstrip().startswith(FBX_ASCII_HEADER)


def _fetch_mesh(url: str) -> tuple[bytes, str]:
    try:
        data = fetch_remote_bytes(url, timeout=60, max_bytes=MAX_MESH_BYTES)
    except UnsafeUrlError as exc:
        raise ValueError(f"refused to fetch mesh: {exc}") from exc
    # The bytes decide, not just the URL: a signed or extensionless URL would
    # otherwise fall back to the glTF parser and fail there with an error that
    # says nothing about FBX.
    if _url_suffix(url) == ".fbx" or _is_fbx(data):
        raise InputFormatError(FBX_UNSUPPORTED_MESSAGE)
    suffix = _url_suffix(url)
    if suffix not in SUPPORTED_INPUT_FORMATS:
        suffix = ".glb"
    return data, suffix


def _load_single_mesh(data: bytes, suffix: str):
    """Load to a single concatenated Trimesh, keeping visual/color where present."""
    import trimesh

    # A meshopt-compressed asset is transcoded first: trimesh cannot read one,
    # and it is the format most three.ws avatars ship as.
    data, suffix = decode_if_meshopt(data, suffix)

    loaded = trimesh.load(io.BytesIO(data), file_type=suffix.lstrip("."), force="mesh", process=False)
    if isinstance(loaded, trimesh.Scene):
        meshes = [g for g in loaded.geometry.values() if isinstance(g, trimesh.Trimesh)]
        if not meshes:
            raise ValueError("no renderable geometry found in scene")
        loaded = trimesh.util.concatenate(meshes)
    if not hasattr(loaded, "faces") or len(loaded.faces) == 0:
        raise ValueError("input has no triangular faces to stylize")
    return loaded


# ── color preservation ─────────────────────────────────────────────────────────────


def _face_colors_of(visual, mesh):
    """Per-face RGBA from a ColorVisuals, whichever way it carries its colors.

    `TextureVisuals.to_color()` hands back a ColorVisuals with no mesh attached,
    so reading `.face_colors` on it raises and, until 2026-08-11, every textured
    input therefore fell through to the flat default: the common case in the
    forge, silently stripped of its colors. Read vertex colors directly and fold
    them to faces here instead. Returns None when the visual carries neither.
    """
    import numpy as np
    from trimesh.visual.color import vertex_to_face_color

    kind = getattr(visual, "kind", None)
    if kind == "face":
        fc = visual.face_colors
        if fc is not None and len(fc) == len(mesh.faces):
            return np.asarray(fc, dtype=np.uint8).reshape(-1, 4)
    if kind == "vertex":
        vc = np.asarray(visual.vertex_colors)
        if len(vc) == len(mesh.vertices):
            folded = vertex_to_face_color(vc, mesh.faces)
            return np.asarray(folded, dtype=np.uint8).reshape(-1, 4)
    return None


def _source_color_sampler(mesh) -> Callable:
    """Return color_at(points)->(N,4) uint8 sampling the nearest source face color.

    Resolves a usable per-face color from whatever the source carries — vertex
    colors, a texture (converted via to_color), or a material base color —
    falling back to a tasteful default when the mesh is untextured. The returned
    closure is what each filter calls to tint its output elements.
    """
    import numpy as np
    from scipy.spatial import cKDTree

    n_faces = len(mesh.faces)
    face_colors = None
    try:
        visual = getattr(mesh, "visual", None)
        if visual is not None:
            if getattr(visual, "kind", None) == "texture" or visual.__class__.__name__ == "TextureVisuals":
                visual = visual.to_color()
            # `defined` is False when trimesh is only synthesizing its stock gray
            # for a mesh that carries no color of its own. Reading colors
            # regardless would hand every untextured input that flat 102-gray and
            # leave DEFAULT_COLOR unreachable.
            if getattr(visual, "defined", True):
                face_colors = _face_colors_of(visual, mesh)
    except Exception as exc:  # noqa: BLE001 — any visual quirk falls back to default
        log.info("color extraction fell back to default: %s", exc)

    if face_colors is None:
        face_colors = np.tile(np.array(DEFAULT_COLOR, dtype=np.uint8), (n_faces, 1))

    centroids = mesh.triangles_center
    tree = cKDTree(centroids)

    def color_at(points):
        pts = np.asarray(points, dtype=np.float64).reshape(-1, 3)
        _, idx = tree.query(pts)
        return face_colors[idx]

    return color_at


# ── filters ─────────────────────────────────────────────────────────────────────


def _require_extent(mesh) -> float:
    """Largest bounding-box dimension, refusing a mesh that has no size at all.

    Every filter derives its feature size (voxel pitch, strut radius) from this,
    and at zero they all degrade into invisible or empty geometry. Failing the
    task with a readable reason beats uploading a blob the caller cannot see.
    """
    extent = float(mesh.extents.max())
    if extent <= 0:
        raise ValueError("mesh has zero extent")
    return extent


def _stylize_voxel(mesh, resolution: int):
    """Voxelize the surface and rebuild it as a mesh of solid, source-colored cubes."""
    import numpy as np

    extent = _require_extent(mesh)
    pitch = extent / max(1, resolution)

    voxel = mesh.voxelized(pitch=pitch)
    n = len(voxel.points)
    if n == 0:
        raise ValueError("voxelization produced no cells — try a higher resolution")
    # Back off resolution if the grid is dangerously dense.
    while n > MAX_VOXELS and pitch < extent:
        pitch *= 1.3
        voxel = mesh.voxelized(pitch=pitch)
        n = len(voxel.points)

    color_at = _source_color_sampler(mesh)
    colors = color_at(voxel.points)  # (N,4), one per occupied cell
    boxes = voxel.as_boxes()
    # as_boxes emits exactly 12 faces per cell in `points` order; tint each cube
    # by repeating its source color across its faces. (Passing colors= directly
    # is silently dropped by this trimesh version.)
    per_face = len(boxes.faces) // len(voxel.points)
    boxes.visual.face_colors = np.repeat(colors, per_face, axis=0)
    return boxes


def _stylize_brick(mesh, resolution: int):
    """Voxel grid plus a stud on each column's top voxel — a toy-brick rebuild."""
    import numpy as np
    import trimesh

    extent = _require_extent(mesh)
    pitch = extent / max(1, resolution)

    voxel = mesh.voxelized(pitch=pitch)
    n = len(voxel.points)
    if n == 0:
        raise ValueError("voxelization produced no cells — try a higher resolution")
    while n > MAX_VOXELS and pitch < extent:
        pitch *= 1.3
        voxel = mesh.voxelized(pitch=pitch)
        n = len(voxel.points)

    color_at = _source_color_sampler(mesh)
    centers = np.asarray(voxel.points, dtype=np.float64)
    colors = color_at(centers)

    base = voxel.as_boxes()
    per_face = len(base.faces) // len(centers)
    base.visual.face_colors = np.repeat(colors, per_face, axis=0)

    # Find the top voxel of each (x,y) column (grid up-axis = Z) and cap it with a
    # cylindrical stud sitting on the block's top face.
    grid = np.asarray(voxel.sparse_indices, dtype=np.int64)  # (N,3) integer cells
    column_top: dict[tuple, int] = {}
    for i in range(len(grid)):
        key = (int(grid[i, 0]), int(grid[i, 1]))
        if key not in column_top or grid[i, 2] > grid[column_top[key], 2]:
            column_top[key] = i

    stud_r = pitch * 0.30
    stud_h = pitch * 0.42
    studs = []
    for idx in column_top.values():
        c = centers[idx]
        cyl = trimesh.creation.cylinder(radius=stud_r, height=stud_h, sections=12)
        cyl.apply_translation([c[0], c[1], c[2] + pitch * 0.5 + stud_h * 0.5])
        cyl.visual.face_colors = np.tile(colors[idx], (len(cyl.faces), 1))
        studs.append(cyl)

    if studs:
        return trimesh.util.concatenate([base, *studs])
    return base


def _decimate(mesh, target_faces: int):
    """Quadric decimation via open3d, with a trimesh fallback. Used by lattice/lowpoly."""
    import numpy as np
    import trimesh

    if len(mesh.faces) <= target_faces:
        return mesh
    try:
        import open3d as o3d

        om = o3d.geometry.TriangleMesh()
        om.vertices = o3d.utility.Vector3dVector(mesh.vertices.astype(np.float64))
        om.triangles = o3d.utility.Vector3iVector(mesh.faces.astype(np.int32))
        simplified = om.simplify_quadric_decimation(int(target_faces))
        return trimesh.Trimesh(
            vertices=np.asarray(simplified.vertices),
            faces=np.asarray(simplified.triangles),
            process=False,
        )
    except Exception as exc:  # noqa: BLE001
        log.info("open3d decimation fell back to trimesh: %s", exc)
        try:
            return mesh.simplify_quadric_decimation(face_count=int(target_faces))
        except Exception:
            return mesh


def _stylize_voronoi(mesh, resolution: int):
    """Thicken a decimated shell's edges into an open strut-and-node lattice."""
    import numpy as np
    import trimesh

    _require_extent(mesh)
    target_faces = int(np.clip(resolution * 40, 200, 4000))
    shell = _decimate(mesh, target_faces)

    edges = shell.edges_unique  # (E,2) vertex index pairs
    verts = np.asarray(shell.vertices, dtype=np.float64)
    if len(edges) == 0:
        raise ValueError("mesh has no edges to latticize")

    # Cap strut count by decimating further if needed.
    if len(edges) > MAX_LATTICE_EDGES:
        ratio = MAX_LATTICE_EDGES / len(edges)
        shell = _decimate(shell, max(60, int(len(shell.faces) * ratio)))
        edges = shell.edges_unique
        verts = np.asarray(shell.vertices, dtype=np.float64)
    # Hard backstop: if decimation was unavailable and the edge set is still over
    # budget, keep a deterministic uniform stride so output stays bounded.
    if len(edges) > MAX_LATTICE_EDGES:
        stride = int(np.ceil(len(edges) / MAX_LATTICE_EDGES))
        edges = edges[::stride]

    diag = float(np.linalg.norm(mesh.extents))
    strut_r = max(diag * 0.004, diag / max(resolution, 1) * 0.18)

    color_at = _source_color_sampler(mesh)
    mids = (verts[edges[:, 0]] + verts[edges[:, 1]]) * 0.5
    edge_colors = color_at(mids)

    parts = []
    for i, (a, b) in enumerate(edges):
        seg = verts[[a, b]]
        length = float(np.linalg.norm(seg[1] - seg[0]))
        if length <= 1e-9:
            continue
        strut = trimesh.creation.cylinder(radius=strut_r, segment=seg, sections=6)
        strut.visual.face_colors = np.tile(edge_colors[i], (len(strut.faces), 1))
        parts.append(strut)

    # Spherical nodes weld the struts at each used vertex.
    used = np.unique(edges)
    node_colors = color_at(verts[used])
    for j, vi in enumerate(used):
        node = trimesh.creation.icosphere(subdivisions=0, radius=strut_r * 1.45)
        node.apply_translation(verts[vi])
        node.visual.face_colors = np.tile(node_colors[j], (len(node.faces), 1))
        parts.append(node)

    if not parts:
        raise ValueError("lattice generation produced no geometry")
    return trimesh.util.concatenate(parts)


def _stylize_lowpoly(mesh, resolution: int):
    """Decimate hard, then split every face onto its own vertices for flat shading."""
    import numpy as np
    import trimesh

    _require_extent(mesh)
    target_faces = int(np.clip(resolution * 60, 80, 20_000))
    deci = _decimate(mesh, target_faces)

    # Sample the SOURCE, not the decimated shell: open3d's quadric decimation
    # (the path taken whenever open3d imports, which is every deployed image)
    # returns bare vertices and triangles with no visuals at all, so sampling
    # `deci` painted every facet the fallback color and threw the model's own
    # colors away. Voronoi already samples the source for the same reason.
    color_at = _source_color_sampler(mesh)
    face_colors = color_at(deci.triangles_center)  # (F,4)

    # Unweld: each triangle gets three unique vertices so normals are per-face,
    # producing crisp facets instead of smooth Gouraud shading.
    tri_verts = deci.vertices[deci.faces].reshape(-1, 3)
    new_faces = np.arange(len(tri_verts)).reshape(-1, 3)
    vertex_colors = np.repeat(face_colors, 3, axis=0)

    faceted = trimesh.Trimesh(vertices=tri_verts, faces=new_faces, process=False)
    faceted.visual.vertex_colors = vertex_colors
    return faceted


STYLES: dict[str, Callable] = {
    "voxel": _stylize_voxel,
    "brick": _stylize_brick,
    "voronoi": _stylize_voronoi,
    "lowpoly": _stylize_lowpoly,
}


# ── export + pipeline ───────────────────────────────────────────────────────────────


def _export_mesh(mesh, output_format: str) -> tuple[bytes, str]:
    import trimesh

    fmt = output_format.lower()
    with tempfile.TemporaryDirectory() as tmpdir:
        out_path = Path(tmpdir) / f"output.{fmt}"
        if fmt == "glb":
            scene = trimesh.scene.scene.Scene(geometry={"stylized": mesh})
            scene.export(str(out_path))
        else:
            mesh.export(str(out_path))
        data = out_path.read_bytes()
    return data, ("model/gltf-binary" if fmt == "glb" else "application/octet-stream")


def _upload_result(blob, data: bytes, content_type: str) -> None:
    """Upload a finished mesh, retrying the transient transport failures.

    Split out from the request path so the retry policy is directly testable:
    see test_stylize.py, which pins that an SSLError is retryable under it.
    """
    blob.upload_from_string(
        data, content_type=content_type, retry=UPLOAD_RETRY, timeout=UPLOAD_TIMEOUT_S
    )


def _run_processing(mesh_url: str, style: str, resolution: int, output_format: str):
    data, suffix = _fetch_mesh(mesh_url)
    mesh = _load_single_mesh(data, suffix)

    transform = STYLES[style]
    styled = transform(mesh, resolution)

    out_bytes, content_type = _export_mesh(styled, output_format)
    face_count = int(len(styled.faces)) if hasattr(styled, "faces") else 0
    return out_bytes, face_count, content_type


async def _process(task_id: str, mesh_url: str, style: str, resolution: int, output_format: str) -> None:
    async with _sem:
        _tasks[task_id]["status"] = "running"
        loop = asyncio.get_event_loop()
        t0 = time.time()
        try:
            out_bytes, face_count, content_type = await loop.run_in_executor(
                None, _run_processing, mesh_url, style, resolution, output_format
            )

            blob_name = f"stylize/{task_id}.{output_format}"
            blob = _bucket.blob(blob_name)
            await loop.run_in_executor(
                None, lambda: _upload_result(blob, out_bytes, content_type)
            )
            result_url = f"https://storage.googleapis.com/{GCS_BUCKET}/{blob_name}"

            elapsed = time.time() - t0
            _tasks[task_id].update({
                "status": "done",
                "result_url": result_url,
                "face_count": face_count,
                "style": style,
                "resolution": resolution,
                "output_format": output_format,
                "bytes": len(out_bytes),
                "elapsed_ms": int(elapsed * 1000),
            })
            log.info(
                "[%s] %s done in %.2fs — %d faces, %d bytes → %s",
                task_id, style, elapsed, face_count, len(out_bytes), result_url,
            )
        except InputFormatError as exc:
            log.info("[%s] rejected input: %s", task_id, exc)
            _tasks[task_id].update({
                "status": "failed",
                "error": str(exc),
                # Same taxonomy the avatar workers report and api/_providers/gcp.js
                # relays: `input` means `error` is caller-facing copy.
                "error_kind": "input",
                "elapsed_ms": int((time.time() - t0) * 1000),
            })
        except Exception as exc:  # noqa: BLE001
            _tasks[task_id].update({
                "status": "failed",
                "error": safe_error(exc, context=f"[{task_id}] stylize {style}"),
                "error_kind": "internal",
                "elapsed_ms": int((time.time() - t0) * 1000),
            })


class ProcessRequest(BaseModel):
    mesh: str = Field(..., description="https URL to input mesh (GLB/GLTF/OBJ/STL/PLY/OFF/DAE)")
    style: str = Field(default="voxel", description="|".join(STYLE_CATALOG))
    resolution: Optional[int] = Field(default=None, description="Style-specific density; see /styles")
    output_format: str = Field(default="glb")

    @field_validator("mesh")
    @classmethod
    def validate_mesh(cls, v: str) -> str:
        # Refuse an FBX at the door with a 422 that names the supported formats,
        # rather than accepting a job that can only fail. An FBX behind an
        # extensionless URL is caught by the byte sniff in _fetch_mesh.
        if _url_suffix(v) == ".fbx":
            raise ValueError(FBX_UNSUPPORTED_MESSAGE)
        return v

    @field_validator("style")
    @classmethod
    def validate_style(cls, v: str) -> str:
        v = v.lower().strip()
        if v not in STYLE_CATALOG:
            raise ValueError(f"unknown style: {v}. Choose from {sorted(STYLE_CATALOG)}")
        return v

    @field_validator("output_format")
    @classmethod
    def validate_format(cls, v: str) -> str:
        v = v.lower().lstrip(".")
        if v not in SUPPORTED_OUTPUT_FORMATS:
            raise ValueError(f"unsupported output format: {v}. Choose from {sorted(SUPPORTED_OUTPUT_FORMATS)}")
        return v


@app.post("/process", status_code=202)
async def process_mesh(
    body: ProcessRequest,
    background_tasks: BackgroundTasks,
    authorization: Optional[str] = Header(default=None),
) -> dict:
    _require_api_key(authorization)
    resolution = _clamp_resolution(body.style, body.resolution)
    task_id = str(uuid.uuid4())
    _remember_task({
        "task_id": task_id,
        "status": "queued",
        "style": body.style,
        "resolution": resolution,
        "output_format": body.output_format,
    })
    background_tasks.add_task(
        _process, task_id, body.mesh, body.style, resolution, body.output_format
    )
    return {"task_id": task_id, "status": "queued", "style": body.style, "resolution": resolution}


@app.get("/tasks/{task_id}")
async def get_task(task_id: str, authorization: Optional[str] = Header(default=None)) -> dict:
    _require_api_key(authorization)
    task = _tasks.get(task_id)
    if task is None:
        raise HTTPException(status_code=404, detail="task not found")
    return task


@app.get("/styles")
async def list_styles() -> dict:
    """Public filter catalog — drives the UI gallery and documents the density knob."""
    return {
        "styles": [
            {"key": key, "name": spec["name"], "description": spec["description"], "resolution": spec["resolution"]}
            for key, spec in STYLE_CATALOG.items()
        ]
    }


@app.get("/health")
async def health() -> dict:
    return {"ok": True, "service": "stylize", "styles": list(STYLE_CATALOG)}


# ── Open Inference Protocol (OIN) ─────────────────────────────────────────────
# specs/OPEN_INFERENCE_PROTOCOL.md. Behind a flag: with OIN_ENABLED unset the
# worker is byte-for-byte its pre-OIN self; with it set the worker refuses to
# boot without OIN_SIGNING_KEY so a node can never advertise a key it cannot
# sign with.

OIN_ENABLED = os.environ.get("OIN_ENABLED") == "true"


def _oin_run_job(envelope: dict, report, sink) -> None:
    """Run one OIN job through the same stylization pipeline as /process.

    The envelope's `input.data` is the mesh URL, `input.model` the style, and
    `params` the resolution/format knobs. The sink uploads the artifact and the
    OIN layer signs against the exact bytes it stored.
    """
    mesh_url = envelope["input"].get("data", "")
    style = str(envelope["input"].get("model", "voxel")).lower().strip()
    params = envelope.get("params") or {}
    if style not in STYLES:
        report.failed(code="bad_input", message=f"unknown style: {style}. Choose from {sorted(STYLE_CATALOG)}")
        return
    output_format = str(params.get("output_format", "glb")).lower().lstrip(".")
    if output_format not in SUPPORTED_OUTPUT_FORMATS:
        report.failed(code="bad_input", message=f"unsupported output format: {output_format}")
        return
    resolution = _clamp_resolution(style, params.get("resolution"))
    try:
        out_bytes, face_count, content_type = _run_processing(mesh_url, style, resolution, output_format)
    except ValueError as exc:
        report.failed(code="bad_input", message=str(exc))
        return
    except Exception as exc:  # noqa: BLE001
        report.failed(code="node_error", message=safe_error(exc, context=f"oin stylize {style}"))
        return
    result = sink.put(envelope["job_id"], out_bytes, content_type)
    log.info(
        "oin job %s done: %s, %d faces, %d bytes",
        envelope["job_id"], style, face_count, len(out_bytes),
    )
    report.done(url=result.url, data=result.data)


if OIN_ENABLED:
    _oin_key = os.environ.get("OIN_SIGNING_KEY")
    if not _oin_key:
        raise RuntimeError("OIN_ENABLED=true requires OIN_SIGNING_KEY (base64 Ed25519 secret)")

    # The sink is bound lazily on first use: the GCS bucket client exists only
    # after the lifespan opens, and mount_oin registers the routes immediately
    # (before startup) so the advertisement is servable from the first request.
    # Local runs set OIN_RESULT_DIR + OIN_RESULT_BASE_URL and skip GCS entirely.
    def _get_oin_sink():
        return make_result_sink(_bucket)

    def _run_oin_job(envelope: dict, report) -> None:
        _oin_run_job(envelope, report, _get_oin_sink())

    oin.mount_oin(
        app,
        node_id=os.environ.get("OIN_NODE_ID", "three-ws-stylize"),
        signing_key_b64=_oin_key,
        capabilities=[
            {
                "key": "mesh.stylize",
                "version": "0.1",
                "models": sorted(STYLE_CATALOG),
                "max_input_bytes": MAX_MESH_BYTES,
                "pricing": {"currency": "USDC", "unit": "job", "amount": "0"},
                "sla": {"typical_seconds": 10},
            }
        ],
        auth="bearer",
        require_auth=_require_api_key,
        run_job=_run_oin_job,
    )