Kaeru

An AI-powered financial operations platform that automates cancellations, disputes, and fraud detection.

The name comes from 帰る (kaeru) — Japanese for "to return, go back, or restore" — reflecting the project's goal of helping users reclaim control over their financial life. Note: the npm package name in package.json is aws-amplify-gen2 for historical reasons tied to the underlying AWS Amplify Gen2 scaffold; the repository, product, and folder name is kaeru.

Kaeru combines Next.js 14 (App Router), AWS Amplify Gen2, Plaid, VAPI voice agents, and LangChain-powered GPT-4 fraud detection into a single dashboard for managing subscriptions, disputing fraudulent charges, and automating customer outreach by phone and email.

Table of Contents

• Background
• Architecture
• Install
• Usage
• Features
• Documentation
• API
• Maintainers
• Contributing
• License

Background

Cancelling subscriptions, disputing fraudulent transactions, and chasing refunds are time-consuming, repetitive tasks that financial institutions have historically pushed onto consumers. Kaeru automates this work using a combination of:

• Plaid for transaction aggregation and account linking.
• LangChain for fraud detection and behavioral analysis.
• VAPI voice agents ("Riley") for placing cancellation and dispute phone calls.
• AWS Step Functions for orchestrating multi-step cancellation and dispute workflows.

See Also: Plaid, AWS Amplify Gen2, LangChain, VAPI.

Architecture

A typical end-to-end Kaeru session, step by step:

1. Sign in. User opens the Kaeru dashboard at / and authenticates.
2. Link a bank account. User connects their financial institution through Plaid Link.
3. Ingest transactions. Plaid sends a webhook to the ingestTransactions Lambda, which writes transactions to the Amplify data layer.
4. Analyze for fraud. FraudDetectionAgent (LangChain + GPT-4) scores each transaction and assigns a risk level: LOW (0–30), MEDIUM (30–50), or HIGH (50+).
5. Surface alerts. MEDIUM and HIGH risk transactions appear on the dashboard as fraud alerts; LOW risk transactions land in the standard transaction history.
6. User reviews the alert. The user opens a flagged transaction and chooses one of three paths:
   • Legitimate — dismiss the alert; the transaction stays in history.
   • Cancel a subscription — go to step 7.
   • Dispute a charge — go to step 8.
7. Cancellation workflow. A Step Functions workflow picks the best channel:
   • cancelApi — programmatic API cancellation when supported.
   • cancelEmail — sends a cancellation email.
   • cancelViaVapi — Riley (VAPI voice agent) places a phone call to the provider.
8. Dispute workflow. A Step Functions workflow runs disputeViaVapi, where Riley calls the issuer and files the dispute on the user's behalf.
9. Stream status. Workflow progress (queued → in-progress → completed/failed) streams back to the dashboard via the agent status API.
10. Resolution. The user sees the final outcome — cancelled subscription, filed dispute, or refunded charge — and an updated transaction list.

Install

This project requires Node.js >=18.17 <=20.x (Amplify Gen2 compatibility) and npm.

git clone https://github.com/teddymalhan/kaeru.git
cd kaeru
npm install

Dependencies

The following external credentials are required for full functionality:

• OPENAI_API_KEY — for fraud detection (degrades gracefully if absent).
• Plaid credentials — see docs/PLAID_SETUP.md.
• VAPI credentials — see docs/vapi-assistants.md.
• AWS credentials — required for Amplify backend and Bedrock features.

Copy the environment template and fill in your values:

cp .env.example .env.local

Usage

Start the Next.js development server:

npm run dev

Then visit http://localhost:3000.

To run the local Amplify sandbox backend in parallel:

npx ampx sandbox

Build and run for production:

npm run build
npm start

Lint the project:

npm run lint

Features

• AI-driven subscription cancellation across multiple providers.
• Real-time fraud detection with risk scoring (LOW / MEDIUM / HIGH).
• One-click transaction dispute filing.
• Voice-agent phone automation for cancellations and disputes.
• Email-based cancellation workflows.
• Live agent and workflow status dashboard.
• Transaction history with export.

Documentation

Detailed guides live in /docs:

• PLAID_SETUP.md — Plaid integration.
• FRAUD_DETECTION_README.md — Fraud detection system.
• AI_FRAUD_DETECTION_SETUP.md — AI configuration.
• vapi-assistants.md — VAPI voice agents.
• riley-system-prompt.md — Voice agent prompts.

API

The application exposes Next.js App Router API routes under /app/api/, and a shared FraudDetectionAgent class in lib/fraud-detection-agent.ts:

import { fraudDetectionAgent } from "@/lib/fraud-detection-agent"

await fraudDetectionAgent.analyzeTransaction(transaction)
await fraudDetectionAgent.analyzeUserBehavior(userId)
await fraudDetectionAgent.batchAnalyzeTransactions(transactions)

Risk scoring thresholds are configured in lib/fraud-config.ts: LOW (0–30), MEDIUM (30–50), HIGH (50+).

Maintainers

• @teddymalhan

Contributing

Questions and bug reports are welcome via GitHub Issues. Feature discussions belong in GitHub Discussions.

PRs are accepted. Please ensure npm run lint passes before opening a PR. See CONTRIBUTING.md if present for further guidelines.

License

MIT © Teddy Malhan