update(arc-basic): bokeh — comprehensive quality review

[MarkusNeusinger]

Summary

Updated bokeh implementation for arc-basic.

Changes: Comprehensive quality review and update

Changes

• Updated implementation with improved code quality and visual design

Test Plan

• Preview images uploaded to GCS staging
• Implementation file passes ruff format/check
• Metadata YAML updated with current versions
• Automated review triggered

---

Generated with Claude Code /update command

[Copilot]

Pull request overview

This PR updates the bokeh implementation for the arc-basic specification, representing a comprehensive refactoring that improves both code quality and visual design. The update transitions from manually computed quadratic bezier curves to Bokeh's native cubic bezier glyph, adds interactive hover tooltips (addressing a previously noted weakness), and shifts from distance-based to weight-based arc coloring for better semantic clarity.

Changes:

• Refactored arc rendering to use Bokeh's native bezier glyph with cubic bezier curves instead of manually computed quadratic curves
• Added interactive HoverTool for both arcs (showing connection details) and nodes (showing character names)
• Changed color scheme from distance-based (yellow/blue) to weight-based (light/medium/dark blue gradient)
• Updated metadata with new versions (Python 3.14.3, bokeh 3.8.2) and set quality_score to null pending automated review

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
plots/arc-basic/metadata/bokeh.yaml	Updated metadata with new Python/library versions, timestamp, and null quality score for pending review
plots/arc-basic/implementations/bokeh.py	Comprehensive refactor using native bezier glyphs, added hover interactivity, weight-based styling, and improved visual design

[Copilot]

Using Unicode character '\u00b7' (middle dot) directly in the title string. While this works, it's inconsistent with the approach in the old version and some other files that use the actual character '·' directly. For better readability and consistency with other implementations, consider using the actual character directly in the string.

Suggested change

	title="arc-basic \u00b7 bokeh \u00b7 pyplots.ai",
	title="arc-basic · bokeh · pyplots.ai",

[Copilot]

The HoverTool uses the bidirectional arrow character '\u2194' (↔) in the tooltip. While functional, consider using the actual character '↔' directly in the string for better code readability, similar to the recommendation for the title's middle dot.

Suggested change

	tooltips=[("Connection", "@source_name \u2194 @target_name"), ("Frequency", "@weight_label")], line_policy="interp"
	tooltips=[("Connection", "@source_name ↔ @target_name"), ("Frequency", "@weight_label")], line_policy="interp"

[Copilot]

This line appears to exceed the project's 120 character line length limit. Consider splitting the tooltips list across multiple lines for better readability and to comply with the project's formatting standards.

Suggested change

	tooltips=[("Connection", "@source_name \u2194 @target_name"), ("Frequency", "@weight_label")], line_policy="interp"
	tooltips=[
	("Connection", "@source_name \u2194 @target_name"),
	("Frequency", "@weight_label"),
	],
	line_policy="interp",

[Copilot]

The node_hover HoverTool on line 119 references p.renderers[-1], which assumes the last renderer added is the scatter plot for nodes. This is fragile and could break if additional renderers are added later. Consider storing the scatter renderer in a variable (e.g., node_renderer = p.scatter(...)) and then referencing it explicitly in the HoverTool for better maintainability.

Suggested change

	p.scatter(x="x", y="y", source=node_source, size=30, fill_color="#306998", line_color="white", line_width=3)
	# Node hover
	node_hover = HoverTool(tooltips=[("Character", "@name")], renderers=[p.renderers[-1]])
	node_renderer = p.scatter(
	x="x",
	y="y",
	source=node_source,
	size=30,
	fill_color="#306998",
	line_color="white",
	line_width=3,
	)
	# Node hover
	node_hover = HoverTool(tooltips=[("Character", "@name")], renderers=[node_renderer])

[Copilot]

The docstring header has a space missing after the opening triple quotes. The format should be """ pyplots.ai (with a space) not """pyplots.ai (without space), based on the convention seen in other implementations like matplotlib and seaborn for this same plot.

Suggested change

	"""pyplots.ai
	""" pyplots.ai

[claude]

AI Review - Attempt 1/3

Image Description

