Skip to content

Official Codebase of 3DCodeVerse

Python

Review fixes for #33-#36: Embree stays the default ray engine, gate names stated once, fixed parts reach refine/repair

gaoypengddcf853bc00e
diff --git a/eval/bench/run_bench.py b/eval/bench/run_bench.py
index f52e2d9e..c689e11d 100644
--- a/eval/bench/run_bench.py
+++ b/eval/bench/run_bench.py
@@ -30,6 +30,7 @@ import argparse
import csv
import json
import logging
+import shutil
import sys
import traceback
from collections.abc import Callable, Sequence
@@ -375,7 +376,11 @@ def _run_battery(
# was over budget before its first round (measured 2026-08-26: clock_q4 and
# lighthouse_1 came back `budget`, 0 rounds, 60.3 / 76.7 min "elapsed").
# The old tree is kept beside it as <id>.attempt<N>, the way ab_plan does.
- archive_attempt(ws.root)
+ prev = archive_attempt(ws.root)
+ for f in item.fixed_parts: # the project's seeds went with the archived attempt
+ if (prev / f.path).is_file():
+ (ws.root / f.path).parent.mkdir(parents=True, exist_ok=True)
+ shutil.copy2(prev / f.path, ws.root / f.path)
resume = ws.exists()
if not resume:
ws.create()
diff --git a/harness/codeverse3d/addons/select.py b/harness/codeverse3d/addons/select.py
index ab61c183..dbf405a5 100644
--- a/harness/codeverse3d/addons/select.py
+++ b/harness/codeverse3d/addons/select.py
@@ -13,6 +13,7 @@ from pydantic import BaseModel, Field
from codeverse3d.contracts.common import Usage
from codeverse3d.contracts.run import RoundRecord, RunRecord
+from codeverse3d.contracts.spec import FIXED_PARTS_GATE, PROJECT_GATE_PREFIX
from codeverse3d.cost.context import call_context
from codeverse3d.cost.types import Role, Stage
from codeverse3d.judges.base import judged_subset, resolve_paths
@@ -104,12 +105,6 @@ def round_rows(run_dir: Path | str, *, record: RunRecord | None = None) -> list[
return rows
-#: the gates that measure the project's own truth: its registered checks (tracks/project_checks.py) and its
-#: fixed parts (spatial/contract.py); named here so the pick never imports a track
-PROJECT_GATE_PREFIX = "project:"
-FIXED_PARTS_GATE = "contract_fixed"
-
-
def is_project_gate(name: str) -> bool:
"""A gate that measures the project's own truth: its registered checks (``project:*``) or its fixed parts."""
return name.startswith(PROJECT_GATE_PREFIX) or name == FIXED_PARTS_GATE
@@ -141,7 +136,8 @@ def pick(run_dir: Path | str, *, by: PickBy = "score", pairwise_model: str | Non
if not ranked:
return None
top = ranked[0]
- if by != "pairwise" or len(ranked) < 2 or (top.score or 0.0) - (ranked[1].score or 0.0) > PAIRWISE_MARGIN:
+ if (by != "pairwise" or len(ranked) < 2 or (ranked[1].project_errors > 0) != (top.project_errors > 0)
+ or (top.score or 0.0) - (ranked[1].score or 0.0) > PAIRWISE_MARGIN):
return top.index
note = pairwise_verdict(Workspace(run_dir), rec, top.index, ranked[1].index,
model=pairwise_model or rec.spec.backends.judge, judge=judge)
diff --git a/harness/codeverse3d/config.py b/harness/codeverse3d/config.py
index b1f6896f..e4079527 100644
--- a/harness/codeverse3d/config.py
+++ b/harness/codeverse3d/config.py
@@ -247,10 +247,10 @@ class Settings(BaseSettings):
default_captioner: str = Field(default_factory=lambda: Backends().captioner)
default_candidates: int = Field(default=1, description="best-of-N baseline candidates (tracks read it)")
ray_engine: Literal["numpy", "embree"] = Field(
- default="numpy",
- description="ray engine of the deterministic inside tests (connectivity penetration, pose sweep): trimesh's "
- "own ray-triangle intersector, or Embree via embreex when installed. numpy by default: embreex 4 can "
- "segfault on large multi-part GLBs, which kills every parallel run of the process. C3D_RAY_ENGINE.",
+ default="embree",
+ description="ray engine of the deterministic inside tests (connectivity penetration, pose sweep): Embree via "
+ "embreex, or trimesh's own ray-triangle intersector (numpy: ~100x slower, memory grows with rays x "
+ "triangles) for a GLB on which embreex 4 segfaults. C3D_RAY_ENGINE.",
)
model_timeout_s: float = Field(
diff --git a/harness/codeverse3d/contracts/spec.py b/harness/codeverse3d/contracts/spec.py
index 9e373f45..e8abebcf 100644
--- a/harness/codeverse3d/contracts/spec.py
+++ b/harness/codeverse3d/contracts/spec.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import posixpath
from datetime import UTC, datetime
from typing import Any
@@ -43,6 +44,11 @@ class FixedPart(BaseModel):
note: str = Field(default="", description="one line for the planner and the agent")
+#: the gates that measure the project's own truth: Spec.checks report as project:<name>, Spec.fixed_parts as contract_fixed
+PROJECT_GATE_PREFIX = "project:"
+FIXED_PARTS_GATE = "contract_fixed"
+
+
class ProjectCheck(BaseModel):
"""A deterministic check the PROJECT registers (``Spec.checks``): ``entry`` names a function
(``package.module:function``, importable where the harness runs) that measures each round's GLB against
@@ -89,8 +95,11 @@ class Spec(BaseModel):
@model_validator(mode="after")
def _fixed_parts_are_sources(self) -> Spec:
+ if (self.fixed_parts or self.checks) and self.track not in (Track.STATIC_OBJECT, Track.ARTICULATED_OBJECT):
+ raise ValueError(f"fixed_parts and checks are measured on the object tracks only, not {self.track.value}")
for f in self.fixed_parts:
- parts = f.path.replace("\\", "/").split("/")
+ f.path = posixpath.normpath(f.path.replace("\\", "/"))
+ parts = f.path.split("/")
if parts[0] != "src" or ".." in parts or len(parts) < 2:
raise ValueError(f"fixed part {f.path!r}: must be a file under src/")
if (f.bbox_min is None) != (f.bbox_max is None):
diff --git a/harness/codeverse3d/orchestrator.py b/harness/codeverse3d/orchestrator.py
index ab35a872..f6c18def 100644
--- a/harness/codeverse3d/orchestrator.py
+++ b/harness/codeverse3d/orchestrator.py
@@ -20,6 +20,7 @@ from codeverse3d.contracts.artifacts import PLACEHOLDER_PART, GateReport, Judgme
from codeverse3d.contracts.common import Budget
from codeverse3d.contracts.plan import AcceptanceItem, Plan
from codeverse3d.contracts.run import RoundRecord, RunStatus, StepTime
+from codeverse3d.contracts.spec import PROJECT_GATE_PREFIX
from codeverse3d.conventions import split_instance, to_snake
from codeverse3d.cost.tally import timed
from codeverse3d.proc import EventLog
@@ -248,7 +249,8 @@ def build_refine_instructions(
errors.sort(key=lambda gf: gf[1].data.get("kind") != PLACEHOLDER_PART) # stable: placeholders first
for g, f in errors:
_add(RefineTask(target=f.target or "overall", kind=f"gate:{g.gate}", instruction=f.as_line(),
- priority=0, source="gate"), str(f.data.get("kind") or ""))
+ priority=0, source="gate"),
+ str(f.data.get("kind") or (f.message if g.gate.startswith(PROJECT_GATE_PREFIX) else "")))
for t in extra:
_add(t.model_copy())
for a in acceptance_failures:
diff --git a/harness/codeverse3d/prompts/tracks/refine_object.j2 b/harness/codeverse3d/prompts/tracks/refine_object.j2
index 63bb46f0..754b61d1 100644
--- a/harness/codeverse3d/prompts/tracks/refine_object.j2
+++ b/harness/codeverse3d/prompts/tracks/refine_object.j2
@@ -9,6 +9,10 @@ THIS round. Make exactly these changes, keep everything else as it is, and keep
{% endfor %}
Targets: {{ targets | join(', ') }}
+{% if fixed_parts %}
+
+{{ fixed_parts }}
+{% endif %}
{% if edit_only_these %}
Change only these files (shown below) and the entry file; any other existing part file is refused:
{% for f in files %}`{{ f }}`{% if not loop.last %}, {% endif %}{% endfor %}
diff --git a/harness/codeverse3d/prompts/tracks/repair.j2 b/harness/codeverse3d/prompts/tracks/repair.j2
index d9e3fa42..d0a6a306 100644
--- a/harness/codeverse3d/prompts/tracks/repair.j2
+++ b/harness/codeverse3d/prompts/tracks/repair.j2
@@ -5,6 +5,10 @@ material exactly as they are. Do not refactor, do not "simplify" the model, do n
## Error report
{{ error_report }}
+{% if fixed_parts %}
+
+{{ fixed_parts }}
+{% endif %}
{% if repeats > 0 %}
THIS IS THE SAME ERROR AS THE PREVIOUS ATTEMPT ({{ repeats }}× repeated). Your last edit did not
diff --git a/harness/codeverse3d/spatial/contract.py b/harness/codeverse3d/spatial/contract.py
index 168054e3..7749a4cc 100644
--- a/harness/codeverse3d/spatial/contract.py
+++ b/harness/codeverse3d/spatial/contract.py
@@ -17,6 +17,7 @@ from codeverse3d.contracts.artifacts import (
Severity,
)
from codeverse3d.contracts.plan import BBox, PartPlan, Plan, StaticPlan
+from codeverse3d.contracts.spec import FIXED_PARTS_GATE as FIXED_GATE
from codeverse3d.contracts.spec import FixedPart
from codeverse3d.conventions import (
BBOX_TOLERANCE_M,
@@ -340,7 +341,6 @@ def check_contract(measurement: Measurement, plan: StaticPlan, *, language: str,
# --------------------------------------------------------------------------- fixed parts
-FIXED_GATE = "contract_fixed"
#: a fixed part is built by code the agent may not change, so its box must come out as declared: any face of
#: it further than this from the declared box is an ERROR
FIXED_TOL_M = 0.05
diff --git a/harness/codeverse3d/spatial/joints_collide.py b/harness/codeverse3d/spatial/joints_collide.py
index ffcffe58..8b380959 100644
--- a/harness/codeverse3d/spatial/joints_collide.py
+++ b/harness/codeverse3d/spatial/joints_collide.py
@@ -76,13 +76,13 @@ def inside_island(island: trimesh.Trimesh, points: np.ndarray) -> np.ndarray:
def _intersector(mesh: trimesh.Trimesh) -> object:
- """The ray engine of the parity test: trimesh's own ray-triangle intersector, or Embree (``mesh.ray`` when
- embreex is installed) only if ``Settings.ray_engine`` asks for it: a segfault in embreex cannot be caught."""
+ """The ray engine of the parity test: Embree (``mesh.ray``), or trimesh's own intersector under
+ ``C3D_RAY_ENGINE=numpy`` for a GLB on which embreex segfaults (a segfault cannot be caught)."""
from codeverse3d.config import get_settings
- if get_settings().ray_engine == "embree":
- return mesh.ray
- return RayMeshIntersector(mesh)
+ if get_settings().ray_engine == "numpy":
+ return RayMeshIntersector(mesh)
+ return mesh.ray
class LinkBody:
diff --git a/harness/codeverse3d/tracks/project_checks.py b/harness/codeverse3d/tracks/project_checks.py
index ff422a46..8b15b3cd 100644
--- a/harness/codeverse3d/tracks/project_checks.py
+++ b/harness/codeverse3d/tracks/project_checks.py
@@ -21,11 +21,11 @@ from pathlib import Path
from typing import Any, Protocol
from codeverse3d.contracts.artifacts import GateFinding, GateReport, Measurement, Severity
+from codeverse3d.contracts.spec import PROJECT_GATE_PREFIX as PREFIX
from codeverse3d.contracts.spec import ProjectCheck, Spec
log = logging.getLogger(__name__)
-PREFIX = "project:"
class CheckFn(Protocol):
diff --git a/harness/codeverse3d/tracks/prompting.py b/harness/codeverse3d/tracks/prompting.py
index 96b3e045..1a75f495 100644
--- a/harness/codeverse3d/tracks/prompting.py
+++ b/harness/codeverse3d/tracks/prompting.py
@@ -159,6 +159,7 @@ def base_prompt_context(ctx: RunContext, **extra: Any) -> dict[str, Any]:
"output_format": SINGLE_SHOT_OUTPUT if ctx.single_shot else AGENT_OUTPUT_RULES,
"spec_prompt": ctx.spec.prompt,
"constraints": constraints_text(ctx.spec),
+ "fixed_parts": "\n".join(fixed_parts_lines(ctx.spec)),
"object_name": object_name,
"plan_summary": getattr(plan, "summary", "") if plan else "",
"style_notes": getattr(plan, "style_notes", "") if plan else "",
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.md
index e1ed5e7c..b80cd99d 100644
--- a/harness/docs/ARCHITECTURE.md
+++ b/harness/docs/ARCHITECTURE.md
@@ -375,8 +375,8 @@ then max_rounds refine rounds, EACH built on the round before it — a FIXED cou
stop reasons: max_rounds | budget (the wall clock — BudgetGuard / max_minutes) | agent_quota | no_change |
no_refine_tasks | judge_unavailable | failed
finalise: the workspace ENDS AT THE LAST ROUND; finalize_record → record.json. No best round, no deliverable/
-after the run (`3dcodeverse make`, unless --no-pick): addons/select.pick(by="score") — highest effective score, ties →
- fewer gate errors → the earlier round — then package(): deliverable/ + selection.json
+after the run (`3dcodeverse make`, unless --no-pick): addons/select.pick(by="score") — rounds without a project:* /
+ contract_fixed ERROR first, then highest effective score, ties → fewer gate errors → the earlier round — then package(): deliverable/ + selection.json
```
Track-specific gates: static `connectivity` + `contract` (+ `reference_silhouette`); articulated
diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.md
index 64234578..17de1af9 100644
--- a/harness/docs/RUNBOOK.md
+++ b/harness/docs/RUNBOOK.md
@@ -147,9 +147,10 @@ pick with Argon, use `3dcodeverse pick <slug> --by pairwise --judge gemini:gemin
# it archives the round journal + record.json to rounds/pre_force/ and the
# run starts again at round 0
3dcodeverse pick <slug> [--by score|pairwise] [--round N] [--judge MODEL]
- # hand over a round: deliverable/ + selection.json. score = highest
+ # hand over a round: deliverable/ + selection.json. score = rounds
+ # without a project:* / contract_fixed ERROR first, then highest
# effective score, ties → fewer gate errors → the earlier round; pairwise =
- # the pairwise judge between the top two when within 0.03; --round N = that
+ # the pairwise judge between the top two when within 0.03 (same tier); --round N = that
# round. `make`/`resume` run `pick --by score` for you
3dcodeverse render <slug> [--mode shaded|wire|normals|clay|silhouette] [--out dir]
3dcodeverse judge <slug> [--round N] [--rubric static_object] [--model gemini:gemini-4-argon] [--n 3] [--thinking off|low|medium|high]
diff --git a/harness/pyproject.toml b/harness/pyproject.toml
index 940cc014..0888caa6 100644
--- a/harness/pyproject.toml
+++ b/harness/pyproject.toml
@@ -20,7 +20,7 @@ classifiers = [
"Operating System :: MacOS",
]
dependencies = [
- "pydantic>=2.7",
+ "pydantic>=2.12", # Field(exclude_if=...)
"pydantic-settings>=2.3",
"typer>=0.12",
"click>=8.1", # imported directly by cli/cost_cmd.py (typer re-exports it, but we use it by name)
diff --git a/harness/tests/flywheel_cli/test_cli.py b/harness/tests/flywheel_cli/test_cli.py
index fcae67f3..a96c9f95 100644
--- a/harness/tests/flywheel_cli/test_cli.py
+++ b/harness/tests/flywheel_cli/test_cli.py
@@ -65,7 +65,7 @@ def test_make_no_run_creates_valid_workspace(tmp_path: Path):
assert (ws / "src").is_dir() and (ws / "artifacts" / "renders").is_dir()
# same prompt again → same slug → refuse without --force
r2 = runner.invoke(app, ["make", "a wooden dining chair", "--runs-dir", str(runs), "--no-run"])
- assert r2.exit_code == 1 and "already exists" in (r2.output + str(r2.stderr if hasattr(r2, "stderr") else ""))
+ assert r2.exit_code == 1 and "already exists" in " ".join(r2.output.split()) # the console wraps long paths
r3 = runner.invoke(app, ["make", "a wooden dining chair", "--runs-dir", str(runs), "--no-run", "--force"])
assert r3.exit_code == 0
diff --git a/harness/tests/flywheel_cli/test_select.py b/harness/tests/flywheel_cli/test_select.py
index f3d0daba..e7497c1f 100644
--- a/harness/tests/flywheel_cli/test_select.py
+++ b/harness/tests/flywheel_cli/test_select.py
@@ -252,3 +252,18 @@ def test_a_round_failing_the_projects_own_checks_loses_to_one_that_passes(tmp_pa
assert select.pick(ws.root) == want
rows = select.round_rows(ws.root)
assert [r.project_errors for r in rows] == ([e for _, e in rounds] if gate != "contract" else [0] * len(rounds))
+
+
+def test_pairwise_never_overturns_the_project_tier(tmp_path):
+ """Within the pairwise margin, a round failing a project check is never asked against a clean one."""
+ ws = _run(tmp_path / "r", [(0.70, 0), (0.71, 0)])
+ rec = json.loads(ws.record_path.read_text())
+ rec["rounds"][1]["gates"].append({"gate": "project:survey", "passed": False, "findings": [
+ {"gate": "project:survey", "severity": "error", "message": "eaves 0.9 m off"}]})
+ ws.record_path.write_text(json.dumps(rec))
+
+ class Never:
+ def judge(self, *a, **k):
+ raise AssertionError("pairwise asked across tiers")
+
+ assert select.pick(ws.root, by="pairwise", judge=Never()) == 0
diff --git a/harness/tests/orchestrator_tracks/test_fixed_parts.py b/harness/tests/orchestrator_tracks/test_fixed_parts.py
index 3e583134..cccc6035 100644
--- a/harness/tests/orchestrator_tracks/test_fixed_parts.py
+++ b/harness/tests/orchestrator_tracks/test_fixed_parts.py
@@ -120,3 +120,16 @@ def test_the_skeleton_keeps_a_fixed_part_and_stops_without_one(tmp_path: Path) -
ctx.spec = _spec(SHELL, FixedPart(path="src/missing.js"))
with pytest.raises(FileNotFoundError, match="src/missing.js"):
_skeleton(None, ctx) # type: ignore[arg-type]
+
+
+def test_fixed_parts_are_object_track_only_and_stored_canonical() -> None:
+ assert _spec(FixedPart(path="src//parts/./a.js")).fixed_parts[0].path == "src/parts/a.js"
+ with pytest.raises(ValueError, match="object tracks only"):
+ Spec(id="x", track=Track.SCENE, language=Language.SCENE_THREEJS, prompt="p", fixed_parts=[DATA])
+
+
+def test_refine_and_repair_prompts_carry_the_fixed_parts() -> None:
+ from codeverse3d.prompts import load_text
+
+ for name in ("tracks/refine_object.j2", "tracks/repair.j2"):
+ assert "{% if fixed_parts %}" in load_text(name)
diff --git a/harness/tests/spatial_tools/test_connectivity.py b/harness/tests/spatial_tools/test_connectivity.py
index afcb36bb..def17185 100644
--- a/harness/tests/spatial_tools/test_connectivity.py
+++ b/harness/tests/spatial_tools/test_connectivity.py
@@ -213,8 +213,9 @@ def test_planned_edges_are_measured_regardless_of_the_aabb_prefilter(solid_stool
assert sorted(d["parts"]) == ["Leg_0", "Leg_1", "Leg_2", "Leg_3", "Seat"]
assert len(d["contacts"]) == 4 and all(c[1] == "Seat" or c[0] == "Seat" for c in d["contacts"])
-def test_inside_test_uses_trimesh_rays_unless_embree_is_asked_for(switch) -> None:
- """The default ray engine is trimesh's own intersector, Embree only by ``C3D_RAY_ENGINE=embree``."""
+
+def test_inside_test_uses_embree_unless_numpy_is_asked_for(switch) -> None:
+ """The default ray engine is Embree (``mesh.ray``); trimesh's own intersector only by ``C3D_RAY_ENGINE=numpy``."""
from trimesh.ray.ray_triangle import RayMeshIntersector
from codeverse3d.spatial import joints_collide
@@ -222,7 +223,7 @@ def test_inside_test_uses_trimesh_rays_unless_embree_is_asked_for(switch) -> Non
box = trimesh.creation.box(extents=(1.0, 1.0, 1.0))
points = np.array([[0.0, 0.0, 0.0], [2.0, 0.0, 0.0]])
switch("C3D_RAY_ENGINE", None)
+ assert joints_collide._intersector(box) is box.ray
+ switch("C3D_RAY_ENGINE", "numpy")
assert isinstance(joints_collide._intersector(box), RayMeshIntersector)
assert joints_collide.inside_island(box, points).tolist() == [True, False]
- switch("C3D_RAY_ENGINE", "embree")
- assert joints_collide._intersector(box) is box.ray