Skip to content

Official Codebase of 3DCodeVerse

Python
32.4 KB
Raw Blame
"""Plans: the agent's structured decomposition, each with an acceptance checklist.

Written by the host agent as ``plan.json``, then validated in code (``3dcode validate-plan``)."""

from __future__ import annotations

import contextlib
import math
import re
from typing import Annotated, Any, Literal

from pydantic import AfterValidator, BaseModel, Field, field_validator, model_validator

from codeverse3d.contracts.common import (
    Language,
    MimicSpec,
    Vec3,
    mimic_issues,
)
from codeverse3d.conventions import to_snake

#: model ids / placeholders that leak into part names.  High-precision patterns only:
#: "CameraFlash" or "ModelStand" must stay legal.
_MODEL_NAME_LEAK = re.compile(r"(?i)(gemini|gpt[-_ ]?\d|claude|llama|qwen|deepseek|placeholder)")


def reject_model_leak(v: str) -> str:
    """Reject (never mangle) part names that are model ids / placeholders."""
    m = _MODEL_NAME_LEAK.search(v)
    if m:
        raise ValueError(
            f"part name {v!r} contains {m.group(1)!r} — a model id or placeholder leaked from "
            "thinking, not a component of the object.  Name the real part (e.g. GrinderWheel).")
    return v


LeakFreeName = Annotated[str, AfterValidator(reject_model_leak)]


class BBox(BaseModel):
    """Axis-aligned box in the plan's frame: centre + full extents (meters)."""

    center: Vec3
    extents: Vec3

    @property
    def min(self) -> tuple[float, float, float]:
        return tuple(c - e / 2 for c, e in zip(self.center, self.extents, strict=True))  # type: ignore[return-value]

    @property
    def max(self) -> tuple[float, float, float]:
        return tuple(c + e / 2 for c, e in zip(self.center, self.extents, strict=True))  # type: ignore[return-value]


class AcceptanceItem(BaseModel):
    """One verifiable requirement.  ``how`` says which evidence proves it."""

    id: str
    text: str
    how: Literal["measure", "visual", "probe", "articulation"] = "visual"
    priority: Literal["must", "should"] = "must"


#: how far a sub-part may stick out of its parent's bbox: ``max(SUBPART_SLACK_M,
#: SUBPART_REL_SLACK × parent extent)`` per axis (planner boxes are design intent).
SUBPART_SLACK_M = 0.01
SUBPART_REL_SLACK = 0.15
#: A ``revolute`` range over 2π with both limits inside ±``DEGREES_MAX_ABS`` and a span of at
#: least ``DEGREES_MIN_SPAN`` is read as degrees; a smaller span over 2π is radians and becomes
#: ``continuous``.
DEGREES_MAX_ABS = 360.0
DEGREES_MIN_SPAN = 30.0


class SubPartPlan(BaseModel):
    """One sub-part of a :class:`PartPlan` — depth 1 by construction (a sub-part has no
    children of its own, so a cycle cannot be expressed).

    Sub-parts are a PLANNING device, not export nodes: the parent part is still exactly ONE
    named object in the GLB and the contract gate still checks exactly the parent's bbox.
    They exist so a part a human would call an *assembly* ("burr mechanism", "pegbox",
    "belt housing") can be planned as the 3-6 shapes it really is — which is where the
    measured judge reward lives — without adding contact surfaces the assembly gates must
    police.  See the complexity baseline: built-parts ÷ planned-parts is
    the only complexity metric with a positive partial correlation to geometry_detail."""

    name: LeakFreeName = Field(description="PascalCase, unique within the parent, e.g. Burr")
    role: str = Field(default="", description="what this sub-part is, a few words")
    description: str = Field(description="shape and construction in numbers")
    bbox: BBox = Field(description="inside the parent's bbox, same frame")
    material: str = Field(default="", description="material / finish when it differs from the parent's")
    instances: int = Field(default=1, ge=1, description="identical copies inside the parent")


