feat(bokeh): implement gauge-basic

[github-actions]

Implementation: gauge-basic - python/bokeh

Implements the python/bokeh version of gauge-basic.

File: plots/gauge-basic/implementations/python/bokeh.py

Parent Issue: #857

---

🤖 impl-generate workflow

[claude]

AI Review - Attempt 1/3

Image Description

Light render (plot-light.png): Semi-circular gauge on warm off-white #FAF8F1 background. Three annular-wedge zones in Imprint semantic colors: matte red #AE3030 (0–30 "bad"), amber #DDCC77 (30–70 "caution"), brand green #009E73 (70–100 "good"). Dark triangle needle (INK token) points to 72, just past the 70 threshold inside the green zone. Center hub circle in dark ink with PAGE_BG outline. Tick marks and labels (0, 25, 50, 75, 100) positioned radially around the semicircle in INK_SOFT. Bold "72" in 80pt INK ink is prominently centered below the arc; "CPU Utilization (%)" in 26pt INK_SOFT sits below that. Title "gauge-basic · python · bokeh · anyplot.ai" in dark ink at ~55% canvas width. All text is clearly readable against the light background — no light-on-light issues.

Dark render (plot-dark.png): Same composition on near-black #1A1A17 background. Zone colors are IDENTICAL to the light render (#AE3030 / #DDCC77 / #009E73) — only chrome flips. Needle correctly adapts to light cream (#F0EFE8), hub circle in light cream with dark outline — fully visible on the dark surface. Title, "72", tick labels, and "CPU Utilization (%)" all render in appropriate light INK/INK_SOFT tokens against the dark background. One cosmetic blemish: a faint thin rectangular outline is visible at the canvas border, likely from the HTML page background in the headless-Chrome screenshot — does not impair readability. All text is readable against the dark background — no dark-on-dark failures.

Both renders pass the theme-readability check.

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; 28pt ticks (slightly below 34pt guideline but appropriate for radial layout), 80pt bold value, 26pt metric label; minor hierarchy gap between 26pt metric label and 80pt value display
• VQ-02: No Overlap (6/6) — All tick labels, value, and metric label cleanly positioned with no collisions
• VQ-03: Element Visibility (6/6) — Zones, needle, hub, value all clearly visible in both themes; needle correctly adapts (dark/light) per theme
• VQ-04: Color Accessibility (2/2) — Three distinct luminance levels across zones; needle position provides redundant encoding beyond color
• VQ-05: Layout & Canvas (4/4) — 3200×1800 correct; gauge fills ~60–65% of canvas; well-balanced margins; value + metric label well-positioned below arc
• VQ-06: Axis Labels & Title (2/2) — Title format correct; "CPU Utilization (%)" includes units; 0–100 tick range shown
• VQ-07: Palette Compliance (2/2) — Imprint semantic exceptions correct: #AE3030 bad, #DDCC77 amber caution, #009E73 brand green good; backgrounds #FAF8F1/#1A1A17; all chrome theme-adaptive

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Clearly above a generic default: semantic Imprint color hierarchy, clean triangle needle with hub, prominent 80pt value — shows intentional design; not yet publication-ready (zone labels would elevate this)
• DE-02: Visual Refinement (4/6) — Axes fully hidden, no grid, subtle tick marks; dark render has faint canvas border blemish from browser rendering; overall clean
• DE-03: Data Storytelling (4/6) — Clear focal point (needle at 72 just past 70 threshold into green) reinforced by bold value; color zones guide interpretation immediately; CPU monitoring story is clear

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct semi-circular gauge with annular wedge zones and triangle needle
• SC-02: Required Features (4/4) — value=72, min=0, max=100, thresholds [30,70], three color zones, needle, prominent value label, metric label all present
• SC-03: Data Mapping (3/3) — Needle correctly positioned at 72; zone boundaries accurately computed from thresholds
• SC-04: Title & Legend (3/3) — "gauge-basic · python · bokeh · anyplot.ai" correct; no legend needed for semantic zone gauge

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — All gauge aspects shown: single value, range, threshold zones, needle, value label, metric context
• DQ-02: Realistic Context (5/5) — CPU utilization is real, common, neutral monitoring scenario
• DQ-03: Appropriate Scale (4/4) — 0–100% range standard; 72% is realistic; 30/70 thresholds reasonable for system monitoring

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Imports → Data → Plot → Save; no functions or classes
• CQ-02: Reproducibility (2/2) — Fully deterministic; no random data
• CQ-03: Clean Imports (2/2) — All imports used; no unused dependencies
• CQ-04: Code Elegance (2/2) — Clean, well-organized; sys.path manipulation necessary given filename; trigonometry is appropriate for gauge geometry
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.html and plot-{THEME}.png; current Bokeh API

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — annular_wedge for zones, Label layout model, output_file+save, Selenium CDP for exact viewport — correct Bokeh patterns throughout
• LM-02: Distinctive Features (3/5) — annular_wedge is Bokeh-specific and ideal for gauge zones; CDP viewport control is sophisticated; HTML interactive artifact alongside PNG is distinctive; missed opportunity: no hover tooltips on zones/needle despite HTML supporting it

