Skip to content

Official Codebase of 3DCodeVerse

Python

Merge simplify lane L2

gaoypeng6dd90c19e4b3
diff --cc harness/CLAUDE.md
index 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-run
3dcodeverse make "..." --no-pick # a run = baseline + --rounds refine rounds (fixed); make then picks a round → deliverable/ unless --no-pick
3dcodeverse 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.md
index 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; Blender
5.2 LTS optional). Developed and measured on python 3.13 / node 24; there is no CI — the offline suite and
diff --cc harness/codeverse3d/cli/main.py
index 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 co
from codeverse3d.cli.flywheel_cmd import flywheel_app
from codeverse3d.cli.skills_cmd import skills_app
from 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 make
language = 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.py
index 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: str
track: 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 = 0
tags: list[str] = Field(default_factory=list)
created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
diff --cc harness/codeverse3d/tracks/lifecycle.py
index 6933eeeb,2bfc2e22..0e85645a
--- a/harness/codeverse3d/tracks/lifecycle.py
+++ b/harness/codeverse3d/tracks/lifecycle.py
@@@ -37,13 -37,8 +37,7 @@@ from codeverse3d.orchestrator import
from codeverse3d.proc import EventLog, fan_out, read_json_or_none
from codeverse3d.prompts import load_text, render
from 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_n
from codeverse3d.tracks.common import RunContext, Services
from codeverse3d.tracks.generation import ALLOWED_ROOTS, GenerationTask, single_shot_model_id
from codeverse3d.tracks.planner import plan as run_planner
diff --cc harness/docs/ARCHITECTURE.md
index 16e85e7d,39b386cc..edd3ea81
--- a/harness/docs/ARCHITECTURE.md
+++ b/harness/docs/ARCHITECTURE.md
@@@ -75,7 -76,7 +75,7 @@@ codeverse3d
get_settings() where it is used; an on/off switch is a Flag, Settings.FLAT holds the flat
spellings 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 snapshots
diff --cc harness/docs/INSTALL.md
index cd0f281f,b93216bf..36ac5ebe
--- a/harness/docs/INSTALL.md
+++ b/harness/docs/INSTALL.md
@@@ -374,9 -375,9 +374,8 @@@ export C3D_RUNS_DIR=/data/run
export C3D_BINARIES__BLENDER=/opt/blender/blender
export C3D_RENDER__GPU=off
export C3D_LIMITS__AGENT_TIMEOUT_S=900
-export C3D_DEFAULT_CANDIDATES=2
export C3D_DEFAULT_JUDGE=gemini:gemini-4-argon
export 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 description
diff --cc harness/docs/RUNBOOK.md
index 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 one
before 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