brickwright 0.1.0__py3-none-any.whl

brickwright/__init__.py

@@ -0,0 +1,5 @@
+"""BrickWright: an agent harness for building LEGO models with BrickLayer."""
+
+from .tools.testing import TestContext
+
+__all__ = ["TestContext"]

brickwright/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m brickwright`` as an alias for the CLI."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

brickwright/_build_template.py

@@ -0,0 +1,25 @@
+import bricklayer as bl
+
+from brickwright import TestContext
+
+
+def create_build():
+    """Return the finished :class:`bricklayer.LegoBuild`."""
+    build = bl.LegoBuild()
+    # TODO: assemble the requested build
+    build.add(
+        bl.brick(2, 2, color=bl.Color.RED), bl.Position(0, 0, 0), bl.Rotation.FRONT
+    )
+    return build
+
+
+def run_tests():
+    """Create the build and return a report of which checks passed."""
+    build = create_build()
+    tests = TestContext(build)
+    tests.check_no_floating()
+    tests.check_no_collisions()
+    tests.check_connected(expected_components=1)
+    # Add a custom check for any measurable requirement, e.g.:
+    # tests.check("over 100 bricks", build.brick_count > 100)
+    return tests.report()

brickwright/cli.py

@@ -0,0 +1,446 @@
+"""Command-line interface to generate LEGO builds using BrickWright.
+
+Top-level commands are for a human orchestrating runs; the ``external`` group
+holds the operations an external agent (e.g. Claude Code pointed at the
+package) drives to iterate on a build.
+"""
+
+import time
+from collections.abc import Generator
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+
+from .config import (
+    DEFAULT_RECORDS_DIR,
+    RECORDS_DIR_ENV,
+    Config,
+    CritiqueMode,
+    Effort,
+)
+from .driver import run_agent
+from .driver.external_critique import (
+    DEFAULT_CRITIQUE_ROUNDS,
+    external_critique_instructions,
+)
+from .driver.gallery import print_gallery
+from .driver.tracking import tally_failure
+from .prompts import system_prompt
+from .record import Record, Timing, ValidationFailures, list_records
+from .tools import FinalizationReport, RenderReport, ValidationReport
+from .tools import finalize as finalize_record
+from .tools import render as render_record
+from .tools import render_angle as render_angle_record
+from .tools import validate as validate_record
+from .tools.software_rendering import MAX_ELEVATION
+
+app = typer.Typer(
+    name="brickwright",
+    help=__doc__,
+    add_completion=False,
+    no_args_is_help=True,
+)
+
+external_app = typer.Typer(
+    help="Operations meant for an external agent.",
+    no_args_is_help=True,
+)
+app.add_typer(external_app, name="external")
+
+RecordsDir = Annotated[
+    Path,
+    typer.Option(
+        "--records-dir", envvar=RECORDS_DIR_ENV, help="where record directories live"
+    ),
+]
+Prompt = Annotated[str | None, typer.Argument(help="text prompt")]
+RecordId = Annotated[str, typer.Argument(help="record id")]
+Image = Annotated[Path | None, typer.Option(help="image prompt")]
+
+# Defaults for the Config-backed options, so Typer can display them in --help.
+_DEFAULTS = Config()
+Model = Annotated[
+    str | None,
+    typer.Option(envvar="BRICKWRIGHT_GENERATION_MODEL", help="generation model id"),
+]
+Effort_ = Annotated[Effort | None, typer.Option(help="reasoning effort")]
+MaxValidations = Annotated[
+    int, typer.Option(min=0, help="cap on validate calls (0: unlimited)")
+]
+MaxTurns = Annotated[int, typer.Option(min=0, help="cap on model turns (0: unlimited)")]
+MaxCost = Annotated[float, typer.Option(help="cap on USD spent per run")]
+BuildTimeout = Annotated[float, typer.Option(help="max seconds per build")]
+RenderTimeout = Annotated[float, typer.Option(help="max seconds per render")]
+RequestTimeout = Annotated[
+    float | None,
+    typer.Option(help="max seconds per LLM request (unset: the client's own default)"),
+]
+Subagents = Annotated[
+    bool,
+    typer.Option(
+        "--use-subagents/--no-use-subagents",
+        help="allow dispatching subagents to complete subtasks in parallel",
+    ),
+]
+MaxParallelSubagents = Annotated[
+    int, typer.Option(help="cap on concurrently running subagents")
+]
+SubagentMaxTurns = Annotated[int, typer.Option(help="cap on model turns per subagent")]
+SubagentMaxCost = Annotated[float, typer.Option(help="cap on USD spent per subagent")]
+CritiqueRounds = Annotated[
+    int, typer.Option(help="outer visual-critique rounds (0 disables the loop)")
+]
+CritiqueMode_ = Annotated[
+    CritiqueMode, typer.Option(help="how the builder re-enters after a critique")
+]
+CritiqueModel = Annotated[
+    str | None, typer.Option(help="critic model id (defaults to --model)")
+]
+CritiqueEffort = Annotated[
+    Effort | None, typer.Option(help="critic reasoning effort (defaults to --effort)")
+]
+ViewpointIterations = Annotated[
+    int,
+    typer.Option(
+        help="viewpoint-matching iterations per critique round (0 disables the critique)"
+    ),
+]
+ViewpointModel = Annotated[
+    str | None, typer.Option(help="viewpoint agent model id (defaults to --model)")
+]
+ViewpointEffort = Annotated[
+    Effort | None, typer.Option(help="viewpoint agent effort (defaults to --effort)")
+]
+
+FromId = Annotated[
+    str | None, typer.Option("--from", help="fork a new record from this record id")
+]
+
+Azimuth = Annotated[
+    float,
+    typer.Option(help="horizontal camera angle in degrees (-180..180; 0 = front)"),
+]
+Elevation = Annotated[
+    float,
+    typer.Option(
+        help=(
+            f"vertical camera angle in degrees (-{MAX_ELEVATION:g}..{MAX_ELEVATION:g};"
+            " 0 = level)"
+        )
+    ),
+]
+AngleOut = Annotated[
+    Path | None,
+    typer.Option("--out", help="output PNG path (default: the record's viewpoint.png)"),
+]
+CritiqueInstructionsRounds = Annotated[
+    int,
+    typer.Option(
+        "--critique-rounds", help="rounds the printed critique playbook advises"
+    ),
+]
+
+
+@app.command()
+def generate(
+    prompt: Prompt = None,
+    image: Image = None,
+    records_dir: RecordsDir = Path(DEFAULT_RECORDS_DIR),
+    model: Model = _DEFAULTS.model,
+    effort: Effort_ = _DEFAULTS.effort,
+    max_validations: MaxValidations = _DEFAULTS.max_validations,
+    max_turns: MaxTurns = _DEFAULTS.max_turns,
+    max_cost: MaxCost = _DEFAULTS.max_cost,
+    build_timeout: BuildTimeout = _DEFAULTS.build_timeout,
+    render_timeout: RenderTimeout = _DEFAULTS.render_timeout,
+    request_timeout: RequestTimeout = _DEFAULTS.request_timeout,
+    use_subagents: Subagents = _DEFAULTS.subagents_enabled,
+    max_parallel_subagents: MaxParallelSubagents = _DEFAULTS.max_parallel_subagents,
+    subagent_max_turns: SubagentMaxTurns = _DEFAULTS.subagent_max_turns,
+    subagent_max_cost: SubagentMaxCost = _DEFAULTS.subagent_max_cost,
+    critique_rounds: CritiqueRounds = _DEFAULTS.max_critique_rounds,
+    critique_mode: CritiqueMode_ = _DEFAULTS.critique_mode,
+    critique_model: CritiqueModel = _DEFAULTS.critique_model,
+    critique_effort: CritiqueEffort = _DEFAULTS.critique_effort,
+    viewpoint_iterations: ViewpointIterations = _DEFAULTS.max_viewpoint_iterations,
+    viewpoint_model: ViewpointModel = _DEFAULTS.viewpoint_model,
+    viewpoint_effort: ViewpointEffort = _DEFAULTS.viewpoint_effort,
+    from_id: FromId = None,
+) -> None:
+    """Generate a new LEGO build record from a text or image prompt."""
+    config = Config(
+        records_dir=records_dir,
+        model=model,
+        effort=effort,
+        max_validations=max_validations,
+        max_turns=max_turns,
+        max_cost=max_cost,
+        build_timeout=build_timeout,
+        render_timeout=render_timeout,
+        request_timeout=request_timeout,
+        subagents_enabled=use_subagents,
+        max_parallel_subagents=max_parallel_subagents,
+        subagent_max_turns=subagent_max_turns,
+        subagent_max_cost=subagent_max_cost,
+        max_critique_rounds=critique_rounds,
+        critique_mode=critique_mode,
+        critique_model=critique_model,
+        critique_effort=critique_effort,
+        max_viewpoint_iterations=viewpoint_iterations,
+        viewpoint_model=viewpoint_model,
+        viewpoint_effort=viewpoint_effort,
+    )
+    rec = _create_record(config, prompt=prompt, image=image, from_id=from_id)
+    if not run_agent(rec, config).succeeded:
+        raise typer.Exit(1)
+
+
+@app.command()
+def show(
+    record_id: RecordId, records_dir: RecordsDir = Path(DEFAULT_RECORDS_DIR)
+) -> None:
+    """Print a record's metadata."""
+    meta = Record.load(Config(records_dir=records_dir), record_id).read_meta()
+    Console().print_json(meta.model_dump_json(indent=2))
+
+
+@app.command()
+def ls(records_dir: RecordsDir = Path(DEFAULT_RECORDS_DIR)) -> None:
+    """List records."""
+    console = Console()
+    for rec in list_records(Config(records_dir=records_dir)):
+        try:
+            meta = rec.read_meta()
+        except (OSError, ValueError):
+            console.print(f"{rec.id}\tunreadable", markup=False, soft_wrap=True)
+            continue
+        summary = (meta.prompt or "").partition("\n")[0][:48]
+        console.print(
+            f"{rec.id}\t{meta.status.value}\t{summary}",
+            markup=False,  # don't break if summary text has special characters
+            soft_wrap=True,  # one line per record even with long records
+        )
+
+
+@app.command(hidden=True)
+def gallery() -> None:
+    """Print a style guide of every narration output (for testing purposes)."""
+    print_gallery()
+
+
+@external_app.command()
+def init(
+    prompt: Prompt = None,
+    image: Image = None,
+    records_dir: RecordsDir = Path(DEFAULT_RECORDS_DIR),
+    model: Model = None,
+    effort: Effort_ = None,
+    from_id: FromId = None,
+) -> None:
+    """Initialize a new record.
+
+    Prints the new record's id and path to the build.py file to be edited.
+    An external agent should edit the build.py file directly, then run
+    ``brickwright external validate <record_id>`` to validate it.
+    """
+    config = Config(records_dir=records_dir, model=model, effort=effort)
+    rec = _create_record(
+        config, prompt=prompt, image=image, from_id=from_id, external=True
+    )
+    print(f"record_id={rec.id}")
+    print(f"build_path={rec.build_path.absolute()}")
+
+
+@external_app.command()
+def instructions() -> None:
+    print(system_prompt(external=True))
+
+
+@external_app.command()
+def validate(
+    record_id: RecordId,
+    records_dir: RecordsDir = Path(DEFAULT_RECORDS_DIR),
+    timeout: BuildTimeout = _DEFAULTS.build_timeout,
+    max_validations: MaxValidations = _DEFAULTS.max_validations,
+) -> None:
+    """Verify a record's correctness."""
+    config = Config(
+        records_dir=records_dir,
+        build_timeout=timeout,
+        max_validations=max_validations,
+    )
+    rec = Record.load(config, record_id)
+
+    validations = rec.read_meta().validations
+    # Each call is one validation; refuse once the budget is spent.
+    if config.max_validations and validations >= config.max_validations:
+        typer.echo(
+            f"validation budget of {config.max_validations} reached; stop validating",
+            err=True,
+        )
+        raise typer.Exit(1)
+    with _track_command(rec, "validate"):
+        report = validate_record(rec, config)
+    failures = rec.read_meta().validation_failures or ValidationFailures()
+    rec.update_meta(
+        validations=validations + 1,
+        validation_failures=tally_failure(failures, report),
+    )
+
+    _print_report(report)
+
+
+@external_app.command()
+def finalize(
+    record_id: RecordId,
+    records_dir: RecordsDir = Path(DEFAULT_RECORDS_DIR),
+    timeout: RenderTimeout = _DEFAULTS.render_timeout,
+) -> None:
+    """Finalize a record.
+
+    Run this once the build is valid (per ``validate``) and you are finished.
+    The finished build is compiled into an LDraw file and, when a parts library
+    is available, rendered to a multi-view PNG.
+    """
+    config = Config(records_dir=records_dir, render_timeout=timeout)
+    rec = Record.load(config, record_id)
+
+    with _track_command(rec, "finalize"):
+        report = finalize_record(rec, config)
+
+    # Close out the run: total wall-clock from creation, remainder attributed to llm.
+    meta = rec.read_meta()
+    created = meta.created
+    if created is not None:
+        timing = meta.timing or Timing()
+        total = round((datetime.now(created.tzinfo) - created).total_seconds(), 3)
+        llm = round(max(0.0, total - sum(timing.tools.values())), 3)
+        rec.update_meta(timing=timing.model_copy(update={"total": total, "llm": llm}))
+
+    _print_report(report)
+
+
+@external_app.command()
+def render(
+    record_id: RecordId,
+    records_dir: RecordsDir = Path(DEFAULT_RECORDS_DIR),
+    timeout: RenderTimeout = _DEFAULTS.render_timeout,
+) -> None:
+    """Render a record's current build to a multi-view image.
+
+    Writes ``out/build.png`` and prints its path. Open that file to see how the
+    build currently looks (front, side, top, and isometric views).
+    """
+    config = Config(records_dir=records_dir, render_timeout=timeout)
+    rec = Record.load(config, record_id)
+
+    with _track_command(rec, "render"):
+        report = render_record(rec, config)
+    _print_image_and_report(report)
+
+
+@external_app.command(name="render-angle")
+def render_angle(
+    record_id: RecordId,
+    azimuth: Azimuth = 0.0,
+    elevation: Elevation = 0.0,
+    out: AngleOut = None,
+    records_dir: RecordsDir = Path(DEFAULT_RECORDS_DIR),
+    timeout: RenderTimeout = _DEFAULTS.render_timeout,
+) -> None:
+    """Render the current build from a single camera angle.
+
+    Writes the image (default: the record's ``out/viewpoint.png``) and prints its path.
+    """
+    config = Config(records_dir=records_dir, render_timeout=timeout)
+    rec = Record.load(config, record_id)
+
+    with _track_command(rec, "render-angle"):
+        report = render_angle_record(rec, azimuth, elevation, config, out_path=out)
+    _print_image_and_report(report)
+
+
+@external_app.command(name="critique-instructions")
+def critique_instructions(
+    record_id: RecordId,
+    records_dir: RecordsDir = Path(DEFAULT_RECORDS_DIR),
+    critique_rounds: CritiqueInstructionsRounds = DEFAULT_CRITIQUE_ROUNDS,
+) -> None:
+    """Print the visual-critique playbook for this record.
+
+    The external counterpart of the driver's ``viewpoint`` critique loop. It tells you to
+    dispatch two fresh subagents -- one to match the camera viewpoint (via
+    ``render-angle``), one to critique the render against the reference image -- each with
+    the same system prompt the driver path uses, then to revise ``build.py`` from the
+    critic's verdict. Requires the record to have a prompt image.
+    """
+    rec = Record.load(Config(records_dir=records_dir), record_id)
+    try:
+        print(external_critique_instructions(rec, rounds=critique_rounds))
+    except ValueError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(1) from exc
+
+
+def _create_record(
+    config: Config,
+    *,
+    prompt: str | None,
+    image: Path | None,
+    from_id: str | None,
+    external: bool = False,
+) -> Record:
+    if not prompt and image is None and from_id is None:
+        raise typer.BadParameter("provide a prompt, --image, or --from")
+    return Record.create(
+        config, prompt=prompt or "", image=image, from_id=from_id, external=external
+    )
+
+
+@contextmanager
+def _track_command(rec: Record, name: str) -> Generator[None]:
+    """Time the wrapped command and tally it on the record's meta.
+
+    The wall-clock is added to this command's entry in the timing breakdown, and
+    the call is counted toward ``tool_calls`` under ``name``.
+    """
+    start = time.perf_counter()
+    try:
+        yield
+    finally:
+        dt = time.perf_counter() - start
+        meta = rec.read_meta()
+        timing = meta.timing or Timing()
+        tools = {**timing.tools, name: round(timing.tools.get(name, 0.0) + dt, 3)}
+        rec.update_meta(
+            timing=timing.model_copy(update={"tools": tools}),
+            tool_calls={**meta.tool_calls, name: meta.tool_calls.get(name, 0) + 1},
+        )
+
+
+def _print_image_and_report(report: RenderReport) -> None:
+    """Print the rendered image's path (when there is one), then the report."""
+    if report.ok and report.image_path is not None:
+        print(str(report.image_path.absolute()))
+    _print_report(report)
+
+
+def _print_report(
+    report: ValidationReport | FinalizationReport | RenderReport,
+) -> None:
+    """Print the report as JSON and exit nonzero if the operation failed."""
+    print(report.model_dump_json(indent=2))
+    if not report.ok:
+        raise typer.Exit(1)
+
+
+def main(argv: list[str] | None = None) -> None:
+    app(args=argv)
+
+
+if __name__ == "__main__":
+    main()

