orchestrate.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286
  1. """Pet generation orchestration — the base-draft → hatch flow.
  2. :func:`generate_base_drafts` makes a few cheap prompt-only look variants the user
  3. picks between; :func:`hatch_pet` grounds one row strip per state on the chosen
  4. base, slices frames, composes + validates the atlas, and writes it to the store.
  5. Splitting bounds cost (the ~8 row calls happen once, on the pet you keep) and
  6. gives each UI a natural preview/loading point.
  7. """
  8. from __future__ import annotations
  9. import contextlib
  10. import logging
  11. import time
  12. from collections import Counter
  13. from concurrent.futures import ThreadPoolExecutor, as_completed
  14. from dataclasses import dataclass
  15. from pathlib import Path
  16. from typing import Callable, Iterator
  17. from agent.pet.generate import atlas, imagegen, prompts
  18. from agent.pet.generate.imagegen import GenerationError, SpriteProvider
  19. logger = logging.getLogger(__name__)
  20. # (event, detail) — e.g. ("row", "idle"), ("compose", ""), ("save", "<slug>").
  21. ProgressFn = Callable[[str, str], None]
  22. # Fan-out so a hatch (~8 rows) doesn't blow the client's RPC timeout; capped for provider rate limits.
  23. _MAX_PARALLEL_GENERATIONS = 4
  24. # Row attempts: early ones demand clean per-pose gutters, the last is lenient so a stubborn row still yields.
  25. _ROW_GEN_ATTEMPTS = 3
  26. _MIN_FILLED_STATES = 6
  27. _REQUIRED_STATES = frozenset({"idle", "running-right", "waving"})
  28. # (substrings, friendly message), first match wins. Moderation is the big one:
  29. # image models refuse trademarked characters / real people as an opaque 400.
  30. _IMAGE_ERROR_HINTS: tuple[tuple[tuple[str, ...], str], ...] = (
  31. (("moderation_blocked", "safety system", "content policy", "content_policy"),
  32. "The image provider blocked this prompt — its safety filter rejects "
  33. "trademarked characters and real people. Try an original description."),
  34. (("api key", "unauthorized", "401", "auth"),
  35. "The image provider rejected the request — check your API key in Settings → Providers."),
  36. (("rate limit", "429"), "The image provider is rate-limiting — wait a moment and try again."),
  37. )
  38. @dataclass(frozen=True)
  39. class HatchResult:
  40. """Outcome of a successful :func:`hatch_pet`."""
  41. slug: str
  42. display_name: str
  43. spritesheet: Path
  44. states: list[str]
  45. validation: dict
  46. def _unlink_quietly(path: Path) -> None:
  47. with contextlib.suppress(OSError):
  48. path.unlink(missing_ok=True)
  49. def _harden_transparency(path: Path) -> Path:
  50. """Key out any solid backdrop the provider painted; save as an RGBA PNG.
  51. ``background=transparent`` is honored inconsistently, so every base draft gets
  52. the chroma-key pass. Best-effort: a decode failure leaves the original untouched.
  53. """
  54. try:
  55. keyed = atlas._clear_transparent_rgb(atlas.remove_background(atlas._load_rgba(path))) # no halo on the dark UI
  56. # PNGs (any case) are hardened in place: with_suffix(".png") on ".PNG" would
  57. # name the same file on case-insensitive filesystems and the unlink below
  58. # would delete the hardened output.
  59. out = path if path.suffix.lower() == ".png" else path.with_suffix(".png")
  60. keyed.save(out, format="PNG")
  61. if out != path:
  62. _unlink_quietly(path) # nothing prunes cache/generated/images, so drop it now
  63. return out
  64. except Exception as exc:
  65. logger.debug("base draft transparency hardening failed for %s: %s", path, exc)
  66. return path
  67. def _run_parallel(fn, items, *, cancelled, on_cancel_log: str) -> Iterator:
  68. """Fan *fn* over *items* in a pool, yielding results in completion order.
  69. ``as_completed`` runs on the caller's thread, so result callbacks inherit the
  70. request's bound transport (workers don't). Once *cancelled* trips, queued work
  71. is cancelled and in-flight results dropped.
  72. """
  73. workers = max(1, min(len(items), _MAX_PARALLEL_GENERATIONS))
  74. with ThreadPoolExecutor(max_workers=workers) as pool:
  75. futures = [pool.submit(fn, item) for item in items]
  76. for fut in as_completed(futures):
  77. if cancelled():
  78. logger.info(on_cancel_log)
  79. for pending in futures:
  80. pending.cancel()
  81. break
  82. yield fut.result()
  83. def generate_base_drafts(
  84. concept: str,
  85. *,
  86. n: int = 4,
  87. style: str = "auto",
  88. reference_images: list[Path] | None = None,
  89. provider: SpriteProvider | None = None,
  90. on_draft: Callable[[int, Path], None] | None = None,
  91. is_cancelled: Callable[[], bool] | None = None,
  92. ) -> list[Path]:
  93. """Generate *n* candidate base looks for *concept* concurrently; returns image paths.
  94. Drafts are hardened to transparent cutouts; *on_draft(index, path)* fires as each
  95. finishes so UIs can stream previews. *is_cancelled* is polled cooperatively.
  96. """
  97. # A user reference image grounds every draft, so it needs a reference-capable provider.
  98. refs = reference_images or None
  99. sprite = provider or imagegen.resolve_provider(require_references=bool(refs))
  100. cancelled = is_cancelled or (lambda: False)
  101. logger.info("pet generate: drafting %d base looks for %r (style=%s)", n, concept, style)
  102. def _one(index: int) -> tuple[int, Path | None, str | None]:
  103. if cancelled():
  104. return index, None, None
  105. t0 = time.monotonic()
  106. variation = prompts.BASE_VARIATIONS[index % len(prompts.BASE_VARIATIONS)] # distinct look per draft
  107. prompt = prompts.build_base_prompt(concept, style=style, variation=variation)
  108. try:
  109. out = imagegen.generate(prompt, n=1, reference_images=refs, provider=sprite, prefix="pet_base")
  110. except Exception as exc:
  111. logger.warning("pet generate: draft %d failed after %.1fs: %s", index, time.monotonic() - t0, exc)
  112. return index, None, str(exc)
  113. if not out:
  114. logger.warning("pet generate: draft %d produced no image", index)
  115. return index, None, "the image provider returned no image"
  116. logger.info("pet generate: draft %d ready in %.1fs", index, time.monotonic() - t0)
  117. return index, _harden_transparency(out[0]), None
  118. results: dict[int, Path] = {}
  119. errors: list[str] = []
  120. cancel_log = "pet generate: cancelled — dropping remaining drafts"
  121. for index, path, err in _run_parallel(_one, range(n), cancelled=cancelled, on_cancel_log=cancel_log):
  122. if path is None:
  123. errors += [err] if err else []
  124. continue
  125. results[index] = path
  126. if on_draft is not None:
  127. try:
  128. on_draft(index, path)
  129. except Exception as exc:
  130. logger.debug("on_draft callback failed: %s", exc)
  131. drafts = [results[i] for i in sorted(results)]
  132. if not drafts and not cancelled():
  133. # Surface *why*: the most common failure reason is the representative cause.
  134. if not errors:
  135. raise GenerationError("image generation produced no usable drafts")
  136. raise GenerationError(_humanize_image_error(Counter(errors).most_common(1)[0][0]))
  137. return drafts
  138. def _humanize_image_error(error: str) -> str:
  139. """Turn a raw provider error into a friendly, actionable sentence."""
  140. low = error.lower()
  141. hint = next((message for needles, message in _IMAGE_ERROR_HINTS if any(s in low for s in needles)), None)
  142. return hint or error.splitlines()[0].strip()[:200] # first line, sans provider envelope
  143. def _generate_row(spec: tuple[str, int, int], *, base: Path, label: str, style: str, slug: str, sprite, cancelled) -> tuple[str, list | None]:
  144. """Generate + slice one animation row, retrying up to ``_ROW_GEN_ATTEMPTS`` times.
  145. Self-healing: a roll whose poses touch (no gutters) slices badly, so
  146. ``components`` (raises on touching poses) drives regeneration and only the
  147. final attempt uses lenient ``auto`` slicing. Returns ``(state, None)`` when
  148. cancelled or every attempt failed.
  149. """
  150. state, _row, count = spec
  151. t0 = time.monotonic()
  152. last_exc: Exception | None = None
  153. for attempt in range(_ROW_GEN_ATTEMPTS):
  154. if cancelled():
  155. return state, None
  156. strips: list[Path] = []
  157. try:
  158. # Landscape: each frame gets real horizontal room and clean gutters.
  159. strips = imagegen.generate(
  160. prompts.build_row_prompt(state, count, label, style=style), n=1, reference_images=[base],
  161. provider=sprite, prefix=f"pet_row_{state}", aspect_ratio="landscape",
  162. )
  163. # fit=False keeps raw columns so normalize_cells registers the whole pet at once.
  164. method = "components" if attempt < _ROW_GEN_ATTEMPTS - 1 else "auto"
  165. frames = atlas.extract_strip_frames(strips[0], count, method=method, fit=False)
  166. logger.info("pet hatch %r: row %r ready in %.1fs (attempt %d)", slug, state, time.monotonic() - t0, attempt + 1)
  167. return state, frames
  168. except Exception as exc:
  169. last_exc = exc
  170. logger.warning("pet hatch %r: row %r attempt %d/%d failed: %s", slug, state, attempt + 1, _ROW_GEN_ATTEMPTS, exc)
  171. finally:
  172. # Strips are intermediates already decoded into memory; nothing
  173. # prunes cache/generated/images, so drop them now.
  174. for strip in strips:
  175. _unlink_quietly(Path(strip))
  176. logger.warning("pet hatch %r: row %r gave up after %.1fs: %s", slug, state, time.monotonic() - t0, last_exc)
  177. return state, None
  178. def hatch_pet(
  179. *,
  180. base_image: str | Path,
  181. slug: str,
  182. display_name: str = "",
  183. description: str = "",
  184. concept: str = "",
  185. style: str = "auto",
  186. on_progress: ProgressFn | None = None,
  187. provider: SpriteProvider | None = None,
  188. is_cancelled: Callable[[], bool] | None = None,
  189. ) -> HatchResult:
  190. """Turn an approved base image into a full, installed Hermes pet.
  191. Idle falls back to the base look so the pet always renders. Raises
  192. :class:`GenerationError` on failure. Once *is_cancelled* trips, aborts before
  193. composing/saving so a stopped hatch never writes a half-built pet.
  194. """
  195. base = Path(base_image)
  196. if not base.is_file():
  197. raise GenerationError(f"base image not found: {base}")
  198. sprite = provider or imagegen.resolve_provider(require_references=True)
  199. progress = on_progress or (lambda *_: None)
  200. cancelled = is_cancelled or (lambda: False)
  201. label = concept or display_name or slug
  202. frames_by_state: dict[str, list] = {}
  203. total_rows = len(atlas.ROW_SPECS)
  204. logger.info("pet hatch %r: generating %d animation rows", slug, total_rows)
  205. def _gen_row(spec: tuple[str, int, int]) -> tuple[str, list | None]:
  206. return _generate_row(spec, base=base, label=label, style=style, slug=slug, sprite=sprite, cancelled=cancelled)
  207. # running-left is mirrored from running-right (consistent, one fewer generation).
  208. generated_specs = [spec for spec in atlas.ROW_SPECS if spec[0] != "running-left"]
  209. cancel_log = f"pet hatch {slug!r}: cancelled — dropping remaining rows"
  210. done = 0
  211. for state, frames in _run_parallel(_gen_row, generated_specs, cancelled=cancelled, on_cancel_log=cancel_log):
  212. done += 1
  213. progress("row", f"{state}:{done}:{total_rows}")
  214. if frames:
  215. frames_by_state[state] = frames
  216. if cancelled():
  217. raise GenerationError("hatch cancelled")
  218. # Per-frame mirror preserves order/timing. A missing running-right is
  219. # rejected below: a pet without its canonical walk cycle is a failed hatch.
  220. right = frames_by_state.get("running-right")
  221. if right:
  222. done += 1
  223. progress("row", f"running-left:{done}:{total_rows}")
  224. frames_by_state["running-left"] = atlas.mirror_frames(right)
  225. logger.info("pet hatch %r: row 'running-left' mirrored from running-right", slug)
  226. else:
  227. logger.warning("pet hatch %r: no running-right to mirror; left walk left empty", slug)
  228. if not frames_by_state.get("idle"): # the renderer's resting fallback — guarantee it
  229. progress("row", "idle-fallback")
  230. frames_by_state["idle"] = [atlas.single_frame(base, fit=False)]
  231. progress("compose", "")
  232. logger.info("pet hatch %r: composing atlas from %d states", slug, len(frames_by_state))
  233. # One shared scale + baseline across states so the pet never slides or pulses.
  234. sheet = atlas.compose_atlas(atlas.normalize_cells(frames_by_state))
  235. validation = atlas.validate_atlas(sheet)
  236. if not validation["ok"]:
  237. raise GenerationError("; ".join(validation["errors"]) or "atlas validation failed")
  238. filled_states = set(validation["filled_states"])
  239. if missing_required := sorted(_REQUIRED_STATES - filled_states):
  240. raise GenerationError(f"missing required animation row(s): {', '.join(missing_required)}")
  241. if len(filled_states) < _MIN_FILLED_STATES:
  242. raise GenerationError(f"only {len(filled_states)}/{total_rows} animation rows were usable; regenerate")
  243. from agent.pet import store
  244. progress("save", slug)
  245. logger.info("pet hatch %r: saving pet", slug)
  246. pet = store.register_local_pet(sheet, slug=slug, display_name=display_name or slug, description=description)
  247. return HatchResult(pet.slug, pet.display_name, pet.spritesheet, validation["filled_states"], validation)