Graphs
A graph field is a placeholder that AdviceDocs replaces with a rendered chart at document-fill time. You write it like any other field — {{ portfolio_graph }} — and the system detects it as a graph because the field name contains the substring graph. The chart type, dimensions, and colours are then configured in the field configuration UI after the template is uploaded.
How to write graph fields
There is no special syntax. Any field whose name contains graph is classified as a graph field. All the same rules as simple fields apply — whitespace inside the braces is ignored, names are lowercased for storage, and dots are allowed for nested access.
{{ portfolio_graph }}
{{ asset_allocation_graph }}
{{ net_worth_graph }}
{{ cost_comparison_graph }}
{{ adviser.fees_graph }}
One placeholder, many chart types
{{ portfolio_graph }} can be a pie or a bar — the placeholder is identical, only the configuration changes.Supported chart types
AdviceDocs supports four chart types. Pick the one that matches your data shape; each type renders a distinct figure server-side via Plotly.
Pie (default)
A categorical breakdown shown as wedges of a circle. Best for proportions of a whole — asset allocation, fee composition, income split. Default chart type when none is set.
Bar
A categorical breakdown shown as vertical bars. Best for comparing magnitudes side by side — expenses by category, returns by year, holdings by asset class.
Net Worth
A stacked bar chart with assets stacked upward, liabilities inverted downward, and a net worth trend line drawn over the top. One bar per period (e.g. one per year). Best for cashflow / wealth-projection visuals.
Cost Comparison
A multi-bar comparison with the Y-axis zoomed to the data range. Designed for comparing plan costs side by side — existing plan vs recommended plan, with each plan’s fee components stacked.
Configuring a graph field
After uploading your template, open the field configuration modal for any graph field. You will see:
- Chart type — pie, bar, net worth, or cost comparison.
- Base colour — a single hex value (e.g.
#2E86AB) which the renderer expands into a full palette. - Width and height — in pixels.
- Font family, font size, font colour — used for axis labels, slice labels, and the legend.
These settings are saved against the field on the template, so every document generated from that template will produce a chart with the same look.
How colours are generated
You only pick one colour. AdviceDocs derives the rest of the palette from it so the chart always has enough distinct shades for every category.
Shade generation
- The base hex is converted to HSL.
- Lightness is clamped into the range
[0.30, 0.85]so very dark and very light picks still produce a usable palette. - For an N-category chart, N shades are generated. The base colour stays at index 0; sibling shades fan out across lightness
[0.45, 0.85]with a small hue rotation per step (~9°) to keep the palette in an analogous family.
Net Worth uses two palettes
Net worth charts have two stacks — assets going up, liabilities going down — so the renderer uses a complementary colour for liabilities. Assets get shades of your base colour; liabilities get shades of the hue rotated 180°.
Default palette
If no base colour is set on the field, the renderer falls back to a five-colour categorical palette:
#2E86AB (blue)
#A23B72 (magenta)
#F18F01 (orange)
#8E7DBE (lavender)
#2CA58D (teal)
Data shapes by chart type
At fill time, your data has to match the shape the chart type expects. Pandas-based extraction will produce these automatically when a CSV is configured; the LLM fallback is schema-enforced to the same structures.
Pie and Bar
A list of { label, value } objects. At least one row, at least one numeric column.
[
{ "label": "Australian Equities", "value": 184155 },
{ "label": "International Equities", "value": 92340 },
{ "label": "Cash", "value": 31200 }
]
Net Worth
A single object with parallel arrays. Every array must be the same length as periods.
{
"periods": ["Jul-25", "Jul-26", "Jul-27"],
"assets": {
"Ordinary Investment": [184155, 198020, 213130],
"Superannuation": [421500, 452600, 486200]
},
"liabilities": {
"Home Loan": [463302, 451100, 438600]
},
"net_worth": [142353, 199520, 260730]
}
Cost Comparison
An object containing one entry per plan. Component names must be the same across every plan so the bars line up.
{
"plans": [
{
"name": "Existing Plans",
"components": {
"Admin Fees": 1881.09,
"Investment Fees": 3142.55,
"Adviser Fees": 2001.07
},
"net_ongoing_cost": 7024.71
},
{
"name": "Recommended Plan",
"components": {
"Admin Fees": 1240.00,
"Investment Fees": 2150.40,
"Adviser Fees": 1800.00
},
"net_ongoing_cost": 5190.40
}
]
}
Defaults
- Chart type —
piewhen nothing is configured. - Dimensions —
400 × 300for pie and bar;623 × 400for net worth. - Colours — the five-colour
DEFAULT_COLORWAYshown above. - Image scale — PNG output is rendered at 3× pixel density (Kaleido
scale=3) so the chart stays crisp when the document is printed.
Common pitfalls
Net Worth: array lengths must match
assets and liabilities, plus net_worth, must be the same length as periods. If they don’t match, the field fails validation with a message like "Asset 'X' must have N values, got M".Pie / Bar: needs at least one numeric column
value. Rows with only strings will fail validation.Cost Comparison: components must match across plans
Adviser Fees and another doesn’t, the chart will fail to render. Use 0 for components that don’t apply rather than omitting them.Type/data mismatch falls back to pie
cost_comparison but the data arrives as a flat list (e.g. from a stale extraction run), the renderer logs a warning and falls back to pie. Re-run extraction so the data shape matches the configured type.Extreme colours are clamped
#000000) and pure white (#FFFFFF) are clamped into the [0.30, 0.85] lightness band before the palette is generated, so the derived shades stay distinguishable. If you need a true black or white look, the chart won’t honour it exactly — pick a near-black or near-white instead.Rendering pipeline
At document-fill time:
- The field is detected as a graph (
field_type="graph"). - Chart type, dimensions, and colours are read from the field’s configuration.
- Data is shaped into the structure required by the chart type.
- Plotly builds the figure; Kaleido exports it to PNG at 3× scale.
- The PNG bytes are inlined into the Word document at the placeholder location.
Syntax to copy
Drop these into a template document. Rename to match your data; configure the chart type and colour in the field editor afterwards.
{{ asset_allocation_graph }}
{{ income_breakdown_graph }}
{{ fee_split_graph }}
{{ net_worth_graph }}
{{ wealth_projection_graph }}
{{ cost_comparison_graph }}
{{ fee_comparison_graph }}