class PartPlan(BaseModel):
    name: LeakFreeName = Field(description="PascalCase unique part name, e.g. SeatCushion")
    role: str = Field(description="what this part is / does, one line")
    description: str = Field(description="shape, construction and visible detail the builder must realise")
    bbox: BBox
    material: str = Field(default="", description="material / finish in plain words")
    attach_to: str | None = Field(default=None, description="parent part name this part touches")
    symmetry: Literal["none", "mirror_x", "mirror_y", "radial"] = "none"
    instances: int = Field(default=1, ge=1, description="identical copies (e.g. 4 legs)")
    children: list[SubPartPlan] = Field(
        default_factory=list, max_length=8,
        description="sub-parts of an ASSEMBLY part (a mechanism, a housing, a head) — still ONE named "
                    "object in the export; leave empty for a simple part such as a leg")
    detail_hint: str = Field(
        default="", description="one line telling the builder what makes THIS part read as real "
                                "(e.g. 'carries the visible mechanism — model the burrs, the shaft and the nut')")

    @property
    def leaf_count(self) -> int:
        """Shapes this part stands for: its own copies, or the sum of its children's."""
        inner = sum(c.instances for c in self.children) or 1
        return self.instances * inner

    @model_validator(mode="after")
    def _children_ok(self) -> PartPlan:
        seen: set[str] = set()
        pmin, pmax = self.bbox.min, self.bbox.max
        for c in self.children:
            key = to_snake(c.name)
            if key == to_snake(self.name):
                raise ValueError(f"part {self.name}: sub-part {c.name} repeats its parent's name")
            if key in seen:
                raise ValueError(f"part {self.name}: duplicate sub-part name (after normalisation): {c.name}")
            seen.add(key)
            cmin, cmax = c.bbox.min, c.bbox.max
            for axis, lo, hi, clo, chi, ext in zip("xyz", pmin, pmax, cmin, cmax, self.bbox.extents, strict=True):
                slack = max(SUBPART_SLACK_M, SUBPART_REL_SLACK * abs(ext))
                over = max(lo - clo, chi - hi)
                if over > slack:
                    raise ValueError(
                        f"part {self.name}: sub-part {c.name} sticks {over * 1000:.0f} mm out of the parent bbox on "
                        f"{axis} (parent {axis} in [{lo:.3f}, {hi:.3f}], sub-part [{clo:.3f}, {chi:.3f}], "
                        f"allowed slack {slack * 1000:.0f} mm) — either shrink/move the sub-part or grow the parent bbox")
        return self


class StaticPlan(BaseModel):
    object_name: str
    summary: str
    overall_bbox: BBox
    style_notes: str = ""
    parts: list[PartPlan] = Field(min_length=1)
    acceptance: list[AcceptanceItem] = Field(default_factory=list)

    @model_validator(mode="after")
    def _unique_names(self) -> StaticPlan:
        seen: set[str] = set()
        for p in self.parts:
            key = to_snake(p.name)
            if key in seen:
                raise ValueError(f"duplicate part name (after normalisation): {p.name}")
            seen.add(key)
        names = {to_snake(p.name) for p in self.parts}
        for p in self.parts:
            if p.attach_to and to_snake(p.attach_to) not in names:
                raise ValueError(f"part {p.name} attaches to unknown part {p.attach_to}")
        for p in self.parts:
            for c in p.children:
                if to_snake(c.name) in names:
                    raise ValueError(f"sub-part {p.name}.{c.name} has the same name as top-level part {c.name}; "
                                     "either rename it or promote it to a top-level part")
        return self

    @property
    def leaf_count(self) -> int:
        """Total shapes the plan asks for (parts × instances, sub-parts counted individually)."""
        return sum(p.leaf_count for p in self.parts)


