sea-dev 1.0.0

package/libs/core/src/chat/tools/chart-agent.ts

@@ -0,0 +1,526 @@
+/**
+ * Deep Dive Agent
+ * Specializes in sandbox code execution and exploratory analysis
+ */
+
+import type { VercelConfig } from "@sea/config/vercel";
+import {
+  getConversation,
+  updateAgentConversation,
+} from "@sea/dal/conversation";
+import { memorySchema } from "@sea/db/schema";
+import type { Member } from "@sea/db/types";
+import { nanoid } from "@sea/util/id";
+import { Sandbox } from "@vercel/sandbox";
+import { tool, ToolLoopAgent, type LanguageModel } from "ai";
+import { z } from "zod/v4";
+import { createArtifact } from "./agent";
+import { getData } from "./submission";
+
+export interface ChartAgentConfig {
+  model: LanguageModel;
+  member: Member;
+  conversationId: string;
+  vercelConfig: VercelConfig;
+}
+
+const barLineBasePropsSchema = z
+  .object({
+    data: z.array(z.unknown()).min(1).optional(),
+    xField: z.string().optional(),
+    yField: z.string().optional(),
+    categories: z.array(z.unknown()).optional(),
+    series: z.array(z.unknown()).optional(),
+  })
+  .catchall(z.unknown());
+
+const barChartSchema = z
+  .object({
+    type: z.literal("BarChart"),
+    props: barLineBasePropsSchema.optional(),
+  })
+  .catchall(z.unknown())
+  .refine(
+    (config) => {
+      const props = config.props || config;
+      if (props.data && Array.isArray(props.data) && props.data.length > 0) {
+        return props.xField || props.yField || props.categories;
+      }
+      return props.categories || props.series;
+    },
+    {
+      message:
+        "BarChart: need either data array with xField/yField, or categories/series",
+    },
+  );
+
+const lineChartSchema = z
+  .object({
+    type: z.literal("LineChart"),
+    props: barLineBasePropsSchema.optional(),
+  })
+  .catchall(z.unknown())
+  .refine(
+    (config) => {
+      const props = config.props || config;
+      if (props.data && Array.isArray(props.data) && props.data.length > 0) {
+        return props.xField || props.yField || props.categories;
+      }
+      return props.categories || props.series;
+    },
+    {
+      message:
+        "LineChart: need either data array with xField/yField, or categories/series",
+    },
+  );
+
+const pieChartSchema = z
+  .object({
+    type: z.literal("PieChart"),
+    props: z
+      .object({
+        data: z.array(z.unknown()).min(1, {
+          message: "need non-empty data array with {name, value} objects",
+        }),
+      })
+      .catchall(z.unknown())
+      .optional(),
+  })
+  .catchall(z.unknown());
+
+const gaugeChartSchema = z
+  .object({
+    type: z.literal("GaugeChart"),
+    props: z
+      .object({
+        value: z.number({ message: "need numeric value property" }),
+      })
+      .catchall(z.unknown())
+      .optional(),
+  })
+  .catchall(z.unknown());
+
+const waterfallChartSchema = z
+  .object({
+    type: z.literal("WaterfallChart"),
+    props: z
+      .object({
+        items: z
+          .array(z.unknown())
+          .min(1, { message: "need non-empty items array" }),
+      })
+      .catchall(z.unknown())
+      .optional(),
+  })
+  .catchall(z.unknown());
+
+const heatmapChartSchema = z
+  .object({
+    type: z.literal("HeatmapChart"),
+    props: z
+      .object({
+        matrix: z
+          .array(z.array(z.unknown()))
+          .min(1, { message: "need non-empty matrix 2D array" }),
+        xLabels: z.array(z.unknown()),
+        yLabels: z.array(z.unknown()),
+      })
+      .catchall(z.unknown())
+      .optional(),
+  })
+  .catchall(z.unknown())
+  .refine(
+    (config) => {
+      const props = config.props || config;
+      return props.xLabels && props.yLabels;
+    },
+    {
+      message: "HeatmapChart: need xLabels and yLabels arrays",
+    },
+  );
+
+const bulletChartSchema = z
+  .object({
+    type: z.literal("BulletChart"),
+    props: z.object({}).catchall(z.unknown()).optional(),
+  })
+  .catchall(z.unknown());
+
+const metricCardSchema = z
+  .object({
+    type: z.literal("MetricCard"),
+    props: z.object({}).catchall(z.unknown()).optional(),
+  })
+  .catchall(z.unknown());
+
+const componentChartSchema = z.union([
+  barChartSchema,
+  lineChartSchema,
+  pieChartSchema,
+  gaugeChartSchema,
+  waterfallChartSchema,
+  heatmapChartSchema,
+  bulletChartSchema,
+  metricCardSchema,
+]);
+
+type ChartConfig =
+  | z.infer<typeof componentChartSchema>
+  | {
+      type: "Dashboard";
+      components: ChartConfig[];
+      [key: string]: unknown;
+    };
+
+const chartConfigSchema: z.ZodType<ChartConfig> = z.union([
+  z
+    .object({
+      type: z.literal("Dashboard"),
+      components: z
+        .array(z.lazy(() => chartConfigSchema))
+        .min(1, { message: "Dashboard components array is empty" }),
+    })
+    .catchall(z.unknown()),
+  componentChartSchema,
+]);
+
+export const chartSchema = chartConfigSchema;
+
+const tableColumnSchema = z
+  .object({
+    header: z.string({ message: "Column: missing or invalid header string" }),
+    field: z.string({ message: "Column: missing or invalid field string" }),
+    format: z
+      .enum(["currency", "percent", "date", "number"], {
+        message:
+          "Column: invalid format. Valid: currency, percent, date, number",
+      })
+      .optional(),
+  })
+  .catchall(z.unknown());
+
+const tableTreeConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    childrenField: z.string().optional(),
+  })
+  .catchall(z.unknown())
+  .refine(
+    (tree) => {
+      if (tree.enabled && !tree.childrenField) {
+        return false;
+      }
+      return true;
+    },
+    {
+      message: 'Tree config requires "childrenField" when enabled',
+    },
+  );
+
+const tableConfigSchema = z
+  .object({
+    columns: z
+      .array(tableColumnSchema)
+      .min(1, { message: "Table columns array is empty" }),
+    data: z.array(z.unknown()),
+    tree: tableTreeConfigSchema.optional(),
+    title: z.string().optional(),
+  })
+  .catchall(z.unknown());
+
+export const tableSchema = tableConfigSchema;
+
+export async function createChartAgent(config: ChartAgentConfig) {
+  const { model, member, conversationId, vercelConfig } = config;
+  const conversationResult = await getConversation({ member, conversationId });
+  if (!conversationResult.ok) {
+    throw new Error(conversationResult.error);
+  }
+  const conversation = conversationResult.data;
+  const sandbox = await Sandbox.create({
+    token: vercelConfig.token,
+    projectId: vercelConfig.projectId,
+    teamId: vercelConfig.teamId,
+    runtime: "python3.13",
+  });
+  await sandbox.runCommand({
+    cmd: "dnf",
+    args: ["install", "-y", "jq"],
+    sudo: true,
+  });
+
+  // // Track if Python is installed (lazy install)
+  // let pythonInstalled = false;
+  // async function ensurePython() {
+  //   if (pythonInstalled) return;
+  //   await sandbox.runCommand({
+  //     cmd: 'dnf',
+  //     args: ['install', '-y', 'python3', 'python3-pip'],
+  //     sudo: true,
+  //   });
+  //   await sandbox.runCommand({
+  //     cmd: 'pip3',
+  //     args: ['install', 'pandas', 'numpy', 'python-dateutil'],
+  //   });
+  //   pythonInstalled = true;
+  // }
+
+  const agent = new ToolLoopAgent({
+    model,
+    callOptionsSchema: z.object({
+      dealId: z.string().describe("The ID of the deal to create charts for"),
+      submissionIds: z
+        .array(z.string())
+        .describe("The IDs of submissions to visualize"),
+    }),
+    prepareCall: ({ options, ...settings }) => ({
+      ...settings,
+      instructions: `
+You are a charting specialist agent with access to an isolated environment where you can 
+- run Python code
+- run bash commands
+- run jq code to do calculations
+
+You are working on a specific deal and a specific set of submissions:
+
+Deal ID: ${options.dealId}
+Submission IDs: ${options.submissionIds.join(", ")}
+
+You should fetch the data about these specific submissions and use it to create charts and dashboards.
+Create artifacts to present findings and update progress for long-running tasks.
+
+General guidelines:
+- If you use your code tool and receive an error, fix the code and retry.
+- ALWAYS USE TOOLS FOR CALCULATIONS. NEVER compute numbers in your head - use jq for ALL math
+- IMPORTANT: When referencing specific data from submissions, include citation references using the format [citation:CITATION_ID] where CITATION_ID is the citationId field from the submission data. This allows users to click and view the source document.
+
+UNDERWRITING WORKFLOW:
+For business underwriting tasks:
+1. Use listScripts to discover analysis tools
+2. Use listPrompts to find analysis templates
+3. Categorize transactions with python (scripts/categorization/rules.py)
+4. Calculate metrics with python (scripts/ratios/*.py)
+5. Generate scores with python (scripts/scoring/credit_score.py)
+6. Output credit summary with renderMarkdown
+7. Visualize with renderChart
+
+Use updateProgress to track steps (first as in_progress, rest pending, update as you go).
+
+OUTPUT FORMATS:
+- Charts: renderChart with native ECharts config (see examples below)
+- Tables: renderTable for financial statements, transaction lists, tabular data
+- Analysis: renderMarkdown for credit summaries and reports
+- Dashboard: { "type": "Dashboard", "components": [...] }
+
+WHEN TO USE TABLE vs CHART:
+- Table: Financial statements, transaction lists, detailed data with many columns, data that needs sorting
+- Chart: Trends, comparisons, distributions, visual insights
+
+ECHARTS FORMAT EXAMPLES:
+
+Bar chart:
+{
+  "title": { "text": "Monthly Sales" },
+  "tooltip": { "trigger": "axis" },
+  "xAxis": { "type": "category", "data": ["Jan", "Feb", "Mar"] },
+  "yAxis": { "type": "value" },
+  "series": [{ "type": "bar", "data": [100, 200, 150] }]
+}
+
+Line chart:
+{
+  "title": { "text": "Trend" },
+  "xAxis": { "type": "category", "data": ["Q1", "Q2", "Q3"] },
+  "yAxis": { "type": "value" },
+  "series": [{ "type": "line", "data": [10, 20, 15], "smooth": true }]
+}
+
+Pie chart:
+{
+  "title": { "text": "Distribution" },
+  "series": [{ "type": "pie", "radius": "60%", "data": [{"name": "A", "value": 30}, {"name": "B", "value": 70}] }]
+}
+
+Use native ECharts format - do NOT use component types like "BarChart", "LineChart".
+`,
+      tools: {
+        bash: tool({
+          description:
+            "Run bash commands in the sandbox. Use for file operations (cat, echo >), exploration (ls, find), and shell scripting.",
+          inputSchema: z.object({ command: z.string() }),
+          execute: async ({ command }) => {
+            const result = await sandbox.runCommand({
+              cmd: "bash",
+              args: ["-c", command],
+            });
+            const stdout = await result.stdout();
+            const stderr = await result.stderr();
+
+            return stdout || stderr;
+          },
+        }),
+        jq: tool({
+          description: "Run jq code to do calculations.",
+          inputSchema: z.object({
+            cmd: z.string().describe(`
+The jq command to execute. Must be a valid jq expression.
+
+Examples:
+- Sum values: jq '[.[].amount] | add' {message: .commit.message, name: .commit.committer.name}
+- Group & count: jq 'group_by(.category) | map({category: .[0].category, count: length})' {category: message, name: name}
+- Filter: jq '.[] | select(.amount > 100)' {message: .commit.message, amount: 100} : '';
+`),
+          }),
+          execute: async ({ cmd }) => {
+            const result = await sandbox.runCommand({ cmd });
+            const stdout = await result.stdout();
+            const stderr = await result.stderr();
+
+            return {
+              output: stdout,
+              error: stderr,
+              success: result.exitCode === 0,
+              sandboxId: sandbox.sandboxId,
+            };
+          },
+        }),
+        getData: getData({ member, submissionIds: options.submissionIds }),
+        renderChart: tool({
+          description:
+            "Render a chart or dashboard to the user. If the config is invalid, an error will be returned - fix the config and retry.",
+          inputSchema: z.object({
+            config: chartConfigSchema.describe("Chart configuration object"),
+          }),
+          execute: async (input) => {
+            const memory = memorySchema.parse(conversation.memory);
+            const artifact = {
+              id: nanoid(),
+              type: "chart",
+              title: "Chart",
+              content: JSON.stringify(input.config),
+              createdAt: new Date().toISOString(),
+            };
+            const updatedMemory = {
+              ...memory,
+              artifacts: [...memory.artifacts, artifact],
+            };
+            await updateAgentConversation({
+              member,
+              conversationId,
+              memory: updatedMemory,
+            });
+
+            return { rendered: true, type: input.config.type };
+          },
+        }),
+        renderTable: tool({
+          description:
+            "Render a data table. Use for financial statements, transaction lists, or any tabular data that benefits from sorting and detailed viewing.",
+          inputSchema: z.object({
+            config: tableConfigSchema.describe(
+              "Table configuration with columns and data",
+            ),
+          }),
+          execute: async (input) => {
+            const memory = memorySchema.parse(conversation.memory);
+            const artifact = {
+              id: nanoid(),
+              type: "table",
+              title: input.config.title,
+              content: JSON.stringify(input.config),
+              createdAt: new Date().toISOString(),
+            };
+            const updatedMemory = {
+              ...memory,
+              artifacts: [...memory.artifacts, artifact],
+            };
+            await updateAgentConversation({
+              member,
+              conversationId,
+              memory: updatedMemory,
+            });
+
+            return { rendered: true, type: "table" };
+          },
+        }),
+        renderMarkdown: tool({
+          description:
+            "Render a markdown document as an artifact. Use for credit summaries, analysis reports, and other formatted text output.",
+          inputSchema: z.object({
+            title: z.string().describe("Title of the document"),
+            content: z.string().describe("Markdown content"),
+            metadata: z
+              .object({
+                type: z
+                  .enum(["credit_summary", "analysis", "report"])
+                  .optional()
+                  .describe("Type of document"),
+                score: z
+                  .number()
+                  .optional()
+                  .describe("Overall score if applicable"),
+                recommendation: z
+                  .string()
+                  .optional()
+                  .describe(
+                    "Recommendation (APPROVE, CONDITIONAL, REVIEW, DECLINE)",
+                  ),
+              })
+              .optional()
+              .describe("Optional metadata for the document"),
+          }),
+          execute: async ({ title, content, metadata }) => {
+            const memory = memorySchema.parse(conversation.memory);
+            const artifact = {
+              id: nanoid(),
+              type: "markdown",
+              title,
+              content: JSON.stringify({ content, metadata: metadata || {} }),
+              createdAt: new Date().toISOString(),
+            };
+            const updatedMemory = {
+              ...memory,
+              artifacts: [...memory.artifacts, artifact],
+            };
+            await updateAgentConversation({
+              member,
+              conversationId,
+              memory: updatedMemory,
+            });
+            return { rendered: true, type: "markdown", title };
+          },
+        }),
+        setChartTheme: tool({
+          description: "Change the visual theme for all charts.",
+          inputSchema: z.object({
+            theme: z.enum(["dark", "light"]),
+            customColors: z
+              .object({
+                primary: z.string().optional(),
+                background: z.string().optional(),
+                foreground: z.string().optional(),
+                chartColors: z.array(z.string()).optional(),
+              })
+              .optional(),
+          }),
+          execute: async ({ theme, customColors }) => {
+            return { updated: true, theme, customColors: customColors || null };
+          },
+        }),
+        createArtifact: createArtifact({ member, conversationId }),
+      },
+    }),
+  });
+
+  return {
+    agent,
+    conversation,
+    cleanup: async () => {
+      try {
+        await sandbox.stop();
+      } catch (err) {
+        console.error(`Failed to stop sandbox ${sandbox.sandboxId}:`, err);
+      }
+    },
+  };
+}

