[NOTICKET] fix: aggregate trend charts + materialize analyze_* tables in the chart chain

A "visualize the trend of X" question produced a broken chart in two ways:
render_chart errored ("cannot materialize 'data' of kind 'table'"), and once
that was worked around it plotted 9,729 raw rows (a vertical smear) of the wrong
column (Plan_PA_Percent aliased "pa_percent") instead of a per-day mean trend.

Tools (materialize + render):
- _materialize (invoker.py) now accepts the analyze_* table shape: a ToolOutput
of kind "table" whose data is `value` = list-of-dicts (columns/rows None), as
analyze_aggregate emits. Previously only the retrieve_data columns+rows shape
was handled, so ANY analyze_* -> analyze_*/render_chart chain failed. Class fix.
- render_chart (visualization.py) resolves a requested x/y column to its
aggregated name when the exact name is absent (pa_percent -> pa_percent_mean),
so a retrieve -> analyze_aggregate -> render_chart chain doesn't 404 on columns.

Planner (planner.md + examples.py):
- A line/trend chart over time must produce ONE ROW PER PERIOD: group_by the date
+ aggregate the measure in the retrieve_data IR (or chain analyze_trend), never
feed render_chart raw per-record rows. Added Example M (trend line chart).
- Pick the EXACT measure the user named, not a planned/target/adjusted/_2 sibling
(generic guidance, no dataset-specific column names in the global prompt).

Verified live: "visualisasi trend PA" now plans retrieve(group_by From_Date +
avg PA_Percent) -> render_chart, a clean 20-point daily trend on the right column.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/agents/planner/examples.py

@@ -905,6 +905,85 @@ _EXAMPLE_L = TaskList(
 )
 
 