The plot displays an arc diagram with 8 character nodes (Alice, Bob, Carol, David, Eve, Frank, Grace, Henry) arranged along a horizontal baseline. Curved bezier arcs connect pairs of nodes above the line, with arc height proportional to the distance between connected nodes. The longest arc spans from Alice to Henry across the full width. Three visual weights are used: Frequent connections appear in dark navy (#1A3F5C) with thick lines, Moderate connections in medium blue (#306998), and Brief connections in light blue (#93B5CF) with thin, more transparent lines. Nodes are rendered as medium-blue circles with white borders. Character name labels appear below the baseline in dark gray. The title "arc-basic · bokeh · pyplots.ai" is positioned at the top-left. A legend at the top-right shows the three frequency categories. The background is white with all axes, grids, and outlines removed for a clean look.

Score: 85/100

Category	Score	Max
Visual Quality	27	30
Design Excellence	12	20
Spec Compliance	15	15
Data Quality	13	15
Code Quality	10	10
Library Mastery	8	10
Total	85	100

Visual Quality (27/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 28pt, labels 20pt, legend 20pt). Readable at full resolution, though title and legend text appear somewhat small relative to the large 4800×2700 canvas.
• VQ-02: No Overlap (6/6) — No text collisions. Node labels are well-spaced. Arcs overlap naturally but are semi-transparent as required.
• VQ-03: Element Visibility (5/6) — Nodes and arcs are visible. Brief-weight arcs (alpha=0.50, line_width=2.5) are somewhat faint; could benefit from slightly more contrast. Nodes at size=30 are adequate but on the smaller side.
• VQ-04: Color Accessibility (4/4) — Monochromatic blue palette differentiated by lightness is inherently colorblind-safe. Good contrast against white background.
• VQ-05: Layout & Canvas (3/4) — Good horizontal utilization. Vertical space has noticeable empty areas at the top (above tallest arc) and bottom (below labels). Canvas could be better utilized.
• VQ-06: Axis Labels & Title (2/2) — Title follows correct format. Axes are appropriately hidden for an arc diagram. Node labels are descriptive character names.

Design Excellence (12/20)

• DE-01: Aesthetic Sophistication (5/8) — Custom monochromatic blue palette (#93B5CF → #306998 → #1A3F5C) is cohesive and professional. White node borders add polish. Typography colors (#333333 title, #444444 legend) are intentional. Above defaults but not publication-level.
• DE-02: Visual Refinement (4/6) — All chrome removed (axes, grids, outline). Clean minimal appearance. Legend has subtle background (alpha=0.85). Good spacing and padding. Some wasted canvas space at top and bottom prevents a perfect score.
• DE-03: Data Storytelling (3/6) — Weight-based encoding (color + thickness + alpha) creates visual hierarchy. The Alice-Henry long-range frequent connection stands out as a natural focal point. However, the viewer still needs to discover patterns on their own — no strong emphasis or annotation guides interpretation.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct arc diagram: nodes along horizontal axis, curved arcs above.
• SC-02: Required Features (4/4) — All spec features present: arc height proportional to distance, semi-transparent arcs for overlap, readable node labels, color-coded edges by weight, thickness varies by weight.
• SC-03: Data Mapping (3/3) — Nodes correctly positioned along horizontal axis. All 12 edges correctly mapped. Arc heights correctly proportional to node distance.
• SC-04: Title & Legend (3/3) — Title "arc-basic · bokeh · pyplots.ai" matches required format. Legend with Frequent/Moderate/Brief labels matches weight categories in data.

Data Quality (13/15)

• DQ-01: Feature Coverage (5/6) — Shows both short-range (Bob-Carol) and long-range (Alice-Henry) connections, three weight levels, varying node connectivity (Alice=4 connections, others fewer). Could include a disconnected node or denser cluster for more variety.
• DQ-02: Realistic Context (4/5) — "Character interactions in a story chapter" is a plausible, neutral scenario. Character names (Alice, Bob, etc.) are recognizable but feel like standard placeholder names rather than characters from a real narrative.
• DQ-03: Appropriate Scale (4/4) — 8 nodes is slightly below the spec's "10-50" guideline but reasonable for readability. 12 edges across 8 nodes provides good density. Weight scale 1-3 is sensible.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Clean Imports → Data → Plot → Save structure with no functions or classes.
• CQ-02: Reproducibility (2/2) — All data is deterministic (hardcoded nodes and edges, no random elements).
• CQ-03: Clean Imports (2/2) — All imports are used: numpy, bokeh.io (export_png, save), bokeh.models (ColumnDataSource, HoverTool, Label, Legend, LegendItem), bokeh.plotting (figure).
• CQ-04: Code Elegance (2/2) — Clean, well-organized. Per-edge ColumnDataSource enables tooltips — appropriate pattern for Bokeh interactivity. No over-engineering.
• CQ-05: Output & API (1/1) — Saves as plot.png via export_png and plot.html via save. Uses current Bokeh 3.x API.

Library Mastery (8/10)

• LM-01: Idiomatic Usage (4/5) — Good use of ColumnDataSource for data, figure() for creation, p.bezier() for native curves, HoverTool for interactivity, Label/Legend/LegendItem for annotation. Very idiomatic Bokeh.
• LM-02: Distinctive Features (4/5) — Uses multiple Bokeh-distinctive features: native bezier glyph (p.bezier), HoverTool with tooltips for both arcs and nodes, dual output (PNG + interactive HTML). These features leverage Bokeh's web-first interactive design.

Score Caps Applied

• None — no score caps triggered

Strengths

• Perfect spec compliance — all required arc diagram features are present and correctly implemented
• Excellent use of Bokeh's native bezier glyph for arcs, avoiding manual path construction
• Interactive hover tooltips on both arcs and nodes leverage Bokeh's distinctive capabilities
• Clean monochromatic blue palette with weight-based visual encoding (color + thickness + alpha)
• Dual output (PNG + HTML) exploits Bokeh's web-first design
• Perfect code quality with KISS structure and deterministic data

Weaknesses

• Design excellence needs improvement — the plot is clean but not publication-ready
• Canvas utilization has empty space at top and bottom — tighter y_range would help
• Brief-weight arcs are somewhat faint and hard to distinguish at a glance
• No strong data storytelling — the viewer must discover patterns independently
• Node markers could be slightly larger for better visual presence

Issues Found

1. DE-01 MODERATE: Professional but not exceptional design. Custom palette is good but the overall impression is "clean default" rather than "intentionally designed."
   • Fix: Consider a subtle background tint, more typographic hierarchy (larger title, subtitle describing the data context), or accent color for the most important connections
2. DE-03 LOW: Data is displayed but not interpreted. No visual emphasis guides the viewer to key insights.
   • Fix: Highlight Alice as the most connected node (different color/size), or annotate the longest-range frequent connection (Alice-Henry). Use size variation on nodes to encode degree.
3. VQ-05 MINOR: Canvas has wasted vertical space at top and bottom.
   • Fix: Tighten y_range to better frame the arcs and labels. Reduce bottom padding.
4. VQ-03 MINOR: Brief-weight arcs are faint.
   • Fix: Increase minimum alpha from 0.50 to 0.55-0.60, or increase minimum line_width for better visibility.

AI Feedback for Next Attempt

The implementation is technically excellent with perfect spec compliance and strong library usage. To reach 90+, focus on Design Excellence: (1) Add data storytelling by encoding node degree in node size (larger nodes = more connections), making Alice visually prominent as the hub character. (2) Tighten the y_range to eliminate wasted vertical space. (3) Consider a subtle background color or gradient to add visual sophistication. (4) Increase the minimum arc alpha/width so Brief connections are more easily distinguished. (5) Add a descriptive subtitle below the title to provide context ("Character Interaction Frequency in Chapter 1").

Verdict: REJECTED

[github-actions]

🔧 Repair Attempt 1/3

Applied fixes based on AI review feedback.

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

---

🤖 impl-repair

[claude]

AI Review - Attempt 2/3

Image Description

The plot displays a basic arc diagram with 8 character nodes (Alice, Bob, Carol, David, Eve, Frank, Grace, Henry) arranged horizontally along a baseline. Curved bezier arcs connect nodes above the baseline, with arc height proportional to the distance between connected nodes. Three shades of blue encode connection frequency: dark navy (#1A3F5C) for "Frequent" interactions, medium blue (#306998) for "Moderate", and light blue (#93B5CF) for "Brief". Node sizes vary by weighted degree — Alice is the largest and darkest node, clearly identifiable as the hub character. A long-range arc from Alice to Henry is the tallest and most prominent. A subtle off-white background (#F7F9FB) with no visible axes or grid lines creates a clean look. The title "arc-basic · bokeh · pyplots.ai" appears in dark blue at the upper left with an italic subtitle "Character Interaction Frequency in Chapter 1" below. A three-item legend (Frequent, Moderate, Brief) sits in the upper right corner.

Score: 90/100

Category	Score	Max
Visual Quality	27	30
Design Excellence	15	20
Spec Compliance	15	15
Data Quality	15	15
Code Quality	10	10
Library Mastery	8	10
Total	90	100

Visual Quality (27/30)

• VQ-01: Text Legibility (7/8) — All font sizes explicitly set (title 32pt, subtitle 22pt, labels 20pt, legend 20pt). All text readable at full resolution. Legend text in corner appears slightly small relative to canvas.
• VQ-02: No Overlap (6/6) — No overlapping text or visual elements. Node labels well-spaced. Legend does not overlap data.
• VQ-03: Element Visibility (5/6) — Nodes and arcs visible and adapted to density. Brief-weight arcs are somewhat faint but distinguishable. Node sizes vary from 28 to 56 — smallest nodes (e.g., Grace) are small but visible.
• VQ-04: Color Accessibility (4/4) — Monochromatic blue palette relies on luminance differences, fully colorblind-safe. Good contrast between the three weight levels.
• VQ-05: Layout & Canvas (3/4) — Good horizontal utilization. Some wasted vertical space below the baseline. Legend positioned in far upper-right corner, slightly detached. Overall ~55% canvas utilization.
• VQ-06: Axis Labels & Title (2/2) — Correct title format with descriptive subtitle providing context. Node labels serve as axis for this chart type.

Design Excellence (15/20)

• DE-01: Aesthetic Sophistication (6/8) — Strong design: custom monochromatic blue palette (#93B5CF to #1A3F5C), intentional color hierarchy, data-driven node sizing, white node outlines for separation, subtle background tint. Clearly above defaults but not quite FiveThirtyEight-level polish.
• DE-02: Visual Refinement (5/6) — Axes hidden, grid hidden, outline removed, subtle background tint, clean minimal chrome. Nearly perfect — slight point off for legend placement in far corner and unbalanced bottom whitespace.
• DE-03: Data Storytelling (4/6) — Good visual hierarchy: Alice is clearly the hub character through larger size and darker color. Arc thickness/color encodes connection weight. Focal point is clear. Subtitle provides narrative context. Not quite "excellent" — doesn't quite tell a complete story the way a 6 would.

Spec Compliance (15/15)

• SC-01: Plot Type (5/5) — Correct arc diagram with nodes along horizontal line and curved arcs above.
• SC-02: Required Features (4/4) — All spec features present: nodes along horizontal line, arcs above baseline, arc height proportional to distance, semi-transparent arcs (alpha 0.45-0.71), readable node labels, color-coded edges by weight.
• SC-03: Data Mapping (3/3) — X positions linearly spaced, Y baseline at 0, arc heights correctly proportional to node distance.
• SC-04: Title & Legend (3/3) — Title "arc-basic · bokeh · pyplots.ai" in correct format. Legend with Frequent/Moderate/Brief labels matches data.

Data Quality (15/15)

• DQ-01: Feature Coverage (6/6) — Shows short-range arcs (Bob-Carol), long-range arcs (Alice-Henry), all three weight levels, hub vs. peripheral nodes. 12 edges across 8 nodes — good density for readability.
• DQ-02: Realistic Context (5/5) — Character interactions in a story chapter — real, comprehensible, neutral scenario. One of the canonical use cases for arc diagrams.
• DQ-03: Appropriate Scale (4/4) — 8 nodes appropriate for arc diagram readability. Weights 1-3 simple and clear. 12 edges show patterns without overcrowding.

Code Quality (10/10)

• CQ-01: KISS Structure (3/3) — Linear flow: imports → data → figure → arcs → nodes → labels → legend → save. No functions or classes.
• CQ-02: Reproducibility (2/2) — Fully deterministic data (hardcoded nodes and edges). No random generation.
• CQ-03: Clean Imports (2/2) — All imports used: numpy, bokeh.io (export_png, save), bokeh.models (ColumnDataSource, HoverTool, Label, Legend, LegendItem), bokeh.plotting (figure).
• CQ-04: Code Elegance (2/2) — Clean, Pythonic code. Good use of dictionaries for weight-based styling. Appropriate complexity. No fake functionality.
• CQ-05: Output & API (1/1) — Saves as plot.png via export_png and plot.html via save. Current Bokeh 3.x API.

Library Mastery (8/10)

• LM-01: Idiomatic Usage (4/5) — Good idiomatic Bokeh usage: ColumnDataSource, figure(), bezier glyph, scatter, Label, Legend with LegendItem. Creating separate ColumnDataSource per arc rather than batching is slightly suboptimal but functional.
• LM-02: Distinctive Features (4/5) — HoverTool for arc tooltips with source/target names, HoverTool for node tooltips with connection strength, native bezier glyph, HTML export — all distinctively Bokeh. Could go further with callbacks or linked selections for a 5.

Score Caps Applied

• None — No score caps triggered.

Strengths

• Cohesive monochromatic blue palette with intentional color hierarchy (darker = more connected)
• Data-driven node sizing (weighted degree) creates clear visual hierarchy with Alice as focal point
• Effective use of Bokeh-specific features: HoverTool for both arcs and nodes, native bezier glyph, dual PNG/HTML output
• Clean minimal chrome: no axes, no grid, subtle background tint, professional appearance
• Excellent data choice: character interactions in a story chapter is a canonical arc diagram use case
• Semi-transparent arcs allow overlapping connections to remain distinguishable

Weaknesses

• Legend positioned in far upper-right corner appears slightly small and detached from the main plot area
• Some "Brief" weight arcs are quite faint and may be hard to distinguish at smaller viewing sizes
• Bottom portion of canvas has unused whitespace below the node labels

Issues Found

None critical. Minor visual polish items noted in weaknesses.

AI Feedback for Next Attempt

Implementation meets quality standards. The cohesive blue palette, data-driven node sizing, Bokeh-specific interactivity, and clean minimal design create a professional arc diagram. The storytelling through visual hierarchy (Alice as hub) is effective.

Verdict: APPROVED