Official Codebase of 3DCodeVerse
Python
docs: keys, settings and test counts each keep one home — and texture pass textures the PICKED round
gaoypeng2055619e2d7d
diff --git a/harness/CLAUDE.md b/harness/CLAUDE.mdindex c356a0ca..d258b763 100644--- a/harness/CLAUDE.md+++ b/harness/CLAUDE.md@@ -49,9 +49,9 @@ push, with `set -o pipefail` so a `| tail` cannot swallow a red exit. The versi## Environment (this machine)- Gemini keys: `~/.config/astra3d/gemini_keys.env` (15 keys, the owner's list of 2026-09-22) → `get_settings().gemini_api_keys`(or `GEMINI_API_KEYS` / `GEMINI_API_KEY` env). Settings: `~/.config/3dcodeverse/config.yaml`- or `./3dcodeverse.yaml`, env prefix `C3D_` (the pre-D78 `CV3D_*` names are still read) (`C3D_RENDER__GPU=off`, `C3D_RUNS_DIR=…`,- `C3D_DEFAULT_CANDIDATES=2`). Every `C3D_*` switch is a `Settings` field read through `get_settings()`- where it is used — never read the environment by hand (one grammar: docs/INSTALL.md §8.3).+ or `./3dcodeverse.yaml`, env prefix `C3D_` (the pre-D78 `CV3D_*` names are still read; the+ grammar and examples: docs/INSTALL.md §8.3). Every `C3D_*` switch is a `Settings` field read through `get_settings()`+ where it is used — never read the environment by hand.- Blender 5.0.1 headless: `~/.local/bin/blender-5.0` (always `--factory-startup`; clear scene).- Node 24 (floor 20.6) + `runtime_js/node_modules` ([email protected], puppeteer; chrome cached). HeadlessChrome WebGL uses the GPU on WSL2 with `--use-angle=gl-egl` + Mesa d3d12 env (see@@ -106,9 +106,9 @@ python -m codeverse3d.addons.calibration runs/<slug>... --model gemini:gemini-3.python ../eval/bench/complexity_report.py ../eval/bench/out --recursive # score-vs-complexity + $/complexity point (eval/docs/COMPLEXITY.md)python ../eval/bench/compare_backends.py --prompts ../eval/bench/prompts/compare_v1.yaml --arms harness:gemini-cli:gemini-3.6-flash,oneshot:claude-code --judge gemini:gemini-3.1-pro-preview --out ../eval/bench/out/compare_v1python -m tests.prompts.manifest [--bless | --dump DIR] # what every model is shown, pinned (RUNBOOK §8): bless only a change a model is MEANT to see-python -m pytest tests -q -m "not live" # 2 688 tests, ~100 s (real Blender + headless Chrome + CadQuery)-python -m pytest tests -q -m "not live and not blender and not node" # pure python: 2 161 tests (the 244 bench tests: `cd ../eval && python -m pytest`)-# (the counts drift every commit — `--collect-only` is the answer, not a number in this file)+python -m pytest tests -q -m "not live" # the offline suite (real Blender + headless Chrome + CadQuery)+python -m pytest tests -q -m "not live and not blender and not node" # pure python (the bench tests: `cd ../eval && python -m pytest`)+# (how many: `--collect-only`; a count written here drifts every commit)# both run PARALLEL by default (pytest-xdist, -n auto --dist worksteal, in pyproject addopts).# A nested pytest inside a test MUST pass -n0 or it forks another full set of workers.```diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex e74bd67f..ee7d7ddb 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -529,8 +529,8 @@ shader-traps skill); before 2026-09-22 the scene's two never reached a round, an`texturing.run.texture_pass(ws, spec, plan, model_id=…)` — never inside a run: `3dcode pick--texture` (and `make --texture`, which picks after the run) texture the PICKED round's kept-`artifacts/rNN/object.glb`; a standalone `3dcode texture pass` textures the canonical one, i.e.-the last round:+`artifacts/rNN/object.glb`, and so does a standalone `3dcode texture pass` (the round+`addons.select` reports as picked):one VLM **material plan** (parts → shared texture ids, family, projection,`tile_size_m`; cached) → text-to-image tiles (`GeminiImageModel`,gemini-3.1-flash-image; mirror cross-fade makes them tileable, `seam_score ≤ 0.08`diff --git a/harness/docs/INSTALL.md b/harness/docs/INSTALL.mdindex 31ff191a..dfb11370 100644--- a/harness/docs/INSTALL.md+++ b/harness/docs/INSTALL.md@@ -150,8 +150,8 @@ Run the offline test suite to confirm the install:```bashcd harness-python -m pytest tests -q # needs node + Blender for the full set (~32 s)-python -m pytest tests -q -m "not live and not blender and not node" # pure-python subset (~27 s)+python -m pytest tests -q # needs node + Blender for the full set+python -m pytest tests -q -m "not live and not blender and not node" # pure-python subset# Parallel by default (pytest-xdist, -n auto --dist worksteal). Serial: add -n0.python -m pytest tests -q -m live # OPT-IN: real API calls, needs keys```@@ -337,7 +337,7 @@ driver installed on the Windows side for the d3d12 path — check with| variable | needed for | notes ||---|---|---|-| `GEMINI_API_KEYS` | all `gemini:*` models (planner, judge, captioner, generators) | comma-separated list; the whole list becomes one `KeyPool` (per-key rate limits, 30 s cooldown on 429, dead keys benched 1 h) |+| `GEMINI_API_KEYS` | all `gemini:*` models (planner, judge, captioner, generators) | comma-separated list; the whole list becomes one `KeyPool` (a 429 rotates to another key and cools the key ≤ 3 s, dead keys benched 1 h; no per-key RPM buckets since 2026-09-22) || `GEMINI_API_KEY` / `GOOGLE_API_KEY` | same | single-key fallback when `GEMINI_API_KEYS` is unset || `ANTHROPIC_API_KEY` | `anthropic:*` chat models | optional; not set here → those backends are unavailable (doctor WARN) || `OPENAI_API_KEY` | `openai:*` chat models | optional; `C3D_OPENAI_BASE_URL` points at a compatible gateway |@@ -346,7 +346,7 @@ Resolution order for the Gemini keys (`codeverse3d/config.py`), first non-emptysettings YAML `gemini_api_keys:` → `GEMINI_API_KEYS` (csv) → `GEMINI_API_KEY` /`GOOGLE_API_KEY` → the legacy compatibility file`~/.config/astra3d/gemini_keys.env`, from which a line-`GEMINI_API_KEYS="key1,key2,…"` is read (this is where the 21 keys on this box+`GEMINI_API_KEYS="key1,key2,…"` is read (this is where this box's keyscome from). Duplicates are removed, order preserved. Keys are never writteninto run records.diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.mdindex 8c1e4223..c8acb2d7 100644--- a/harness/docs/RUNBOOK.md+++ b/harness/docs/RUNBOOK.md@@ -18,26 +18,10 @@ python -m pytest tests -q -m live # OPT-IN: real API calls```### Keys and settings-* Gemini keys, in precedence order: `GEMINI_API_KEYS` (comma-separated) → `GEMINI_API_KEY`- / `GOOGLE_API_KEY` → legacy `~/.config/astra3d/gemini_keys.env` (21 keys here).- All `gemini:*` models share one `KeyPool` (900 rpm/key, 30 s cooldown on 429; dead- keys benched 1 h and re-probed; 429s rotate to fresh keys for free).- `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `C3D_OPENAI_BASE_URL` for the other- providers (not set on this box → `anthropic:*` / `openai:*` unavailable).-* Settings: `~/.config/3dcodeverse/config.yaml` or `./3dcodeverse.yaml`, overridden by env- with prefix `C3D_` and `__` nesting — e.g. `C3D_RUNS_DIR=/data/runs`,- `C3D_RENDER__GPU=off`, `C3D_BINARIES__BLENDER=/opt/blender/blender`,- `C3D_LIMITS__AGENT_TIMEOUT_S=900`, `C3D_DEFAULT_CANDIDATES=2`.- Defaults: runs_dir `runs/`, cache_dir `~/.cache/codeverse3d`, build/render timeout 300 s,- agent timeout 1800 s, bpy RLIMIT 12 GB, 6 parallel agents, 3 parallel builds,- `default_judge gemini:gemini-3.1-pro-preview`, `default_candidates 1`.-* Blender: `settings.binaries.blender` else first `blender-5.0`/`blender`/… on PATH.- Always `-b --factory-startup`; the child env strips `PYTHONPATH`/`PYTHONHOME`.-* GPU rendering: `runtime_js/gpu_launch.cjs` tries Chrome with `--use-angle=gl-egl` +- Mesa d3d12 env and falls back to SwiftShader; probe cached in- `~/.cache/codeverse3d/gpu_probe.json`. Force with `C3D_RENDER_GPU=on|off|auto` or- `settings.render.gpu`. The graphics track uses moderngl the same way (d3d12 GPU- context first, llvmpipe fallback; no probe needed — `GlHost` decides per process).+Gemini keys, the other providers' keys, the settings files, every `C3D_*` override, how+Blender is found and how the GPU path is chosen are `docs/INSTALL.md` §8, §6 and §7 (their+one home); each setting's default and description is its `Settings` field in+`codeverse3d/config.py`.## 2. Running each track@@ -191,8 +175,8 @@ unless you type `--host` yourself; it never serves a path outside the declared rpython -m codeverse3d.addons.calibration runs/<slug> [runs/<slug2> …] --model gemini:gemini-3.1-pro-preview --n 3 --out out/# re-judges recorded rounds; writes calibration_<model>.md/.json (never touches runs/)```-**Do not run the offline suite while a battery is running.** The suite is 2 300+ tests on-24 cores under xdist; a battery holds Blender, a browser pool and several agent sessions.+**Do not run the offline suite while a battery is running.** The suite runs thousands of tests+on 24 cores under xdist; a battery holds Blender, a browser pool and several agent sessions.Twice on 2026-09-04/05 that produced 11 and 21 spurious failures that vanished on a cleanre-run (`tests/scene_runtime/lib/*` first, since those hold the renderer longest). A redsuite during a battery is **not evidence until it reproduces on a quiet machine** — re-run@@ -284,8 +268,8 @@ stages are reused — this also recovers from Gemini 503 storms). Ctrl-C is saf`3dcode pick <slug> --texture` (or `--texture` on `make`, which picks after the run) textures thePICKED round's own `artifacts/rNN/object.glb` — once per round: a pass that already started from-those bytes is re-used, never re-bought; `3dcode texture pass <slug>` textures the canonical-`artifacts/object.glb`, i.e. the LAST round. Either way: one VLM material plan →+those bytes is re-used, never re-bought; `3dcode texture pass <slug>` textures the same picked+round's GLB. Either way: one VLM material plan →tileable texture images (gemini-3.1-flash-image, ~$0.07/tile, cached by prompt) →world-metre UVs → `artifacts/object_textured.glb` → seam gate + before/after judgegate (ships only when the score does not drop and the materials criterion improves).