brickwright 0.1.0__py3-none-any.whl

brickwright/driver/critique.py

@@ -0,0 +1,133 @@
+"""The visual-critique step: an independent model judges the build against the target.
+
+A separate agent first picks a camera angle whose render matches the reference's
+viewpoint (see :mod:`.viewpoint`); a single call then sees the reference beside that
+matched render and reports whether they match and what differs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, ValidationError
+
+from ..config import Config
+from ..record import Record
+from .completion import bad_request_error, litellm_complete
+from .messages import image_content_block, request_kwargs
+from .viewpoint import match_viewpoint
+
+VIEWPOINT_COMPARE_PROMPT = """\
+You are an independent reviewer judging how faithfully a LEGO build reproduces a
+target object. You are given:
+
+1. The target reference image.
+2. A single rendered image of the LEGO build, captured from a camera viewpoint chosen
+   to match the reference's viewpoint.
+3. The original text prompt that requested the build.
+
+First describe both objects in detail, then enumerate the concrete differences between
+them. Judge only the main object that the prompt refers to -- ignore lighting, shadows,
+background, camera angle, photographic style, and rendering artifacts. Focus on shape,
+proportions, structure, parts and coloring, and any missing or extra features.
+
+Reply with a single JSON object with exactly these keys:
+- "differences_description": a string with your detailed descriptions of both objects
+  followed by the differences between them.
+- "done": a boolean -- true if the build faithfully matches the reference (only minor
+  or cosmetic differences remain), false if it should be revised further.
+
+Reply with only the JSON object, no prose around it."""
+
+# What the critic is shown as the original prompt when the build had none.
+NO_TEXT_PROMPT = "(no text prompt)"
+
+
+class CritiqueResult(BaseModel):
+    """An independent reviewer's verdict comparing the build to the target image."""
+
+    model_config = ConfigDict(frozen=True)
+
+    differences_description: str
+    done: bool
+
+
+def critique(
+    record: Record,
+    config: Config,
+    *,
+    complete: Callable[..., Any] | None = None,
+    on_response: Callable[[Any], None] | None = None,
+) -> CritiqueResult | None:
+    """Compare the build to the prompt image and return the verdict.
+
+    The build is shown from a camera angle matched to the reference's viewpoint.
+    The result is ``None`` when no comparison could be made: no matched render, or a
+    reply that won't parse into a verdict. Raises ``ValueError`` without a prompt
+    image.
+
+    ``on_response`` observes every raw completion response immediately (the
+    viewpoint agent's and the critic's), so the caller can fold their usage and cost
+    into the run's tracker; it may raise to stop before another paid request.
+    """
+    reference = record.prompt_image_path
+    if reference is None:
+        raise ValueError("critique requires a prompt image")
+    complete = complete or litellm_complete()
+    prompt = record.read_meta().prompt or NO_TEXT_PROMPT
+
+    result = match_viewpoint(record, config, complete=complete, on_response=on_response)
+    if result is None:
+        return None  # no matched render to compare against
+
+    content: list[dict[str, Any]] = [
+        {"type": "text", "text": f"Original prompt:\n{prompt}"},
+        {"type": "text", "text": "Target reference image:"},
+        image_content_block(reference),
+        {
+            "type": "text",
+            "text": (
+                "The LEGO build, rendered from a viewpoint chosen to match the "
+                f"reference (azimuth {result.azimuth:g}, elevation {result.elevation:g}):"
+            ),
+        },
+        image_content_block(record.viewpoint_path),
+    ]
+    messages = [
+        {"role": "system", "content": VIEWPOINT_COMPARE_PROMPT},
+        {"role": "user", "content": content},
+    ]
+    response = _complete(complete, config, messages)
+    if on_response is not None:
+        on_response(response)
+    try:
+        return CritiqueResult.model_validate_json(_text_of(response))
+    except ValidationError:
+        return None
+
+
+_RESPONSE_FORMATS = (CritiqueResult, {"type": "json_object"})
+
+
+def _complete(
+    complete: Callable[..., Any], config: Config, messages: list[dict[str, Any]]
+) -> Any:
+    """Run one critic completion, weakening response_format until the provider takes it."""
+    kwargs = request_kwargs(config, "critique")
+
+    def ask(**asked: Any) -> Any:
+        return complete(messages=messages, **asked, **kwargs)
+
+    for response_format in _RESPONSE_FORMATS:
+        try:
+            return ask(response_format=response_format)
+        except bad_request_error() as exc:
+            if "response_format" not in str(exc):
+                raise
+    return ask()
+
+
+def _text_of(response: Any) -> str:
+    """The text content of a completion response (``""`` if it has none)."""
+    return response.choices[0].message.content or ""

