Official Codebase of 3DCodeVerse
Python
cleanup: split orchestrator/rounds.py along the review's seam — refine-task compilation moved to refine_tasks.py
gaoypeng7556a5646be5
diff --git a/harness/codeverse/orchestrator/refine_tasks.py b/harness/codeverse/orchestrator/refine_tasks.pynew file mode 100644index 00000000..4fc79c05--- /dev/null+++ b/harness/codeverse/orchestrator/refine_tasks.py@@ -0,0 +1,250 @@+"""Refine-task compilation: what the next round is asked to change.++Owns the typed change request (``RefineTask``), its file-ownership grouping+(``TaskGroup``, ``plan_parallel_groups``, ``plan_refine_groups``), the compiler+that turns gate errors + failed *must* acceptance items + the judge's improvement+plan into tasks (``build_refine_instructions``) and the per-task line compaction+(``compact_instructions``), plus the plan-name canonicalisation helpers they share.++Sibling: ``codeverse.orchestrator.rounds`` owns the round-loop *policy* -- when to+stop, which round is best, what shape the next round takes -- and re-exports every+public name below so existing importers keep working. This module is a leaf: it+reads contracts + conventions only and never imports the policy.+"""++from __future__ import annotations++import logging+from collections.abc import Callable, Sequence+from typing import Literal++from pydantic import BaseModel, Field++from codeverse.contracts.artifacts import GateReport+from codeverse.contracts.judgment import Judgment+from codeverse.contracts.plan import AcceptanceItem, Plan+from codeverse.conventions import to_snake++log = logging.getLogger(__name__)+++class RefineTask(BaseModel):+ """One targeted change request compiled for the next round."""++ target: str = Field(description="part / zone / asset / joint / camera / 'overall'")+ kind: str = Field(description="geometry | assembly | material | articulation | bug | acceptance | ...")+ instruction: str+ priority: int = Field(ge=0, le=9, description="0 = gate error, 1 = failed must item, 2+ = judge")+ files: list[str] = Field(default_factory=list, description="files this task may edit ([] = unknown/whole)")+ source: Literal["gate", "acceptance", "judge"] = "judge"++ def line(self) -> str:+ files = f" (files: {', '.join(self.files)})" if self.files else ""+ return f"[{self.source}/{self.kind}] {self.target}: {self.instruction}{files}"+++class TaskGroup(BaseModel):+ """Tasks that must run together (they touch the same files)."""++ tasks: list[RefineTask]+ files: list[str] = Field(default_factory=list)++ @property+ def targets(self) -> list[str]:+ seen: list[str] = []+ for t in self.tasks:+ if t.target not in seen:+ seen.append(t.target)+ return seen++ @property+ def label(self) -> str:+ return "+".join(to_snake(t) for t in self.targets[:3]) or "refine"+++FileForTarget = Callable[[str], list[str]]+++def build_refine_instructions(+ judgment: Judgment | None,+ gates: Sequence[GateReport],+ acceptance_failures: Sequence[AcceptanceItem],+ plan: Plan | None,+ *,+ file_for_target: FileForTarget | None = None,+ max_tasks: int = 6,+ extra: Sequence[RefineTask] = (),+) -> list[RefineTask]:+ """Gate ERRORS first (with fix hints), then ``extra`` harness-derived tasks+ (e.g. reference-silhouette mismatch), then failed *must* acceptance items,+ then the judge's improvement plan; de-duplicated by (target, kind), capped.+ Gate/acceptance/extra tasks are never dropped by the cap unless they alone exceed it."""+ known = _known_targets(plan)+ tasks: list[RefineTask] = []+ seen: set[tuple[str, str]] = set()++ def _add(t: RefineTask) -> None:+ key = (to_snake(t.target), t.kind)+ if key in seen:+ return+ seen.add(key)+ t.target = _canon_target(t.target, known)+ if file_for_target is not None and not t.files:+ t.files = list(file_for_target(t.target))+ tasks.append(t)++ for g in gates:+ for f in g.errors:+ _add(RefineTask(target=f.target or "overall", kind=f"gate:{g.gate}", instruction=f.as_line(),+ priority=0, source="gate"))+ for t in extra:+ _add(t.model_copy())+ for a in acceptance_failures:+ if a.priority != "must":+ continue+ _add(RefineTask(target=_acceptance_target(a, known), kind="acceptance",+ instruction=f"Acceptance item {a.id} NOT met: {a.text}", priority=1,+ source="acceptance"))+ if judgment is not None:+ for item in sorted(judgment.improvement_plan, key=lambda i: (i.priority, -i.expected_gain)):+ _add(RefineTask(target=item.target or "overall", kind=item.kind, instruction=item.instruction,+ priority=min(9, 1 + item.priority), source="judge"))+ tasks.sort(key=lambda t: t.priority)+ if len(tasks) > max_tasks:+ protected = [t for t in tasks if t.source != "judge"]+ rest = [t for t in tasks if t.source == "judge"]+ tasks = (protected + rest)[:max(max_tasks, len(protected))]+ return tasks+++def plan_parallel_groups(tasks: Sequence[RefineTask]) -> list[TaskGroup]:+ """Group tasks by file ownership. Tasks with unknown files (``[]``) cannot+ be isolated, so if any exists everything collapses into ONE group (a single+ whole-object task). Otherwise groups are the connected components of the+ "shares a file" relation — each group may run concurrently with the others."""+ if not tasks:+ return []+ if any(not t.files for t in tasks):+ files = sorted({f for t in tasks for f in t.files})+ return [TaskGroup(tasks=list(tasks), files=files)]+ parent = list(range(len(tasks)))++ def find(i: int) -> int:+ while parent[i] != i:+ parent[i] = parent[parent[i]]+ i = parent[i]+ return i++ owner: dict[str, int] = {}+ for i, t in enumerate(tasks):+ for f in t.files:+ if f in owner:+ parent[find(i)] = find(owner[f])+ else:+ owner[f] = i+ groups: dict[int, list[RefineTask]] = {}+ for i, t in enumerate(tasks):+ groups.setdefault(find(i), []).append(t)+ out = []+ for members in groups.values():+ files = sorted({f for t in members for f in t.files})+ out.append(TaskGroup(tasks=members, files=files))+ out.sort(key=lambda g: min(t.priority for t in g.tasks))+ return out+++def plan_refine_groups(+ tasks: Sequence[RefineTask],+ *,+ allow_fanout: bool = True,+ parallel_min_tasks: int = 2,+) -> tuple[list[TaskGroup], bool]:+ """The ONE grouping rule of the refine scaffold (``BaseTrack.refine_tasks``).++ Groups by file ownership via :func:`plan_parallel_groups`; the groups run in+ parallel only when fan-out is allowed for the track, at least+ ``parallel_min_tasks`` file-disjoint groups exist and every group owns+ files. Otherwise everything collapses into ONE whole-artifact group."""+ groups = plan_parallel_groups(tasks)+ parallel = allow_fanout and len(groups) >= parallel_min_tasks and all(g.files for g in groups)+ if not parallel:+ groups = [TaskGroup(tasks=list(tasks), files=sorted({f for t in tasks for f in t.files}))]+ return groups, parallel+++def compact_instructions(tasks: Sequence[RefineTask], max_lines: int = 6) -> list[str]:+ """The instruction lines handed to ONE generation task: grouped by target+ (instances ``Leg_0``/``Leg_1`` fold into ``Leg``), ordered by priority, capped+ at ``max_lines``. A flash-class agent given 12 near-identical connectivity+ errors fixes none; given "FrontLeg: (a) … (b) …" it fixes the part."""+ if not tasks:+ return []+ groups: dict[str, list[RefineTask]] = {}+ for t in sorted(tasks, key=lambda t: t.priority):+ groups.setdefault(_instance_base(t.target), []).append(t)+ lines: list[str] = []+ for target, members in groups.items():+ if len(members) == 1:+ lines.append(members[0].line())+ continue+ bits = []+ for i, t in enumerate(members):+ who = f" [{t.target}]" if t.target != target else ""+ bits.append(f"({chr(97 + i % 26)}){who} [{t.source}/{t.kind}] {t.instruction}")+ files = sorted({f for t in members for f in t.files})+ tail = f" (files: {', '.join(files)})" if files else ""+ lines.append(f"{target}: " + "; ".join(bits) + tail)+ if len(lines) > max_lines:+ dropped = len(lines) - max_lines+ lines = lines[:max_lines]+ log.info("compact_instructions: %d target group(s) deferred to a later round", dropped)+ return lines+++# ----------------------------------------------------------------------------- helpers+def _split_instance(target: str) -> tuple[str, str]:+ """``BackLeg_1`` → (``BackLeg``, ``1``) per the ``Name_0..N-1`` instance naming+ convention; anything else → (target, "")."""+ base, sep, suffix = (target or "").rpartition("_")+ if sep and base and suffix.isdigit():+ return base, suffix+ return target or "overall", ""+++def _instance_base(target: str) -> str:+ return _split_instance(target)[0]+++def _known_targets(plan: Plan | None) -> dict[str, str]:+ """snake → canonical name for every part/zone/asset/joint/camera in the plan."""+ names: dict[str, str] = {}+ if plan is None:+ return names+ for attr in ("parts", "joints", "zones", "assets", "cameras", "effects"):+ for item in getattr(plan, attr, None) or []:+ names[to_snake(item.name)] = item.name+ return names+++def _canon_target(target: str, known: dict[str, str]) -> str:+ """Plan name for ``target``; instance suffixes (``Leg_1``, ``leg.2``) keep the+ suffix but take the plan's spelling of the base name."""+ hit = known.get(to_snake(target))+ if hit is not None:+ return hit+ base, suffix = _split_instance(target)+ if suffix and to_snake(base) in known:+ return f"{known[to_snake(base)]}_{suffix}"+ snake = to_snake(target)+ if snake.endswith("s") and snake[:-1] in known: # judges say "Legs" for the plan's "Leg"+ return known[snake[:-1]]+ return target+++def _acceptance_target(item: AcceptanceItem, known: dict[str, str]) -> str:+ """Route a failed acceptance item to the part it names, else 'overall'."""+ words = item.text.lower()+ for snake, name in known.items():+ if snake.replace("_", " ") in words or snake in words:+ return name+ return "overall"diff --git a/harness/codeverse/orchestrator/rounds.py b/harness/codeverse/orchestrator/rounds.pyindex a2c77c64..e1a96cf1 100644--- a/harness/codeverse/orchestrator/rounds.py+++ b/harness/codeverse/orchestrator/rounds.py@@ -2,10 +2,11 @@All thresholds live in ``RoundPolicy`` (one calibrated object, no scatteredifs). ``StopPolicy.evaluate`` is a pure function of the round history;-``BestSelector.pick`` is a pure function of the rounds; ``build_refine_-instructions`` compiles gate errors + failed acceptance + the judge's-improvement plan into typed ``RefineTask``s, and ``plan_parallel_groups``-decides which tasks may run concurrently from file ownership.+``BestSelector.pick`` is a pure function of the rounds. Compiling gate errors++ failed acceptance + the judge's improvement plan into typed ``RefineTask``s+(and grouping them by file ownership) lives in the sibling module+``codeverse.orchestrator.refine_tasks``; its public names are re-exported at+the bottom of this file so existing importers keep working.**Two money stops** were added from the cost audit (docs/COST.md §5), bothmeasured against the judge's own noise rather than a magic constant — the@@ -28,17 +29,11 @@ per-model σ table lives in ONE place, ``codeverse.cost.routing.JUDGE_NOISE``from __future__ import annotationsimport logging-from collections.abc import Callable, Sequence+from collections.abc import Sequencefrom dataclasses import dataclass, replacefrom typing import Literal-from pydantic import BaseModel, Field--from codeverse.contracts.artifacts import GateReport-from codeverse.contracts.judgment import Judgment-from codeverse.contracts.plan import AcceptanceItem, Planfrom codeverse.contracts.run import RoundRecord-from codeverse.conventions import to_snakefrom codeverse.judges.metrics import best_indexlog = logging.getLogger(__name__)@@ -376,223 +371,22 @@ def _build_failed(r: RoundRecord) -> bool:# ----------------------------------------------------------------------------- refine tasks-class RefineTask(BaseModel):- """One targeted change request compiled for the next round."""-- target: str = Field(description="part / zone / asset / joint / camera / 'overall'")- kind: str = Field(description="geometry | assembly | material | articulation | bug | acceptance | ...")- instruction: str- priority: int = Field(ge=0, le=9, description="0 = gate error, 1 = failed must item, 2+ = judge")- files: list[str] = Field(default_factory=list, description="files this task may edit ([] = unknown/whole)")- source: Literal["gate", "acceptance", "judge"] = "judge"-- def line(self) -> str:- files = f" (files: {', '.join(self.files)})" if self.files else ""- return f"[{self.source}/{self.kind}] {self.target}: {self.instruction}{files}"---class TaskGroup(BaseModel):- """Tasks that must run together (they touch the same files)."""-- tasks: list[RefineTask]- files: list[str] = Field(default_factory=list)-- @property- def targets(self) -> list[str]:- seen: list[str] = []- for t in self.tasks:- if t.target not in seen:- seen.append(t.target)- return seen-- @property- def label(self) -> str:- return "+".join(to_snake(t) for t in self.targets[:3]) or "refine"---FileForTarget = Callable[[str], list[str]]---def build_refine_instructions(- judgment: Judgment | None,- gates: Sequence[GateReport],- acceptance_failures: Sequence[AcceptanceItem],- plan: Plan | None,- *,- file_for_target: FileForTarget | None = None,- max_tasks: int = 6,- extra: Sequence[RefineTask] = (),-) -> list[RefineTask]:- """Gate ERRORS first (with fix hints), then ``extra`` harness-derived tasks- (e.g. reference-silhouette mismatch), then failed *must* acceptance items,- then the judge's improvement plan; de-duplicated by (target, kind), capped.- Gate/acceptance/extra tasks are never dropped by the cap unless they alone exceed it."""- known = _known_targets(plan)- tasks: list[RefineTask] = []- seen: set[tuple[str, str]] = set()-- def _add(t: RefineTask) -> None:- key = (to_snake(t.target), t.kind)- if key in seen:- return- seen.add(key)- t.target = _canon_target(t.target, known)- if file_for_target is not None and not t.files:- t.files = list(file_for_target(t.target))- tasks.append(t)-- for g in gates:- for f in g.errors:- _add(RefineTask(target=f.target or "overall", kind=f"gate:{g.gate}", instruction=f.as_line(),- priority=0, source="gate"))- for t in extra:- _add(t.model_copy())- for a in acceptance_failures:- if a.priority != "must":- continue- _add(RefineTask(target=_acceptance_target(a, known), kind="acceptance",- instruction=f"Acceptance item {a.id} NOT met: {a.text}", priority=1,- source="acceptance"))- if judgment is not None:- for item in sorted(judgment.improvement_plan, key=lambda i: (i.priority, -i.expected_gain)):- _add(RefineTask(target=item.target or "overall", kind=item.kind, instruction=item.instruction,- priority=min(9, 1 + item.priority), source="judge"))- tasks.sort(key=lambda t: t.priority)- if len(tasks) > max_tasks:- protected = [t for t in tasks if t.source != "judge"]- rest = [t for t in tasks if t.source == "judge"]- tasks = (protected + rest)[:max(max_tasks, len(protected))]- return tasks---def plan_parallel_groups(tasks: Sequence[RefineTask]) -> list[TaskGroup]:- """Group tasks by file ownership. Tasks with unknown files (``[]``) cannot- be isolated, so if any exists everything collapses into ONE group (a single- whole-object task). Otherwise groups are the connected components of the- "shares a file" relation — each group may run concurrently with the others."""- if not tasks:- return []- if any(not t.files for t in tasks):- files = sorted({f for t in tasks for f in t.files})- return [TaskGroup(tasks=list(tasks), files=files)]- parent = list(range(len(tasks)))-- def find(i: int) -> int:- while parent[i] != i:- parent[i] = parent[parent[i]]- i = parent[i]- return i-- owner: dict[str, int] = {}- for i, t in enumerate(tasks):- for f in t.files:- if f in owner:- parent[find(i)] = find(owner[f])- else:- owner[f] = i- groups: dict[int, list[RefineTask]] = {}- for i, t in enumerate(tasks):- groups.setdefault(find(i), []).append(t)- out = []- for members in groups.values():- files = sorted({f for t in members for f in t.files})- out.append(TaskGroup(tasks=members, files=files))- out.sort(key=lambda g: min(t.priority for t in g.tasks))- return out---def plan_refine_groups(- tasks: Sequence[RefineTask],- *,- allow_fanout: bool = True,- parallel_min_tasks: int = 2,-) -> tuple[list[TaskGroup], bool]:- """The ONE grouping rule of the refine scaffold (``BaseTrack.refine_tasks``).-- Groups by file ownership via :func:`plan_parallel_groups`; the groups run in- parallel only when fan-out is allowed for the track, at least- ``parallel_min_tasks`` file-disjoint groups exist and every group owns- files. Otherwise everything collapses into ONE whole-artifact group."""- groups = plan_parallel_groups(tasks)- parallel = allow_fanout and len(groups) >= parallel_min_tasks and all(g.files for g in groups)- if not parallel:- groups = [TaskGroup(tasks=list(tasks), files=sorted({f for t in tasks for f in t.files}))]- return groups, parallel---def compact_instructions(tasks: Sequence[RefineTask], max_lines: int = 6) -> list[str]:- """The instruction lines handed to ONE generation task: grouped by target- (instances ``Leg_0``/``Leg_1`` fold into ``Leg``), ordered by priority, capped- at ``max_lines``. A flash-class agent given 12 near-identical connectivity- errors fixes none; given "FrontLeg: (a) … (b) …" it fixes the part."""- if not tasks:- return []- groups: dict[str, list[RefineTask]] = {}- for t in sorted(tasks, key=lambda t: t.priority):- groups.setdefault(_instance_base(t.target), []).append(t)- lines: list[str] = []- for target, members in groups.items():- if len(members) == 1:- lines.append(members[0].line())- continue- bits = []- for i, t in enumerate(members):- who = f" [{t.target}]" if t.target != target else ""- bits.append(f"({chr(97 + i % 26)}){who} [{t.source}/{t.kind}] {t.instruction}")- files = sorted({f for t in members for f in t.files})- tail = f" (files: {', '.join(files)})" if files else ""- lines.append(f"{target}: " + "; ".join(bits) + tail)- if len(lines) > max_lines:- dropped = len(lines) - max_lines- lines = lines[:max_lines]- log.info("compact_instructions: %d target group(s) deferred to a later round", dropped)- return lines---# ----------------------------------------------------------------------------- helpers-def _split_instance(target: str) -> tuple[str, str]:- """``BackLeg_1`` → (``BackLeg``, ``1``) per the ``Name_0..N-1`` instance naming- convention; anything else → (target, "")."""- base, sep, suffix = (target or "").rpartition("_")- if sep and base and suffix.isdigit():- return base, suffix- return target or "overall", ""---def _instance_base(target: str) -> str:- return _split_instance(target)[0]---def _known_targets(plan: Plan | None) -> dict[str, str]:- """snake → canonical name for every part/zone/asset/joint/camera in the plan."""- names: dict[str, str] = {}- if plan is None:- return names- for attr in ("parts", "joints", "zones", "assets", "cameras", "effects"):- for item in getattr(plan, attr, None) or []:- names[to_snake(item.name)] = item.name- return names---def _canon_target(target: str, known: dict[str, str]) -> str:- """Plan name for ``target``; instance suffixes (``Leg_1``, ``leg.2``) keep the- suffix but take the plan's spelling of the base name."""- hit = known.get(to_snake(target))- if hit is not None:- return hit- base, suffix = _split_instance(target)- if suffix and to_snake(base) in known:- return f"{known[to_snake(base)]}_{suffix}"- snake = to_snake(target)- if snake.endswith("s") and snake[:-1] in known: # judges say "Legs" for the plan's "Leg"- return known[snake[:-1]]- return target---def _acceptance_target(item: AcceptanceItem, known: dict[str, str]) -> str:- """Route a failed acceptance item to the part it names, else 'overall'."""- words = item.text.lower()- for snake, name in known.items():- if snake.replace("_", " ") in words or snake in words:- return name- return "overall"+# Moved to codeverse.orchestrator.refine_tasks; imported here so existing importers+# (tracks/*, reference/mismatch, tests) keep working unchanged.+from codeverse.orchestrator.refine_tasks import ( # noqa: E402+ FileForTarget,+ RefineTask,+ TaskGroup,+ build_refine_instructions,+ compact_instructions,+ plan_parallel_groups,+ plan_refine_groups,+)++__all__ = [+ "BestSelector", "DEFAULT_JUDGE_SIGMA", "DETAIL_KIND", "FileForTarget", "KIND_FOR_STRATEGY",+ "REWRITE_KIND", "RefineTask", "RoundPolicy", "StopDecision", "StopPolicy", "StopReason",+ "Strategy", "TaskGroup", "best_score", "build_refine_instructions", "compact_instructions",+ "detail_blocked", "gate_error_count", "judge_sigma", "kind_for_strategy", "last_gain",+ "plan_parallel_groups", "plan_refine_groups",+]diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex 37cc83ee..51555ad9 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -154,7 +154,8 @@ codeverse/texturing/ plan.py (VLM material plan), generate.py (+ tile.py seam fix), uv.py (world-metreunwrap), apply.py, gate.py (seam + before/after judge), scene_pack.py, run.py (texture_pass),maps.py (PBR map set), materials.py (named material library), normalise.py- orchestrator/ runner.py, state.py, rounds.py (RoundPolicy, compaction), candidates.py (best-of-N+ orchestrator/ runner.py, state.py, rounds.py (RoundPolicy, StopPolicy, BestSelector), refine_tasks.py+ (RefineTask compilation + file-ownership grouping + compaction), candidates.py (best-of-N+ pairwise decisions), budget.pytracks/ base.py (get_track(track, **options)), lifecycle.py, steps.py, candidates.py,generation.py, repair.py, planner.py, prompting.py (prompt helpers, split from common),