Skip to content

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.md
index 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). Headless
Chrome 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_v1
python -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.md
index 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.md
index 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:
```bash
cd 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-empty
settings 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 keys
come from). Duplicates are removed, order preserved. Keys are never written
into run records.
diff --git a/harness/docs/RUNBOOK.md b/harness/docs/RUNBOOK.md
index 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 r
python -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 clean
re-run (`tests/scene_runtime/lib/*` first, since those hold the renderer longest). A red
suite 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 the
PICKED 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 judge
gate (ships only when the score does not drop and the materials criterion improves).