brickwright/driver/external_critique.py

@@ -0,0 +1,114 @@
+"""The playbook ``brickwright external critique-instructions`` prints.
+
+It has the external agent dispatch two fresh subagents -- one to match the viewpoint
+(rendering through ``brickwright external render-angle``), one to critique -- each
+handed the driver's own system prompt.
+"""
+
+from __future__ import annotations
+
+from ..record import Record
+from .critique import NO_TEXT_PROMPT, VIEWPOINT_COMPARE_PROMPT
+from .viewpoint import ANGLE_CONVENTIONS, ORIENTATION_HINT, VIEWPOINT_TASK
+
+DEFAULT_CRITIQUE_ROUNDS = 2
+
+
+def external_viewpoint_prompt(record_id: str, viewpoint_path: str) -> str:
+    """The angle-finding subagent's system prompt: the driver's
+    :data:`~driver.viewpoint.VIEWPOINT_TASK`, rendering through
+    ``brickwright external render-angle``."""
+    return f"""\
+{VIEWPOINT_TASK}
+
+Render the build from a camera angle by running this command from the repository root:
+
+    uv run brickwright external render-angle {record_id} --azimuth <A> --elevation <E>
+
+{ANGLE_CONVENTIONS}
+
+The command renders the build, writes the image to
+{viewpoint_path}
+(overwriting any previous one), and prints that path. Open the PNG, compare its viewpoint
+to the reference, and re-run the command with adjusted angles to get closer.
+{ORIENTATION_HINT} Use as few renders as you need. When the render is seen from essentially the same viewpoint as
+the reference, stop -- your final render must be that matched view, so it is left at the
+path above for the critic to compare against. Then reply with a plain-text message
+reporting the matched azimuth and elevation and confirming the render at that path."""
+
+
+def external_critique_instructions(
+    record: Record, *, rounds: int = DEFAULT_CRITIQUE_ROUNDS
+) -> str:
+    """Assemble the record-specific critique playbook for the external agent.
+
+    Raises ``ValueError`` when the record has no prompt image, since there is nothing to
+    critique the build against -- the external mirror of the driver skipping the loop.
+    """
+    reference = record.prompt_image_path
+    if reference is None:
+        raise ValueError("external critique requires a prompt image")
+
+    record_id = record.id
+    reference_path = str(reference.absolute())
+    build_path = str(record.build_path.absolute())
+    viewpoint_path = str(record.viewpoint_path.absolute())
+    prompt = record.read_meta().prompt or NO_TEXT_PROMPT
+    viewpoint_prompt = external_viewpoint_prompt(record_id, viewpoint_path)
+    # Braces in the JSON schema example are doubled so the f-string emits them literally.
+    return f"""\
+# BrickWright visual critique (image prompt)
+
+This is the external-agent counterpart of the driver's `viewpoint` visual-critique loop.
+Run it for image-prompt builds once the build validates and renders acceptably, to check
+the build against the reference image and revise it before finalizing.
+
+The loop has two steps, and each is run by a **fresh subagent** -- a new agent started
+with no prior context, so it judges independently, exactly as the driver runs each step as
+an independent model call. Dispatch the subagents yourself, and give each one the system
+prompt quoted below **verbatim**. Do not do these steps in your own context.
+
+- Record: {record_id}
+- Reference image: {reference_path}
+- build.py: {build_path}
+- Original prompt: {prompt}
+
+Repeat the loop below up to {rounds} time(s), or until the critic reports `"done": true`.
+
+## Step A -- match the camera viewpoint (fresh subagent)
+
+Dispatch a fresh subagent whose system prompt is exactly:
+
+----------------------------------------------------------------------
+{viewpoint_prompt}
+----------------------------------------------------------------------
+
+Give that subagent this task: read the reference image at {reference_path} and the build
+source at {build_path}, then find the matching camera angle as its system prompt
+instructs. It leaves the matched render at {viewpoint_path} and reports the azimuth and
+elevation it chose.
+
+## Step B -- critique the build (fresh subagent)
+
+Dispatch a second fresh subagent whose system prompt is exactly:
+
+----------------------------------------------------------------------
+{VIEWPOINT_COMPARE_PROMPT}
+----------------------------------------------------------------------
+
+Give that subagent this task:
+
+- Original prompt: {prompt}
+- Read the target reference image at {reference_path}.
+- Read the LEGO build's matched render at {viewpoint_path}.
+
+It must reply with only the JSON object its system prompt describes
+(`{{"differences_description": "...", "done": true|false}}`).
+
+## Step C -- revise
+
+Parse the critic's JSON. If `"done"` is true, the build matches the reference well enough:
+stop the loop and finalize. Otherwise edit `build.py` to address the
+`differences_description`, re-run `uv run brickwright external validate {record_id}` until
+it passes, then repeat from Step A. Stop after {rounds} round(s) even if the critic is not
+yet satisfied."""