class MimicPlan(BaseModel):
    """This joint is driven by another: ``q = multiplier * q[joint] + offset``.

    A coupled mechanism (umbrella ribs on one runner, a pantograph, a tambour) has ONE
    input and many moving links.  Declaring the coupling lets the sweep pose it the way
    it really moves; without it every link is driven independently."""

    joint: str = Field(description="the joint this one follows, by name")
    multiplier: float = Field(default=1.0, description="q_this = multiplier * q_that + offset")
    offset: float = Field(default=0.0)

class JointPlan(BaseModel):
    name: LeakFreeName
    type: Literal["revolute", "prismatic", "continuous", "fixed"]
    parent: str = Field(description="parent link (part) name")
    child: str = Field(description="child link (part) name")
    axis: Vec3 = Field(description="unit axis in the plan frame")
    pivot: Vec3 = Field(description="a point on the joint axis, WORLD coords (rest pose)")
    lower: float = Field(default=0.0, description="rad for revolute, m for prismatic")
    upper: float = Field(default=0.0)
    rest: float = Field(default=0.0, description="joint value in the authored rest pose")
    motion: str = Field(default="", description="what moving this joint does, one line")
    mimic: MimicPlan | None = Field(default=None, description="set when this joint is driven by another")

    @model_validator(mode="after")
    def _sane(self) -> JointPlan:
        n = math.sqrt(sum(a * a for a in self.axis))
        if n < 1e-6:
            raise ValueError(f"joint {self.name}: zero axis")
        if abs(n - 1.0) > 1e-3:
            self.axis = tuple(a / n for a in self.axis)  # type: ignore[assignment]
        if self.type in ("revolute", "prismatic"):
            if self.upper < self.lower:
                raise ValueError(f"joint {self.name}: upper < lower")
            if not (self.lower - 1e-9 <= self.rest <= self.upper + 1e-9):
                raise ValueError(f"joint {self.name}: rest {self.rest} outside [{self.lower},{self.upper}]")
            if self.type == "revolute" and (self.upper - self.lower) > 2 * math.pi + 1e-6:
                raise ValueError(f"joint {self.name}: revolute range > 2π, use continuous")
            if self.type == "prismatic" and (self.upper - self.lower) > 5.0:
                raise ValueError(f"joint {self.name}: prismatic range > 5 m is implausible")
        if to_snake(self.parent) == to_snake(self.child):
            # name BOTH sides: pydantic truncates the offending value after the joint name.
            same = "" if self.parent == self.child else (
                f" ('{self.parent}' and '{self.child}' are the same name once normalised)")
            raise ValueError(
                f"joint {self.name}: parent and child are both '{self.parent}'{same} — a joint "
                f"connects TWO different links; name the moving link as child and what it is "
                f"attached to as parent, or drop the joint if nothing moves")
        return self


def _looks_like_degrees(lower: float, upper: float) -> bool:
    """Revolute limits the planner wrote in degrees: inside ±360 with a span of at least 30 (see the constants)."""
    return abs(lower) <= DEGREES_MAX_ABS and abs(upper) <= DEGREES_MAX_ABS and upper - lower >= DEGREES_MIN_SPAN



def _promoted(child: dict, owner: dict) -> dict:
    """A sub-part a joint moves, as the top-level link it becomes (repairs 1 and 1c)."""
    return {"name": child.get("name"), "role": child.get("role") or f"moving part of {owner.get('name')}",
            "description": child.get("description", ""), "bbox": child.get("bbox"),
            "material": child.get("material") or owner.get("material", ""),
            "attach_to": owner.get("name"), "instances": child.get("instances", 1)}


