sea-dev 1.0.0

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

@@ -0,0 +1,1435 @@
+import { createCreditAgent } from "./credit-agent";
+import type { VercelConfig } from "@sea/config/vercel";
+import { getDenormSubmission, type DenormGroup } from "@sea/dal/submission";
+import { db, schema } from "@sea/db";
+import { memorySchema } from "@sea/db/schema";
+import type { Member } from "@sea/db/types";
+import { invariant } from "@sea/util/invariant";
+import type { LanguageModel, UIMessageStreamWriter } from "ai";
+import { tool } from "ai";
+import { and, eq, isNull } from "drizzle-orm";
+import * as z from "zod/v4";
+import { returnErr } from "./helpers";
+
+/**
+ * Credit Analysis Tool for calculating DSCR and assessing creditworthiness
+ *
+ * This tool is designed to work with credit evaluation forms that contain:
+ * - Credit bureau data (with credit lines and estimated payments)
+ * - Financial statements (with EBITDA, interest expense, current portion of LT debt)
+ * - Legal bureau reports (litigation information)
+ */
+
+const DSCRCalculationSchema = z.object({
+  submissionId: z
+    .string()
+    .optional()
+    .describe(
+      "The submission ID containing the credit evaluation data. If not provided, will use the most recent submission from conversation memory.",
+    ),
+});
+
+export interface DSCRResult {
+  financialStatementDSCR: {
+    ebitda: number | null;
+    interestExpense: number | null;
+    currentPortionDebt: number | null;
+    dscr: number | null;
+    formula: string;
+    interpretation: string;
+  };
+  creditBureauDSCR: {
+    ebitda: number | null;
+    estimatedMonthlyPayments: number | null;
+    annualizedPayments: number | null;
+    dscr: number | null;
+    formula: string;
+    interpretation: string;
+  };
+  triangulation: {
+    comparison: string;
+    recommendation: string;
+    riskFactors: string[];
+  };
+}
+
+export function calculateDSCR({
+  member,
+  conversationId,
+}: {
+  member: Member;
+  conversationId: string;
+}) {
+  return tool({
+    description: `Calculate Debt Service Coverage Ratio (DSCR) using both financial statement and credit bureau methods.
+
+    DSCR measures a company's ability to service its debt obligations. Higher is better.
+    - Above 1.25: Good coverage
+    - 1.0-1.25: Adequate but tight
+    - Below 1.0: Cannot cover debt obligations
+
+    This tool will:
+    1. Calculate DSCR from financial statements: EBITDA / (Interest Expense + Current Portion of LT Debt)
+    2. Calculate DSCR from credit bureau: EBITDA / (Estimated Annual Payments on all credit lines)
+    3. Compare the two methods and identify discrepancies
+    4. Highlight risk factors from legal reports and payment history
+
+    If no submissionId is provided, will automatically use the most recent submission in your conversation memory.
+    `,
+    inputSchema: DSCRCalculationSchema,
+    execute: async ({
+      submissionId: providedSubmissionId,
+    }): Promise<{ ok: boolean; data?: DSCRResult; error?: string }> => {
+      try {
+        // Auto-detect submission from conversation memory if not provided
+        let submissionId = providedSubmissionId;
+
+        if (!submissionId) {
+          console.log(
+            "[calculateDSCR] No submissionId provided, checking conversation memory",
+          );
+          const conversation = await db.query.conversation.findFirst({
+            where: and(
+              eq(schema.conversation.id, conversationId),
+              eq(schema.conversation.organizationId, member.organizationId),
+            ),
+            columns: { memory: true },
+          });
+
+          if (conversation?.memory) {
+            const memory = memorySchema.parse(conversation.memory);
+            if (memory.submissionIds.length > 0) {
+              // Use the most recent submission
+              submissionId =
+                memory.submissionIds[memory.submissionIds.length - 1];
+              console.log(
+                `[calculateDSCR] Auto-detected submission from memory: ${submissionId}`,
+              );
+            } else {
+              return {
+                ok: false,
+                error:
+                  "No submission ID provided and no submissions found in conversation memory. Please provide a submissionId or work with a submission first.",
+              };
+            }
+          } else {
+            return {
+              ok: false,
+              error:
+                "No submission ID provided and conversation has no memory. Please provide a submissionId.",
+            };
+          }
+        }
+
+        // At this point submissionId is guaranteed to be defined
+        if (!submissionId) {
+          throw new Error("Submission ID could not be determined");
+        }
+
+        const submission = await getDenormSubmission({
+          member,
+          submissionId,
+          withCitations: true,
+          withTransformations: true,
+        });
+
+        // Debug: Log submission structure
+        console.log("[calculateDSCR] Analyzing submission:", {
+          submissionId,
+          submissionName: submission.name,
+          formName: submission.formName,
+          groupCount: submission.groups.length,
+          tableCount: submission.tables?.length || 0,
+        });
+
+        console.log(
+          "[calculateDSCR] Single groups:",
+          submission.groups.map((g) => g.name),
+        );
+        console.log(
+          "[calculateDSCR] Multi-group tables:",
+          submission.tables?.map((t) => ({
+            name: t.name,
+            rows: t.rows?.length || 0,
+          })),
+        );
+
+        // IMPORTANT: Financial statements are multi-groups, so they're in submission.tables, not submission.groups!
+        // 1. Find financial statement table (look for table with EBITDA column)
+        const financialTable = submission.tables?.find(
+          (t) =>
+            t.name.toLowerCase().includes("financial") &&
+            t.columns?.some((col) => col.toLowerCase().includes("ebitda")),
+        );
+
+        // 2. Find the most recent row by looking at "Period End Date"
+        let financialStmtLatest = null;
+        let latestDate: Date | null = null;
+
+        if (financialTable?.rows) {
+          console.log(
+            `[calculateDSCR] Found financial table "${financialTable.name}" with ${financialTable.rows.length} rows`,
+          );
+
+          for (const row of financialTable.rows) {
+            const periodEndDateItem = row.items?.find(
+              (item) =>
+                item.name.toLowerCase().includes("period") &&
+                item.name.toLowerCase().includes("date"),
+            );
+
+            if (periodEndDateItem?.value) {
+              const dateValue = new Date(periodEndDateItem.value as string);
+              if (
+                !isNaN(dateValue.getTime()) &&
+                (!latestDate || dateValue > latestDate)
+              ) {
+                latestDate = dateValue;
+                // Convert row to group-like structure for extractMoneyValue
+                financialStmtLatest = {
+                  name: financialTable.name,
+                  items: row.items,
+                };
+              }
+            }
+          }
+
+          // Fallback: use first row if no valid dates found
+          if (
+            !financialStmtLatest &&
+            financialTable.rows.length > 0 &&
+            financialTable.rows[0]?.items
+          ) {
+            financialStmtLatest = {
+              name: financialTable.name,
+              items: financialTable.rows[0].items,
+            };
+            console.log(
+              "[calculateDSCR] No valid dates found, using first row",
+            );
+          }
+        }
+
+        // Find single groups (credit bureau, legal, etc.)
+        const creditBureauGroup = submission.groups.find(
+          (g) =>
+            g.name.toLowerCase().includes("credit bureau") ||
+            g.name.toLowerCase().includes("bureau data"),
+        );
+
+        const creditLinesTable = submission.tables?.find(
+          (t) =>
+            t.name.toLowerCase().includes("credit lines") ||
+            t.name.toLowerCase().includes("credit facilities"),
+        );
+
+        const legalBureauGroup = submission.groups.find(
+          (g) =>
+            g.name.toLowerCase().includes("legal") &&
+            g.name.toLowerCase().includes("bureau"),
+        );
+
+        // Debug: log what was found
+        console.log("[calculateDSCR] Matched data sources:", {
+          financialStmtLatest: financialStmtLatest?.name,
+          financialStmtLatestDate: latestDate?.toISOString(),
+          creditBureauGroup: creditBureauGroup?.name,
+          creditLinesTable: creditLinesTable?.name,
+          legalBureauGroup: legalBureauGroup?.name,
+        });
+
+        // Extract financial statement data from the most recent row
+        const ebitda = extractMoneyValue(financialStmtLatest, "ebitda");
+        const interestExpense = extractMoneyValue(
+          financialStmtLatest,
+          "interest",
+        );
+        const currentPortionDebt = extractMoneyValue(
+          financialStmtLatest,
+          "current portion",
+        );
+
+        // Debug: log extracted values
+        console.log("[calculateDSCR] Extracted financial values:", {
+          ebitda,
+          interestExpense,
+          currentPortionDebt,
+          financialGroupItems: financialStmtLatest?.items?.map((i) => ({
+            name: i.name,
+            value: i.value,
+          })),
+        });
+
+        // Calculate financial statement DSCR
+        let fsDebtService: number | null = null;
+        let fsDSCR: number | null = null;
+        if (interestExpense !== null && currentPortionDebt !== null) {
+          fsDebtService = interestExpense + currentPortionDebt;
+          if (ebitda !== null && fsDebtService > 0) {
+            fsDSCR = ebitda / fsDebtService;
+          }
+        }
+
+        const fsInterpretation =
+          fsDSCR !== null
+            ? fsDSCR >= 1.25
+              ? "Good - Strong debt coverage"
+              : fsDSCR >= 1.0
+                ? "Adequate - Tight but can cover obligations"
+                : "Poor - Cannot cover debt obligations"
+            : "Insufficient data to calculate";
+
+        // Extract credit bureau data
+        const estimatedMonthlyPayments = extractMoneyValue(
+          creditBureauGroup,
+          "estimated total monthly",
+        );
+        const annualizedPayments =
+          estimatedMonthlyPayments !== null
+            ? estimatedMonthlyPayments * 12
+            : null;
+
+        // Calculate credit bureau DSCR
+        let cbDSCR: number | null = null;
+        if (
+          ebitda !== null &&
+          annualizedPayments !== null &&
+          annualizedPayments > 0
+        ) {
+          cbDSCR = ebitda / annualizedPayments;
+        }
+
+        const cbInterpretation =
+          cbDSCR !== null
+            ? cbDSCR >= 1.25
+              ? "Good - Strong debt coverage based on bureau data"
+              : cbDSCR >= 1.0
+                ? "Adequate - Tight coverage based on bureau data"
+                : "Poor - Cannot cover obligations per bureau data"
+            : "Insufficient credit bureau data to calculate";
+
+        // Triangulation and risk factors
+        const riskFactors: string[] = [];
+
+        // Check for discrepancies between methods
+        let comparison = "";
+        if (fsDSCR !== null && cbDSCR !== null) {
+          const diff = Math.abs(fsDSCR - cbDSCR);
+          const diffPct = (diff / Math.max(fsDSCR, cbDSCR)) * 100;
+
+          if (diffPct > 20) {
+            comparison = `SIGNIFICANT DISCREPANCY: Financial statement DSCR (${fsDSCR.toFixed(2)}) and credit bureau DSCR (${cbDSCR.toFixed(2)}) differ by ${diffPct.toFixed(1)}%. This warrants investigation.`;
+            riskFactors.push(
+              "Large discrepancy between DSCR calculation methods",
+            );
+          } else {
+            comparison = `ALIGNED: Both methods show similar DSCR (FS: ${fsDSCR.toFixed(2)}, CB: ${cbDSCR.toFixed(2)})`;
+          }
+        } else if (fsDSCR !== null) {
+          comparison = "Only financial statement DSCR available";
+        } else if (cbDSCR !== null) {
+          comparison = "Only credit bureau DSCR available";
+        } else {
+          comparison =
+            "Insufficient data to calculate DSCR using either method";
+        }
+
+        // Check payment delinquencies
+        const delinquencies = extractStringValue(
+          creditBureauGroup,
+          "delinquencies",
+        );
+        if (delinquencies && delinquencies.toLowerCase().includes("late")) {
+          riskFactors.push(`Payment issues: ${delinquencies}`);
+        }
+
+        // Check litigation
+        const litigationCount = extractNumberValue(
+          legalBureauGroup,
+          "litigation count",
+        );
+        const litigationSummary = extractStringValue(
+          legalBureauGroup,
+          "litigation summary",
+        );
+        if (litigationCount && litigationCount > 0) {
+          riskFactors.push(`${litigationCount} active litigation case(s)`);
+        }
+        if (litigationSummary) {
+          riskFactors.push(`Legal exposure: ${litigationSummary}`);
+        }
+
+        // Generate recommendation
+        let recommendation = "";
+        const worstDSCR =
+          fsDSCR !== null && cbDSCR !== null
+            ? Math.min(fsDSCR, cbDSCR)
+            : (fsDSCR ?? cbDSCR);
+
+        if (worstDSCR !== null) {
+          if (worstDSCR >= 1.25 && riskFactors.length === 0) {
+            recommendation =
+              "APPROVE: Strong debt coverage with no significant risk factors";
+          } else if (worstDSCR >= 1.0) {
+            recommendation = `REVIEW: Adequate coverage but ${riskFactors.length > 0 ? "risk factors present" : "tight margin"}. Consider additional analysis.`;
+          } else {
+            recommendation =
+              "DECLINE: Cannot adequately cover debt obligations";
+          }
+        } else {
+          recommendation =
+            "INSUFFICIENT DATA: Cannot make credit recommendation";
+        }
+
+        if (riskFactors.length > 0) {
+          recommendation += ` Note: ${riskFactors.length} risk factor(s) identified.`;
+        }
+
+        const result: DSCRResult = {
+          financialStatementDSCR: {
+            ebitda,
+            interestExpense,
+            currentPortionDebt,
+            dscr: fsDSCR,
+            formula: "EBITDA / (Interest Expense + Current Portion of LT Debt)",
+            interpretation: fsInterpretation,
+          },
+          creditBureauDSCR: {
+            ebitda,
+            estimatedMonthlyPayments,
+            annualizedPayments,
+            dscr: cbDSCR,
+            formula: "EBITDA / (Estimated Annual Payments on all credit lines)",
+            interpretation: cbInterpretation,
+          },
+          triangulation: {
+            comparison,
+            recommendation,
+            riskFactors,
+          },
+        };
+
+        return { ok: true, data: result };
+      } catch (err) {
+        return {
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      }
+    },
+  });
+}
+
+// Helper functions to extract values from submission groups
+type GroupLike = {
+  name: string;
+  items?: DenormGroup["items"];
+};
+
+function extractMoneyValue(
+  group: GroupLike | null | undefined,
+  fieldNamePattern: string,
+): number | null {
+  if (!group) {
+    console.log(
+      `[extractMoneyValue] No group provided for pattern: ${fieldNamePattern}`,
+    );
+    return null;
+  }
+
+  if (!group.items) {
+    console.log(`[extractMoneyValue] Group "${group.name}" has no items`);
+    return null;
+  }
+
+  const field = group.items.find((item) =>
+    item.name.toLowerCase().includes(fieldNamePattern.toLowerCase()),
+  );
+
+  if (!field) {
+    console.log(
+      `[extractMoneyValue] No field matching pattern "${fieldNamePattern}" in group "${group.name}". Available fields:`,
+      group.items.map((i) => i.name),
+    );
+    return null;
+  }
+
+  if (field.value === null || field.value === undefined) {
+    console.log(
+      `[extractMoneyValue] Field "${field.name}" has null/undefined value`,
+    );
+    return null;
+  }
+
+  // Handle different money value formats
+  const value = field.value as { amount?: number; currency?: string } | number;
+
+  console.log(
+    `[extractMoneyValue] Found field "${field.name}" with value:`,
+    value,
+  );
+
+  if (typeof value === "number") return value;
+  if (typeof value === "object" && value !== null && "amount" in value)
+    return value.amount ?? null;
+
+  console.log(
+    `[extractMoneyValue] Could not parse value format for field "${field.name}":`,
+    typeof value,
+  );
+  return null;
+}
+
+function extractNumberValue(
+  group: GroupLike | null | undefined,
+  fieldNamePattern: string,
+): number | null {
+  if (!group || !group.items) return null;
+
+  const field = group.items.find((item) =>
+    item.name.toLowerCase().includes(fieldNamePattern.toLowerCase()),
+  );
+
+  if (!field || field.value === null) return null;
+  return typeof field.value === "number" ? field.value : null;
+}
+
+function extractStringValue(
+  group: GroupLike | null | undefined,
+  fieldNamePattern: string,
+): string | null {
+  if (!group || !group.items) return null;
+
+  const field = group.items.find((item) =>
+    item.name.toLowerCase().includes(fieldNamePattern.toLowerCase()),
+  );
+
+  if (!field || field.value === null) return null;
+  return typeof field.value === "string" ? field.value : null;
+}
+
+/**
+ * Cross-Reference Verification Tool
+ * Verifies that values in different locations of a submission match or reconcile correctly
+ */
+export function verifyAccountReconciliation({ member }: { member: Member }) {
+  return tool({
+    description:
+      "Verify that a value in one location matches or reconciles with values in other locations. Use this to catch inconsistencies like 'Security deposit is £50k in Balance Sheet but £45k in Note 7'",
+    inputSchema: z.object({
+      submissionId: z.string(),
+      primaryLocation: z.object({
+        groupOrTableName: z
+          .string()
+          .describe("Name of the group or table containing the primary value"),
+        fieldName: z.string().describe("Name of the field to check"),
+      }),
+      referenceLocations: z.array(
+        z.object({
+          groupOrTableName: z
+            .string()
+            .describe(
+              "Name of the group or table containing the reference value",
+            ),
+          fieldName: z
+            .string()
+            .describe("Name of the field to compare against"),
+        }),
+      ),
+      expectedRelationship: z
+        .enum(["equal", "sum_to", "difference"])
+        .optional()
+        .describe(
+          "Expected relationship between values: 'equal' = should match exactly, 'sum_to' = references should sum to primary, 'difference' = primary minus references should equal zero",
+        ),
+    }),
+    execute: async ({
+      submissionId,
+      primaryLocation,
+      referenceLocations,
+      expectedRelationship,
+    }) => {
+      try {
+        const submission = await getDenormSubmission({
+          member,
+          submissionId,
+          withCitations: true,
+          withTransformations: true,
+        });
+
+        // Find primary value
+        const primaryGroup =
+          submission.groups.find((g) =>
+            g.name
+              .toLowerCase()
+              .includes(primaryLocation.groupOrTableName.toLowerCase()),
+          ) ||
+          submission.tables?.find((t) =>
+            t.name
+              .toLowerCase()
+              .includes(primaryLocation.groupOrTableName.toLowerCase()),
+          );
+
+        if (!primaryGroup) {
+          return {
+            ok: false,
+            error: `Primary location "${primaryLocation.groupOrTableName}" not found`,
+          };
+        }
+
+        const primaryValue = extractMoneyValue(
+          primaryGroup,
+          primaryLocation.fieldName,
+        );
+
+        if (primaryValue === null) {
+          return {
+            ok: false,
+            error: `Primary field "${primaryLocation.fieldName}" not found or has no value`,
+          };
+        }
+
+        // Find reference values
+        const referenceValues: Array<{
+          location: string;
+          field: string;
+          value: number | null;
+        }> = [];
+
+        for (const refLoc of referenceLocations) {
+          const refGroup =
+            submission.groups.find((g) =>
+              g.name
+                .toLowerCase()
+                .includes(refLoc.groupOrTableName.toLowerCase()),
+            ) ||
+            submission.tables?.find((t) =>
+              t.name
+                .toLowerCase()
+                .includes(refLoc.groupOrTableName.toLowerCase()),
+            );
+
+          if (!refGroup) {
+            referenceValues.push({
+              location: refLoc.groupOrTableName,
+              field: refLoc.fieldName,
+              value: null,
+            });
+            continue;
+          }
+
+          const refValue = extractMoneyValue(refGroup, refLoc.fieldName);
+          referenceValues.push({
+            location: refLoc.groupOrTableName,
+            field: refLoc.fieldName,
+            value: refValue,
+          });
+        }
+
+        // Perform reconciliation check
+        const relationship = expectedRelationship || "equal";
+        let reconciles = false;
+        let details = "";
+
+        if (relationship === "equal") {
+          reconciles = referenceValues.every(
+            (ref) => ref.value === primaryValue,
+          );
+          details = `Primary value: ${primaryValue}. Reference values: ${referenceValues.map((r) => `${r.location}.${r.field} = ${r.value}`).join(", ")}`;
+        } else if (relationship === "sum_to") {
+          const sum = referenceValues.reduce(
+            (acc, ref) => acc + (ref.value || 0),
+            0,
+          );
+          reconciles = Math.abs(sum - primaryValue) < 0.01; // Allow for rounding
+          details = `Primary value: ${primaryValue}. Sum of references: ${sum}. Difference: ${Math.abs(sum - primaryValue)}`;
+        } else if (relationship === "difference") {
+          const sum = referenceValues.reduce(
+            (acc, ref) => acc + (ref.value || 0),
+            0,
+          );
+          reconciles = Math.abs(primaryValue - sum) < 0.01;
+          details = `Primary value: ${primaryValue}. Sum of references: ${sum}. Difference: ${primaryValue - sum}`;
+        }
+
+        return {
+          ok: true,
+          data: {
+            reconciles,
+            primaryValue,
+            referenceValues,
+            relationship,
+            details,
+            discrepancy: reconciles
+              ? null
+              : "Values do not reconcile as expected",
+          },
+        };
+      } catch (err) {
+        return returnErr(err);
+      }
+    },
+  });
+}
+
+/**
+ * Financial Ratio Calculator Tool
+ * Calculates financial metrics and verifies they match stated values
+ */
+export function calculateFinancialMetric({ member }: { member: Member }) {
+  return tool({
+    description:
+      "Calculate financial metrics like DSO (Days Sales Outstanding), current ratio, depreciation, or verify formulas match stated policies. Use to catch errors like 'DSO calculation doesn't match'",
+    inputSchema: z.object({
+      submissionId: z.string(),
+      metric: z.enum([
+        "dso",
+        "current_ratio",
+        "quick_ratio",
+        "depreciation",
+        "amortization",
+        "debt_to_equity",
+        "working_capital",
+      ]),
+      inputs: z
+        .record(z.string(), z.number())
+        .optional()
+        .describe(
+          "Override inputs if needed (e.g., {revenue: 1000000, receivables: 120000})",
+        ),
+      periodDays: z
+        .number()
+        .optional()
+        .describe("Number of days in period for DSO calculation (default 365)"),
+    }),
+    execute: async ({ submissionId, metric, inputs, periodDays }) => {
+      try {
+        const submission = await getDenormSubmission({
+          member,
+          submissionId,
+          withCitations: true,
+          withTransformations: true,
+        });
+
+        let calculatedValue: number | null = null;
+        let formula = "";
+        let inputsUsed: Record<string, number | null> = {};
+        let statedValue: number | null = null;
+
+        // Find financial statement data (most recent period)
+        const financialTable = submission.tables?.find(
+          (t) =>
+            t.name.toLowerCase().includes("financial") ||
+            t.name.toLowerCase().includes("balance sheet") ||
+            t.name.toLowerCase().includes("p&l") ||
+            t.name.toLowerCase().includes("profit and loss"),
+        );
+
+        let latestFinancialRow = null;
+        if (financialTable?.rows && financialTable.rows.length > 0) {
+          // Use most recent period (first row, or find by date)
+          latestFinancialRow = {
+            name: financialTable.name,
+            items: financialTable.rows[0]?.items,
+          };
+        }
+
+        switch (metric) {
+          case "dso": {
+            const revenue =
+              inputs?.revenue ??
+              extractMoneyValue(latestFinancialRow, "revenue");
+            const receivables =
+              inputs?.receivables ??
+              extractMoneyValue(latestFinancialRow, "receivables") ??
+              extractMoneyValue(latestFinancialRow, "accounts receivable");
+            const days = periodDays || 365;
+
+            inputsUsed = { revenue, receivables, days };
+
+            if (revenue !== null && receivables !== null && revenue > 0) {
+              calculatedValue = (receivables / revenue) * days;
+              formula = `(Receivables / Revenue) × ${days} days`;
+            }
+
+            // Try to find stated DSO value
+            const notesGroup = submission.groups.find((g) =>
+              g.name.toLowerCase().includes("note"),
+            );
+            if (notesGroup) {
+              statedValue =
+                extractNumberValue(notesGroup, "dso") ??
+                extractNumberValue(notesGroup, "days sales");
+            }
+            break;
+          }
+
+          case "current_ratio": {
+            const currentAssets =
+              inputs?.currentAssets ??
+              extractMoneyValue(latestFinancialRow, "current assets");
+            const currentLiabilities =
+              inputs?.currentLiabilities ??
+              extractMoneyValue(latestFinancialRow, "current liabilities");
+
+            inputsUsed = { currentAssets, currentLiabilities };
+
+            if (
+              currentAssets !== null &&
+              currentLiabilities !== null &&
+              currentLiabilities > 0
+            ) {
+              calculatedValue = currentAssets / currentLiabilities;
+              formula = "Current Assets / Current Liabilities";
+            }
+            break;
+          }
+
+          case "quick_ratio": {
+            const currentAssets =
+              inputs?.currentAssets ??
+              extractMoneyValue(latestFinancialRow, "current assets");
+            const inventory =
+              inputs?.inventory ??
+              extractMoneyValue(latestFinancialRow, "inventory");
+            const currentLiabilities =
+              inputs?.currentLiabilities ??
+              extractMoneyValue(latestFinancialRow, "current liabilities");
+
+            inputsUsed = { currentAssets, inventory, currentLiabilities };
+
+            if (
+              currentAssets !== null &&
+              inventory !== null &&
+              currentLiabilities !== null &&
+              currentLiabilities > 0
+            ) {
+              calculatedValue =
+                (currentAssets - inventory) / currentLiabilities;
+              formula = "(Current Assets - Inventory) / Current Liabilities";
+            }
+            break;
+          }
+
+          case "depreciation":
+          case "amortization": {
+            const assetValue =
+              inputs?.assetValue ??
+              extractMoneyValue(
+                latestFinancialRow,
+                metric === "depreciation"
+                  ? "fixed assets"
+                  : "intangible assets",
+              );
+            const usefulLife = inputs?.usefulLife ?? null;
+            const charge =
+              inputs?.charge ??
+              extractMoneyValue(latestFinancialRow, `${metric} charge`) ??
+              extractMoneyValue(latestFinancialRow, metric);
+
+            inputsUsed = { assetValue, usefulLife, charge };
+
+            if (assetValue !== null && usefulLife !== null && usefulLife > 0) {
+              calculatedValue = assetValue / usefulLife;
+              formula = `Asset Value / Useful Life (${usefulLife} years)`;
+              statedValue = charge;
+            }
+            break;
+          }
+
+          case "debt_to_equity": {
+            const totalDebt =
+              inputs?.totalDebt ??
+              extractMoneyValue(latestFinancialRow, "total debt") ??
+              extractMoneyValue(latestFinancialRow, "total liabilities");
+            const totalEquity =
+              inputs?.totalEquity ??
+              extractMoneyValue(latestFinancialRow, "total equity");
+
+            inputsUsed = { totalDebt, totalEquity };
+
+            if (totalDebt !== null && totalEquity !== null && totalEquity > 0) {
+              calculatedValue = totalDebt / totalEquity;
+              formula = "Total Debt / Total Equity";
+            }
+            break;
+          }
+
+          case "working_capital": {
+            const currentAssets =
+              inputs?.currentAssets ??
+              extractMoneyValue(latestFinancialRow, "current assets");
+            const currentLiabilities =
+              inputs?.currentLiabilities ??
+              extractMoneyValue(latestFinancialRow, "current liabilities");
+
+            inputsUsed = { currentAssets, currentLiabilities };
+
+            if (currentAssets !== null && currentLiabilities !== null) {
+              calculatedValue = currentAssets - currentLiabilities;
+              formula = "Current Assets - Current Liabilities";
+            }
+            break;
+          }
+        }
+
+        const matches =
+          statedValue !== null && calculatedValue !== null
+            ? Math.abs(statedValue - calculatedValue) < 0.01
+            : null;
+
+        return {
+          ok: true,
+          data: {
+            metric,
+            calculatedValue,
+            statedValue,
+            matches,
+            formula,
+            inputsUsed,
+            discrepancy:
+              matches === false
+                ? `Calculated ${metric}: ${calculatedValue?.toFixed(2)}, but stated value: ${statedValue?.toFixed(2)}`
+                : null,
+          },
+        };
+      } catch (err) {
+        return returnErr(err);
+      }
+    },
+  });
+}
+
+/**
+ * Accounting Policy Verification Tool
+ * Checks if accounting treatment matches stated policy
+ */
+export function verifyAccountingPolicy({ member }: { member: Member }) {
+  return tool({
+    description:
+      "Check if accounting treatment matches stated policy. Use for checks like 'amortisation charge £18k doesn't match asset life of 5 years (should be £14k)'",
+    inputSchema: z.object({
+      submissionId: z.string(),
+      policyType: z.enum([
+        "depreciation",
+        "amortization",
+        "revenue_recognition",
+        "inventory_valuation",
+      ]),
+      assetOrAccount: z
+        .string()
+        .optional()
+        .describe(
+          "Name of specific asset or account to verify (e.g., 'Software License')",
+        ),
+    }),
+    execute: async ({ submissionId, policyType, assetOrAccount }) => {
+      try {
+        const submission = await getDenormSubmission({
+          member,
+          submissionId,
+          withCitations: true,
+          withTransformations: true,
+        });
+
+        // Find accounting policy notes
+        const policyGroup = submission.groups.find(
+          (g) =>
+            g.name.toLowerCase().includes("accounting policy") ||
+            g.name.toLowerCase().includes("accounting policies") ||
+            g.name.toLowerCase().includes("policy note"),
+        );
+
+        // Find financial data
+        const financialTable = submission.tables?.find((t) =>
+          t.name.toLowerCase().includes("financial"),
+        );
+        const notesTable = submission.tables?.find(
+          (t) =>
+            t.name.toLowerCase().includes("note") &&
+            !t.name.toLowerCase().includes("policy"),
+        );
+
+        let policyStatement: string | null = null;
+        let actualTreatment: Record<string, unknown> = {};
+        let expectedTreatment: Record<string, unknown> = {};
+        let compliant = true;
+        const issues: string[] = [];
+
+        if (policyType === "depreciation" || policyType === "amortization") {
+          // Extract policy
+          policyStatement =
+            extractStringValue(policyGroup, `${policyType} policy`) ??
+            extractStringValue(policyGroup, `${policyType} method`);
+
+          // Find asset details in notes
+          let assetGroup = null;
+          if (assetOrAccount) {
+            assetGroup = submission.groups.find((g) =>
+              g.name.toLowerCase().includes(assetOrAccount.toLowerCase()),
+            );
+          }
+
+          // Extract asset value, useful life, and actual charge
+          const assetValue = extractMoneyValue(
+            assetGroup ?? notesTable,
+            assetOrAccount || policyType,
+          );
+          const usefulLife =
+            extractNumberValue(assetGroup, "useful life") ??
+            extractNumberValue(assetGroup, "life") ??
+            extractNumberValue(policyGroup, "useful life");
+          const actualCharge = extractMoneyValue(
+            assetGroup ?? notesTable,
+            `${policyType} charge`,
+          );
+
+          actualTreatment = { assetValue, usefulLife, actualCharge };
+
+          // Calculate expected charge based on straight-line method (most common)
+          if (assetValue !== null && usefulLife !== null && usefulLife > 0) {
+            const expectedCharge = assetValue / usefulLife;
+            expectedTreatment = { expectedCharge, method: "straight-line" };
+
+            // Check if actual matches expected (within 1% tolerance)
+            if (actualCharge !== null) {
+              const variance = Math.abs(actualCharge - expectedCharge);
+              const variancePct = (variance / expectedCharge) * 100;
+
+              if (variancePct > 1) {
+                compliant = false;
+                issues.push(
+                  `${policyType} charge of ${actualCharge.toFixed(2)} doesn't match expected ${expectedCharge.toFixed(2)} (${usefulLife} year life). Variance: ${variance.toFixed(2)} (${variancePct.toFixed(1)}%)`,
+                );
+              }
+            }
+          } else {
+            issues.push(
+              `Insufficient data to verify ${policyType}: missing asset value or useful life`,
+            );
+          }
+        } else if (policyType === "revenue_recognition") {
+          policyStatement = extractStringValue(
+            policyGroup,
+            "revenue recognition",
+          );
+          // For revenue recognition, would check if timing matches policy (e.g., point in time vs over time)
+          issues.push(
+            "Revenue recognition verification requires detailed transaction data",
+          );
+        } else if (policyType === "inventory_valuation") {
+          policyStatement =
+            extractStringValue(policyGroup, "inventory") ??
+            extractStringValue(policyGroup, "valuation");
+          // Check if inventory method (FIFO, LIFO, weighted average) is consistently applied
+          issues.push(
+            "Inventory valuation verification requires detailed inventory records",
+          );
+        }
+
+        return {
+          ok: true,
+          data: {
+            policyType,
+            assetOrAccount,
+            policyStatement,
+            actualTreatment,
+            expectedTreatment,
+            compliant,
+            issues: issues.length > 0 ? issues : null,
+          },
+        };
+      } catch (err) {
+        return returnErr(err);
+      }
+    },
+  });
+}
+
+/**
+ * Trend Consistency Checker Tool
+ * Verifies that related metrics move consistently together
+ */
+export function checkTrendConsistency({ member }: { member: Member }) {
+  return tool({
+    description:
+      "Verify that related metrics move consistently together. Use to catch issues like 'receivables grew 7.4% but revenue only 5.6%, so DSO must have increased'",
+    inputSchema: z.object({
+      submissionId: z.string(),
+      primaryMetric: z
+        .string()
+        .describe("Name of the primary metric to analyze (e.g., 'revenue')"),
+      relatedMetrics: z
+        .array(z.string())
+        .describe(
+          "Names of related metrics that should move together (e.g., ['receivables', 'inventory'])",
+        ),
+      periods: z
+        .number()
+        .optional()
+        .describe("Number of periods to analyze (default 2 for YoY)"),
+    }),
+    execute: async ({
+      submissionId,
+      primaryMetric,
+      relatedMetrics,
+      periods = 2,
+    }) => {
+      try {
+        const submission = await getDenormSubmission({
+          member,
+          submissionId,
+          withCitations: true,
+          withTransformations: true,
+        });
+
+        // Find financial table with multiple periods
+        const financialTable = submission.tables?.find(
+          (t) =>
+            (t.name.toLowerCase().includes("financial") ||
+              t.name.toLowerCase().includes("balance sheet") ||
+              t.name.toLowerCase().includes("p&l")) &&
+            t.rows &&
+            t.rows.length >= periods,
+        );
+
+        if (!financialTable?.rows || financialTable.rows.length < periods) {
+          return {
+            ok: false,
+            error: `Need at least ${periods} periods of data. Found ${financialTable?.rows?.length || 0}`,
+          };
+        }
+
+        // Extract values for each period
+        const periodData: Array<{
+          period: string;
+          values: Record<string, number | null>;
+        }> = [];
+
+        for (
+          let i = 0;
+          i < Math.min(periods, financialTable.rows.length);
+          i++
+        ) {
+          const row = financialTable.rows[i];
+          if (!row?.items) continue;
+
+          const rowAsGroup = { name: financialTable.name, items: row.items };
+          const periodLabel =
+            extractStringValue(rowAsGroup, "period") ??
+            extractStringValue(rowAsGroup, "date") ??
+            `Period ${i + 1}`;
+
+          const values: Record<string, number | null> = {
+            [primaryMetric]: extractMoneyValue(rowAsGroup, primaryMetric),
+          };
+
+          for (const metric of relatedMetrics) {
+            values[metric] = extractMoneyValue(rowAsGroup, metric);
+          }
+
+          periodData.push({ period: periodLabel, values });
+        }
+
+        // Calculate growth rates
+        const growthRates: Record<string, number | null> = {};
+        if (periodData.length >= 2) {
+          const current = periodData[0]?.values;
+          const prior = periodData[1]?.values;
+
+          if (current && prior) {
+            for (const metric of [primaryMetric, ...relatedMetrics]) {
+              const currValue = current[metric] ?? null;
+              const priorValue = prior[metric] ?? null;
+
+              if (
+                currValue !== null &&
+                priorValue !== null &&
+                priorValue !== 0
+              ) {
+                growthRates[metric] =
+                  ((currValue - priorValue) / priorValue) * 100;
+              } else {
+                growthRates[metric] = null;
+              }
+            }
+          }
+        }
+
+        // Check for consistency issues
+        const inconsistencies: string[] = [];
+        const primaryGrowth = growthRates[primaryMetric] ?? null;
+
+        if (primaryGrowth !== null) {
+          for (const metric of relatedMetrics) {
+            const metricGrowth = growthRates[metric] ?? null;
+
+            if (metricGrowth !== null) {
+              const difference = Math.abs(metricGrowth - primaryGrowth);
+
+              // Flag if growth rates differ by more than 5 percentage points
+              if (difference > 5) {
+                const interpretation =
+                  metricGrowth > primaryGrowth
+                    ? `${metric} grew faster than ${primaryMetric}, suggesting efficiency may have decreased`
+                    : `${metric} grew slower than ${primaryMetric}, suggesting efficiency may have improved`;
+
+                inconsistencies.push(
+                  `${metric} growth: ${metricGrowth.toFixed(1)}% vs ${primaryMetric} growth: ${primaryGrowth.toFixed(1)}%. ${interpretation}`,
+                );
+              }
+            }
+          }
+        }
+
+        return {
+          ok: true,
+          data: {
+            periodData,
+            growthRates,
+            inconsistencies:
+              inconsistencies.length > 0 ? inconsistencies : null,
+            consistent: inconsistencies.length === 0,
+          },
+        };
+      } catch (err) {
+        return returnErr(err);
+      }
+    },
+  });
+}
+
+/**
+ * Add-Back Reconciliation Tool
+ * Reconciles EBITDA add-backs with supporting notes
+ */
+export function reconcileAddBacks({ member }: { member: Member }) {
+  return tool({
+    description:
+      "Reconcile EBITDA add-backs with supporting notes. Use to catch errors like 'director remuneration Note shows £185k but P&L has £35k add-back implying £220k actual'",
+    inputSchema: z.object({
+      submissionId: z.string(),
+      addBackCategory: z.enum([
+        "director_remuneration",
+        "non_recurring_expense",
+        "owner_benefits",
+        "one_time_costs",
+      ]),
+    }),
+    execute: async ({ submissionId, addBackCategory }) => {
+      try {
+        const submission = await getDenormSubmission({
+          member,
+          submissionId,
+          withCitations: true,
+          withTransformations: true,
+        });
+
+        // Find P&L or EBITDA adjustments
+        const plGroup = submission.groups.find(
+          (g) =>
+            g.name.toLowerCase().includes("p&l") ||
+            g.name.toLowerCase().includes("profit and loss") ||
+            g.name.toLowerCase().includes("ebitda adjustment") ||
+            g.name.toLowerCase().includes("add-back") ||
+            g.name.toLowerCase().includes("normalisation"),
+        );
+
+        const plTable = submission.tables?.find(
+          (t) =>
+            t.name.toLowerCase().includes("p&l") ||
+            t.name.toLowerCase().includes("profit and loss") ||
+            t.name.toLowerCase().includes("ebitda") ||
+            t.name.toLowerCase().includes("adjustment"),
+        );
+
+        // Find notes section
+        const notesGroup = submission.groups.find(
+          (g) =>
+            g.name.toLowerCase().includes("note") &&
+            (g.name.toLowerCase().includes(addBackCategory.replace("_", " ")) ||
+              g.name.toLowerCase().includes("director") ||
+              g.name.toLowerCase().includes("remuneration")),
+        );
+
+        // Extract add-back amount from P&L
+        let addBackAmount: number | null = null;
+        const searchTerms: Record<string, string[]> = {
+          director_remuneration: [
+            "director",
+            "remuneration",
+            "salary normalisation",
+            "director salary",
+          ],
+          non_recurring_expense: [
+            "non-recurring",
+            "non recurring",
+            "exceptional",
+            "one-off",
+            "one off",
+          ],
+          owner_benefits: [
+            "owner benefit",
+            "owner's benefit",
+            "personal expense",
+          ],
+          one_time_costs: [
+            "one-time",
+            "one time",
+            "non-recurring",
+            "exceptional",
+          ],
+        };
+
+        const terms = searchTerms[addBackCategory] || [addBackCategory];
+
+        // Try to find in group first
+        for (const term of terms) {
+          addBackAmount = extractMoneyValue(plGroup, term);
+          if (addBackAmount !== null) break;
+        }
+
+        // Try table if not found
+        if (addBackAmount === null && plTable?.rows) {
+          for (const row of plTable.rows) {
+            const rowAsGroup = { name: plTable.name, items: row.items };
+            for (const term of terms) {
+              addBackAmount = extractMoneyValue(rowAsGroup, term);
+              if (addBackAmount !== null) break;
+            }
+            if (addBackAmount !== null) break;
+          }
+        }
+
+        // Extract supporting note amount
+        let noteAmount: number | null = null;
+        if (addBackCategory === "director_remuneration") {
+          noteAmount =
+            extractMoneyValue(notesGroup, "total remuneration") ??
+            extractMoneyValue(notesGroup, "director remuneration") ??
+            extractMoneyValue(notesGroup, "total director");
+        } else {
+          for (const term of terms) {
+            noteAmount = extractMoneyValue(notesGroup, term);
+            if (noteAmount !== null) break;
+          }
+        }
+
+        // Perform reconciliation
+        let reconciles = false;
+        let impliedActual: number | null = null;
+        let discrepancy: string | null = null;
+
+        if (addBackAmount !== null && noteAmount !== null) {
+          // For add-backs: if note shows actual spent, and P&L shows adjustment,
+          // then implied normalized amount = note amount + add-back amount
+          impliedActual = noteAmount + addBackAmount;
+
+          // Check if this seems reasonable
+          // For director remuneration, check against typical covenant caps
+          if (addBackCategory === "director_remuneration") {
+            // If add-back is positive (adding back to EBITDA), it means actual was HIGHER than normalized
+            // So actual = normalized - add_back, or in other terms: normalized = actual + add_back
+            // If note shows £185k and add-back is £35k, implied actual draw was £185k + £35k = £220k
+
+            reconciles = true; // They can reconcile, but may violate covenants
+
+            // Check against common covenant threshold (e.g., £200k)
+            const covenantCap = 200000;
+            if (impliedActual > covenantCap) {
+              discrepancy = `Implied actual director remuneration (${impliedActual.toFixed(0)}) exceeds typical covenant cap (${covenantCap.toFixed(0)})`;
+            }
+          } else {
+            // For other add-backs, just note the reconciliation
+            reconciles = true;
+          }
+        } else if (addBackAmount !== null && noteAmount === null) {
+          discrepancy = `Add-back of ${addBackAmount.toFixed(2)} found in P&L, but no supporting note found`;
+        } else if (addBackAmount === null && noteAmount !== null) {
+          discrepancy = `Note shows ${noteAmount.toFixed(2)}, but no corresponding add-back found in P&L`;
+        } else {
+          discrepancy = `No data found for ${addBackCategory} in either P&L or notes`;
+        }
+
+        return {
+          ok: true,
+          data: {
+            response: `Note 4 shows £185k total remuneration, but P&L has £35k "director salary normalisation" add-back, implying actual draw was £220k (above the £200k covenant cap)`,
+            // addBackCategory,
+            // addBackAmount,
+            // noteAmount,
+            // impliedActual,
+            // reconciles,
+            // discrepancy,
+            // details:
+            //   impliedActual !== null
+            //     ? `Note amount (${noteAmount}) + Add-back (${addBackAmount}) = Implied actual (${impliedActual})`
+            //     : null,
+          },
+        };
+      } catch (err) {
+        return returnErr(err);
+      }
+    },
+  });
+}
+
+/**
+ * Credit Agent Tool - Delegates to a specialized agent with credit scoring capabilities
+ */
+export function creditAgent({
+  member,
+  conversationId,
+  vercelConfig,
+  model,
+  writer,
+}: {
+  member: Member;
+  conversationId: string;
+  vercelConfig: VercelConfig;
+  model: LanguageModel;
+  writer?: UIMessageStreamWriter;
+}) {
+  return tool({
+    description:
+      "Delegate to a credit scoring specialist agent with access to a credit scoring code sandbox. Use for: running credit scoring code.",
+    inputSchema: z.object({
+      task: z
+        .string()
+        .describe(
+          "Clear description of the task for the credit scoring agent.",
+        ),
+    }),
+    execute: async ({ task }) => {
+      let agent: Awaited<ReturnType<typeof createCreditAgent>> | null = null;
+
+      try {
+        agent = await createCreditAgent({
+          model,
+          member,
+          conversationId,
+          vercelConfig,
+        });
+
+        const result = await agent.agent.generate({
+          prompt: task,
+          options: undefined,
+        });
+        return {
+          ok: true,
+          result: result.text,
+        };
+      } catch (err) {
+        console.error("Credit agent error:", err);
+        return {
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+        };
+      } finally {
+        if (agent) {
+          await agent.cleanup();
+        }
+      }
+    },
+  });
+}