Eyes agent: visualization render harness, gallery + manifest (Phase 1 of 3)

[Jammy2211]

Overview

The organism produces rich visualizations (imaging / interferometer / point_source / multi / cluster) but has no formal loop for a human to look at them, judge them, and drive updates. This epic adds the missing loop as the Eyes agent: a domain-agnostic PyAutoBrain conductor for render → present → critique → delegate, fed by a per-project viz manifest contract. This issue tracks the epic; Phase 1 (this task) builds the render harness + gallery + manifest in autolens_workspace_test, riding the existing visualization scripts.

Plan

• Phase 1 (this task) — render harness + gallery: a gallery builder over the existing workspace_test visualization scripts' PNG outputs, plus a generated machine-readable viz manifest ("every figure the project can output"). autolens_workspace_test only.
• Phase 2 — Eyes conductor in PyAutoBrain: judge-and-iterate loop consuming the manifest/gallery; reasons and delegates plot edits via start_dev (like the hygiene conductor, it never edits plot source itself). Blocked until workspace-agent ships (PyAutoBrain worktree claim).
• Phase 3 — paper-informed critique ("restyle to match this paper"), leaning on the manifest + PyAutoMemory. Must not gate phases 1–2.

Design context: the plot API is now functional (aplt.subplot_* + config/visualize yaml — the old MatPlot2D/Output plotter classes are gone), so the surface the Eyes agent ultimately steers is the functional plot API + visualize configs. The five per-domain visualization*.py scripts already run the real Visualizer and write the complete expected PNG+FITS set, with expected outputs derived from the visualizer source — Phase 1 is thin glue, not new machinery.

Detailed implementation plan

Affected Repositories

• autolens_workspace_test (primary, Phase 1)
• PyAutoBrain (Phase 2, blocked — claimed by workspace-agent)

Branch Survey

Repository	Current Branch	Dirty?
./autolens_workspace_test	main	clean
./PyAutoBrain	main	1 file (_intake.py, unrelated in-progress fix)

Suggested branch: feature/viz-render-gallery
Worktree root: ~/Code/PyAutoLabs-wt/viz-render-gallery/ (created by /start_workspace)
Work classification: Workspace

Implementation Steps (Phase 1)