Score Caps Applied

• None — DE-01=5 exceeds the ≤2 cap threshold; all other caps inapplicable

Strengths

• Correct semi-circular gauge with semantic Imprint zone colors (red/amber/green) exactly matching spec conventions
• Needle accurately points to value=72 just past the 70 threshold into the green zone
• Prominent bold 80pt value display below arc creates an immediate focal point
• Full theme-adaptive chrome: needle, hub, tick labels, value, and metric label all correctly use INK/INK_SOFT tokens in both renders
• Perfect spec compliance: zones at 30/70, needle, value label, metric label all present and accurate
• annular_wedge is the ideal Bokeh primitive for gauge zones — well-chosen
• HTML artifact correctly saved alongside PNG; Selenium CDP viewport matches canvas dimensions exactly

Weaknesses

• Tick labels at 28pt are slightly below the 34pt bokeh guideline; the jump from 26pt metric label to 80pt value creates a hierarchy imbalance — bump metric label to ~30–32pt and tick labels to ~30pt to smooth the scale
• Dark render shows a faint thin rectangular outline at the canvas border from browser rendering; ensure the HTML page background matches PAGE_BG (e.g., add <body style="margin:0;background:#1A1A17"> via Bokeh's curdoc() theme or match border_fill_color / background_fill_color through all Bokeh layout layers)
• Zone labels ("Low" / "Caution" / "Optimal" or similar) inside or near each arc segment would make the color semantics self-evident — currently relying on color memory alone; simple Label additions would elevate DE-01 meaningfully
• No hover tooltips on zones or needle hub despite the HTML artifact fully supporting HoverTool — this is the key Bokeh-distinctive opportunity missed

Issues Found

1. DE-01 MODERATE: Design is above generic default but zone labels and minor refinements would push into publication-ready territory
   • Fix: Add short arc labels ("Low" / "Caution" / "Optimal") inside each zone segment using Label or Text glyphs; use theme-adaptive text color for contrast
2. DE-02 MINOR: Dark render has faint canvas border outline
   • Fix: Ensure full background coverage — check that border_fill_color, background_fill_color, and the HTML page body background all use PAGE_BG; the Selenium --window-size approach sometimes leaves a thin browser chrome artifact
3. VQ-01 MINOR: Metric label at 26pt is slightly small vs 80pt value; tick labels at 28pt below guideline
   • Fix: Raise metric label to ~30pt and tick labels to ~30–32pt for better proportional balance
4. LM-02: HTML interactivity capability underused
   • Fix: Add HoverTool to show zone info on hover — a natural Bokeh advantage over static libraries

AI Feedback for Next Attempt

Score is 89/100 — very close to threshold. Repair focus: (1) Add zone labels inside arc segments using Label glyphs to make zone semantics self-evident — most impactful DE-01 lift; (2) Fix dark-render canvas border by ensuring PAGE_BG covers all Bokeh layout layers; (3) Bump tick labels from 28pt to ~30pt and metric label from 26pt to ~30pt to balance the text hierarchy; (4) Optionally add a HoverTool for zone/value info to leverage Bokeh's interactive HTML output.

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): Semi-circular gauge on a warm off-white (#FAF8F1) background. Three color zones fill the arc from left to right: matte red (0–30, labelled "Low"), amber/yellow (30–70, labelled "Caution"), and brand green (70–100, labelled "Optimal"). Zone labels are rotated to follow the arc tangent and rendered in contrasting fixed colors (white on red/green, near-black on amber). Tick marks (0, 25, 50, 75, 100) extend outside the arc with values in INK_SOFT. A triangular black needle points to 72, with a black circular hub at center. Below the arc the value "72" is displayed in bold black at 80pt and a subtitle "CPU Utilization (%)" in INK_SOFT at 30pt. Title "gauge-basic · python · bokeh · anyplot.ai" in dark ink is prominently centered at top. All text is clearly readable against the light background. Legibility verdict: PASS.

Dark render (plot-dark.png): Identical gauge layout on a warm near-black (#1A1A17) background. Zone arc colors are identical to the light render (matte red, amber, brand green #009E73) — data colors unchanged as required. Chrome flips correctly: title and value label are rendered in light ink (#F0EFE8), tick labels in INK_SOFT (#B8B7B0), needle and hub in near-white. The zone labels retain their fixed contrasting colors (white on red/green, dark on amber). The bold "72" value is clearly visible in light text. No dark-on-dark failures observed. Legibility verdict: PASS.

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; title, value, tick, and metric labels all well-proportioned and readable in both themes. Minor deduction for zone arc labels (22pt, rotated ~90°) which are slightly small and require tilting to read comfortably.
• VQ-02: No Overlap (6/6) — No text or element collisions; all labels clearly separated.
• VQ-03: Element Visibility (6/6) — Gauge arcs, needle, hub, value display all optimally sized and immediately visible.
• VQ-04: Color Accessibility (2/2) — Semantic traffic-light zones have redundant text labels inside arcs; amber zone correctly uses dark text for contrast; overall CVD-safe with shape + color + label redundancy.
• VQ-05: Layout & Canvas (4/4) — Gauge is well-centered in the 3200×1800 canvas with balanced margins; value and metric label anchor the lower space; no wasted corners.
• VQ-06: Axis Labels & Title (2/2) — "CPU Utilization (%)" provides context with units; title format correct.
• VQ-07: Palette Compliance (2/2) — Zones use #009E73 (brand green), #DDCC77 (semantic amber anchor), and #AE3030 (semantic red anchor) — all Imprint palette members correctly applied for traffic-light semantics. Background #FAF8F1 light / #1A1A17 dark. Chrome flips correctly in both renders.

Design Excellence (13/20)

• DE-01: Aesthetic Sophistication (5/8) — Above a generic default: semantic color assignment to zones (not just ordinal palette), arc-tangent text rotation for zone labels, hub circle with ring detail, clean separation with background-color zone dividers. Not quite FiveThirtyEight-level but clearly intentional design.
• DE-02: Visual Refinement (4/6) — Axes and grid fully hidden, custom external tick marks, hub detail, generous whitespace — good refinement beyond library defaults.
• DE-03: Data Storytelling (4/6) — The needle at 72 in the green zone communicates the message immediately. The bold value and semantic zone colors create clear visual hierarchy. The focal point (needle + value) is immediately apparent.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct semi-circular gauge/speedometer chart.
• SC-02: Required Features (4/4) — All spec features present: value display (72), min/max (0, 100), thresholds at [30, 70], color zones (red/amber/green), needle indicator, value label.
• SC-03: Data Mapping (3/3) — Needle correctly positioned at 72 in the green zone; zones correctly divide at thresholds 30 and 70.
• SC-04: Title & Legend (3/3) — Title "gauge-basic · python · bokeh · anyplot.ai" correct; zone labels embedded in arcs serve as the legend, appropriate for this chart type.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows all gauge aspects: three zones, needle, tick marks, tick labels, zone labels, value display, metric label.
• DQ-02: Realistic Context (5/5) — CPU utilization at 72% is a realistic, neutral technology monitoring scenario with appropriate thresholds.
• DQ-03: Appropriate Scale (4/4) — 0–100% range correct for utilization; 72% is a realistic value; thresholds at 30 and 70 align with standard system monitoring conventions.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean Imports → Data → Plot → Save flow with no unnecessary functions or classes.
• CQ-02: Reproducibility (2/2) — All data is hardcoded and deterministic.
• CQ-03: Clean Imports (2/2) — All imported modules (numpy, bokeh.io, bokeh.models, bokeh.plotting, selenium, pathlib, os, sys, time) are actively used.
• CQ-04: Code Elegance (2/2) — Clean, Pythonic; angle calculations via numpy are elegant; sys.path fix for self-shadowing is documented and necessary.
• CQ-05: Output & API (1/1) — Saves plot-{THEME}.html and plot-{THEME}.png; uses current Bokeh 3.x API.

Library Mastery (7/10)

• LM-01: Idiomatic Usage (4/5) — Strong Bokeh idioms: ColumnDataSource for zone data enabling HoverTool integration, annular_wedge for arc segments, Label for annotations, output_file+save for HTML artifact. Very idiomatic.
• LM-02: Distinctive Features (3/5) — HoverTool with zone name and range (Bokeh-distinctive interactive feature in HTML output), CDP-based viewport override for accurate screenshots, CSS body background injection.

Score Caps Applied

• None applicable.

Strengths

• Correct semantic color assignment: brand green, amber anchor, and matte red properly applied to good/caution/bad gauge zones
• Proper theme-adaptive chrome in both renders; all INK/INK_SOFT tokens correctly threaded through needle, hub, tick labels, and text elements
• HoverTool with zone information leverages Bokeh's interactive HTML output distinctively
• Arc-tangent text rotation for zone labels is a professional touch
• Clean, deterministic code with no unnecessary abstraction

Weaknesses

• Zone arc labels ("Low", "Optimal") at 22pt with ~90° rotation are slightly small and hard to read at a glance; consider increasing to 26–28pt or adding a separate legend
• The 50-tick mark and label are positioned at the very top center of the arc and the tick mark partially overlaps with the label above it — minor visual conflict

Issues Found

1. VQ-01 MINOR: Zone labels at 22pt with arc-tangent rotation are slightly undersized for comfortable reading at full canvas resolution — they require tilting the head to parse.
   • Fix: Increase zone label font size to 26–28pt, or supplement with a small external legend.

AI Feedback for Next Attempt

The implementation is strong and the design is intentional. If a repair is triggered: increase zone arc label font sizes from 22pt to 26–28pt so they are easier to read without rotation. Consider whether the 50-tick mark label needs additional spacing from the tick line at the top of the arc. These are minor polish issues — the overall design is solid.

Verdict: APPROVED