Add financing data import and normalization flow
This commit is contained in:
@@ -314,6 +314,109 @@ const categoryBreakdownValidator = v.object({
|
||||
block: v.optional(v.union(v.literal("wiederkehrend"), v.literal("variabel"))),
|
||||
});
|
||||
|
||||
const safeCategoryBreakdownValidator = v.object({
|
||||
name: v.string(),
|
||||
amount: v.number(),
|
||||
block: v.optional(v.union(v.literal("wiederkehrend"), v.literal("variabel"))),
|
||||
});
|
||||
|
||||
const accountInsightValidator = v.object({
|
||||
name: v.string(),
|
||||
type: v.string(),
|
||||
currency: v.string(),
|
||||
isArchived: v.boolean(),
|
||||
openingBalance: v.number(),
|
||||
transactionCount: v.number(),
|
||||
balance: v.number(),
|
||||
});
|
||||
|
||||
const categoryInsightValidator = v.object({
|
||||
name: v.string(),
|
||||
kind: v.union(v.literal("einnahme"), v.literal("ausgabe")),
|
||||
block: v.optional(v.union(v.literal("wiederkehrend"), v.literal("variabel"))),
|
||||
isSystem: v.boolean(),
|
||||
transactionCount: v.number(),
|
||||
amount: v.number(),
|
||||
shareOfExpenses: v.optional(v.number()),
|
||||
});
|
||||
|
||||
const recurringPatternValidator = v.object({
|
||||
label: v.string(),
|
||||
counterparty: v.optional(v.string()),
|
||||
categoryName: v.optional(v.string()),
|
||||
months: v.array(v.string()),
|
||||
occurrenceCount: v.number(),
|
||||
averageAmount: v.number(),
|
||||
minAmount: v.number(),
|
||||
maxAmount: v.number(),
|
||||
frequency: v.literal("monthly"),
|
||||
lastDate: v.string(),
|
||||
nextExpectedMonth: v.string(),
|
||||
});
|
||||
|
||||
const anomalyValidator = v.object({
|
||||
kind: v.union(v.literal("amount_spike"), v.literal("missing_recurring")),
|
||||
label: v.string(),
|
||||
month: v.string(),
|
||||
amount: v.number(),
|
||||
expectedAmount: v.number(),
|
||||
severity: v.union(v.literal("low"), v.literal("medium"), v.literal("high")),
|
||||
});
|
||||
|
||||
const topCounterpartyValidator = v.object({
|
||||
name: v.string(),
|
||||
count: v.number(),
|
||||
amount: v.number(),
|
||||
});
|
||||
|
||||
const summarySnapshotValidator = v.object({
|
||||
from: v.string(),
|
||||
to: v.string(),
|
||||
totals: totalsValidator,
|
||||
fixedCosts: v.number(),
|
||||
variableCosts: v.number(),
|
||||
monthlyTrend: v.array(monthlyTrendValidator),
|
||||
categoryBreakdown: v.array(safeCategoryBreakdownValidator),
|
||||
});
|
||||
|
||||
const periodDeltasValidator = v.object({
|
||||
income: v.number(),
|
||||
expenses: v.number(),
|
||||
balance: v.number(),
|
||||
fixedCosts: v.number(),
|
||||
variableCosts: v.number(),
|
||||
});
|
||||
|
||||
const categoryDeltaValidator = v.object({
|
||||
name: v.string(),
|
||||
currentAmount: v.number(),
|
||||
previousAmount: v.number(),
|
||||
delta: v.number(),
|
||||
});
|
||||
|
||||
const fixedCostItemValidator = v.object({
|
||||
label: v.string(),
|
||||
averageAmount: v.number(),
|
||||
occurrenceCount: v.number(),
|
||||
months: v.array(v.string()),
|
||||
});
|
||||
|
||||
const fixedCostForecastMonthValidator = v.object({
|
||||
month: v.string(),
|
||||
totalFixedCosts: v.number(),
|
||||
});
|
||||
|
||||
const savingsDriverValidator = v.object({
|
||||
name: v.string(),
|
||||
amount: v.number(),
|
||||
shareOfExpenses: v.number(),
|
||||
});
|
||||
|
||||
const savingsLeverValidator = v.object({
|
||||
label: v.string(),
|
||||
monthlyImpact: v.number(),
|
||||
});
|
||||
|
||||
export const getContext = query({
|
||||
args: contextArgsValidator,
|
||||
returns: contextSummaryValidator,
|
||||
@@ -529,6 +632,155 @@ function summarizeTransactions(context: ToolTransactionContext) {
|
||||
};
|
||||
}
|
||||
|
||||
function roundRatio(value: number) {
|
||||
return Math.round(value * 1000) / 1000;
|
||||
}
|
||||
|
||||
function summarizeSnapshot(
|
||||
context: ToolTransactionContext,
|
||||
summary: ReturnType<typeof summarizeTransactions>,
|
||||
) {
|
||||
return {
|
||||
from: context.from,
|
||||
to: context.to,
|
||||
totals: summary.totals,
|
||||
fixedCosts: summary.fixedCosts,
|
||||
variableCosts: summary.variableCosts,
|
||||
monthlyTrend: summary.monthlyTrend,
|
||||
categoryBreakdown: summary.categoryBreakdown.map((entry) => ({
|
||||
name: entry.name,
|
||||
amount: entry.amount,
|
||||
...(entry.block ? { block: entry.block } : {}),
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
function normalizedText(value: string | undefined) {
|
||||
return value?.trim().toLocaleLowerCase("de-DE") ?? "";
|
||||
}
|
||||
|
||||
function recurringLabelForTransaction(
|
||||
tx: Doc<"transactions">,
|
||||
context: Pick<ToolTransactionContext, "categoryById">,
|
||||
) {
|
||||
const category = tx.categoryId ? context.categoryById.get(tx.categoryId) : undefined;
|
||||
return tx.description.trim() || tx.counterparty?.trim() || category?.name || "Unbekannt";
|
||||
}
|
||||
|
||||
function dateForTransaction(tx: Doc<"transactions">) {
|
||||
return tx.valueDate || tx.bookingDate || tx.effectiveMonth || "n/a";
|
||||
}
|
||||
|
||||
function monthIndexesAreConsecutive(months: string[]) {
|
||||
if (months.length < 2) return false;
|
||||
for (let index = 1; index < months.length; index++) {
|
||||
if (parseMonthIndex(months[index]) - parseMonthIndex(months[index - 1]) !== 1) {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
function amountSeriesIsStable(amounts: number[]) {
|
||||
const average = amounts.reduce((sum, amount) => sum + amount, 0) / amounts.length;
|
||||
const maxDeviation = Math.max(...amounts.map((amount) => Math.abs(amount - average)));
|
||||
return maxDeviation <= Math.max(Math.abs(average) * 0.2, 5);
|
||||
}
|
||||
|
||||
type RecurringDetectionOptions = {
|
||||
beforeMonth?: string;
|
||||
expensesOnly?: boolean;
|
||||
fixedCategoriesOnly?: boolean;
|
||||
includeUncategorized?: boolean;
|
||||
};
|
||||
|
||||
function detectRecurringPatterns(
|
||||
context: ToolTransactionContext,
|
||||
options: RecurringDetectionOptions = {},
|
||||
) {
|
||||
const groups = new Map<
|
||||
string,
|
||||
{
|
||||
label: string;
|
||||
counterparty?: string;
|
||||
categoryName?: string;
|
||||
amountsByMonth: Map<string, number>;
|
||||
lastDate: string;
|
||||
firstCreationTime: number;
|
||||
}
|
||||
>();
|
||||
|
||||
for (const tx of context.transactions) {
|
||||
if (tx.amount === 0) continue;
|
||||
if (options.expensesOnly && tx.amount >= 0) continue;
|
||||
if (!options.includeUncategorized && !tx.categoryId) continue;
|
||||
|
||||
const category = tx.categoryId ? context.categoryById.get(tx.categoryId) : undefined;
|
||||
if (options.fixedCategoriesOnly && category?.block !== "wiederkehrend") continue;
|
||||
|
||||
const month = monthKeyFromBasis(tx, context.basis);
|
||||
if (!month || (options.beforeMonth && month >= options.beforeMonth)) continue;
|
||||
|
||||
const label = recurringLabelForTransaction(tx, context);
|
||||
const key = [
|
||||
normalizedText(label),
|
||||
normalizedText(tx.counterparty),
|
||||
tx.categoryId ?? "none",
|
||||
tx.amount > 0 ? "income" : "expense",
|
||||
].join("|");
|
||||
const entry = groups.get(key) ?? {
|
||||
label,
|
||||
counterparty: tx.counterparty,
|
||||
categoryName: category?.name,
|
||||
amountsByMonth: new Map<string, number>(),
|
||||
lastDate: dateForTransaction(tx),
|
||||
firstCreationTime: tx._creationTime,
|
||||
};
|
||||
entry.amountsByMonth.set(month, (entry.amountsByMonth.get(month) ?? 0) + tx.amount);
|
||||
if (dateForTransaction(tx) > entry.lastDate) entry.lastDate = dateForTransaction(tx);
|
||||
entry.firstCreationTime = Math.min(entry.firstCreationTime, tx._creationTime);
|
||||
groups.set(key, entry);
|
||||
}
|
||||
|
||||
return [...groups.values()]
|
||||
.map((entry) => {
|
||||
const monthAmounts = [...entry.amountsByMonth.entries()].sort(([a], [b]) =>
|
||||
a.localeCompare(b),
|
||||
);
|
||||
const months = monthAmounts.map(([month]) => month);
|
||||
const amounts = monthAmounts.map(([, amount]) => amount);
|
||||
if (months.length < 2 || !monthIndexesAreConsecutive(months) || !amountSeriesIsStable(amounts)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const averageAmount = roundMoney(amounts.reduce((sum, amount) => sum + amount, 0) / amounts.length);
|
||||
return {
|
||||
label: entry.label,
|
||||
counterparty: entry.counterparty,
|
||||
categoryName: entry.categoryName,
|
||||
months,
|
||||
occurrenceCount: months.length,
|
||||
averageAmount,
|
||||
minAmount: roundMoney(Math.min(...amounts)),
|
||||
maxAmount: roundMoney(Math.max(...amounts)),
|
||||
frequency: "monthly" as const,
|
||||
lastDate: entry.lastDate,
|
||||
nextExpectedMonth: addMonthsToMonthKey(months[months.length - 1], 1),
|
||||
};
|
||||
})
|
||||
.filter((pattern): pattern is NonNullable<typeof pattern> => pattern !== null)
|
||||
.sort(
|
||||
(a, b) =>
|
||||
b.occurrenceCount - a.occurrenceCount ||
|
||||
a.label.localeCompare(b.label, "de-DE") ||
|
||||
a.lastDate.localeCompare(b.lastDate),
|
||||
);
|
||||
}
|
||||
|
||||
function buildCategoryAmountMap(summary: ReturnType<typeof summarizeTransactions>) {
|
||||
return new Map(summary.categoryBreakdown.map((entry) => [entry.name, entry.amount]));
|
||||
}
|
||||
|
||||
function toDisplayContextLine(
|
||||
tx: Doc<"transactions">,
|
||||
categoryById: Map<Id<"categories">, string>,
|
||||
@@ -673,6 +925,539 @@ export const forecastCashflowTool = internalQuery({
|
||||
},
|
||||
});
|
||||
|
||||
export const getAccountsTool = internalQuery({
|
||||
args: {
|
||||
scope: toolScopeValidator,
|
||||
from: v.optional(v.string()),
|
||||
to: v.optional(v.string()),
|
||||
accountId: v.optional(v.id("accounts")),
|
||||
accountName: v.optional(v.string()),
|
||||
includeArchived: v.optional(v.boolean()),
|
||||
},
|
||||
returns: v.object({
|
||||
from: v.string(),
|
||||
to: v.string(),
|
||||
basis: v.union(v.literal("effective"), v.literal("booking")),
|
||||
accounts: v.array(accountInsightValidator),
|
||||
}),
|
||||
handler: async (ctx, args) => {
|
||||
const userId = await requireUserId(ctx);
|
||||
const maps = await loadNameMaps(ctx, userId);
|
||||
const range = normalizeToolRange(args.scope, args.from, args.to);
|
||||
const accountId = args.accountId ?? findAccountIdByName(maps.accounts, args.accountName) ?? args.scope.accountId;
|
||||
const transactions = await loadMatchingTransactions(ctx, userId, {
|
||||
...range,
|
||||
accountId,
|
||||
basis: args.scope.basis,
|
||||
});
|
||||
const transactionsByAccount = new Map<Id<"accounts">, Doc<"transactions">[]>();
|
||||
for (const tx of transactions) {
|
||||
if (!tx.accountId) continue;
|
||||
const list = transactionsByAccount.get(tx.accountId) ?? [];
|
||||
list.push(tx);
|
||||
transactionsByAccount.set(tx.accountId, list);
|
||||
}
|
||||
|
||||
const accounts = maps.accounts
|
||||
.filter((account) => {
|
||||
if (accountId && account._id !== accountId) return false;
|
||||
return args.includeArchived === true || !account.isArchived;
|
||||
})
|
||||
.sort((a, b) => Number(a.isArchived) - Number(b.isArchived) || a.name.localeCompare(b.name, "de-DE"))
|
||||
.map((account) => {
|
||||
const accountTransactions = transactionsByAccount.get(account._id) ?? [];
|
||||
return {
|
||||
name: account.name,
|
||||
type: account.type,
|
||||
currency: account.currency,
|
||||
isArchived: account.isArchived,
|
||||
openingBalance: roundMoney(account.openingBalance),
|
||||
transactionCount: accountTransactions.length,
|
||||
balance: calculateTotals(accountTransactions).balance,
|
||||
};
|
||||
});
|
||||
|
||||
return {
|
||||
from: range.from,
|
||||
to: range.to,
|
||||
basis: args.scope.basis,
|
||||
accounts,
|
||||
};
|
||||
},
|
||||
});
|
||||
|
||||
export const getCategoriesTool = internalQuery({
|
||||
args: {
|
||||
scope: toolScopeValidator,
|
||||
from: v.optional(v.string()),
|
||||
to: v.optional(v.string()),
|
||||
accountId: v.optional(v.id("accounts")),
|
||||
accountName: v.optional(v.string()),
|
||||
categoryIds: v.optional(v.array(v.id("categories"))),
|
||||
categoryNames: v.optional(v.array(v.string())),
|
||||
search: v.optional(v.string()),
|
||||
type: v.optional(transactionTypeFilterValidator),
|
||||
},
|
||||
returns: v.object({
|
||||
from: v.string(),
|
||||
to: v.string(),
|
||||
basis: v.union(v.literal("effective"), v.literal("booking")),
|
||||
accountName: v.optional(v.string()),
|
||||
categories: v.array(categoryInsightValidator),
|
||||
}),
|
||||
handler: async (ctx, args) => {
|
||||
const userId = await requireUserId(ctx);
|
||||
const context = await buildToolTransactionContext(ctx, userId, args);
|
||||
const totalExpenses = Math.abs(calculateTotals(context.transactions).expenses);
|
||||
const sortOrderByCategory = new Map(context.categories.map((category) => [category._id, category.sortOrder]));
|
||||
const categoryRows = new Map<
|
||||
string,
|
||||
{
|
||||
categoryId?: Id<"categories">;
|
||||
name: string;
|
||||
kind: "einnahme" | "ausgabe";
|
||||
block?: "wiederkehrend" | "variabel";
|
||||
isSystem: boolean;
|
||||
transactionCount: number;
|
||||
amount: number;
|
||||
}
|
||||
>();
|
||||
|
||||
for (const tx of context.transactions) {
|
||||
const category = tx.categoryId ? context.categoryById.get(tx.categoryId) : undefined;
|
||||
const key = tx.categoryId ?? "none";
|
||||
const existing = categoryRows.get(key) ?? {
|
||||
categoryId: tx.categoryId,
|
||||
name: category?.name ?? "Ohne Kategorie",
|
||||
kind: category?.kind ?? (tx.amount >= 0 ? "einnahme" : "ausgabe"),
|
||||
block: category?.block,
|
||||
isSystem: category?.isSystem ?? false,
|
||||
transactionCount: 0,
|
||||
amount: 0,
|
||||
};
|
||||
existing.transactionCount += 1;
|
||||
existing.amount += tx.amount;
|
||||
if (!category && existing.amount < 0) existing.kind = "ausgabe";
|
||||
categoryRows.set(key, existing);
|
||||
}
|
||||
|
||||
const categories = [...categoryRows.values()]
|
||||
.sort((a, b) => {
|
||||
const aSort = a.categoryId ? sortOrderByCategory.get(a.categoryId) ?? 0 : Number.MAX_SAFE_INTEGER;
|
||||
const bSort = b.categoryId ? sortOrderByCategory.get(b.categoryId) ?? 0 : Number.MAX_SAFE_INTEGER;
|
||||
return aSort - bSort || a.name.localeCompare(b.name, "de-DE");
|
||||
})
|
||||
.map((entry) => ({
|
||||
name: entry.name,
|
||||
kind: entry.kind,
|
||||
...(entry.block ? { block: entry.block } : {}),
|
||||
isSystem: entry.isSystem,
|
||||
transactionCount: entry.transactionCount,
|
||||
amount: roundMoney(entry.amount),
|
||||
...(entry.amount < 0 && totalExpenses > 0
|
||||
? { shareOfExpenses: roundRatio(Math.abs(entry.amount) / totalExpenses) }
|
||||
: {}),
|
||||
}));
|
||||
|
||||
return {
|
||||
from: context.from,
|
||||
to: context.to,
|
||||
basis: context.basis,
|
||||
accountName: context.accountName,
|
||||
categories,
|
||||
};
|
||||
},
|
||||
});
|
||||
|
||||
export const getUncategorizedTransactionsTool = internalQuery({
|
||||
args: transactionToolArgsValidator,
|
||||
returns: v.object({
|
||||
from: v.string(),
|
||||
to: v.string(),
|
||||
basis: v.union(v.literal("effective"), v.literal("booking")),
|
||||
accountName: v.optional(v.string()),
|
||||
totalCount: v.number(),
|
||||
hasMore: v.boolean(),
|
||||
totals: totalsValidator,
|
||||
topCounterparties: v.array(topCounterpartyValidator),
|
||||
rows: v.array(safeTransactionRowValidator),
|
||||
}),
|
||||
handler: async (ctx, args) => {
|
||||
const userId = await requireUserId(ctx);
|
||||
const context = await buildToolTransactionContext(ctx, userId, {
|
||||
...args,
|
||||
categoryIds: undefined,
|
||||
categoryNames: undefined,
|
||||
});
|
||||
const limit = clampToolLimit(args.limit);
|
||||
const uncategorized = context.transactions.filter((tx) => !tx.categoryId);
|
||||
const counterpartyMap = new Map<string, { count: number; amount: number }>();
|
||||
for (const tx of uncategorized) {
|
||||
const name = tx.counterparty?.trim() || tx.description.trim() || "Unbekannt";
|
||||
const entry = counterpartyMap.get(name) ?? { count: 0, amount: 0 };
|
||||
entry.count += 1;
|
||||
entry.amount += tx.amount;
|
||||
counterpartyMap.set(name, entry);
|
||||
}
|
||||
|
||||
return {
|
||||
from: context.from,
|
||||
to: context.to,
|
||||
basis: context.basis,
|
||||
accountName: context.accountName,
|
||||
totalCount: uncategorized.length,
|
||||
hasMore: uncategorized.length > limit,
|
||||
totals: calculateTotals(uncategorized),
|
||||
topCounterparties: [...counterpartyMap.entries()]
|
||||
.map(([name, entry]) => ({ name, count: entry.count, amount: roundMoney(entry.amount) }))
|
||||
.sort((a, b) => b.count - a.count || Math.abs(b.amount) - Math.abs(a.amount) || a.name.localeCompare(b.name, "de-DE"))
|
||||
.slice(0, 5),
|
||||
rows: uncategorized.slice(0, limit).map((tx) => safeTransactionRow(tx, context)),
|
||||
};
|
||||
},
|
||||
});
|
||||
|
||||
export const comparePeriodsTool = internalQuery({
|
||||
args: {
|
||||
scope: toolScopeValidator,
|
||||
from: v.optional(v.string()),
|
||||
to: v.optional(v.string()),
|
||||
compareFrom: v.string(),
|
||||
compareTo: v.string(),
|
||||
accountId: v.optional(v.id("accounts")),
|
||||
accountName: v.optional(v.string()),
|
||||
categoryIds: v.optional(v.array(v.id("categories"))),
|
||||
categoryNames: v.optional(v.array(v.string())),
|
||||
search: v.optional(v.string()),
|
||||
type: v.optional(transactionTypeFilterValidator),
|
||||
},
|
||||
returns: v.object({
|
||||
basis: v.union(v.literal("effective"), v.literal("booking")),
|
||||
accountName: v.optional(v.string()),
|
||||
current: summarySnapshotValidator,
|
||||
previous: summarySnapshotValidator,
|
||||
deltas: periodDeltasValidator,
|
||||
categoryDeltas: v.array(categoryDeltaValidator),
|
||||
}),
|
||||
handler: async (ctx, args) => {
|
||||
const userId = await requireUserId(ctx);
|
||||
const currentContext = await buildToolTransactionContext(ctx, userId, args);
|
||||
const previousContext = await buildToolTransactionContext(ctx, userId, {
|
||||
scope: args.scope,
|
||||
from: args.compareFrom,
|
||||
to: args.compareTo,
|
||||
accountId: args.accountId,
|
||||
accountName: args.accountName,
|
||||
categoryIds: args.categoryIds,
|
||||
categoryNames: args.categoryNames,
|
||||
search: args.search,
|
||||
type: args.type,
|
||||
});
|
||||
const currentSummary = summarizeTransactions(currentContext);
|
||||
const previousSummary = summarizeTransactions(previousContext);
|
||||
const currentCategoryMap = buildCategoryAmountMap(currentSummary);
|
||||
const previousCategoryMap = buildCategoryAmountMap(previousSummary);
|
||||
const categoryNames = new Set([...currentCategoryMap.keys(), ...previousCategoryMap.keys()]);
|
||||
|
||||
return {
|
||||
basis: currentContext.basis,
|
||||
accountName: currentContext.accountName,
|
||||
current: summarizeSnapshot(currentContext, currentSummary),
|
||||
previous: summarizeSnapshot(previousContext, previousSummary),
|
||||
deltas: {
|
||||
income: roundMoney(currentSummary.totals.income - previousSummary.totals.income),
|
||||
expenses: roundMoney(currentSummary.totals.expenses - previousSummary.totals.expenses),
|
||||
balance: roundMoney(currentSummary.totals.balance - previousSummary.totals.balance),
|
||||
fixedCosts: roundMoney(currentSummary.fixedCosts - previousSummary.fixedCosts),
|
||||
variableCosts: roundMoney(currentSummary.variableCosts - previousSummary.variableCosts),
|
||||
},
|
||||
categoryDeltas: [...categoryNames]
|
||||
.map((name) => {
|
||||
const currentAmount = currentCategoryMap.get(name) ?? 0;
|
||||
const previousAmount = previousCategoryMap.get(name) ?? 0;
|
||||
return {
|
||||
name,
|
||||
currentAmount,
|
||||
previousAmount,
|
||||
delta: roundMoney(currentAmount - previousAmount),
|
||||
};
|
||||
})
|
||||
.sort((a, b) => a.delta - b.delta || a.name.localeCompare(b.name, "de-DE")),
|
||||
};
|
||||
},
|
||||
});
|
||||
|
||||
export const explainSavingsRateTool = internalQuery({
|
||||
args: {
|
||||
scope: toolScopeValidator,
|
||||
from: v.optional(v.string()),
|
||||
to: v.optional(v.string()),
|
||||
accountId: v.optional(v.id("accounts")),
|
||||
accountName: v.optional(v.string()),
|
||||
categoryIds: v.optional(v.array(v.id("categories"))),
|
||||
categoryNames: v.optional(v.array(v.string())),
|
||||
search: v.optional(v.string()),
|
||||
type: v.optional(transactionTypeFilterValidator),
|
||||
},
|
||||
returns: v.object({
|
||||
from: v.string(),
|
||||
to: v.string(),
|
||||
income: v.number(),
|
||||
expenses: v.number(),
|
||||
savedAmount: v.number(),
|
||||
savingsRate: v.union(v.number(), v.null()),
|
||||
fixedCosts: v.number(),
|
||||
variableCosts: v.number(),
|
||||
transactionCount: v.number(),
|
||||
drivers: v.array(savingsDriverValidator),
|
||||
levers: v.array(savingsLeverValidator),
|
||||
}),
|
||||
handler: async (ctx, args) => {
|
||||
const userId = await requireUserId(ctx);
|
||||
const context = await buildToolTransactionContext(ctx, userId, args);
|
||||
const summary = summarizeTransactions(context);
|
||||
const totalExpenses = Math.abs(summary.totals.expenses);
|
||||
const drivers = summary.categoryBreakdown.slice(0, 3).map((entry) => ({
|
||||
name: entry.name,
|
||||
amount: entry.amount,
|
||||
shareOfExpenses: totalExpenses > 0 ? roundRatio(Math.abs(entry.amount) / totalExpenses) : 0,
|
||||
}));
|
||||
const levers = [];
|
||||
if (summary.variableCosts < 0) {
|
||||
levers.push({
|
||||
label: "Variable Ausgaben um 10% senken",
|
||||
monthlyImpact: roundMoney(Math.abs(summary.variableCosts) * 0.1),
|
||||
});
|
||||
}
|
||||
if (summary.fixedCosts < 0) {
|
||||
levers.push({
|
||||
label: "Fixkosten um 5% senken",
|
||||
monthlyImpact: roundMoney(Math.abs(summary.fixedCosts) * 0.05),
|
||||
});
|
||||
}
|
||||
|
||||
return {
|
||||
from: context.from,
|
||||
to: context.to,
|
||||
income: summary.totals.income,
|
||||
expenses: summary.totals.expenses,
|
||||
savedAmount: summary.totals.balance,
|
||||
savingsRate: summary.totals.income > 0 ? roundRatio(summary.totals.balance / summary.totals.income) : null,
|
||||
fixedCosts: summary.fixedCosts,
|
||||
variableCosts: summary.variableCosts,
|
||||
transactionCount: summary.totals.transactionCount,
|
||||
drivers,
|
||||
levers,
|
||||
};
|
||||
},
|
||||
});
|
||||
|
||||
export const detectRecurringTransactionsTool = internalQuery({
|
||||
args: {
|
||||
scope: toolScopeValidator,
|
||||
from: v.optional(v.string()),
|
||||
to: v.optional(v.string()),
|
||||
accountId: v.optional(v.id("accounts")),
|
||||
accountName: v.optional(v.string()),
|
||||
categoryIds: v.optional(v.array(v.id("categories"))),
|
||||
categoryNames: v.optional(v.array(v.string())),
|
||||
search: v.optional(v.string()),
|
||||
type: v.optional(transactionTypeFilterValidator),
|
||||
},
|
||||
returns: v.object({
|
||||
from: v.string(),
|
||||
to: v.string(),
|
||||
basis: v.union(v.literal("effective"), v.literal("booking")),
|
||||
accountName: v.optional(v.string()),
|
||||
patterns: v.array(recurringPatternValidator),
|
||||
}),
|
||||
handler: async (ctx, args) => {
|
||||
const userId = await requireUserId(ctx);
|
||||
const context = await buildToolTransactionContext(ctx, userId, args);
|
||||
return {
|
||||
from: context.from,
|
||||
to: context.to,
|
||||
basis: context.basis,
|
||||
accountName: context.accountName,
|
||||
patterns: detectRecurringPatterns(context),
|
||||
};
|
||||
},
|
||||
});
|
||||
|
||||
export const forecastFixedCostsTool = internalQuery({
|
||||
args: {
|
||||
scope: toolScopeValidator,
|
||||
from: v.optional(v.string()),
|
||||
to: v.optional(v.string()),
|
||||
accountId: v.optional(v.id("accounts")),
|
||||
accountName: v.optional(v.string()),
|
||||
horizonMonths: v.optional(v.number()),
|
||||
asOf: v.optional(v.string()),
|
||||
},
|
||||
returns: v.object({
|
||||
from: v.string(),
|
||||
to: v.string(),
|
||||
basis: v.union(v.literal("effective"), v.literal("booking")),
|
||||
accountName: v.optional(v.string()),
|
||||
items: v.array(fixedCostItemValidator),
|
||||
forecast: v.array(fixedCostForecastMonthValidator),
|
||||
}),
|
||||
handler: async (ctx, args) => {
|
||||
const userId = await requireUserId(ctx);
|
||||
const context = await buildToolTransactionContext(ctx, userId, args);
|
||||
const fixedGroups = new Map<
|
||||
string,
|
||||
{ label: string; amountsByMonth: Map<string, number> }
|
||||
>();
|
||||
|
||||
for (const tx of context.transactions) {
|
||||
if (tx.amount >= 0 || !tx.categoryId) continue;
|
||||
const category = context.categoryById.get(tx.categoryId);
|
||||
if (category?.block !== "wiederkehrend") continue;
|
||||
const month = monthKeyFromBasis(tx, context.basis);
|
||||
if (!month) continue;
|
||||
const label = recurringLabelForTransaction(tx, context);
|
||||
const key = [normalizedText(label), tx.categoryId, normalizedText(tx.counterparty)].join("|");
|
||||
const entry = fixedGroups.get(key) ?? { label, amountsByMonth: new Map<string, number>() };
|
||||
entry.amountsByMonth.set(month, (entry.amountsByMonth.get(month) ?? 0) + tx.amount);
|
||||
fixedGroups.set(key, entry);
|
||||
}
|
||||
|
||||
const items = [...fixedGroups.values()]
|
||||
.map((entry) => {
|
||||
const monthAmounts = [...entry.amountsByMonth.entries()].sort(([a], [b]) =>
|
||||
a.localeCompare(b),
|
||||
);
|
||||
const months = monthAmounts.map(([month]) => month);
|
||||
const amounts = monthAmounts.map(([, amount]) => amount);
|
||||
return {
|
||||
label: entry.label,
|
||||
averageAmount: roundMoney(amounts.reduce((sum, amount) => sum + amount, 0) / amounts.length),
|
||||
occurrenceCount: months.length,
|
||||
months,
|
||||
};
|
||||
})
|
||||
.filter((item) => item.months.length > 0)
|
||||
.sort((a, b) => a.averageAmount - b.averageAmount || a.label.localeCompare(b.label, "de-DE"));
|
||||
const horizonMonths = Math.max(1, Math.min(6, Math.floor(args.horizonMonths ?? 3)));
|
||||
const asOfMonth = (args.asOf ?? context.to).slice(0, 7);
|
||||
const totalFixedCosts = roundMoney(items.reduce((sum, item) => sum + item.averageAmount, 0));
|
||||
|
||||
return {
|
||||
from: context.from,
|
||||
to: context.to,
|
||||
basis: context.basis,
|
||||
accountName: context.accountName,
|
||||
items,
|
||||
forecast: Array.from({ length: horizonMonths }, (_, index) => ({
|
||||
month: addMonthsToMonthKey(asOfMonth, index + 1),
|
||||
totalFixedCosts,
|
||||
})),
|
||||
};
|
||||
},
|
||||
});
|
||||
|
||||
export const findAnomaliesTool = internalQuery({
|
||||
args: {
|
||||
scope: toolScopeValidator,
|
||||
from: v.optional(v.string()),
|
||||
to: v.optional(v.string()),
|
||||
accountId: v.optional(v.id("accounts")),
|
||||
accountName: v.optional(v.string()),
|
||||
asOf: v.optional(v.string()),
|
||||
},
|
||||
returns: v.object({
|
||||
from: v.string(),
|
||||
to: v.string(),
|
||||
basis: v.union(v.literal("effective"), v.literal("booking")),
|
||||
accountName: v.optional(v.string()),
|
||||
anomalies: v.array(anomalyValidator),
|
||||
}),
|
||||
handler: async (ctx, args) => {
|
||||
const userId = await requireUserId(ctx);
|
||||
const context = await buildToolTransactionContext(ctx, userId, args);
|
||||
const targetMonth = (args.asOf ?? context.to).slice(0, 7);
|
||||
const amountByCategoryMonth = new Map<string, Map<string, number>>();
|
||||
const amountByRecurringLabelMonth = new Map<string, Map<string, number>>();
|
||||
|
||||
for (const tx of context.transactions) {
|
||||
const month = monthKeyFromBasis(tx, context.basis);
|
||||
if (!month) continue;
|
||||
|
||||
const category = tx.categoryId ? context.categoryById.get(tx.categoryId) : undefined;
|
||||
const categoryName = category?.name ?? "Ohne Kategorie";
|
||||
const categoryMonthMap = amountByCategoryMonth.get(categoryName) ?? new Map<string, number>();
|
||||
categoryMonthMap.set(month, (categoryMonthMap.get(month) ?? 0) + tx.amount);
|
||||
amountByCategoryMonth.set(categoryName, categoryMonthMap);
|
||||
|
||||
if (tx.categoryId) {
|
||||
const label = recurringLabelForTransaction(tx, context);
|
||||
const recurringMonthMap = amountByRecurringLabelMonth.get(label) ?? new Map<string, number>();
|
||||
recurringMonthMap.set(month, (recurringMonthMap.get(month) ?? 0) + tx.amount);
|
||||
amountByRecurringLabelMonth.set(label, recurringMonthMap);
|
||||
}
|
||||
}
|
||||
|
||||
const anomalies: Array<{
|
||||
kind: "amount_spike" | "missing_recurring";
|
||||
label: string;
|
||||
month: string;
|
||||
amount: number;
|
||||
expectedAmount: number;
|
||||
severity: "low" | "medium" | "high";
|
||||
}> = [];
|
||||
|
||||
for (const [label, amountsByMonth] of amountByCategoryMonth.entries()) {
|
||||
const currentAmount = roundMoney(amountsByMonth.get(targetMonth) ?? 0);
|
||||
if (currentAmount >= 0) continue;
|
||||
const baseline = [...amountsByMonth.entries()]
|
||||
.filter(([month, amount]) => month < targetMonth && amount < 0)
|
||||
.map(([, amount]) => amount);
|
||||
if (baseline.length < 2) continue;
|
||||
const expectedAmount = roundMoney(baseline.reduce((sum, amount) => sum + amount, 0) / baseline.length);
|
||||
const ratio = Math.abs(currentAmount) / Math.max(Math.abs(expectedAmount), 1);
|
||||
if (ratio >= 2 && Math.abs(currentAmount - expectedAmount) >= 100) {
|
||||
anomalies.push({
|
||||
kind: "amount_spike",
|
||||
label,
|
||||
month: targetMonth,
|
||||
amount: currentAmount,
|
||||
expectedAmount,
|
||||
severity: ratio >= 3 ? "high" : "medium",
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
for (const pattern of detectRecurringPatterns(context, { beforeMonth: targetMonth })) {
|
||||
if (pattern.nextExpectedMonth !== targetMonth) continue;
|
||||
const actualAmount = roundMoney(amountByRecurringLabelMonth.get(pattern.label)?.get(targetMonth) ?? 0);
|
||||
if (actualAmount === 0) {
|
||||
anomalies.push({
|
||||
kind: "missing_recurring",
|
||||
label: pattern.label,
|
||||
month: targetMonth,
|
||||
amount: 0,
|
||||
expectedAmount: pattern.averageAmount,
|
||||
severity: "medium",
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return {
|
||||
from: context.from,
|
||||
to: context.to,
|
||||
basis: context.basis,
|
||||
accountName: context.accountName,
|
||||
anomalies: anomalies.sort(
|
||||
(a, b) =>
|
||||
(b.severity === "high" ? 2 : b.severity === "medium" ? 1 : 0) -
|
||||
(a.severity === "high" ? 2 : a.severity === "medium" ? 1 : 0) ||
|
||||
a.label.localeCompare(b.label, "de-DE"),
|
||||
),
|
||||
};
|
||||
},
|
||||
});
|
||||
|
||||
export const getPromptContext = internalQuery({
|
||||
args: contextArgsValidator,
|
||||
returns: v.object({
|
||||
@@ -748,6 +1533,10 @@ function totalsFromOutput(output: Record<string, unknown>) {
|
||||
};
|
||||
}
|
||||
|
||||
function countLabel(count: number, singular: string, plural: string) {
|
||||
return `${count} ${count === 1 ? singular : plural}`;
|
||||
}
|
||||
|
||||
function summarizeToolOutput(toolName: string, output: unknown) {
|
||||
const record = unknownRecord(output);
|
||||
if (toolName === "get_transactions") {
|
||||
@@ -773,6 +1562,49 @@ function summarizeToolOutput(toolName: string, output: unknown) {
|
||||
return `Prognose ${projectionCount} Monate, durchschnittlicher Saldo ${formatEuro(balance)}`;
|
||||
}
|
||||
|
||||
if (toolName === "get_accounts") {
|
||||
const count = Array.isArray(record.accounts) ? record.accounts.length : 0;
|
||||
return `${countLabel(count, "Konto", "Konten")} ausgewertet`;
|
||||
}
|
||||
|
||||
if (toolName === "get_categories") {
|
||||
const count = Array.isArray(record.categories) ? record.categories.length : 0;
|
||||
return `${countLabel(count, "Kategorie", "Kategorien")} ausgewertet`;
|
||||
}
|
||||
|
||||
if (toolName === "detect_recurring_transactions") {
|
||||
const count = Array.isArray(record.patterns) ? record.patterns.length : 0;
|
||||
return `${count} ${count === 1 ? "wiederkehrendes Muster" : "wiederkehrende Muster"} erkannt`;
|
||||
}
|
||||
|
||||
if (toolName === "find_anomalies") {
|
||||
const count = Array.isArray(record.anomalies) ? record.anomalies.length : 0;
|
||||
return `${count} ${count === 1 ? "Auffälligkeit" : "Auffälligkeiten"} erkannt`;
|
||||
}
|
||||
|
||||
if (toolName === "get_uncategorized_transactions") {
|
||||
const count = maybeNumber(record.totalCount) ?? 0;
|
||||
const hasMore = record.hasMore === true;
|
||||
return `${count} unklassifizierte Umsätze, ${hasMore ? "weitere vorhanden" : "vollständig"}`;
|
||||
}
|
||||
|
||||
if (toolName === "compare_periods") {
|
||||
const deltas = unknownRecord(record.deltas);
|
||||
const balance = maybeNumber(deltas.balance) ?? 0;
|
||||
return `Periodenvergleich, Saldo-Differenz ${formatEuro(balance)}`;
|
||||
}
|
||||
|
||||
if (toolName === "forecast_fixed_costs") {
|
||||
const count = Array.isArray(record.forecast) ? record.forecast.length : 0;
|
||||
return `Fixkosten-Prognose ${count} Monate`;
|
||||
}
|
||||
|
||||
if (toolName === "explain_savings_rate") {
|
||||
const savingsRate = maybeNumber(record.savingsRate) ?? 0;
|
||||
const savedAmount = maybeNumber(record.savedAmount) ?? 0;
|
||||
return `Sparquote ${(savingsRate * 100).toFixed(1)}%, gespart ${formatEuro(savedAmount)}`;
|
||||
}
|
||||
|
||||
return "Werkzeug ausgeführt";
|
||||
}
|
||||
|
||||
@@ -814,6 +1646,50 @@ const forecastToolInputSchema = z.object({
|
||||
horizonMonths: z.number().int().min(1).max(3).optional().describe("Anzahl der zu prognostizierenden Monate, 1 bis 3."),
|
||||
});
|
||||
|
||||
const accountToolInputSchema = z.object({
|
||||
from: z.string().optional().describe("Optionales Startdatum im Format YYYY-MM-DD."),
|
||||
to: z.string().optional().describe("Optionales Enddatum im Format YYYY-MM-DD."),
|
||||
accountName: z.string().optional().describe("Optionaler Kontoname, falls nur ein Konto betrachtet werden soll."),
|
||||
includeArchived: z.boolean().optional().describe("Archivierte Konten einbeziehen."),
|
||||
});
|
||||
|
||||
const recurringToolInputSchema = summaryToolInputSchema;
|
||||
|
||||
const anomalyToolInputSchema = z.object({
|
||||
from: z.string().optional().describe("Optionales Startdatum im Format YYYY-MM-DD."),
|
||||
to: z.string().optional().describe("Optionales Enddatum im Format YYYY-MM-DD."),
|
||||
accountName: z.string().optional().describe("Optionaler Kontoname, falls von der UI-Auswahl abweichend."),
|
||||
asOf: z.string().optional().describe("Stichtag für erwartete Muster im Format YYYY-MM-DD."),
|
||||
});
|
||||
|
||||
const uncategorizedToolInputSchema = z.object({
|
||||
from: z.string().optional().describe("Optionales Startdatum im Format YYYY-MM-DD."),
|
||||
to: z.string().optional().describe("Optionales Enddatum im Format YYYY-MM-DD."),
|
||||
accountName: z.string().optional().describe("Optionaler Kontoname, falls von der UI-Auswahl abweichend."),
|
||||
search: z.string().optional().describe("Optionaler Suchtext für Beschreibung oder Gegenpartei."),
|
||||
type: z.enum(["income", "expense"]).optional().describe("Optional nur Einnahmen oder Ausgaben abrufen."),
|
||||
limit: z.number().int().min(1).max(MAX_TOOL_ROW_LIMIT).optional().describe("Maximale Anzahl Umsatzzeilen."),
|
||||
});
|
||||
|
||||
const comparePeriodsToolInputSchema = z.object({
|
||||
from: z.string().optional().describe("Startdatum des aktuellen Zeitraums im Format YYYY-MM-DD."),
|
||||
to: z.string().optional().describe("Enddatum des aktuellen Zeitraums im Format YYYY-MM-DD."),
|
||||
compareFrom: z.string().describe("Startdatum des Vergleichszeitraums im Format YYYY-MM-DD."),
|
||||
compareTo: z.string().describe("Enddatum des Vergleichszeitraums im Format YYYY-MM-DD."),
|
||||
accountName: z.string().optional().describe("Optionaler Kontoname, falls von der UI-Auswahl abweichend."),
|
||||
categoryNames: z.array(z.string()).optional().describe("Optionale Kategorienamen für den Vergleich."),
|
||||
search: z.string().optional().describe("Optionaler Suchtext für beide Zeiträume."),
|
||||
type: z.enum(["income", "expense"]).optional().describe("Optional nur Einnahmen oder Ausgaben vergleichen."),
|
||||
});
|
||||
|
||||
const fixedCostsForecastToolInputSchema = z.object({
|
||||
from: z.string().optional().describe("Optionales Startdatum der historischen Fixkostenbasis im Format YYYY-MM-DD."),
|
||||
to: z.string().optional().describe("Optionales Enddatum der historischen Fixkostenbasis im Format YYYY-MM-DD."),
|
||||
accountName: z.string().optional().describe("Optionaler Kontoname, falls von der UI-Auswahl abweichend."),
|
||||
horizonMonths: z.number().int().min(1).max(6).optional().describe("Anzahl der zu prognostizierenden Monate, 1 bis 6."),
|
||||
asOf: z.string().optional().describe("Stichtag für den Start der Prognose im Format YYYY-MM-DD."),
|
||||
});
|
||||
|
||||
export const ask = action({
|
||||
args: {
|
||||
messages: v.array(chatMessageValidator),
|
||||
@@ -903,6 +1779,86 @@ export const ask = action({
|
||||
...input,
|
||||
}),
|
||||
}),
|
||||
get_accounts: tool({
|
||||
description:
|
||||
"Listet read-only Konten mit Typ, Währung, Archivstatus, Startsaldo, Umsatzanzahl und Zeitraumssaldo. Nutze es für Fragen nach Konten, Konto-Scope oder Datenabdeckung.",
|
||||
inputSchema: accountToolInputSchema,
|
||||
execute: async (input) =>
|
||||
await ctx.runQuery(internal.savingsChat.getAccountsTool, {
|
||||
scope,
|
||||
...input,
|
||||
}),
|
||||
}),
|
||||
get_categories: tool({
|
||||
description:
|
||||
"Listet read-only Kategorien mit Art, Fix/Variabel-Block, Umsatzanzahl, Summe und Ausgabenanteil im Zeitraum. Nutze es für Kategorie- und Budgetstrukturfragen.",
|
||||
inputSchema: summaryToolInputSchema,
|
||||
execute: async (input) =>
|
||||
await ctx.runQuery(internal.savingsChat.getCategoriesTool, {
|
||||
scope,
|
||||
...input,
|
||||
}),
|
||||
}),
|
||||
detect_recurring_transactions: tool({
|
||||
description:
|
||||
"Erkennt deterministisch monatlich wiederkehrende Muster nach Beschreibung, Gegenpartei, Kategorie und stabiler Betragshöhe. Nutze es für Miete, Gehalt, Abos und regelmäßige Abbuchungen.",
|
||||
inputSchema: recurringToolInputSchema,
|
||||
execute: async (input) =>
|
||||
await ctx.runQuery(internal.savingsChat.detectRecurringTransactionsTool, {
|
||||
scope,
|
||||
...input,
|
||||
}),
|
||||
}),
|
||||
find_anomalies: tool({
|
||||
description:
|
||||
"Findet read-only auffällige Betragsausreißer und fehlende erwartete wiederkehrende Buchungen gegenüber historischen Mustern.",
|
||||
inputSchema: anomalyToolInputSchema,
|
||||
execute: async (input) =>
|
||||
await ctx.runQuery(internal.savingsChat.findAnomaliesTool, {
|
||||
scope,
|
||||
...input,
|
||||
}),
|
||||
}),
|
||||
get_uncategorized_transactions: tool({
|
||||
description:
|
||||
"Ruft bounded und sanitizt unklassifizierte Umsätze mit Summen und Top-Gegenparteien ab. Nutze es für Datenqualität und Fragen nach fehlenden Kategorien.",
|
||||
inputSchema: uncategorizedToolInputSchema,
|
||||
execute: async (input) =>
|
||||
await ctx.runQuery(internal.savingsChat.getUncategorizedTransactionsTool, {
|
||||
scope,
|
||||
...input,
|
||||
}),
|
||||
}),
|
||||
compare_periods: tool({
|
||||
description:
|
||||
"Vergleicht zwei Zeiträume deterministisch mit Totals, Monatsverlauf, Kategorie-Deltas und Fix/Variabel-Deltas.",
|
||||
inputSchema: comparePeriodsToolInputSchema,
|
||||
execute: async (input) =>
|
||||
await ctx.runQuery(internal.savingsChat.comparePeriodsTool, {
|
||||
scope,
|
||||
...input,
|
||||
}),
|
||||
}),
|
||||
forecast_fixed_costs: tool({
|
||||
description:
|
||||
"Prognostiziert wiederkehrende Fixkosten für 1 bis 6 Monate aus Fixkosten-Kategorien und stabilen historischen Monatsmustern.",
|
||||
inputSchema: fixedCostsForecastToolInputSchema,
|
||||
execute: async (input) =>
|
||||
await ctx.runQuery(internal.savingsChat.forecastFixedCostsTool, {
|
||||
scope,
|
||||
...input,
|
||||
}),
|
||||
}),
|
||||
explain_savings_rate: tool({
|
||||
description:
|
||||
"Berechnet Sparquote, gesparten Betrag, fixe und variable Kostenquote, Haupttreiber und konkrete Hebel aus exakten Aggregaten.",
|
||||
inputSchema: summaryToolInputSchema,
|
||||
execute: async (input) =>
|
||||
await ctx.runQuery(internal.savingsChat.explainSavingsRateTool, {
|
||||
scope,
|
||||
...input,
|
||||
}),
|
||||
}),
|
||||
};
|
||||
|
||||
const envModel = process.env.SAVINGS_CHAT_MODEL?.trim();
|
||||
|
||||
Reference in New Issue
Block a user