def _raw_bounds(bbox: object) -> tuple[list[float], list[float]] | None:
    """``(lo, hi)`` of a raw ``{center, extents}`` bbox dict, or None when it is not one (repair 3)."""
    if not (isinstance(bbox, dict) and isinstance(bbox.get("center"), (list, tuple))
            and isinstance(bbox.get("extents"), (list, tuple))):
        return None
    try:
        pairs = [(float(c), float(e) / 2) for c, e in zip(bbox["center"], bbox["extents"], strict=True)]
    except (TypeError, ValueError):
        return None
    return [c - h for c, h in pairs], [c + h for c, h in pairs]

class ArticulatedPlan(StaticPlan):
    root_link: str
    joints: list[JointPlan] = Field(min_length=1)
    normalisations: list[str] = Field(
        default_factory=list,
        description="filled by validate-plan, leave empty: automatic corrections applied to the plan "
                    "before validation (a sub-part promoted to a link because a joint moves it, revolute limits "
                    "written in degrees converted to radians or a > 2π radian range made continuous, swapped "
                    "or out-of-range limits clamped, a parent bbox grown around a sub-part)")

    @model_validator(mode="before")
    @classmethod
    def _normalise_raw(cls, data: object) -> object:
        """Repair schema-shaped planner slips that are not design decisions:

        1. a joint naming a sub-part promotes it to a top-level part;
        1b/1c. a joint naming a part or sub-part by a unique fragment is resolved;
        2. revolute limits written in degrees become radians; other ranges over 2π become ``continuous``;
        2b. swapped limits are swapped back, an out-of-range ``rest`` is clamped;
        3. a sub-part outside its parent's bbox grows the parent;
        4. a ``root_link`` naming no part is rewritten when exactly one part matches.

        Every repair is recorded in ``normalisations``; anything else fails validation.
        """
        if not isinstance(data, dict):
            return data
        data = dict(data)
        parts = [dict(p) for p in (data.get("parts") or []) if isinstance(p, dict)]
        joints = [dict(j) for j in (data.get("joints") or []) if isinstance(j, dict)]
        # harness-only field: any incoming value is dropped
        notes: list[str] = []
        if not parts or not joints:
            return data
        by_name = {to_snake(str(p.get("name", ""))): p for p in parts}

        # 1. joints that move a sub-part → promote it
        referenced = {to_snake(str(j.get(k, ""))) for j in joints for k in ("parent", "child")}
        for part in list(parts):
            kept = []
            for child in part.get("children") or []:
                if not isinstance(child, dict):
                    kept.append(child)
                    continue
                key = to_snake(str(child.get("name", "")))
                if key in referenced and key not in by_name:
                    promoted = _promoted(child, part)
                    parts.append(promoted)
                    by_name[key] = promoted
                    notes.append(f"promoted sub-part {part.get('name')}.{child.get('name')} to a link: a joint moves it")
                else:
                    kept.append(child)
            part["children"] = kept

        # 1b. a joint naming a link by a unique fragment of a real part ("Lid" for "ChestLid")
        known = set(by_name)
        for j in joints:
            for side in ("parent", "child"):
                raw_name = str(j.get(side, ""))
                key = to_snake(raw_name)
                if not key or key in known:
                    continue
                hits = [n for n in known if key in n.split("_") or n.endswith(f"_{key}") or n.startswith(f"{key}_")]
                if len(hits) == 1:
                    j[side] = by_name[hits[0]].get("name")
                    notes.append(f"joint {j.get('name')}.{side} '{raw_name}' resolved to the one part it names: {j[side]}")

        # 1c. a joint naming a sub-part by a fragment: WORD-SUBSET match ({glazed,door} within
        # {glazed,front,door}; "arm" never matches "alarm"); a unique hit is promoted.
        sub_index: dict[str, tuple[dict, dict]] = {}
        for part in list(parts):
            for child in part.get("children") or []:
                if isinstance(child, dict) and child.get("name"):
                    sub_index[to_snake(str(child["name"]))] = (part, child)
        for j in joints:
            for side in ("parent", "child"):
                raw_name = str(j.get(side, ""))
                key = to_snake(raw_name)
                if not key or key in by_name:
                    continue
                kw = set(key.split("_"))
                hits = [k for k in sub_index if kw <= set(k.split("_"))]
                if len(hits) != 1:
                    continue
                owner, child = sub_index[hits[0]]
                ckey = to_snake(str(child["name"]))
                if ckey not in by_name:
                    promoted = _promoted(child, owner)
                    parts.append(promoted)
                    by_name[ckey] = promoted
                    with contextlib.suppress(ValueError, KeyError):
                        owner["children"].remove(child)
                    notes.append(f"promoted sub-part {owner.get('name')}.{child.get('name')} to a link: "
                                 f"joint {j.get('name')} names it")
                j[side] = by_name[ckey].get("name")
                notes.append(f"joint {j.get('name')}.{side} '{raw_name}' resolved to sub-part {j[side]}")

        # 2. revolute joints with a > 2π range: degrees written for radians → radians; a radian
        #    range over 2π → continuous
        for j in joints:
            if j.get("type") != "revolute":
                continue
            try:
                lower, upper = float(j.get("lower", 0.0)), float(j.get("upper", 0.0))
            except (TypeError, ValueError):
                continue
            if upper - lower <= 2 * math.pi + 1e-6:
                continue
            if _looks_like_degrees(lower, upper):
                j.update(lower=math.radians(lower), upper=math.radians(upper))
                try:
                    rest = float(j.get("rest", 0.0))
                except (TypeError, ValueError):
                    rest = None
                if rest is not None and lower - 1e-9 <= rest <= upper + 1e-9:
                    j["rest"] = math.radians(rest)
                notes.append(f"joint {j.get('name')}: limits looked like degrees ({lower:g}..{upper:g}) → radians")
                lower, upper = float(j["lower"]), float(j["upper"])
            span = upper - lower
            if span > 2 * math.pi + 1e-6:
                j.update(type="continuous", lower=0.0, upper=0.0, rest=0.0)
                notes.append(f"joint {j.get('name')}: revolute range {span:.2f} rad > 2π → continuous")

        # 2b. swapped or out-of-range limits → swap / clamp (see the docstring)
        for j in joints:
            if j.get("type") not in ("revolute", "prismatic"):
                continue
            try:
                lower, upper = float(j.get("lower", 0.0)), float(j.get("upper", 0.0))
            except (TypeError, ValueError):
                continue
            if upper < lower:
                j["lower"], j["upper"] = upper, lower
                notes.append(f"joint {j.get('name')}: limits swapped ({lower:g}..{upper:g} → {upper:g}..{lower:g})")
                lower, upper = upper, lower
            try:
                rest = float(j.get("rest", 0.0))
            except (TypeError, ValueError):
                continue
            if rest < lower - 1e-9 or rest > upper + 1e-9:
                j["rest"] = min(max(rest, lower), upper)
                notes.append(f"joint {j.get('name')}: rest {rest:g} outside [{lower:g},{upper:g}] → clamped to {j['rest']:g}")

        # 3. sub-parts outside the parent bbox → grow the parent
        for part in parts:
            bounds = _raw_bounds(part.get("bbox"))
            if bounds is None:
                continue
            lo, hi = bounds
            grown = False
            for child in part.get("children") or []:
                cbounds = _raw_bounds(child.get("bbox") if isinstance(child, dict) else None)
                if cbounds is None:
                    continue
                clo, chi = cbounds
                for a in range(3):
                    slack = max(SUBPART_SLACK_M, SUBPART_REL_SLACK * abs(hi[a] - lo[a]))
                    if lo[a] - clo[a] > slack or chi[a] - hi[a] > slack:
                        lo[a], hi[a] = min(lo[a], clo[a]), max(hi[a], chi[a])
                        grown = True
                        notes.append(f"part {part.get('name')}: bbox grown on {'xyz'[a]} around sub-part "
                                     f"{child.get('name')}")
            if grown:
                part["bbox"] = {"center": [(lo[a] + hi[a]) / 2 for a in range(3)],
                                "extents": [hi[a] - lo[a] for a in range(3)]}

        # 4. root_link that names no part: loose word-match against the part list
        root = data.get("root_link")
        if isinstance(root, str) and root.strip():
            names = {to_snake(p.get("name", "")): p.get("name") for p in parts if p.get("name")}
            rk = to_snake(root)
            if rk not in names:
                # word-boundary rule as in 1b, never bare substring
                hits = [orig for k, orig in names.items()
                        if rk in k.split("_") or k.endswith(f"_{rk}") or k.startswith(f"{rk}_")]
                if len(hits) == 1:
                    notes.append(f"root_link '{root}' named no part; rewrote to '{hits[0]}'")
                    data["root_link"] = hits[0]
                elif not hits:
                    # 4b. nothing matches: the one part no joint names as a child is the root
                    children = {to_snake(str(j.get("child", ""))) for j in joints}
                    roots = [orig for k, orig in names.items() if k not in children]
                    if len(roots) == 1:
                        notes.append(f"root_link '{root}' named no part; rewrote to the one link no joint moves: '{roots[0]}'")
                        data["root_link"] = roots[0]

        data["parts"], data["joints"], data["normalisations"] = parts, joints, notes
        return data

    @model_validator(mode="after")
    def _tree(self) -> ArticulatedPlan:
        links = {to_snake(p.name) for p in self.parts}
        root = to_snake(self.root_link)
        if root not in links:
            raise ValueError(f"root_link {self.root_link} is not a part")
        parent_of: dict[str, str] = {}
        for j in self.joints:
            p, c = to_snake(j.parent), to_snake(j.child)
            if p not in links or c not in links:
                unknown = ", ".join(n for n, k in ((j.parent, p), (j.child, c)) if k not in links)
                subs = sorted({c.name for part in self.parts for c in part.children})
                sub_note = (f" Sub-parts that exist but are NOT links: {', '.join(subs)} — a joint may "
                            f"only move a top-level part; name one of those exactly to promote it, or a real part."
                            if subs else "")
                raise ValueError(
                    f"joint {j.name} references unknown link(s) {unknown} — the parts in this plan are: "
                    f"{', '.join(sorted(links))}. Use those exact names (or add the missing part).{sub_note}")
            if c in parent_of:
                raise ValueError(f"link {j.child} has two parent joints")
            if c == root:
                raise ValueError(f"root link {self.root_link} cannot be a joint child")
            parent_of[c] = p
        # every non-root link must reach root
        for link in links - {root}:
            seen, cur = set(), link
            while cur != root:
                if cur in seen or cur not in parent_of:
                    raise ValueError(f"link {link} is not connected to root {self.root_link} (single-root tree required)")
                seen.add(cur)
                cur = parent_of[cur]
        self._check_mimics()
        return self

    def _check_mimics(self) -> None:
        """Every coupling must name a joint that exists, moves, and does not loop (``common.mimic_issues``)."""
        by_name = {j.name: j for j in self.joints}
        issues = mimic_issues([
            MimicSpec(key=to_snake(j.name), name=j.name, movable=j.type != "fixed",
                      target=to_snake(j.mimic.joint) if j.mimic else None,
                      multiplier=j.mimic.multiplier if j.mimic else 1.0)
            for j in self.joints])
        for i in issues:
            follower = by_name.get(i.joint)
            wanted = follower.mimic.joint if follower is not None and follower.mimic else i.target
            if i.kind == "out_of_range":
                continue  # only the lint warns about overshooting a limit
            raise ValueError({
                "immobile": f"joint {i.joint}: a fixed joint cannot mimic {wanted}",
                "zero_multiplier": f"mimic of {wanted}: multiplier 0 means the joint cannot move; use type=fixed",
                "self": f"joint {i.joint}: mimics itself",
                "unknown_target": f"joint {i.joint}: mimic joint {wanted} is not a joint in this plan; "
                                  f"the joints are: {', '.join(sorted(x.name for x in self.joints))}",
                "immobile_target": f"joint {i.joint}: mimics {i.target}, which is fixed and never moves",
                "cycle": f"joint {i.joint}: mimic chain loops back through {i.detail}",
            }[i.kind])


