| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286 |
- """Pet generation orchestration — the base-draft → hatch flow.
- :func:`generate_base_drafts` makes a few cheap prompt-only look variants the user
- picks between; :func:`hatch_pet` grounds one row strip per state on the chosen
- base, slices frames, composes + validates the atlas, and writes it to the store.
- Splitting bounds cost (the ~8 row calls happen once, on the pet you keep) and
- gives each UI a natural preview/loading point.
- """
- from __future__ import annotations
- import contextlib
- import logging
- import time
- from collections import Counter
- from concurrent.futures import ThreadPoolExecutor, as_completed
- from dataclasses import dataclass
- from pathlib import Path
- from typing import Callable, Iterator
- from agent.pet.generate import atlas, imagegen, prompts
- from agent.pet.generate.imagegen import GenerationError, SpriteProvider
- logger = logging.getLogger(__name__)
- # (event, detail) — e.g. ("row", "idle"), ("compose", ""), ("save", "<slug>").
- ProgressFn = Callable[[str, str], None]
- # Fan-out so a hatch (~8 rows) doesn't blow the client's RPC timeout; capped for provider rate limits.
- _MAX_PARALLEL_GENERATIONS = 4
- # Row attempts: early ones demand clean per-pose gutters, the last is lenient so a stubborn row still yields.
- _ROW_GEN_ATTEMPTS = 3
- _MIN_FILLED_STATES = 6
- _REQUIRED_STATES = frozenset({"idle", "running-right", "waving"})
- # (substrings, friendly message), first match wins. Moderation is the big one:
- # image models refuse trademarked characters / real people as an opaque 400.
- _IMAGE_ERROR_HINTS: tuple[tuple[tuple[str, ...], str], ...] = (
- (("moderation_blocked", "safety system", "content policy", "content_policy"),
- "The image provider blocked this prompt — its safety filter rejects "
- "trademarked characters and real people. Try an original description."),
- (("api key", "unauthorized", "401", "auth"),
- "The image provider rejected the request — check your API key in Settings → Providers."),
- (("rate limit", "429"), "The image provider is rate-limiting — wait a moment and try again."),
- )
- @dataclass(frozen=True)
- class HatchResult:
- """Outcome of a successful :func:`hatch_pet`."""
- slug: str
- display_name: str
- spritesheet: Path
- states: list[str]
- validation: dict
- def _unlink_quietly(path: Path) -> None:
- with contextlib.suppress(OSError):
- path.unlink(missing_ok=True)
- def _harden_transparency(path: Path) -> Path:
- """Key out any solid backdrop the provider painted; save as an RGBA PNG.
- ``background=transparent`` is honored inconsistently, so every base draft gets
- the chroma-key pass. Best-effort: a decode failure leaves the original untouched.
- """
- try:
- keyed = atlas._clear_transparent_rgb(atlas.remove_background(atlas._load_rgba(path))) # no halo on the dark UI
- # PNGs (any case) are hardened in place: with_suffix(".png") on ".PNG" would
- # name the same file on case-insensitive filesystems and the unlink below
- # would delete the hardened output.
- out = path if path.suffix.lower() == ".png" else path.with_suffix(".png")
- keyed.save(out, format="PNG")
- if out != path:
- _unlink_quietly(path) # nothing prunes cache/generated/images, so drop it now
- return out
- except Exception as exc:
- logger.debug("base draft transparency hardening failed for %s: %s", path, exc)
- return path
- def _run_parallel(fn, items, *, cancelled, on_cancel_log: str) -> Iterator:
- """Fan *fn* over *items* in a pool, yielding results in completion order.
- ``as_completed`` runs on the caller's thread, so result callbacks inherit the
- request's bound transport (workers don't). Once *cancelled* trips, queued work
- is cancelled and in-flight results dropped.
- """
- workers = max(1, min(len(items), _MAX_PARALLEL_GENERATIONS))
- with ThreadPoolExecutor(max_workers=workers) as pool:
- futures = [pool.submit(fn, item) for item in items]
- for fut in as_completed(futures):
- if cancelled():
- logger.info(on_cancel_log)
- for pending in futures:
- pending.cancel()
- break
- yield fut.result()
- def generate_base_drafts(
- concept: str,
- *,
- n: int = 4,
- style: str = "auto",
- reference_images: list[Path] | None = None,
- provider: SpriteProvider | None = None,
- on_draft: Callable[[int, Path], None] | None = None,
- is_cancelled: Callable[[], bool] | None = None,
- ) -> list[Path]:
- """Generate *n* candidate base looks for *concept* concurrently; returns image paths.
- Drafts are hardened to transparent cutouts; *on_draft(index, path)* fires as each
- finishes so UIs can stream previews. *is_cancelled* is polled cooperatively.
- """
- # A user reference image grounds every draft, so it needs a reference-capable provider.
- refs = reference_images or None
- sprite = provider or imagegen.resolve_provider(require_references=bool(refs))
- cancelled = is_cancelled or (lambda: False)
- logger.info("pet generate: drafting %d base looks for %r (style=%s)", n, concept, style)
- def _one(index: int) -> tuple[int, Path | None, str | None]:
- if cancelled():
- return index, None, None
- t0 = time.monotonic()
- variation = prompts.BASE_VARIATIONS[index % len(prompts.BASE_VARIATIONS)] # distinct look per draft
- prompt = prompts.build_base_prompt(concept, style=style, variation=variation)
- try:
- out = imagegen.generate(prompt, n=1, reference_images=refs, provider=sprite, prefix="pet_base")
- except Exception as exc:
- logger.warning("pet generate: draft %d failed after %.1fs: %s", index, time.monotonic() - t0, exc)
- return index, None, str(exc)
- if not out:
- logger.warning("pet generate: draft %d produced no image", index)
- return index, None, "the image provider returned no image"
- logger.info("pet generate: draft %d ready in %.1fs", index, time.monotonic() - t0)
- return index, _harden_transparency(out[0]), None
- results: dict[int, Path] = {}
- errors: list[str] = []
- cancel_log = "pet generate: cancelled — dropping remaining drafts"
- for index, path, err in _run_parallel(_one, range(n), cancelled=cancelled, on_cancel_log=cancel_log):
- if path is None:
- errors += [err] if err else []
- continue
- results[index] = path
- if on_draft is not None:
- try:
- on_draft(index, path)
- except Exception as exc:
- logger.debug("on_draft callback failed: %s", exc)
- drafts = [results[i] for i in sorted(results)]
- if not drafts and not cancelled():
- # Surface *why*: the most common failure reason is the representative cause.
- if not errors:
- raise GenerationError("image generation produced no usable drafts")
- raise GenerationError(_humanize_image_error(Counter(errors).most_common(1)[0][0]))
- return drafts
- def _humanize_image_error(error: str) -> str:
- """Turn a raw provider error into a friendly, actionable sentence."""
- low = error.lower()
- hint = next((message for needles, message in _IMAGE_ERROR_HINTS if any(s in low for s in needles)), None)
- return hint or error.splitlines()[0].strip()[:200] # first line, sans provider envelope
- def _generate_row(spec: tuple[str, int, int], *, base: Path, label: str, style: str, slug: str, sprite, cancelled) -> tuple[str, list | None]:
- """Generate + slice one animation row, retrying up to ``_ROW_GEN_ATTEMPTS`` times.
- Self-healing: a roll whose poses touch (no gutters) slices badly, so
- ``components`` (raises on touching poses) drives regeneration and only the
- final attempt uses lenient ``auto`` slicing. Returns ``(state, None)`` when
- cancelled or every attempt failed.
- """
- state, _row, count = spec
- t0 = time.monotonic()
- last_exc: Exception | None = None
- for attempt in range(_ROW_GEN_ATTEMPTS):
- if cancelled():
- return state, None
- strips: list[Path] = []
- try:
- # Landscape: each frame gets real horizontal room and clean gutters.
- strips = imagegen.generate(
- prompts.build_row_prompt(state, count, label, style=style), n=1, reference_images=[base],
- provider=sprite, prefix=f"pet_row_{state}", aspect_ratio="landscape",
- )
- # fit=False keeps raw columns so normalize_cells registers the whole pet at once.
- method = "components" if attempt < _ROW_GEN_ATTEMPTS - 1 else "auto"
- frames = atlas.extract_strip_frames(strips[0], count, method=method, fit=False)
- logger.info("pet hatch %r: row %r ready in %.1fs (attempt %d)", slug, state, time.monotonic() - t0, attempt + 1)
- return state, frames
- except Exception as exc:
- last_exc = exc
- logger.warning("pet hatch %r: row %r attempt %d/%d failed: %s", slug, state, attempt + 1, _ROW_GEN_ATTEMPTS, exc)
- finally:
- # Strips are intermediates already decoded into memory; nothing
- # prunes cache/generated/images, so drop them now.
- for strip in strips:
- _unlink_quietly(Path(strip))
- logger.warning("pet hatch %r: row %r gave up after %.1fs: %s", slug, state, time.monotonic() - t0, last_exc)
- return state, None
- def hatch_pet(
- *,
- base_image: str | Path,
- slug: str,
- display_name: str = "",
- description: str = "",
- concept: str = "",
- style: str = "auto",
- on_progress: ProgressFn | None = None,
- provider: SpriteProvider | None = None,
- is_cancelled: Callable[[], bool] | None = None,
- ) -> HatchResult:
- """Turn an approved base image into a full, installed Hermes pet.
- Idle falls back to the base look so the pet always renders. Raises
- :class:`GenerationError` on failure. Once *is_cancelled* trips, aborts before
- composing/saving so a stopped hatch never writes a half-built pet.
- """
- base = Path(base_image)
- if not base.is_file():
- raise GenerationError(f"base image not found: {base}")
- sprite = provider or imagegen.resolve_provider(require_references=True)
- progress = on_progress or (lambda *_: None)
- cancelled = is_cancelled or (lambda: False)
- label = concept or display_name or slug
- frames_by_state: dict[str, list] = {}
- total_rows = len(atlas.ROW_SPECS)
- logger.info("pet hatch %r: generating %d animation rows", slug, total_rows)
- def _gen_row(spec: tuple[str, int, int]) -> tuple[str, list | None]:
- return _generate_row(spec, base=base, label=label, style=style, slug=slug, sprite=sprite, cancelled=cancelled)
- # running-left is mirrored from running-right (consistent, one fewer generation).
- generated_specs = [spec for spec in atlas.ROW_SPECS if spec[0] != "running-left"]
- cancel_log = f"pet hatch {slug!r}: cancelled — dropping remaining rows"
- done = 0
- for state, frames in _run_parallel(_gen_row, generated_specs, cancelled=cancelled, on_cancel_log=cancel_log):
- done += 1
- progress("row", f"{state}:{done}:{total_rows}")
- if frames:
- frames_by_state[state] = frames
- if cancelled():
- raise GenerationError("hatch cancelled")
- # Per-frame mirror preserves order/timing. A missing running-right is
- # rejected below: a pet without its canonical walk cycle is a failed hatch.
- right = frames_by_state.get("running-right")
- if right:
- done += 1
- progress("row", f"running-left:{done}:{total_rows}")
- frames_by_state["running-left"] = atlas.mirror_frames(right)
- logger.info("pet hatch %r: row 'running-left' mirrored from running-right", slug)
- else:
- logger.warning("pet hatch %r: no running-right to mirror; left walk left empty", slug)
- if not frames_by_state.get("idle"): # the renderer's resting fallback — guarantee it
- progress("row", "idle-fallback")
- frames_by_state["idle"] = [atlas.single_frame(base, fit=False)]
- progress("compose", "")
- logger.info("pet hatch %r: composing atlas from %d states", slug, len(frames_by_state))
- # One shared scale + baseline across states so the pet never slides or pulses.
- sheet = atlas.compose_atlas(atlas.normalize_cells(frames_by_state))
- validation = atlas.validate_atlas(sheet)
- if not validation["ok"]:
- raise GenerationError("; ".join(validation["errors"]) or "atlas validation failed")
- filled_states = set(validation["filled_states"])
- if missing_required := sorted(_REQUIRED_STATES - filled_states):
- raise GenerationError(f"missing required animation row(s): {', '.join(missing_required)}")
- if len(filled_states) < _MIN_FILLED_STATES:
- raise GenerationError(f"only {len(filled_states)}/{total_rows} animation rows were usable; regenerate")
- from agent.pet import store
- progress("save", slug)
- logger.info("pet hatch %r: saving pet", slug)
- pet = store.register_local_pet(sheet, slug=slug, display_name=display_name or slug, description=description)
- return HatchResult(pet.slug, pet.display_name, pet.spritesheet, validation["filled_states"], validation)
|