Charts

Charts ship in one of two forms. Pick the form first, then follow that section plus the shared rules at the end.

• Native chart — an interactive figure the app renders inline, with zoom, hover, and PNG export. Default for anything delivered on screen.
• Raster chart — a matplotlib PNG or SVG. Use it when the chart must be embedded in a generated document (DOCX, PDF, PPTX) or when the user asks for an image file.

When a chart is both shown to the user and embedded in a document, produce both: the native figure for the conversation, the image for the document.

Native charts

Write a file named <name>.chart.json in output/. It must contain a single JSON object — a Plotly figure — with a data array of traces and an optional layout object:

{
  "data": [
    {
      "type": "bar",
      "name": "Revenue",
      "x": ["Q1", "Q2", "Q3", "Q4"],
      "y": [12400, 15100, 14800, 19300]
    }
  ],
  "layout": {
    "title": { "text": "Revenue by quarter (USD)" },
    "xaxis": { "title": { "text": "Quarter" } },
    "yaxis": { "title": { "text": "Revenue (USD)" } }
  }
}

No library is required. Author the JSON directly when you already know the numbers — with json.dump from a small script, or by writing the file outright. Reach for plotly only when the traces have to be computed from data you are processing anyway; if you do, install it in its own exec call the way matplotlib is installed below (python3 -m pip install --user plotly==6.9.0) and serialize with fig.to_json().

Use standard Plotly figure attributes — the whole vocabulary is available, including bar, scatter (lines and points), pie, heatmap, histogram, box, candlestick, treemap, sunburst, waterfall, and funnel.

Rules for native figures:

• Self-contained data only. Inline every value in the trace. No external data URLs, no remote sources, no scripts — a figure that fetches something will not render.
• Stay well under 512 KiB. Aggregate, bucket, or downsample before writing rather than embedding a huge raw series; a chart nobody can read at full resolution does not need full resolution.
• Title, axis labels with units, and a legend for multi-series figures are mandatory, same as for raster charts.
• Do not set explicit colors, fonts, or backgrounds unless the user asks for specific ones. The app themes figures to match its light and dark palette, and hardcoded styling fights it.

Raster charts (matplotlib)

Installing the library

Install the pinned dependency with its own exec call — commands have a bounded wall clock, and one pip invocation per package stays inside it:

python3 -m pip install --user matplotlib==3.11.1

Installs work only when this chat's network policy allows package managers, and they persist for the rest of the conversation. If an install is refused by policy, do not retry: tell the user to enable the package-manager network policy for this chat, and offer the closest result you can produce without the library (a native chart figure, the summarized data as a table, or an SVG you write by hand for a simple chart) — only with their knowledge, never as a silent substitution. If a dependency cannot be installed at all, say so plainly instead of quietly delivering a lesser format.

Rendering

• Use the non-interactive backend — set matplotlib.use("Agg") before importing pyplot — and save with fig.savefig(...); never call plt.show() in the sandbox.
• Render PNG by default. When the user asks for a vector or print-ready graphic, save SVG (and provide PNG alongside it unless they only want the vector).
• Size for reading, not for thumbnails: around figsize=(10, 6) at dpi=150 for a standalone PNG, and bbox_inches="tight" so labels are not clipped.

Readability

• Every chart gets a title, axis labels with units, and — whenever more than one series is plotted — a legend with meaningful names.
• Rotate or thin dense tick labels rather than letting them collide; format large numbers with thousands separators or scaled units.
• Prefer one clear message per chart over a crowded multi-axis figure; produce several charts when the data carries several stories.
• Use color plus a second cue (marker or line style) to distinguish series, and keep font sizes at 10pt equivalent or larger after export.

Saving deliverables

Save finished charts in output/ — files there are published to the user as durable outputs. Writing the same filename again publishes a new version of the same output, so keep the filename stable when revising and change it only when the user asks for a distinct chart. When a chart accompanies a document deliverable (a report embedding the figure), save both files in output/: the document and the standalone chart.

Validation before declaring done

Native charts. You cannot see the render, so validate the file instead. Read it back and check that it parses as JSON, that it is a single object, that data is a non-empty array whose entries are objects, and that each trace carries a plausible type and the fields that type needs. Re-read the numbers against your source too — a figure that renders beautifully from the wrong values is still wrong. Fix the file rather than shipping a figure you have not checked.

Raster charts. PNG and SVG land in output/ where you can see them directly in the exec result flow — inspect the rendered image before presenting it: no clipped or colliding labels, a legend that matches the series, axes that start where you intended, and text large enough to read at natural size. Fix the plotting code rather than accepting a flawed render.

Only declare the chart done after it checks out.