class ZonePlan(BaseModel):
    name: str = Field(description="PascalCase zone name, e.g. Harbour")
    description: str = Field(description="what the place is, what happens there, its layout as numbers and "
                             "how much dressing it carries — one builder realises it")
    bbox: BBox = Field(description="where this zone's builder may place; any size or shape, laid out as the "
                       "place is (its layout is validated against this box)")
    contents: list[str] = Field(default_factory=list, description="asset names placed in this zone")


#: the asset kinds each scene language plans: ``bpy`` / ``threejs`` = a procedural module,
#: ``blender_glb`` = a hero built as an object and shipped as a GLB
SCENE_ASSET_KINDS: dict[str, tuple[str, ...]] = {
    "scene_threejs": ("threejs", "blender_glb"),
    "scene_blender": ("bpy", "blender_glb"),
}


#: what ``AssetPlan.kind`` means to the planner of each scene language (scene_threejs keeps the field's own text)
SCENE_KIND_DOCS: dict[str, str] = {
    "scene_blender": "bpy = a procedural Blender module (src/assets/<snake>.py, built once at the origin and "
                     "placed as collection instances); blender_glb = a hero built as an object and shipped as a GLB",
}


class AssetPlan(BaseModel):
    name: str = Field(description="PascalCase asset name")
    kind: Literal["threejs", "bpy", "blender_glb"] = Field(
        description="threejs = procedural module; blender_glb = built with bpy and compiled to a GLB",
        # default is scene_threejs's enum; ``scene_plan_schema`` swaps in the language's own
        json_schema_extra={"enum": list(SCENE_ASSET_KINDS["scene_threejs"])},
    )
    description: str = Field(description="construction in numbers and colours; the builder realises it")
    approx_size_m: Vec3 = Field(description="width x height x depth in meters; the built asset is measured against it")
    instances_hint: int = Field(default=1, description="how many appear in the whole scene")