brickwright/config.py

@@ -0,0 +1,104 @@
+"""Harness configuration: where records live and how the agent is driven."""
+
+import os
+from copy import deepcopy
+from enum import Enum
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# Where records live by default, and the env var that overrides it.
+DEFAULT_RECORDS_DIR = "records"
+RECORDS_DIR_ENV = "BRICKWRIGHT_RECORDS_DIR"
+
+
+def default_records_dir() -> Path:
+    return Path(os.environ.get(RECORDS_DIR_ENV, DEFAULT_RECORDS_DIR))
+
+
+class Effort(str, Enum):
+    """How much reasoning effort to request from the model."""
+
+    NONE = "none"
+    MINIMAL = "minimal"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    XHIGH = "xhigh"
+    MAX = "max"
+
+
+# Subagent model tiers per provider; an absent provider uses the main model.
+DEFAULT_SUBAGENT_TIERS: dict[str, dict[str, str]] = {
+    "openai": {
+        "smart": "openai/gpt-6-astra",
+        "balanced": "openai/gpt-6-sol",
+        "fast": "openai/gpt-6-luna",
+    },
+    "anthropic": {
+        "smart": "anthropic/claude-opus-4-8",
+        "balanced": "anthropic/claude-sonnet-5",
+        "fast": "anthropic/claude-haiku-4-5",
+    },
+    "google": {
+        "smart": "gemini/gemini-pro-latest",
+        "balanced": "gemini/gemini-flash-latest",
+        "fast": "gemini/gemini-flash-lite-latest",
+    },
+}
+
+
+class CritiqueMode(str, Enum):
+    """How the builder re-enters after a visual critique asks for changes."""
+
+    CONTINUE = "continue"  # resume the builder's existing conversation
+    FRESH = "fresh"  # re-seed a new conversation each round
+
+
+class Config(BaseModel):
+    """Main configuration class for BrickWright."""
+
+    model_config = ConfigDict(frozen=True)
+
+    records_dir: Path = Field(default_factory=default_records_dir)
+    model: str | None = None
+    effort: Effort | None = Effort.HIGH
+    max_validations: int = Field(default=50, ge=0)  # 0 disables the validation cap
+    max_turns: int = Field(default=200, ge=0)  # 0 disables the turn cap
+    max_cost: float = 5.0  # cap on USD spent per run
+    build_timeout: float = 30.0
+    render_timeout: float = 60.0
+    # Seconds allowed for one LLM request; ``None`` leaves it to the client.
+    request_timeout: float | None = None
+    subagents_enabled: bool = False
+    is_subagent: bool = False  # internal: this run is a subagent
+    subagent_tiers: dict[str, dict[str, str]] = Field(
+        default_factory=lambda: deepcopy(DEFAULT_SUBAGENT_TIERS)
+    )
+    max_parallel_subagents: int = 4
+    subagent_max_turns: int = 100
+    subagent_max_cost: float = 1.0  # USD
+    max_critique_rounds: int = 0  # outer visual-critique rounds (0 disables the loop)
+    critique_mode: CritiqueMode = CritiqueMode.CONTINUE  # how the builder re-enters
+    critique_model: str | None = None  # critic model id (None -> use ``model``)
+    critique_effort: Effort | None = None  # critic effort (None -> use ``effort``)
+    # Viewpoint-matching agent: picks a camera angle whose render matches the
+    # reference image's viewpoint. 0 disables it, and with it the critique.
+    max_viewpoint_iterations: int = 6  # max render/adjust turns the agent gets
+    viewpoint_model: str | None = None  # viewpoint agent model (None -> use ``model``)
+    viewpoint_effort: Effort | None = None  # viewpoint effort (None -> use ``effort``)
+
+    @property
+    def can_dispatch_subagents(self) -> bool:
+        """Whether this run may hand subtasks to subagents."""
+        return self.subagents_enabled and not self.is_subagent
+
+    def agent_model_and_effort(self, prefix: str) -> tuple[str | None, Effort]:
+        """The model and effort for a helper agent, falling back to the builder's.
+
+        ``prefix`` names the agent's option pair, e.g. ``"critique"`` reads
+        ``critique_model`` and ``critique_effort``.
+        """
+        model = getattr(self, f"{prefix}_model") or self.model
+        effort = getattr(self, f"{prefix}_effort") or self.effort or Effort.NONE
+        return model, effort