package/libs/core/src/chat/tools/chart-helpers/sandbox.ts

@@ -0,0 +1,47 @@
+/**
+ * List available scripts in sandbox
+ */
+export function listAvailableScripts(): {
+  path: string;
+  description: string;
+}[] {
+  return [
+    {
+      path: "scripts/categorization/rules.py",
+      description:
+        "Categorize bank transactions by type (revenue, payroll, rent, etc.)",
+    },
+    {
+      path: "scripts/ratios/liquidity.py",
+      description: "Calculate liquidity ratios (current, quick, cash ratio)",
+    },
+    {
+      path: "scripts/ratios/cashflow.py",
+      description: "Analyze cash flow patterns and burn rate",
+    },
+    {
+      path: "scripts/scoring/credit_score.py",
+      description: "Calculate credit score and recommendation",
+    },
+  ];
+}
+
+/**
+ * List available prompt templates
+ */
+export function listAvailablePrompts(): {
+  path: string;
+  description: string;
+}[] {
+  return [
+    {
+      path: "prompts/credit_summary.md",
+      description:
+        "Template for credit analysis summary with sections for financials, risks, and recommendation",
+    },
+    {
+      path: "prompts/underwriting_guidelines.md",
+      description: "Guidelines for evaluating asset-light businesses",
+    },
+  ];
+}