class EffectPlan(BaseModel):
    name: str
    kind: Literal["glsl_material", "postprocess", "particles", "animated_geometry"]
    description: str
    target: str = Field(default="", description="zone / asset / scene it applies to")


#: a camera name becomes a render filename, so it is charset- and length-bounded
CAMERA_NAME_RE = re.compile(r"[A-Za-z0-9_-]{1,64}")


#: Same name / fov / position rules as ``scene_host.mjs`` validateCameras.
class CameraPlan(BaseModel):
    name: str = Field(description="letters/digits/_/- only; it becomes a render filename")
    position: Vec3
    look_at: Vec3
    fov: float = Field(default=50.0, ge=5.0, le=150.0)
    purpose: str = Field(default="", description="what the shot is of and what the judge should see in it")

    @field_validator("name")
    @classmethod
    def _filename_safe(cls, v: str) -> str:
        """Reject (never mangle) unsafe names."""
        if not CAMERA_NAME_RE.fullmatch(v):
            raise ValueError(
                f"camera name {v!r} must match [A-Za-z0-9_-]{{1,64}}: it becomes a render "
                "filename (no spaces, dots, slashes or other path characters)")
        return v

    @model_validator(mode="after")
    def _looks_somewhere(self) -> CameraPlan:
        if all(abs(p - q) < 1e-6 for p, q in zip(self.position, self.look_at, strict=True)):
            raise ValueError(f"camera {self.name!r}: position equals look_at (it looks nowhere)")
        return self


