Skip to content

Official Codebase of 3DCodeVerse

Python

judge: conditional cross-section slices + provenance elicitation on gate-ERROR rounds (D48)

gaoypengc3f831deb441
diff --git a/harness/codeverse/cli/_judge.py b/harness/codeverse/cli/_judge.py
index cc4ab5d6..9a5feb26 100644
--- a/harness/codeverse/cli/_judge.py
+++ b/harness/codeverse/cli/_judge.py
@@ -21,7 +21,7 @@ from codeverse.contracts.artifacts import BuildResult, RenderSet, RenderView
from codeverse.contracts.common import TRACK_INFO
from codeverse.contracts.plan import AcceptanceItem
from codeverse.contracts.run import RoundRecord, RunRecord
-from codeverse.judges.base import judged_subset, plan_digest, resolve_paths
+from codeverse.judges.base import SLICE_TRACKS, judged_subset, plan_digest, resolve_paths
from codeverse.proc import read_json_or_none
from codeverse.workspace import Workspace
@@ -102,9 +102,19 @@ def build_judge_input(ws: Workspace, rec: RunRecord, rnd: RoundRecord) -> Any:
acceptance=acceptance, plan_summary=plan_summary_for(ws), round_index=rnd.index,
previous=previous_judgment(ws, rec, rnd.index), extra_context=extra_context_for(ws, rec, rnd),
geometry_views=clay_geometry_views(ws, rnd.index),
+ glb_path=stored_glb_path(ws, rec, rnd),
)
+def stored_glb_path(ws: Workspace, rec: RunRecord, rnd: RoundRecord) -> str | None:
+ """The round's canonical GLB (object tracks), rebased to THIS workspace — what lets
+ ``3dcv judge`` reproduce the D48 conditional slice payload from the stored gates."""
+ if rec.spec.track.value not in SLICE_TRACKS or rnd.build is None or not rnd.build.glb_path:
+ return None
+ p = ws.rebase(rnd.build.glb_path)
+ return str(p) if p.is_file() else None
+
+
def make_judge(rec: RunRecord, rubric_name: str, model_id: str, n: int) -> Any:
"""ReferenceJudge for measured rubrics / reference specs, VlmJudge otherwise."""
load_rubric = C.lazy("codeverse.judges.rubrics", "load_rubric")
@@ -120,14 +130,19 @@ def make_judge(rec: RunRecord, rubric_name: str, model_id: str, n: int) -> Any:
return VlmJudge(rubric=rubric_name, model_id=model_id, n_samples=n)
-def count_prompt_images(inp: Any, rubric_name: str) -> int | None:
- """Number of image parts a single judge sample will send (None on failure)."""
+def count_prompt_images(inp: Any, rubric_name: str, judge: Any = None) -> int | None:
+ """Number of image parts a single judge sample will send (None on failure).
+
+ With ``judge`` given, its D48 slice payload is counted too, so a dirty round's
+ printed count matches what the verdict call actually sends."""
try:
load_rubric = C.lazy("codeverse.judges.rubrics", "load_rubric")
build_judge_messages = C.lazy("codeverse.judges.prompt_builder", "build_judge_messages")
from codeverse.contracts.chat import ImagePart
- _, messages = build_judge_messages(inp, load_rubric(rubric_name))
+ slices, elicit = judge.slice_payload(inp) if judge is not None else ([], False)
+ _, messages = build_judge_messages(inp, load_rubric(rubric_name),
+ slice_images=slices, provenance_elicitation=elicit)
return sum(1 for m in messages for p in m.parts if isinstance(p, ImagePart))
except Exception: # noqa: BLE001 — informational only
return None
diff --git a/harness/codeverse/cli/inspect_cmd.py b/harness/codeverse/cli/inspect_cmd.py
index ee8125ec..000206dd 100644
--- a/harness/codeverse/cli/inspect_cmd.py
+++ b/harness/codeverse/cli/inspect_cmd.py
@@ -210,7 +210,7 @@ def judge(
rubric_name = J.rubric_for(rec, rnd, rubric)
inp = J.build_judge_input(ws, rec, rnd)
judge_obj = J.make_judge(rec, rubric_name, model or rec.spec.backends.judge, n)
- n_images = J.count_prompt_images(inp, rubric_name)
+ n_images = J.count_prompt_images(inp, rubric_name, judge_obj)
from codeverse.cost.instrument import run_ledger
# writes artifacts/judge/rNN_cli.json into the run: one writer per run dir
diff --git a/harness/codeverse/config.py b/harness/codeverse/config.py
index e93cca90..88b88409 100644
--- a/harness/codeverse/config.py
+++ b/harness/codeverse/config.py
@@ -16,7 +16,7 @@ import re
import shutil
from functools import lru_cache
from pathlib import Path
-from typing import Any, ClassVar
+from typing import Any, ClassVar, Literal
import yaml
from pydantic import BaseModel, Field, model_validator
@@ -159,6 +159,12 @@ class Judge(BaseModel):
montages: int = Field(default=5, description="max 2x2 montages per verdict (14-view rig, D47)")
detail_crops: int = Field(default=2, description="max zoomed detail crops per verdict")
samples: int = Field(default=1, description="default VLM samples per verdict")
+ slices: Literal["on-error", "off"] = Field(
+ default="on-error",
+ description="conditional cross-section slices (D48, CV3D_JUDGE__SLICES): 'on-error' appends ≤2 "
+ "interior slice images + one provenance-elicitation sentence to an object-track verdict whose "
+ "connectivity gate carries an ERROR; clean rounds build a byte-identical payload either way. "
+ "Slice render is local CPU; no profile touches this dial (the channel measured ≤ $0).")
#: The fewer-turns switch (docs/COST.md §29). Read at CALL time by
diff --git a/harness/codeverse/doctor.py b/harness/codeverse/doctor.py
index c9de3608..1b28f001 100644
--- a/harness/codeverse/doctor.py
+++ b/harness/codeverse/doctor.py
@@ -16,7 +16,7 @@ from codeverse.proc import version_line
Row = tuple[str, str, str]
_PY_DEPS = ("pydantic", "pydantic_settings", "typer", "rich", "jinja2", "yaml", "numpy", "trimesh", "fcl", "PIL", "pyarrow",
- "scipy", "shapely", "networkx", "manifold3d", "google.genai", "anthropic", "openai",
+ "scipy", "shapely", "networkx", "manifold3d", "matplotlib", "google.genai", "anthropic", "openai",
"yourdfpy", "mcp", "moderngl", "cadquery")
#: modules that come from an OPTIONAL extra: missing means one track is unavailable, not a
#: broken install, so they are a WARN naming the extra to install. `moderngl` and `cadquery`
@@ -29,7 +29,7 @@ _PY_DEPS = ("pydantic", "pydantic_settings", "typer", "rich", "jinja2", "yaml",
#: docs/INSTALL.md §1 documents (no extras) got `python deps FAIL 14/23` — "your install
#: is broken" for an install that is correct — and a remedy that named four of the five
#: extras and could not clear the row. Verified on a 3.13 clean clone, 2026-08-24.
-_OPTIONAL_DEPS = {"manifold3d": "mesh", "shapely": "mesh", "networkx": "mesh",
+_OPTIONAL_DEPS = {"manifold3d": "mesh", "shapely": "mesh", "networkx": "mesh", "matplotlib": "mesh",
"yourdfpy": "urdf", "scipy": "urdf", "mcp": "mcp",
"moderngl": "graphics", "cadquery": "cad", "pyarrow": "flywheel"}
_CLI_TIMEOUT = 25
diff --git a/harness/codeverse/judges/base.py b/harness/codeverse/judges/base.py
index abad941e..a67e4d19 100644
--- a/harness/codeverse/judges/base.py
+++ b/harness/codeverse/judges/base.py
@@ -11,6 +11,10 @@ from codeverse.contracts.plan import AcceptanceItem
from codeverse.contracts.spec import Spec
from codeverse.workspace import Workspace
+#: tracks whose rounds have one canonical GLB the judge slice channel (D48) may cut;
+#: scene and graphics have none and are unaffected.
+SLICE_TRACKS = ("static_object", "articulated_object")
+
class JudgeInput(BaseModel):
spec: Spec
@@ -25,6 +29,11 @@ class JudgeInput(BaseModel):
geometry_views: RenderSet | None = Field(
default=None, description="clay/normals renders for the geometry-only montage (holes, intersections)"
)
+ glb_path: str | None = Field(
+ default=None,
+ description="the round's canonical GLB (object tracks fill it; `3dcv judge` fills it from the stored "
+ "build) — the D48 slice channel cuts it on gate-ERROR rounds; None disables the channel",
+ )
# ===================================================================== round replay
diff --git a/harness/codeverse/judges/prompt_builder.py b/harness/codeverse/judges/prompt_builder.py
index 6f36a001..39401927 100644
--- a/harness/codeverse/judges/prompt_builder.py
+++ b/harness/codeverse/judges/prompt_builder.py
@@ -395,6 +395,7 @@ if TYPE_CHECKING: # pragma: no cover
TEXT_BUDGET_CHARS = 24_000 # ≈ 6k tokens
MAX_PX = 1024 # montages are 2×2 grids: keep them legible
MONTAGE_TILE_PX = 512
+SLICE_MAX_PX = 1024 # D48 slice images: single drawings, sent at the montage size
_ROLE = """You are the BLIND JUDGE of a 3D-code harness: exacting but fair.
You see only the brief, a plan digest, measured numbers, deterministic gate findings and labelled renders of the result — never the builder's code or reasoning. Judge what is visible and measured; do not invent faults and do not credit what you cannot see.
@@ -412,6 +413,18 @@ SCORING RULES
- Reply with ONE JSON object matching the requested schema; no prose outside it."""
+#: D48: end of the DEFECT CHECKLIST scoring-rule bullet in ``_ROLE`` — the anchor the
+#: provenance-elicitation sentence is appended after on slice (gate-ERROR) rounds.
+_DEFECT_BULLET_END = 'do not mark a defect to "be safe", and do not hide one to be kind.'
+#: D48: one neutral, defect-agnostic sentence. Measured (42-item battery, n=3 pro): it turns
+#: dirty-round defect votes into locatable citations (62/97 image-located, 26 explicit
+#: text-only, 2/23 fabricated slice cites — both guard-caught) without naming any defect.
+PROVENANCE_ELICITATION = (
+ "For each defect you mark present, say where it is visible (MONTAGE n / "
+ "DETAIL CROP n / slice n) or state that it rests on the measured text alone."
+)
+
+
def _rubric_block(rubric: Rubric) -> str:
lines = [f"RUBRIC {rubric.name} v{rubric.version} (pass threshold {rubric.pass_threshold:.2f}, for information only)"]
for i, c in enumerate(rubric.criteria, 1):
@@ -440,8 +453,16 @@ def _rubric_block(rubric: Rubric) -> str:
return "\n".join(lines)
-def build_system_prompt(rubric: Rubric) -> str:
- return _ROLE + "\n\n" + _rubric_block(rubric)
+def build_system_prompt(rubric: Rubric, *, provenance_elicitation: bool = False) -> str:
+ """The judge's system prompt. ``provenance_elicitation=True`` (D48, slice rounds only)
+ appends :data:`PROVENANCE_ELICITATION` once to the DEFECT CHECKLIST bullet; the default
+ is byte-identical to the pre-D48 prompt, which keeps ``judge_prompt_hash`` stable."""
+ role = _ROLE
+ if provenance_elicitation:
+ if role.count(_DEFECT_BULLET_END) != 1: # the anchor moved: fail loudly, not silently
+ raise ValueError("prompt_builder._ROLE: the defect-checklist bullet anchor drifted")
+ role = role.replace(_DEFECT_BULLET_END, _DEFECT_BULLET_END + " " + PROVENANCE_ELICITATION)
+ return role + "\n\n" + _rubric_block(rubric)
# --------------------------------------------------------------------------- text sections
@@ -569,6 +590,26 @@ def gates_section(gates: list[GateReport], *, max_errors: int = 12, max_warns: i
return "\n".join(lines)
+def connectivity_error_pairs(gates: list[GateReport]) -> list[tuple[str, str]]:
+ """The connectivity gate's ERROR-level penetration part pairs — the D48 slice
+ channel's hatch targets. The pair is read the way the measured batteries read it:
+ the finding's ``target`` (falling back to ``data.entering``) against ``data.other``
+ (falling back to ``data.container``) — never ``data.entering`` first, whose
+ direction is the probe's, not the finding's."""
+ pairs: set[frozenset[str]] = set()
+ for g in gates:
+ if g.gate != "connectivity":
+ continue
+ for f in g.findings:
+ if f.severity != Severity.ERROR or f.data.get("kind") != "penetration":
+ continue
+ a = f.target or f.data.get("entering")
+ b = f.data.get("other") or f.data.get("container")
+ if a and b and a != b:
+ pairs.add(frozenset((str(a), str(b))))
+ return [tuple(sorted(p)) for p in sorted(pairs, key=sorted)]
+
+
def _finding_line(g: GateReport, f: GateFinding) -> str:
tgt = f" [{f.target}]" if f.target else ""
return f"- {g.gate}{tgt}: {_clip(f.message, 220)}"
@@ -813,6 +854,20 @@ def view_rig_section(renders: RenderSet, montages: list[Montage], *, scene: bool
return "\n".join(bits)
+def slice_rig_section(labels: list[str]) -> str:
+ """The D48 slice block appended to the view rig on gate-ERROR rounds: what the slice
+ images are (facts only: F2 wording for the hatch), the anti-over-read sentence (F3 —
+ an in-plane gap is not evidence of disconnection), and the slice list in send order."""
+ lines = "\n".join(f"- slice {i}: {lbl}" for i, lbl in enumerate(labels, 1))
+ return (f"After the crops, {len(labels)} cross-section slice(s) show the interior: "
+ "slices cut the object on two centre planes; each part keeps one color "
+ "(legend on the image); regions the connectivity gate measured as ERROR-level "
+ "overlap are hatched red. "
+ "A gap between parts IN THE CUT PLANE is not evidence of disconnection — parts "
+ "may join outside this plane; the measured structure block is authoritative for "
+ "connectivity.\n" + lines)
+
+
def judge_prompt_hash(rubric: Rubric) -> str:
"""Hash of everything the judge is told that is constant for a rubric.
@@ -882,6 +937,8 @@ def build_judge_messages(
cache_dir: Path | None = None,
extra_images: list[tuple[str, str | Path]] | None = None,
extra_text: str = "",
+ slice_images: list[tuple[str, str | Path]] | None = None,
+ provenance_elicitation: bool = False,
) -> tuple[str, list[ChatMessage]]:
"""Return ``(system, [user_message])`` for a rubric judge call.
@@ -892,8 +949,15 @@ def build_judge_messages(
order (n-sample noise control). ``extra_images`` (label, path) are placed
BEFORE the montages (e.g. reference images); ``extra_text`` is appended to
the text block (e.g. measured silhouette).
+
+ ``slice_images`` (label, path) are the D48 cross-section slices: placed AFTER
+ the montages and detail crops (the measured placement — the ``extra_images``
+ prepend was not what the batteries tested), described by
+ :func:`slice_rig_section` in the view-rig text, and ``provenance_elicitation``
+ adds one sentence to the system prompt's defect-checklist bullet. With both
+ left at their defaults the output is byte-identical to the pre-D48 payload.
"""
- system = build_system_prompt(rubric)
+ system = build_system_prompt(rubric, provenance_elicitation=provenance_elicitation)
is_scene = inp.spec.track.value == "scene"
sections = [
brief_section(inp.spec),
@@ -910,7 +974,11 @@ def build_judge_messages(
inp.renders, geometry_views=geometry_views, scene=is_scene, shuffle_seed=shuffle_seed,
max_montages=max_montages, detail_crops=detail_crops, max_px=max_px, cache_dir=cache_dir,
)
- sections.append(view_rig_section(inp.renders, montages, scene=is_scene))
+ slices = slice_images or []
+ rig = view_rig_section(inp.renders, montages, scene=is_scene)
+ if slices:
+ rig = rig + "\n" + slice_rig_section([lbl for lbl, _ in slices])
+ sections.append(rig)
text = "\n\n".join(s for s in sections if s)
if len(text) > TEXT_BUDGET_CHARS:
text = _clip(text, TEXT_BUDGET_CHARS)
@@ -921,5 +989,8 @@ def build_judge_messages(
for lbl, ip in images:
parts.append(TextPart(text=lbl))
parts.append(ip)
+ for lbl, p in slices: # D48: slices AFTER the montages and crops — the measured placement
+ parts.append(TextPart(text=lbl))
+ parts.append(image_part(prepare_image(p, label=lbl, max_px=SLICE_MAX_PX, cache_dir=cache_dir), lbl))
parts.append(TextPart(text="Now score every criterion with evidence, answer every defect-checklist item and every acceptance item, and return the JSON object."))
return system, [ChatMessage(role="user", parts=parts)]
diff --git a/harness/codeverse/judges/vlm_judge.py b/harness/codeverse/judges/vlm_judge.py
index 53a0a3c8..a09e5c98 100644
--- a/harness/codeverse/judges/vlm_judge.py
+++ b/harness/codeverse/judges/vlm_judge.py
@@ -17,9 +17,12 @@ to treat as a glitch, never as a score.
from __future__ import annotations
+import hashlib
import logging
import os
import re
+import shutil
+import threading
import time
from collections.abc import Callable
from dataclasses import dataclass, field
@@ -30,8 +33,13 @@ from codeverse.config import get_settings
from codeverse.contracts.artifacts import Judgment, RenderView
from codeverse.contracts.chat import ChatRequest, ChatResponse
from codeverse.contracts.common import Usage
-from codeverse.judges.base import JudgeInput
-from codeverse.judges.prompt_builder import build_judge_messages, judge_prompt_hash
+from codeverse.judges.base import SLICE_TRACKS, JudgeInput
+from codeverse.judges.prompt_builder import (
+ build_judge_messages,
+ connectivity_error_pairs,
+ default_cache_dir,
+ judge_prompt_hash,
+)
from codeverse.judges.rubrics import (
JudgeOutput,
JudgeParseError,
@@ -56,6 +64,12 @@ SAMPLE_BUDGET_S = 900.0
#: the floor of one attempt's ``max_wait_s``: a last attempt still gets a real try
SAMPLE_MIN_WAIT_S = 20.0
+#: D48 slice-image labels, keyed by ``sections.JUDGE_SLICE_PLANES`` name (the tested wording)
+SLICE_LABELS = {
+ "front_back": "cross-section front-back · interior view",
+ "left_right": "cross-section left-right · interior view",
+}
+
@dataclass
class JudgeContext:
@@ -144,6 +158,7 @@ class VlmJudge:
ctx = self.context(inp)
measured, extra_text, extra_images = ctx.measured_scores, ctx.extra_text, ctx.extra_images
usage = ctx.usage
+ slice_images, elicit = self.slice_payload(inp) # D48: [] / False on a clean round
samples: list[JudgeOutput] = []
errors: list[str] = []
reqs: list[ChatRequest] = []
@@ -154,6 +169,7 @@ class VlmJudge:
inp, self.rubric, shuffle_seed=seed, geometry_views=geometry_views, max_montages=self.max_montages,
detail_crops=self.detail_crops, max_px=self.max_px, cache_dir=self.cache_dir,
extra_images=extra_images, extra_text=extra_text,
+ slice_images=slice_images, provenance_elicitation=elicit,
)
reqs.append(ChatRequest(
messages=messages, system=system, response_schema=schema, temperature=self.temperature,
@@ -207,6 +223,65 @@ class VlmJudge:
)
return JudgeContext()
+ # ------------------------------------------------------------------ D48 conditional slices
+ def slice_payload(self, inp: JudgeInput) -> tuple[list[tuple[str, str]], bool]:
+ """``([(label, png_path)…], provenance_elicitation)`` for the D48 slice channel.
+
+ The channel fires ONLY when ``Settings.judge.slices == "on-error"``, the track is
+ an object track, ``inp.glb_path`` exists, AND the connectivity gate carries ≥ 1
+ ERROR finding; otherwise ``([], False)`` and the payload is byte-identical to the
+ pre-D48 one. On a firing round the slices are rendered (cached by GLB identity +
+ error pairs) into the judge cache dir; F4 may drop them all, in which case the
+ elicitation sentence still applies (the tested v3 semantics: elicitation follows
+ dirtiness, not slice count). A missing mesh extra disables the channel; a render
+ crash degrades to text-only elicitation — a verdict never dies on a drawing.
+ """
+ if get_settings().judge.slices != "on-error":
+ return [], False
+ if inp.spec.track.value not in SLICE_TRACKS or not inp.glb_path:
+ return [], False
+ glb = Path(inp.glb_path)
+ if not glb.is_file():
+ return [], False
+ if not any(g.gate == "connectivity" and g.errors for g in inp.gates):
+ return [], False
+ pairs = connectivity_error_pairs(inp.gates)
+ try:
+ out_dir, manifest = self._render_slices(glb, pairs)
+ except ImportError as e:
+ log.warning("judge slices disabled: %s (install the 'mesh' extra)", e)
+ return [], False
+ except Exception as e: # noqa: BLE001 — the drawing must never sink the verdict
+ log.warning("judge slice render failed for %s: %s", glb, e)
+ return [], True
+ return [(SLICE_LABELS.get(s.name, f"cross-section {s.name} · interior view"),
+ str(out_dir / s.png)) for s in manifest.rendered()], True
+
+ def _render_slices(self, glb: Path, pairs: list[tuple[str, str]]):
+ """Render (or reuse) the slice set for ``glb`` under the judge cache dir.
+
+ Keyed like ``prepare_image``: path + mtime + size + the error pairs, so a
+ rebuilt GLB re-renders and concurrent judges of the same round share one set.
+ Writes go to a per-writer temp dir renamed into place (a concurrent identical
+ writer simply wins first)."""
+ from codeverse.spatial.sections import SliceManifest, judge_slices
+
+ cache = Path(self.cache_dir) if self.cache_dir else default_cache_dir()
+ st = glb.stat()
+ key = hashlib.sha1(
+ f"{glb.resolve()}|{st.st_mtime_ns}|{st.st_size}|{pairs}".encode()).hexdigest()[:20]
+ out_dir = cache / f"slices_{key}"
+ mpath = out_dir / "manifest.json"
+ if not mpath.is_file():
+ tmp = cache / f"slices_{key}.{os.getpid()}-{threading.get_ident()}.tmp"
+ shutil.rmtree(tmp, ignore_errors=True)
+ judge_slices(glb, pairs, tmp)
+ try:
+ tmp.rename(out_dir)
+ except OSError: # a concurrent writer got there first — use theirs
+ shutil.rmtree(tmp, ignore_errors=True)
+ return out_dir, SliceManifest.model_validate_json(mpath.read_text())
+
# ------------------------------------------------------------------ one sample with retries
def _sample(
self, req: ChatRequest, acceptance_ids: list[str], measured: dict[str, float]
diff --git a/harness/codeverse/tracks/steps.py b/harness/codeverse/tracks/steps.py
index cc0550bd..ebf7a967 100644
--- a/harness/codeverse/tracks/steps.py
+++ b/harness/codeverse/tracks/steps.py
@@ -31,7 +31,7 @@ from codeverse.contracts.artifacts import BuildResult, GateReport, Judgment, Mea
from codeverse.contracts.common import Usage
from codeverse.contracts.plan import AcceptanceItem, Plan
from codeverse.contracts.run import RoundRecord
-from codeverse.judges.base import JudgeInput
+from codeverse.judges.base import SLICE_TRACKS, JudgeInput
from codeverse.judges.rubrics import is_degraded
from codeverse.orchestrator import BudgetExceeded, usage_delta
from codeverse.proc import fan_out
@@ -451,6 +451,8 @@ def _judge(ctx: RunContext, pipeline: RoundPipeline, index: int, build: BuildRes
acceptance=list(getattr(ctx.plan, "acceptance", []) or []), plan_summary=pipeline.plan_summary(ctx),
round_index=index, previous=previous, extra_context=pipeline.judge_context(ctx.ws, ctx.plan, index, build, gates),
geometry_views=geometry,
+ # D48: the round's canonical GLB feeds the conditional slice channel (object tracks only)
+ glb_path=build.glb_path if ctx.spec.track.value in SLICE_TRACKS else None,
)
t0 = time.time()
try:
diff --git a/harness/docs/INSTALL.md b/harness/docs/INSTALL.md
index 7587180b..64ccd53e 100644
--- a/harness/docs/INSTALL.md
+++ b/harness/docs/INSTALL.md
@@ -133,7 +133,7 @@ openai.
| `cad` | cadquery | the `cadquery` language (`--language cadquery`) |
| `urdf` | yourdfpy, scipy | the `articulated_object` track: URDF parse/validate + joint math |
| `graphics` | moderngl | the `graphics` track (`glsl_shader`, `opengl_python`) — headless GL rendering in `spatial/gl_render.py` |
-| `mesh` | shapely, networkx, manifold3d | `cross_section` filled-area/hollow ratio (shapely), mesh split / connectivity (networkx), joint-sweep boolean intersections (`trimesh.boolean(engine="manifold")`) |
+| `mesh` | shapely, networkx, manifold3d, matplotlib | `cross_section` filled-area/hollow ratio (shapely), mesh split / connectivity (networkx), joint-sweep boolean intersections (`trimesh.boolean(engine="manifold")`), judge cross-section slices on gate-ERROR rounds (`judge_slices`, D48; without the extra the judge logs a warning and sends the pre-D48 payload) |
| `mcp` | mcp | `3dcv mcp` / `codeverse.spatial.mcp_server`, i.e. spatial tools for the `gemini-cli`, `claude-code` and `codex` backends |
| `flywheel` | pyarrow | `3dcv flywheel export --pack` (parquet shards). A plain `flywheel export` needs nothing: without pyarrow it writes `metadata.jsonl` and skips `metadata.parquet` with a warning. |
| `all` | all of the above | — |
diff --git a/harness/pyproject.toml b/harness/pyproject.toml
index 97ad1fbb..3c4b1a9a 100644
--- a/harness/pyproject.toml
+++ b/harness/pyproject.toml
@@ -41,7 +41,7 @@ dependencies = [
cad = ["cadquery>=2.4"] # language `cadquery`
urdf = ["yourdfpy>=0.0.56", "scipy>=1.11"] # track `articulated_object` (urdf_blender)
graphics = ["moderngl>=5.8"] # track `graphics` (glsl_shader / opengl_python)
-mesh = ["shapely>=2.0", "networkx>=3.2", "manifold3d>=2.3"] # cross_section area, mesh split, joint-sweep booleans
+mesh = ["shapely>=2.0", "networkx>=3.2", "manifold3d>=2.3", "matplotlib>=3.8"] # cross_section area, mesh split, joint-sweep booleans, judge slices (D48)
mcp = ["mcp>=1.0"] # `3dcv mcp` spatial-tool server for the agentic CLIs
flywheel = ["pyarrow>=15"] # `3dcv flywheel export --pack` (parquet)
all = ["3dcodeverse[cad,urdf,graphics,mesh,mcp,flywheel]"]
diff --git a/harness/tests/judges/test_judge_slices.py b/harness/tests/judges/test_judge_slices.py
new file mode 100644
index 00000000..6e3f2ff5
--- /dev/null
+++ b/harness/tests/judges/test_judge_slices.py
@@ -0,0 +1,194 @@
+"""D48: conditional cross-section slices in the judge payload.
+
+The load-bearing invariant is byte-identity: a round WITHOUT a connectivity
+gate ERROR must build exactly the pre-D48 messages (same system prompt, same
+parts, same ``judge_prompt_hash``) whatever the knob or ``glb_path`` say. A
+gate-ERROR round on an object track appends the slice images AFTER the
+montages and detail crops, describes them in the view-rig text, and adds the
+provenance-elicitation sentence to the defect-checklist bullet exactly once.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import trimesh
+
+from codeverse.config import Settings, get_settings
+from codeverse.contracts.artifacts import BuildResult, GateFinding, GateReport, RenderSet, Severity
+from codeverse.contracts.chat import ImagePart, TextPart
+from codeverse.contracts.run import RoundRecord, RunRecord
+from codeverse.judges.base import JudgeInput
+from codeverse.judges.prompt_builder import (
+ PROVENANCE_ELICITATION,
+ build_judge_messages,
+ connectivity_error_pairs,
+ judge_prompt_hash,
+)
+from codeverse.judges.rubrics import load_rubric
+from codeverse.judges.vlm_judge import SLICE_LABELS, VlmJudge
+from codeverse.workspace import Workspace
+from tests.judges.conftest import ACCEPTANCE, FakeChatModel, good_reply, make_renders, make_spec
+
+R = load_rubric("static_object_v1")
+IDS = ["A1", "A2"]
+
+
+def two_box_glb(path: Path) -> Path:
+ """Two 0.3 m boxes overlapping by 50 mm along x — both centre planes show the overlap."""
+ sc = trimesh.Scene()
+ a = trimesh.creation.box(extents=(0.3, 0.3, 0.3))
+ a.apply_translation((0, 0.15, 0))
+ b = trimesh.creation.box(extents=(0.3, 0.3, 0.3))
+ b.apply_translation((0.25, 0.15, 0))
+ sc.add_geometry(a, node_name="A", geom_name="A")
+ sc.add_geometry(b, node_name="B", geom_name="B")
+ sc.export(str(path))
+ return path
+
+
+def dirty_gates() -> list[GateReport]:
+ return [GateReport(gate="connectivity", passed=False, findings=[
+ GateFinding(gate="connectivity", severity=Severity.ERROR, target="A",
+ message="'A' and 'B' interpenetrate by ≈50.0 mm",
+ data={"kind": "penetration", "other": "B", "entering": "B", "container": "A",
+ "depth_m": 0.05}),
+ ])]
+
+
+def clean_gates() -> list[GateReport]:
+ return [GateReport(gate="connectivity", passed=True, findings=[
+ GateFinding(gate="connectivity", severity=Severity.WARN, target="A",
+ message="'A' and 'B' overlap by 1.2 mm (weld)",
+ data={"kind": "penetration", "other": "B", "depth_m": 0.0012}),
+ ])]
+
+
+def make_input(renders: RenderSet, gates: list[GateReport], glb: Path | None, **kw) -> JudgeInput:
+ return JudgeInput(spec=make_spec(**kw.pop("spec_kw", {})), renders=renders, gates=gates,
+ acceptance=list(ACCEPTANCE), glb_path=str(glb) if glb else None, **kw)
+
+
+def judge_request(inp: JudgeInput, cache_dir: Path):
+ model = FakeChatModel([good_reply(R, IDS, 0.8)])
+ VlmJudge("static_object_v1", model_id="fake:fake-1", chat_model=model, cache_dir=cache_dir).judge(inp)
+ return model.requests[0]
+
+
+def labels(req) -> list[str]:
+ return [p.label for m in req.messages for p in m.parts if isinstance(p, ImagePart)]
+
+
+def text_of(req) -> str:
+ return "\n".join(p.text for m in req.messages for p in m.parts if isinstance(p, TextPart))
+
+
+# --------------------------------------------------------------------- (a) clean = byte-identical
+def test_clean_gates_build_byte_identical_messages(tmp_path, cache_dir):
+ """The invariant: glb present + knob on, but no gate ERROR → the exact pre-D48 payload."""
+ inp = make_input(make_renders(tmp_path / "r"), clean_gates(), two_box_glb(tmp_path / "o.glb"))
+ req = judge_request(inp, cache_dir)
+ system, messages = build_judge_messages(inp, R, cache_dir=cache_dir) # the baseline builder
+ assert req.system == system
+ assert [m.model_dump() for m in req.messages] == [m.model_dump() for m in messages]
+ assert PROVENANCE_ELICITATION not in req.system
+ assert "cross-section" not in text_of(req)
+ # and the protocol hash is untouched: the hash builds the default (elicitation-free) prompt
+ assert judge_prompt_hash(R) == VlmJudge("static_object_v1", model_id="fake:fake-1").prompt_hash
+
+
+def test_knob_off_wrong_track_and_missing_glb_stay_baseline(tmp_path, cache_dir, monkeypatch):
+ renders = make_renders(tmp_path / "r")
+ glb = two_box_glb(tmp_path / "o.glb")
+ baseline = build_judge_messages(make_input(renders, dirty_gates(), None), R, cache_dir=cache_dir)
+
+ # dirty gates but no glb_path (e.g. a pre-D48 record): baseline
+ req = judge_request(make_input(renders, dirty_gates(), None), cache_dir)
+ assert req.system == baseline[0] and PROVENANCE_ELICITATION not in req.system
+ assert [m.model_dump() for m in req.messages] == [m.model_dump() for m in baseline[1]]
+
+ # dirty gates + glb, but the knob is off: baseline
+ monkeypatch.setattr("codeverse.judges.vlm_judge.get_settings",
+ lambda: Settings(judge={"slices": "off"}))
+ req = judge_request(make_input(renders, dirty_gates(), glb), cache_dir)
+ assert PROVENANCE_ELICITATION not in req.system and "cross-section" not in text_of(req)
+ get_settings.cache_clear()
+
+
+# --------------------------------------------------------------------- (b) dirty = slices appended
+def test_dirty_gates_append_slices_after_crops_with_rig_text_and_one_elicitation(tmp_path, cache_dir):
+ inp = make_input(make_renders(tmp_path / "r"), dirty_gates(), two_box_glb(tmp_path / "o.glb"))
+ req = judge_request(inp, cache_dir)
+
+ # placement: montage, 2 detail crops, THEN the two slices — never prepended
+ lbls = labels(req)
+ assert lbls[-2:] == [SLICE_LABELS["front_back"], SLICE_LABELS["left_right"]]
+ assert "DETAIL CROP" in lbls[-3] and len(lbls) == 5 # 1 montage + 2 crops + 2 slices
+
+ text = text_of(req)
+ assert "After the crops, 2 cross-section slice(s) show the interior" in text
+ assert "A gap between parts IN THE CUT PLANE is not evidence of disconnection" in text
+ assert f"- slice 1: {SLICE_LABELS['front_back']}" in text
+ assert req.system.count(PROVENANCE_ELICITATION) == 1
+ assert 'do not hide one to be kind. ' + PROVENANCE_ELICITATION in req.system
+
+ # the slice pngs and their manifest landed in the judge cache, hatching the gate pair
+ from codeverse.spatial.sections import SliceManifest
+ manifests = list(cache_dir.glob("slices_*/manifest.json"))
+ assert len(manifests) == 1
+ man = SliceManifest.model_validate_json(manifests[0].read_text())
+ assert man.error_pairs == [("A", "B")]
+ assert all({p.a, p.b} == {"A", "B"} for s in man.rendered() for p in s.hatched_pairs)
+
+
+def test_error_pair_extraction_reads_target_and_other(tmp_path):
+ # target/other win over entering/container (the probe's direction is not the finding's)
+ assert connectivity_error_pairs(dirty_gates()) == [("A", "B")]
+ g = GateReport(gate="connectivity", passed=False, findings=[
+ GateFinding(gate="connectivity", severity=Severity.ERROR, target="",
+ message="x", data={"kind": "penetration", "entering": "Leg", "container": "Seat"}),
+ GateFinding(gate="connectivity", severity=Severity.ERROR, target="Mast",
+ message="floating", data={"kind": "floating"}), # no pair: not a penetration
+ GateFinding(gate="connectivity", severity=Severity.WARN, target="C",
+ message="weld", data={"kind": "penetration", "other": "D"}), # WARN: never
+ ])
+ assert connectivity_error_pairs([g]) == [("Leg", "Seat")]
+ assert connectivity_error_pairs([GateReport(gate="contract", passed=False, findings=[])]) == []
+
+
+def test_a_dirty_round_with_a_floating_only_error_still_elicits(tmp_path, cache_dir):
+ """The trigger is ANY connectivity ERROR; with no penetration pair the slices carry
+ no hatch but the elicitation sentence still applies (the tested v3 semantics)."""
+ gates = [GateReport(gate="connectivity", passed=False, findings=[
+ GateFinding(gate="connectivity", severity=Severity.ERROR, target="B",
+ message="part 'B' is floating", data={"kind": "floating"})])]
+ inp = make_input(make_renders(tmp_path / "r"), gates, two_box_glb(tmp_path / "o.glb"))
+ req = judge_request(inp, cache_dir)
+ assert req.system.count(PROVENANCE_ELICITATION) == 1
+ assert labels(req)[-2:] == [SLICE_LABELS["front_back"], SLICE_LABELS["left_right"]]
+
+
+# --------------------------------------------------------------------- (d) 3dcv judge replay
+def test_replay_reproduces_the_conditional_payload_from_stored_gates_and_glb(tmp_ws: Workspace, tmp_path, cache_dir):
+ from codeverse.cli._judge import build_judge_input
+
+ glb = two_box_glb(tmp_path / "object.glb")
+ renders = make_renders(tmp_path / "renders")
+ rec = RunRecord(spec=make_spec(), workspace=str(tmp_ws.root))
+ rnd = RoundRecord(index=0, kind="baseline", gates=dirty_gates(), renders=renders,
+ build=BuildResult(ok=True, language="blender", glb_path=str(glb)))
+
+ inp = build_judge_input(tmp_ws, rec, rnd)
+ assert inp.glb_path == str(glb)
+ req = judge_request(inp, cache_dir)
+ assert labels(req)[-2:] == [SLICE_LABELS["front_back"], SLICE_LABELS["left_right"]]
+ assert req.system.count(PROVENANCE_ELICITATION) == 1
+
+ # a scene round's stored build never feeds the channel, whatever it exported
+ scene_rec = RunRecord(spec=make_spec(track="scene", language="scene_threejs"), workspace=str(tmp_ws.root))
+ assert build_judge_input(tmp_ws, scene_rec, rnd).glb_path is None
+
+ # a moved/deleted glb disables the channel instead of crashing the replay
+ rnd_gone = rnd.model_copy(update={"build": BuildResult(ok=True, language="blender",
+ glb_path=str(tmp_path / "gone.glb"))})
+ assert build_judge_input(tmp_ws, rec, rnd_gone).glb_path is None
diff --git a/harness/tests/spatial_tools/test_sections.py b/harness/tests/spatial_tools/test_sections.py
index d14beca4..30676f5f 100644
--- a/harness/tests/spatial_tools/test_sections.py
+++ b/harness/tests/spatial_tools/test_sections.py
@@ -6,7 +6,7 @@ import pytest
import trimesh
from PIL import Image
-from codeverse.spatial.sections import cross_section, slices_sheet
+from codeverse.spatial.sections import SliceManifest, cross_section, judge_slices, slices_sheet
def test_cross_section_stool(stool_glb: Path, tmp_path: Path) -> None:
@@ -45,3 +45,78 @@ def test_slices_sheet(stool_glb: Path, tmp_path: Path) -> None:
o = slices_sheet(stool_glb, "y", 5, out)
assert o.ok and out.is_file() and len(o.numbers["slices"]) == 5
assert all(s["n_loops"] == 4 for s in o.numbers["slices"][:4])
+
+
+# ===================================================================== judge slices (D48)
+def _two_boxes(path: Path, *, overlap_x: float = 0.05, dy: float = 0.0) -> Path:
+ """Box A (0.3³ at origin, resting on y=0) + box B shifted so they overlap by
+ ``overlap_x`` along x (and optionally offset ``dy`` up)."""
+ sc = trimesh.Scene()
+ a = trimesh.creation.box(extents=(0.3, 0.3, 0.3))
+ a.apply_translation((0, 0.15, 0))
+ b = trimesh.creation.box(extents=(0.3, 0.3, 0.3))
+ b.apply_translation((0.3 - overlap_x, 0.15 + dy, 0))
+ sc.add_geometry(a, node_name="A", geom_name="A")
+ sc.add_geometry(b, node_name="B", geom_name="B")
+ sc.export(str(path))
+ return path
+
+
+def test_judge_slices_hatches_only_gate_error_pairs(tmp_path: Path) -> None:
+ glb = _two_boxes(tmp_path / "boxes.glb")
+ m = judge_slices(glb, [("A", "B")], tmp_path / "err")
+ assert [s.name for s in m.rendered()] == ["front_back", "left_right"]
+ assert m.error_pairs == [("A", "B")]
+ for s in m.rendered():
+ assert [(p.a, p.b) for p in s.hatched_pairs] == [("B", "A")] or \
+ [(p.a, p.b) for p in s.hatched_pairs] == [("A", "B")]
+ assert s.plain_pairs == []
+ assert (tmp_path / "err" / s.png).is_file()
+
+ # the SAME geometry with no gate-ERROR pair: plain darkened blend, no hatch (F1)
+ plain = judge_slices(glb, [], tmp_path / "plain")
+ for s in plain.rendered():
+ assert s.hatched_pairs == [] and len(s.plain_pairs) == 1
+
+
+def test_judge_slices_ignores_hairline_contact_slivers(tmp_path: Path) -> None:
+ # 1 mm of in-plane overlap (a weld) is under the ~2·erode thickness: not drawn at all
+ glb = _two_boxes(tmp_path / "weld.glb", overlap_x=0.3, dy=0.299) # stacked, 1 mm y-overlap
+ m = judge_slices(glb, [("A", "B")], tmp_path / "out")
+ assert m.rendered()
+ for s in m.rendered():
+ assert s.hatched_pairs == [] and s.plain_pairs == []
+
+
+def test_judge_slices_drops_a_degenerate_slice(tmp_path: Path) -> None:
+ """A portal frame whose centre-x plane cuts only the thin top beam (4 % of the
+ part's projected silhouette): F4 drops front_back, keeps left_right."""
+ cols = []
+ for x in (-0.45, 0.45):
+ c = trimesh.creation.box(extents=(0.1, 1.0, 0.1))
+ c.apply_translation((x, 0.5, 0))
+ cols.append(c)
+ beam = trimesh.creation.box(extents=(1.0, 0.04, 0.1))
+ beam.apply_translation((0, 0.98, 0))
+ sc = trimesh.Scene()
+ sc.add_geometry(trimesh.util.concatenate([*cols, beam]), node_name="Frame", geom_name="Frame")
+ glb = tmp_path / "portal.glb"
+ sc.export(str(glb))
+
+ m = judge_slices(glb, [], tmp_path / "out")
+ by_name = {s.name: s for s in m.slices}
+ assert not by_name["front_back"].rendered and "degenerate" in by_name["front_back"].reason
+ assert by_name["left_right"].rendered
+ assert not (tmp_path / "out" / "slice_front_back.png").is_file()
+
+
+def test_judge_slices_manifest_round_trips_and_bad_glb_degrades(tmp_path: Path) -> None:
+ glb = _two_boxes(tmp_path / "boxes.glb")
+ out = tmp_path / "out"
+ m = judge_slices(glb, [("B", "A"), ("A", "A")], out, planes=("front_back",)) # self-pair ignored
+ assert m.error_pairs == [("A", "B")] and [s.name for s in m.slices] == ["front_back"]
+ stored = SliceManifest.model_validate_json((out / "manifest.json").read_text())
+ assert stored == m
+
+ bad = judge_slices(tmp_path / "missing.glb", [], tmp_path / "bad")
+ assert bad.slices == [] and bad.errors and (tmp_path / "bad" / "manifest.json").is_file()