feat(bokeh): implement maze-circular

[github-actions]

Implementation: maze-circular - python/bokeh

Implements the python/bokeh version of maze-circular.

File: plots/maze-circular/implementations/python/bokeh.py

Parent Issue: #3804

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Warm off-white background (#FAF8F1). Title "maze-circular · python · bokeh · anyplot.ai" centered at top in dark text — clearly readable. Axes, grid, and toolbar are hidden (appropriate for a maze puzzle). The circular maze fills roughly 70% of the 2400×2400 canvas: 7 concentric rings with dark ink (#1A1A17) walls, sector counts increasing outward from 8 (innermost) to 32 (outermost). Entry gap is visible on the rightmost outer boundary with a green (#009E73) triangle marker and bold "START" label outside the maze. Central goal: orange (#E69F00) filled circle at the hub with a "★" star. Noticeable empty space at the bottom of the canvas. All text is readable against the light background.

Dark render (plot-dark.png): Near-black (#1A1A17) background — correct warm near-black, not pure black. A thin rectangular border artifact is visible around the entire canvas perimeter — likely the browser window background bleeding through during the Selenium screenshot (HTML page background not explicitly forced to #1A1A17). Walls render in light cream (#F0EFE8) against the dark surface, clearly visible. Title appears in light text — readable. Data colors are identical to the light render: orange goal (#E69F00) and green entry (#009E73) unchanged. The "★" star appears white on the dark orange circle — still visible. "START" label in green — readable. No dark-on-dark failures for any text element.

Both paragraphs are required. A review that only describes one render is invalid.

Score: 86/100

Category	Score	Max
Visual Quality	27	30
Design Excellence	13	20
Spec Compliance	15	15
Data Quality	14	15
Code Quality	10	10
Library Mastery	7	10
Total	86	100

Visual Quality (27/30)

• VQ-01: Text Legibility (7/8) — Title explicitly 50pt, START 22pt, star 28pt; all readable in both renders. START label slightly small for 2400px canvas but acceptable.
• VQ-02: No Overlap (6/6) — No overlapping elements in either render.
• VQ-03: Element Visibility (5/6) — Walls, goal, and entry markers all visible. Wall width=5 adequate throughout.
• VQ-04: Color Accessibility (2/2) — Okabe-Ito colors CVD-safe; green vs orange distinguishable across vision types.
• VQ-05: Layout & Canvas (3/4) — Maze appropriately centered; noticeable empty space at canvas bottom — tightening x/y range from ±1.25 to ±1.15 would help.
• VQ-06: Axis Labels & Title (2/2) — Correct title format; axes hidden (appropriate for maze).
• VQ-07: Palette Compliance (2/2) — Entry = #009E73 (Okabe-Ito Add workflow diagram for new prototype discovery #1), Goal = #E69F00 (Okabe-Ito #5). Backgrounds #FAF8F1/#1A1A17 correct. Data colors identical between themes.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Clean puzzle aesthetic above generic defaults. Intentional color use for entry/goal focal points. Not publication-ready: plain typography, no concentric ring differentiation.
• DE-02: Visual Refinement (4/6) — Grid, axes, toolbar hidden — clean. Dark render has thin rectangular canvas border artifact from Selenium screenshot. No additional ring accent or graduated wall styling.
• DE-03: Data Storytelling (4/6) — Clear visual hierarchy: START (green outer) → rings → GOAL (orange center). Puzzle narrative immediately legible. Could add difficulty annotation or subtle visual path hints.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct circular maze with concentric rings and radial passages.
• SC-02: Required Features (4/4) — All features present: concentric walls, radial walls, radial passages, outer entry point, center goal, single-solution guarantee, consistent wall thickness.
• SC-03: Data Mapping (3/3) — 7 rings (medium difficulty), sector counts 8/12/16/20/24/28/32. Coordinate system correctly maps maze geometry.
• SC-04: Title & Legend (3/3) — Title format correct; no legend needed for a maze.

Data Quality (14/15)

• DQ-01: Feature Coverage (5/6) — All maze features shown. Only medium difficulty rendered; a brief difficulty annotation would complete feature demonstration.
• DQ-02: Realistic Context (5/5) — Circular maze puzzle: neutral, real, well-understood context.
• DQ-03: Appropriate Scale (4/4) — 7 rings, 8–32 sectors, radii 0.12–0.95 — appropriate for medium difficulty.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Flat structure: imports → theme → params → generation → draw → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set before maze generation.
• CQ-03: Clean Imports (2/2) — All 9 imports used.
• CQ-04: Code Elegance (2/2) — Iterative backtracking is appropriate complexity. Selenium pattern follows library guide.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.html + plot-{THEME}.png. Current Bokeh API.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — figure(), p.line(), p.scatter(), p.patch(), p.add_layout(Label()), match_aspect=True. Follows library guide Selenium pattern.
• LM-02: Distinctive Features (3/5) — HTML export, Label model, angle-rotated scatter marker, match_aspect. Does not use Bokeh's AnnularWedge glyph or other ring-native geometries that would be more idiomatic for concentric ring structures.

Score Caps Applied

• None

Strengths

• Correct circular maze: concentric rings + radial passages, single-solution guarantee via recursive backtracking
• Full spec compliance: entry marker, goal circle, hub, consistent wall thickness, varied sector counts
• Both renders theme-adapt correctly — Okabe-Ito colors identical, backgrounds #FAF8F1/#1A1A17 correct
• Clean KISS code structure with seed, all imports used, correct HTML+PNG output artifacts

Weaknesses

• Dark render has thin rectangular canvas border artifact — HTML page background not explicitly set to #1A1A17, browser edge bleeds through in Selenium screenshot
• Canvas bottom has noticeable empty space — tighten x/y range from ±1.25 to ±1.15 to let maze fill more of the canvas
• No ring differentiation or typographic hierarchy — consider slightly thicker outer boundary, subtle outer-ring label, or bold title weight
• Does not use Bokeh's AnnularWedge glyph for ring sectors — manually drawing arcs via p.line() misses the more idiomatic approach for ring geometry

Issues Found

1. Dark-mode border artifact: Selenium screenshot captures browser-window border against the dark canvas — inject a CSS body { background: #1A1A17; } style before screenshotting, or set driver.execute_script("document.body.style.backgroundColor='#1A1A17'")
2. Canvas utilization (VQ-05): x_range/y_range = ±1.25 leaves ~24% padding per side. Shrink to ±1.15 or increase outer_radius to fill the canvas better.
3. DE-02 refinement: Use AnnularWedge glyphs for ring corridor fills to add subtle concentric shading, or increase the outer boundary wall width to wall_width+4 (currently +2) for stronger visual framing.
4. LM-02: Replace arc-drawing p.line() loops with Bokeh's AnnularWedge glyph for corridor backgrounds — this is a Bokeh-distinctive approach for ring geometry.

AI Feedback for Next Attempt

Fix the dark-mode border artifact (inject body { background: #1A1A17 } before Selenium screenshot). Tighten x_range/y_range from ±1.25 to ±1.15 to reduce bottom empty space. Add a bold title weight (p.title.text_font_style = "bold"). Consider replacing or supplementing the arc-drawing approach with Bokeh's AnnularWedge glyph for more idiomatic ring geometry — even using it for the goal hub or entry ring highlight would demonstrate LM-02. Keep all current Okabe-Ito color choices and spec features.

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 1/4

Applied fixes based on AI review feedback.

Status: Repair completed, re-triggering review...

---

🤖 impl-repair

[claude]

AI Review - Attempt 2/3

Image Description

Light render (plot-light.png): Warm off-white background consistent with #FAF8F1 (not pure white). Title "maze-circular · python · bokeh · anyplot.ai" rendered in dark ink at top — clearly readable. No axes or grid (correct for a maze). A circular maze of 7 concentric rings with radial sector divisions is drawn in dark #1A1A17 walls against the warm background. The center goal circle is filled in Okabe-Ito orange (#E69F00) with a white star (★). The entry gap on the outer ring at ~3 o'clock has a green #009E73 triangle marker and a bold "START" label. A small italic "7 rings · medium" annotation sits at the bottom. All text is readable against the light background.

Dark render (plot-dark.png): Warm near-black background consistent with #1A1A17 (not pure black). Title in light cream (#F0EFE8) — clearly readable with no dark-on-dark issues anywhere. Maze walls are now rendered in light/cream against the dark background providing high contrast. The goal orange #E69F00 and entry green #009E73 are identical to the light render — only the chrome (background, walls, title) has flipped. All text is readable against the dark background; no dark-on-dark failures detected.

Both paragraphs are required. A review that only describes one render is invalid.

Score: 89/100

Category	Score	Max
Visual Quality	29	30
Design Excellence	13	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	7	10
Total	89	100

Visual Quality (29/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (50pt title, 28pt labels, 24pt annotation). Readable in both themes. The difficulty annotation at 24pt near the bottom border is slightly small for mobile scale.
• VQ-02: No Overlap (6/6) — No text or element overlaps; entry label, goal star, title, and annotation clearly separated.
• VQ-03: Element Visibility (6/6) — Wall width=5 appropriate for 2400px canvas; goal circle and entry triangle are prominent.
• VQ-04: Color Accessibility (2/2) — Green/orange from Okabe-Ito are CVD-safe with high contrast on both themes.
• VQ-05: Layout & Canvas (4/4) — Circular maze fills ~49% of square canvas (expected for a circle in a square frame); margins used well for title and annotation.
• VQ-06: Axis Labels & Title (2/2) — No axis labels (correct for maze). Title follows exact required format. Difficulty annotation adds meaningful context.
• VQ-07: Palette Compliance (2/2) — Entry #009E73 (Okabe-Ito pos 1), goal #E69F00 (Okabe-Ito pos 5). Backgrounds #FAF8F1 light / #1A1A17 dark. Data colors identical between themes; chrome flips correctly.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Intentional two-color wayfinding system (green entry → orange goal) is CVD-safe and purposeful. Clean, consistent maze aesthetic. Clearly above defaults but not at publication-level polish.
• DE-02: Visual Refinement (4/6) — Axes, grid, and outline hidden correctly; min_border tuned; italic difficulty annotation; Selenium page-background JS fix avoids border artifacts. Entry marker as floating triangle is functional but slightly inelegant.
• DE-03: Data Storytelling (4/6) — Green-to-orange visual narrative guides start → goal clearly. Color contrast creates focal points. No additional storytelling layering (e.g., difficulty zone shading).

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct circular maze with concentric rings and radial passages; recursive backtracking guarantees exactly one solution.
• SC-02: Required Features (4/4) — All spec features present: concentric rings, radial walls, radial passages, outer entry gap, center goal, consistent wall thickness, single-solution algorithm.
• SC-03: Data Mapping (3/3) — 7 rings (medium), sectors increase ring-by-ring (8→32), ring radii linearly spaced 0.12→0.95, correct maze topology.
• SC-04: Title & Legend (3/3) — Title exactly maze-circular · python · bokeh · anyplot.ai. No legend (single-use puzzle — correctly omitted).

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all aspects: variable sector density per ring, outer boundary with entry gap, central hub, both arc and radial wall types, entry and goal markers.
• DQ-02: Realistic Context (5/5) — Clean puzzle/educational context. Neutral printable maze puzzle application with no controversial content.
• DQ-03: Appropriate Scale (4/4) — 7 rings for medium difficulty is appropriate; sector counts (8→32) geometrically sensible; recursive backtracking ensures valid maze topology.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → theme tokens → maze generation → figure → drawing → labels → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — np.random.seed(42) set at top.
• CQ-03: Clean Imports (2/2) — All imports used: os, time, pathlib.Path, numpy, bokeh.io, bokeh.models, bokeh.plotting, selenium.
• CQ-04: Code Elegance (2/2) — Clean Pythonic code; maze algorithm well-structured with inline neighbor computation. No over-engineering.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.png and plot-{THEME}.html. Current Bokeh 3.9 API used correctly.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Correct use of figure(), ColumnDataSource, p.line(), p.scatter(), p.patches(), Label, HoverTool, output_file(), save(), Selenium screenshot — matches canonical bokeh.md patterns.
• LM-02: Distinctive Features (3/5) — HoverTool on goal and entry for interactive HTML tooltips; output_file() for HTML catalog artifact; match_aspect=True for undistorted circular rendering; JS execute_script() to fix Selenium screenshot background. Distinctly Bokeh features.

Score Caps Applied

• None — no caps triggered.

Strengths

• Correct circular maze with concentric rings and radial passages using recursive backtracking for guaranteed single solution
• Proper theme-adaptive chrome: wall color, title, and annotations flip correctly between light (#FAF8F1) and dark (#1A1A17) backgrounds
• Correct Okabe-Ito palette: brand green #009E73 for entry, orange #E69F00 for goal — data colors identical between themes
• match_aspect=True ensures undistorted circular rendering in Bokeh
• Idiomatic Bokeh usage: ColumnDataSource + HoverTool on goal and entry markers, HTML catalog artifact correctly generated
• KISS code structure — linear flow, no functions/classes, np.random.seed(42) ensures reproducibility
• Selenium page-background JS fix prevents thin lighter-border artifact in dark theme screenshots

Weaknesses

• DE-01 (5/8): Design is intentional and clean but not at publication-level polish — a more sophisticated typographic treatment or subtle background differentiation for the entry/goal area could elevate it
• DE-02 (4/6): Entry triangle marker placed outside the outer boundary is functional but slightly inelegant — a small inward-pointing notch or arrow at the boundary gap would be more refined
• DE-03 (4/6): Green-to-orange color contrast guides the eye but the puzzle lacks additional hierarchy — e.g., subtle gradient ring shading for outer→inner difficulty zones
• VQ-01 (7/8): Difficulty annotation at y=-1.12 (24pt) sits close to the bottom border; at mobile scale it may barely register — increase to 28pt and move slightly to y=-1.08

Issues Found

1. DE-02 MINOR: Entry marker (triangle) placed at outer_r * 1.04 outside the maze boundary looks slightly disconnected
   • Fix: Position marker at the boundary gap opening itself, or draw a small colored arc segment at the entry gap instead
2. VQ-01 MINOR: Difficulty annotation at 24pt and y=-1.12 is borderline for mobile readability
   • Fix: Increase annotation font size to 28pt and move to y=-1.08 for more breathing room from bottom border

AI Feedback for Next Attempt

The maze is algorithmically correct and visually clean. To raise score further: (1) increase difficulty annotation to 28pt at y=-1.08; (2) consider refining the entry marker — instead of a floating triangle outside the boundary, use a colored arc segment filling the entry gap, which integrates more naturally with the circular geometry; (3) optionally add subtle radial gradient shading (lighter outer rings → darker inner rings) to reinforce the "navigate inward" difficulty direction, which would improve DE-03 storytelling.

Verdict: APPROVED