@vertesia/ui 0.80.0-dev.20251121 → 0.80.0

package/src/features/agent/createChartTool.ts

@@ -0,0 +1,364 @@
+/**
+ * Chart creation tool definition for AI agents.
+ *
+ * This provides a tool schema that AI agents can use to understand
+ * how to create charts in their responses.
+ */
+
+import type { AgentChartSpec } from './chat/AgentChart';
+
+/**
+ * Tool definition for creating charts.
+ * Can be used with Claude, OpenAI, or other LLM tool-calling systems.
+ */
+export const createChartToolDefinition = {
+    name: 'create_chart',
+    description: `Create an interactive chart visualization that will be rendered in the UI.
+
+IMPORTANT: You don't actually "call" this tool. Instead, you include a markdown code block with language "chart" in your response.
+
+Charts are created using JSON specifications in markdown code blocks:
+
+\`\`\`chart
+{
+  "chart": "bar|line|area|composed|pie|scatter|radar|radialBar|funnel|treemap",
+  "title": "Chart Title",
+  "data": [...],
+  ...
+}
+\`\`\`
+
+## CHART TYPES & WHEN TO USE
+
+| Type | Use Case | Data Shape |
+|------|----------|------------|
+| bar | Category comparisons | \`[{x, y1, y2}]\` |
+| line | Trends over time | \`[{x, y1, y2}]\` |
+| area | Trends with volume emphasis | \`[{x, y1, y2}]\` |
+| composed | Mix bars + lines | \`[{x, y1, y2}]\` with series.type |
+| pie | Part-to-whole (%) | \`[{name, value}]\` |
+| scatter | Correlation analysis | \`[{x, y}]\` |
+| radar | Multi-dimensional comparison | \`[{axis, A, B}]\` |
+| radialBar | Progress/gauges | \`[{name, value}]\` |
+| funnel | Conversion stages | \`[{name, value}]\` |
+| treemap | Hierarchical proportions | \`[{name, value}]\` |
+
+## EXAMPLES
+
+### Bar Chart
+\`\`\`chart
+{"chart":"bar","title":"Revenue by Quarter","data":[{"quarter":"Q1","revenue":100000},{"quarter":"Q2","revenue":150000}],"xKey":"quarter","series":[{"key":"revenue","label":"Revenue"}]}
+\`\`\`
+
+### Line Chart
+\`\`\`chart
+{"chart":"line","title":"Performance","data":[{"period":"Q1","tvpi":1.2},{"period":"Q2","tvpi":1.5}],"xKey":"period","series":[{"key":"tvpi","label":"TVPI","color":"#4f46e5"}]}
+\`\`\`
+
+### Area Chart
+\`\`\`chart
+{"chart":"area","title":"Sales Volume","data":[{"month":"Jan","sales":1000},{"month":"Feb","sales":1500}],"xKey":"month","series":[{"key":"sales","label":"Sales"}],"options":{"stacked":true}}
+\`\`\`
+
+### Composed Chart (Bar + Line)
+\`\`\`chart
+{"chart":"composed","title":"Cashflow","data":[{"period":"Q1","calls":1000000,"net":-500000}],"xKey":"period","series":[{"key":"calls","type":"bar","color":"#ef4444"},{"key":"net","type":"line","yAxisId":"right"}],"yAxis":{"left":{"label":"Amount"},"right":{"label":"Net"}}}
+\`\`\`
+
+### Pie Chart
+\`\`\`chart
+{"chart":"pie","title":"Market Share","data":[{"name":"Product A","value":400},{"name":"Product B","value":300},{"name":"Product C","value":200}],"nameKey":"name","valueKey":"value"}
+\`\`\`
+
+### Donut Chart (Pie with innerRadius)
+\`\`\`chart
+{"chart":"pie","title":"Revenue Split","data":[{"name":"Services","value":60},{"name":"Products","value":40}],"nameKey":"name","valueKey":"value","options":{"innerRadius":50}}
+\`\`\`
+
+### Scatter Chart
+\`\`\`chart
+{"chart":"scatter","title":"Price vs Volume","data":[{"price":100,"volume":500},{"price":150,"volume":400}],"xKey":"price","yKey":"volume","series":[{"key":"data","label":"Products"}]}
+\`\`\`
+
+### Radar Chart
+\`\`\`chart
+{"chart":"radar","title":"Skills Comparison","data":[{"skill":"Speed","A":120,"B":110},{"skill":"Power","A":98,"B":130}],"axisKey":"skill","series":[{"key":"A","label":"Team A"},{"key":"B","label":"Team B"}]}
+\`\`\`
+
+### RadialBar Chart (Progress)
+\`\`\`chart
+{"chart":"radialBar","title":"Goal Progress","data":[{"name":"Sales","value":80},{"name":"Users","value":65}],"nameKey":"name","valueKey":"value"}
+\`\`\`
+
+### Funnel Chart
+\`\`\`chart
+{"chart":"funnel","title":"Conversion Funnel","data":[{"name":"Visits","value":5000},{"name":"Cart","value":2500},{"name":"Purchase","value":1000}],"nameKey":"name","valueKey":"value"}
+\`\`\`
+
+### Treemap
+\`\`\`chart
+{"chart":"treemap","title":"Budget Allocation","data":[{"name":"Engineering","value":500000},{"name":"Marketing","value":200000},{"name":"Sales","value":300000}],"nameKey":"name","dataKey":"value"}
+\`\`\`
+
+## CONFIGURATION
+
+### Series (for bar/line/area/composed/radar)
+- key: (required) Field name in data
+- label: Display name
+- type: "bar"|"line"|"area" (composed only)
+- color: Hex color
+- yAxisId: "left"|"right"
+- dot: Show dots on lines
+
+### Keys (for pie/scatter/radar/funnel/treemap)
+- nameKey: Field for labels (default: "name")
+- valueKey: Field for values (default: "value")
+- xKey/yKey: For scatter charts
+- axisKey: For radar axis labels
+- dataKey: For treemap values
+
+### Options
+- stacked: Stack bars/areas
+- referenceZero: Show y=0 line
+- innerRadius: For donut charts (0-100)
+- showLabels: Show value labels
+- startAngle/endAngle: For radialBar
+
+## COLORS
+- Blue #4f46e5 - Primary
+- Cyan #06b6d4 - Secondary
+- Green #22c55e - Positive
+- Amber #f59e0b - Warning
+- Red #ef4444 - Negative
+- Purple #8b5cf6 - Accent
+- Pink #ec4899 - Highlight
+- Teal #14b8a6 - Alternative
+
+Numbers auto-format: 1K, 1M, 1B`,
+
+    input_schema: {
+        type: 'object',
+        properties: {
+            chart: {
+                type: 'string',
+                enum: ['bar', 'line', 'area', 'composed', 'pie', 'scatter', 'radar', 'radialBar', 'funnel', 'treemap'],
+                description: 'Type of chart to create',
+            },
+            title: {
+                type: 'string',
+                description: 'Chart title',
+            },
+            description: {
+                type: 'string',
+                description: 'Optional description shown below the title',
+            },
+            data: {
+                type: 'array',
+                description: 'Array of data objects',
+                items: {
+                    type: 'object',
+                    additionalProperties: true,
+                },
+            },
+            xKey: {
+                type: 'string',
+                description: 'Field name to use for X-axis (for bar/line/area/composed/scatter)',
+            },
+            yKey: {
+                type: 'string',
+                description: 'Field name for Y values (for scatter charts)',
+            },
+            nameKey: {
+                type: 'string',
+                description: 'Field name for labels (for pie/funnel/radialBar/treemap, default: "name")',
+            },
+            valueKey: {
+                type: 'string',
+                description: 'Field name for values (for pie/funnel/radialBar, default: "value")',
+            },
+            axisKey: {
+                type: 'string',
+                description: 'Field name for radar axis labels',
+            },
+            dataKey: {
+                type: 'string',
+                description: 'Field name for treemap values',
+            },
+            series: {
+                type: 'array',
+                description: 'Array of series to plot (for bar/line/area/composed/radar)',
+                items: {
+                    type: 'object',
+                    properties: {
+                        key: {
+                            type: 'string',
+                            description: 'Field name in data',
+                        },
+                        label: {
+                            type: 'string',
+                            description: 'Display name',
+                        },
+                        type: {
+                            type: 'string',
+                            enum: ['bar', 'line', 'area'],
+                            description: 'Series type (for composed charts)',
+                        },
+                        color: {
+                            type: 'string',
+                            description: 'Hex color code',
+                        },
+                        yAxisId: {
+                            type: 'string',
+                            enum: ['left', 'right'],
+                            description: 'Which Y-axis to use',
+                        },
+                        dot: {
+                            type: 'boolean',
+                            description: 'Show dots on line (default: false)',
+                        },
+                    },
+                    required: ['key'],
+                },
+            },
+            yAxis: {
+                type: 'object',
+                description: 'Y-axis configuration',
+                properties: {
+                    left: {
+                        type: 'object',
+                        properties: {
+                            label: { type: 'string' },
+                        },
+                    },
+                    right: {
+                        type: 'object',
+                        properties: {
+                            label: { type: 'string' },
+                        },
+                    },
+                },
+            },
+            options: {
+                type: 'object',
+                description: 'Chart options',
+                properties: {
+                    stacked: {
+                        type: 'boolean',
+                        description: 'Stack bars/areas',
+                    },
+                    referenceZero: {
+                        type: 'boolean',
+                        description: 'Show reference line at y=0',
+                    },
+                    collapsible: {
+                        type: 'boolean',
+                        description: 'Allow user to collapse chart',
+                    },
+                    collapseInitially: {
+                        type: 'boolean',
+                        description: 'Start collapsed',
+                    },
+                    innerRadius: {
+                        type: 'number',
+                        description: 'Inner radius for donut/radialBar charts (0-100)',
+                    },
+                    showLabels: {
+                        type: 'boolean',
+                        description: 'Show value labels on pie/funnel',
+                    },
+                    startAngle: {
+                        type: 'number',
+                        description: 'Start angle for radialBar (default: 180)',
+                    },
+                    endAngle: {
+                        type: 'number',
+                        description: 'End angle for radialBar (default: 0)',
+                    },
+                },
+            },
+        },
+        required: ['chart', 'data'],
+    },
+};
+
+/**
+ * System prompt addition for chart capabilities.
+ * Include this in your agent's system prompt to enable chart creation.
+ */
+export const chartSystemPromptAddition = `
+# Chart Visualization Capability
+
+You can create interactive charts by including markdown code blocks with the language "chart".
+
+## Chart Types
+
+| Type | Use Case | Required Fields |
+|------|----------|-----------------|
+| bar | Category comparisons | xKey, series |
+| line | Trends over time | xKey, series |
+| area | Trends with volume | xKey, series |
+| composed | Mix bars + lines | xKey, series with type |
+| pie | Part-to-whole | nameKey, valueKey |
+| scatter | Correlation | xKey, yKey |
+| radar | Multi-dimensional | axisKey, series |
+| radialBar | Progress/gauges | nameKey, valueKey |
+| funnel | Conversion stages | nameKey, valueKey |
+| treemap | Hierarchical data | nameKey, dataKey |
+
+## Quick Examples
+
+Bar: \`{"chart":"bar","data":[{"x":"A","y":10}],"xKey":"x","series":[{"key":"y"}]}\`
+Pie: \`{"chart":"pie","data":[{"name":"A","value":60},{"name":"B","value":40}]}\`
+Scatter: \`{"chart":"scatter","data":[{"x":1,"y":2}],"xKey":"x","yKey":"y"}\`
+
+Use charts when:
+- User requests visualization
+- 3+ data points to display
+- Visual form clarifies comparisons/trends
+
+Colors: Blue #4f46e5 (primary), Green #22c55e (positive), Red #ef4444 (negative)
+`;
+
+/**
+ * Type-safe chart specification builder.
+ * Use this when you want to build charts programmatically.
+ */
+export function buildChartSpec(spec: AgentChartSpec): string {
+    // Validate the spec
+    if (!spec.chart || !spec.data || !spec.xKey || !spec.series) {
+        throw new Error('Invalid chart spec: missing required fields (chart, data, xKey, series)');
+    }
+
+    if (!Array.isArray(spec.data)) {
+        throw new Error('Invalid chart spec: data must be an array');
+    }
+
+    if (!Array.isArray(spec.series) || spec.series.length === 0) {
+        throw new Error('Invalid chart spec: series must be a non-empty array');
+    }
+
+    // Return as markdown code block
+    const json = JSON.stringify(spec, null, 2);
+    return `\`\`\`chart\n${json}\n\`\`\``;
+}
+
+/**
+ * Extract chart specifications from markdown text.
+ * Useful for parsing agent responses.
+ */
+export function extractChartSpecs(markdown: string): AgentChartSpec[] {
+    const chartBlockRegex = /```chart\s*\n([\s\S]*?)\n```/g;
+    const specs: AgentChartSpec[] = [];
+
+    let match;
+    while ((match = chartBlockRegex.exec(markdown)) !== null) {
+        try {
+            const spec = JSON.parse(match[1]) as AgentChartSpec;
+            specs.push(spec);
+        } catch (e) {
+            console.warn('Failed to parse chart spec:', e);
+        }
+    }
+
+    return specs;
+}