brickwright/driver/__init__.py

@@ -0,0 +1,7 @@
+"""The litellm-backed autonomous driver over the harness primitives."""
+
+from .loop import run_agent
+from .narration import Narrator
+from .report import RunReport
+
+__all__ = ["Narrator", "RunReport", "run_agent"]

brickwright/driver/completion.py

@@ -0,0 +1,89 @@
+"""The litellm completion seam, shared by the builder loop and the critic.
+
+Kept in its own module so the loop and the critique step can each bind (and tests
+can each patch) ``litellm_complete`` independently, without an import cycle.
+"""
+
+from collections.abc import Callable, Iterable
+from typing import Any
+
+
+def litellm_complete() -> Callable[..., Any]:
+    # Imported lazily so tests can monkeypatch sys.modules["litellm"] before this
+    # runs; a module-level import binds the real module too early for that to work.
+    import litellm
+
+    # Sanitize tool calls; see https://docs.litellm.ai/docs/completion/message_sanitization
+    litellm.modify_params = True
+
+    def complete(**kwargs: Any) -> Any:
+        routed = _route(kwargs)
+        response = litellm.completion(**routed)
+        if (routed.get("model") or "").startswith("openai/responses/"):
+            return _merge_choices(response)
+        return response
+
+    return complete
+
+
+def bad_request_error() -> type[Exception]:
+    import litellm
+
+    return litellm.BadRequestError
+
+
+def _route(kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Configure Claude prefix caching and OpenAI's Responses API bridge.
+
+    OpenAI rejects function tools alongside reasoning for gpt-6 on
+    ``/v1/chat/completions``, and litellm doesn't list ``reasoning_effort`` among
+    gpt-6's params, so it has to be allowed explicitly. The Responses API caches
+    prompts automatically, and litellm's injected cache breakpoints defeat that.
+    """
+    model = kwargs.get("model") or ""
+    if model.removeprefix("anthropic/").startswith("claude-"):
+        # Keep the static prefix reusable across builds, and cache the growing
+        # conversation through the latest tool result or rendered image.
+        return {
+            **kwargs,
+            "cache_control_injection_points": [
+                {"location": "message", "role": "system"},
+                {"location": "message", "index": -1},
+            ],
+        }
+    name = model.removeprefix("openai/")
+    if not name.startswith("gpt-6"):
+        return kwargs
+    routed = {**kwargs, "model": f"openai/responses/{name}"}
+    routed.pop("cache_control_injection_points", None)
+    if "reasoning_effort" in kwargs:
+        routed["allowed_openai_params"] = ["reasoning_effort"]
+    return routed
+
+
+def _merge_choices(response: Any) -> Any:
+    """Fold the Responses API bridge's choices back into the one callers read.
+
+    The bridge makes each output message (such as a preamble before tool calls) its
+    own choice and puts every tool call in a trailing one, so ``choices[0]`` alone
+    looks like a final text reply.
+    """
+    if len(response.choices) < 2:
+        return response
+    merged = response.choices[0]
+    messages = [c.message for c in response.choices]
+    # litellm's Message drops unset fields rather than holding None.
+    merged.message.content = _join(getattr(m, "content", None) for m in messages)
+    merged.message.reasoning_content = _join(
+        getattr(m, "reasoning_content", None) for m in messages
+    )
+    merged.message.tool_calls = [
+        tc for m in messages for tc in (getattr(m, "tool_calls", None) or [])
+    ] or None
+    merged.finish_reason = response.choices[-1].finish_reason
+    response.choices = [merged]
+    return response
+
+
+def _join(texts: Iterable[str | None]) -> str | None:
+    return "\n\n".join(t for t in texts if t) or None