Official Codebase of 3DCodeVerse
Python
"""Helpers that keep tool Observations compact and workspace-safe: number/path formatting,
truncation, the shared lint / BUILD FAILED report, and the standard Observation builders."""
from __future__ import annotations
from collections.abc import Iterable, Sequence
from pathlib import Path
from typing import Any
from codeverse3d import proc
from codeverse3d.contracts.artifacts import BuildResult, GateReport, RenderSet, Severity
from codeverse3d.spatial.registry import Observation
MAX_TEXT = 2400
def fmt_float(v: float, digits: int = 4) -> str:
if v == 0:
return "0"
if abs(v) >= 1000 or abs(v) < 1e-3:
return f"{v:.3g}"
return f"{v:.{digits}f}".rstrip("0").rstrip(".")
def fmt_numbers(numbers: dict[str, Any], max_items: int = 24) -> str:
"""``a=1.5 b=[0.1, 0.2] c=ok`` — nested dicts/lists are compacted, long ones elided."""
bits = []
for i, (k, v) in enumerate(numbers.items()):
if i >= max_items:
bits.append(f"…+{len(numbers) - max_items}")
break
bits.append(f"{k}={_fmt_value(v)}")
return " ".join(bits)
def _fmt_value(v: Any, depth: int = 0) -> str:
if isinstance(v, bool):
return "yes" if v else "no"
if isinstance(v, float):
return fmt_float(v)
if isinstance(v, (list, tuple)):
if len(v) > 8:
return "[" + ", ".join(_fmt_value(x, depth + 1) for x in v[:8]) + f", …+{len(v) - 8}]"
return "[" + ", ".join(_fmt_value(x, depth + 1) for x in v) + "]"
if isinstance(v, dict):
if depth >= 2:
return f"{{{len(v)} keys}}"
return "{" + ", ".join(f"{k}:{_fmt_value(x, depth + 1)}" for k, x in list(v.items())[:12]) + "}"
s = str(v)
return s if len(s) <= 80 else s[:77] + "…"
def truncate(text: str, n: int = MAX_TEXT, tail_ratio: float = 0.3) -> str:
"""Keep the head and the tail of ``text`` (tail-biased errors survive)."""
if len(text) <= n:
return text
tail_n = int(n * tail_ratio)
head_n = n - tail_n - 24
head, tail = text[:head_n], text[-tail_n:] if tail_n else ""
return f"{head}\n… [{len(text) - head_n - tail_n} chars omitted] …\n{tail}"
def rel_path(path: Path | str | None, root: Path) -> str:
"""Display path relative to the workspace root (falls back to the file name)."""
if path is None:
return ""
p = Path(path)
try:
return str(p.resolve().relative_to(Path(root).resolve()))
except ValueError:
return p.name
def sanitize_text(text: str, root: Path) -> str:
"""Replace absolute workspace paths in free text with workspace-relative ones."""
r = str(Path(root).resolve())
return text.replace(r + "/", "").replace(r, ".")
# --------------------------------------------------------------------------- builders
def text_observation(
lines: Sequence[str] | str,
*,
ok: bool = True,
failed: bool = False,
numbers: dict[str, Any] | None = None,
images: Sequence[str | Path] = (),
limit: int = MAX_TEXT,
) -> Observation:
"""Observation from text lines, truncated to ``limit``. ``ok=False`` is a verdict; ``failed`` means the tool could not run."""
body = lines if isinstance(lines, str) else "\n".join(str(x) for x in lines)
return Observation(ok=ok, failed=failed, text=truncate(body, limit), numbers=dict(numbers or {}),
images=[str(i) for i in images if i])
_SEV_ORDER = {Severity.ERROR: 0, Severity.WARN: 1, Severity.INFO: 2}
_SEV_TAG = {Severity.ERROR: "ERROR", Severity.WARN: "WARN", Severity.INFO: "info"}
# --------------------------------------------------------------------------- build reports
def lint_lines(report: GateReport, root: Path, *, errors_only: bool) -> list[str]:
"""``- ERROR (src/x.py): msg`` (+ fix hint) lines for the errors or the warnings; INFO is never shown."""
want = Severity.ERROR if errors_only else Severity.WARN
out = []
for f in report.findings:
if f.severity != want:
continue
loc = f" ({rel_path(f.target, root)})" if f.target else ""
out.append(f"- {_SEV_TAG[f.severity]}{loc}: {sanitize_text(f.message, root)}")
if f.fix_hint:
out.append(f" fix: {sanitize_text(f.fix_hint, root)}")
return out
def error_file_display(error_file: str, root: Path) -> str:
"""``error_file`` for the agent: absolute paths become workspace-relative, relative ones are kept."""
if not error_file or not Path(error_file).is_absolute():
return error_file
return rel_path(error_file, root)
def build_failure_lines(br: BuildResult, root: Path, lint_warns: Sequence[str], *, tail_n: int) -> list[str]:
"""``BUILD FAILED: <type>: <message> at <file>:<line>`` + stderr tail + up to 10 lint hints."""
where = f" at {error_file_display(br.error_file, root)}:{br.error_line}" if br.error_file else ""
# the location stays on the headline when the message is multi-line
head, _, rest = sanitize_text(br.error_message, root).partition("\n")
lines = [f"BUILD FAILED: {br.error_type or 'Error'}: {head}{where}"] + ([rest] if rest else [])
tail = proc.tail(sanitize_text(br.stderr_tail, root).rstrip("\n"), max_lines=tail_n)
if tail and tail not in br.error_message:
lines.append("stderr (tail):\n" + tail)
if lint_warns:
lines.append("lint hints:\n" + "\n".join(lint_warns[:10]))
return lines
def gate_observation(report: GateReport, *, title: str = "", max_findings: int = 20,
images: Iterable[str] = (), failed: bool = False) -> Observation:
"""Errors first, each with its fix hint; counts in ``numbers``.
The PASS/FAIL verdict leads the text. ``failed`` marks a tool that could not run and forces ``ok=False``.
"""
findings = sorted(report.findings, key=lambda f: _SEV_ORDER.get(f.severity, 3))
n_err = sum(1 for f in findings if f.severity == Severity.ERROR)
n_warn = sum(1 for f in findings if f.severity == Severity.WARN)
head = f"{title or report.gate}: {'PASS' if report.passed else 'FAIL'}"
lines = [f"{head} — {n_err} error(s), {n_warn} warning(s)"]
for f in findings[:max_findings]:
tgt = f" [{f.target}]" if f.target else ""
lines.append(f"- {_SEV_TAG[f.severity]}{tgt}: {f.message}")
if f.fix_hint and f.severity != Severity.INFO:
lines.append(f" fix: {f.fix_hint}")
if len(findings) > max_findings:
lines.append(f"- … {len(findings) - max_findings} more finding(s)")
numbers: dict[str, Any] = {"passed": report.passed, "errors": n_err, "warnings": n_warn}
for f in findings:
if f.severity == Severity.ERROR and f.data:
numbers.setdefault("error_data", {})[f.target or f.message[:40]] = f.data
return Observation(ok=report.passed and not failed, failed=failed,
text=truncate("\n".join(lines)), numbers=numbers, images=list(images))
def render_observation(rs: RenderSet, root: Path, *, note: str = "", max_individual: int = 4) -> Observation:
"""Contact sheet first, individual views when few; text lists views + cameras.
Console errors are a verdict (``ok=False``); no views and nothing logged is a failure (``failed=True``).
"""
images: list[str] = []
if rs.contact_sheet:
images.append(rs.contact_sheet)
if len(rs.views) <= max_individual:
images.extend(v.path for v in rs.views)
lines: list[str] = []
if rs.console_errors:
lines.append(f"RENDER: FAIL — {len(rs.console_errors)} console error(s)"
+ (" and no view rendered; the errors below say why" if not rs.views
else "; the views below rendered anyway"))
elif not rs.views:
lines.append("RENDER PRODUCED NO VIEWS" + (f" ({rs.renderer})" if rs.renderer else "")
+ " — nothing to look at and nothing logged: the renderer failed, "
"there is no finding here to fix in src/")
if note:
lines.append(note)
lines.append(f"{len(rs.views)} view(s)" + (f" via {rs.renderer}" if rs.renderer else "") + (", contact sheet first" if rs.contact_sheet else ""))
for v in rs.views:
cam = ""
if v.camera_position is not None:
cam = " cam=(" + ", ".join(fmt_float(c, 2) for c in v.camera_position) + ")"
if v.fov:
cam += f" fov={v.fov:g}"
t = f" t={v.time_s:g}s" if v.time_s is not None else ""
lines.append(f"- {v.name} [{v.mode}{t}]{cam} → {rel_path(v.path, root)}")
if rs.console_errors:
lines.append(f"console errors ({len(rs.console_errors)}):")
lines.extend(f" ! {e[:200]}" for e in rs.console_errors[:8])
if rs.fps is not None:
lines.append(f"fps ≈ {rs.fps:.0f}")
numbers: dict[str, Any] = {"n_views": len(rs.views), "views": [v.name for v in rs.views]}
if rs.fps is not None:
numbers["fps"] = rs.fps
if rs.console_errors:
numbers["console_errors"] = len(rs.console_errors)
return Observation(ok=bool(rs.views) and not rs.console_errors,
failed=not rs.views and not rs.console_errors,
text=truncate("\n".join(lines)), numbers=numbers, images=[str(i) for i in images if i])