Official Codebase of 3DCodeVerse
Python
Merge simplify lane L2
gaoypeng6dd90c19e4b3
diff --cc harness/CLAUDE.mdindex 6b9b0ea3,098a5132..4e8a331b--- a/harness/CLAUDE.md+++ b/harness/CLAUDE.md@@@ -97,9 -97,8 +97,8 @@@ cd harnes# Every track states REQUIREMENTS, never templates (D106 scene, D107 the rest, 2026-10-15): no language ships a cookbook, no inlined# recipes, placeholder skeletons; a prompt / skill keeps only interface, sandbox rules and measured thresholds, each contract.md ONE# executable interface example (tests/prompts/test_snippets_run.py), the craft as short optional practices in the skills (fences ≤ ~12 lines).- 3dcodeverse make "..." --variant argon # per-model prompt/skill overlay: prompts/variants/<name>/ + skills/variants/<name>/ (D105; C3D_VARIANT, C3D_VARIANTS='{"agy:gemini-4-argon": "argon"}')3dcodeverse make "neon rain on a window" --track graphics --language glsl_shader-3dcodeverse make "..." --image ref.png --candidates 3 --rounds 2 --dim height=0.45 --must "three legs" --no-run+3dcodeverse make "..." --image ref.png --rounds 2 --dim height=0.45 --must "three legs" --no-run3dcodeverse make "..." --no-pick # a run = baseline + --rounds refine rounds (fixed); make then picks a round → deliverable/ unless --no-pick3dcodeverse pick <slug> [--by score|pairwise] [--round N] [--judge MODEL] # hand over a round (codeverse3d/addons/select.py)3dcodeverse resume <slug> · 3dcodeverse show <slug> [--section status] (`status` = its STATUS section) · 3dcodeverse render <slug> [--mode wire] · 3dcodeverse judge <slug> [--model ... --n 3 --thinking medium]diff --cc harness/README.mdindex 341a899f,112cb6fe..776b8302--- a/harness/README.md+++ b/harness/README.md@@@ -28,41 -28,10 +28,9 @@@ renders, judges, refines and records ev## Architecture- Every run is **spec → plan → skeleton → [scene stages] → baseline round →- refine rounds → finalise → record**. The package tree:-Every run is **spec → plan → skeleton → [scene stages] → baseline round (best-of-N-optional) → refine rounds → finalise → record**. The package tree is `docs/ARCHITECTURE.md` §2.++Every run is **spec → plan → skeleton → [scene stages] → baseline round → refine rounds → finalise → record**. The package tree is `docs/ARCHITECTURE.md` §2.- ```- codeverse3d/- contracts/ typed pydantic contracts: Track/Language/Usage/Budget/Backends,- Spec, plans, artifacts, run record, AgentJob- conventions.py frames, units, views, naming, tolerances (THE constants source)- config.py Settings (C3D_* env + config.yaml) · workspace.py run-dir layout + git snapshots- proc.py stdlib-only subprocess/JSON/JSONL primitives, run lock, fan-out (a leaf)- orchestrator.py the round loop's library: stage runner + resume state, round knobs, the clock- tracks/ the four track pipelines + the round loop, the one planner loop, generation strategies- (vendor-CLI agent / single-shot), repair, skills hook- languages/ one merged module per language (lint → skeleton → runtime) beside its- data dirs: blender cadquery threejs urdf scene_threejs scene_blender glsl_shader opengl_python- agents/ CodingAgent protocol + the vendor-CLI backends (claude-code,- codex, antigravity): sessions, watchdog clocks, transcripts- models/ ChatModel + gemini/anthropic/openai adapters; key-pool retry machine,- streaming with stall detection, IPv4-pinned transport, pricing, health- spatial/ the measurement/render toolbox behind every gate and MCP tool- judges/ rubric VLM judge on labelled montages, pairwise, reference/likeness- reference.py a user `--image` against the render: proportion check, mismatch diff- cost/ append-only ledger, metering, per-block tallies, pre-call estimates- skills/ typed skill routes + materialisation + read telemetry- record/ what every run writes: record.json, deliverable/, telemetry- addons/ optional tools that READ finished runs — nothing a run needs:- gallery (the runs browser), dataset (export, tiers, preference/repair pairs,- captions), costreport (`3dcodeverse cost`), calibration, skill_targets- cli/ the typer CLI · doctor.py the environment checks behind `3dcodeverse doctor`- ../eval/bench/ the evaluation harness around the harness: run_bench, compare_backends- (A/B matrix), ab_plan, infra-failure classification- runtime_js/ node side: [email protected] + headless-Chrome render/probe hosts- ```-- Design laws, the full package map and what each stage does: `docs/ARCHITECTURE.md`.+ Design laws and what each stage does: `docs/ARCHITECTURE.md`.**Supported versions:** python **3.13** and node **20.6+** (Linux x86_64; Blender5.2 LTS optional). Developed and measured on python 3.13 / node 24; there is no CI — the offline suite anddiff --cc harness/codeverse3d/cli/main.pyindex 315aa3a8,ea7654f8..66f0e650--- a/harness/codeverse3d/cli/main.py+++ b/harness/codeverse3d/cli/main.py@@@ -30,8 -30,8 +30,8 @@@ from codeverse3d.cli.cost_cmd import cofrom codeverse3d.cli.flywheel_cmd import flywheel_appfrom codeverse3d.cli.skills_cmd import skills_appfrom codeverse3d.config import get_settings-from codeverse3d.contracts.common import TRACK_INFO, TRACK_LANGUAGES, Budget, Language, Track-from codeverse3d.contracts.spec import Constraints, ReferenceImage, RunOptions, Spec+from codeverse3d.contracts.common import TRACK_LANGUAGES, Budget, Language, Track- from codeverse3d.contracts.spec import Constraints, ReferenceImage, RunOptions, Spec++from codeverse3d.contracts.spec import Constraints, ReferenceImage, Spec# ===================================================================== doctor@@@ -307,10 -314,12 +298,8 @@@ def makelanguage = TRACK_LANGUAGES[track][0]run_slug = C.make_slug(prompt, track.value, language.value, slug)settings = get_settings()- if candidates is None:- candidates = settings.default_candidates- if candidates > 1 and not TRACK_INFO[track].best_of_n:- raise _no_best_of_n(track)backends = settings.backends(generator=generator, planner=planner, judge=judge)C.check_backends(backends)- # resolved once here and frozen on the spec- chosen = C.resolve_variant(settings, backends.generator, variant)# validate the whole Spec before touching the filesystem (no orphan run directory)try:spec = Spec(@@@ -328,7 -337,8 +317,6 @@@budget=Budget(**{k: v for k, v in{"max_rounds": rounds, "max_minutes": max_minutes}.items() if v is not None}),backends=backends,- options=RunOptions(variant=chosen.name),- options=RunOptions(candidates=candidates),- seed=seed,tags=tag,)except ValueError as e:@@@ -350,7 -360,7 +338,6 @@@"judge": f"{backends.judge} n={settings.judge.samples} "f"({settings.judge.max_px}px/{settings.judge.detail_crops}crop)","rounds": spec.budget.max_rounds,- "variant": chosen.label,- "candidates": candidates,},))diff --cc harness/codeverse3d/contracts/spec.pyindex d0efa327,b5dfd455..a59c840c--- a/harness/codeverse3d/contracts/spec.py+++ b/harness/codeverse3d/contracts/spec.py@@@ -61,17 -61,16 +61,6 @@@ class ProjectCheck(BaseModel)args: dict[str, Any] = Field(default_factory=dict, description="keyword data passed to the check as args=")--class RunOptions(BaseModel):-- """Run-shape options frozen on the spec (distinct from Budget and Backends).--- ``None`` / ``False`` means "not stated".- ``None`` / ``False`` means "not stated": the resolver falls through to its- ``Settings`` default (``BaseTrack._resolve_candidates``).-- """--- variant: str = Field(default="", description="per-model prompt/skill variant this run was created with "- "(codeverse3d/prompts/variants/<name>/, D105); '' = the base prompts and skills; "- "frozen here so a resume and the record name the same overlay")- candidates: int | None = Field(default=None, ge=1, description="best-of-N baseline candidates")----class Spec(BaseModel):id: strtrack: Track@@@ -86,7 -85,8 +75,6 @@@description="project checks run on every round's GLB (ProjectCheck)")budget: Budget = Field(default_factory=Budget)backends: Backends = Field(default_factory=Backends)-- options: RunOptions = Field(default_factory=RunOptions)- seed: int = 0tags: list[str] = Field(default_factory=list)created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))diff --cc harness/codeverse3d/tracks/lifecycle.pyindex 6933eeeb,2bfc2e22..0e85645a--- a/harness/codeverse3d/tracks/lifecycle.py+++ b/harness/codeverse3d/tracks/lifecycle.py@@@ -37,13 -37,8 +37,7 @@@ from codeverse3d.orchestrator importfrom codeverse3d.proc import EventLog, fan_out, read_json_or_nonefrom codeverse3d.prompts import load_text, renderfrom codeverse3d.prompts.catalog import language_text- from codeverse3d.prompts.variants import (- activate,- active_variant,- resolve_variant,- variant_block,- )from codeverse3d.record.record import previous_verdict-from codeverse3d.tracks.candidates import run_best_of_nfrom codeverse3d.tracks.common import RunContext, Servicesfrom codeverse3d.tracks.generation import ALLOWED_ROOTS, GenerationTask, single_shot_model_idfrom codeverse3d.tracks.planner import plan as run_plannerdiff --cc harness/docs/ARCHITECTURE.mdindex 16e85e7d,39b386cc..edd3ea81--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@@ -75,7 -76,7 +75,7 @@@ codeverse3dget_settings() where it is used; an on/off switch is a Flag, Settings.FLAT holds the flatspellings of nested knobs (docs/INSTALL.md §8.3)contracts/ pydantic: common (Track, Language, Usage, Budget, Backends, TRACK_INFO registry,-- ENTRY_FILE/code_file/LANGUAGE_LABEL tables), spec (+ RunOptions), plan, artifacts++ ENTRY_FILE/code_file/LANGUAGE_LABEL tables), spec, plan, artifacts(GateFinding, GateReport, BuildResult.gates, RenderView, RenderSet, Judgment), run(+ SkillsUsage/SkillRead), chat, agent (typed AgentJob)workspace.py run-dir layout + git snapshotsdiff --cc harness/docs/INSTALL.mdindex cd0f281f,b93216bf..36ac5ebe--- a/harness/docs/INSTALL.md+++ b/harness/docs/INSTALL.md@@@ -374,9 -375,9 +374,8 @@@ export C3D_RUNS_DIR=/data/runexport C3D_BINARIES__BLENDER=/opt/blender/blenderexport C3D_RENDER__GPU=offexport C3D_LIMITS__AGENT_TIMEOUT_S=900-export C3D_DEFAULT_CANDIDATES=2export C3D_DEFAULT_JUDGE=gemini:gemini-4-argonexport C3D_JUDGE__THINKING=medium- export C3D_VARIANTS='{"agy:gemini-4-argon": "argon"}' # per-model prompt/skill variant by exact generator id; C3D_VARIANT=argon names one for every run```Every knob the harness reads is a `Settings` field (`codeverse3d/config.py`, one descriptiondiff --cc harness/docs/RUNBOOK.mdindex d27017b5,b6ca1496..3a310294--- a/harness/docs/RUNBOOK.md+++ b/harness/docs/RUNBOOK.md@@@ -43,18 -43,17 +43,13 @@@ Useful flags (`3dcodeverse make --help`refine tasks.* `--rounds N` — refine rounds after the baseline. A run does exactly N, each built on the onebefore it, unless the clock or a hard failure stops it; there is no pass / plateau stop.-* `--candidates N` — best-of-N baseline: N parallel candidates in `<ws>/_cand/`, quick-judged,- the highest quick score kept (fewer gate errors on a tie); multiplies baseline cost ≈ N;- object and graphics tracks only (a scene writes its baseline in its stages).* `--no-pick` — package nothing (no `deliverable/`, no `selection.json`; `3dcodeverse pick` later).-* `--max-minutes`, `--dim height=0.45`, `--must`, `--must-not`, `--style`, `--tag`, `--seed` (a- label: it re-keys the plan, nothing else is seeded by it), `--slug`, `--runs-dir`, `--force`,+* `--max-minutes`, `--dim height=0.45`, `--must`, `--must-not`, `--style`, `--tag`, `--slug`, `--runs-dir`, `--force`,`--no-run` (workspace + spec.json only).- * `--variant NAME` — a per-model prompt/skill overlay (`codeverse3d/prompts/variants/<name>/` +- `codeverse3d/skills/variants/<name>/`), frozen on `spec.options.variant` so `resume` and- `judge` read the same files; default `C3D_VARIANT`, else `C3D_VARIANTS` keyed by the exact- generator id, else the base prompts.- Expected cost/time with gemini-3.8-flash: object tracks ≈ $0.7–0.9 and 12–36 min for baseline +- 1 refine; graphics single-shot ≈ $0.05 / 2 min per judged- round; scenes ≈ $2.3 and 30 min before the first judged round, then ≈ $0.36 / ~7 min per refine- (give scenes `--max-minutes 60`). Actual spend: `3dcodeverse cost <slug>`.+ Expected cost with the default `agy:gemini-4-argon` generator (median `total_usage` over the recorded+ Oct-Nov runs, mixed round counts): static_object ≈ $2.2, articulated ≈ $4.2, graphics ≈ $4.4, scene ≈+ $10.4; give scenes `--max-minutes 60` or more. Actual spend: `3dcodeverse cost <slug>`.## 3. Backends