Official Codebase of 3DCodeVerse
Python
scene: hierarchical zone layouts — an L2 zone director places, the builder realises
gaoypengf7a0c091da17
diff --git a/harness/codeverse/contracts/plan.py b/harness/codeverse/contracts/plan.pyindex 52bc3625..92ddea89 100644--- a/harness/codeverse/contracts/plan.py+++ b/harness/codeverse/contracts/plan.py@@ -511,6 +511,38 @@ class ScenePlan(BaseModel):return self+class ZonePlacement(BaseModel):+ """One asset's placement inside a zone, decided by the L2 zone director.++ Typed rows with concrete numbers on purpose (the RefDimension lesson: an+ open-ended dict maps to a property-less schema and the model answers ``{}``)."""++ asset: str = Field(description="asset name from the plan")+ count: int = Field(ge=1, description="how many instances in this zone")+ cluster: tuple[float, float] = Field(description="cluster centre (x, z) in WORLD meters, inside the zone bbox")+ spread_m: float = Field(ge=0, description="radius the instances scatter within (0 = exactly at the centre)")+ faces: str = Field(default="", description="what the instances face, e.g. 'the path', 'azimuth 220'")+ support: str = Field(default="ground", description="'ground' or the asset they stand on")+++class ZoneLayout(BaseModel):+ """The L2 layout for ONE zone: where its planned contents actually go.++ Produced by a cheap structured call per zone (parallel, never an agent),+ validated deterministically against the zone bbox and the plan before it is+ handed to the zone builder — the builder realises a layout instead of+ inventing one."""++ zone: str = Field(description="the zone's name, exactly as planned")+ placements: list[ZonePlacement] = Field(default_factory=list)+ path_points: list[tuple[float, float]] = Field(+ default_factory=list, description="(x, z) polyline of the walkway through this zone, if any")+ mid_props: int = Field(default=0, ge=0, description="loose mid props (0.3-1.5 m) beyond the placements")+ small_props: int = Field(default=0, ge=0, description="small props (< 0.3 m)")+ ground_cover: int = Field(default=0, ge=0, description="instanced tufts / pebbles")+ notes: str = Field(default="", description="one line of layout intent, e.g. 'stalls face the lane'")++class RefDimension(BaseModel):"""One reference dimension of the real object. A LIST of typed rows, not a free``dict[str, float]``: an open-ended object maps to a property-less ``{"type":diff --git a/harness/codeverse/prompts/tracks/plan_zone_layout.j2 b/harness/codeverse/prompts/tracks/plan_zone_layout.j2new file mode 100644index 00000000..fde23d74--- /dev/null+++ b/harness/codeverse/prompts/tracks/plan_zone_layout.j2@@ -0,0 +1,31 @@+You are the ZONE DIRECTOR for one zone of `{{ title }}`. The scene director already fixed the+world ({{ setting }} — mood: {{ mood }}); a builder model will realise YOUR layout verbatim, so+answer with exact numbers, all in WORLD meters, and nothing outside the JSON.++Environment (for light/path context only — do not restate it):+{{ environment }}++## The zone+- Name: {{ zone.name }}+- Bbox: x {{ '%.1f'|format(zone.bbox.min[0]) }}..{{ '%.1f'|format(zone.bbox.max[0]) }}, z {{ '%.1f'|format(zone.bbox.min[2]) }}..{{ '%.1f'|format(zone.bbox.max[2]) }} — every cluster centre stays INSIDE it.+- Description (binding, including its density counts): {{ zone.description }}++Neighbouring zones (do not place into them):+{% for n in neighbours %}- {{ n }}+{% endfor %}++## Assets to place (measured sizes)+{% for a in assets %}- {{ a }}+{% endfor %}++WHAT TO PRODUCE (JSON, fields: {{ schema_fields }}):+- `placements` — one row per contents asset (split an asset into 2-3 rows when it appears in+ distinct spots): `count`, `cluster` (x, z), `spread_m`, `faces` (what they look at — a path,+ a doorway, an azimuth), `support` (`ground`, or the asset they stand ON, e.g. bottles on a+ counter). Compose PICTURES, not scatter: things line paths and edges, face what they serve,+ stand in clusters with breathing room for the cameras. Respect each asset's footprint — two+ clusters closer than the assets are wide will interpenetrate.+- `path_points` — the walkway through this zone as 2-4 (x, z) points, if the description has one.+- `mid_props`, `small_props`, `ground_cover` — the dressing counts the description demands+ beyond the placements (the builder invents WHAT they are; you fix HOW MANY).+- `notes` — one line of intent the builder must keep, e.g. "stalls face the lane, gap at the gate".diff --git a/harness/codeverse/prompts/tracks/scene_zone.j2 b/harness/codeverse/prompts/tracks/scene_zone.j2index 3f014a54..e193e925 100644--- a/harness/codeverse/prompts/tracks/scene_zone.j2+++ b/harness/codeverse/prompts/tracks/scene_zone.j2@@ -7,7 +7,10 @@ Scene: {{ spec_prompt }} · Setting: {{ setting }} · Mood: {{ mood }}- Bbox: {{ zone_bbox }} — place EVERYTHING inside it (x/z), on the ground via `heightAt`.- Contents (asset names to place): {{ zone_contents | join(', ') if zone_contents else '(none — build local detail from primitives)' }}-Neighbouring zones (do not build into them):+{% if layout is defined and layout %}## Zone director's layout (realise EXACTLY these placements; positions are world meters)+{{ layout }}++{% endif %}Neighbouring zones (do not build into them):{% for n in neighbours %}- {{ n }}{% endfor %}diff --git a/harness/codeverse/tracks/scene.py b/harness/codeverse/tracks/scene.pyindex 22913586..d264ff85 100644--- a/harness/codeverse/tracks/scene.py+++ b/harness/codeverse/tracks/scene.py@@ -65,6 +65,7 @@ from codeverse.tracks.scene_assets import (select_assets,single_shot_ctx,)+from codeverse.tracks.zone_layout import layout_block, layout_zonesfrom codeverse.workspace import Workspacelog = logging.getLogger(__name__)@@ -199,8 +200,23 @@ class SceneTrack(BaseTrack):# (each measured at ~+0.13). Workspace.commit serialises under its own lock,# so the two stages' commits cannot race. One cached stage keeps resume# atomic: both results or neither.+ def _layouts() -> dict[str, Any]:+ """L2 zone layouts (optional accelerator): planner-model calls, never fatal."""+ try:+ model = self._planner_model+ if model is None:+ from codeverse.models import get_chat_model++ model = get_chat_model(ctx.spec.backends.planner)+ layouts = layout_zones(plan, model, budget=ctx.budget, events=ctx.events)+ return {k: v.model_dump(mode="json") for k, v in layouts.items()}+ except Exception as e: # noqa: BLE001 — layouts accelerate, they must never kill+ ctx.events.emit("layout.stage_failed", error=f"{type(e).__name__}: {e}"[:300])+ return {}+def _assets_and_env() -> dict[str, Any]:- thunks = {"assets": lambda: run_asset_stage(ctx), "env": lambda: self._env_stage(ctx)}+ thunks = {"assets": lambda: run_asset_stage(ctx), "env": lambda: self._env_stage(ctx),+ "layouts": _layouts}results = fan_out(list(thunks.items()), lambda kv: kv[1](), max_workers=2,label="assets+env", item_name=lambda kv: kv[0])out: dict[str, Any] = {}@@ -213,12 +229,14 @@ class SceneTrack(BaseTrack):ctx.events.emit("stage.failed", stage=name, error=f"{type(r).__name__}: {r}")else:out[name] = {k: v.model_dump(mode="json") for k, v in r.items()} if name == "assets" else r+ out.setdefault("layouts", {})if first_exc is not None:raise first_excreturn outboth = runner.stage("assets+env", _assets_and_env,inputs={"assets": plan.assets, "plan_env": plan.environment,- "setting": plan.setting, "agent": ctx.agent_id})+ "setting": plan.setting, "zones": plan.zones, "agent": ctx.agent_id})+ ctx.extra["layouts"] = (both or {}).get("layouts") or {}assets = {k: AssetResult.model_validate(v) if isinstance(v, dict) else vfor k, v in ((both or {}).get("assets") or {}).items()}# the merge map is a pure function of the plan, so a RESUMED run (cached asset@@ -354,7 +372,8 @@ class SceneTrack(BaseTrack):# a batched session reads ONE copy of the recipes (they are identical per zone)briefs.append(render("tracks/scene_zone.j2", **self._ctx(ctx, recipes=recipes if i == 0 else "", zone_name=zone.name, zone_description=zone.description,zone_bbox=bbox_line(zone.bbox), zone_contents=zone.contents,- zone_file=zone_file(zone), neighbours=neighbours)))+ zone_file=zone_file(zone), neighbours=neighbours,+ layout=layout_block(ctx.extra.get("layouts", {}).get(zone.name)))))ctx.record_prompt("scene_zone", briefs[0])if len(batch) == 1:prompt, label = briefs[0], f"zone_{to_snake(names[0])}"diff --git a/harness/codeverse/tracks/zone_layout.py b/harness/codeverse/tracks/zone_layout.pynew file mode 100644index 00000000..5e6d31a4--- /dev/null+++ b/harness/codeverse/tracks/zone_layout.py@@ -0,0 +1,136 @@+"""L2 zone layouts: one cheap structured call per zone, in parallel, validated.++Why this layer exists (measured 2026-08-30 across the 48 scored scene runs):+``ZonePlan.contents`` is a list of NAMES — the zone agent freehand-places+everything, and the final rounds still carried 55 interpenetration, 38 sunken+and 22 floating gate ERRORS, with undressed_scene standing in 31/48 verdicts.+The layout is planning work, so it is done by the PLANNER model with a schema+(never a coding agent), validated deterministically against the zone bbox and+the plan, re-asked once with the exact complaint, and handed to the zone+builder as numbers to realise.++Layouts are an optional accelerator like the engineering brief: any failure+returns no layout for that zone and generation proceeds exactly as before.+"""++from __future__ import annotations++import logging+from typing import Any++from codeverse.contracts.chat import ChatMessage, ChatRequest+from codeverse.contracts.plan import ScenePlan, ZoneLayout, ZonePlan+from codeverse.conventions import to_snake+from codeverse.models.schema_utils import parse_json_lenient+from codeverse.proc import fan_out+from codeverse.prompts import render++log = logging.getLogger(__name__)++LAYOUT_TEMPLATE = "tracks/plan_zone_layout.j2"+LAYOUT_MAX_TOKENS = 4000+LAYOUT_WAIT_S = 300.0+#: a placement may multiply the plan's instances_hint by at most this much+COUNT_SLACK = 4+#: cluster centres may sit this far outside the zone bbox (assets have radius)+BBOX_MARGIN_M = 1.0+++def validate_layout(layout: ZoneLayout, zone: ZonePlan, plan: ScenePlan) -> str:+ """"" when the layout is buildable; otherwise the exact complaint to re-ask with."""+ problems: list[str] = []+ known = {to_snake(a.name): a for a in plan.assets}+ hints = {to_snake(a.name): max(1, a.instances_hint) for a in plan.assets}+ lo, hi = zone.bbox.min, zone.bbox.max+ for p in layout.placements:+ k = to_snake(p.asset)+ if k not in known:+ problems.append(f"placement names unknown asset '{p.asset}' (plan assets: {', '.join(sorted(known))})")+ continue+ x, z = p.cluster+ if not (lo[0] - BBOX_MARGIN_M <= x <= hi[0] + BBOX_MARGIN_M and lo[2] - BBOX_MARGIN_M <= z <= hi[2] + BBOX_MARGIN_M):+ problems.append(f"{p.asset} cluster ({x:.1f}, {z:.1f}) is outside zone {zone.name} bbox "+ f"x {lo[0]:.1f}..{hi[0]:.1f}, z {lo[2]:.1f}..{hi[2]:.1f}")+ if p.count > COUNT_SLACK * hints[k]:+ problems.append(f"{p.asset} count {p.count} is over {COUNT_SLACK}x the plan's instances_hint {hints[k]}")+ placed = {to_snake(p.asset) for p in layout.placements}+ missing = [c for c in zone.contents if to_snake(c) not in placed]+ if missing:+ problems.append(f"no placement for planned contents: {', '.join(missing)}")+ return "; ".join(problems)+++def layout_block(layout: ZoneLayout | dict[str, Any] | None) -> str:+ """The prompt table a zone builder realises (`""` when there is no layout)."""+ if layout is None:+ return ""+ lay = layout if isinstance(layout, ZoneLayout) else ZoneLayout.model_validate(layout)+ lines = []+ for p in lay.placements:+ faces = f", facing {p.faces}" if p.faces else ""+ support = f", on {p.support}" if p.support and p.support != "ground" else ""+ lines.append(f"- {p.count}x {p.asset} around ({p.cluster[0]:.1f}, {p.cluster[1]:.1f}) "+ f"spread {p.spread_m:.1f} m{faces}{support}")+ if lay.path_points:+ pts = " -> ".join(f"({x:.1f}, {z:.1f})" for x, z in lay.path_points)+ lines.append(f"- path polyline: {pts}")+ dress = [f"{n} {label}" for n, label in ((lay.mid_props, "mid props"), (lay.small_props, "small props"),+ (lay.ground_cover, "ground-cover instances")) if n]+ if dress:+ lines.append("- dressing beyond the placements: " + ", ".join(dress))+ if lay.notes:+ lines.append(f"- intent: {lay.notes}")+ return "\n".join(lines)+++def _one_layout(zone: ZonePlan, plan: ScenePlan, model: Any, budget: Any, events: Any) -> ZoneLayout | None:+ neighbours = [f"{z.name}: x {z.bbox.min[0]:.0f}..{z.bbox.max[0]:.0f}, z {z.bbox.min[2]:.0f}..{z.bbox.max[2]:.0f}"+ for z in plan.zones if z.name != zone.name]+ assets = [f"{a.name}: {a.approx_size_m[0]:g}x{a.approx_size_m[1]:g}x{a.approx_size_m[2]:g} m, ~{a.instances_hint} planned"+ for a in plan.assets if to_snake(a.name) in {to_snake(c) for c in zone.contents}] or ["(no planned assets — dressing only)"]+ system = render(LAYOUT_TEMPLATE, title=plan.title, setting=plan.setting, mood=plan.mood,+ environment=plan.environment[:600], zone=zone, neighbours=neighbours, assets=assets,+ schema_fields=", ".join(ZoneLayout.model_fields))+ user = f"Lay out zone {zone.name}. Description (binding): {zone.description}\nContents to place: {', '.join(zone.contents) or '(none)'}"+ complaint = ""+ for attempt in (0, 1):+ ask = user if not complaint else f"{user}\n\nYour previous layout was rejected: {complaint}. Fix exactly these problems."+ resp = model.generate(ChatRequest(messages=[ChatMessage.user(ask)], system=system,+ response_schema=ZoneLayout.model_json_schema(), temperature=0.3,+ thinking="low", max_output_tokens=LAYOUT_MAX_TOKENS,+ max_wait_s=LAYOUT_WAIT_S, label="zone-layout"))+ if budget is not None:+ budget.add(resp.usage, stage="plan")+ raw = resp.parsed if resp.parsed is not None else parse_json_lenient(resp.text or "{}")+ layout = ZoneLayout.model_validate(raw)+ layout.zone = zone.name # the name is an input, never model-invented+ complaint = validate_layout(layout, zone, plan)+ if not complaint:+ if events is not None:+ events.emit("layout.done", zone=zone.name, placements=len(layout.placements), reasked=bool(attempt))+ return layout+ if events is not None:+ events.emit("layout.rejected", zone=zone.name, complaint=complaint[:300])+ log.warning("zone layout for %s rejected twice (%s); building without one", zone.name, complaint)+ return None+++def layout_zones(plan: ScenePlan, model: Any, *, budget: Any = None, events: Any = None,+ max_workers: int = 6) -> dict[str, ZoneLayout]:+ """One validated layout per zone, computed in parallel. Failures drop out silently+ (an exception or double rejection yields no layout for that zone, never a dead run)."""++ def _safe(zone: ZonePlan) -> ZoneLayout | None:+ return _one_layout(zone, plan, model, budget, events)++ results = fan_out(list(plan.zones), _safe, max_workers=max_workers, label="layouts",+ item_name=lambda z: z.name)+ out: dict[str, ZoneLayout] = {}+ for zone, r in zip(plan.zones, results, strict=True):+ if isinstance(r, Exception):+ if events is not None:+ events.emit("layout.failed", zone=zone.name, error=f"{type(r).__name__}: {r}"[:300])+ log.warning("zone layout for %s failed (%s); building without one", zone.name, r)+ elif r is not None:+ out[zone.name] = r+ return outdiff --git a/harness/tests/orchestrator_tracks/test_zone_layout.py b/harness/tests/orchestrator_tracks/test_zone_layout.pynew file mode 100644index 00000000..b87a7873--- /dev/null+++ b/harness/tests/orchestrator_tracks/test_zone_layout.py@@ -0,0 +1,83 @@+"""L2 zone layouts: validator complaints, prompt table, parallel calls with one re-ask."""++from __future__ import annotations++from types import SimpleNamespace++from codeverse.contracts.plan import AssetPlan, BBox, CameraPlan, ScenePlan, ZoneLayout, ZonePlan+from codeverse.tracks.zone_layout import layout_block, layout_zones, validate_layout+++def _plan() -> ScenePlan:+ return ScenePlan(+ title="t", summary="s", setting="harbour, dusk", mood="calm",+ bounds=BBox(center=(0, 0, 0), extents=(60, 10, 60)), environment="sky 0x223250",+ zones=[ZonePlan(name="Quay", description="12 mid props", bbox=BBox(center=(-10, 0, 0), extents=(20, 8, 20)),+ contents=["Bollard", "FishingBoat"]),+ ZonePlan(name="Market", description="stalls", bbox=BBox(center=(10, 0, 0), extents=(20, 8, 20)),+ contents=["Stall"])],+ assets=[AssetPlan(name="Bollard", kind="threejs", description="d", approx_size_m=(0.3, 0.8, 0.3), instances_hint=6),+ AssetPlan(name="FishingBoat", kind="threejs", description="d", approx_size_m=(6, 2.5, 2), instances_hint=2),+ AssetPlan(name="Stall", kind="threejs", description="d", approx_size_m=(3, 2.5, 2), instances_hint=4)],+ cameras=[CameraPlan(name="overview", position=(1, 1, 1), look_at=(0, 0, 0), fov=50, purpose="p")])+++def _layout(**over) -> ZoneLayout:+ base = {"zone": "Quay",+ "placements": [{"asset": "Bollard", "count": 6, "cluster": (-12.0, 3.0), "spread_m": 4.0},+ {"asset": "FishingBoat", "count": 2, "cluster": (-8.0, -5.0), "spread_m": 2.0}]}+ base.update(over)+ return ZoneLayout.model_validate(base)+++def test_validator_accepts_a_buildable_layout_and_names_every_problem():+ plan = _plan()+ assert validate_layout(_layout(), plan.zones[0], plan) == ""+ bad = _layout(placements=[{"asset": "Kraken", "count": 1, "cluster": (-12.0, 3.0), "spread_m": 1.0},+ {"asset": "Bollard", "count": 99, "cluster": (55.0, 3.0), "spread_m": 1.0}])+ complaint = validate_layout(bad, plan.zones[0], plan)+ assert "unknown asset 'Kraken'" in complaint+ assert "outside zone Quay bbox" in complaint+ assert "count 99" in complaint+ assert "no placement for planned contents: FishingBoat" in complaint+++def test_layout_block_renders_numbers_the_builder_can_follow():+ text = layout_block(_layout(path_points=[(-18.0, 0.0), (-2.0, 4.0)], mid_props=12, ground_cover=400,+ notes="boats face the quay"))+ assert "6x Bollard around (-12.0, 3.0) spread 4.0 m" in text+ assert "path polyline: (-18.0, 0.0) -> (-2.0, 4.0)" in text+ assert "12 mid props" in text and "400 ground-cover" in text and "boats face the quay" in text+ assert layout_block(None) == ""+++class _Model:+ """Scripted planner: first answer per zone from the queue, then valid ones."""++ def __init__(self, answers):+ self.answers = list(answers)+ self.calls = 0++ def generate(self, req):+ self.calls += 1+ return SimpleNamespace(parsed=self.answers.pop(0), text="", usage=None)+++def test_layout_zones_runs_per_zone_and_reasks_once_with_the_complaint():+ plan = _plan()+ good_quay = _layout().model_dump(mode="json")+ bad_quay = _layout(placements=[{"asset": "Kraken", "count": 1, "cluster": (0.0, 0.0), "spread_m": 1.0}]).model_dump(mode="json")+ good_market = {"zone": "Market", "placements": [{"asset": "Stall", "count": 4, "cluster": (10.0, 0.0), "spread_m": 5.0}]}+ # zones fan out with max_workers=1 so the scripted queue stays ordered+ model = _Model([bad_quay, good_quay, good_market])+ out = layout_zones(plan, model, max_workers=1)+ assert set(out) == {"Quay", "Market"} and model.calls == 3+ assert out["Quay"].placements[0].asset == "Bollard"+++def test_layout_zones_drops_a_twice_rejected_zone_instead_of_dying():+ plan = _plan()+ bad = {"zone": "Quay", "placements": [{"asset": "Kraken", "count": 1, "cluster": (0.0, 0.0), "spread_m": 1.0}]}+ good_market = {"zone": "Market", "placements": [{"asset": "Stall", "count": 4, "cluster": (10.0, 0.0), "spread_m": 5.0}]}+ out = layout_zones(plan, _Model([bad, bad, good_market]), max_workers=1)+ assert set(out) == {"Market"}