class ScenePlan(BaseModel):
    title: str
    summary: str
    setting: str = Field(description="place, era, weather, time of day")
    mood: str = ""
    bounds: BBox = Field(description="the DETAILED area the harness measures against (layouts, placements, camera "
                         "clearance); the world continues past it as the place does")
    environment: str = Field(description="lighting, atmosphere, landform and ground surface, water, and how the world "
                             "continues beyond the bounds — one paragraph of numbers")
    interior: bool = Field(
        default=False,
        description="the view is from INSIDE a built space (workshop, room, cabin, hall, shop): the "
        "environment module owns the enclosure — floor, walls, ceiling and the openings `environment` "
        "describes (the skeleton starts it on the bounds' faces; the builder may reshape it) — and the "
        "zones dress the inside; false outdoors",
    )
    glazed: bool = Field(
        default=False,
        description="only with interior: the enclosure itself is glass on a metal frame (glasshouse, "
        "conservatory, palm house, greenhouse, glass atrium) — the environment builds glass walls and "
        "roof on a frame grid, and the sun and the land outside come through them; false for a room "
        "with windows",
    )
    zones: list[ZonePlan] = Field(min_length=1)
    assets: list[AssetPlan] = Field(default_factory=list)
    effects: list[EffectPlan] = Field(default_factory=list)
    animation: list[str] = Field(default_factory=list, description="what moves and how")
    cameras: list[CameraPlan] = Field(min_length=1, max_length=6)
    acceptance: list[AcceptanceItem] = Field(default_factory=list)

    @model_validator(mode="after")
    def _names(self) -> ScenePlan:
        assets = {to_snake(a.name) for a in self.assets}
        zones = set()
        for z in self.zones:
            k = to_snake(z.name)
            if k in zones:
                raise ValueError(f"duplicate zone {z.name}")
            zones.add(k)
            for c in z.contents:
                if to_snake(c) not in assets:
                    raise ValueError(f"zone {z.name} lists unknown asset {c}")
        return self


