feat: add planning step before visualization generation (#62)

Add a plan_visualization tool that the agent must call before any
visualization tool (widgetRenderer, pieChart, barChart). This gives users
transparency into the agent's approach and improves output quality by
forcing structured thinking before code generation.

Author: GeneralJerel

apps/agent/main.py

@@ -18,13 +18,14 @@
 from src.query import query_data
 from src.todos import AgentState, todo_tools
 from src.form import generate_form
+from src.plan import plan_visualization
 from src.templates import template_tools
 
 load_dotenv()
 
 agent = create_deep_agent(
     model=ChatOpenAI(model=os.environ.get("LLM_MODEL", "gpt-5.4-2026-03-05")),
-    tools=[query_data, *todo_tools, generate_form, *template_tools],
+    tools=[query_data, plan_visualization, *todo_tools, generate_form, *template_tools],
     middleware=[CopilotKitMiddleware()],
     context_schema=AgentState,
     skills=[str(Path(__file__).parent / "skills")],
@@ -53,6 +54,23 @@
         - Pre-styled form elements (buttons, inputs, sliders look native automatically)
         - Pre-built SVG CSS classes for color ramps (.c-purple, .c-teal, .c-blue, etc.)
 
+        ## Visualization Workflow (MANDATORY)
+
+        When producing ANY visual response (widgetRenderer, pieChart, barChart), you MUST
+        follow this exact sequence:
+
+        1. **Acknowledge** — Reply with 1-2 sentences of plain text acknowledging the
+           request and setting context for what the visualization will show.
+        2. **Plan** — Call `plan_visualization` with your approach, technology choice,
+           and 2-4 key elements. Keep it concise.
+        3. **Build** — Call the appropriate visualization tool (widgetRenderer, pieChart,
+           or barChart).
+        4. **Narrate** — After the visualization, add 2-3 sentences walking through
+           what was built and offering to go deeper.
+
+        NEVER skip the plan_visualization step. NEVER call widgetRenderer, pieChart, or
+        barChart without calling plan_visualization first.
+
         ## UI Templates
 
         Users can save generated UIs as reusable templates and apply them later.

apps/agent/src/plan.py

@@ -0,0 +1,21 @@
+"""Planning tool for visualization generation."""
+
+from langchain.tools import tool
+
+
+@tool
+def plan_visualization(
+    approach: str, technology: str, key_elements: list[str]
+) -> str:
+    """Plan a visualization before building it. MUST be called before
+    widgetRenderer, pieChart, or barChart. Outlines the approach, technology
+    choice, and key elements.
+
+    Args:
+        approach: One sentence describing the visualization strategy.
+        technology: The primary technology (e.g. "inline SVG", "Chart.js",
+            "HTML + Canvas", "Three.js", "Mermaid", "D3.js").
+        key_elements: 2-4 concise bullet points describing what will be built.
+    """
+    elements = "\n".join(f"  - {e}" for e in key_elements)
+    return f"Plan: {approach}\nTech: {technology}\n{elements}"

apps/app/src/components/generative-ui/plan-card.tsx

@@ -0,0 +1,56 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+interface PlanCardProps {
+  status: "executing" | "inProgress" | "complete";
+  approach?: string;
+  technology?: string;
+  key_elements?: string[];
+}
+
+export function PlanCard({ status, approach, technology, key_elements }: PlanCardProps) {
+  const detailsRef = useRef<HTMLDetailsElement>(null);
+  const isRunning = status === "executing" || status === "inProgress";
+
+  useEffect(() => {
+    if (!detailsRef.current) return;
+    detailsRef.current.open = isRunning;
+  }, [isRunning]);
+
+  const spinner = (
+    <span className="inline-block h-3 w-3 rounded-full border-2 border-gray-400 border-t-transparent animate-spin" />
+  );
+  const checkmark = <span className="text-green-500 text-xs">✓</span>;
+
+  return (
+    <div className="my-2 text-sm">
+      <details ref={detailsRef} open>
+        <summary className="flex items-center gap-2 text-gray-600 dark:text-gray-400 cursor-pointer list-none">
+          {isRunning ? spinner : checkmark}
+          <span className="font-medium">
+            {isRunning ? "Planning visualization…" : `Plan: ${technology || "visualization"}`}
+          </span>
+          <span className="text-[10px]">▼</span>
+        </summary>
+        {approach && (
+          <div className="pl-5 mt-1.5 space-y-1.5 text-xs text-gray-500 dark:text-zinc-400">
+            {technology && (
+              <span className="inline-block px-1.5 py-0.5 rounded bg-gray-100 dark:bg-zinc-700 text-gray-600 dark:text-zinc-300 font-medium text-[11px]">
+                {technology}
+              </span>
+            )}
+            <p className="text-gray-600 dark:text-gray-400">{approach}</p>
+            {key_elements && key_elements.length > 0 && (
+              <ul className="list-disc pl-4 space-y-0.5">
+                {key_elements.map((el, i) => (
+                  <li key={i}>{el}</li>
+                ))}
+              </ul>
+            )}
+          </div>
+        )}
+      </details>
+    </div>
+  );
+}

apps/app/src/hooks/use-generative-ui-examples.tsx

@@ -7,6 +7,7 @@ import {
   useFrontendTool,
   useHumanInTheLoop,
   useDefaultRenderTool,
+  useRenderTool,
 } from "@copilotkit/react-core/v2";
 
 // Generative UI imports
@@ -15,6 +16,7 @@ import { BarChart, BarChartProps } from "@/components/generative-ui/charts/bar-c
 import { WidgetRenderer, WidgetRendererProps } from "@/components/generative-ui/widget-renderer";
 import { MeetingTimePicker } from "@/components/generative-ui/meeting-time-picker";
 import { ToolReasoning } from "@/components/tool-rendering";
+import { PlanCard } from "@/components/generative-ui/plan-card";
 
 export const useGenerativeUIExamples = () => {
   const { theme, setTheme } = useTheme();
@@ -61,6 +63,22 @@ export const useGenerativeUIExamples = () => {
     render: WidgetRenderer,
   });
 
+  // --------------------------
+  // 🪁 Plan Visualization: Custom rendering for the planning step
+  // --------------------------
+  const PlanVisualizationParams = z.object({
+    approach: z.string(),
+    technology: z.string(),
+    key_elements: z.array(z.string()),
+  });
+  useRenderTool({
+    name: "plan_visualization",
+    parameters: PlanVisualizationParams,
+    render: ({ status, parameters }) => (
+      <PlanCard status={status} {...parameters} />
+    ),
+  });
+
   // --------------------------
   // 🪁 Default Tool Rendering: https://docs.copilotkit.ai/langgraph/generative-ui/backend-tools
   // --------------------------