Official Codebase of 3DCodeVerse
Python
"""What deterministic tools produce: builds, measurements, renders, gates."""
from __future__ import annotations
import json
from collections.abc import Sequence
from enum import StrEnum
from typing import Any, Literal
from pydantic import BaseModel, Field
from codeverse3d.contracts.common import Vec3
class Severity(StrEnum):
ERROR = "error" # blocks acceptance; routed to a repair task
WARN = "warn" # shown to judge/agent; does not block
INFO = "info"
class LintKind(StrEnum):
"""``data.kind`` of a ``lint:<language>`` finding (the shader rubric's kind-less ``lint*`` cap reads them; the rest are labels)."""
SYNTAX = "syntax" # the file does not parse
MISSING_FILE = "missing_file" # an entry / planned part file is absent
FORBIDDEN_IMPORT = "forbidden_import" # an import the sandbox forbids
BAD_IMPORT = "bad_import" # an import that cannot resolve here (package, URL, escape, missing)
SANDBOX = "sandbox" # file IO, network, subprocess, DOM, eval, exiting the process
HARNESS_OWNED = "harness_owned" # camera, light, world, renderer, render loop, export
API_TRAP = "api_trap" # a removed / renamed / context-dependent API
UNDEFINED_NAME = "undefined_name" # a name used and never imported
NAMING = "naming" # object / link / file naming
LAYOUT = "layout" # module exports and the multi-file layout
PART_NOT_IMPORTED = "part_not_imported" # a part file nothing imports, so its part is never built
LINK_NAME = "link_name" # a URDF link no object in model.py is named after
URDF_STRUCTURE = "urdf_structure" # the XML, the root, the link/joint tree
URDF_LINK = "urdf_link" # a link's visual / collision / mesh
URDF_JOINT = "urdf_joint" # a joint's type, parent/child, axis, limits
MIMIC = "mimic" # a <mimic> coupling
HANG_RISK = "hang_risk" # a loop / call that can stall a headless build
NONDETERMINISM = "nondeterminism" # an unseeded random source
#: ``GateFinding.data["kind"]`` of a plan part that is still a placeholder box.
PLACEHOLDER_PART = "placeholder_part"
class GateFinding(BaseModel):
gate: str
severity: Severity
target: str | None = Field(default=None, description="part / zone / joint / file this is about")
message: str
fix_hint: str = Field(default="", description="concrete, copyable instruction for the fixer")
data: dict[str, Any] = Field(default_factory=dict)
def as_line(
self,
*,
with_gate: bool = False,
with_severity: bool = False,
with_target: bool = False,
with_hint: bool = True,
) -> str:
"""One line for prompts/reports, no leading bullet; the flags opt in to prefix/tag/suffix parts."""
parts: list[str] = []
if with_gate:
parts.append(f"GATE {self.gate}:")
if with_severity:
parts.append(f"[{self.severity.value}]")
parts.append(self.message)
line = " ".join(parts)
if with_target and self.target:
line += f" [{self.target}]"
if with_hint and self.fix_hint:
line += f" FIX: {self.fix_hint}"
return line
class GateReport(BaseModel):
gate: str
passed: bool
findings: list[GateFinding] = Field(default_factory=list)
duration_ms: int = 0
@classmethod
def of(cls, gate: str, findings: Sequence[GateFinding] = (), *, duration_ms: int = 0) -> GateReport:
"""The report whose verdict is its findings: ``passed`` iff none is an ERROR."""
return cls(gate=gate, passed=not any(f.severity == Severity.ERROR for f in findings),
findings=list(findings), duration_ms=duration_ms)
@property
def errors(self) -> list[GateFinding]:
return [f for f in self.findings if f.severity == Severity.ERROR]
class BuildResult(BaseModel):
ok: bool
language: str
glb_path: str | None = None
extra_paths: dict[str, str] = Field(default_factory=dict, description="stl/step/urdf/blend ...")
stdout_tail: str = ""
stderr_tail: str = ""
error_type: str = ""
error_message: str = ""
error_file: str = ""
error_line: int | None = None
duration_ms: int = 0
census: dict[str, Any] = Field(default_factory=dict, description="language-native census (objects, materials ...)")
gates: list[GateReport] = Field(
default_factory=list,
description="the build's own gate reports (scene_threejs: scene_probe + shader_preflight; the graphics "
"languages: gl_frames) — ``check`` appends them to the gates, built or not",
)
harness_failure: bool = Field(
default=False,
description="the build did not fail on the agent's code — the instrument could not run it "
"(driver output lost, browser gone).",
)
class PartMeasure(BaseModel):
name: str
bbox_min: Vec3
bbox_max: Vec3
tri_count: int = 0
islands: int = 1
volume_m3: float | None = None
watertight: bool | None = None
class Measurement(BaseModel):
"""Language-agnostic census computed from the canonical GLB (Y-up, meters)."""
bbox_min: Vec3
bbox_max: Vec3
extents: Vec3
center: Vec3
tri_count: int
n_meshes: int
n_islands: int
parts: list[PartMeasure] = Field(default_factory=list)
ground_gap_m: float = Field(default=0.0, description="lowest point minus 0 (negative = below ground)")
footprint_offset_m: float = Field(default=0.0, description="xz distance of bbox centre from origin")
materials: int = 0
frame: str = "y_up_pos_z_front"
extra: dict[str, Any] = Field(default_factory=dict)
#: every mode the object rig draws (runtime_js/render_glb.mjs MODES)
RENDER_MODES = ("shaded", "wire", "normals", "silhouette", "clay")
class RenderView(BaseModel):
name: str
path: str
mode: str = "shaded"
width: int = 0
height: int = 0
camera_position: Vec3 | None = None
look_at: Vec3 | None = None
fov: float | None = None
time_s: float | None = Field(default=None, description="animation time for scenes")
judge: bool | None = Field(
default=None,
description="True/False once the judge subset is stamped at render time; None = not stamped",
)
class RenderSet(BaseModel):
views: list[RenderView] = Field(default_factory=list)
contact_sheet: str | None = Field(default=None, description="one labelled grid image of all views")
renderer: str = ""
duration_ms: int = 0
console_errors: list[str] = Field(default_factory=list, description="(scenes) JS/WebGL errors seen")
fps: float | None = Field(default=None, description="(scenes) measured frame rate: a record only — it swings with "
"the machine's load and renderer, so no gate or judge reads it")
out_dir: str = Field(default="", description="directory the views (+ views.json/metrics.json) were written to")
# ===================================================================== judgment
class JudgeIssue(BaseModel):
target: str = Field(description="part / zone / joint / asset / 'overall'")
kind: Literal[
"geometry", "proportion", "detail", "material", "assembly", "articulation",
"lighting", "composition", "animation", "effect", "fidelity", "scale", "bug",
]
severity: Literal["critical", "major", "minor"]
detail: str = Field(description="what is wrong, observable in the renders")
evidence: str = Field(default="", description="which view(s) / measurement show it")
class ImprovementItem(BaseModel):
target: str
kind: Literal["geometry", "material", "assembly", "articulation", "lighting", "composition", "animation", "effect", "bug"]
instruction: str = Field(description="concrete, actionable change for the builder")
priority: int = Field(ge=1, le=6, description="1 = do first (a plan holds at most 6 items)")
expected_gain: float = Field(default=0.0, ge=0.0, le=1.0)
class Judgment(BaseModel):
rubric: str
judge_backend: str = ""
scores: dict[str, float] = Field(description="criterion → 0..1")
overall: float = Field(ge=0.0, le=1.0, description="weighted by the rubric (computed in code)")
passed: bool
summary: str = ""
strengths: list[str] = Field(default_factory=list)
issues: list[JudgeIssue] = Field(default_factory=list)
improvement_plan: list[ImprovementItem] = Field(default_factory=list)
acceptance_results: dict[str, bool] = Field(default_factory=dict, description="acceptance item id → verified")
n_samples: int = 1
score_std: float = 0.0
raw: str = ""
@property
def degraded(self) -> bool:
"""A judge glitch (unparseable verdict), never a score."""
if self.summary.startswith("judge_error:"):
return True
try:
return json.loads(self.raw).get("status") == "degraded"
except (json.JSONDecodeError, AttributeError, TypeError):
return False