def scene_plan_schema(language: Language | str) -> dict[str, Any]:
    """The ``ScenePlan`` JSON schema for ``language``: ``AssetPlan.kind``'s enum and description
    are that language's.  ``KeyError`` for a language that plans no scene."""
    kinds = SCENE_ASSET_KINDS[Language(language).value]
    schema = ScenePlan.model_json_schema()
    kind = schema["$defs"]["AssetPlan"]["properties"]["kind"]
    kind["enum"] = list(kinds)
    doc = SCENE_KIND_DOCS.get(Language(language).value)
    if doc:
        kind["description"] = doc
    return schema


class PassPlan(BaseModel):
    name: str = Field(description="PascalCase pass name, e.g. Clouds, Bloom")
    kind: Literal["fullscreen", "geometry", "postprocess", "feedback"] = "fullscreen"
    description: str = Field(description="what this pass draws / computes, concrete")
    elements: list[str] = Field(
        default_factory=list, max_length=8,
        description="optional: up to 8 named things this pass draws, each with its numbers")
    detail_hint: str = Field(default="", description="one line: what makes THIS pass read as real")


class GraphicsPlan(BaseModel):
    """Plan for the graphics track (GLSL shader / raw OpenGL program)."""

    title: str
    summary: str
    style: str = Field(description="visual style: palette, mood, references in words")
    resolution: tuple[int, int] = (1280, 720)
    duration_s: float = Field(default=8.0, description="loop length for judging / video")
    passes: list[PassPlan] = Field(min_length=1)
    uniforms: list[str] = Field(default_factory=list, description="uniform names the program exposes (u_time, u_resolution, ...)")
    motion: str = Field(default="", description="what animates over time and how")
    key_visuals: list[str] = Field(default_factory=list, description="visible elements a viewer must recognise")
    acceptance: list[AcceptanceItem] = Field(default_factory=list)


Plan = StaticPlan | ArticulatedPlan | ScenePlan | GraphicsPlan