package/libs/core/src/chat/tools/chart.ts

@@ -0,0 +1,86 @@
+import { createChartAgent } from "./chart-agent";
+import type { VercelConfig } from "@sea/config/vercel";
+import { persistMessages } from "@sea/dal/conversation";
+import type { Member } from "@sea/db/types";
+import { nanoid } from "@sea/util/id";
+import type { LanguageModel, UIMessage, UIMessageStreamWriter } from "ai";
+import { convertToModelMessages, tool } from "ai";
+import * as z from "zod/v4";
+
+export function chartAgent({
+  member,
+  conversationId,
+  vercelConfig,
+  model,
+  writer,
+}: {
+  member: Member;
+  conversationId: string;
+  vercelConfig: VercelConfig;
+  model: LanguageModel;
+  writer?: UIMessageStreamWriter;
+}) {
+  return tool({
+    description:
+      "Delegate to a charting specialist agent. Use for: creating charts and dashboards.",
+    inputSchema: z.object({
+      task: z.string()
+        .describe(`Clear description of the charting task. Try to include specific details about the chart or dashboard you want to create, such as the type of chart,
+the data to include, and the formatting.
+
+Example:
+- Create a dashboard with a pie chart showing the distribution of submissions by status.
+- Create a line chart showing the trend of submissions over time.
+- Create a bar chart showing the top 5 submissions by value.
+- Create a table showing the submissions by status.
+- Create a dashboard with a heatmap showing the distribution of submissions by status.
+`),
+      dealId: z
+        .string()
+        .describe("The ID of the deal to create the chart for."),
+      submissionIds: z
+        .array(z.string())
+        .describe(
+          "The IDs of the submissions to create the chart or charts for.",
+        ),
+    }),
+    execute: async ({ task, dealId, submissionIds }) => {
+      const { agent, cleanup, conversation } = await createChartAgent({
+        model,
+        member,
+        conversationId,
+        vercelConfig,
+      });
+      try {
+        const modelMessages = await convertToModelMessages(
+          conversation.messages as UIMessage[],
+        );
+        const result = await agent.stream({
+          messages: [...modelMessages, { role: "user", content: task }],
+          options: { dealId, submissionIds },
+        });
+
+        if (writer) {
+          const outputStream = result.toUIMessageStream({
+            generateMessageId: nanoid,
+            onFinish: ({ messages }) => {
+              persistMessages({ member, conversationId, messages });
+            },
+          });
+          for await (const chunk of outputStream) {
+            writer.write(chunk);
+          }
+        }
+
+        return {
+          ok: true,
+          result: "Chart created successfully.",
+        };
+      } catch (err) {
+        return { ok: false, error: String(err) };
+      } finally {
+        await cleanup();
+      }
+    },
+  });
+}