1. scripts/gallery/gallery_build.py — walk scripts/<domain>/images/** PNGs (domains: imaging, interferometer, point_source, multi, cluster), emit a static gallery.html contact sheet grouped domain → script → source-type with relative image links, plus viz_manifest.yaml: domain → script → figure name / path / producing Visualizer method, derived from the scripts' own expected-output lists.
2. scripts/gallery/gallery_run.sh — run the five visualization*.py scripts under the TEST_MODE env, then build the gallery. Time each script first; only fast ones go in the default run list (cluster-tier scripts may need a --slow flag).
3. Viewing loop needs no new code: Claude reads PNGs natively in-session for critique; towin() copies gallery.html + images for human viewing on Windows.
4. Hygiene: confirm .gitignore covers the gallery output and images/ dirs (known ship_workspace binary-leak trap).

Testing

• Run the imaging visualization script + gallery build end-to-end; verify every HTML img reference resolves and the manifest lists every PNG on disk (and vice versa).

Key Files

• autolens_workspace_test/scripts/imaging/visualization.py — reference harness script (pattern for all domains)
• autolens_workspace_test/scripts/<domain>/images/ — PNG/FITS output trees the gallery walks
• autolens/imaging/model/visualizer.py, autolens/analysis/plotter.py — where expected outputs are derived from (read-only in Phase 1)

Original Prompt

Click to expand starting prompt

I am now at the point where PyAutoLens and other projects produce lots of
visualizations, but I dont have an easy way to look at them, judge them and
then get them updated based on my requirements. We have places which outputs
them for tests (e.g. autolens_workspace_test/scripts/imaging/visualizaiotn.py),
but I think we need a more formal mechanism for me to look at images, judge
them and then update them.

In particular, I wonder if PyAutoBrain would benefit from a visualization
agent for this task, which handles both a streamlined way to make .png files
from PyAutoLens (and other projects), shows me them and then has the context
to change them based on my input as well as make suggestions for how they
could be improved. I can imagine me giving it papers and asking it to make
updates based on how those papers work.

What do you think? Full on brain conductor or something simpler? Obviously
the agent should not be project specific (PyAutoScientist is code-base and
domain agnostic), but it needs to interface with PyAutoLens to understand
"These are all the images it could output, there are lots (imaging /
interferometer / point source", it probably needs to output them via a
Visualizer so its representation of modeling runs. So maybe we need a domain
agnostic visualization (eyes) conductor but also something which more
direclty links to how it runs on a given project.

Filed via /intake on 2026-07-16 as draft/feature/pyautobrain/visualization_eyes_agent.md.

[Jammy2211]

Phase 1 shipped to PR — 2026-07-16

PR: PyAutoLabs/autolens_workspace_test#170 (pending-release, awaiting merge)

Render harness + gallery + manifest complete in autolens_workspace_test/scripts/gallery/:

• gallery_build.py — contact-sheet gallery.html + machine-readable viz_manifest.yaml (41 png + 8 fits across imaging/interferometer/point_source/multi/cluster); --check verifies gallery ↔ manifest ↔ disk; --embed writes a single self-contained HTML.
• gallery_run.sh — per-domain runner (fast tier by default; cluster ~13 min moved to a slow tier; --all adds slow + JAX variants).

All six visualization scripts validated green this session. The in-session critique loop is proven: figures were reviewed directly by the agent (PNG reads) and the embedded gallery was delivered for human review. Heart RED at ship time was human-acknowledged as 6 organism-level reasons unrelated to this change.

Next: Phase 2 (Eyes conductor in PyAutoBrain) — unblocks when the workspace-agent PyAutoBrain claim clears (PR #118).

[Jammy2211]

Phase 1 MERGED: autolens_workspace_test#170 (b82b356). Mind record: complete/2026/07/viz-render-gallery.md; worktree cleaned. Epic stays open — next is Phase 2 (Eyes conductor), which consumes output/gallery/viz_manifest.yaml + the gallery.

[Jammy2211]

Phase 2 shipped to PR — 2026-07-16

PR: #127 (awaiting merge)

The Eyes conductor is built: bin/pyauto-brain eyes survey|review <workspace-root> — decision-only, stdlib-only, firewall-clean (workspace root is always an argument; zero instance tokens in code). The /eyes skill drives the full loop: survey → render (workspace gallery_run.sh) → review (in-session PNG reads + human critique against the note schema) → delegate accepted changes via intake → start_dev.

Validated: full Brain suite 98 passed; live survey against autolens_workspace_test immediately surfaced real findings — the never-rendered modeling_visualization_jit* tier and two visualization_upper scripts missing from the Phase-1 runner default list (gallery_run.sh follow-up candidates).

Heart RED at ship time human-acknowledged (same 6 unrelated organism-level reasons as Phase 1). Shipped as a parallel PR alongside community-ears-v2-prs' PyAutoBrain claim (user-approved; additive-only shared-file edits).

Next: Phase 3 — paper-informed critique (memory-faculty consultation).

[Jammy2211]

Phase 2 MERGED: PyAutoBrain#127 (231a3de). Mind record: complete/2026/07/eyes-conductor.md; worktree + branch cleaned. Follow-ups filed: draft/feature/pyautobrain/eyes_paper_informed_critique.md (Phase 3 — the last phase of this epic) and draft/feature/workspaces/gallery_runner_missing_tiers.md (visualization_upper + jit-tier gaps the live survey found). Epic closes when Phase 3 ships.

[Jammy2211]

Phase 3 shipped to PR — 2026-07-16

PR: #129 (awaiting merge — closes the epic when merged)

Paper-informed critique: eyes review --against <reference-dir> carries a paper's extracted panels on the review surface; the /eyes skill's new pass reads the references first, writes an explicit convention-list rubric for the human, then critiques workspace figures against it — notes carry reference, delegation unchanged. Core stays decision-only/firewall-clean; zero shared files touched this PR. Tests: 7/7 ×3 (a real fixture mtime race found and fixed), full suite 104. Heart RED human-acked (third identical ack today).

[Jammy2211]

Epic complete — 2026-07-16

All three phases MERGED in one day:

• Phase 1 — render harness, gallery + viz_manifest.yaml (autolens_workspace_test#170)
• Phase 2 — the Eyes conductor + /eyes skill (PyAutoBrain#127)
• Phase 3 — paper-informed critique, review --against (PyAutoBrain#129)

The organism can now render its visualization surface on demand, survey it for staleness and gaps, present it for human judgment, and turn critiques — including paper-informed restyles — into routed dev work. Maiden production run of the full gallery follows tonight; first human review session tomorrow. Mind records: complete/2026/07/{viz-render-gallery,eyes-conductor,eyes-paper-critique}.md. Remaining satellite: draft/feature/workspaces/gallery_runner_missing_tiers.md.