Diagrams

Quizzes, exam papers and Ask replies can include figures: graphs, geometry, charts, number lines, science diagrams. They are delivered as complete, self-contained SVG strings inside the existing JSON responses. There are no image URLs, extra endpoints or extra round trips. Diagrams are an opt-in entitlement: ask us to enable svg_diagrams on your account. It takes effect on the next request, is reversible, and can be granted per environment. While it is off, no diagram fields appear.

Diagrams are additive and uncommon: most questions and replies carry none, so treat every diagram field as optional.

Surface	Field	Location
Quiz	diagram_data	On each object in questions[] in Retrieve a quiz
Exams	diagram_data	On each paper question, same shape as Quiz
Ask	visualisations	Top level of Send a message and GET /api/v1/messages/:id; inside chat on Retrieve a chat (latest assistant message only)

Quiz diagram_data

Omitted entirely when the question has no diagram or the entitlement is off. It is never null and never {}, so a presence check is enough.

Key	Type	Description
question_diagram	object, optional	The figure belonging to the question stem
option_diagrams	object, optional	Map of option key (A–E) to a diagram object
.svg	string	Complete SVG document. Render inline
.alt_text	string	Description of the figure. Always present; use it as the accessible name
.diagram_type	string	What produced the figure (see below). Descriptive only; treat unknown values as normal

Read only the keys above and ignore any key you do not recognise; do not store, display or fail on it.

Pick-the-graph questions: option_diagrams

Some multiple-choice questions ask the student to identify the correct graph or shape. Each option is a diagram, delivered in option_diagrams keyed by option letter. These are rare, but they are the one case where a missing render makes the question unanswerable.

When option_diagrams is present, the options array holds the placeholder strings "Graph A", "Graph B" and so on. That text is not answer content: render each option’s figure in place of its text label and submit the option key. Iterate the object’s own keys rather than assuming four options. A question may have both a stem figure and option figures; handle them independently.

Ask visualisations

An array, omitted when empty. A reply can carry several figures.

format is svg. If you ever receive another value, show alt_text as a caption and skip the figure; never inject unknown content as HTML. As a defensive measure, strip any inline

block from assistant content before display; the figures are supplied in the array. This regex allows > inside quoted attribute values:

The SVG

• Each SVG is a complete <svg> document, safe to inline: no scripts, no event-handler attributes and no external references. Rendering makes no network requests, so inlining needs no img-src, connect-src or font-src CSP allowance.
• The root has viewBox, width="100%", role="img" and an inline max-width style; fonts are system-ui stacks.
• Each SVG is a few KB and never more than 50 KB.
• diagram_type describes the kind of figure, for example coordinate_graph, geometry, bar_chart, pie_chart, line_chart, number_line, box_whisker, physics, chemistry, biology, economics, contextual, primary, solid or network. Other values may be added; treat unknown values as normal and render the SVG.
• A diagram returned for a question or message is identical on every later read, so cache it with the record.

Integration checklist

1. One shared figure component taking { svg, alt_text }. Inline the markup (do not wrap it in a data: image) and set aria-label from alt_text.
2. Guard against empty renders. Occasionally a stored SVG draws nothing but a background. Before injecting, test for at least one drawn element and fall back to alt_text otherwise: /<(path|circle|ellipse|line|polygon|polyline|text|image)b/.test(svg).
3. Handle option_diagrams in the MCQ renderer (above). This is the only change that affects answer selection.
4. Treat diagrams as optional everywhere; design layouts so no figure is the default.
5. Use a light surface. Figures are dark-on-white with meaningful colour; do not apply filter: invert() for dark mode.
6. Presence can vary. Diagrams are added to content generated after enablement, but treat any quiz as possibly carrying one and handle presence normally.