피파가 직접 쓰는 이펙트

import json
import math
import re

SHAPES = ("circle", "square", "triangle", "star", "heart", "petal", "drop", "flake",
          "ribbon", "ring", "spark", "text")
MAX_LAYERS = 6
DEFAULT_SURFACE = {"web_search", "calendar", "home_control", "onair_effect"}
TURN_GATED = {"onair_effect"}               # never part of an "every tool" expansion


class EffectError(ValueError):
    """A definition the library refuses, with the reason in words."""


def clamp(value, low, high, default):
    try:
        number = float(value)
    except (TypeError, ValueError):
        return default
    return max(low, min(high, number)) if math.isfinite(number) else default


def clamp_range(value, low, high, default):
    """A [min, max] pair, each end clamped; one number means both ends."""
    if isinstance(value, (int, float)):
        value = [value, value]
    if not isinstance(value, (list, tuple)) or len(value) != 2:
        value = default
    first, second = (clamp(v, low, high, d) for v, d in zip(value, default))
    return [min(first, second), max(first, second)]


COLOR = re.compile(r"^#[0-9a-fA-F]{3,8}$")


def normalize_layer(raw: dict) -> dict:
    """Every number clamped on save, so the renderer never meets one it can't draw."""
    shape = raw.get("shape") if raw.get("shape") in SHAPES else "circle"
    colors = [c for c in (raw.get("colors") or []) if isinstance(c, str) and COLOR.match(c)]
    layer = {"shape": shape, "colors": colors[:8] or ["#ffffff"],
             "count": int(clamp(raw.get("count"), 1, 400, 60)),
             "gravity": clamp(raw.get("gravity"), -2000, 2000, 120),
             "speed": clamp_range(raw.get("speed"), 0, 2000, (80, 220)),
             "size": clamp_range(raw.get("size"), 1, 200, (6, 14)),
             "wobble": clamp(raw.get("wobble"), 0, 200, 0),
             "lifetime_ms": clamp_range(raw.get("lifetime_ms"), 100, 15000, (1500, 3500))}
    if shape == "text":
        glyph = (raw.get("glyph") or "").strip()
        if not glyph:
            raise EffectError("a text layer needs a glyph (an emoji or a few letters)")
        layer["glyph"] = glyph[:8]
    return layer


def normalize_visual(spec: dict) -> dict:
    layers = [normalize_layer(layer) for layer in (spec.get("layers") or [])[:MAX_LAYERS]]
    if not layers:
        raise EffectError("visual.layers must list at least one particle layer")
    visual = {"duration_ms": int(clamp(spec.get("duration_ms"), 300, 15000, 3000)), "layers": layers}
    caption = spec.get("caption")
    if isinstance(caption, dict) and isinstance(caption.get("text"), str) and caption["text"].strip():
        visual["caption"] = {"text": caption["text"].strip()[:60],
                             "ms": int(clamp(caption.get("ms"), 300, 8000, 1800))}
    return visual


def with_effect_tool(allowlist: list[str] | None, *, onair: bool) -> list[str] | None:
    """Add the tool to an On Air turn's list and take it off any other. No list means
    the default surface: expand it first, or the tool has nowhere to go."""
    if allowlist is None:
        return sorted(DEFAULT_SURFACE - TURN_GATED) + ["onair_effect"] if onair else None
    rest = [name for name in allowlist if name != "onair_effect"]
    return rest + ["onair_effect"] if onair else rest


def fired_effect(tool_input: str) -> str | None:
    """A stored tool input may be JSON or a Python repr; read both."""
    try:
        data = json.loads(tool_input)
    except ValueError:
        found = {key: re.search(rf"""['"]{key}['"]\s*:\s*['"]([^'"]+)""", tool_input)
                 for key in ("action", "id")}
        data = {key: match.group(1) if match else None for key, match in found.items()}
    return data.get("id") if isinstance(data, dict) and data.get("action") == "fire" else None


party = normalize_visual({"duration_ms": 99_999, "layers": [
    {"shape": "star", "count": 5000, "gravity": 300},
    {"shape": "text", "glyph": "🎉", "count": 12},
]})
print(party["duration_ms"], [(layer["shape"], layer["count"]) for layer in party["layers"]])
print(with_effect_tool(["web_search"], onair=True))
print(with_effect_tool(["web_search", "onair_effect"], onair=False))
print(with_effect_tool(None, onair=True))              # a client that sends no list
print(fired_effect('{"action": "fire", "id": "confetti"}'),
      fired_effect("{'action': 'fire', 'id': 'petals'}"),
      fired_effect('{"action": "create", "name": "snow"}'))