Official Codebase of 3DCodeVerse
Python
"""``3dcode validate-plan``: ``plan.json`` against the track's plan model plus the deterministic plan checks
(placeholder echo, the size / detail budget derived from the request, fixed-part clash), then the normalisation
every accepted plan gets (PascalCase names, the acceptance items the spec implies)."""
from __future__ import annotations
import re
from dataclasses import dataclass
from typing import Any
from pydantic import BaseModel, ValidationError
from codeverse3d.contracts.common import Language, Track
from codeverse3d.contracts.plan import SCENE_ASSET_KINDS, AcceptanceItem
from codeverse3d.contracts.spec import Spec
from codeverse3d.conventions import to_pascal, to_snake
# ===================================================================== plan budgets
#: practical ceiling on TOP-LEVEL plan parts per language. Blender/three.js own one
#: file per part so they scale; cadquery is one file; urdf links cost a joint each and
#: the collision sweep is O(links² × poses), so depth there goes into sub-parts.
PART_CAP: dict[str, int] = {
Language.BLENDER.value: 20,
Language.THREEJS.value: 20,
Language.CADQUERY.value: 14,
Language.URDF_BLENDER.value: 10,
}
DEFAULT_PART_CAP = 14
MIN_PARTS = 6
#: a checklist this long is EVIDENCE that the request really needs the target part count; below it the
#: target is an aspiration the check must not enforce
EVIDENCE_MIN_CHECKLIST = 4
GRAPHICS_CAP = 6
GRAPHICS_MIN = 1
# --------------------------------------------------------------------- "is this a box?"
#: construction verbs / counted repeated features that make a part description more than
#: "a box of size X". Stems, not bare words: `taper` alone never matches "tapered", which
#: is how every real plan writes it.
_CRAFT = re.compile(
r"\b(bevel\w*|chamfer\w*|fillet\w*|round(?:ed)?[- ](?:edge|corner|over)\w*|bullnose\w*|taper\w*|groove\w*"
r"|flute\w*|thread(?:ed|s)?|helix|helical|spline\w*|loft\w*|revolv\w*|extrud\w*|bezier|swept|sweep\w*"
r"|profile[ds]?|inset\w*|boolean\w*|subdivi\w*|smooth[- ]shad\w*|array\w*|lattice\w*|slot(?:s|ted)?"
r"|notch\w*|ribs?|louvre\w*|louver\w*|knurl\w*|serrat\w*|scallop\w*|hollow\w*|shell(?:ed)?|cut-?out\w*"
r"|recess\w*|emboss\w*|moulding\w*|molding\w*|curv\w*|arc\b|arch\w*|spiral\w*|dome[ds]?|domed|ogee"
r"|scroll\w*|pierc\w*|perforat\w*|crown\w*|swage\w*|bulg\w*|waist\w*|concave|convex|rebate[ds]?|dovetail\w*"
r"|mortise\w*|tenon\w*|splay\w*|conical|tapering|beading|reeded|turned|rounded|radius|radii)\b"
r"|\br\s*=\s*\d",
re.I)
_COUNTED = re.compile(
r"\b\d+\s*(x|×)?\s*(slats?|spokes?|teeth|dentils?|panes?|rafters?|bolts?|screws?|rivets?|holes?|segments?"
r"|facets?|ribs?|flutes?|turns?|steps?|rings?|wires?|bars?|louvres?|louvers?|vents?|grooves?|studs?|pads?)\b",
re.I)
_GFX_CRAFT = re.compile(
r"\b(fbm|noise|hash|sdf|raymarch|ray[- ]?march|march|domain[- ]?warp|voronoi|worley|curl|advect|feedback"
r"|parallax|refract|reflect|fresnel|bokeh|blur|bloom|vignette|aberration|tonemap|gamma|dither|grain"
r"|particle|instanc|scatter|caustic|godray|god[- ]ray|volumetric|shadow|ao\b|ambient occlusion|palette"
r"|gradient|dissolve|erosion|turbulen|flow[- ]?map|displac|tessell|subsurface|halftone|posteris|posteriz)\b",
re.I)
_NUMBER = re.compile(r"\d+(?:\.\d+)?")
def has_real_detail(text: str) -> bool:
"""True when a part description says something a box cannot say."""
return bool(_CRAFT.search(text) or _COUNTED.search(text))
def has_pass_detail(text: str) -> bool:
"""True when a graphics pass description names a technique or carries a recipe."""
return bool(_GFX_CRAFT.search(text)) or len(_NUMBER.findall(text)) >= 2
@dataclass(frozen=True)
class PlanBudget:
"""What this request is worth, in plan units (parts, or passes for graphics)."""
target_parts: int
min_parts: int
cap_parts: int
min_detail_parts: int
min_assemblies: int
reason: str = ""
evidence: bool = False
def as_dict(self) -> dict[str, int | str | bool]:
return {"target_parts": self.target_parts, "min_parts": self.min_parts, "cap_parts": self.cap_parts,
"min_detail_parts": self.min_detail_parts, "min_assemblies": self.min_assemblies,
"budget_evidence": self.evidence, "reason": self.reason}
def plan_budget(spec: Spec) -> PlanBudget:
"""Derive the plan's size budget from the REQUEST, not from a constant."""
n_must = len(spec.constraints.must_have)
if spec.track is Track.GRAPHICS:
target = max(GRAPHICS_MIN, min(GRAPHICS_CAP, GRAPHICS_MIN + (n_must + 1) // 3))
return PlanBudget(target_parts=target, min_parts=max(GRAPHICS_MIN, target - 1), cap_parts=GRAPHICS_CAP,
min_detail_parts=max(1, target - 1), min_assemblies=0,
reason=f"{n_must} checklist items" if n_must else "no checklist",
evidence=n_must >= EVIDENCE_MIN_CHECKLIST)
cap = PART_CAP.get(spec.language.value, DEFAULT_PART_CAP)
want = n_must
target = max(MIN_PARTS, min(cap, want))
floor = max(2, int(round(0.85 * min(cap, want))))
return PlanBudget(
target_parts=target, min_parts=floor, cap_parts=cap,
min_detail_parts=min(floor, max(2, int(round(0.35 * target)))),
min_assemblies=1 if target >= 10 else 0,
reason=f"{n_must} checklist items" if n_must else "no checklist",
evidence=n_must >= EVIDENCE_MIN_CHECKLIST,
)
def plan_quality_complaints(plan_obj: Any, budget: PlanBudget, *, unit: str = "parts") -> tuple[list[str], list[str]]:
"""``(hard, soft)`` complaints about a VALID plan: hard ones fail the check, soft ones are warnings."""
parts: list[Any] = list(getattr(plan_obj, "parts", None) or getattr(plan_obj, "passes", None) or [])
if not parts:
return [], []
nest = "elements" if unit == "passes" else "children"
hard: list[str] = []
soft: list[str] = []
if budget.evidence and len(parts) < budget.min_parts:
hard.append(
f"Only {len(parts)} {unit} for a request that needs at least {budget.min_parts} "
f"({budget.reason}). Split the ones that are really assemblies and add the features you skipped — "
f"do NOT pad with duplicates.")
detector = has_pass_detail if unit == "passes" else has_real_detail
detailed = [p for p in parts if detector(f"{p.description} {getattr(p, 'detail_hint', '')}")
or getattr(p, "children", None) or getattr(p, "elements", None)]
if len(detailed) < budget.min_detail_parts:
plain = [p.name for p in parts if p not in detailed][:8]
# enforced only on EVIDENCE (a long checklist): without it the request never said the object has
# shaping a primitive cannot express — "a stool" may be four boxes
(hard if budget.evidence else soft).append(
f"This plan is boxes at different sizes: only {len(detailed)} of {len(parts)} {unit} describe anything a "
f"plain primitive cannot express, and this request needs at least {budget.min_detail_parts}. Rewrite "
f"{', '.join(plain)} where the real thing has it: a profile, a stated radius or edge "
f"treatment, a counted repeat, or the sub-shapes it is actually made of.")
if budget.min_assemblies:
n_nested = sum(1 for p in parts if getattr(p, nest, None))
if n_nested < budget.min_assemblies:
soft.append(
f"{n_nested} of the {unit} use `{nest}`, but this request has at least {budget.min_assemblies} real "
f"sub-assemblies. Give each of them its `{nest}`" +
("" if unit == "passes" else " with their own bboxes (inside the parent's) and materials") +
f"; leave the simple {unit} alone.")
materials = {(getattr(p, "material", "") or "").strip().lower() for p in parts} - {""}
if unit == "parts" and len(parts) >= 5 and len(materials) <= 1:
soft.append("Every part has the same material (or none). Real objects mix materials — give each part its "
"own material with a colour.")
return hard, soft
# ===================================================================== deterministic checks on the raw plan
_PLACEHOLDERS = {"string", "str", "name", "text", "..."}
def schema_echo(raw: dict[str, Any]) -> str:
""""" or what in ``raw`` is a JSON-schema placeholder (``"name": "string"``) rather than content."""
bad: list[str] = []
if str(raw.get("object_name", "")).strip().lower() in _PLACEHOLDERS:
bad.append("object_name")
for key in ("parts", "joints", "zones", "assets", "passes"):
for i, item in enumerate(raw.get(key) or []):
if isinstance(item, dict) and str(item.get("name", "")).strip().lower() in _PLACEHOLDERS:
bad.append(f"{key}[{i}].name")
return ", ".join(bad[:6])
def missing_link_names(raw: Any) -> list[str]:
"""Link names the joints reference that ``parts`` does not define (snake-compared)."""
if not isinstance(raw, dict):
return []
parts = raw.get("parts")
joints = raw.get("joints")
if not isinstance(parts, list) or not isinstance(joints, list):
return []
known = {to_snake(str(p.get("name", ""))) for p in parts if isinstance(p, dict)}
known |= {to_snake(str(c.get("name", ""))) for p in parts if isinstance(p, dict)
for c in (p.get("children") or []) if isinstance(c, dict)}
missing: list[str] = []
for j in joints:
if not isinstance(j, dict):
continue
for side in ("parent", "child"):
name = str(j.get(side, "")).strip()
if name and to_snake(name) not in known and name not in missing:
missing.append(name)
return missing
def fixed_part_clash(plan_obj: BaseModel, spec: Spec) -> str:
"""'' unless the plan lists one of the spec's fixed parts (``Spec.fixed_parts``) as a part of its own: the
project builds those, so a planned one invites the agent to author it."""
fixed = {to_snake(f.name): f for f in spec.fixed_parts if f.name}
if not fixed:
return ""
names = [p.name for p in getattr(plan_obj, "parts", None) or []]
hits = [n for n in names if to_snake(n) in fixed]
if not hits:
return ""
return (f"the plan lists fixed parts {hits} as its own parts: they are given by the project (FIXED PARTS) — "
"remove them from the plan and plan only the parts around them")
def asset_kind_errors(raw: Any, language: Language) -> list[str]:
"""Scene assets whose ``kind`` is not one this scene language builds (``SCENE_ASSET_KINDS``)."""
kinds = SCENE_ASSET_KINDS.get(language.value)
if not kinds or not isinstance(raw, dict):
return []
out = []
for i, a in enumerate(raw.get("assets") or []):
if isinstance(a, dict) and a.get("kind") not in kinds:
out.append(f"assets[{i}].kind: {a.get('kind')!r} is not one of {list(kinds)} for {language.value}")
return out
def validation_errors(e: ValidationError) -> list[str]:
"""One ``path: message`` line per pydantic error."""
out = []
for err in e.errors():
path = ".".join(str(p) for p in err.get("loc", ())) or "(root)"
out.append(f"{path}: {err.get('msg', '')}")
return out
# ===================================================================== normalisation
def _fold_pass(ps: Any) -> None:
"""Fold a graphics pass's ``elements`` + ``detail_hint`` into its ``description``."""
if not (ps.elements or ps.detail_hint) or " · " in ps.description:
return
bits = [ps.description.rstrip().rstrip(".")]
if ps.elements:
bits.append("draws: " + " · ".join(e.strip() for e in ps.elements))
if ps.detail_hint:
bits.append(f"what makes it real: {ps.detail_hint.strip()}")
ps.description = " · ".join(bits).replace("\n", " ").replace("|", "/")
def add_acceptance_item(items: list[AcceptanceItem], prefix: str, text: str, how: str, *,
priority: str = "must") -> bool:
"""Append a derived acceptance item (*must* unless told otherwise) unless an equal text exists."""
if text.strip().lower() in {a.text.strip().lower() for a in items}:
return False
ids = {a.id for a in items}
n = 1
while f"{prefix}{n}" in ids:
n += 1
items.append(AcceptanceItem(id=f"{prefix}{n}", text=text, how=how, priority=priority)) # type: ignore[arg-type]
return True
def ensure_acceptance(plan_obj: Any, spec: Spec) -> list[str]:
"""Append the acceptance items the spec constraints imply; returns the ids added."""
items: list[AcceptanceItem] = list(plan_obj.acceptance)
before = {a.id for a in items}
if spec.track is Track.SCENE:
items = [a if a.priority == "should" else a.model_copy(update={"priority": "should"}) for a in items]
c = spec.constraints
solid = spec.track is not Track.GRAPHICS
if solid and c.dimensions_m:
dims = ", ".join(f"{k} = {v:.3f} m" for k, v in c.dimensions_m.items())
add_acceptance_item(items, "dim", f"Overall dimensions match the request within 5%: {dims}", "measure")
for m in c.must_have:
add_acceptance_item(items, "must", f"Includes: {m}", "visual")
for m in c.must_not:
add_acceptance_item(items, "not", f"Does NOT include: {m}", "visual")
if not solid:
planned_motion = getattr(plan_obj, "motion", "").strip()
if planned_motion and not any(w in a.text.lower() for a in items for w in ("static", "motion", "change over time")):
add_acceptance_item(items, "motion", "Frames change over time as planned (not a static image)", "probe")
elif spec.track is not Track.SCENE and not any(a.how == "measure" for a in items):
add_acceptance_item(items, "ground", "Object stands on the ground plane (lowest point at up=0) with its footprint centred", "measure")
items.extend(articulation_acceptance(plan_obj, items))
plan_obj.acceptance = items
return [a.id for a in items if a.id not in before]
def articulation_acceptance(plan_obj: Any, items: list[AcceptanceItem]) -> list[AcceptanceItem]:
"""One ``articulation`` item per moving joint the plan's own checklist does not cover."""
joints = [j for j in (getattr(plan_obj, "joints", None) or []) if j.type != "fixed"]
if not joints:
return []
covered = " ".join(a.text.lower() for a in items if a.how == "articulation")
words = set(re.findall(r"[a-z0-9]+", covered.replace("_", " ")))
out: list[AcceptanceItem] = []
for j in joints:
# whole-word match on the joint's or the child's name ("lid" must not match "slides")
keys = {j.name.lower(), to_snake(j.child).replace("_", " "), j.child.lower()}
if any(k and all(w in words for w in re.findall(r"[a-z0-9]+", k)) for k in keys):
continue
unit = "m" if j.type == "prismatic" else "rad"
rest = "closed / stowed" if abs(j.rest) < 1e-9 else f"at {j.rest:.2f} {unit}"
rng = "turns freely" if j.type == "continuous" else f"moves over [{j.lower:.2f}, {j.upper:.2f}] {unit}"
out.append(AcceptanceItem(
id=f"art_{to_snake(j.child)}"[:40], how="articulation", priority="should",
text=f"Joint {j.name}: at rest {j.child} sits {rest} against {j.parent}; it {rng} — {j.motion} — "
f"without passing through {j.parent} or any other link (pose_* views)"))
return out
def normalise_names(plan_obj: Any) -> None:
"""PascalCase part/link/zone/asset names in place."""
for attr in ("parts", "zones", "assets"):
for item in getattr(plan_obj, attr, None) or []:
item.name = to_pascal(item.name)
if getattr(item, "attach_to", None):
item.attach_to = to_pascal(item.attach_to)
for z in getattr(plan_obj, "zones", None) or []:
z.contents = [to_pascal(c) for c in z.contents]
if hasattr(plan_obj, "root_link"):
plan_obj.root_link = to_pascal(plan_obj.root_link)
for j in plan_obj.joints:
j.parent, j.child = to_pascal(j.parent), to_pascal(j.child)
def normalise_plan(plan_obj: Any, spec: Spec) -> list[str]:
"""Every normalisation an accepted plan gets, as human lines (``[]`` when nothing changed)."""
notes: list[str] = list(getattr(plan_obj, "normalisations", None) or [])
before = [p.name for p in getattr(plan_obj, "parts", None) or []]
normalise_names(plan_obj)
after = [p.name for p in getattr(plan_obj, "parts", None) or []]
renamed = [f"{a} → {b}" for a, b in zip(before, after, strict=True) if a != b]
if renamed:
notes.append("part names made PascalCase: " + ", ".join(renamed[:8]))
for ps in getattr(plan_obj, "passes", None) or []:
_fold_pass(ps)
added = ensure_acceptance(plan_obj, spec)
if added:
notes.append("acceptance items added from the spec: " + ", ".join(added))
return notes