charts

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.