+# --------------------------------------------------------------------------- #
+# Example M — line/TREND chart over time (viz tail on a time series).
+# "Show me a line chart of average revenue over time."
+# Shows: a trend line chart aggregates PER TIME PERIOD first — group_by the date
+# column + aggregate the measure in the retrieve_data IR (one row per date), THEN
+# tail render_chart. Never chart raw per-record rows over time (many rows per date
+# = an unreadable vertical smear). Mirrors Example J (bar) but grouping by the date
+# instead of a category. (analyze_trend -> render_chart is an equally valid shape.)
+# --------------------------------------------------------------------------- #
+
+_EXAMPLE_M = TaskList(
+    plan_id="example_m",
+    goal_restated="Chart average order revenue per day as a line chart over time.",
+    assumptions=["The date and revenue columns exist in the catalog (c_order_date, c_revenue)."],
+    open_questions=[],
+    tasks=[
+        Task(
+            id="t1",
+            stage="data_understanding",
+            objective="Confirm the sales source exposes order date and revenue.",
+            tool_calls=[ToolCall(tool="check_data", args={"source_id": "src_sales"})],
+            expected_output="source_shape",
+            success_criteria="Produced the orders table schema; order date and revenue present.",
+            depends_on=[],
+            estimated_cost="low",
+        ),
+        Task(
+            id="t2",
+            stage="data_preparation",
+            objective="Aggregate average revenue per day (one row per date).",
+            tool_calls=[
+                ToolCall(
+                    tool="retrieve_data",
+                    args={
+                        "ir": {
+                            "source_id": "src_sales",
+                            "table_id": "t_orders",
+                            "select": [
+                                {"kind": "column", "column_id": "c_order_date", "alias": "order_date"},
+                                {"kind": "agg", "fn": "avg", "column_id": "c_revenue", "alias": "avg_revenue"},
+                            ],
+                            "group_by": ["c_order_date"],
+                            "order_by": [{"column_id": "c_order_date", "dir": "asc"}],
+                        }
+                    },
+                )
+            ],
+            expected_output="daily_revenue",
+            success_criteria="Produced one average-revenue row per date, ordered by date.",
+            depends_on=["t1"],
+            estimated_cost="low",
+        ),
+        Task(
+            id="t3",
+            stage="evaluation",
+            objective="Render the daily average-revenue series as a line chart.",
+            tool_calls=[
+                ToolCall(
+                    tool="render_chart",
+                    args={
+                        # `data` is the AGGREGATED daily table (t2) — one point per date,
+                        # never the raw per-order rows.
+                        "data": "${t2}",
+                        "chart_type": "line",
+                        "x": "order_date",
+                        "y": "avg_revenue",
+                        "title": "Average revenue over time",
+                    },
+                )
+            ],
+            expected_output="revenue_line_chart",
+            success_criteria="Produced a line-chart spec with one point per date.",
+            depends_on=["t2"],
+            estimated_cost="low",
+        ),
+    ],
+)
+
+
 EXAMPLES: list[tuple[str, TaskList]] = [
     ("Which product categories drove last quarter's revenue?", _EXAMPLE_A),
     ("How has monthly revenue trended by region this year, and what's unusual?", _EXAMPLE_B),
@@ -922,6 +1001,7 @@ EXAMPLES: list[tuple[str, TaskList]] = [
     ("Show me a bar chart of total revenue per product category.", _EXAMPLE_J),
     ("Plot the customer churn rate by month as a line chart.", _EXAMPLE_K),
     ("How many orders have zero revenue?", _EXAMPLE_L),
+    ("Show me a line chart of average revenue over time.", _EXAMPLE_M),
 ]
 
 

src/config/prompts/planner.md

@@ -137,6 +137,17 @@ recipe verbatim; a genuinely multi-part question composes recipes.
   already-aggregated table (one row per category/period), not raw rows. Pick
   `chart_type` by the question: `bar` (magnitude per category), `line` (over
   time), `pie` (share of a small whole), `scatter` (two numeric columns).
+  **A `line`/trend chart over time needs ONE ROW PER TIME PERIOD** — either
+  `group_by` the date column + aggregate the measure in the `retrieve_data` IR
+  (like the per-category bar chart, but grouping by the date), or chain
+  `analyze_trend` first, then tail `render_chart` on that. NEVER feed the chart
+  raw per-record rows over time: with many records per date it draws an
+  unreadable vertical smear, not a trend. And pick the EXACT measure the user
+  named: when several catalog columns share a name stem — an actual metric vs a
+  `planned`/`target`/`adjusted`/`_2`-style variant — choose the one that matches
+  the user's term exactly, not a qualified sibling, unless the user asked for the
+  variant. Aliasing a near-miss column to the asked-for name is the same mistake
+  as rule 6's stand-in column.
   A chart ask NEVER relaxes feasibility (rule 6): if the asked-for dimension or
   measure has no catalog column, the question is **infeasible** — never chart a
   stand-in column aliased under the asked-for name (e.g. never select a status

src/tools/analytics/visualization.py

@@ -153,6 +153,19 @@ Example questions:
 """
 
 
+# analyze_aggregate renames a measure column to "<col>_<fn>" (e.g. pa_percent ->
+# pa_percent_mean). A chart planned before that rename references the original
+# name, so resolve it to the aggregated column when the exact name is absent.
+_AGG_SUFFIXES = ("mean", "sum", "count", "min", "max", "median", "nunique", "avg")
+
+
+def _resolve_col(name: str, columns) -> str:
+    if name in columns:
+        return name
+    hits = [c for c in columns if c in {f"{name}_{s}" for s in _AGG_SUFFIXES}]
+    return hits[0] if len(hits) == 1 else name
+
+
 def render_chart(
     df: pd.DataFrame,
     chart_type: str,
@@ -182,6 +195,12 @@ def render_chart(
         raise UnsupportedChartTypeError(
             f"unsupported chart_type '{chart_type}'; supported: {list(CHART_TYPES)}"
         )
+    # Resolve chart columns to their aggregated names (pa_percent -> pa_percent_mean)
+    # so a retrieve_data -> analyze_aggregate -> render_chart chain works.
+    x = _resolve_col(x, df.columns)
+    y = _resolve_col(y, df.columns)
+    if series is not None:
+        series = _resolve_col(series, df.columns)
     needed = [x, y] if chart_type == "pie" or series is None else [x, y, series]
     missing = [c for c in needed if c not in df.columns]
     if missing:

src/tools/invoker.py

@@ -157,14 +157,24 @@ def _materialize(data: Any) -> tuple[pd.DataFrame, None] | tuple[None, str]:
     if isinstance(data, ToolOutput):
         if data.kind == "error":
             return None, f"upstream data unavailable: {data.error}"
-        if data.kind != "table" or data.columns is None:
-            return None, f"cannot materialize 'data' of kind {data.kind!r}"
-        return _normalize_numeric(pd.DataFrame(data.rows or [], columns=data.columns)), None
+        if data.kind == "table":
+            # retrieve_data shape: columns + rows (list-of-lists).
+            if data.columns is not None:
+                return _normalize_numeric(pd.DataFrame(data.rows or [], columns=data.columns)), None
+            # analyze_* shape: `value` is a list-of-dicts (e.g. analyze_aggregate),
+            # so a chained analyze_* / render_chart can consume an aggregate output.
+            if isinstance(data.value, list):
+                return _normalize_numeric(pd.DataFrame(data.value)), None
+        return None, f"cannot materialize 'data' of kind {data.kind!r}"
 
     if isinstance(data, dict) and "columns" in data:
         df = pd.DataFrame(data.get("rows") or [], columns=data["columns"])
         return _normalize_numeric(df), None
 
+    # Serialized analyze_* table: {"kind": "table", "value": [ {...}, ... ]}.
+    if isinstance(data, dict) and isinstance(data.get("value"), list):
+        return _normalize_numeric(pd.DataFrame(data["value"])), None
+
     # A {table_id/source_id} dict is a raw catalog reference the planner inlined
     # instead of chaining a retrieve_data output (Pattern A). analyze_* tools never
     # self-fetch, so give an actionable message rather than the opaque type name.