# Shared parameter snippets reused across chart tool schemas. # Update here to change the description everywhere at once. _LAYOUT_PARAM = { "type": "array", "description": ( "Optional. An array containing a single JSON-formatted Plotly layout dictionary. " "Use to set chart title, axis labels, colours, fonts, and other layout properties. " "Example: [{\"title\": \"Monthly Sales\", \"xaxis\": {\"title\": \"Month\"}}]" ), "items": {"type": "string"}, } _TRACE_STYLE_PARAM = { "type": "array", "description": ( "Optional. An array containing a single JSON-formatted Plotly trace styling dictionary. " "Use to control visual properties such as line colour, opacity, and marker style. " "Do NOT include 'x', 'y', or 'type' keys — those are set automatically from query.csv." ), "items": {"type": "string"}, } chart_tool_schemas = [ { "name": "scatter_chart_generation_func", "description": ( "Generates a Plotly scatter plot from query.csv data. " "Use when the user wants to visualise the relationship between two numeric columns, " "create a bubble chart (via the size parameter), or overlay a trendline. " "Returns an HTML iframe — display it verbatim in the chat." ), "parameters": { "type": "object", "properties": { "x_column": { "type": "array", "description": ( "One or more column names from query.csv to plot on the x-axis. " "Multiple columns produce multiple series, each plotted against y_column." ), "items": {"type": "string"}, }, "y_column": { "type": "string", "description": "Column name from query.csv to plot on the y-axis.", }, "category": { "type": "string", "description": "Optional column name used to colour-code points by a categorical grouping.", }, "trendline": { "type": "string", "description": ( "Optional trendline type. One of: 'ols' (linear regression), " "'lowess' (local smoothing), 'rolling', 'ewm', 'expanding'. " "Requires trendline_options when using 'lowess', 'rolling', or 'ewm'." ), }, "trendline_options": { "type": "array", "description": ( "Required when trendline is 'lowess', 'rolling', or 'ewm'. " "An array containing a single JSON-formatted dict of trendline options " "(e.g. [{\"window\": 7}] for a 7-point rolling average)." ), "items": {"type": "string"}, }, "marginal_x": { "type": "string", "description": "Optional marginal distribution plot along the x-axis. One of: 'histogram', 'rug', 'box', 'violin'.", }, "marginal_y": { "type": "string", "description": "Optional marginal distribution plot along the y-axis. One of: 'histogram', 'rug', 'box', 'violin'.", }, "size": { "type": "string", "description": "Optional column name whose values control the size of each point (bubble chart). Negative values are clamped to zero.", }, "data": _TRACE_STYLE_PARAM, "layout": _LAYOUT_PARAM, }, "required": ["x_column", "y_column"], }, }, { "name": "line_chart_generation_func", "description": ( "Generates a Plotly line chart from query.csv data. " "Use for trends over time or any ordered sequence. " "Returns an HTML iframe — display it verbatim in the chat." ), "parameters": { "type": "object", "properties": { "x_column": { "type": "string", "description": "Column name from query.csv for the x-axis (typically a date or ordered index).", }, "y_column": { "type": "string", "description": "Column name from query.csv for the y-axis (numeric values).", }, "category": { "type": "string", "description": "Optional column name used to split the data into multiple colour-coded lines.", }, "data": _TRACE_STYLE_PARAM, "layout": _LAYOUT_PARAM, }, "required": ["x_column", "y_column"], }, }, { "name": "bar_chart_generation_func", "description": ( "Generates a Plotly bar chart from query.csv data. " "Use for comparing values across categories. Supports grouped/stacked bars via category, " "and faceted subplots via facet_row or facet_col. " "Returns an HTML iframe — display it verbatim in the chat." ), "parameters": { "type": "object", "properties": { "x_column": { "type": "string", "description": "Column name from query.csv for the x-axis (category labels).", }, "y_column": { "type": "string", "description": "Column name from query.csv for the y-axis (numeric values).", }, "category": { "type": "string", "description": "Optional column name used to colour-code bars into grouped or stacked series.", }, "facet_row": { "type": "string", "description": "Optional column name. Creates one subplot row per unique value — useful for comparing distributions across a second dimension.", }, "facet_col": { "type": "string", "description": "Optional column name. Creates one subplot column per unique value.", }, "data": _TRACE_STYLE_PARAM, "layout": _LAYOUT_PARAM, }, "required": ["x_column", "y_column"], }, }, { "name": "pie_chart_generation_func", "description": ( "Generates a Plotly pie chart from query.csv data. " "Use when the user wants to show part-to-whole proportions. " "Returns an HTML iframe — display it verbatim in the chat." ), "parameters": { "type": "object", "properties": { "values": { "type": "string", "description": "Column name from query.csv containing the numeric value for each slice.", }, "names": { "type": "string", "description": "Column name from query.csv containing the label for each slice.", }, "data": _TRACE_STYLE_PARAM, "layout": _LAYOUT_PARAM, }, "required": ["values", "names"], }, }, { "name": "histogram_generation_func", "description": ( "Generates a Plotly histogram from query.csv data. " "Use to show the frequency distribution of a numeric column. " "Supports normalisation (percent, probability, density) and aggregation functions per bin. " "Returns an HTML iframe — display it verbatim in the chat." ), "parameters": { "type": "object", "properties": { "x_column": { "type": "string", "description": "Column name from query.csv whose values are binned on the x-axis.", }, "y_column": { "type": "string", "description": "Optional column name aggregated per bin via histfunc (e.g. sum of sales per price bucket).", }, "histnorm": { "type": "string", "description": "Optional normalisation. One of: 'percent', 'probability', 'density', 'probability density'.", }, "category": { "type": "string", "description": "Optional column name used to overlay multiple colour-coded histograms.", }, "histfunc": { "type": "string", "description": "Optional aggregation function applied to y_column per bin. One of: 'avg', 'sum', 'count'.", }, "data": _TRACE_STYLE_PARAM, "layout": _LAYOUT_PARAM, }, "required": ["x_column"], }, }, { "name": "box_chart_generation_func", "description": ( "Generates a Plotly box plot from query.csv data. " "Use to visualise the distribution of a numeric column and identify outliers. " "Especially useful for comparing distributions across categories. " "Returns an HTML iframe — display it verbatim in the chat." ), "parameters": { "type": "object", "properties": { "y_column": { "type": "string", "description": "Column name from query.csv containing the numeric values to distribute on the y-axis.", }, "x_column": { "type": "string", "description": "Optional column name. Groups data into one box per unique value on the x-axis.", }, "category": { "type": "string", "description": "Optional column name used to colour-code boxes by a secondary grouping.", }, "layout": _LAYOUT_PARAM, }, "required": ["y_column"], }, }, { "name": "correlation_heatmap_func", "description": ( "Computes pairwise Pearson correlations between numeric columns in query.csv and renders " "the result as a colour-coded heatmap (blue = positive, red = negative). " "Use when the user asks which variables are related, correlated, or associated with each other. " "Returns an HTML iframe — display it verbatim in the chat." ), "parameters": { "type": "object", "properties": { "columns": { "type": "array", "description": "Optional list of numeric column names to include in the matrix. If omitted, all numeric columns from query.csv are used. Avoid ID or index columns.", "items": {"type": "string"}, }, }, "required": [], }, }, { "name": "rolling_stats_func", "description": ( "Generates a rolling statistics / moving average chart from query.csv data. " "Overlays rolling aggregations (mean, std, min, max) on top of the original series. " "Use when the user asks for a moving average, rolling average, rolling statistics, or wants to smooth a time series. " "Returns an HTML iframe — display it verbatim in the chat." ), "parameters": { "type": "object", "properties": { "x_column": { "type": "string", "description": "Column name from query.csv for the x-axis — typically a date or sequential index.", }, "y_column": { "type": "string", "description": "Column name from query.csv containing the numeric values to compute rolling stats on.", }, "window": { "type": "integer", "description": "Rolling window size in number of rows. Default 7. Infer from the user's request.", }, "stats": { "type": "array", "description": "Statistics to overlay. Valid values: 'mean', 'std', 'min', 'max'. Defaults to ['mean'] if omitted.", "items": {"type": "string"}, }, "category": { "type": "string", "description": "Optional column name to group the data, producing separate rolling stat lines per group.", }, "layout": _LAYOUT_PARAM, }, "required": ["x_column", "y_column"], }, }, { "name": "table_generation_func", "description": ( "Formats query.csv results as a styled HTML table. " "Use when the user wants to view raw query results in a readable format, " "or when result data is too large to describe in text. Displays up to 200 rows. " "Returns an HTML table — display it verbatim in the chat." ), "parameters": {"type": "object", "properties": {}}, }, ]