Skip to content

Official Codebase of 3DCodeVerse

Python

docs: recipe seeding — GRAPHICS_LOOP §3 bullet, ARCHITECTURE package map, INTERFACES signatures + recipes.seeded event

gaoypengead201a70140
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.md
index 8d0f84ac..45f789f7 100644
--- a/harness/docs/ARCHITECTURE.md
+++ b/harness/docs/ARCHITECTURE.md
@@ -162,6 +162,9 @@ codeverse/
generation.py, repair.py, planner.py, prompting.py (prompt helpers, split from common),
common.py (RunContext, Services), motion.py, reference.py, static_object.py,
articulated_object.py, scene.py, scene_assets.py, graphics.py + graphics_steps.py,
+ graphics_recipes.py (the brief's verified cookbook recipes + their helpers written into
+ src/common.glsl before the session — measured: flash calls a recipe on disk, not one it
+ is shown; CV3D_SEED_RECIPES, docs/GRAPHICS_LOOP.md §3),
brief.py (cached EngineeringBrief: one cheap call turns a one-line prompt into
real dimensions / sub-assemblies / signature features; never fatal, CV3D_PLAN_BRIEF),
plan_budget.py (plan size derived from the request, capped per language),
diff --git a/harness/docs/GRAPHICS_LOOP.md b/harness/docs/GRAPHICS_LOOP.md
index d716b2ca..a56526d1 100644
--- a/harness/docs/GRAPHICS_LOOP.md
+++ b/harness/docs/GRAPHICS_LOOP.md
@@ -78,6 +78,20 @@ Eye scores: `scratchpad/gfx_eye.json` → copied to `bench/out/judge_calib_graph
_likeness_note`); the judge becomes `judges/reference.py::LikenessJudge` — the same photos
beside the frames, no silhouette IoU (that is an object-track measurement). Same battery with
the folder present vs absent is the A/B (`bench/prompts/refs_v1_graphics.yaml`, in flight).
+* **Seeded recipes** (`tracks/graphics_recipes.py`, `Settings.limits.seed_recipes` / `CV3D_SEED_RECIPES`,
+ default ON) — measured 2026-08-26 on `refs_v2_graphics` (aurora brief, flash api-agent, shader_v2): the
+ baseline prompt carried the cookbook's Light chapter with `curtain()` five times and `src/shader.frag` called
+ it zero times in both finished runs — round 0 a comb of bars (0.33), a later round a wash (0.12). Showing
+ flash a recipe is not flash using it, so the harness now writes the recipes the brief selects (the same
+ chapters `select_cookbook_chapters` puts in the prompt, minus the always-on helper chapters and the
+ raymarching template) into `src/common.glsl` before the session — function definitions only, plus exactly
+ the `hash / noise / fbm` helpers they call, under `// ---- harness-seeded verified recipes` — and the
+ baseline prompt names them ("call them, do not rewrite them"); the refine prompt carries a one-line
+ reminder; a resume appends only names the file does not define. The aurora brief seeds `skyGrad, sun,
+ stars, waterHeight, curtain, auroraCol, aurora` on top of the skeleton's helpers; the neon-rain brief
+ `dropsLayer, bokehSoft`; a brief matching no chapter seeds nothing and the prompt has no block. The event
+ is `recipes.seeded`; `CV3D_SEED_RECIPES=0` is the control arm. The number to watch stays the
+ `comb_artefact` firing rate — and now also `grep -c "curtain(" src/shader.frag`.
* **Measuring the turn** — `bench/judge_calib_graphics.py` re-judges the corpus under v1 and v2
(pro, n=2, no planner acceptance so the rubric is measured on its own) and prints
Spearman(judge, eye), means, defect firing rates and the biggest disagreements. The result of
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 60e1ece8..0c4ea740 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -346,6 +346,16 @@ from codeverse.tracks.detailing import drift_gate, detail_instructions, DRIFT_GA
# ERROR when a detail round moved/resized/removed a part or changed the overall extents (tol from policy)
from codeverse.tracks.prompting import base_prompt_context, reference_images, file_for_target_factory, \
scope_context, budget_for, detail_budget_text # Δ split out of
+from codeverse.tracks.prompting import select_cookbook_chapters, select_cookbook_excerpt, is_always_chapter
+ # select_cookbook_chapters(ctx, brief, *, budget=9000, always=COOKBOOK_ALWAYS) -> list[Section]: the header +
+ # always-on chapters + the brief's chapters (whole, cookbook order, inside budget); the excerpt joins them
+from codeverse.tracks.graphics_recipes import seed_recipes, graphics_brief, cookbook_functions, EXTRA_KEY
+ # seed_recipes(ctx) -> list[str]: glsl_shader + seed_recipes_enabled() only. Appends the selected chapters'
+ # function definitions (minus always-on chapters and the raymarching template) + the helpers they call to
+ # src/common.glsl under "// ---- harness-seeded verified recipes"; returns the names written THIS call;
+ # ctx.extra["seeded_recipes"] = [{name, signature, purpose}] for every seeded recipe on disk (the prompt
+ # block); emits recipes.seeded {names, present, chapters}. GraphicsTrack.prepare() runs it after the
+ # skeleton and commits "recipes" when it wrote something.
from codeverse.tracks.common import RunContext, Services # common.py
from codeverse.tracks.generation import generate, run_agent_task, parse_multifile, is_single_shot
GenerationTask.phase: int = 0 # tasks run in parallel WITHIN a phase, phases in ascending order
@@ -430,7 +440,7 @@ from codeverse.flywheel.index import build_index, query, summary # sqlite + pa
`EventLog.emit(event, **data)` writes `{"t", "event", ...}` (**Δ** key is `event`).
Event names: `run.start`, `stage.start/done`, `plan.done`, `workspace.materialized`,
`round.start`, `generate.done`, `build.done`, `gates.done`, `judge.done`,
-`round.done`, `best.updated`, `refine.planned`, `asset.judged`, `assets.done`,
+`round.done`, `best.updated`, `refine.planned`, `recipes.seeded` (graphics: names written this call, present on disk, chapters), `asset.judged`, `assets.done`,
`zones.done`, `assemble.done`, `round.no_change`, `candidates.start`,
`candidate.start/done/failed/retry/selected`, `pairwise.done`,
`texture.start/plan/generated/applied/gate/done`, `budget.exceeded`,