Skip to content

Official Codebase of 3DCodeVerse

Python

planner: every track through one loop dispatched on spec.track — graphics stops parameterising it with six hooks

gaoypengb99daf617c63
diff --git a/harness/codeverse3d/record/telemetry.py b/harness/codeverse3d/record/telemetry.py
index 4e740f63..88a467a1 100644
--- a/harness/codeverse3d/record/telemetry.py
+++ b/harness/codeverse3d/record/telemetry.py
@@ -86,15 +86,10 @@ def _judge_defaults() -> dict[str, Any]:
def _planner_defaults(record: RunRecord) -> dict[str, Any]:
- """The temperature THIS track plans at (``BaseTrack.plan_temperature``: graphics 0.5, the
- rest 0.4). ``planner.plan()``'s own default is never the one used — every track passes
- its own — so reading it reported 0.4 for every graphics run."""
- try:
- from codeverse3d.tracks import get_track
+ """The temperature THIS track plans at (``planner.plan_temperature``: graphics 0.5, the rest 0.4)."""
+ from codeverse3d.tracks.planner import plan_temperature
- return {"temperature": get_track(record.spec.track).plan_temperature}
- except Exception: # pragma: no cover
- return {}
+ return {"temperature": plan_temperature(record.spec.track)}
def _generator_defaults(model_id: str) -> dict[str, Any]:
diff --git a/harness/codeverse3d/tracks/graphics.py b/harness/codeverse3d/tracks/graphics.py
index ffee83e4..ad28be46 100644
--- a/harness/codeverse3d/tracks/graphics.py
+++ b/harness/codeverse3d/tracks/graphics.py
@@ -2,11 +2,12 @@
Languages: glsl_shader (Shadertoy-style fragment shader) · opengl_python (raw
moderngl program). Reuses ``BaseTrack`` (lifecycle) and ``run_round`` (steps)
-unchanged; the track-specific pieces are the planner hooks (template / example /
-acceptance, below), the prompt context (no 3D frame), the
-``gl_frames`` gate (frame statistics from the build) and the render step (the
-sampled frames + contact sheet as the RenderSet the ``shader_v2`` judge sees).
-Refinement is always one whole-program task.
+unchanged; the track-specific pieces are the recipe seeding, the prompt context
+(no 3D frame), the ``gl_frames`` gate (frame statistics from the build) and the render
+step (the sampled frames + contact sheet as the RenderSet the ``shader_v2`` judge sees).
+Planning is ``tracks/planner.py``'s, like every track's (template, worked example,
+T = 0.5, acceptance: all dispatched on the track there). Refinement is always one
+whole-program task.
"""
from __future__ import annotations
@@ -28,9 +29,8 @@ from codeverse3d.contracts.artifacts import (
Severity,
)
from codeverse3d.contracts.common import HARNESS_OWNED_SRC, TRACK_INFO, Language, Track
-from codeverse3d.contracts.plan import AcceptanceItem, GraphicsPlan, Plan
+from codeverse3d.contracts.plan import GraphicsPlan, Plan
from codeverse3d.contracts.run import RoundRecord
-from codeverse3d.contracts.spec import Spec
from codeverse3d.languages._gl_common import SHEET_NAME, read_metrics
from codeverse3d.languages.glsl_shader import COMMON_GLSL, FUNC_DEF, strip_comments
from codeverse3d.orchestrator import TaskGroup
@@ -39,7 +39,6 @@ from codeverse3d.prompts.sections import Section, split_sections
from codeverse3d.tracks.common import RunContext
from codeverse3d.tracks.generation import GenerationTask
from codeverse3d.tracks.lifecycle import BaseTrack, StageRunner
-from codeverse3d.tracks.planner import add_acceptance_item
from codeverse3d.tracks.prompting import (
base_prompt_context,
is_always_chapter,
@@ -276,57 +275,13 @@ def seed_recipes(ctx: RunContext) -> list[str]:
return [r.name for r in new]
-# ===================================================================== planner hooks + prompt context + frames
-PLAN_TEMPLATE = "tracks/plan_graphics.j2"
-PLAN_TEMPERATURE = 0.5
-PLAN_MAX_OUTPUT_TOKENS = 65_536 # the model's declared output ceiling; unused tokens cost nothing
+# ===================================================================== prompt context + frames
EXPECTED_FILES: dict[Language, list[str]] = {
Language.GLSL_SHADER: ["src/shader.frag", "src/common.glsl"],
Language.OPENGL_PYTHON: ["src/program.py"],
}
-# ----------------------------------------------------------------------------- planner
-def plan_example() -> dict[str, Any]: # the graphics worked example (planner hook)
- return {
- "title": "Neon rain on a window", "summary": "Looking through a rain-streaked window at a neon-lit street at night; "
- "drops run down the glass, city lights turn into coloured bokeh discs that pulse.",
- "style": "cyberpunk night: deep indigo/black base, magenta + cyan neon accents, warm sodium highlights; soft, filmic",
- "resolution": [1280, 720], "duration_s": 8.0,
- "passes": [
- {"name": "CityBokeh", "kind": "fullscreen", "description": "background: 40-60 blurred bokeh discs (hash-placed, 3 depth layers, cyan/magenta/amber), slow horizontal parallax, pulsing brightness"},
- {"name": "RainDrops", "kind": "fullscreen", "description": "grid-cell drops with hash offsets, running trails (fract(t) per cell), refraction offset applied when sampling the background"},
- {"name": "Grade", "kind": "postprocess", "description": "vignette, slight chromatic aberration, tonemap + gamma"},
- ],
- "uniforms": ["u_time", "u_resolution"],
- "motion": "drops slide down with gravity and wobble; bokeh drifts left 0.02/s and pulses at 0.5-1 Hz; no hard cuts",
- "key_visuals": ["rain drops with trails on glass", "blurred neon bokeh discs", "dark night street behind", "magenta/cyan palette"],
- "acceptance": [
- {"id": "a1", "text": "Raindrops with trails visibly run down the glass (compare t=0 and t=1)", "how": "visual", "priority": "must"},
- {"id": "a2", "text": "Blurred coloured bokeh lights are visible in the background", "how": "visual", "priority": "must"},
- {"id": "a3", "text": "Frames change over time (no static image)", "how": "probe", "priority": "must"},
- ],
- }
-
-
-def ensure_graphics_acceptance(plan: GraphicsPlan, spec: Spec) -> GraphicsPlan:
- """Spec must_have / must_not → visual items; planned motion → a probe item (never 'ground contact')."""
- items: list[AcceptanceItem] = list(plan.acceptance)
- for m in spec.constraints.must_have:
- add_acceptance_item(items, "must", f"Includes: {m}", "visual")
- for m in spec.constraints.must_not:
- add_acceptance_item(items, "not", f"Does NOT include: {m}", "visual")
- if plan.motion.strip() and not any("static" in a.text.lower() or "motion" in a.text.lower() or "change over time" in a.text.lower() for a in items):
- add_acceptance_item(items, "motion", "Frames change over time as planned (not a static image)", "probe")
- plan.acceptance = items
- return plan
-
-
-def graphics_event_stats(plan: GraphicsPlan) -> dict[str, Any]:
- """``plan.done`` payload for graphics (passes, not parts/zones)."""
- return {"n_passes": len(plan.passes), "n_acceptance": len(plan.acceptance)}
-
-
# ----------------------------------------------------------------------------- prompt context
def graphics_expected_files(ctx: RunContext) -> list[str]:
return list(EXPECTED_FILES.get(ctx.language, ["src/shader.frag"]))
@@ -424,26 +379,12 @@ class GraphicsTrack(BaseTrack):
plan_model = GraphicsPlan
generate_template = "tracks/generate_graphics.j2"
refine_template = "tracks/refine_graphics.j2"
- # planner hooks: own template/example/acceptance, T=0.5, 65 536 tokens (no 3D frame)
- plan_template = PLAN_TEMPLATE
- plan_temperature = PLAN_TEMPERATURE
- plan_max_output_tokens = PLAN_MAX_OUTPUT_TOKENS
# refinement is always ONE whole-program task
allow_refine_fanout = False
def make_pipeline(self) -> GraphicsPipeline:
return GraphicsPipeline()
- # ------------------------------------------------------------------ planner hooks
- def plan_example(self, spec: Spec) -> dict[str, Any]:
- return plan_example()
-
- def finalise_plan(self, plan_obj: Any, spec: Spec) -> Any:
- return ensure_graphics_acceptance(plan_obj, spec)
-
- def plan_event_stats(self, plan_obj: Any) -> dict[str, Any]:
- return graphics_event_stats(plan_obj)
-
# ------------------------------------------------------------------ prepare
def prepare(self, ctx: RunContext, runner: StageRunner) -> None:
"""Skeleton, then the brief's verified cookbook recipes into the harness-owned, read-only
diff --git a/harness/codeverse3d/tracks/lifecycle.py b/harness/codeverse3d/tracks/lifecycle.py
index c3f18781..37257ff2 100644
--- a/harness/codeverse3d/tracks/lifecycle.py
+++ b/harness/codeverse3d/tracks/lifecycle.py
@@ -1,9 +1,9 @@
"""BaseTrack: the resumable plan → prepare → rounds → finalise lifecycle.
Concrete tracks (static / articulated / scene / graphics) override the hooks
-(``plan_model``, ``make_pipeline``, ``prepare``, ``baseline_tasks``, the planner
-knobs ``plan_template``/``plan_example``/``finalise_plan`` and the refine
-scaffold's ``_refine_task``). All bookkeeping — workspace, events, budget, run
+(``plan_model``, ``make_pipeline``, ``prepare``, ``baseline_tasks`` and the refine
+scaffold's ``_refine_task``); what differs per track at PLANNING time is
+``tracks/planner.py``'s alone. All bookkeeping — workspace, events, budget, run
state, stage cache, the fixed round count, record — lives here once. Which round of a
finished run to hand over is not the core's question: ``codeverse3d.addons.select``.
"""
@@ -50,9 +50,7 @@ from codeverse3d.tracks.common import (
load_prompt_or,
)
from codeverse3d.tracks.generation import GenerationTask, single_shot_model_id
-from codeverse3d.tracks.planner import default_event_stats, ensure_acceptance, normalise_names
from codeverse3d.tracks.planner import plan as run_planner
-from codeverse3d.tracks.planner import plan_example as default_plan_example
from codeverse3d.tracks.prompting import (
base_prompt_context,
expected_files,
@@ -142,18 +140,13 @@ class SpecChanged(RuntimeError):
class BaseTrack:
"""Shared lifecycle. Subclasses set ``track``, ``rubric``, ``plan_model``
- and parameterise the ONE planner loop / refine scaffold via the hook
- attributes below (``plan_template``, ``plan_example``, ``_refine_task`` …)."""
+ and parameterise the refine scaffold via the hooks below (``_refine_task`` …)."""
track: Track
rubric: str
plan_model: type[Plan]
generate_template: str = ""
refine_template: str = ""
- #: planner knobs (GraphicsTrack: own template/example, T=0.5, 65 536 tokens)
- plan_template: str | None = None # None → tracks/plan_<track>.j2
- plan_temperature: float = 0.4
- plan_max_output_tokens: int = 24000
#: refine fan-out (graphics is always ONE whole-program task)
allow_refine_fanout: bool = True
#: share of the run budget the BASELINE may use (1.0 = no soft cap). The scene
@@ -213,19 +206,6 @@ class BaseTrack:
still returns False."""
return (ctx.ws.root / "rounds" / "candidates.json").is_file()
- # ---- planner hooks (tracks/planner.py runs the one loop)
- def plan_example(self, spec: Spec) -> dict[str, Any]:
- """Worked example JSON for the plan system prompt."""
- return default_plan_example(spec.track)
-
- def finalise_plan(self, plan_obj: Any, spec: Spec) -> Any:
- """Post-validation fixup (names + deterministic acceptance items)."""
- return ensure_acceptance(normalise_names(plan_obj), spec)
-
- def plan_event_stats(self, plan_obj: Any) -> dict[str, Any]:
- """Extra ``plan.done`` payload (n_parts/n_zones… per track)."""
- return default_event_stats(plan_obj)
-
# ---- refine hooks (the scaffold below is shared; tracks fill in the task)
def refine_file_for_target(self, ctx: RunContext) -> Any:
"""``target → [files]`` mapper for refine tasks (None = whole-object language)."""
@@ -482,16 +462,11 @@ class BaseTrack:
ctx.state.save(ctx.ws)
try:
plan = run_planner(ctx.spec, ctx.spec.backends.planner, self.plan_model, ctx.ws, model=self._planner_model,
- events=ctx.events, budget=ctx.budget, runtime=ctx.runtime, **self._plan_kwargs(ctx.spec))
+ events=ctx.events, budget=ctx.budget, runtime=ctx.runtime)
finally:
self._save_budget(ctx) # charged on success AND PlanningError
return plan
- def _plan_kwargs(self, spec: Spec) -> dict[str, Any]:
- return {"template": self.plan_template, "example": self.plan_example(spec),
- "temperature": self.plan_temperature, "max_output_tokens": self.plan_max_output_tokens,
- "finalise": lambda p: self.finalise_plan(p, spec), "event_stats": self.plan_event_stats}
-
# ------------------------------------------------------------------ stages
def stage_skeleton(self, ctx: RunContext, runner: StageRunner) -> list[str]:
def _do() -> list[str]:
diff --git a/harness/codeverse3d/tracks/planner.py b/harness/codeverse3d/tracks/planner.py
index 67ee5545..723bcac2 100644
--- a/harness/codeverse3d/tracks/planner.py
+++ b/harness/codeverse3d/tracks/planner.py
@@ -1,4 +1,10 @@
-"""Planner: spec → validated Plan (StaticPlan / ArticulatedPlan / ScenePlan).
+"""Planner: spec → validated Plan (StaticPlan / ArticulatedPlan / ScenePlan / GraphicsPlan).
+
+The ONE owner of what differs per track at planning time — the system-prompt template
+(``PLAN_TEMPLATES``), the worked example (``plan_example``), the sampling temperature
+(``plan_temperature``), the output-token floor, the plan budget's unit (graphics counts
+passes) and the deterministic acceptance items (``ensure_acceptance``): all dispatched on
+``spec.track``, so no track class parameterises the loop.
An optional cheap **brief expansion** (``expand_brief``, below) turns the one-line
request into an engineering brief, which — together with a **plan budget derived
@@ -20,7 +26,6 @@ import hashlib
import json
import logging
import re
-from collections.abc import Callable
from dataclasses import dataclass
from pathlib import Path
from typing import Any, TypeVar
@@ -482,6 +487,26 @@ def enrich_plan(plan_obj: Any, brief: EngineeringBrief | None) -> Any:
# ===================================================================== worked examples
def plan_example(track: Track) -> dict[str, Any]:
"""Compact, valid worked example per track (concrete beats abstract)."""
+ if track is Track.GRAPHICS:
+ return {
+ "title": "Neon rain on a window", "summary": "Looking through a rain-streaked window at a neon-lit street at night; "
+ "drops run down the glass, city lights turn into coloured bokeh discs that pulse.",
+ "style": "cyberpunk night: deep indigo/black base, magenta + cyan neon accents, warm sodium highlights; soft, filmic",
+ "resolution": [1280, 720], "duration_s": 8.0,
+ "passes": [
+ {"name": "CityBokeh", "kind": "fullscreen", "description": "background: 40-60 blurred bokeh discs (hash-placed, 3 depth layers, cyan/magenta/amber), slow horizontal parallax, pulsing brightness"},
+ {"name": "RainDrops", "kind": "fullscreen", "description": "grid-cell drops with hash offsets, running trails (fract(t) per cell), refraction offset applied when sampling the background"},
+ {"name": "Grade", "kind": "postprocess", "description": "vignette, slight chromatic aberration, tonemap + gamma"},
+ ],
+ "uniforms": ["u_time", "u_resolution"],
+ "motion": "drops slide down with gravity and wobble; bokeh drifts left 0.02/s and pulses at 0.5-1 Hz; no hard cuts",
+ "key_visuals": ["rain drops with trails on glass", "blurred neon bokeh discs", "dark night street behind", "magenta/cyan palette"],
+ "acceptance": [
+ {"id": "a1", "text": "Raindrops with trails visibly run down the glass (compare t=0 and t=1)", "how": "visual", "priority": "must"},
+ {"id": "a2", "text": "Blurred coloured bokeh lights are visible in the background", "how": "visual", "priority": "must"},
+ {"id": "a3", "text": "Frames change over time (no static image)", "how": "probe", "priority": "must"},
+ ],
+ }
if track is Track.SCENE:
return {
"title": "Harbour at dusk", "summary": "Small fishing harbour: quay, two boats, lighthouse, calm water.",
@@ -747,7 +772,16 @@ PLAN_TEMPLATES: dict[Track, str] = {
Track.STATIC_OBJECT: "tracks/plan_static.j2",
Track.ARTICULATED_OBJECT: "tracks/plan_articulated.j2",
Track.SCENE: "tracks/plan_scene.j2",
+ Track.GRAPHICS: "tracks/plan_graphics.j2", # no 3D frame: passes, uniforms, motion
}
+#: the output-token floor ``plan_tokens`` grows from; a graphics plan starts at the model's ceiling
+PLAN_OUTPUT_FLOOR = 24_000
+
+
+def plan_temperature(track: Track) -> float:
+ """What the planner samples at: 0.5 for a shader brief, 0.4 for everything else. THE value —
+ ``record/telemetry`` reports this function, not a default it guesses."""
+ return 0.5 if track is Track.GRAPHICS else 0.4
class PlanningError(RuntimeError):
@@ -761,12 +795,11 @@ class PlanningError(RuntimeError):
self.usage = usage or Usage()
-#: hook types (BaseTrack subclasses parameterise the ONE planner loop with these)
-FinalisePlan = Callable[[Any], Any]
-EventStats = Callable[[Any], dict[str, Any]]
-
-
-def default_event_stats(plan_obj: Any) -> dict[str, Any]:
+def plan_event_stats(plan_obj: Any) -> dict[str, Any]:
+ """The ``plan.done`` payload: a graphics plan counts passes, every other plan parts and zones."""
+ passes = getattr(plan_obj, "passes", None)
+ if passes is not None:
+ return {"n_passes": len(passes), "n_acceptance": len(plan_obj.acceptance)}
parts = getattr(plan_obj, "parts", []) or []
return {"n_parts": len(parts),
"n_zones": len(getattr(plan_obj, "zones", []) or []),
@@ -779,16 +812,11 @@ def default_event_stats(plan_obj: Any) -> dict[str, Any]:
def plan[P: BaseModel](spec: Spec, model_id: str, plan_model: type[P], ws: Workspace, *, model: Any | None = None,
- events: Any | None = None, budget: Any | None = None, runtime: Any | None = None,
- template: str | None = None, example: dict[str, Any] | None = None, temperature: float = 0.4,
- max_output_tokens: int = 24000, finalise: FinalisePlan | None = None,
- event_stats: EventStats | None = None) -> P:
+ events: Any | None = None, budget: Any | None = None, runtime: Any | None = None) -> P:
"""Plan and write ``ws.plan_path``: optional brief expansion → one structured planner
call → re-asks (schema, quality, a degenerate-plan restart). ``model`` may be injected (tests).
-
- Parameterised by the track hooks: ``template``/``example`` (system prompt),
- ``finalise`` (post-validation fixup, default = ``ensure_acceptance(normalise_names(...))``)
- and ``event_stats`` (extra ``plan.done`` payload).
+ Everything that differs per track is looked up from ``spec.track`` (module docstring);
+ the validated plan is finalised by ``ensure_acceptance(normalise_names(...))``.
The two re-asks have SEPARATE budgets and different complaints:
``MAX_VALIDATION_REASKS`` for a plan the schema rejects, ``MAX_QUALITY_REASKS`` for a
@@ -821,7 +849,7 @@ def plan[P: BaseModel](spec: Spec, model_id: str, plan_model: type[P], ws: Works
guard.add(usage, stage="plan")
budget = plan_budget(spec, brief)
unit = "passes" if spec.track is Track.GRAPHICS else "parts"
- system = build_system_prompt(spec, plan_model, runtime=runtime, template=template, example=example, budget=budget)
+ system = build_system_prompt(spec, plan_model, runtime=runtime, budget=budget)
user = build_user_prompt(spec, brief=brief, budget=budget, unit=unit)
images = [ImagePart(path=r.path, label=f"{r.role}: {r.note}".strip(": ")) for r in spec.references]
messages = [ChatMessage.user(user, images=images or None)]
@@ -829,13 +857,13 @@ def plan[P: BaseModel](spec: Spec, model_id: str, plan_model: type[P], ws: Works
schema = plan_model.model_json_schema()
last_error = ""
invalid = requeried = grown = restarts = 0
- tokens = plan_tokens(budget, max_output_tokens)
+ tokens = plan_tokens(budget, PLAN_TOKENS_MAX if spec.track is Track.GRAPHICS else PLAN_OUTPUT_FLOOR)
thinking = "medium"
wait_scale = 1.0
# 4 = the first call + truncation retries; it was 2 + the geometry re-ask's 2 (D49, code
# removed 2026-09-21) — the total is kept so a default run has the attempts it always had
for attempt in range(4 + MAX_VALIDATION_REASKS + MAX_QUALITY_REASKS + MAX_PLAN_RESTARTS):
- req = ChatRequest(messages=messages, system=system, response_schema=schema, temperature=temperature,
+ req = ChatRequest(messages=messages, system=system, response_schema=schema, temperature=plan_temperature(spec.track),
thinking=thinking, max_output_tokens=tokens, label=f"planner{'-retry' if attempt else ''}",
max_wait_s=plan_wait_s(tokens, guard, scale=wait_scale))
try:
@@ -921,12 +949,10 @@ def plan[P: BaseModel](spec: Spec, model_id: str, plan_model: type[P], ws: Works
normalised = list(getattr(result, "normalisations", None) or [])
if normalised and events is not None:
events.emit("plan.normalised", attempt=attempt, n=len(normalised), items=normalised[:8])
- result = finalise(result) if finalise is not None else ensure_acceptance(normalise_names(result), spec)
- result = enrich_plan(result, brief)
+ result = enrich_plan(ensure_acceptance(normalise_names(result), spec), brief)
ws.write_json(ws.plan_path, result)
if events is not None:
- stats = (event_stats or default_event_stats)(result)
- events.emit("plan.done", model=model_id, **stats,
+ events.emit("plan.done", model=model_id, **plan_event_stats(result),
cost_usd=round(usage.cost_usd, 4), prompt_hash=prompt_hash(system), attempt=attempt,
brief=brief is not None, quality_reasks=requeried, restarts=restarts, **budget.as_dict())
if guard is not None:
@@ -942,18 +968,16 @@ def _echo(raw: Any, text: str) -> ChatMessage:
# ----------------------------------------------------------------------------- prompts
def build_system_prompt(spec: Spec, plan_model: type[BaseModel], *, runtime: Any | None = None,
- template: str | None = None, example: dict[str, Any] | None = None,
budget: PlanBudget | None = None) -> str:
- template = template or PLAN_TEMPLATES[spec.track]
lang: Language = spec.language
budget = budget or plan_budget(spec)
return render(
- template,
+ PLAN_TEMPLATES[spec.track],
track=spec.track.value,
language=lang.value,
frame_doc=frame_doc(LANGUAGE_FRAME[lang.value]),
contract=language_contract(lang, runtime),
- example_json=json.dumps(example if example is not None else plan_example(spec.track), indent=1),
+ example_json=json.dumps(plan_example(spec.track), indent=1),
schema_fields=", ".join(plan_model.model_json_schema().get("properties", {}).keys()),
target_parts=budget.target_parts,
min_parts=budget.min_parts,
@@ -1000,21 +1024,28 @@ def ensure_acceptance[P: BaseModel](plan_obj: P, spec: Spec) -> P:
wishes were capping finished scenes at 0.60. The spec's ``must_have`` list is the
contract with the user, so on that track the plan's own items stay on the checklist as
``should`` (the judge still answers them, the refine loop still reads them) and only the
- spec-derived items keep ``must``."""
+ spec-derived items keep ``must``. A shader has no size, triangle count or ground: the graphics
+ track gets the spec's checklist and, when the plan animates, one probe item that the frames
+ change (never 'ground contact')."""
items: list[AcceptanceItem] = list(plan_obj.acceptance)
if spec.track is Track.SCENE:
items = [a if a.priority == "should" else a.model_copy(update={"priority": "should"}) for a in items]
c = spec.constraints
- if c.dimensions_m:
+ solid = spec.track is not Track.GRAPHICS
+ if solid and c.dimensions_m:
dims = ", ".join(f"{k} = {v:.3f} m" for k, v in c.dimensions_m.items())
add_acceptance_item(items, "dim", f"Overall dimensions match the request within 5%: {dims}", "measure")
- if c.max_triangles:
+ if solid and c.max_triangles:
add_acceptance_item(items, "tri", f"Triangle count ≤ {c.max_triangles}", "measure")
for m in c.must_have:
add_acceptance_item(items, "must", f"Includes: {m}", "visual")
for m in c.must_not:
add_acceptance_item(items, "not", f"Does NOT include: {m}", "visual")
- if spec.track is not Track.SCENE and not any(a.how == "measure" for a in items):
+ if not solid:
+ planned_motion = getattr(plan_obj, "motion", "").strip()
+ if planned_motion and not any(w in a.text.lower() for a in items for w in ("static", "motion", "change over time")):
+ add_acceptance_item(items, "motion", "Frames change over time as planned (not a static image)", "probe")
+ elif spec.track is not Track.SCENE and not any(a.how == "measure" for a in items):
add_acceptance_item(items, "ground", "Object stands on the ground plane (lowest point at up=0) with its footprint centred", "measure")
items.extend(articulation_acceptance(plan_obj, items))
plan_obj.acceptance = items
@@ -1067,7 +1098,7 @@ def normalise_names[P: BaseModel](plan_obj: P) -> P:
__all__ = ["MAX_PLAN_RESTARTS", "MAX_QUALITY_REASKS", "MAX_VALIDATION_REASKS",
"PLAN_RESTART_ENV", "PLAN_TOKENS_MAX", "PlanningError", "add_acceptance_item",
- "articulation_acceptance", "build_system_prompt", "build_user_prompt", "default_event_stats",
+ "articulation_acceptance", "build_system_prompt", "build_user_prompt", "plan_event_stats",
"ensure_acceptance", "missing_link_names", "normalise_names", "plan",
- "degenerate_plan", "plan_example", "plan_tokens", "restart_enabled",
+ "degenerate_plan", "plan_example", "plan_temperature", "plan_tokens", "restart_enabled",
"restart_note"]
diff --git a/harness/codeverse3d/tracks/scene_assets.py b/harness/codeverse3d/tracks/scene_assets.py
index 00ed321c..23cedd47 100644
--- a/harness/codeverse3d/tracks/scene_assets.py
+++ b/harness/codeverse3d/tracks/scene_assets.py
@@ -492,13 +492,10 @@ def hero_plan(sub: RunContext, asset: AssetPlan) -> StaticPlan:
demands, per-part bboxes, ``style_notes`` and an acceptance list — what a static_object
run gets, from the code that gives it to them.
"""
- from codeverse3d.tracks.static_object import StaticObjectTrack
-
- track = StaticObjectTrack(services=sub.services, settings=sub.settings)
try:
model = sub.services.chat_model(sub.spec.backends.planner)
plan = run_planner(sub.spec, sub.spec.backends.planner, StaticPlan, sub.ws, model=model, events=sub.events,
- budget=sub.budget, runtime=sub.runtime, **track._plan_kwargs(sub.spec))
+ budget=sub.budget, runtime=sub.runtime)
features = hero_features(asset.description)
if len(plan.parts) <= HERO_THIN_PLAN_PARTS and len(features) > HERO_THIN_PLAN_PARTS:
# a one-part answer for a prop whose sheet names several features (the windmill got
@@ -508,7 +505,7 @@ def hero_plan(sub: RunContext, asset: AssetPlan) -> StaticPlan:
sub.events.emit("asset.plan_thin", asset=asset.name, n_parts=len(plan.parts), features=features)
spec2 = sub.spec.model_copy(update={"constraints": sub.spec.constraints.model_copy(update={"must_have": features})})
plan = run_planner(spec2, spec2.backends.planner, StaticPlan, sub.ws, model=model, events=sub.events,
- budget=sub.budget, runtime=sub.runtime, **track._plan_kwargs(spec2))
+ budget=sub.budget, runtime=sub.runtime)
except Exception as e: # noqa: BLE001 — PlanningError / outage: the sheet still says what the prop is
if isinstance(e, BudgetExceeded):
raise
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.md
index 79e6147f..3b1df92f 100644
--- a/harness/docs/ARCHITECTURE.md
+++ b/harness/docs/ARCHITECTURE.md
@@ -189,12 +189,14 @@ codeverse3d/
gates), articulated_object.py (+ the planned-motion gate),
scene.py, scene_assets.py (+ cheap single-shot asset generation),
zone_layout.py (L2 zone director: per-zone structured layout calls + deterministic validator),
- graphics.py (the whole graphics track: planner hooks, prompt context, frame
+ graphics.py (the whole graphics track: prompt context, frame
RenderSet, and recipe seeding into the harness-owned, read-only
src/recipes.glsl — measured: flash calls a recipe on disk, not one it is
shown; AgentJob.read_only, C3D_SEED_RECIPES),
planner.py (the ONE planner loop + the cached EngineeringBrief
- (C3D_PLAN_BRIEF), plan budgets and the worked examples),
+ (C3D_PLAN_BRIEF), plan budgets and the worked examples — and the ONE owner of
+ what differs per track when planning: template, example, temperature, output
+ floor, acceptance, all dispatched on spec.track),
plan_features.py (the A/B switch registry: LIVE_SWITCHES / DEAD_SWITCHES,
+ pin_plan_blockers() deciding when two arms may share one plan —
eval/docs/EVAL.md §8.1),
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 4e42f61a..e872930a 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -502,7 +502,13 @@ run_round(ctx, *, index, kind, tasks, pipeline, ..., previous_best=None) -> Roun
# pipeline's render; candidates pass quick_render) and geometry_views=False (skips the clay/normals views)
# emits cost.round {stages{}, judge_usd, total_usd, agent_turns, wasted, waste_reason}; on ANY exception it
# records what the round burned (rounds/aborted_rNN.json, ctx.extra["aborted_rounds"]) and re-raises
-from codeverse3d.tracks.planner import plan, ensure_acceptance # graphics too, through its hooks (GraphicsTrack.plan_template / plan_example)
+from codeverse3d.tracks.planner import plan, ensure_acceptance, plan_example, plan_temperature
+plan(spec, model_id, plan_model, ws, *, model=None, events=None, budget=None, runtime=None) -> Plan
+ # Δ 2026-09-22: every track, graphics included, through ONE loop that dispatches on spec.track — PLAN_TEMPLATES,
+ # plan_example(track), plan_temperature(track) (graphics 0.5, else 0.4; record/telemetry reports it), the output
+ # floor (graphics PLAN_TOKENS_MAX, else PLAN_OUTPUT_FLOOR), plan_budget's unit (passes) and ensure_acceptance
+ # (graphics: must_have / must_not + a motion probe item, never dimensions / triangles / ground). The six BaseTrack
+ # planner hooks and plan()'s template / example / temperature / max_output_tokens / finalise / event_stats are gone
```
`run_round` = generate → commit → `build_with_repair` → measure → gates → render →
post-render gates → judge → commit. Post-render gates: static `reference_silhouette`
diff --git a/harness/docs/RUN_LAYOUT.md b/harness/docs/RUN_LAYOUT.md
index 0fa3080e..294c15b5 100644
--- a/harness/docs/RUN_LAYOUT.md
+++ b/harness/docs/RUN_LAYOUT.md
@@ -127,7 +127,7 @@ produces no diff.
hashes; tool versions (python, blender, node, three, chrome, puppeteer);
harness version + git sha; key-pool size; **price-table hash**; resolved
render and limit settings. Sampling values are read from the call sites'
- typed defaults (`VlmJudge.__init__`, the track's `plan_temperature`, and
+ typed defaults (`VlmJudge.__init__`, `tracks/planner.plan_temperature(track)`, and
`record/telemetry.py::_generator_defaults` — a historical shim that
configures nothing, kept so old records still read back); a
value a call site hard-codes per task is left empty with `source` saying so,
diff --git a/harness/tests/graphics/test_live.py b/harness/tests/graphics/test_live.py
index 9b97a7d5..f966f34b 100644
--- a/harness/tests/graphics/test_live.py
+++ b/harness/tests/graphics/test_live.py
@@ -41,7 +41,7 @@ def test_live_plan_generate_build_judge(tmp_path, keys_ok):
ws = Workspace(tmp_path / "live_gfx").create()
model = get_chat_model(MODEL)
from codeverse3d.tracks.planner import plan as run_planner
- plan = run_planner(spec, MODEL, GraphicsPlan, ws, model=model, **GraphicsTrack()._plan_kwargs(spec))
+ plan = run_planner(spec, MODEL, GraphicsPlan, ws, model=model)
assert isinstance(plan, GraphicsPlan) and plan.passes and plan.key_visuals and plan.motion
rt = GlslShaderRuntime()
rt.skeleton(ws, plan)
diff --git a/harness/tests/graphics/test_track.py b/harness/tests/graphics/test_track.py
index 53e4b198..608c92bc 100644
--- a/harness/tests/graphics/test_track.py
+++ b/harness/tests/graphics/test_track.py
@@ -22,14 +22,9 @@ from codeverse3d.languages.glsl_shader import lint_workspace, write_skeleton
from codeverse3d.proc import EventLog
from codeverse3d.prompts import render
from codeverse3d.spatial.gl_render import GlFrame, GlResult, gif_times
-from codeverse3d.tracks import get_track
-from codeverse3d.tracks.graphics import (
- GraphicsTrack,
- ensure_graphics_acceptance,
- graphics_prompt_context,
- plan_example,
-)
-from codeverse3d.tracks.planner import PlanningError
+from codeverse3d.tracks import get_track, planner
+from codeverse3d.tracks.graphics import GraphicsTrack, graphics_prompt_context
+from codeverse3d.tracks.planner import PlanningError, ensure_acceptance
from codeverse3d.workspace import Workspace
from tests.orchestrator_tracks.fakes import FakeAgent, FakeChatModel, FakeJudge, FakeServices
@@ -101,14 +96,14 @@ def _services(**kw):
return FakeServices(runtime_factory=lambda lang: FakeGlRuntime(), **kw)
+def plan_example() -> dict[str, Any]:
+ return planner.plan_example(Track.GRAPHICS)
+
+
def _plan(spec, ws, model, budget=None):
- """What plan_graphics() used to be: run_planner with GraphicsTrack's own hooks.
- The wrapper was a second spelling of _plan_kwargs and had no production caller,
- so the tests go through the hooks the live path actually uses."""
- from codeverse3d.tracks.graphics import GraphicsTrack
- from codeverse3d.tracks.planner import plan as run_planner
- return run_planner(spec, "fake:planner", GraphicsPlan, ws, model=model, budget=budget,
- **GraphicsTrack()._plan_kwargs(spec))
+ """The planner as the live path calls it: everything graphics-specific (template, worked
+ example, T = 0.5, acceptance) is dispatched on ``spec.track`` inside it."""
+ return planner.plan(spec, "fake:planner", GraphicsPlan, ws, model=model, budget=budget)
def test_graphics_track_end_to_end(tmp_path, settings):
@@ -237,15 +232,14 @@ def test_planner_reask_and_acceptance(tmp_ws):
ids = [a.id for a in plan.acceptance]
assert "must1" in ids and "a3" in ids # spec must_have appended, motion item already present in the example
# a plan without a motion acceptance item gets one; no 'ground contact' ever
- p2 = ensure_graphics_acceptance(GraphicsPlan.model_validate({**plan_example(), "acceptance": []}), spec)
+ p2 = ensure_acceptance(GraphicsPlan.model_validate({**plan_example(), "acceptance": []}), spec)
assert any(a.id.startswith("motion") for a in p2.acceptance) and not any("ground" in a.text.lower() for a in p2.acceptance)
always_bad = FakeChatModel(lambda req: {"title": "x"})
with pytest.raises(PlanningError):
_plan(spec, tmp_ws, always_bad)
- from codeverse3d.tracks.graphics import PLAN_TEMPLATE
- from codeverse3d.tracks.planner import build_system_prompt
- sys_prompt = build_system_prompt(spec, GraphicsPlan, template=PLAN_TEMPLATE, example=plan_example())
+ sys_prompt = planner.build_system_prompt(spec, GraphicsPlan)
assert "ART-DIRECTOR" in sys_prompt and "NeonRainWindow" in sys_prompt
+ assert model.requests[0].temperature == 0.5 and model.requests[0].max_output_tokens == planner.PLAN_TOKENS_MAX
def test_templates_render_and_rubric_loads(tmp_path, settings):
diff --git a/harness/tests/orchestrator_tracks/test_graphics_recipes.py b/harness/tests/orchestrator_tracks/test_graphics_recipes.py
index a92aecd6..5aa5c380 100644
--- a/harness/tests/orchestrator_tracks/test_graphics_recipes.py
+++ b/harness/tests/orchestrator_tracks/test_graphics_recipes.py
@@ -35,11 +35,11 @@ from codeverse3d.tracks.graphics import (
graphics_prompt_context,
is_skeleton_common,
parse_functions,
- plan_example,
recipe_chapters,
seed_recipes,
seeded_on_disk,
)
+from codeverse3d.tracks.planner import plan_example
from codeverse3d.workspace import Workspace
AURORA = "Aurora borealis over a mountain ridge with a frozen lake, dense stars, green and violet curtains"
@@ -211,7 +211,7 @@ def test_brief_and_plan_visuals_select_recipes(tmp_path) -> None:
assert "vec2 dropsLayer(vec2 uv, float t, float scale)" in text and "vec3 bokehSoft(vec2 p, float t)" in text
ws = _ws(tmp_path / "plan")
- plan = GraphicsPlan.model_validate({**plan_example(), "key_visuals": ["an aurora curtain over the ridge"]})
+ plan = GraphicsPlan.model_validate({**plan_example(Track.GRAPHICS), "key_visuals": ["an aurora curtain over the ridge"]})
names = seed_recipes(_ctx(ws, "a landscape", plan=plan))
assert "curtain" in names and "bokehSoft" not in names
# the seed follows the prompt's selection exactly, budget included: for "a city at night" the Light +
@@ -375,7 +375,7 @@ def test_lint_flags_a_redefinition_of_a_seeded_recipe(tmp_path) -> None:
def test_prompt_block_lists_the_seeded_names(tmp_path) -> None:
ws = _ws(tmp_path)
- ctx = _ctx(ws, plan=GraphicsPlan.model_validate({**plan_example(), "key_visuals": ["green aurora curtains", "dense stars"]}))
+ ctx = _ctx(ws, plan=GraphicsPlan.model_validate({**plan_example(Track.GRAPHICS), "key_visuals": ["green aurora curtains", "dense stars"]}))
names = seed_recipes(ctx)
d = graphics_prompt_context(ctx, skeleton_files={}, previous_error="")
assert [r["name"] for r in d["seeded_recipes"]] == names
diff --git a/harness/tests/orchestrator_tracks/test_planner_depth.py b/harness/tests/orchestrator_tracks/test_planner_depth.py
index 413a9463..4ffefd1d 100644
--- a/harness/tests/orchestrator_tracks/test_planner_depth.py
+++ b/harness/tests/orchestrator_tracks/test_planner_depth.py
@@ -27,7 +27,6 @@ from codeverse3d.tracks.planner import (
MAX_QUALITY_REASKS,
build_system_prompt,
build_user_prompt,
- plan_example,
)
from codeverse3d.tracks.planner import plan as run_planner
from codeverse3d.workspace import Workspace
@@ -136,9 +135,7 @@ def test_plan_templates_render_the_budget_numbers():
for track, language, model in ((Track.STATIC_OBJECT, Language.BLENDER, StaticPlan),
(Track.GRAPHICS, Language.GLSL_SHADER, GraphicsPlan)):
spec = _spec(must=9, track=track, language=language)
- template = "tracks/plan_graphics.j2" if track is Track.GRAPHICS else None
- out = build_system_prompt(spec, model, template=template, example=plan_example(Track.STATIC_OBJECT),
- budget=B.plan_budget(spec))
+ out = build_system_prompt(spec, model, budget=B.plan_budget(spec))
assert str(B.plan_budget(spec).target_parts) in out
diff --git a/harness/tests/orchestrator_tracks/test_refactor_batch2.py b/harness/tests/orchestrator_tracks/test_refactor_batch2.py
index 336a5ccb..96a6827c 100644
--- a/harness/tests/orchestrator_tracks/test_refactor_batch2.py
+++ b/harness/tests/orchestrator_tracks/test_refactor_batch2.py
@@ -104,7 +104,6 @@ def test_graphics_planner_hooks_charge_budget_on_planning_error(tmp_ws):
from codeverse3d.contracts.plan import GraphicsPlan
from codeverse3d.contracts.spec import Budget
from codeverse3d.orchestrator import BudgetGuard
- from codeverse3d.tracks.graphics import GraphicsTrack
from codeverse3d.tracks.planner import PlanningError
from codeverse3d.tracks.planner import plan as run_planner
@@ -112,7 +111,6 @@ def test_graphics_planner_hooks_charge_budget_on_planning_error(tmp_ws):
budget = BudgetGuard(Budget(max_minutes=10))
always_bad = FakeChatModel(lambda req: {"title": "x"})
with pytest.raises(PlanningError):
- run_planner(spec, "fake:planner", GraphicsPlan, tmp_ws, model=always_bad, budget=budget,
- **GraphicsTrack()._plan_kwargs(spec))
+ run_planner(spec, "fake:planner", GraphicsPlan, tmp_ws, model=always_bad, budget=budget)
assert budget.spent.cost_usd > 0, "a failed re-ask is still paid for"