brickwright/driver/gallery.py

@@ -0,0 +1,289 @@
+"""A catalog of the Narrator's lifecycle, tool, and summary output."""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+from rich.console import Console
+
+from ..config import Config, Effort
+from ..record import Timing, Usage
+from ..tools.registry import ToolOutcome, subagent_outcome, validation_outcome
+from ..tools.subagents import SubagentResult
+from ..tools.testing import CheckResult
+from ..tools.validation import BuildDimensions, ValidationReport
+from .narration import Narrator
+from .report import RunReport
+
+_SAMPLE_SOURCE = """\
+import bricklayer as bl
+
+
+def create_build():
+    build = bl.LegoBuild()
+    base = build.add(bl.brick(4, 2, color=bl.Color.RED), name="base")
+    build.stack(bl.brick(4, 2, color=bl.Color.RED), on=base)
+    return build
+"""
+
+_TRACEBACK = """\
+Traceback (most recent call last):
+  File "<explore>", line 1, in <module>
+ValueError: no part matches id '9999'
+"""
+
+
+def print_gallery(console: Console | None = None) -> None:
+    """Print one example of every Narrator output to ``console``."""
+    console = console or Console()
+    narrator = Narrator(console)
+    record = _sample_record()
+    config = _sample_config()
+
+    _section(console, "lifecycle")
+    narrator.run_started(record, config)
+    narrator.turn_started(1)
+    narrator.model_message(
+        "I'll lay a 4×2 footprint and stack two courses of red brick."
+    )
+    narrator.warn("the cost limit cannot be enforced for this provider")
+
+    _section(console, "tool calls & results")
+    for call in _tool_scenes():
+        narrator.tool_called(call.name, call.arguments)
+        for outcome in call.outcomes:
+            narrator.tool_finished(call.name, outcome)
+        print()
+
+    _section(console, "run summary")
+    for result in _summary_scenes():
+        narrator.run_finished(record, result)
+        print()
+
+
+@dataclass(frozen=True)
+class _Call:
+    """One tool's call line plus the result variants worth showing."""
+
+    name: str
+    arguments: dict[str, Any] = field(default_factory=dict)
+    outcomes: list[ToolOutcome] = field(default_factory=list)
+
+
+def _tool_scenes() -> list[_Call]:
+    return [
+        _Call(
+            name="read_build",
+            outcomes=[ToolOutcome(_SAMPLE_SOURCE)],
+        ),
+        _Call(
+            name="write_build",
+            arguments={"content": _SAMPLE_SOURCE},
+            outcomes=[
+                ToolOutcome("ok: build.py written"),
+                ToolOutcome("write failed: missing argument 'content'", ok=False),
+            ],
+        ),
+        _Call(
+            name="insert_build",
+            arguments={
+                "insert_line": 6,
+                "insert_text": "    build.stack(bl.tile(4, 2, color=bl.Color.WHITE), on=base)",
+            },
+            outcomes=[
+                ToolOutcome(
+                    "ok: build.py edited. Edited region:\n"
+                    "7:     build.stack(bl.tile(4, 2, color=bl.Color.WHITE), on=base)"
+                ),
+                ToolOutcome(
+                    "insert failed: invalid insert_line 99: must be in 0..12 "
+                    "(0 inserts at the top of the file; N inserts after line N)",
+                    ok=False,
+                ),
+            ],
+        ),
+        _Call(
+            name="edit_build",
+            arguments={
+                "old_str": "bl.brick(4, 2, color=bl.Color.RED), name=",
+                "new_str": "bl.brick(4, 2, color=bl.Color.BLUE), name=",
+            },
+            outcomes=[
+                ToolOutcome("ok: build.py edited"),
+                ToolOutcome("edit failed: old_str not found", ok=False),
+            ],
+        ),
+        _Call(
+            name="multi_edit_build",
+            arguments={
+                "edits": [
+                    {"old_str": "Color.RED", "new_str": "Color.BLUE"},
+                    {"old_str": "bl.brick(4, 2,", "new_str": "bl.brick(4, 4,"},
+                ]
+            },
+            outcomes=[
+                ToolOutcome("ok: applied 2 edits to build.py"),
+                ToolOutcome(
+                    "multi-edit failed (build.py unchanged): "
+                    "edit 2 of 2: old_str not found",
+                    ok=False,
+                ),
+            ],
+        ),
+        _Call(
+            name="validate",
+            outcomes=[
+                validation_outcome(
+                    ValidationReport(
+                        ok=True,
+                        dimensions=BuildDimensions(width=4, depth=2, height=2.0),
+                        brick_count=8,
+                        checks=[
+                            CheckResult(name="connected", passed=True, detail=""),
+                            CheckResult(name="no_collisions", passed=True, detail=""),
+                        ],
+                    )
+                ),
+                validation_outcome(
+                    ValidationReport(
+                        ok=False,
+                        dimensions=BuildDimensions(width=4, depth=2, height=2.0),
+                        brick_count=8,
+                        checks=[
+                            CheckResult(name="connected", passed=True, detail=""),
+                            CheckResult(
+                                name="no_collisions",
+                                passed=False,
+                                detail="2 bricks overlap at (2, 0)",
+                            ),
+                        ],
+                    )
+                ),
+                validation_outcome(
+                    ValidationReport.error(
+                        "Traceback (most recent call last):\n"
+                        "NameError: name 'Color' is not defined"
+                    )
+                ),
+            ],
+        ),
+        _Call(
+            name="explore",
+            arguments={"code": "print(bricklayer.search_parts('brick', limit=5))"},
+            outcomes=[
+                ToolOutcome("Brick 2x2"),
+                ToolOutcome("Brick 2x2 (3003)\nBrick 2x4 (3001)\nBrick 1x2 (3004)"),
+                ToolOutcome(f"explore error:\n{_TRACEBACK}", ok=False),
+            ],
+        ),
+        _Call(
+            name="render",
+            outcomes=[
+                ToolOutcome(
+                    "ok: rendered the build to a multi-view contact sheet; "
+                    "the image follows.",
+                    image=Path("out/render.png"),
+                ),
+                ToolOutcome(f"render failed:\n{_TRACEBACK}", ok=False),
+            ],
+        ),
+        _Call(
+            name="finalize",
+            outcomes=[
+                ToolOutcome("ok: build compiled to out/build.ldr", done=True),
+                ToolOutcome(f"compile failed:\n{_TRACEBACK}", ok=False, done=True),
+            ],
+        ),
+        _Call(
+            name="dispatch_subagents",
+            arguments={
+                "tasks": [
+                    {"prompt": "Design the archway using arch parts.", "tier": "smart"},
+                    {"prompt": "Design the two flanking towers.", "tier": "balanced"},
+                ]
+            },
+            outcomes=[
+                subagent_outcome(
+                    [
+                        SubagentResult(ok=True, text="Use two 1x6 arch bricks (3455)."),
+                        SubagentResult(ok=True, text="Stack 2x2 round bricks (3941)."),
+                    ]
+                ),
+                subagent_outcome(
+                    [
+                        SubagentResult(ok=True, text="Use two 1x6 arch bricks (3455)."),
+                        SubagentResult(
+                            ok=False,
+                            reason="subagent produced no final answer",
+                        ),
+                    ]
+                ),
+            ],
+        ),
+    ]
+
+
+def _summary_scenes() -> list[RunReport]:
+    usage = Usage(
+        prompt_tokens=18_432,
+        completion_tokens=2_561,
+        total_tokens=20_993,
+        cost_usd=0.2317,
+    )
+    timing = Timing(
+        total=42.8, llm=31.2, tools={"validate": 8.1, "render": 2.9}, other=0.6
+    )
+    return [
+        RunReport(
+            done=True,
+            source_sha256="example-source",
+            report=ValidationReport(ok=True, source_sha256="example-source"),
+            validations=3,
+            turns=11,
+            usage=usage,
+            timing=timing,
+        ),
+        RunReport(
+            done=True,
+            report=ValidationReport(ok=False),
+            validations=5,
+            turns=14,
+            usage=usage,
+            timing=timing,
+        ),
+        RunReport(
+            done=False,
+            report=ValidationReport(ok=True),
+            validations=2,
+            turns=30,
+            usage=usage,
+            timing=timing,
+        ),
+    ]
+
+
+def _section(console: Console, title: str) -> None:
+    console.print()
+    console.rule(f"[bold]{title}", style="blue")
+    console.print()
+
+
+def _sample_record() -> Any:
+    """A stand-in record exposing just what the narration panels read."""
+    meta = SimpleNamespace(prompt="Build a 4×2 red brick wall, two courses high.")
+    return SimpleNamespace(
+        id="rec_3f9a2b-red-brick-wall",
+        path=Path("records/rec_3f9a2b-red-brick-wall"),
+        read_meta=lambda: meta,
+    )
+
+
+def _sample_config() -> Config:
+    return Config(
+        model="anthropic/claude-opus-4-8",
+        effort=Effort.HIGH,
+        max_validations=10,
+        max_turns=30,
+        max_cost=5.0,
+    )