package/src/features/agent/examples.ts

@@ -0,0 +1,321 @@
+/**
+ * Chart creation examples for testing and reference.
+ *
+ * These examples demonstrate how to use the chart functionality
+ * from both AI agents and TypeScript code.
+ */
+
+import {
+    buildCashflowComposedChart,
+    buildPerformanceLineChart,
+    buildScenarioComparisonBarChart,
+    buildScenarioDeltaPercentChart,
+    buildNavLineChart,
+    toChartMarkdown,
+} from './visualization';
+
+/**
+ * Example 1: Simple bar chart (markdown)
+ */
+export const exampleBarChartMarkdown = `
+Here's a comparison of revenue across quarters:
+
+\`\`\`chart
+{
+  "version": "1.0",
+  "chart": "bar",
+  "title": "Quarterly Revenue",
+  "description": "Revenue performance by quarter",
+  "data": [
+    { "quarter": "Q1 2024", "revenue": 125000 },
+    { "quarter": "Q2 2024", "revenue": 145000 },
+    { "quarter": "Q3 2024", "revenue": 160000 },
+    { "quarter": "Q4 2024", "revenue": 180000 }
+  ],
+  "xKey": "quarter",
+  "series": [
+    {
+      "key": "revenue",
+      "label": "Revenue",
+      "type": "bar",
+      "color": "#4f46e5"
+    }
+  ],
+  "yAxis": {
+    "left": { "label": "Amount ($)" }
+  }
+}
+\`\`\`
+
+Revenue shows consistent growth throughout 2024.
+`;
+
+/**
+ * Example 2: Line chart with multiple series (markdown)
+ */
+export const exampleLineChartMarkdown = `
+Here's the fund performance over time:
+
+\`\`\`chart
+{
+  "version": "1.0",
+  "chart": "line",
+  "title": "Fund Performance Metrics",
+  "description": "TVPI, DPI, and RVPI over time",
+  "data": [
+    { "period": "2024-Q1", "tvpi": 1.2, "dpi": 0.3, "rvpi": 0.9 },
+    { "period": "2024-Q2", "tvpi": 1.4, "dpi": 0.5, "rvpi": 0.9 },
+    { "period": "2024-Q3", "tvpi": 1.6, "dpi": 0.7, "rvpi": 0.9 },
+    { "period": "2024-Q4", "tvpi": 1.8, "dpi": 0.9, "rvpi": 0.9 }
+  ],
+  "xKey": "period",
+  "series": [
+    {
+      "key": "tvpi",
+      "label": "TVPI",
+      "type": "line",
+      "color": "#4f46e5",
+      "dot": false
+    },
+    {
+      "key": "dpi",
+      "label": "DPI",
+      "type": "line",
+      "color": "#16a34a",
+      "dot": false
+    },
+    {
+      "key": "rvpi",
+      "label": "RVPI",
+      "type": "line",
+      "color": "#f59e0b",
+      "dot": false
+    }
+  ],
+  "yAxis": {
+    "left": { "label": "Multiple (x)" }
+  },
+  "options": {
+    "referenceZero": false
+  }
+}
+\`\`\`
+
+The fund shows strong performance with TVPI growing to 1.8x.
+`;
+
+/**
+ * Example 3: Composed chart with dual Y-axis (markdown)
+ */
+export const exampleComposedChartMarkdown = `
+Here's the cashflow analysis:
+
+\`\`\`chart
+{
+  "version": "1.0",
+  "chart": "composed",
+  "title": "Fund Cashflow Timeline",
+  "description": "Capital calls, distributions, and net cashflow",
+  "data": [
+    { "period": "2024-Q1", "calls": 2000000, "distributions": 500000, "net": -1500000 },
+    { "period": "2024-Q2", "calls": 1500000, "distributions": 800000, "net": -700000 },
+    { "period": "2024-Q3", "calls": 1000000, "distributions": 1200000, "net": 200000 },
+    { "period": "2024-Q4", "calls": 500000, "distributions": 1800000, "net": 1300000 }
+  ],
+  "xKey": "period",
+  "series": [
+    {
+      "key": "calls",
+      "label": "Capital Calls",
+      "type": "bar",
+      "color": "#ef4444"
+    },
+    {
+      "key": "distributions",
+      "label": "Distributions",
+      "type": "bar",
+      "color": "#22c55e"
+    },
+    {
+      "key": "net",
+      "label": "Net Cashflow",
+      "type": "line",
+      "color": "#0ea5e9",
+      "yAxisId": "right",
+      "dot": false
+    }
+  ],
+  "yAxis": {
+    "left": { "label": "Amount ($)" },
+    "right": { "label": "Net CF ($)" }
+  },
+  "options": {
+    "referenceZero": true
+  }
+}
+\`\`\`
+
+The fund transitions from net negative to net positive cashflow in Q3.
+`;
+
+/**
+ * Example 4: Using TypeScript builders
+ */
+export function generateCashflowChart() {
+    const chart = buildCashflowComposedChart({
+        title: 'Fund Cashflow Analysis',
+        description: 'Quarterly cashflows with net overlay',
+        rows: [
+            { period: '2024-Q1', calls: 2000000, distributions: 500000 },
+            { period: '2024-Q2', calls: 1500000, distributions: 800000 },
+            { period: '2024-Q3', calls: 1000000, distributions: 1200000 },
+            { period: '2024-Q4', calls: 500000, distributions: 1800000 },
+        ],
+        collapseInitially: false,
+    });
+
+    return toChartMarkdown(chart);
+}
+
+/**
+ * Example 5: Performance chart with TypeScript
+ */
+export function generatePerformanceChart() {
+    const chart = buildPerformanceLineChart({
+        title: 'Fund Performance',
+        description: 'TVPI, DPI, and RVPI over time',
+        rows: [
+            { period: '2024-Q1', tvpi: 1.2, dpi: 0.3, rvpi: 0.9 },
+            { period: '2024-Q2', tvpi: 1.4, dpi: 0.5, rvpi: 0.9 },
+            { period: '2024-Q3', tvpi: 1.6, dpi: 0.7, rvpi: 0.9 },
+            { period: '2024-Q4', tvpi: 1.8, dpi: 0.9, rvpi: 0.9 },
+        ],
+    });
+
+    return toChartMarkdown(chart);
+}
+
+/**
+ * Example 6: Scenario comparison
+ */
+export function generateScenarioComparisonChart() {
+    const chart = buildScenarioComparisonBarChart({
+        title: 'Base vs Optimistic Scenario',
+        leftLabel: 'Base Case',
+        rightLabel: 'Optimistic Case',
+        metrics: [
+            { label: 'Final TVPI', left: 2.5, right: 3.2 },
+            { label: 'IRR (%)', left: 18, right: 25 },
+            { label: 'Total Distributions ($M)', left: 125, right: 160 },
+        ],
+        description: 'Comparison of key metrics across scenarios',
+    });
+
+    return toChartMarkdown(chart);
+}
+
+/**
+ * Example 7: Delta percentage chart
+ */
+export function generateDeltaChart() {
+    const chart = buildScenarioDeltaPercentChart({
+        title: 'Performance vs Plan',
+        metrics: [
+            { label: 'Revenue', left: 1000000, right: 1200000 },
+            { label: 'EBITDA', left: 250000, right: 320000 },
+            { label: 'Net Income', left: 150000, right: 180000 },
+        ],
+        description: 'Percentage change from plan',
+    });
+
+    return toChartMarkdown(chart);
+}
+
+/**
+ * Example 8: NAV timeline
+ */
+export function generateNavChart() {
+    const chart = buildNavLineChart({
+        title: 'Fund NAV Over Time',
+        description: 'Net Asset Value progression',
+        rows: [
+            { period: '2024-Q1', nav: 10000000 },
+            { period: '2024-Q2', nav: 12000000 },
+            { period: '2024-Q3', nav: 15000000 },
+            { period: '2024-Q4', nav: 18000000 },
+        ],
+    });
+
+    return toChartMarkdown(chart);
+}
+
+/**
+ * Example 9: Complete agent response with chart
+ */
+export const exampleAgentResponseWithChart = `
+I've analyzed the fund performance for Q1-Q4 2024. Here are the key findings:
+
+## Performance Summary
+
+- **Final TVPI:** 1.8x
+- **Final DPI:** 0.9x
+- **Net Cashflow:** Positive since Q3
+
+## Visual Analysis
+
+${generatePerformanceChart()}
+
+## Cashflow Breakdown
+
+${generateCashflowChart()}
+
+## Recommendations
+
+1. The fund is performing well above industry benchmarks
+2. Cashflow turned positive in Q3, indicating maturity
+3. Consider planning distributions for Q1 2025
+
+Would you like me to run a Monte Carlo simulation to project future scenarios?
+`;
+
+/**
+ * Example 10: Error handling example
+ */
+export const exampleInvalidChart = `
+This will fall back to a code block because the JSON is invalid:
+
+\`\`\`chart
+{
+  "chart": "bar",
+  // Missing required fields
+  "title": "Invalid Chart"
+}
+\`\`\`
+
+The UI will render this as a regular code block.
+`;
+
+/**
+ * Test data generator for interactive testing
+ */
+export function generateTestData(periods: number) {
+    const data = [];
+
+    for (let i = 0; i < periods; i++) {
+        const quarter = Math.floor(i / 3) + 1;
+        const year = 2024 + Math.floor(i / 4);
+        const period = `${year}-Q${quarter}`;
+
+        data.push({
+            period,
+            tvpi: 1.0 + (i * 0.15) + (Math.random() * 0.1),
+            dpi: 0.2 + (i * 0.08) + (Math.random() * 0.05),
+            rvpi: 0.8 + (i * 0.07) + (Math.random() * 0.05),
+            calls: Math.floor(500000 + Math.random() * 1500000),
+            distributions: Math.floor(300000 + Math.random() * 2000000),
+            nav: Math.floor(5000000 + (i * 1000000) + (Math.random() * 500000)),
+        });
+    }
+
+    return data;
+}

package/src/features/agent/index.ts

@@ -1,2 +1,4 @@
 export * from "./chat";
 export * from "./PayloadBuilder";
+export * from "./visualization";
+export * from "./createChartTool";